@d4gger/design-system 2.7.0

package/dist/docs/icon-button.md

@@ -0,0 +1,254 @@
+---
+title: IconButton
+status: canonical
+category: Primitives
+archetype: primitive
+package_path: packages/d4gger-design-system/src/components/iconButton/IconButton.tsx
+css_path: packages/d4gger-design-system/src/styles/components/icon-button.css
+props_path: packages/d4gger-design-system/src/components/iconButton/iconButton.props.ts
+test_path: packages/d4gger-design-system/src/test/components/IconButton.test.tsx
+demo_path: apps/playground/app/(themeable)/docs/[component]/page.tsx
+playground_registry_path: apps/playground/lib/registry/actions.tsx
+playground_manifest_path: apps/playground/lib/component-manifest.ts
+depends_on:
+  - Button
+  - Spinner
+  - Icon
+---
+
+# IconButton
+
+> 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 compact icon-only button with a required accessible name, used for toolbar toggles, dialog close affordances, and any action that does not have room for a text label. The component enforces a square hit target and a built-in loading state with a centered spinner.
+
+## Anatomy & slots
+
+**Parent:** `IconButton` (no compound; flat export). The component renders a single `<button>` host element (or a slotted child when `asChild` is set) through the package's `BaseButton` engine. Internal layout elements are implementation details: `dsx-icon-button__content` wraps the icon, and `dsx-icon-button__spinner` hosts the loading indicator. These are not public slots.
+
+**Slots:**
+
+No slots: flat export. The visible body is whatever the consumer passes as `children` (typically an `Icon` element). The component does not own a fallback icon.
+
+## Props contract
+
+| Prop | Type | Default | Required | Description | Responsive |
+|---|---|---|---|---|---|
+| `variant` | `'primary' \| 'secondary' \| 'ghost' \| 'destructive' \| 'outline'` | `'ghost'` | no | Visual treatment; writes `data-variant`. | no |
+| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | no | Square hit target; writes `data-size`. | no |
+| `radius` | `'none' \| 'sm' \| 'md' \| 'lg' \| 'full'` | `undefined` | no | Corner roundness; writes `data-radius`. The root class uses `var(--dsx-rounded-full)` by default. | no |
+| `color` | `string` | `undefined` | no | Accent color; writes `data-accent-color`. The prop def has an empty enum so any string is accepted. | no |
+| `highContrast` | `boolean` | `false` | no | When `true`, swaps to the high-contrast palette; writes `data-high-contrast="true"`. | no |
+| `loading` | `boolean` | `false` | no | When `true`, swaps the visible icon for a centered spinner and disables interaction. Writes `data-loading="true"` and `aria-busy="true"` through `BaseButton`. | no |
+| `asChild` | `boolean` | `false` | no | Renders the button through `Slot`; consumer supplies the host element. `type` is dropped in this mode. | no |
+| `type` | `'button' \| 'submit' \| 'reset'` | `'button'` | no | Native button type. Ignored when `asChild` is `true`. | no |
+| `disabled` | `boolean` | `false` | no | When `true`, disables interaction and swaps to the disabled palette. Forwarded to `BaseButton` which sets `data-disabled="true"`. | no |
+| `aria-label` | `string` | `undefined` | no | Required for accessibility. The screen reader announces this when the button is focused. | no |
+| `className` | `string` | `undefined` | no | Extra classes appended to `dsx-icon-button`. | no |
+| `style` | `React.CSSProperties` | `undefined` | no | Extra inline style forwarded to the host element. | no |
+| `children` | `React.ReactNode` | `undefined` | no | The icon element. Typically a single `Icon` (for example `<Icon name="settings" />`). | no |
+
+Rules:
+
+- `IconButton` extends `Omit<ComponentPropsWithoutRef<'button'>, 'color'>` because `color` is redefined by the prop def bag.
+- All listed props are wired through `extractProps` and the prop def bag. The runtime also passes the resolved `loading` to `BaseButton` so the disabled-while-loading click guard fires.
+- The component has no `leadingIcon` or `trailingIcon` props. The single icon is `children`. The internal `dsx-icon-button__content` wrapper provides the same flex centering that `dsx-button__content` provides in `Button`.
+
+## CSS class contract
+
+**Root class:** `dsx-icon-button`
+
+**Modifier classes** (driven by `data-*` attributes written by the component):
+
+| Attribute | Allowed values | Class | CSS file |
+|---|---|---|---|
+| `data-variant` | `primary`, `secondary`, `ghost`, `destructive`, `outline` | `.dsx-icon-button:where([data-variant='primary'])` etc. | `icon-button.css` |
+| `data-size` | `sm`, `md`, `lg` | `.dsx-icon-button[data-size='sm']` etc. | `icon-button.css` |
+| `data-radius` | `none`, `sm`, `md`, `lg`, `full` | `.dsx-icon-button[data-radius='...']` (CSS hook) | `icon-button.css` |
+| `data-accent-color` | `amber`, `silver`, `bronze` (or any custom string) | `.dsx-icon-button[data-accent-color='...']` (CSS hook) | `icon-button.css` |
+| `data-high-contrast` | `true` | `.dsx-icon-button:where([data-variant='outline'])[data-high-contrast='true']` etc. (variant-specific HC overrides) | `icon-button.css` |
+| `data-loading` | `true` | `.dsx-icon-button[data-loading='true']` | `icon-button.css` |
+| `data-disabled` | `true` | `.dsx-icon-button[data-disabled='true']` | `icon-button.css` |
+| `aria-pressed` | `true` | n/a (CSS does not target this attribute) | n/a |
+
+**Internal classes** (implementation detail, not public slots):
+
+| Class | Role | CSS file |
+|---|---|---|
+| `dsx-icon-button__content` | Flex container for the icon; hidden when loading. | `icon-button.css` |
+| `dsx-icon-button__spinner` | Centered absolute-positioned spinner when loading. | `icon-button.css` |
+| `dsx-icon-button__spinner-indicator` | Inner Spinner class binding. | `icon-button.css` |
+
+**Responsive behavior:**
+
+- The component does not write `@media` rules. `size` is single-value only; the prop def is not `responsive: true`. Density tokens (`--dsx-density-control-height`, `--dsx-density-control-height-sm`, etc.) let parent themes override the square size per breakpoint without adding new variants.
+
+**Reduced motion:**
+
+- The component's `transition` properties on `dsx-icon-button` and `dsx-icon-button__content` collapse to `none` when `@media (prefers-reduced-motion: reduce)` matches. The rule is in `icon-button.css`.
+
+## Token mapping
+
+Every CSS value the component paints is a `var(--dsx-*)` token.
+
+| Property | Token | Role |
+|---|---|---|
+| `box-sizing` | `border-box` (CSS keyword) | Match the package's box model. |
+| `display` | `inline-flex` (CSS keyword) | Inline block. |
+| `align-items`, `justify-content` | `center` (CSS keyword) | Centered icon. |
+| `position` | `relative` (CSS keyword) | Anchor the spinner. |
+| `border-radius` | `var(--dsx-rounded-full)` (default, `data-radius` overrides) | Circular hit target. |
+| `border` | `var(--dsx-border-width-sm) solid transparent` | Invisible default edge; variants paint over it. |
+| `padding` | `0` (zero) | Square hit target. |
+| `font-family` | `var(--dsx-typography-label-large-font-family), sans-serif` | Inherited from the package's button ramp. |
+| `isolation` | `isolate` (CSS keyword) | Stacking context for overlays. |
+| `transition` | `var(--dsx-motion-duration-fast, 150ms) var(--dsx-motion-easing-standard, ease)` | State transitions. |
+| `cursor` | `var(--dsx-cursor-pointer, pointer)` (default), `var(--dsx-cursor-not-allowed, not-allowed)` (disabled), `var(--dsx-cursor-wait, wait)` (loading) | Pointer affordance. |
+| Width and height (`sm`) | `var(--dsx-density-control-height-sm, var(--dsx-size-lg))` | Small square hit target. |
+| Width and height (`md`) | `var(--dsx-density-control-height, var(--dsx-size-xl))` | Default square hit target. |
+| Width and height (`lg`) | `var(--dsx-density-control-height-lg, var(--dsx-size-2xl))` | Large square hit target. |
+| Background (primary) | `var(--dsx-color-primary)` | Primary fill. |
+| Text (primary) | `var(--dsx-color-on-primary)` | Primary icon. |
+| Border (primary) | `var(--dsx-color-primary)` | Primary edge. |
+| Background (primary hover) | `linear-gradient(var(--dsx-effect-hover-primary), var(--dsx-effect-hover-primary)), var(--dsx-color-primary)` | Primary hover overlay. |
+| Background (secondary) | `var(--dsx-color-secondary)` | Secondary fill. |
+| Text (secondary) | `var(--dsx-color-on-secondary)` | Secondary icon. |
+| Border (secondary) | `var(--dsx-color-secondary)` | Secondary edge. |
+| Background (secondary hover) | `var(--dsx-color-secondary-container)` | Secondary hover fill. |
+| Text (secondary hover) | `var(--dsx-color-on-secondary-container)` | Secondary hover icon. |
+| Border (secondary hover) | `var(--dsx-color-secondary-container)` | Secondary hover edge. |
+| Background (outline) | `transparent` (CSS keyword) | Outline fill. |
+| Border (outline) | `var(--dsx-color-outline-variant)` | Outline edge. |
+| Text (outline) | `var(--dsx-color-on-surface)` | Outline icon. |
+| Background (outline HC) | `var(--dsx-color-high-contrast-container)` | High-contrast outline fill. |
+| Border (outline HC) | `var(--dsx-color-high-contrast-border)` | High-contrast outline edge. |
+| Text (outline HC) | `var(--dsx-accent-indicator)` | High-contrast outline icon. |
+| Background (ghost) | `transparent` (CSS keyword) | Ghost fill. |
+| Text (ghost) | `var(--dsx-color-on-surface)` | Ghost icon. |
+| Text (ghost HC) | `var(--dsx-accent-indicator)` | High-contrast ghost icon. |
+| Background (ghost hover) | `linear-gradient(var(--dsx-effect-hover-ghost), var(--dsx-effect-hover-ghost)), transparent` | Ghost hover overlay. |
+| Text (ghost hover) | `var(--dsx-color-primary)` | Ghost hover icon. |
+| Background (destructive) | `var(--dsx-color-error)` | Destructive fill. |
+| Text (destructive) | `var(--dsx-color-on-error)` | Destructive icon. |
+| Border (destructive) | `var(--dsx-color-error)` | Destructive edge. |
+| Background (destructive hover) | `linear-gradient(var(--dsx-effect-hover-secondary), var(--dsx-effect-hover-secondary)), var(--dsx-color-error)` | Destructive hover overlay. |
+| Background (destructive HC) | `var(--dsx-color-error)` | High-contrast destructive fill. |
+| Border (destructive HC) | `var(--dsx-color-high-contrast-border)` | High-contrast destructive edge. |
+| Focus ring | `var(--dsx-shadow-focus-ring)` | Visible focus ring on `:focus-visible`. |
+| Disabled cursor | `var(--dsx-cursor-not-allowed, not-allowed)` | Disabled affordance. |
+| Disabled opacity | `var(--dsx-opacity-disabled)` | Disabled fade. |
+| Spinner color | `currentColor` (default) and `var(--dsx-color-on-surface)` (loading on disabled) | Spinner inherits text color. |
+
+Rules:
+
+- No raw color, spacing, radius, or motion values in `icon-button.css`.
+
+## Motion contract
+
+| Region | Token | Default | Reduced |
+|---|---|---|---|
+| State transitions (`background-color`, `border-color`, `box-shadow`, `color`, `opacity`) | `var(--dsx-motion-duration-fast, 150ms)` + `var(--dsx-motion-easing-standard, ease)` | Animates the fill, edge, focus ring, and text color changes on hover, focus, active, and disabled. | `transition: none` inside `@media (prefers-reduced-motion: reduce)`. |
+| Content fade (`opacity`) | `var(--dsx-motion-duration-fast, 150ms)` + `var(--dsx-motion-easing-standard, ease)` | Fades the visible icon when loading swaps it for the spinner. | `transition: none` inside `@media (prefers-reduced-motion: reduce)`. |
+
+Rules:
+
+- The package's `icon-button.css` does not use `MOTION_TRANSITIONS` JS presets; the runtime does not import framer-motion for IconButton. The CSS rules own the transition behavior and the reduced-motion fallback.
+
+## Accessibility
+
+**Roles:**
+
+- `<button>` by default. When `asChild` is set, the consumer's host element owns the role. The accessibility contract requires a focusable, pressable host (anchor with `href`, etc.).
+
+**Keyboard:**
+
+| Key | Action |
+|---|---|
+| `Tab` | Moves focus to or from the button. |
+| `Enter`, `Space` | Activates the button (native semantics). |
+
+**Focus:**
+
+- The visible focus ring is `var(--dsx-shadow-focus-ring)`, applied on `:focus-visible`. The `icon-button.css` does not reset `outline`, so the focus ring stacks with the native browser outline.
+
+**Reduced motion:**
+
+- Transitions collapse to `none` when `prefers-reduced-motion: reduce` matches. The `loading` state still swaps the icon for a static spinner.
+
+**Color and meaning:**
+
+- The variant communicates intent (`primary` for actions, `destructive` for removal). The icon must carry the same meaning so the variant color is not the only signal.
+
+**Naming:**
+
+- The accessible name must be supplied by the consumer. IconButton never auto-generates a label; without `aria-label` (or a wrapping labelled element), the screen reader will announce only "button" with no context. This is a deliberate contract: an icon-only button with no label is a contract violation.
+
+## Playground demo spec
+
+**Default story:**
+
+- Renders `IconButton` with `aria-label="Settings"` and `<Icon name="settings" />` as children. Asserts the root class is `dsx-icon-button`, `data-variant="ghost"`, and `data-size="md"` are set.
+
+**Variant story** (one per variant value):
+
+- Renders IconButton with `variant="primary"`, `variant="secondary"`, `variant="ghost"`, `variant="destructive"`, and `variant="outline"`. Asserts the matching `data-variant` attribute on the root.
+
+**Size story:**
+
+- Renders IconButton with `size="sm"`, `size="md"`, and `size="lg"`. Asserts the matching `data-size` attribute on the root.
+
+**State story:**
+
+- Renders IconButton with `loading={true}`. Asserts the visible icon is hidden, the `.dsx-icon-button__spinner` element is rendered, the button is disabled, and `aria-busy="true"` is set.
+- Renders IconButton with `disabled`. Asserts the button is disabled, `data-disabled="true"` is set, and the disabled palette is applied.
+- Renders IconButton with `highContrast`. Asserts `data-high-contrast="true"` is set.
+
+**Composition story:**
+
+- Renders IconButton with `aria-label="Add item"` wrapping a custom `<svg>` element. Asserts the host element is `button`, the `dsx-icon-button` class is preserved, and the SVG is rendered inside `dsx-icon-button__content`.
+
+**Token story:**
+
+- Renders inside a `Theme` wrapper with `accentColor="silver"` and one with `accentColor="bronze"`. Asserts the `data-accent-color` attribute is `silver` and `bronze` respectively.
+
+**A11y story:**
+
+- Uses `vitest-axe` against the rendered default icon button. Asserts there are no axe violations.
+
+**Props exposed in the playground controls:**
+
+| Prop | Control | Default |
+|---|---|---|
+| `variant` | select | `ghost` |
+| `size` | select | `md` |
+| `radius` | select | (none) |
+| `color` | text | (empty) |
+| `highContrast` | boolean | `false` |
+| `loading` | boolean | `false` |
+| `disabled` | boolean | `false` |
+| `asChild` | boolean | `false` |
+
+## Wiring notes
+
+**Composes from:**
+
+- `BaseButton` (`src/_internal/BaseButton.tsx`): owns `asChild`, `loading`, `disabled`, `data-disabled`, `data-loading`, `aria-busy`, `aria-disabled`, and the disabled-while-loading click guard. IconButton passes these through unchanged.
+- `Spinner` (`src/components/spinner/Spinner.tsx`): the centered loading indicator. The runtime sets `spinnerSize = size === 'lg' ? 'md' : 'sm'`.
+- `Icon` (`src/components/icon/Icon.tsx`): the typical child. The component does not import Icon directly; consumers pass any icon element as `children`.
+- `@radix-ui/react-slot`: provides the `Slottable` wrapper used when `asChild` is set.
+
+**Used by:**
+
+- `CopyButton` (in the registry), `TagsInput` (dismiss buttons), `NumberInput` (stepper buttons), `InputGroup` (inline action buttons), toolbars, dialog and sheet close affordances, and command palette triggers. The roster currently lists no DS components that consume IconButton outside the standard helpers; the runtime imports nothing else from the package.
+
+**State boundaries:**
+
+- Owned by IconButton: the root class, the variant, size, radius, accent color, and high-contrast data attributes, the loading state, the spinner, the disabled state, and the square hit target sizing.
+- Owned by the consumer: the icon node, the accessible name, the `onClick` handler, and the host element when `asChild` is set.
+
+**Boundary rules:**
+
+- App-owned data: the icon semantics, the action label, the `aria-label`, the `onClick` handler, and the form action when `type="submit"`.
+- DS-owned visuals: the `dsx-icon-button` root class, the variant and size modifier selectors, the focus ring, the spinner, the typography tokens, the disabled palette, and the density tokens.

