`. Pass `className` to layer (e.g. `text-center` for error states). ### `` — vertical rhythm Owns `space-y-*`. Use instead of bare `

` or stacked `mb-*` magic numbers. | Token | Class | Use for | |---|---|---| | `xs` | `space-y-1` | inline label + value | | `sm` | `space-y-2` | tight grouping (title + meta) | | `md` | `space-y-4` | default body rhythm | | `lg` | `space-y-6` | major blocks within a section | | `xl` | `space-y-8` | cross-section gaps | Use `asChild` to keep the semantic element: ```tsx

{title}

{meta}

``` ### `` — horizontal flex Owns `flex` + `items-*` + `justify-*` + `gap-*`. Defaults: `align="center"`, `justify="start"`, `gap="md"`. Same gap tokens as `Stack`. ## When to Use Which ``` Vertical? ├─ Just spacing → └─ Page root with max-width → Horizontal? → 3+ regions on a page that share a column? → Compound layout ``` ## Compound Layouts for Pages When a page has multiple top-level regions (back nav, article, action bar, comments) that share the column, build a compound component. The slots make "forgot the wrapper" structurally impossible. ```tsx // post/components/PostDetailLayout.tsx function PostDetailLayoutRoot({ children }: { children: ReactNode }) { return (

{children}

); } function Article({ children }: { children: ReactNode }) { return

{children}

; } function Actions({ children }: { children: ReactNode }) { return ( {children} ); } export const PostDetailLayout = Object.assign(PostDetailLayoutRoot, { Article, Actions, Comments: ({ children }) =>

{children}

, }); ``` Usage: ```tsx ... ... ... ``` A new region added to this page can only sit inside an existing slot or extend the compound — it cannot forget `mx-auto max-w-2xl`. ## When to Extract a NEW Primitive Apply the **deletion test**: 1. Find a className combination that appears in 2+ places. 2. Imagine deleting it from one site. Does the pattern still exist elsewhere? 3. Yes → extract. No → leave inline. **One use site = inline. Two = real seam, extract.** Length of the className list is not the smell — repetition is. ## Anti-Patterns ### Magic spacing values ```tsx // BAD — mb-6 and mb-2 are decisions hidden in the markup

{title}

{meta}

// GOOD — spacing is named, grouping is explicit

{title}

{meta}

``` ### Page width repeated on each child ```tsx // BAD — every child must remember max-w-2xl. Miss one → desktop breaks.

...

// GOOD — the column owns the width; children inherit

...

``` ### Primitive built before it has 2 use sites A `` only used by `PostCard` isn't a primitive — it's a renamed component with an indirection step. Wait for the second caller. ### `asChild` on a `

` ```tsx // BAD — Stack already renders

...

// GOOD — asChild only when swapping in

...

``` ### Arbitrary gap value bypassing the token ```tsx // BAD — gap-3 isn't a token; next refactor won't know it exists ... // GOOD — pick the nearest token; if none fits, the scale needs to change, not this call site ... ``` ## Quick Reference | Pattern | Primitive | |---|---| | Page max-width container | `` | | Vertical rhythm between siblings | `` | | Horizontal flex row | `` | | Page with 3+ semantic regions | Compound layout | | Avoid | Replace with | |---|---| | `mb-*` between siblings | Wrap parent in `` | | `flex items-center justify-between` div | `` | | Repeating `mx-auto max-w-2xl` | `` at the root | | Bare `

` only used for layout | One of the primitives above |