@d4gger/design-system 2.7.0

package/dist/docs/alert.md

@@ -0,0 +1,236 @@
+---
+title: Alert
+status: canonical
+category: Components
+archetype: composite
+package_path: packages/d4gger-design-system/src/components/alert/Alert.tsx
+css_path: packages/d4gger-design-system/src/styles/components/alert.css
+props_path: packages/d4gger-design-system/src/components/alert/alert.props.ts
+test_path: packages/d4gger-design-system/src/test/components/Alert.test.tsx
+demo_path: apps/playground/app/(themeable)/docs/[component]/page.tsx
+playground_registry_path: apps/playground/lib/registry/display.tsx
+playground_manifest_path: apps/playground/lib/component-manifest.ts
+depends_on:
+  - Card
+  - Icon
+  - Button
+---
+
+# Alert
+
+> 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
+
+An inline status, warning, or info banner that lives in the page flow. Use Alert for in-flow status messages that need to persist until the user dismisses them or acts on them. For transient, non-blocking notifications that appear above the page and auto-dismiss, use `Toast` or `Sonner` instead.
+
+## Anatomy & slots
+
+**Parent:** `Alert` (alias of `AlertRoot`). The root is a thin wrapper around `CardRoot`; it composes the card surface and adds the alert-specific layout, icon, and content slots.
+
+**Slots:**
+
+| Slot | Element | Renders | Notes |
+|---|---|---|---|
+| `Alert` (root) | `<div>` (or `Slot` host) | `CardRoot` + class | Renders the surface as a Card and overlays the alert-specific class. Writes `dsx-alert`, `data-variant`, `data-size`, `data-high-contrast`, `data-accent-color`. Defaults `role` to `"alert"`; consumers can override with a custom `role` prop. |
+| `Alert.Title` | `<h5>` (or `Slot` host) | Slot class | Title text. Writes `dsx-alert__title`. |
+| `Alert.Description` | `<p>` (or `Slot` host) | Slot class | Description text. Writes `dsx-alert__description`. |
+| `Alert.Action` | `<div>` | Slot class | Trailing action container (typically a Button or IconButton). Writes `dsx-alert__action`. |
+
+**Internal layout:**
+
+The root renders a flex row with three regions, in this order:
+
+1. An icon container (`<span aria-hidden="true" class="dsx-alert__icon">`) that holds the resolved icon. The icon is hidden when `icon === null` and replaced wholesale when `icon` is a `ReactNode`.
+2. A content container (`<div class="dsx-alert__content">`) that wraps whatever the consumer passes as children (typically `Alert.Title` and `Alert.Description`).
+3. The optional `Alert.Action` slot, if the consumer composes it as a child.
+
+The `Alert.Action` slot is independent of the rest of the layout; the consumer can place it inside the content area or as a sibling of `Alert.Title` / `Alert.Description` to control alignment.
+
+## Props contract
+
+**Root props:**
+
+| Prop | Type | Default | Required | Description | Responsive |
+|---|---|---|---|---|---|
+| `variant` | `'default' \| 'destructive' \| 'success' \| 'warning'` | `'default'` | no | Visual tone; writes `data-variant`. The base CSS sets a color per variant; `default` and `warning` use the primary palette, `destructive` uses the error palette, and `success` uses the success palette. | no |
+| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | no | Padding scale; writes `data-size`. | no |
+| `color` | `string` | `undefined` | no | Free-form accent override; writes `data-accent-color` when provided. | no |
+| `highContrast` | `boolean` | `false` | no | When `true`, swaps the surface and border to `var(--dsx-color-high-contrast-container)` and `var(--dsx-color-high-contrast-border)`; writes `data-high-contrast="true"`. | no |
+| `icon` | `ReactNode` | variant icon (see below) | no | The leading icon. When `null`, the icon container is omitted. When a `ReactNode`, replaces the variant-default icon. | no |
+| `role` | `string` | `'alert'` | no | ARIA role on the root element. Override with `'status'` for advisory messages. | no |
+| `asChild` | `boolean` | `false` | no | Renders the root through `Slot`; consumer supplies the host element. | no |
+| `className` | `string` | `undefined` | no | Extra classes appended to `dsx-alert`. | no |
+
+**Slot props (Title, Description, Action):**
+
+| Prop | Type | Default | Required | Description | Responsive |
+|---|---|---|---|---|---|
+| `asChild` | `boolean` | `false` | no | Renders the slot through `Slot`; consumer supplies the host element. | no |
+| `className` | `string` | `undefined` | no | Extra classes appended to the slot class. | no |
+
+`Alert.Title` and `Alert.Description` also accept the standard HTML attributes for their host elements (`<h5>` and `<p>` respectively). `Alert.Action` accepts standard `<div>` attributes.
+
+**Variant default icons (when `icon` is `undefined`):**
+
+| `variant` | Icon `name` |
+|---|---|
+| `default` | `info` |
+| `destructive` | `alert-triangle` |
+| `success` | `check-circle` |
+| `warning` | `alert-triangle` |
+
+The icon is rendered with `size="md"` and `strokeWidth="var(--dsx-icon-stroke-width-strong, 2.25)"`.
+
+## CSS class contract
+
+**Root class:** `dsx-alert` (composed on top of the Card root class)
+
+**Modifier classes** (driven by `data-*` attributes written by the component):
+
+| Attribute | Allowed values | Class | CSS file |
+|---|---|---|---|
+| `data-variant` | `default`, `destructive`, `success`, `warning` | `.dsx-alert[data-variant='destructive']`, `.dsx-alert[data-variant='error']`, `.dsx-alert[data-variant='success']`, `.dsx-alert[data-variant='warning']` | `baseCard.css` |
+| `data-size` | `sm`, `md`, `lg` | (inherits Card size) | `baseCard.css` |
+| `data-accent-color` | any string | (no rule in `alert.css`; attribute is forwarded) | n/a |
+| `data-high-contrast` | `true` | `.dsx-alert[data-high-contrast='true']` | `baseCard.css` |
+
+**Slot classes:**
+
+| Slot | Class | CSS file |
+|---|---|---|
+| `Alert` (root) | `dsx-alert` | `alert.css` |
+| Root icon container | `dsx-alert__icon` | `alert.css` |
+| Root content container | `dsx-alert__content` | `alert.css` |
+| `Alert.Action` | `dsx-alert__action` | `alert.css` |
+| `Alert.Title` | `dsx-alert__title` | `alert.css` |
+| `Alert.Description` | `dsx-alert__description` | `alert.css` |
+
+**Responsive behavior:**
+
+- The component does not write `@media` rules. `size`, `variant`, `color`, and `highContrast` are single-value only.
+
+**Reduced motion:**
+
+- The component is static. No motion is applied. There is no transition or animation in `alert.css`.
+
+## Token mapping
+
+Every CSS value the component paints is a `var(--dsx-*)` token.
+
+| Property | Token | Role |
+|---|---|---|
+| Root display | `flex` (row) | Layout for icon + content + action |
+| Root gap | `var(--dsx-space-md)` | Space between icon, content, and action |
+| Root padding | `var(--dsx-space-md) var(--dsx-space-lg)` | Internal gutter |
+| Root border | `var(--dsx-border-width-sm) solid` | Edge |
+| Root border-radius | `var(--dsx-rounded-lg)` | Roundness |
+| Root text color | `var(--dsx-color-on-surface)` | Default text color |
+| Icon / action minimum size | `var(--dsx-size-md)` | Icon and action slot dimensions |
+| Icon / action color | `currentColor` | Inherits the alert surface color |
+| Title type ramp | `var(--dsx-typography-label-large-*)` | Title text scale |
+| Description type ramp | `var(--dsx-typography-body-medium-*)` | Description text scale |
+| Description opacity | `var(--dsx-opacity-subtle, 0.85)` | Subtle fade for description text |
+| Destructive surface | `var(--dsx-color-error-container)`, `var(--dsx-color-on-error-container)`, `var(--dsx-color-error)` (border) | Destructive palette |
+| Success surface | `var(--dsx-color-success-container)`, `var(--dsx-color-on-success-container)`, `var(--dsx-color-success)` (border) | Success palette |
+| Warning surface | `var(--dsx-color-primary-container)`, `var(--dsx-color-on-primary-container)`, `var(--dsx-color-primary)` (border) | Warning palette (primary palette) |
+| High-contrast surface | `var(--dsx-color-high-contrast-container)`, `var(--dsx-color-high-contrast-border)`, `var(--dsx-color-high-contrast)` (text) | High-contrast palette |
+
+## Motion contract
+
+| Region | Token | Default | Reduced |
+|---|---|---|---|
+| (none) | none | none | n/a |
+
+The component has no motion. It is a static inline surface.
+
+## Accessibility
+
+**Roles:**
+
+- The root renders with `role="alert"` by default, which makes the entire banner content announce as an assertive live region. Consumers who want a non-assertive advisory message should pass `role="status"`.
+
+**Keyboard:**
+
+| Key | Action |
+|---|---|
+| `Tab` | Moves focus to the action control inside `Alert.Action` (if the consumer placed one). The root itself is not focusable. |
+
+**Focus:**
+
+- Focus handling is owned by the action control. The root does not render its own focus ring.
+
+**Reduced motion:**
+
+- No motion is applied; no `prefers-reduced-motion` override is needed.
+
+**Color and meaning:**
+
+- Variant tone is communicated by both color and icon: `success` uses the success palette and a `check-circle` icon, `destructive` uses the error palette and an `alert-triangle` icon, `warning` uses the primary palette and an `alert-triangle` icon, and `default` uses the base palette and an `info` icon.
+
+**Naming:**
+
+- `Alert.Title` should be a short, descriptive heading. `Alert.Description` provides supplementary detail. The action control inside `Alert.Action` must carry its own accessible name (the consumer-supplied Button or IconButton handles this).
+
+## Playground demo spec
+
+**Default story:**
+
+- Renders an `Alert` with a title and description. Asserts the root class is `dsx-alert`, the role is `"alert"`, and the default `info` icon is present.
+
+**Variant story:**
+
+- Renders four alerts with `variant="default"`, `variant="destructive"`, `variant="success"`, and `variant="warning"`. Asserts the matching `data-variant` attribute on each.
+
+**Size story:**
+
+- Renders three alerts with `size="sm"`, `size="md"`, and `size="lg"`. Asserts the matching `data-size` attribute.
+
+**State story:**
+
+- Renders an alert with `highContrast` set. Asserts `data-high-contrast="true"`.
+- Renders an alert with `icon={null}`. Asserts the `dsx-alert__icon` element is not in the DOM.
+- Renders an alert with `icon={<Custom />}` and asserts the custom node is rendered.
+
+**Composition story:**
+
+- Renders an alert with `Alert.Title`, `Alert.Description`, and `Alert.Action` populated. Asserts the `dsx-alert__title`, `dsx-alert__description`, and `dsx-alert__action` classes are present.
+
+**Token story:**
+
+- Renders inside a `Theme` wrapper with `accentColor="silver"` and `accentColor="bronze"`. Asserts the destructive and success surfaces are unchanged because they read from the error and success palettes, not the accent palette.
+
+**A11y story:**
+
+- Uses `vitest-axe` against the rendered default story. Asserts no axe violations.
+
+**Props exposed in the playground controls:**
+
+| Prop | Control | Default |
+|---|---|---|
+| `variant` | select | `default` |
+| `size` | select | `md` |
+| `highContrast` | boolean | `false` |
+| `color` | text | (empty) |
+
+## Wiring notes
+
+**Composes from:**
+
+- `Card` (`CardRoot`): the alert root is a `CardRoot asChild` wrapper. The alert inherits the card surface treatment and the Card size, variant, and high-contrast data attributes.
+- `Icon`: renders the variant default icon and any consumer-supplied icon node.
+- `@radix-ui/react-slot`: enables `asChild` on the root and on `Alert.Title` / `Alert.Description`.
+
+**Used by:**
+
+- App-level in-page status banners, inline warnings, and confirmation strips. The roster currently lists no DS components that consume `Alert`; it is a leaf surface.
+
+**State boundaries:**
+
+- Owned by Alert: the variant / size / color / high-contrast data attributes, the icon fallback, the `role` default, and the `dsx-alert__*` slot classes.
+- Owned by the consumer: the alert content, the action handler, the `role` override, the icon override, and the surrounding layout.
+
+**Boundary rules:**
+
+- App-owned data: the alert message text, the action, the dismiss/timeout behavior, and the analytics events.
+- DS-owned visuals: token bindings, slot classes, icon name resolution, and the surface palette per variant.