package/dist/docs/icon.md

@@ -0,0 +1,185 @@
+---
+title: Icon
+status: canonical
+category: Primitives
+archetype: primitive
+package_path: packages/d4gger-design-system/src/components/icon/Icon.tsx
+css_path: packages/d4gger-design-system/src/components/icon/Icon.tsx
+props_path: packages/d4gger-design-system/src/components/icon/icon.props.ts
+test_path: packages/d4gger-design-system/src/test/components/Icon.test.tsx
+demo_path: apps/playground/app/(themeable)/docs/[component]/page.tsx
+playground_registry_path: apps/playground/lib/registry/utility.tsx
+playground_manifest_path: apps/playground/lib/component-manifest.ts
+depends_on: []
+---
+
+# Icon
+
+> 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 named icon surface backed by `lucide-react` (line and UI icons) and `@icons-pack/react-simple-icons` (brand and service icons), exposed through a single `name` prop and a four-step size scale. This is the canonical icon primitive for the package.
+
+## Anatomy & slots
+
+**Parent:** `Icon` (no compound; flat export). The component renders a single `<svg>` host element. The `dsxIconCatalog` exports a frozen list of all available icon names grouped by category. The internal `createDSXIconComponent` helper builds per-name React components used by the broader package (for example `dsxCheck`, `dsxCopy`).
+
+**Slots:**
+
+No slots: flat export. The component renders a single `<svg>` host. The body content is whatever the consumer passes as `children`; the icon path is determined by the `name` prop and rendered by the underlying Lucide or Simple Icons primitive.
+
+## Props contract
+
+| Prop | Type | Default | Required | Description | Responsive |
+|---|---|---|---|---|---|
+| `name` | `string` | `undefined` | yes | The icon name. The runtime accepts any `DSXIconName` from the icon catalog; passing an unknown name renders nothing. | no |
+| `size` | `'sm' \| 'md' \| 'lg' \| 'xl'` | `'md'` | no | The internal size scale. The component maps this to a pixel value (`sm=16`, `md=20`, `lg=24`, `xl=32`) and writes `data-size`. | no |
+| `title` | `string` | `undefined` | no | When provided, the component sets `role="img"` and `aria-hidden="false"`, and renders a `<title>` child for assistive tech. When omitted, the component sets `role="presentation"` and `aria-hidden="true"`. | no |
+| `color` | `string` | (per-variant default) | no | A color value. For Lucide icons this becomes the SVG `color` attribute. For Simple Icons it falls back to `currentColor` when not provided. The component is tolerant of free-form strings. | no |
+| `className` | `string` | `undefined` | no | Extra classes appended to `dsx-icon`. | no |
+| `style` | `React.CSSProperties` | `undefined` | no | Extra inline style forwarded to the host element. | no |
+| `strokeWidth` | `number \| string` | `'var(--dsx-icon-stroke-width, 1.75)'` | no | The Lucide stroke width. Forwarded as-is. | no |
+| `data-size` | `string` | (writes through prop) | no | Re-emitted by the internal renderer. Consumers do not pass this directly. | no |
+
+Rules:
+
+- `Icon` extends `Omit<React.ComponentPropsWithoutRef<'svg'>, 'color'>` because `color` is redefined. The runtime uses `LucideComponent` or `SimpleIconComponent` for the underlying SVG; both forward standard SVG attributes.
+- The `name` prop is the only visual contract. The internal `isDSXIconName` guard returns `null` for unknown names so callers do not need to handle a missing icon fallback at the call site.
+- The component always writes `data-size` and `class="dsx-icon"`. The `aria-hidden` and `role` attributes are managed by the runtime based on whether `title` is provided.
+
+## CSS class contract
+
+**Root class:** `dsx-icon`
+
+**Modifier classes** (driven by `data-*` attributes written by the component):
+
+| Attribute | Allowed values | Class | CSS file |
+|---|---|---|---|
+| `data-size` | `sm`, `md`, `lg`, `xl` | `.dsx-icon[data-size='...']` (CSS hook; the size is also encoded through the SVG `width`/`height` attributes) | n/a (no Icon-specific CSS file) |
+
+**Slot classes:** none.
+
+**Responsive behavior:**
+
+- The component does not write `@media` rules. `size` is single-value only; the prop def is not `responsive: true`. Consumers control responsive sizing by reading the `data-size` attribute or by setting CSS `width` and `height` on the `dsx-icon` class.
+
+**Reduced motion:**
+
+- N/A. Icon has no motion; the underlying SVGs are static.
+
+## Token mapping
+
+Every CSS value the component paints is a `var(--dsx-*)` token, applied through the SVG attributes the runtime emits.
+
+| Property | Token | Role |
+|---|---|---|
+| `width` and `height` (`sm`) | `16` (px literal) | Small icon edge. |
+| `width` and `height` (`md`) | `20` (px literal) | Default icon edge. |
+| `width` and `height` (`lg`) | `24` (px literal) | Large icon edge. |
+| `width` and `height` (`xl`) | `32` (px literal) | Extra-large icon edge. |
+| `stroke-width` | `var(--dsx-icon-stroke-width, 1.75)` | Default Lucide stroke. |
+| `stroke-width` (override) | `var(--dsx-icon-stroke-width-strong, 2.25)` | Used by Checkbox for the indicator. |
+| `color` (default for `DSXIcon`) | `var(--dsx-color-on-surface)` | Default semantic color. |
+| `color` (`muted`) | `var(--dsx-color-on-surface-variant)` | Muted text. |
+| `color` (`primary`) | `var(--dsx-color-primary)` | Brand tint. |
+| `color` (`secondary`) | `var(--dsx-color-secondary)` | Secondary tint. |
+| `color` (`success`) | `var(--dsx-color-success)` | Success tint. |
+| `color` (`error`) | `var(--dsx-color-error)` | Error tint. |
+| `color` (Simple Icons fallback) | `currentColor` (CSS keyword) | Inherits the surrounding text color. |
+
+Rules:
+
+- The pixel size values are CSS literals in the runtime (the size scale is encoded in the component, not in a CSS file). The colors and stroke-width come from the token layer.
+- Free-form color strings bypass the token mapping; consumers using them are responsible for the value.
+
+## Motion contract
+
+| Region | Token | Default | Reduced |
+|---|---|---|---|
+| (none) | `none` | `none` | `none` |
+
+Rules:
+
+- Icon has no motion. The motion section is intentionally empty.
+
+## Accessibility
+
+**Roles:**
+
+- `role="img"` when `title` is provided (the icon is announced as a labelled image).
+- `role="presentation"` when `title` is omitted (the icon is decorative and removed from the accessibility tree).
+
+**Keyboard:**
+
+- Icon is not interactive. No keyboard contract beyond the page-level Tab order.
+
+**Focus:**
+
+- The icon host is not focusable by default. When an icon sits inside a button (`IconButton`, `Button` with `leadingIcon` or `trailingIcon`), focus follows the button's own contract.
+
+**Reduced motion:**
+
+- N/A. Icon has no motion.
+
+**Color and meaning:**
+
+- The icon is a visual affordance only. When the icon carries meaning that the surrounding text does not repeat, supply `title` so the icon is announced. When the icon is purely decorative, omit `title` so the icon does not pollute the accessibility tree.
+
+**Naming:**
+
+- The accessible name comes from the `title` prop. Consumers should supply a short, descriptive phrase such as "Connected" or "Open settings". For decorative usage, omit `title` and pair the icon with a visible label or a wrapping accessible element.
+
+## Playground demo spec
+
+**Default story:**
+
+- Renders `Icon` with `name="check"` and `title="Check"`. Asserts the host element is an `<svg>`, the root class is `dsx-icon`, and the `<title>` is rendered.
+
+**Size story** (one per size value):
+
+- Renders Icon with `size="sm"`, `size="md"`, `size="lg"`, and `size="xl"`. Asserts the matching `data-size` attribute and the corresponding pixel `width`/`height`.
+
+**State story:**
+
+- Renders Icon with `title="Connected"` and asserts `role="img"` and `aria-hidden="false"`.
+- Renders Icon with no `title` and asserts `role="presentation"` and `aria-hidden="true"`.
+
+**Token story:**
+
+- Renders the icon catalog inside a `Theme` wrapper to confirm the default `color` token resolves to `var(--dsx-color-on-surface)`. Asserts the SVG `color` attribute reflects the resolved token.
+
+**A11y story:**
+
+- Uses `vitest-axe` against the rendered default icon. Asserts there are no axe violations.
+
+**Props exposed in the playground controls:**
+
+| Prop | Control | Default |
+|---|---|---|
+| `name` | text | `check` |
+| `size` | select | `md` |
+| `title` | text | (empty) |
+| `color` | text | (empty) |
+
+## Wiring notes
+
+**Composes from:**
+
+- `lucide-react`: provides the line and UI icon components. Each `DSXIconName` resolves to one Lucide component through the `LUCIDE_ICON_COMPONENTS` map.
+- `@icons-pack/react-simple-icons`: provides the brand and service icon components. Each brand `DSXIconName` resolves to one Simple Icons component through the `SIMPLE_ICON_COMPONENTS` map.
+- `cn` (`src/_internal/cn.ts`): local class joiner for the root class.
+
+**Used by:**
+
+- `AccessibleIcon`, `Button` (leading/trailing icons), `IconButton`, `Checkbox` (check and minus indicators), `CopyButton` (copy and check icons), `EmptyState` (illustration slot), `Item`, `Card`, and most overlay and navigation surfaces. The roster lists the full dependency graph; this row is the source.
+
+**State boundaries:**
+
+- Owned by Icon: the `<svg>` host, the `dsx-icon` root class, the `data-size` attribute, the `role` and `aria-hidden` attributes, the `<title>` child (when `title` is set), and the size-to-pixel mapping.
+- Owned by the consumer: the icon name, the optional title, the optional color override, and the surrounding layout.
+
+**Boundary rules:**
+
+- App-owned data: the icon name (which must be in the catalog), the optional accessible name, the surrounding label or button, and the responsive sizing strategy.
+- DS-owned visuals: the `dsx-icon` root class, the `data-size` attribute, the size-to-pixel mapping, the default color tokens, and the stroke-width token.

