@d4gger/design-system 2.7.0

package/dist/docs/consumer-guide.md

@@ -0,0 +1,916 @@
+# Design System Consumer Guide
+
+This guide describes the supported package boundary for application teams. The
+individual component specifications in this directory contain complete prop
+tables and examples and ship under `dist/docs`.
+
+Looking for theme-specific patterns (mode, accent, density, scaling, SSR)?
+See [theme-guide.md](./theme-guide.md).
+
+## Installation and CSS
+
+Import `@d4gger/design-system/styles.css` once. It contains reset, tokens,
+utilities, and every component style. The narrower `reset.css`, `tokens.css`,
+`utilities.css`, `components.css`, and `components/*.css` entrypoints support
+selective loading.
+
+Tailwind v4 consumers may additionally import
+`@d4gger/design-system/tailwind.css` after `tailwindcss`. It maps utilities
+to DS tokens but does not install or run Tailwind. Tailwind is for page
+composition; DS components and tokens remain the visual authority.
+
+The adapter deliberately namespaces the named DS spacing scale. Use
+`p-dsx-xs`, `gap-dsx-md`, `mt-dsx-2xl`, and similar `*-dsx-*` utilities.
+Numeric utilities such as `p-4` continue to resolve from the shared 4px base.
+Unprefixed named `max-w-*` utilities retain Tailwind's container-width
+semantics, so `max-w-3xl` is not redefined as the DS 64px spacing token. For
+canonical page widths prefer `<Container size="content" />` or
+`<Container size="wide" />`; the adapter also exposes `max-w-content` and
+`max-w-wide` for app-owned composition.
+
+The optional `brand-effects.css` provides `dsx-brand-ambient`,
+`dsx-brand-starfield`, and `dsx-brand-shimmer`. Apply them to a page wrapper;
+core styles do not enable product atmosphere automatically.
+
+Starfield density can be selected with `dsx-brand-starfield--sparse` or
+`dsx-brand-starfield--dense`. Fine-tune an individual wrapper with
+`--dsx-brand-starfield-opacity`, `--dsx-brand-starfield-dot-size`, and
+`--dsx-brand-starfield-tile-size`; tune the top shimmer with
+`--dsx-brand-shimmer-opacity`. Do not copy the effect into app-local CSS.
+
+### CSS entrypoint map
+
+| Entrypoint | Contents | When to use |
+|---|---|---|
+| `styles.css` | Reset + tokens + utilities + every component style | Default app bootstrap. One import at the root. |
+| `reset.css` | CSS reset only | Apps that bring their own tokens or skip utilities. |
+| `tokens.css` | Design tokens as CSS custom properties (`--dsx-*`) | Apps that read tokens through `var()` from their own CSS, with no DS components in the bundle. |
+| `utilities.css` | Utility classes mapped to tokens | Apps that need `p-dsx-md`, `gap-dsx-lg`, and similar DS-token utilities without the component CSS. |
+| `components.css` | All component styles | Apps that have already imported `reset.css` and `tokens.css` and want the rest. |
+| `components/*.css` | Single-component styles | Tree-shaking per component (see below). |
+| `tailwind.css` | Tailwind v4 token adapter | Apps that run Tailwind for page composition and want DS-token utility mappings. |
+| `brand-effects.css` | Optional ambient, starfield, shimmer wrappers | Pages that opt into product atmosphere. |
+
+### Tree-shaking component CSS
+
+`components/<name>.css` ships per-component styles so apps that only render a
+subset of the package can skip the rest. A landing page that uses
+`Button`, `Input`, and `Card` does not need `sidebar.css` or
+`dialog.css` in the bundle.
+
+```ts
+// app/entry.client.tsx
+import '@d4gger/design-system/reset.css'
+import '@d4gger/design-system/tokens.css'
+import '@d4gger/design-system/utilities.css'
+import '@d4gger/design-system/components/button.css'
+import '@d4gger/design-system/components/input.css'
+import '@d4gger/design-system/components/card.css'
+```
+
+Build the entrypoint list from your real component inventory. If you miss
+one, the affected component renders unstyled (it still works at the
+attribute level, but the visual contract is gone). Prefer the full
+`styles.css` until the bundle cost matters more than the safety net.
+
+### PostCSS pipeline overview
+
+The package compiles CSS through a small PostCSS pipeline:
+
+1. PostCSS imports concatenate `reset.css`, `tokens.css`, `utilities.css`,
+   and `components.css` into the published `styles.css`.
+2. Lightning CSS minifies the result for production builds.
+3. The Tailwind v4 adapter (`tailwind.css`) layers DS tokens onto Tailwind
+   utilities at the application level; Tailwind itself is not bundled
+   with the package.
+
+Apps that consume the package do not need to run PostCSS for DS styles.
+PostCSS is the package's build-time concern, not the consumer's runtime
+concern.
+
+## Layout
+
+The layout primitives compose app shells and product pages. Pick the
+narrowest primitive that does the job; do not reach for `Box` where a
+purpose-built primitive is clearer.
+
+| Primitive | Job | When to use |
+|---|---|---|
+| `Box` | Universal surface and spacing primitive | Custom shapes that need token-driven padding, margin, gap, radius, surface, shadow, or border. Default to `Box` for unstyled wrappers. |
+| `Flex` | One-dimensional flex layout | Rows and columns of children. The canonical primitive for navigation bars, button rows, and inline lists. |
+| `Grid` | Two-dimensional grid layout | Card grids, dashboards, and any layout that needs `grid-template-columns` / `grid-template-rows` alignment. |
+| `Stack` | Flex with a single `gap` token | Vertical or horizontal stacks of children. The default primitive for "render a list of items with consistent spacing." |
+| `Container` | Centered block-width shell with horizontal padding | Page-level content shells. Nest `Flex`, `Grid`, or `Stack` inside it. |
+| `Section` | Page-level vertical-rhythm wrapper with block padding | Top-level page regions. Defaults to a `<section>` host. |
+| `Inset` | Edge-padding shortcut for composed surfaces | Padding inside a Card, Panel, or other composed surface. Not an app-shell primitive. |
+
+### Layout relationship diagram
+
+```
+Container (page-width shell)
+└── Section (block padding)
+    └── Stack or Flex or Grid
+        └── Box (token-driven spacing, surface, radius, shadow)
+            └── Inset (edge-padding shortcut)
+                └── content
+```
+
+`Container` and `Section` are page-level wrappers. `Stack`, `Flex`, and
+`Grid` are the layout workhorses. `Box` is the universal surface primitive
+for token-driven spacing, surface, and elevation. `Inset` is a thin
+shortcut over `Box` for edge padding.
+
+### When to use each primitive
+
+- **`Box`** when the wrapper needs token-driven padding, margin, surface
+  tone, radius, shadow, or border and you do not need the layout engine
+  semantics of `Flex` or `Grid`.
+- **`Flex`** when children need to flow along a single axis with
+  alignment, justification, or wrap behavior.
+- **`Grid`** when children need two-dimensional alignment through
+  `grid-template-columns` or `grid-template-rows`.
+- **`Stack`** when children just need a single `gap` token and the
+  default `column` direction. `Stack` is a thin convenience over `Flex`;
+  reach for `Flex` when you need direction, wrap, or alignment
+  semantics.
+- **`Container`** at the top of every page or major page region to
+  center content and apply horizontal padding.
+- **`Section`** for top-level page regions that need consistent block
+  padding.
+- **`Inset`** inside composed surfaces (cards, panels) when the only
+  thing the wrapper does is add edge padding.
+
+```tsx
+<Container size="content">
+  <Stack gap="lg">
+    <Heading>Account</Heading>
+    <Grid columns={{ initial: 1, md: 2 }} gap="md">
+      {children}
+    </Grid>
+  </Stack>
+</Container>
+```
+
+### Box as the universal surface primitive
+
+`Box` is the foundation that every other layout primitive extends. Reach
+for it when the wrapper needs token-driven style props but no layout
+engine semantics. `Box` accepts the full prop bag: `display`, `position`,
+`p`, `px`, `py`, `pt`, `pr`, `pb`, `pl`, `m`, `mx`, `my`, `mt`, `mr`,
+`mb`, `ml`, `gap`, `width`, `height`, `minWidth`, `maxWidth`,
+`minHeight`, `maxHeight`, `inset`, `zIndex`, `hide`, `show`, `radius`,
+`surface`, `shadow`, `border`, `borderTone`, `alignSelf`, `justifySelf`,
+`flex`, `flexBasis`, `flexGrow`, `flexShrink`, `order`, `gridArea`,
+`gridColumn`, `gridRow`.
+
+```tsx
+<Box
+  surface="surface-raised"
+  radius="lg"
+  shadow="3"
+  border
+  p="lg"
+  gap="md"
+>
+  Card content
+</Box>
+```
+
+`Box` and its layout descendants are not the same as `Card`. `Card` is a
+composite with internal header, title, description, content, and footer
+slots; `Box` is a flat surface primitive. Wrap a `Card`'s body in `Box`
+or `Stack` when external spacing is needed. `Text` and `Heading` do not
+own margins; pair them with `Box` or `Stack` for vertical rhythm.
+
+### Inset for padding shortcuts
+
+`Inset` is a thin wrapper over `Box` that exposes a `size` ramp of
+`1`..`4` for padding tokens. It does not replace `Box`; it provides a
+shorter API for the common "I just need edge padding" case.
+
+```tsx
+<Card>
+  <Card.Header>Title</Card.Header>
+  <Inset size="3">
+    Body content with the standard medium padding.
+  </Inset>
+</Card>
+```
+
+`Inset size="1"` resolves to `var(--dsx-space-xs)` (4px).
+`Inset size="2"` resolves to `var(--dsx-space-sm)` (8px).
+`Inset size="3"` resolves to `var(--dsx-space-md)` (16px).
+`Inset size="4"` resolves to `var(--dsx-space-lg)` (24px).
+
+### Responsive prop syntax
+
+Layout primitives accept responsive values for every prop that has the
+`Responsive` column set to `yes` in the per-component spec. The
+breakpoint set is `initial`, `sm` (640px), `md` (768px), `lg` (1024px),
+`xl` (1280px), `2xl` (1536px). The two accepted shapes are:
+
+1. **Object map**. The most explicit form, one value per breakpoint.
+
+   ```tsx
+   <Grid
+     columns={{ initial: 1, md: 2, lg: 3 }}
+     gap={{ initial: 'sm', md: 'md', lg: 'lg' }}
+   >
+     {items}
+   </Grid>
+   ```
+
+2. **Shorthand string**. Semicolon-separated breakpoint:value pairs.
+   `initial` is the default; omit it to use the unprefixed value as the
+   mobile fallback.
+
+   ```tsx
+   <Stack gap="initial:sm;lg:lg" direction="initial:column;md:row">
+     {children}
+   </Stack>
+   ```
+
+Both forms resolve to the same CSS custom property cascade. The runtime
+emits `--dsx-box-gap` (or the matching `--dsx-*` variable) per
+breakpoint; the CSS layer applies the right value inside the right
+`@media (min-width: ...)` block.
+
+The shorthand is parsed by `parseResponsiveValue` from
+`layout/responsive.props.ts`. The object map is the canonical form; use
+it when the value is a TypeScript expression (for example, a value
+coming from a `useBreakpoint` hook).
+
+## Spacing tokens
+
+Box-derived spacing props accept numeric token strings (`"0"` through
+`"9"`) and named tokens. Use them with `gap`, `p`, `px`, `py`, `pt`,
+`pr`, `pb`, `pl`, `m`, `mx`, `my`, `mt`, `mr`, `mb`, and `ml`. Card is
+not Box-derived; wrap its content in Box/Stack when external spacing is
+needed. Text and Heading do not own margins.
+
+| Token | Pixels |
+|---|---:|
+| `none` | 0 |
+| `0` | 0 |
+| `1` | 4 |
+| `2` | 8 |
+| `3` | 12 |
+| `4` | 16 |
+| `5` | 20 |
+| `6` | 24 |
+| `7` | 28 |
+| `8` | 32 |
+| `9` | 36 |
+| `xs` | 4 |
+| `sm` | 8 |
+| `md` | 16 |
+| `lg` | 24 |
+| `xl` | 32 |
+| `2xl` | 48 |
+| `3xl` | 64 |
+| `gutter` | 24 |
+| `margin` | 24 |
+
+### Numeric vs named tokens
+
+Numeric tokens map to the 4px base ramp: `0` is 0, `1` is 4, `2` is 8,
+and so on through `9` at 36. They are the right choice for fine-grained
+adjustments (the difference between `4` and `5` matters when a layout
+needs to align with an underlying baseline).
+
+Named tokens (`xs`, `sm`, `md`, `lg`, `xl`, `2xl`, `3xl`, `gutter`,
+`margin`) are semantic aliases. They are the right choice when the
+spacing is part of the design system's intended rhythm rather than a
+fine-grained adjustment. The semantic names map to the same numeric
+ramp where they overlap:
+
+| Named | Numeric equivalent |
+|---|---|
+| `xs` | `1` (4px) |
+| `sm` | `2` (8px) |
+| `md` | `4` (16px) |
+| `lg` | `6` (24px) |
+| `xl` | `8` (32px) |
+| `2xl` | (48px) |
+| `3xl` | (64px) |
+| `gutter` | `6` (24px) |
+| `margin` | `6` (24px) |
+
+The `SpaceToken` union is `'none' \| '0' \| '1' \| ... \| '9' \| 'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl' \| '2xl' \| '3xl' \| 'gutter' \| 'margin'`. Components accept any value in that union. Free-form strings (for example, a
+custom pixel value like `"22px"`) pass through `resolveSpace` and reach
+the CSS layer unchanged; prefer the token union for new code.
+
+### How spacing composes across Box-derived components
+
+Every layout primitive resolves its spacing props through the same
+`BOX_PROP_DEFS` (or the matching `*_PROP_DEFS`) constant. The CSS layer
+reads `--dsx-box-padding`, `--dsx-box-margin`, `--dsx-box-gap`, and
+the per-axis variants to paint the value. This means spacing composes
+predictably across `Box`, `Flex`, `Grid`, `Stack`, `Container`, and
+`Section`: a `<Stack gap="md">` inside a `<Box p="lg">` is the same
+spacing scale as the same `Stack` directly under the body.
+
+The same rule applies to the responsive cascade. A responsive `gap` on a
+`Grid` and a responsive `gap` on a `Stack` both flow through the same
+`gap` prop def, both write the same `--dsx-box-gap` variable, and both
+respect the same breakpoint set.
+
+## Typography
+
+The package ships two layers of typography. The foundation layer
+(`FoundationText` and `FoundationHeading`, exported as `Text` and
+`Heading` from `@d4gger/design-system/foundations`) is a flat
+polymorphic primitive. The app-level layer (`Text` and `Heading` from
+`@d4gger/design-system/components`) wraps the foundation with a
+prop-def bag, a responsive `size` scale, and the `label-medium`
+uppercase utility.
+
+Prefer the app-level `Text` and `Heading` for new product code. Reach
+for the foundation exports when you need a CSS-variable tone contract
+(for example, when composing inside a custom host element or when the
+consumer wants to apply the tone through a `style` override).
+
+### `Text` variants
+
+| Variant | Job |
+|---|---|
+| `body-large` | Long-form reading copy that needs the larger body size. |
+| `body-medium` | Default body text. The default variant. |
+| `label-large` | Large UI label for prominent controls. |
+| `label-medium` | Uppercase utility label for overlines, table headers, kickers, chips. |
+| `label-small` | Compact normal-case UI label for tags and compact badges. |
+
+```tsx
+<Text variant="body-medium">Default body copy.</Text>
+<Text variant="label-medium" tone="muted">SECTION KICKER</Text>
+<Text variant="label-small" tone="primary">Featured</Text>
+```
+
+The `tone` prop drives the text color through a CSS custom property
+(`--dsx-text-color`). Available tones: `default`, `muted`, `primary`,
+`secondary`, `success`, `error`.
+
+### `Heading` variants
+
+| Variant | Default host |
+|---|---|
+| `display-large` | `h1` |
+| `display-medium` | `h2` |
+| `headline-large` | `h3` |
+| `headline-medium` | `h4` (the default variant) |
+
+```tsx
+<Heading variant="display-large">Welcome</Heading>
+<Heading variant="headline-medium">Account</Heading>
+```
+
+`size` is a separate responsive scale (`1`..`9`) on the app-level
+`Heading` component. When `size` is set, the host element is derived
+from the size (`9` → `h1`, `1` → `h6`) and the variant is ignored for
+the host element. Use `as` to override the host element when the
+derived level does not match the document outline.
+
+### FontProvider: loading fonts at the app root
+
+`FontProvider` writes `--dsx-font-family` and `--dsx-display-font-family`
+on `document.documentElement` from the `fontFamily` and
+`displayFontFamily` props. Wrap the app in `FontProvider` at the root
+and preload the font faces through a normal `<link rel="preload">` or
+`next/font`.
+
+```tsx
+// app/root.tsx
+import { FontProvider } from '@d4gger/design-system'
+
+export function Root({ children }: { children: React.ReactNode }) {
+  return (
+    <FontProvider
+      fontFamily="var(--dsx-typography-body-medium-font-family, sans-serif)"
+      displayFontFamily="var(--dsx-typography-display-font-family, serif)"
+      loadGoogleFonts
+    >
+      {children}
+    </FontProvider>
+  )
+}
+```
+
+The `fontFamily` default is the body-medium token reference, so the
+provider's absence does not break the typography ramp. Pass a
+free-form value when you bring your own font.
+
+#### Merriweather Cyrillic fallback
+
+Heading and display tokens use Fraunces with Merriweather as the
+Cyrillic serif fallback. When your product copy may include Cyrillic
+characters (Russian-language product UI, for example), pass
+`loadGoogleFonts` to inject the Google Fonts stylesheet for Merriweather
+with the `cyrillic,latin` subset.
+
+```tsx
+<FontProvider
+  fontFamily="Manrope, sans-serif"
+  displayFontFamily="Fraunces, serif"
+  loadGoogleFonts
+>
+  {children}
+</FontProvider>
+```
+
+`loadGoogleFonts` injects a `<link rel="stylesheet">` for the Merriweather
+subset on mount and removes it on unmount. The link carries
+`id="dsx-font-provider-merriweather"`, which the provider uses to
+deduplicate when more than one provider mounts in the same document.
+
+### Overriding fonts through CSS custom properties
+
+The provider is the canonical writer of `--dsx-font-family`. Apps that
+want to set the value without mounting the provider can write the
+property directly. The runtime reads the value at render time, so the
+override applies immediately.
+
+```css
+:root {
+  --dsx-font-family: 'Manrope', sans-serif;
+  --dsx-display-font-family: 'Fraunces', 'Merriweather', serif;
+}
+```
+
+The order of fallback matters. The serif fallback should be Merriweather
+so Cyrillic characters in headings retain the same serif voice as the
+Latin Fraunces.
+
+## Component API reference
+
+The package exposes components through three patterns: flat exports
+(`Button`, `Text`, `Heading`), compound components (`Sidebar`,
+`Dialog`, `Card`), and compound components with internal slots that are
+not exposed as named exports (`Accordion`, `AlertDialog`). The patterns
+share the same underlying infra: the `Shared` polymorphic prop bag,
+the `asChild` slot helper from `@radix-ui/react-slot`, the `data-slot`
+attribute contract, and the `extractProps` runtime that turns the prop
+defs into merged class + style output.
+
+### `asChild` polymorphism
+
+`asChild` swaps the rendered element for the consumer's child element.
+When `asChild` is true, the component renders a `Slot` from
+`@radix-ui/react-slot`; the child element is the actual host, and the
+component merges its `className`, `style`, `data-*` attributes, and
+event handlers into the child.
+
+```tsx
+<Button asChild>
+  <Link href="/dashboard">Open dashboard</Link>
+</Button>
+```
+
+The `Link` becomes the host element. The Button's `dsx-button` class,
+`data-variant`, `data-size`, and `onClick` are merged into the `<a>`.
+The `type` attribute is dropped in `asChild` mode (because the host
+is not a `<button>`).
+
+`asChild` is the recommended way to render a component with a custom
+host. Reach for the `as` prop only when there is no child element to
+begin with (a flat, empty wrapper).
+
+### `data-slot` attributes for CSS targeting
+
+Compound components write `data-slot="<name>"` on each slot element so
+the CSS layer can target a specific slot without coupling to the
+internal class names. The slot names follow the kebab-case convention
+of the compound name plus the slot name: `data-slot="sidebar-header"`,
+`data-slot="dialog-content"`, `data-slot="card-title"`.
+
+The `Sidebar` collapsed-state CSS uses the `data-slot` attribute to
+hide non-trigger children when the panel is collapsed:
+
+```css
+.dsx-sidebar[data-state='collapsed'] [data-slot='sidebar-menu-label'] {
+  display: none;
+}
+```
+
+Apps can write their own slot-scoped styles through `data-slot` when
+the component's variant system is not enough. Prefer the published
+variant and `data-*` attributes first; reach for `data-slot` selectors
+last.
+
+### CVA variant pattern (variants, sizes, states)
+
+Most primitives drive their visual treatment through `data-*`
+attributes that the component writes from typed props. `Button` is a
+representative example:
+
+```tsx
+<Button variant="primary" size="md" color="amber">Save</Button>
+<Button variant="secondary" size="sm">Cancel</Button>
+<Button variant="destructive" loading>Delete</Button>
+```
+
+The runtime writes `data-variant="primary"`, `data-size="md"`, and
+`data-accent-color="amber"` on the host element. The CSS layer maps
+those attributes to the right rules.
+
+| Primitive | `variant` | `size` | Other state props |
+|---|---|---|---|
+| `Button` | `primary` \| `secondary` \| `ghost` \| `destructive` \| `outline` | `sm` \| `md` \| `lg` \| `icon` | `color`, `radius`, `highContrast`, `loading` |
+| `Card` | `default` \| `glass` \| `elevated` \| `filled` \| `outline` (compatibility) | `sm` \| `md` \| `lg` | `highContrast` |
+| `Dialog.Content` | (n/a) | `sm` \| `md` \| `lg` | `showClose`, `width`, `height`, etc. |
+| `Badge` | `default` \| `secondary` \| `outline` \| `destructive` | `sm` \| `md` | (n/a) |
+
+The canonical `Card` variants are `default` and `glass`. `outline` is
+compatibility-only and normalizes to `data-variant="default"` plus a
+`dsx-card--outline` class.
+
+### Forward refs and spread props
+
+Every primitive is a `forwardRef`. Refs land on the host element (or on
+the consumer's child when `asChild` is set). Spread props that are
+not part of the prop def flow through to the host element.
+
+```tsx
+const ref = useRef<HTMLButtonElement>(null)
+
+<Button ref={ref} variant="primary" data-testid="submit" onClick={handleSubmit}>
+  Submit
+</Button>
+```
+
+`data-testid`, `aria-*` attributes, and any other HTML attribute that
+is not a defined prop pass through unchanged. This is how
+testing-library queries, focus management, and analytics hooks reach
+the underlying DOM.
+
+### Controlled vs uncontrolled patterns
+
+Compound components with internal state (open/close, expanded/collapsed,
+checked/unchecked) follow a standard pattern: an `open` or `expanded`
+prop plus an `on*Change` handler for controlled usage, and a
+`defaultOpen` or `defaultExpanded` prop for uncontrolled usage.
+
+```tsx
+// Controlled Dialog
+function DeleteAccountButton() {
+  const [open, setOpen] = useState(false)
+  return (
+    <Dialog open={open} onOpenChange={setOpen}>
+      <Dialog.Content>
+        <Dialog.Title>Delete account?</Dialog.Title>
+        <Dialog.Description>This action is permanent.</Dialog.Description>
+        <Dialog.Footer>
+          <Dialog.Close>Cancel</Dialog.Close>
+          <Dialog.ActionTrigger action={deleteAccount}>
+            Delete
+          </Dialog.ActionTrigger>
+        </Dialog.Footer>
+      </Dialog.Content>
+    </Dialog>
+  )
+}
+
+// Uncontrolled Dialog
+function QuickConfirm() {
+  return (
+    <Dialog defaultOpen>
+      <Dialog.Content>...</Dialog.Content>
+    </Dialog>
+  )
+}
+```
+
+`Dialog.ActionTrigger` accepts an `action` prop that runs as an async
+function. The trigger stays disabled with a `Spinner` while the promise
+is in flight and closes the dialog when the promise resolves. Pass
+`loading` to force the loading state.
+
+`Sidebar.Provider` follows the same pattern with `defaultExpanded` and
+persistence: the provider reads the stored state from `localStorage`
+in a `useLayoutEffect` after mount and writes the next state in a
+`useEffect`, so the SSR render matches the initial client render and
+the post-hydration effect flips the state from `localStorage`.
+
+### Sidebar compound example
+
+`Sidebar` is the canonical compound surface. The full slot list lives
+in the per-component spec; the typical composition is:
+
+```tsx
+<Sidebar.Provider storageKey="app-sidebar" defaultExpanded>
+  <Sidebar>
+    <Sidebar.Header>
+      <Sidebar.Trigger />
+    </Sidebar.Header>
+    <Sidebar.Content>
+      <Sidebar.Group>
+        <Sidebar.GroupLabel>Workspace</Sidebar.GroupLabel>
+        <Sidebar.GroupContent>
+          <Sidebar.Menu>
+            <Sidebar.MenuItem>
+              <Sidebar.MenuButton isActive asChild>
+                <Link href="/dashboard">Dashboard</Link>
+              </Sidebar.MenuButton>
+            </Sidebar.MenuItem>
+            <Sidebar.MenuItem>
+              <Sidebar.MenuButton>Servers</Sidebar.MenuButton>
+            </Sidebar.MenuItem>
+          </Sidebar.Menu>
+        </Sidebar.GroupContent>
+      </Sidebar.Group>
+    </Sidebar.Content>
+    <Sidebar.Footer>
+      <Sidebar.MenuBadge>3</Sidebar.MenuBadge>
+    </Sidebar.Footer>
+    <Sidebar.Rail />
+  </Sidebar>
+  <Sidebar.Inset>
+    <main>Page content</main>
+  </Sidebar.Inset>
+</Sidebar.Provider>
+```
+
+`Sidebar.Provider` owns the persisted expanded / collapsed state. The
+provider registers a `Ctrl+B` / `Cmd+B` keyboard shortcut by default
+and falls back to a `Sheet` on mobile when `mobile="sheet"` and the
+viewport is below `mobileBreakpoint`. Persistence is hydration-safe:
+the initial read runs in `useLayoutEffect`, the write in `useEffect`.
+
+`Sidebar.MenuButton` and `Sidebar.MenuSubButton` wrap string or number
+children in a `<span class="dsx-sidebar__menu-button-text">` so the
+collapsed-state CSS can hide the text while keeping the icon. The
+wrapping span is omitted when `asChild` is set.
+
+### Dialog compound example
+
+`Dialog` is a Radix-compound surface. The slots map 1:1 to the Radix
+primitives plus DS-specific positioner, backdrop, and action trigger
+slots:
+
+```tsx
+<Dialog>
+  <Dialog.Trigger asChild>
+    <Button variant="primary">Open</Button>
+  </Dialog.Trigger>
+  <Dialog.Portal>
+    <Dialog.Overlay />
+    <Dialog.Positioner position="center">
+      <Dialog.Backdrop blur />
+      <Dialog.Content size="md">
+        <Dialog.Header>
+          <Dialog.Title>Confirm</Dialog.Title>
+          <Dialog.Description>This action moves a server.</Dialog.Description>
+        </Dialog.Header>
+        <Dialog.Body>Body content</Dialog.Body>
+        <Dialog.Footer>
+          <Dialog.Close>Cancel</Dialog.Close>
+          <Dialog.ActionTrigger action={onConfirm}>
+            Confirm
+          </Dialog.ActionTrigger>
+        </Dialog.Footer>
+      </Dialog.Content>
+    </Dialog.Positioner>
+  </Dialog.Portal>
+</Dialog>
+```
+
+`Dialog.Content` writes `data-size` for the size band and reads
+`width`, `minWidth`, `maxWidth`, `height`, `minHeight`, `maxHeight` as
+CSS custom property overrides (`--dsx-dialog-content-custom-*`). The
+size prop is single value only; the dimension overrides accept
+responsive values.
+
+### Card variant example
+
+`Card` is a flat compound with the canonical `default` and `glass`
+variants:
+
+```tsx
+<Card variant="default" size="md">
+  <Card.Header>
+    <Card.Title>Plan</Card.Title>
+    <Card.Description>Monthly billing</Card.Description>
+  </Card.Header>
+  <Card.Content>
+    <DataList aria-label="Plan details">
+      <DataList.Item text="Bandwidth" metadata="Unlimited" />
+      <DataList.Item text="Locations" metadata="62 countries" />
+    </DataList>
+  </Card.Content>
+  <Card.Footer>
+    <Button variant="primary">Upgrade</Button>
+  </Card.Footer>
+</Card>
+```
+
+`Card.Header`, `Card.Title`, `Card.Description`, `Card.Content`, and
+`Card.Footer` all accept `asChild`. Use it to swap a slot's host
+element when the default doesn't match (for example, `Card.Title
+asChild` with a `Link` when the title is also a navigation link).
+
+## Icons
+
+The package ships icons through a single named surface. The runtime
+catalog is a frozen list (`dsxIconCatalog`); the named React exports
+(`SunIcon`, `MoonIcon`, etc.) are generated from the same list through
+`createDSXIconComponent`.
+
+### `Icon` usage
+
+```tsx
+import { Icon, SunIcon, MoonIcon } from '@d4gger/design-system'
+
+<Icon name="check" />
+<Icon name="check" size="sm" title="Confirmed" />
+<SunIcon size="md" color="primary" />
+<MoonIcon size="lg" className="text-muted" />
+```
+
+The `name` prop drives the catalog lookup. The runtime accepts any
+`DSXIconName`; passing an unknown name renders nothing rather than
+throwing.
+
+### `size` prop
+
+The `Icon` component uses a four-step scale: `sm` (16px), `md` (20px,
+the default), `lg` (24px), and `xl` (32px). The named exports
+(`SunIcon`, `MoonIcon`, etc.) use a five-step scale: `xs` (16px),
+`sm` (20px), `md` (24px), `lg` (32px), and `xl` (40px). Both APIs
+accept numeric values, which pass through to the SVG `size` attribute;
+`<SunIcon size={48} />` renders a 48px icon.
+
+| Size | `Icon` pixels | Named exports pixels |
+|---|---:|---:|
+| `xs` | (n/a) | 16 |
+| `sm` | 16 | 20 |
+| `md` | 20 | 24 |
+| `lg` | 24 | 32 |
+| `xl` | 32 | 40 |
+
+### `strokeWidth` customization
+
+`Icon` forwards `strokeWidth` to the underlying Lucide component. The
+default is `var(--dsx-icon-stroke-width, 1.75)`, which is the package's
+balanced stroke for UI icons. Pass a number for a custom value:
+
+```tsx
+<Icon name="check" strokeWidth={2.25} />
+```
+
+Simple Icons (the brand and service glyphs) do not honor `strokeWidth`;
+they render as filled paths.
+
+### Named exports
+
+Every catalog entry has a named export. The naming convention is
+PascalCase with the kebab-case name converted to PascalCase and
+suffixed with `Icon`: `check` → `CheckIcon`, `arrow-left` →
+`ArrowLeftIcon`, `chevron-down` → `ChevronDownIcon`. The full
+runtime catalog is `dsxIconCatalog`.
+
+```ts
+import {
+  dsxIconCatalog,
+  Icon,
+  SunIcon,
+  MoonIcon,
+  CheckIcon,
+  ChevronDownIcon,
+} from '@d4gger/design-system'
+```
+
+### Accessibility: decorative vs semantic icons
+
+Icons are decorative by default. When the `title` prop is omitted, the
+runtime writes `role="presentation"` and `aria-hidden="true"`, so the
+icon is removed from the accessibility tree. When `title` is set, the
+runtime writes `role="img"`, removes `aria-hidden`, and renders a
+`<title>` child so the icon is announced as a labelled image.
+
+```tsx
+// Decorative (icon next to a visible label)
+<Button>
+  <Icon name="plus" />
+  Add server
+</Button>
+
+// Semantic (icon carries the meaning)
+<Icon name="check" title="Connected" />
+```
+
+Interactive meaning belongs to the wrapping control, not the icon.
+When an `IconButton` renders an icon, the button's `aria-label` is the
+accessible name. The icon inside the button is decorative and should
+not carry a `title`.
+
+### Runtime catalog
+
+`dsxIconCatalog` is a frozen array of `{ name, category, file }`
+entries. Use it to build icon pickers, search inputs, or doc
+generators without hardcoding the icon list.
+
+```ts
+import { dsxIconCatalog } from '@d4gger/design-system'
+
+const names = dsxIconCatalog.map((entry) => entry.name)
+const connectivity = dsxIconCatalog.filter(
+  (entry) => entry.category === 'Connectivity',
+)
+```
+
+### Common icon reference
+
+| Category | Names |
+|---|---|
+| Theme | `sun`, `moon`, `monitor` |
+| Navigation | `arrow-left`, `arrow-right`, `chevron-down`, `chevron-up`, `chevron-left`, `chevron-right`, `menu`, `x`, `plus`, `minus`, `dots-horizontal`, `dots-vertical`, `external-link`, `home`, `search`, `settings`, `user` |
+| Feedback | `check`, `check-circle`, `info`, `help-circle`, `alert-triangle`, `bell`, `loader`, `sparkles`, `star` |
+| Security | `shield`, `shield-check`, `lock`, `lock-keyhole`, `unlock`, `key`, `fingerprint`, `eye`, `eye-off` |
+| Connectivity | `wifi`, `signal`, `globe`, `server`, `hard-drive`, `activity`, `zap` |
+| Communication | `mail`, `send` |
+| Commerce | `banknote`, `circle-dollar-sign`, `gem`, `quote`, `receipt-text`, `russian-ruble` |
+| Forms & Actions | `edit`, `trash`, `copy`, `eraser`, `calendar`, `clock`, `code`, `file`, `image`, `link`, `list`, `list-ordered`, `upload`, `bold`, `italic`, `strikethrough`, `quote`, `heading-1`, `heading-2`, `heading-3`, `undo`, `redo` |
+| Brand & Social | `apple`, `discord`, `facebook`, `github`, `gitlab`, `google`, `instagram`, `netflix`, `npm`, `paypal`, `reddit`, `spotify`, `stripe`, `supabase`, `telegram`, `twitch`, `twitter`, `vercel`, `youtube` |
+| App Specific | `home`, `rocket` |
+
+This is a representative subset. The runtime catalog is the source of
+truth and ships as a frozen array in the package.
+
+### How to add custom icons
+
+Custom icons are not added to the runtime catalog; the catalog is
+frozen and ships with the package. For product-specific icons, render
+the SVG directly through a `Box` (or any layout primitive) and apply
+the `dsx-icon` class plus `data-size` to participate in the icon sizing
+contract.
+
+```tsx
+<Box
+  as="svg"
+  width="24"
+  height="24"
+  viewBox="0 0 24 24"
+  data-size="md"
+  className="dsx-icon"
+  aria-hidden
+>
+  <path d="..." />
+</Box>
+```
+
+Reach for a custom SVG when the catalog is missing a glyph. Reach for
+the catalog when a name exists; the catalog gives you free theme
+integration, a known size scale, and a consistent stroke.
+
+## Accordion indicators
+
+`Accordion.Trigger` renders one built-in chevron by default. Pass
+`indicator={false}` to hide it or `indicator={<YourIcon />}` to replace it.
+`Accordion.ItemIndicator` and `Accordion.ItemBody` remain compatibility exports;
+new code should use the trigger's `indicator` prop and `Accordion.Content`.
+Never place `ItemIndicator` alongside the trigger's built-in indicator, and
+never nest `ItemBody` inside `Content`.
+
+## DataList example
+
+```tsx
+<DataList aria-label="Connection details">
+  <DataList.Item
+    icon={<GlobeIcon />}
+    text="Location"
+    metadata="Finland"
+    badge={<Badge>Active</Badge>}
+  />
+</DataList>
+```
+
+## DropdownMenu scroll locking
+
+`DropdownMenu` with `modal` behavior (the default) locks body scrolling when the menu
+is open. For navigation and header use cases where scrolling should remain available,
+set `modal={false}`:
+
+```tsx
+<DropdownMenu modal={false}>
+  <DropdownMenu.Trigger asChild>
+    <Button variant="ghost">Account</Button>
+  </DropdownMenu.Trigger>
+  <DropdownMenu.Content>
+    <DropdownMenu.Item>Settings</DropdownMenu.Item>
+    <DropdownMenu.Item>Sign out</DropdownMenu.Item>
+  </DropdownMenu.Content>
+</DropdownMenu>
+```
+
+`modal={false}` disables the scroll lock and the overlay backdrop, and the menu
+closes when focus moves outside its content. Prefer the default `modal` behavior
+for forms, destructive actions, and any menu where the user should not scroll the
+page while the menu is open.
+
+## Next steps
+
+- Theme system, ThemeProvider, useTheme, and the SSR guidance live in
+  [theme-guide.md](./theme-guide.md).
+- Per-component prop tables live in the kebab-case spec files
+  alongside this guide.
+- Component taxonomy and classification live in
+  [HIERARCHY.md](./HIERARCHY.md) and [component-roster.md](./component-roster.md).