@d4gger/design-system 2.7.0

package/dist/docs/search-bar.md

@@ -0,0 +1,329 @@
+---
+title: SearchBar
+status: canonical
+category: Components
+archetype: composite
+package_path: packages/d4gger-design-system/src/components/searchBar/SearchBar.tsx
+css_path: packages/d4gger-design-system/src/styles/components/search-bar.css
+props_path: packages/d4gger-design-system/src/components/searchBar/searchBar.props.ts
+test_path: packages/d4gger-design-system/src/test/components/SearchBar.test.tsx
+demo_path: apps/playground/app/(themeable)/docs/[component]/page.tsx
+playground_registry_path: apps/playground/lib/registry/overlay.tsx
+playground_manifest_path: apps/playground/lib/component-manifest.ts
+depends_on:
+  - Command (the `SearchBar.Menu` slot renders through the DS `Command` surface for the search-first list and keyboard navigation)
+  - Dialog (the `SearchBar.Menu` slot mounts a `Dialog` for the modal palette; the trigger button opens the dialog)
+  - Button (the `SearchBar.Trigger` slot renders through the `Button` primitive at the `outline` variant by default)
+  - Icon (lucide-react `search` is the trigger leading icon)
+  - Kbd (the trailing `Kbd` chip on the trigger renders the keyboard shortcut hint, default `⌘K`)
+  - "@radix-ui/react-slot (asChild on the root and on the trigger)"
+---
+
+# SearchBar
+
+> Source of truth: the package source at `package_path`. The spec file mirrors the source. Edits to the spec must land in the source in the same change, or the QA flags will fire.
+
+## Purpose
+
+A global search trigger with a command-palette-style results menu. The trigger button shows a search icon, a label, and an optional keyboard shortcut hint. Clicking the trigger opens a modal dialog that hosts a `Command` palette. The trigger also listens for `Cmd/Ctrl + K` and toggles the menu open or closed when the matching key is pressed. Use `SearchBar` for app-level search-first navigation; use `Combobox` for inline option pickers.
+
+## Anatomy & slots
+
+**Parent:** `SearchBar` (alias of `SearchBar.Root`).
+
+**Slots:**
+
+| Slot | Element | Renders | Notes |
+|---|---|---|---|
+| `SearchBar.Root` | `<div>` (or slotted host) | `dsx-search-bar`, plus `dsx-search-bar--compact` when `compact` is set. Writes `data-radius`, `data-size`, `data-variant`. | Owns the open/close state, the `Cmd/Ctrl + K` shortcut listener, and the `SearchBarContext` provider. |
+| `SearchBar.Trigger` | `Button` primitive | `dsx-search-bar__trigger`, plus `dsx-search-bar__trigger-content`, `dsx-search-bar__trigger-label`, and a trailing `dsx-search-bar__shortcut` (Kbd). Leading icon: lucide `search`. | The button that opens the palette. The runtime wires `onClick` to call `setOpen(true)` unless the consumer's own click handler called `event.preventDefault()`. |
+| `SearchBar.Menu` | `Dialog` wrapping `DialogContent` wrapping `Command` | `dsx-search-bar__menu` (on the dialog content), `dsx-search-bar__command` (on the inner Command shell). The dialog's size follows the `size` prop. | The palette. `showClose` toggles the dialog's close button. |
+
+## Props contract
+
+**Root props (`SearchBar` / `SearchBar.Root`):**
+
+| Prop | Type | Default | Required | Description | Responsive |
+|---|---|---|---|---|---|
+| `asChild` | `boolean` | `false` | no | Renders the root through `Slot` from `@radix-ui/react-slot`. | no |
+| `variant` | `'default' \| 'ghost'` | `'default'` | no | Trigger style. Writes `data-variant`. The CSS does not currently declare per-variant rules; the attribute is the contract hook. | no |
+| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | no | Trigger height. Writes `data-size`. The CSS does not currently declare per-size rules; the attribute is the contract hook. | no |
+| `radius` | `'none' \| 'sm' \| 'md' \| 'lg' \| 'full'` | `undefined` | no | Trigger corner roundness. Writes `data-radius`. | no |
+| `compact` | `boolean` | `false` | no | Reduces the container gap. Adds the `dsx-search-bar--compact` modifier class. | no |
+| `openOnShortcut` | `boolean` | `true` | no | When set, the root listens for `Cmd/Ctrl + K` on `window` and toggles the menu. The listener is registered in a `useEffect` and removed on unmount. | no |
+| `defaultOpen` | `boolean` | `false` | no | Initial open state when uncontrolled. | no |
+| `open` | `boolean` | `undefined` | no | Controlled open state. | no |
+| `onOpenChange` | `(open: boolean) => void` | `undefined` | no | Fires on every open transition. | no |
+| (HTML div props) | n/a | n/a | no | All standard `<div>` attributes are forwarded. | no |
+
+Rules:
+
+- `defaultOpen`, `open`, and `onOpenChange` are extracted by `extractProps` and re-applied through the `useControllableSearchBarOpenState` helper, which is a small internal clone of the controlled/uncontrolled state pattern.
+
+**`SearchBar.Trigger` props:**
+
+| Prop | Type | Default | Required | Description | Responsive |
+|---|---|---|---|---|---|
+| `asChild` | `boolean` | `false` | no | Renders the trigger through `Slot`. | no |
+| `showShortcut` | `boolean` | `true` | no | Shows the trailing Kbd chip. | no |
+| `shortcutLabel` | `React.ReactNode` | `'⌘K'` | no | Content of the trailing Kbd chip. | no |
+| `variant` | `'solid' \| 'outline' \| 'ghost' \| 'soft'` (Button primitive variants) | `'outline'` | no | Button visual variant. Forwarded to the `Button` primitive. | no |
+| (other Button props) | n/a | n/a | no | All other `Button` props are forwarded. The runtime owns `onClick` (with a delegation hook) and `type='button'`. | no |
+
+`SearchBarTriggerProps` is `Omit<React.ComponentPropsWithoutRef<typeof Button>, 'children'> & SearchBarTriggerOwnProps & { children?: React.ReactNode }`. The `children` override allows callers to pass a custom label; when omitted, the trigger renders `Search…`.
+
+**`SearchBar.Menu` props:**
+
+| Prop | Type | Default | Required | Description | Responsive |
+|---|---|---|---|---|---|
+| `contentClassName` | `string` | `undefined` | no | Extra classes appended to the dialog content. | no |
+| `showClose` | `boolean` | `false` | no | Toggles the dialog's close button. | no |
+| `size` | `DialogSize` (the `Dialog` size union) | `'md'` | no | Dialog size. | no |
+| `title` | `string` | `'Search'` | no | Accessible dialog title, rendered via a `VisuallyHidden`-wrapped `DialogTitle`. Fixes the Radix a11y requirement that every `DialogContent` have a `DialogTitle`. | no |
+| (Command props) | n/a | n/a | no | All standard `Command` props are forwarded. | no |
+
+`SearchBarMenuProps` is `CommandProps & SearchBarMenuOwnProps`.
+
+Rules:
+
+- The trigger's `onClick` is wrapped: the runtime calls the consumer's `onClick` first, then opens the menu unless `event.defaultPrevented` is true. Consumers that want to suppress the open can call `event.preventDefault()` in their handler.
+- The `Cmd/Ctrl + K` listener is only attached when `openOnShortcut` is `true` and the code is running in a browser. The listener is added with `window.addEventListener('keydown', handleKeyDown)` and removed on cleanup.
+- The trigger renders a `<button type="button">` to avoid form-submit side effects.
+
+## CSS class contract
+
+**Root class:** `dsx-search-bar`
+
+**Modifier classes** (driven by `data-*` attributes written by the component):
+
+| Attribute | Allowed values | Class | CSS file |
+|---|---|---|---|
+| `data-size` | `sm`, `md`, `lg` | (attribute written on root; no per-size CSS rule today) | `search-bar.css` |
+| `data-variant` | `default`, `ghost` | (attribute written on root; no per-variant CSS rule today) | `search-bar.css` |
+| `data-radius` | `none`, `sm`, `md`, `lg`, `full` | (attribute written on root; CSS does not yet declare matching rules) | `search-bar.css` |
+
+**Slot classes:**
+
+| Slot | Class | CSS file |
+|---|---|---|
+| `SearchBar` (Root) | `dsx-search-bar` (+ `dsx-search-bar--compact` when `compact`) | `search-bar.css` |
+| `SearchBar.Trigger` | `dsx-search-bar__trigger` | `search-bar.css` |
+| Trigger content | `dsx-search-bar__trigger-content` | `search-bar.css` |
+| Trigger label | `dsx-search-bar__trigger-label` | `search-bar.css` |
+| Trigger shortcut (Kbd) | `dsx-search-bar__shortcut` | `search-bar.css` |
+| `SearchBar.Menu` | `dsx-search-bar__menu` (on the dialog content), `dsx-search-bar__command` (on the inner Command shell) | `search-bar.css` |
+
+**Responsive behavior:**
+
+- The component does not write `@media` rules. None of the prop defs are `responsive: true`. Size and radius are single-value only.
+
+**Reduced motion:**
+
+- The component does not declare motion. The Dialog's open/close motion follows the standard `MOTION_TRANSITIONS.dialog` binding owned by the `Dialog` primitive.
+
+## Token mapping
+
+Every CSS value the component paints is a `var(--dsx-*)` token.
+
+| Property | Token | Role |
+|---|---|---|
+| Container gap | `var(--dsx-space-sm)` | Default gap. |
+| Container gap (compact) | `var(--dsx-space-xs)` | Compact gap. |
+| Trigger width | `100%` | Trigger fills the container. |
+| Trigger justify | `flex-start` | Trigger label is left-aligned. |
+| Trigger content gap | `var(--dsx-space-sm)` | Gap between leading icon, label, and trailing shortcut. |
+| Trigger label color | `var(--dsx-color-on-surface-variant)` | Label fill. |
+| Shortcut margin | `auto` | Shortcut sits on the right edge. |
+| Menu padding | `0` | Dialog content has no internal padding. |
+| Menu overflow | `hidden` | Dialog content clips child overflow. |
+| Command shell min-height | `20rem` (hard-coded) | Forces a usable palette height. |
+| Command shell border | `0` | Removes the Command border. |
+| Command shell radius | `inherit` | Picks up the dialog content radius. |
+| Command shell shadow | `none` | Removes the Command shadow. |
+| Command shell background | `transparent` | Picks up the dialog content background. |
+
+Rules:
+
+- The `20rem` Command shell min-height is the only intentional non-token value. The source comment does not call it out, but it is a deliberate choice to keep the palette usable before the consumer's `Command.List` content has measured.
+- The CSS file does not introduce motion durations or easing curves.
+
+## Motion contract
+
+| Region | Token | Default | Reduced |
+|---|---|---|---|
+| `SearchBar.Menu` open/close | inherited from `Dialog` (`MOTION_TRANSITIONS.dialog`) | n/a | inherited from `Dialog` |
+| `SearchBar.Trigger` | `none` | n/a | n/a |
+
+Rules:
+
+- The `SearchBar` runtime does not import `usePrefersReducedMotion` or `MOTION_TRANSITIONS`. All motion comes from the inner `Dialog` primitive and the inner `Command` primitive. Reduced motion is honored at the primitive level, not at the `SearchBar` level.
+
+## Accessibility
+
+**Roles:**
+
+- The trigger renders as a `<button>` through the `Button` primitive. The button's accessible name is the trigger label.
+- The menu mounts a `Dialog`. `SearchBarMenu` renders a `VisuallyHidden`-wrapped `DialogTitle` (the `title` prop, default `'Search'`) so the dialog always has an accessible name. **FIXED 2026-07-03 (visual triage V-1):** previously `SearchBarMenu` rendered no `DialogTitle` at all, which triggered Radix's `DialogContent requires a DialogTitle` console error on every open.
+
+**Keyboard:**
+
+| Key | Action |
+|---|---|
+| `Tab` | Moves focus to or from the trigger. |
+| `Enter`, `Space` | Opens the palette when the trigger is focused. |
+| `Cmd/Ctrl + K` | Toggles the palette open or closed when the trigger is not focused. The listener is attached at the `window` level and removed on unmount. |
+| `Escape` | Closes the palette (delegated to `Dialog`). |
+
+**Focus:**
+
+- The trigger's focus ring follows the `Button` primitive contract. Inside the palette, focus management is owned by `Dialog` and `Command`.
+
+**Reduced motion:**
+
+- Inherited from `Dialog` and `Command`. The `SearchBar` runtime does not introduce its own motion.
+
+**Color and meaning:**
+
+- The shortcut hint uses the same surface tokens as the `Kbd` primitive. The trigger label uses `var(--dsx-color-on-surface-variant)`. The state is communicated by the icon, the label, and the keyboard shortcut hint, not by color alone.
+
+**Naming:**
+
+- The trigger's accessible name is its `children` text (default `Search…`). Provide an explicit label when the trigger is icon-only.
+
+## Playground demo spec
+
+**Default story:**
+
+- Renders `SearchBar` with no extra props. Asserts the root class is `dsx-search-bar`, the trigger renders, and the `Cmd/Ctrl + K` shortcut chip is visible.
+
+**Variant story:**
+
+- Renders one `SearchBar` per `variant` value (`default`, `ghost`). Asserts the matching `data-variant` attribute is set on the root.
+
+**Size story:**
+
+- Renders one `SearchBar` per `size` value (`sm`, `md`, `lg`). Asserts the matching `data-size` attribute is set on the root.
+
+**State story:**
+
+- Renders `SearchBar` with `openOnShortcut={false}`. Asserts the trigger still renders, but the keyboard shortcut hint is hidden when the consumer also passes `showShortcut={false}`.
+- Renders `SearchBar` with `compact`. Asserts the `dsx-search-bar--compact` modifier class is added.
+
+**Composition story:**
+
+- Renders `SearchBar` with a `SearchBar.Trigger` and a `SearchBar.Menu` containing a `Command.Input` and a `Command.List`. Asserts the menu is mounted, the dialog content has the `dsx-search-bar__menu` class, and the inner `Command` has the `dsx-search-bar__command` class.
+
+**Token story:**
+
+- Renders the trigger inside a `Theme` wrapper with `accentColor="silver"` and one with `accentColor="bronze"`. The component does not currently paint accent-color rules, so the story asserts the row still renders without an accent-color override.
+
+**A11y story:**
+
+- Uses `vitest-axe` against a `SearchBar` whose menu is closed. Asserts there are no axe violations.
+- Uses `vitest-axe` against a `SearchBar` whose menu is open with a populated `Command.List`. Asserts there are no axe violations.
+
+**Props exposed in the playground controls:**
+
+| Prop | Control | Default |
+|---|---|---|
+| `variant` | select | `default` |
+| `size` | select | `md` |
+| `radius` | select | (none) |
+| `compact` | boolean | `false` |
+| `openOnShortcut` | boolean | `true` |
+| `showShortcut` | boolean | `true` |
+| `shortcutLabel` | text | `⌘K` |
+
+## Wiring notes
+
+**Composes from:**
+
+- `Command` (DS primitive): the search-first list, item selection, keyboard navigation, and the empty-state row.
+- `Dialog` (DS primitive, radix-compound): the modal palette. The `SearchBar.Menu` slot mounts a `Dialog` and uses `DialogContent` to host the inner `Command`.
+- `Button` (DS primitive): the trigger button. The runtime uses the `outline` variant by default and forwards all other `Button` props.
+- `Icon` (lucide-react `search`): the leading icon on the trigger.
+- `Kbd` (DS primitive): the trailing shortcut hint on the trigger.
+- `@radix-ui/react-slot`: enables `asChild` on the root and on the trigger.
+
+**Used by:**
+
+- `DataTable` (per the roster's `Composed From` column) uses `SearchBar` for the `ToolbarSearch` slot. The `DataTable` runtime imports `SearchBar` to render the toolbar search.
+- App-level search bars in the cabinet shell.
+
+**State boundaries:**
+
+- Owned by `SearchBar`: the `SearchBarContext` (`open`, `setOpen`, `toggleOpen`), the controlled / uncontrolled open state, the `Cmd/Ctrl + K` shortcut listener, the `data-*` attribute contract on the root, and the trigger's open wiring.
+- Owned by the consumer: the search registry (commands, navigation, results), the open label, the shortcut label, the open handler, the surrounding layout, and the form context.
+
+**Boundary rules:**
+
+- App-owned data: the search registry, the persisted shortcut binding, the analytics events, the disabled reason, and the persistence target.
+- DS-owned visuals: token bindings, the `dsx-search-bar*` slot classes, the `data-*` attribute contract, the trigger's `outline` default variant, and the `Cmd/Ctrl + K` listener shape.
+
+## Penpot build recipe
+
+> Optional. Penpot is a visual reference, not a code authority. Keep this section when the component has a published Penpot asset, or when the spec needs to call out a visual decision the package does not encode. Skip the section when the component is utility or layout-primitive; the package code is the only authority.
+
+The package does not yet publish a Penpot asset for SearchBar. Recipe is visual reference only and tracks the CSS contract.
+
+### Root board
+
+- **Name**: `Components / SearchBar`.
+- **Dimensions**: `auto × auto` (sized by `data-size`).
+- **Layout**: `Flex` (row for the root, column for the menu).
+- **Sizing**: `horizontalSizing = 'fix'`, `verticalSizing = 'auto'`.
+
+### Layer tree
+
+```
+<Root Board: SearchBar>
+  ├── <Frame: trigger>
+  │     ├── <Icon: search>
+  │     ├── <Text: label>
+  │     └── <Frame: shortcut (Kbd)>
+  └── <Frame: menu (Dialog)>
+        └── <Frame: command shell>
+              ├── <Text: command input>
+              └── <Frame: command list>
+                    ├── <Frame: item × N>
+                    └── <Text: empty (when no match)>
+```
+
+### Token bindings (Penpot properties)
+
+| Shape | Property | Token | Token type | Penpot property name |
+|---|---|---|---|---|
+| Container | gap | `--dsx-space-sm` | Spacing | `gap` |
+| Container (compact) | gap | `--dsx-space-xs` | Spacing | `gap` |
+| Trigger content | gap | `--dsx-space-sm` | Spacing | `gap` |
+| Trigger label | fill | `--dsx-color-on-surface-variant` | Color | `fills` |
+| Command shell | min-height | `20rem` | Sizing | `min-height` |
+| Command shell | shadow | `none` | Effect | `shadow` |
+| Command shell | fill | `transparent` | Color | `fills` |
+
+### State transformations
+
+| State | Trigger | Menu |
+|---|---|---|
+| `default` (closed) | `outline` button + trailing Kbd | hidden |
+| `default` (open) | `outline` button + trailing Kbd | visible, opens dialog |
+| `compact` (closed) | same trigger, container gap shrinks | hidden |
+| `compact` (open) | same trigger, container gap shrinks | visible, opens dialog |
+
+### Variant model
+
+- `variant`: `default`, `ghost`. Default `default`.
+- `size`: `sm`, `md`, `lg`. Default `md`.
+- `radius`: `none`, `sm`, `md`, `lg`, `full`. Default unset.
+- `compact`: `true`, `false`. Default `false`.
+- `openOnShortcut`: `true`, `false`. Default `true`.
+- `showShortcut`: `true`, `false`. Default `true`.
+- Total members: 2 × 3 × 5 × 2 × 2 × 2 = 240.
+
+### Validation checklist
+
+- [ ] Token bindings resolve at the values `DESIGN.md` describes.
+- [ ] Component is promoted to Main Component under `Components`.
+- [ ] `penpotUtils.shapeStructure(board, 3)` matches the expected hierarchy.
+- [ ] The trigger's search icon and shortcut hint are baked in; do not treat them as themable in Penpot.
+- [ ] The 20rem Command shell min-height is baked in as a deliberate value, not as a Penpot token.

package/dist/docs/section.md

@@ -0,0 +1,208 @@
+---
+title: Section
+status: canonical
+category: Foundations
+archetype: layout-primitive
+package_path: packages/d4gger-design-system/src/components/section/Section.tsx
+css_path: packages/d4gger-design-system/src/styles/components/section.css
+props_path: packages/d4gger-design-system/src/components/section/section.props.ts
+test_path: packages/d4gger-design-system/src/test/components/Section.test.tsx
+demo_path: apps/playground/app/(themeable)/docs/[component]/page.tsx
+playground_registry_path: apps/playground/lib/registry/layout.tsx
+playground_manifest_path: apps/playground/lib/component-manifest.ts
+depends_on:
+  - Box
+---
+
+# Section
+
+> Source of truth: the package source at `package_path`. The spec mirrors the source. Edits to the spec must land in the source in the same change, or the QA flags will fire.
+
+## Purpose
+
+A page-level vertical-rhythm wrapper that applies a `size` ramp to block-axis padding on top of the inherited `Box` style props. `Section` extends `Box`, defaults the host element to `<section>`, and is the canonical primitive for top-level page regions.
+
+## Anatomy & slots
+
+**Parent:** `Section` (alias of `Section.Root`; flat export, no compound).
+
+**Slots:**
+
+No slots: flat export. `Section` is a single forwardRef that renders a host element chosen by `as`, or `<section>` by default. The body is whatever the consumer passes as `children`.
+
+## Props contract
+
+| Prop | Type | Default | Required | Description | Responsive |
+|---|---|---|---|---|---|
+| `as` | `React.ElementType` | `'section'` | no | Host element. `asChild` takes precedence when set. | no |
+| `asChild` | `boolean` | `false` | no | Renders the host through `Slot`; consumer supplies the child. | no |
+| `size` | `ResponsiveValue<'1' \| '2' \| '3'>` | `undefined` | no | Block-axis padding ramp. Resolves `--dsx-section-space`. `1`→`var(--dsx-space-md)`, `2`→`var(--dsx-space-xl)`, `3`→`var(--dsx-space-2xl)`. The serialized value is also written to the `data-size` attribute when it is a single string. | yes (initial, sm, md, lg, xl, 2xl) |
+| `space` | `ResponsiveValue<SpaceToken \| string>` | `'2xl'` | no | Block-axis padding from the spacing scale. Resolves `--dsx-section-space`. Wins over `size` when both are set. | yes (initial, sm, md, lg, xl, 2xl) |
+| (all `Box` style props) | (see [Box](./box.md)) | `undefined` | no | Inherited: `display`, `position`, `padding`, `paddingX`, `paddingY`, `px`, `py`, `pt`, `pr`, `pb`, `pl`, `p`, `margin`, `m`, `mx`, `my`, `mt`, `mr`, `mb`, `ml`, `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`. | yes where Box marks them responsive |
+| `className` | `string` | `undefined` | no | Extra classes appended to the generated utility class string. | no |
+| `style` | `React.CSSProperties` | `undefined` | no | Extra inline style merged with the generated `--dsx-*` variables. | no |
+| `children` | `React.ReactNode` | `undefined` | no | Section body. | no |
+| `ref` | `React.Ref<HTMLElement>` | `undefined` | no | Forwarded to the host element. | no |
+
+Rules:
+
+- Every prop above is declared on `Section` in `Section.tsx` or in `BoxStyleProps` / `SectionStyleProps` from `layout.props.ts`. The runtime type is the source of truth.
+- `size` and `space` share the same `--dsx-section-space` custom property. When both are set, `space` wins because the prop def declares it second in `SECTION_PROP_DEFS`.
+- The `Responsive` column is `yes` for `size` and `space`. The Box-inherited props are `yes` where Box marks them responsive.
+- The `data-size` attribute is the bare value when `size` is a string. `space` does not write a data attribute.
+
+## CSS class contract
+
+**Root class:** `dsx-section`
+
+In addition, Section writes `dsx-box` so the inherited Box tokens apply.
+
+**Modifier attributes:**
+
+| Attribute | Value | Notes |
+|---|---|---|
+| `data-size` | single string `size` value | Only when `size` is a string (e.g. `1`, `2`, `3`). Responsive maps do not write `data-size`. |
+
+The combined selector `.dsx-box.dsx-section` applies the block-axis padding cascade so Section wins over the Box physical padding longhands:
+
+```css
+.dsx-box.dsx-section {
+  padding-block: var(--dsx-section-space, var(--dsx-box-padding, var(--dsx-space-2xl)));
+}
+```
+
+`section.css` then re-declares the same rule inside `@media (min-width: ...)` blocks for `sm`, `md`, `lg`, `xl`, `2xl` so per-breakpoint variables resolve in cascade order.
+
+**Slot classes:** none. Section is a flat export.
+
+**Responsive behavior:**
+
+- The runtime writes `--dsx-section-space` per breakpoint through `assignResponsiveVars`.
+- `space` accepts a `ResponsiveValue<SpaceToken | string>`; tokens resolve through `resolveSpace` in `foundations/Shared.tsx`.
+
+**Reduced motion:**
+
+- Section has no motion. No transitions or animations are declared in `section.css`.
+
+## Token mapping
+
+Every CSS value the component paints is a `var(--dsx-*)` token.
+
+| Property | Token | Role |
+|---|---|---|
+| Padding block | `var(--dsx-section-space, var(--dsx-box-padding, var(--dsx-space-2xl)))` | Default `var(--dsx-space-2xl)` |
+| Size ramp | `1`→`var(--dsx-space-md)`, `2`→`var(--dsx-space-xl)`, `3`→`var(--dsx-space-2xl)` | `size` value resolution |
+| Space ramp | `var(--dsx-space-{none,xs,sm,md,lg,xl,2xl,3xl,gutter,margin})` | `space` value resolution |
+| (all inherited Box tokens) | (see [Box](./box.md)) | Padding, margin, sizing, surface, radius, border, shadow |
+
+Rules:
+
+- No raw color, spacing, radius, or motion values in the CSS. Tokens only.
+- The token list is closed; new tokens are a `DESIGN.md` change first.
+
+## Motion contract
+
+| Region | Token | Default | Reduced |
+|---|---|---|---|
+| (none) | `none` | `none` | `none` |
+
+Section has no motion. The motion section is intentionally empty.
+
+## Accessibility
+
+**Roles:**
+
+- `<section>` element by default. The host element is configurable through `as`. The `Section` host should be paired with a heading region per the WAI-ARIA landmark pattern. Consumers should set `aria-labelledby` or `aria-label` when the section purpose is not obvious from context.
+
+**Keyboard:**
+
+- Section is not interactive. No keyboard contract beyond the page-level Tab order.
+
+**Focus:**
+
+- Section has no interactive surface. Focus management is the consumer's responsibility.
+
+**Reduced motion:**
+
+- N/A. Section has no motion.
+
+**Color and meaning:**
+
+- Section does not paint a surface, border, or shadow on its own. Any visual state comes from inherited Box props and is paired with the consumer's content for meaning.
+
+**Naming:**
+
+- Section is a structural landmark. The accessible name should come from a heading inside the section, an `aria-label`, or an `aria-labelledby` reference.
+
+## Playground demo spec
+
+**Default story:**
+
+- Renders `Section` with no extra props and a child node. Asserts the root classes are `dsx-section` and `dsx-box`, the host element is a `section`, and `--dsx-section-space` resolves to `var(--dsx-space-2xl)`.
+
+**Size story:**
+
+- Renders `Section size="1"`, `Section size="2"`, and `Section size="3"`. Asserts the `data-size` attribute and the matching `--dsx-section-space` value (`var(--dsx-space-md)`, `var(--dsx-space-xl)`, `var(--dsx-space-2xl)`).
+
+**Space story:**
+
+- Renders `Section space="md"` and asserts `--dsx-section-space` resolves to `var(--dsx-space-md)`.
+
+**Responsive story:**
+
+- Renders `Section size={{ initial: '1', md: '3' }}` and `Section space={{ initial: 'md', lg: '2xl' }}`. Asserts the per-breakpoint `--dsx-section-space-*` custom property and the matching `padding-block` resolution.
+
+**Composition story:**
+
+- Renders `Section` with two `Box` children showing different surface tones. Asserts the children keep their own `dsx-box` class and inherit the Section's block padding.
+
+**State story:**
+
+- No discrete state. The story renders a default Section with two children.
+
+**Token story:**
+
+- Section does not honor `data-accent-color`. Render inside a `Theme` wrapper with `accentColor="silver"` and `accentColor="bronze"`. The story asserts the layout is unchanged and any surfaces come from the theme.
+
+**A11y story:**
+
+- Use `vitest-axe` against the rendered Section. The default render is a `<section>` with text content; tests assert no violations.
+
+**Props exposed in the playground controls:**
+
+| Prop | Control | Default |
+|---|---|---|
+| `size` | select | `undefined` |
+| `space` | select | `2xl` |
+
+## Wiring notes
+
+**Composes from:**
+
+- `Box`: the host class and inherited style props. Section writes `dsx-section` and `dsx-box` together.
+- `Slot` from `@radix-ui/react-slot`: enables `asChild`.
+- `_internal/props/propDef.ts` and the helpers in `_internal/helpers/`: the responsive class + custom-property pipeline.
+- `foundations/Shared.tsx`: `PolymorphicProps`, `SpaceToken`, and the `resolve*` helpers.
+- `layout/responsive.props.ts`: `BREAKPOINTS`, `ResponsiveValue`, `assignResponsiveVars`.
+- `layout/layout.props.ts`: `BoxStyleProps`, `SectionStyleProps`, `BOX_PROP_DEFS`, `SECTION_PROP_DEFS`, `extractLayoutProps`, `parseSectionSizeValue`.
+- `components/section/section.props.ts`: the `sectionPropDefs` bag (declares `size` as a `PropDef` enum) and `sectionSizeValues`.
+- `styles/components/section.css`: the `.dsx-box.dsx-section` combined selector and the breakpoint cascade.
+- `styles/components/box.css`: imported transitively through `section.css`.
+
+**Used by:**
+
+- `Sidebar`, `Shell`, `Header`, `Footer`, `Cabinet Shell`, and most app-shell page regions: build their top-level page regions on top of `Section`.
+
+**State boundaries:**
+
+- Owned by `Section`: the host element selection (`as` / `asChild`, defaulting to `<section>`), the responsive prop resolution, the size ramp resolution (`1`/`2`/`3`), the space resolution (`SpaceToken` or string), the generated utility classes, and the host classes.
+- Owned by the consumer: the children, the host element tag, the user-supplied `className` and `style`, the ref target, and any `aria-label` or `aria-labelledby` for the section landmark.
+
+**Boundary rules:**
+
+- App-owned data: the children content, the host element tag (when not the default `<section>`), the section's accessible name, and any host element chosen via `as` or `asChild`.
+- DS-owned visuals: token bindings, the `dsx-section` and `dsx-box` root classes, the size ramp values, the responsive utility classes, and the `data-size` attribute contract.
+
+## Penpot build recipe
+
+Section is a layout primitive. The package code is the only authority. There is no published Penpot build recipe for Section. A future Penpot board would show a page-level section with the size ramp controls, but the spec intentionally does not duplicate the runtime class contract in a visual recipe.