package/dist/docs/index.md

@@ -0,0 +1,149 @@
+# D4gger Design System API
+
+Offline, package-shipped copies of the canonical component specifications and consumer guides.
+The repository documents remain the source of truth.
+
+## Guides
+
+- [Consumer guide](./consumer-guide.md)
+- [Sidebar guide](./sidebar-guide.md)
+- [Theme guide](./theme-guide.md)
+
+## Component specifications
+
+- [HIERARCHY](./HIERARCHY.md)
+- [accessible-icon](./accessible-icon.md)
+- [accordion](./accordion.md)
+- [alert-dialog](./alert-dialog.md)
+- [alert](./alert.md)
+- [article-nodes](./article-nodes.md)
+- [aspect-ratio](./aspect-ratio.md)
+- [avatar](./avatar.md)
+- [badge](./badge.md)
+- [blockquote](./blockquote.md)
+- [box](./box.md)
+- [breadcrumb](./breadcrumb.md)
+- [button-group](./button-group.md)
+- [button](./button.md)
+- [calendar](./calendar.md)
+- [callout](./callout.md)
+- [card](./card.md)
+- [carousel](./carousel.md)
+- [chart](./chart.md)
+- [checkbox-cards](./checkbox-cards.md)
+- [checkbox-group](./checkbox-group.md)
+- [checkbox](./checkbox.md)
+- [code-input](./code-input.md)
+- [code](./code.md)
+- [collapsible](./collapsible.md)
+- [color-picker](./color-picker.md)
+- [color-swatch](./color-swatch.md)
+- [combobox](./combobox.md)
+- [command](./command.md)
+- [comment-thread](./comment-thread.md)
+- [component-roster](./component-roster.md)
+- [component-spec-template](./component-spec-template.md)
+- [config-drawer](./config-drawer.md)
+- [container](./container.md)
+- [context-menu](./context-menu.md)
+- [copy-button](./copy-button.md)
+- [copy-field](./copy-field.md)
+- [data-list](./data-list.md)
+- [data-table](./data-table.md)
+- [date-picker](./date-picker.md)
+- [dialog](./dialog.md)
+- [direction-provider](./direction-provider.md)
+- [drawer](./drawer.md)
+- [dropdown-menu](./dropdown-menu.md)
+- [editable](./editable.md)
+- [em](./em.md)
+- [empty-state](./empty-state.md)
+- [field](./field.md)
+- [file-upload](./file-upload.md)
+- [filter-bar](./filter-bar.md)
+- [flex](./flex.md)
+- [floating-panel](./floating-panel.md)
+- [font-provider](./font-provider.md)
+- [form](./form.md)
+- [grid](./grid.md)
+- [heading](./heading.md)
+- [hover-card](./hover-card.md)
+- [icon-button](./icon-button.md)
+- [icon](./icon.md)
+- [input-group](./input-group.md)
+- [input-otp](./input-otp.md)
+- [input](./input.md)
+- [inset](./inset.md)
+- [item](./item.md)
+- [kbd](./kbd.md)
+- [label](./label.md)
+- [layout-props](./layout-props.md)
+- [link](./link.md)
+- [marquee](./marquee.md)
+- [menu](./menu.md)
+- [menubar](./menubar.md)
+- [metric](./metric.md)
+- [native-select](./native-select.md)
+- [navigation-menu](./navigation-menu.md)
+- [notification-center](./notification-center.md)
+- [number-input](./number-input.md)
+- [page-content](./page-content.md)
+- [page-header](./page-header.md)
+- [pagination](./pagination.md)
+- [password-input](./password-input.md)
+- [pills](./pills.md)
+- [popover](./popover.md)
+- [progress](./progress.md)
+- [prose](./prose.md)
+- [qr-code](./qr-code.md)
+- [quote](./quote.md)
+- [radio-cards](./radio-cards.md)
+- [radio-group](./radio-group.md)
+- [rating](./rating.md)
+- [resizable](./resizable.md)
+- [result](./result.md)
+- [rich-text-editor](./rich-text-editor.md)
+- [scroll-area](./scroll-area.md)
+- [search-bar](./search-bar.md)
+- [section](./section.md)
+- [segmented-control](./segmented-control.md)
+- [segmented-meter](./segmented-meter.md)
+- [select](./select.md)
+- [separator](./separator.md)
+- [shared](./shared.md)
+- [sheet](./sheet.md)
+- [sidebar](./sidebar.md)
+- [skeleton](./skeleton.md)
+- [slider](./slider.md)
+- [slot](./slot.md)
+- [sonner](./sonner.md)
+- [sortable-list](./sortable-list.md)
+- [spinner](./spinner.md)
+- [stack](./stack.md)
+- [stat-card](./stat-card.md)
+- [status](./status.md)
+- [stepper](./stepper.md)
+- [strong](./strong.md)
+- [switch](./switch.md)
+- [tab-nav](./tab-nav.md)
+- [table-of-contents](./table-of-contents.md)
+- [table](./table.md)
+- [tabs](./tabs.md)
+- [tags-input](./tags-input.md)
+- [text-area](./text-area.md)
+- [text-field](./text-field.md)
+- [text](./text.md)
+- [theme-panel](./theme-panel.md)
+- [theme-provider](./theme-provider.md)
+- [theme](./theme.md)
+- [time-picker](./time-picker.md)
+- [timeline](./timeline.md)
+- [toast](./toast.md)
+- [toggle-group](./toggle-group.md)
+- [toggle-tip](./toggle-tip.md)
+- [toggle](./toggle.md)
+- [toolbar](./toolbar.md)
+- [tooltip](./tooltip.md)
+- [tree-view](./tree-view.md)
+- [typography](./typography.md)
+- [visually-hidden](./visually-hidden.md)