package/dist/docs/article-nodes.md

@@ -0,0 +1,29 @@
+---
+title: ArticleNodes
+status: canonical
+category: Components
+archetype: adapter-backed
+package_path: packages/d4gger-design-system/src/components/articleNodes/ArticleNodes.tsx
+css_path: packages/d4gger-design-system/src/styles/components/article-nodes.css
+depends_on: ["@tiptap/core", "@tiptap/extension-image", "@tiptap/extension-table", "@tiptap/extension-code-block-lowlight", "lowlight"]
+---
+
+# ArticleNodes
+
+## Purpose
+
+Authoring extensions and read-side renderers for the RichTextEditor article preset. Exports cover image with caption, canonical-URL embed, authored Callout, syntax-highlighted code, responsive table, before/after comparison, and persistent-ID poll.
+
+## Stable HTML contract
+
+Nodes serialize through `data-dsx-node` and node-specific `data-dsx-*` attributes. Embed values are canonical HTTP(S) URLs and raw iframe HTML is not accepted. Images preserve `src`, `alt`, and optional caption. Comparison preserves both sources, both alt values, and optional labels. Poll preserves its ID and display metadata.
+
+## Application boundary
+
+The package exports `ArticleImage`, `ArticleEmbed`, `BeforeAfterComparison`, and `ArticlePoll`. Consumers own sanitization, image upload/error policy, embed allowlists and render callbacks, poll loading/voting callbacks, authentication, persistence, and networking.
+
+Read-side renderers are available from the root and `components` barrels and from the dedicated `@d4gger/design-system/article-nodes` subpath. Tiptap-backed authoring extensions are isolated at `@d4gger/design-system/article-extensions`, so importing the root package never requires the optional Tiptap peers.
+
+## Playground demo spec
+
+Show each renderer, missing media, invalid embed, comparison at mobile width, and poll loading, error, ready, and voted states.

