website refactor

docs/THEME.md

@@ -121,4 +121,25 @@ Users should feel:
 
 It’s basically:
 
-“A premium cockpit dashboard… built by people who race and code.”
+“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.