gridpilot.gg/docs/THEME.md

🎨 GridPilot Dev Theme — “Precision Racing Minimal”

The core idea: A UI that feels like a race engineer’s dashboard — not a game launcher, not corporate SaaS.

⸻

1. Identity & Mood

The theme should communicate: • Precision (like telemetry screens) • Calm intensity (the feeling before a qualifying lap) • Authority without ego (used by serious racers) • Modern minimalism (dev-friendly, clean structure) • Soft gaming hints (subtle neon touches, not RGB vomit)

It appeals equally to: • Devs (clean, modular, readable components) • Gamers (immersive, familiar atmosphere) • Simracers (motorsport seriousness)

⸻

2. Visual Language

Primary Look • Dark, matte surfaces • Thin, crisp separators • Soft glow accents in blue / cyan / purple • Avoid aggressive neon or gamer-overload • Subtle gradient tints (barely visible)

Color System • Base: Near-black graphite (#0C0D0F) • Surface: Deep charcoal (#141619) • Outline: Soft steel grey (#23272B) • Primary Accent: Electric blue (#198CFF) • Telemetry Accent: Aqua (#4ED4E0) • Warning: Motorsport amber (#FFBE4D)

Everything should feel instrument-grade, not decorative.

⸻

3. Component Philosophy

Cards • Functional over flashy • Slight bevel or inset shadow (hint of cockpit panels) • Dense info, clean hierarchy

Tables • High-density • Thin row dividers • Highlight on hover only • Telemetry-coded status colors

Buttons • Flat by default • Glow + gradient only on hover • Snappy micro-animation (motorsport feedback)

Modals • Soft frosted blur • Fast open/close animation • Dimmed pit-lane-lighting vibe

⸻

4. Motion & Feedback

Racing-inspired, but minimal: • Short accelerations (fast ease-out) • No bounces — this isn’t a game store • Hover = slight lift + color pulse • Loading = progress line (like pit limiter light) • Switching tabs = sliding underline (chicane motion)

Devs should feel the UI is responsive, not playful.

⸻

5. Layout Structure

Think “Telemetry Workspace”: • Sidebar = dashboard rail • Header = control bar • Content = track map / data table zone • Right panel = session or context info

Everything modular, easily replaceable, easy to reason about.

⸻

6. Tone for Dev-Facing Text • Short • Neutral • Calm • Technical • Real-world language (not corporate slang)

Examples: • “Add race” • “Review protest” • “Session updated” • “Export standings” • “Sponsor payout queued”

No hype. No marketing tone inside the app.

⸻

7. Emotional Target

Users should feel: • In control • Supported • Efficient • Connected to motorsport culture • Trusting (nothing looks cheap or gimmicky)

It’s basically:

“A premium cockpit dashboard… built by people who race and code.” ⸻

8. UI Layering & Primitives

To maintain architectural integrity and prevent "div wrapper" abuse, we enforce a strict layering boundary:

Primitives (apps/website/ui/primitives/)

• Generic building blocks: Box, Surface, Stack, Grid, GridItem.
• Internal only: These should NEVER be imported outside of the apps/website/ui/ layer.
• Full flexibility: They allow arbitrary styling (bg, border, shadow, etc.) to build semantic components.

Semantic UI (apps/website/ui/)

• Building blocks for components: Card, Panel, Button, Table, Stack, Grid.
• Restricted flexibility: Semantic layout components (like Stack, Grid) are restricted to layout-only props. They do NOT allow styling props (bg, border, etc.).
• Public API: These are the only UI elements that should be imported by components/ or pages/.

Components (apps/website/components/)

• Domain-specific: RecentRacesPanel, DriverCard, LeagueHeader.
• No raw HTML: Components must use semantic UI elements. Direct use of primitives or raw HTML tags is forbidden.

Rule of thumb: If you need a styled container in a component, use Panel or Card. If you need a new type of styled container, create it in ui/ using primitives.