package/dist/docs/aspect-ratio.md

@@ -0,0 +1,161 @@
+---
+title: AspectRatio
+status: canonical
+category: Primitives
+archetype: radix-wrapper
+package_path: packages/d4gger-design-system/src/components/aspectRatio/AspectRatio.tsx
+css_path: packages/d4gger-design-system/src/styles/components/aspect-ratio.css
+props_path: packages/d4gger-design-system/src/components/aspectRatio/aspectRatio.props.ts
+test_path: packages/d4gger-design-system/src/test/components/AspectRatio.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: []
+---
+
+# AspectRatio
+
+> 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 container that enforces a width-to-height ratio on its child content, used for media surfaces (image, video, iframe) where the consumer does not know the child's intrinsic size in advance.
+
+## Anatomy & slots
+
+**Parent:** `AspectRatio` (no compound; flat export). `AspectRatioRoot` is exported as an alias of `AspectRatio` for symmetry with the rest of the package.
+
+**Slots:**
+
+No slots: flat export. The component renders a single Radix `AspectRatioPrimitive.Root` host element (`<div>`) that wraps its child. The child is whatever the consumer passes; AspectRatio does not own any internal layout or wrapper regions.
+
+## Props contract
+
+| Prop | Type | Default | Required | Description | Responsive |
+|---|---|---|---|---|---|
+| `asChild` | `boolean` | `false` | no | Renders the host element through `Slot`; consumer supplies the element. | no |
+| `ratio` | `number` | `1` (Radix default) | no | Width divided by height. Passed directly to `@radix-ui/react-aspect-ratio`. | no |
+| `className` | `string` | `undefined` | no | Extra classes appended to `dsx-aspect-ratio`. | no |
+| `style` | `React.CSSProperties` | `undefined` | no | Extra inline style forwarded to the host element. | no |
+| `children` | `React.ReactNode` | `undefined` | no | The element being constrained to the ratio (typically an `<img>`, `<video>`, or `<iframe>`). | no |
+
+Rules:
+
+- The prop def bag only declares `asChild`. `ratio` and any other Radix `AspectRatio.Root` props are forwarded through `React.ComponentProps<typeof PrimitiveAspectRatio>`.
+- `AspectRatio` does not define or write any `data-*` attribute. The ratio is encoded by the Radix primitive through a CSS custom property and the package's `dsx-aspect-ratio` root class.
+
+## CSS class contract
+
+**Root class:** `dsx-aspect-ratio`
+
+**Modifier classes:** none. The component has no `data-*` attribute contract.
+
+**Slot classes:** none.
+
+**Responsive behavior:**
+
+- The component does not write `@media` rules. No prop defs are `responsive: true`. Consumers control responsive behavior by overriding the `ratio` at the parent layout level or by sizing the host element with a responsive width.
+
+**Reduced motion:**
+
+- N/A. AspectRatio has no motion.
+
+## Token mapping
+
+Every CSS value the component paints is a `var(--dsx-*)` token.
+
+| Property | Token | Role |
+|---|---|---|
+| `overflow` | `hidden` (CSS keyword) | Clip the child to the enforced ratio box. |
+| `border-radius` | `var(--dsx-rounded-md)` | Default rounded corner; matches the package's standard surface rounding. |
+
+Rules:
+
+- No raw color, spacing, radius, or motion values in `aspect-ratio.css`.
+- The ratio value itself is supplied by the Radix primitive through its own `AspectRatio` CSS variable; the package does not author the math.
+
+## Motion contract
+
+| Region | Token | Default | Reduced |
+|---|---|---|---|
+| (none) | `none` | `none` | `none` |
+
+Rules:
+
+- AspectRatio has no motion. The motion section is intentionally empty.
+
+## Accessibility
+
+**Roles:**
+
+- `<div>` by default. When `asChild` is set, the consumer owns the role. The component is a generic container; no implicit role applies.
+
+**Keyboard:**
+
+- AspectRatio is not interactive. No keyboard contract beyond the page-level Tab order.
+
+**Focus:**
+
+- AspectRatio has no interactive surface. Focus management is the consumer's responsibility when the constrained content is focusable (e.g. an iframe or video controls).
+
+**Reduced motion:**
+
+- N/A. AspectRatio has no motion.
+
+**Color and meaning:**
+
+- N/A. The component does not communicate state.
+
+**Naming:**
+
+- No accessible name is required by default. Consumers that constrain focusable media (video, iframe) should supply an `aria-label` on the inner element or a labelled wrapper.
+
+## Playground demo spec
+
+**Default story:**
+
+- Renders `AspectRatio` with `ratio={16 / 9}` and a fixed width, so the height is computed automatically. Asserts the root class is `dsx-aspect-ratio`.
+
+**Composition story** (for `asChild`):
+
+- Renders AspectRatio with `asChild` wrapping a `<div>` element. Asserts the host element is `DIV` and the `dsx-aspect-ratio` class is preserved.
+
+**State story:**
+
+- Renders AspectRatio with `ratio={1}`, `ratio={4 / 3}`, and `ratio={16 / 9}`. Asserts the rendered height matches the width divided by the supplied ratio.
+
+**Token story:**
+
+- N/A. AspectRatio does not consume `data-accent-color`; the story documents that the rounded corner is token-driven and visually unchanged across accents.
+
+**A11y story:**
+
+- Uses `vitest-axe` against the rendered default aspect ratio. Asserts there are no axe violations.
+
+**Props exposed in the playground controls:**
+
+| Prop | Control | Default |
+|---|---|---|
+| `asChild` | boolean | `false` |
+| `ratio` | number | `1` |
+
+## Wiring notes
+
+**Composes from:**
+
+- `@radix-ui/react-aspect-ratio`: provides the ratio enforcement primitive. The `ratio` prop is a Radix requirement.
+- `@radix-ui/react-slot`: enables `asChild` for consumer-supplied host elements.
+
+**Used by:**
+
+- App-level media surfaces (image thumbnails, video embeds, map tiles, hero panels). The roster currently lists no DS components that consume `AspectRatio`; it is a leaf primitive intended for direct app usage.
+
+**State boundaries:**
+
+- Owned by AspectRatio: the `dsx-aspect-ratio` root class and the enforced ratio.
+- Owned by the consumer: the child content, the `ratio` value, the host element when `asChild` is set, and the responsive width strategy.
+
+**Boundary rules:**
+
+- App-owned data: the aspect ratio itself, the child content, and any surrounding figure or caption.
+- DS-owned visuals: the `dsx-aspect-ratio` root class, the `var(--dsx-rounded-md)` corner, and the `overflow: hidden` clip.

