website refactor

docs/architecture/website/REACT_COMPONENT_ARCHITECTURE.md

@@ -151,6 +151,7 @@ export function TeamLeaderboardPreview({ teams, onTeamClick }: Props) {
 - No Next.js imports
 - Only receive props and render
 - Maximum reusability
+- **Strict Layering**: Generic primitives (`Box`, `Surface`, `Stack`, `Grid`) are internal to this layer.
 
 **Example**:
 ```typescript
@@ -172,6 +173,22 @@ export function Card({ children, className }: CardProps) {
 }
 ```
 
+## UI Layering & Primitives
+
+To prevent "div wrapper" abuse and maintain architectural integrity, we enforce a strict boundary between **Primitives** and **Semantic UI**.
+
+### 1. Primitives (`ui/primitives/`)
+- **Generic building blocks**: `Box`, `Surface`, `Stack`, `Grid`, `GridItem`.
+- **Internal only**: These should NEVER be imported outside of the `ui/` layer.
+- **Full flexibility**: They allow arbitrary styling (bg, border, shadow, etc.) to build semantic components.
+
+### 2. Semantic UI (`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/`.
+
+**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. Direct use of primitives or raw HTML tags in `components/` is forbidden.
+
 ## The Display Object Layer
 
 **Purpose**: Reusable formatting and presentation logic