From 5a52d72719e5b4e23462ce15372c19eae02a467c Mon Sep 17 00:00:00 2001 From: Marc Mintel Date: Sun, 18 Jan 2026 18:15:35 +0100 Subject: [PATCH] website refactor --- .../website/REACT_COMPONENT_ARCHITECTURE.md | 13 ++++++------- 1 file changed, 6 insertions(+), 7 deletions(-) diff --git a/docs/architecture/website/REACT_COMPONENT_ARCHITECTURE.md b/docs/architecture/website/REACT_COMPONENT_ARCHITECTURE.md index c40fa2812..50019b4fb 100644 --- a/docs/architecture/website/REACT_COMPONENT_ARCHITECTURE.md +++ b/docs/architecture/website/REACT_COMPONENT_ARCHITECTURE.md @@ -178,19 +178,18 @@ export function Card({ children, className }: CardProps) { To prevent "div wrapper" abuse and maintain architectural integrity, we enforce a strict boundary between **Primitives** and **Semantic UI**. -### 1. Primitives & Generic Wrappers (Forbidden in Components) -- **Primitives**: `Box`, `Surface` (in `ui/primitives/`) -- **Generic Wrappers**: `Layout`, `Container` (in `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 (Allowed in Components) +### 2. Semantic UI & Layout (Allowed in Components) - **Building blocks**: `Card`, `Panel`, `Button`, `Table`. -- **Layout Components**: `Stack`, `Grid` (Restricted to layout-only props). -- **Restricted flexibility**: Semantic layout components are restricted to layout-only props. They do NOT allow styling props (bg, border, etc.). +- **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.). - **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. +**Rule of thumb**: If you need a styled container or layout in a component, use `Panel`, `Card`, `Layout`, or `Container`. If you need a new type of semantic layout, create it in `ui/` using primitives. Direct use of primitives (`Box`, `Surface`, `Stack`, `Grid`) or raw HTML tags in `components/` is forbidden. ## The Display Object Layer