package/dist/docs/avatar.md

@@ -0,0 +1,250 @@
+---
+title: Avatar
+status: canonical
+category: Primitives
+archetype: composite
+package_path: packages/d4gger-design-system/src/components/avatar/Avatar.tsx
+css_path: packages/d4gger-design-system/src/styles/components/avatar.css
+props_path: packages/d4gger-design-system/src/components/avatar/avatar.props.ts
+test_path: packages/d4gger-design-system/src/test/components/Avatar.test.tsx
+demo_path: apps/playground/app/(themeable)/docs/[component]/page.tsx
+playground_registry_path: apps/playground/lib/registry/display.tsx
+playground_manifest_path: apps/playground/lib/component-manifest.ts
+depends_on: []
+---
+
+# Avatar
+
+> 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 user or entity identity surface that pairs an image with a fallback (initials or icon), plus a group container for stacking multiple avatars with an overflow count chip.
+
+## Anatomy & slots
+
+**Parent:** `Avatar` (no compound slot; `Avatar` itself is the visible root). The composite exports `Avatar`, `AvatarImage`, `AvatarFallback`, `AvatarGroup`, and `AvatarGroupCount` from a single entry.
+
+**Slots:**
+
+| Slot | Element | Renders | Notes |
+|---|---|---|---|
+| `Avatar` | `<span>` (Radix Root) | DS composite + class | Hosts image and fallback. Writes `dsx-avatar`, `data-variant`, `data-size`, `data-radius`, `data-accent-color`, `data-high-contrast`. |
+| `AvatarImage` | `<img>` (Radix Image) | DS primitive + class | Optional image source. Writes `dsx-avatar__image`. |
+| `AvatarFallback` | `<span>` (Radix Fallback) | DS primitive + class | Fallback content (initials or icon). Writes `dsx-avatar__fallback`. |
+| `AvatarGroup` | `<div>` | DS primitive + class | Stacks children with a negative left margin. Writes `dsx-avatar-group`. |
+| `AvatarGroupCount` | `<span>` | DS primitive + class | Overflow count chip (e.g. `+3`). Writes `dsx-avatar-group-count`. |
+
+## Props contract
+
+**Root props (`Avatar`):**
+
+| Prop | Type | Default | Required | Description | Responsive |
+|---|---|---|---|---|---|
+| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | no | Diameter; writes `dsx-avatar--{sm\|md\|lg}` and `data-size`. | no |
+| `variant` | `'solid' \| 'soft'` | `'solid'` | no | Surface treatment; writes `dsx-avatar--{variant}` and `data-variant`. | no |
+| `radius` | `'none' \| 'sm' \| 'md' \| 'lg' \| 'xl' \| 'full'` | `'full'` | no | Corner roundness; writes `data-radius`. | no |
+| `color` | `'amber' \| 'silver' \| 'bronze' \| string` | `undefined` | no | Accent color; writes `data-accent-color`. Free-form strings are allowed. | no |
+| `highContrast` | `boolean` | `false` | no | When `true`, swaps to the high-contrast palette; writes `data-high-contrast="true"`. | no |
+| `asChild` | `boolean` | `false` | no | Renders the host through `Slot`; consumer supplies the element. | no |
+| `className` | `string` | `undefined` | no | Extra classes appended to `dsx-avatar`. | no |
+| `style` | `React.CSSProperties` | `undefined` | no | Extra inline style forwarded to the host element. | no |
+| `children` | `React.ReactNode` | `undefined` | no | Slot content (`AvatarImage`, `AvatarFallback`, or custom children). | no |
+
+**Image props (`AvatarImage`):**
+
+| Prop | Type | Default | Required | Description | Responsive |
+|---|---|---|---|---|---|
+| `asChild` | `boolean` | `false` | no | Renders through `Slot`; consumer supplies the element. | no |
+| `className` | `string` | `undefined` | no | Extra classes appended to `dsx-avatar__image`. | no |
+| `style` | `React.CSSProperties` | `undefined` | no | Extra inline style forwarded to the image. | no |
+
+**Fallback props (`AvatarFallback`):**
+
+| Prop | Type | Default | Required | Description | Responsive |
+|---|---|---|---|---|---|
+| `asChild` | `boolean` | `false` | no | Renders through `Slot`; consumer supplies the element. | no |
+| `className` | `string` | `undefined` | no | Extra classes appended to `dsx-avatar__fallback`. | no |
+| `style` | `React.CSSProperties` | `undefined` | no | Extra inline style forwarded to the fallback. | no |
+| `children` | `React.ReactNode` | `undefined` | no | Initials or icon body. | no |
+
+**Group props (`AvatarGroup`):**
+
+| Prop | Type | Default | Required | Description | Responsive |
+|---|---|---|---|---|---|
+| `asChild` | `boolean` | `false` | no | Renders the group through `Slot`; consumer supplies the element. | no |
+| `className` | `string` | `undefined` | no | Extra classes appended to `dsx-avatar-group`. | no |
+| `style` | `React.CSSProperties` | `undefined` | no | Extra inline style forwarded to the group. | no |
+| `children` | `React.ReactNode` | `undefined` | no | Stacked `Avatar` and optional `AvatarGroupCount` children. | no |
+
+**Group count props (`AvatarGroupCount`):**
+
+| Prop | Type | Default | Required | Description | Responsive |
+|---|---|---|---|---|---|
+| `asChild` | `boolean` | `false` | no | Renders the count chip through `Slot`; consumer supplies the element. | no |
+| `className` | `string` | `undefined` | no | Extra classes appended to `dsx-avatar-group-count`. | no |
+| `style` | `React.CSSProperties` | `undefined` | no | Extra inline style forwarded to the chip. | no |
+| `children` | `React.ReactNode` | `undefined` | no | Overflow label (e.g. `+3`). | no |
+
+Rules:
+
+- `size`, `variant`, `radius`, `color`, `highContrast`, and `asChild` on `Avatar` are wired through `extractProps` and the prop def bag. The image, fallback, group, and group count subcomponents expose only `asChild` in their prop def bag; remaining Radix props forward.
+- `radius`, `color`, and the size modifier are written by both the DS wrapper (`Avatar.tsx`) and the Radix wrapper (`Avatar.radix.tsx`). The two layers are intentionally kept in sync to keep the public surface stable; tests verify the DS wrapper's output.
+
+## CSS class contract
+
+**Root class:** `dsx-avatar`
+
+**Modifier classes** (driven by `data-*` attributes and prop def modifiers):
+
+| Attribute | Allowed values | Class | CSS file |
+|---|---|---|---|
+| `data-size` | `sm`, `md`, `lg` | `dsx-avatar--sm`, `dsx-avatar--md`, `dsx-avatar--lg` | `avatar.css` |
+| `data-variant` | `solid`, `soft` | `dsx-avatar--solid`, `dsx-avatar--soft` | (modifier class scaffolding; the visible variant surfaces via the root token bindings) |
+| `data-radius` | `none`, `sm`, `md`, `lg`, `xl`, `full` | `.dsx-avatar[data-radius='full']` etc. (CSS uses the attribute via the root radius token) | `avatar.css` |
+| `data-accent-color` | `amber`, `silver`, `bronze` (or any custom string) | `.dsx-avatar[data-accent-color='...']` (CSS hook) | `avatar.css` |
+| `data-high-contrast` | `true` | `.dsx-avatar[data-high-contrast='true']` (CSS hook) | `avatar.css` |
+
+**Slot classes:**
+
+| Slot | Class | CSS file |
+|---|---|---|
+| `Avatar` | `dsx-avatar` | `avatar.css` |
+| `AvatarImage` | `dsx-avatar__image` | `avatar.css` |
+| `AvatarFallback` | `dsx-avatar__fallback` | `avatar.css` |
+| `AvatarGroup` | `dsx-avatar-group` | `avatar.css` |
+| `AvatarGroupCount` | `dsx-avatar-group-count` | `avatar.css` |
+
+**Responsive behavior:**
+
+- The component does not write `@media` rules. `size` is single-value only; the prop def is not `responsive: true`.
+
+**Reduced motion:**
+
+- N/A. Avatar has no motion.
+
+## Token mapping
+
+Every CSS value the component paints is a `var(--dsx-*)` token.
+
+| Property | Token | Role |
+|---|---|---|
+| `position` | `relative` (CSS keyword) | Stack image and fallback on the same origin. |
+| `display` | `inline-flex` (CSS keyword) | Inline block with center alignment. |
+| Width and height (`sm`) | `var(--dsx-size-lg)` | Small avatar diameter. |
+| Width and height (`md`) | `var(--dsx-size-xl)` | Default avatar diameter. |
+| Width and height (`lg`) | `var(--dsx-size-2xl)` | Large avatar diameter. |
+| `border-radius` | `var(--dsx-rounded-full)` | Circular avatar. |
+| `border` | `var(--dsx-border-width-sm) solid var(--dsx-color-outline)` | Edge ring. |
+| `background` | `var(--dsx-color-surface-raised)` | Default surface. |
+| `color` | `var(--dsx-color-on-surface)` | Default text color. |
+| `overflow` | `hidden` (CSS keyword) | Clip image to the rounded box. |
+| Fallback typography | `var(--dsx-typography-label-large-*)` | Initials font family, size, weight. |
+| Group spacing | `calc(var(--dsx-space-sm) * -1)` | Negative left margin between stacked avatars. |
+| Group count surface | `var(--dsx-color-surface-raised)` | Count chip background. |
+| Group count color | `var(--dsx-color-on-surface-variant)` | Count chip text. |
+| Group count typography | `var(--dsx-typography-label-medium-*)` | Count chip font. |
+
+Rules:
+
+- No raw color, spacing, radius, or motion values in `avatar.css`.
+- The `soft` variant writes the `dsx-avatar--soft` modifier class but the package's `avatar.css` keeps the variant hook token-agnostic; the visible palette tracks the `data-accent-color` attribute.
+
+## Motion contract
+
+| Region | Token | Default | Reduced |
+|---|---|---|---|
+| (none) | `none` | `none` | `none` |
+
+Rules:
+
+- Avatar has no motion. The motion section is intentionally empty.
+
+## Accessibility
+
+**Roles:**
+
+- `Avatar` renders the Radix Root, which exposes an `<span>` host with `data-state` reflecting the active child (`"loaded"` once an image resolves, `"loading"` while the image is in flight, or `"unloaded"` when no image is present). Consumers do not set `role` directly.
+- `AvatarGroup` and `AvatarGroupCount` are non-semantic `<div>` and `<span>` wrappers; consumers may add `role="group"` and an `aria-label` on `AvatarGroup` when the cluster needs a name.
+
+**Keyboard:**
+
+- Avatar is not interactive. When an avatar is wrapped in a link or button, focus and keyboard follow the wrapper.
+
+**Focus:**
+
+- The avatar host is not focusable by default. Focus management is the consumer's responsibility.
+
+**Reduced motion:**
+
+- N/A. Avatar has no motion.
+
+**Color and meaning:**
+
+- Identity is communicated by the image or fallback content, not by color. The fallback initials or icon carry the meaning.
+
+**Naming:**
+
+- `Avatar` does not auto-generate an accessible name. Consumers should wrap the avatar in a labelled element or set `aria-label` on the wrapping link or button so screen readers announce the represented person or entity.
+
+## Playground demo spec
+
+**Default story:**
+
+- Renders `Avatar` with an `AvatarFallback` whose children are initials (`AB`). Asserts the root class is `dsx-avatar`, `data-size="md"`, and `data-variant="solid"`.
+
+**Size story** (one per size value):
+
+- Renders Avatar with `size="sm"`, `size="md"`, and `size="lg"`. Asserts the matching `data-size` attribute and the `dsx-avatar--{sm|md|lg}` modifier class on the root.
+
+**Variant story** (one per variant value):
+
+- Renders Avatar with `variant="solid"` and `variant="soft"`. Asserts the matching `data-variant` attribute and modifier class.
+
+**State story:**
+
+- Renders Avatar with `highContrast` and asserts `data-high-contrast="true"`. Renders Avatar with `color="blue"` and asserts `data-accent-color="blue"`.
+
+**Composition story:**
+
+- Renders `AvatarGroup` containing two `Avatar` instances and an `AvatarGroupCount` chip. Asserts each slot renders the right class (`dsx-avatar`, `dsx-avatar-group`, `dsx-avatar-group-count`).
+
+**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 avatar. Asserts there are no axe violations.
+
+**Props exposed in the playground controls:**
+
+| Prop | Control | Default |
+|---|---|---|
+| `size` | select | `md` |
+| `variant` | select | `solid` |
+| `radius` | select | `full` |
+| `color` | text | (empty) |
+| `highContrast` | boolean | `false` |
+| `asChild` | boolean | `false` |
+
+## Wiring notes
+
+**Composes from:**
+
+- `@radix-ui/react-avatar`: provides `Root`, `Image`, and `Fallback` primitives with the `data-state` lifecycle.
+- `@radix-ui/react-slot`: enables `asChild` for consumer-supplied host elements on the group and group-count wrappers.
+
+**Used by:**
+
+- App-level identity surfaces (user lists, comment threads, member directories, presence pills). `Item`, `DataList`, and `Card` are reasonable composition targets when the avatar sits inside a richer row surface.
+
+**State boundaries:**
+
+- Owned by Avatar: the root class, the variant, size, radius, accent color, and high-contrast data attributes.
+- Owned by the consumer: the image source, the fallback content, the wrapping label or link, and the group composition.
+
+**Boundary rules:**
+
+- App-owned data: the user identity, the image URL, the initials string, and the overflow count.
+- DS-owned visuals: the `dsx-avatar` root class, the slot classes, and the token bindings for diameter, edge, surface, and fallback typography.