diff --git a/docs/THEME.md b/docs/THEME.md index 0c0446318..3f712c85e 100644 --- a/docs/THEME.md +++ b/docs/THEME.md @@ -128,11 +128,6 @@ It’s basically: 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.). @@ -140,6 +135,6 @@ To maintain architectural integrity and prevent "div wrapper" abuse, we enforce ### 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. +- **No raw HTML**: Components must use semantic UI elements. Direct use of 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. diff --git a/docs/architecture/website/REACT_COMPONENT_ARCHITECTURE.md b/docs/architecture/website/REACT_COMPONENT_ARCHITECTURE.md index f29b1da75..ea1f0dd6a 100644 --- a/docs/architecture/website/REACT_COMPONENT_ARCHITECTURE.md +++ b/docs/architecture/website/REACT_COMPONENT_ARCHITECTURE.md @@ -160,7 +160,6 @@ 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. - **Encapsulation**: Must NOT expose `className`, `style`, or Tailwind-specific props to consumers. - **Semantic APIs**: Use semantic props (e.g., `variant="primary"`, `size="large"`) instead of implementation details. @@ -192,12 +191,7 @@ export function Button({ children, variant = 'primary', onClick }: ButtonProps) To prevent "div wrapper" abuse and maintain architectural integrity, we enforce a strict boundary between **Primitives** and **Semantic UI**. -### 1. Primitives (Forbidden in Components) -- **Primitives**: `Box`, `Surface`, `Stack`, `Grid` (in `ui/primitives/`) -- **Internal only**: These should NEVER be imported by `components/`. They are for building semantic UI elements. -- **Full flexibility**: They allow arbitrary styling (bg, border, shadow, etc.) to build semantic components. - -### 2. Semantic UI & Layout (Allowed in Components) +### Semantic UI & Layout (Allowed in Components) - **Building blocks**: `Card`, `Panel`, `Button`, `Table`. - **Layout Components**: `Layout`, `Container` (in `ui/`). - **Restricted flexibility**: Semantic components are restricted to their defined props. They do NOT allow arbitrary styling props (bg, border, etc.). diff --git a/docs/architecture/website/UI_THEMING.md b/docs/architecture/website/UI_THEMING.md index be9fa6f47..765f36fe6 100644 --- a/docs/architecture/website/UI_THEMING.md +++ b/docs/architecture/website/UI_THEMING.md @@ -142,23 +142,6 @@ Example conceptually: - `intent: default | danger` - CSS module uses variables like `background: var(--ui-color-intent-primary)`. -### Primitives - -The primitives in [`apps/website/ui/primitives`](apps/website/ui/primitives) exist to build consistent semantics. They should not encode a “theme” directly; they expose minimal layout/styling mechanics. - -Examples in code today: - -- [`Box`](apps/website/ui/primitives/Box.tsx:1) -- [`Stack`](apps/website/ui/primitives/Stack.tsx:1) -- [`Surface`](apps/website/ui/primitives/Surface.tsx:1) - -Conceptually, primitives should either: - -- map typed props to standard CSS properties (style object), or -- map typed props to CSS variables that are already in the theme contract. - -What primitives should **not** do: generate Tailwind class strings as their main behavior. - --- ## Token naming: semantic + stable