@d4gger/design-system 2.7.0

package/dist/docs/time-picker.md

@@ -0,0 +1,244 @@
+---
+title: TimePicker
+status: canonical
+category: Components
+archetype: adapter-backed
+package_path: packages/d4gger-design-system/src/components/timePicker/TimePicker.tsx
+css_path: packages/d4gger-design-system/src/styles/components/time-picker.css
+props_path: packages/d4gger-design-system/src/components/timePicker/timePicker.props.ts
+test_path: packages/d4gger-design-system/src/test/components/TimePicker.test.tsx
+demo_path: apps/playground/app/(themeable)/docs/[component]/page.tsx
+playground_registry_path: apps/playground/lib/registry/forms.tsx
+playground_manifest_path: apps/playground/lib/component-manifest.ts
+depends_on:
+  - Popover
+  - ScrollArea
+  - Theme
+  - Icon
+---
+
+# TimePicker
+
+> 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 dropdown-based time selection control with hour, minute, and optional meridiem columns. The package owns the trigger, the column layout, the option buttons, and the token bindings. The popover open/close and portal behavior come from the internal `Popover` component. The scrollable column lists use the internal `ScrollArea` component.
+
+## Anatomy & slots
+
+**Parent:** `TimePicker`.
+
+No slots: flat export. The component is a single `React.forwardRef` that composes `Popover`, `Theme`, `Icon`, and `ScrollArea` internally.
+
+**Internal regions:**
+
+| Region | Element | Class | Notes |
+|---|---|---|---|
+| Trigger | `<button>` | `dsx-time-picker__trigger` | Opens the popover. Shows a clock icon, the current value or placeholder, and a chevron icon. |
+| Value | `<span>` | `dsx-time-picker__value` | Wraps the leading icon and label. |
+| Leading icon | `Icon` | `dsx-time-picker__leading-icon` | Clock glyph. `aria-hidden="true"`. |
+| Label | `<span>` | `dsx-time-picker__label` | Formatted time value or placeholder text. |
+| Trailing icon | `Icon` | `dsx-time-picker__icon` | Chevron-down glyph. `aria-hidden="true"`. |
+| Hidden input | `<input type="hidden">` | (none) | Only rendered when `name` is provided. Holds the canonical 24h value for form submission. |
+| Content | `Popover.Content` | `dsx-time-picker__content` | The popover panel. |
+| Columns | `<div>` | `dsx-time-picker__columns` | Grid layout for hour, minute, and optional period columns. `data-mode` reflects the active mode. |
+| Column | `<div>` | `dsx-time-picker__column` | One scrollable list. `role="group"` with `aria-label`. |
+| Period column | `<div>` | `dsx-time-picker__column dsx-time-picker__column--period` | Only rendered in `12h` mode. |
+| Column label | `<span>` | `dsx-time-picker__column-label` | "Hour", "Minute", or "Period" label. |
+| Scroll area | `ScrollArea` | `dsx-time-picker__scroll` | Wraps the option buttons. Viewport class: `dsx-time-picker__viewport`. |
+| Option button | `<button>` | `dsx-time-picker__option` | One hour, minute, or period option. `aria-pressed` for selected state. |
+| Periods | `<div>` | `dsx-time-picker__periods` | Wraps AM/PM buttons in 12h mode. |
+
+## Props contract
+
+| Prop | Type | Default | Required | Description | Responsive |
+|---|---|---|---|---|---|
+| `asChild` | `boolean` | `false` | no | Extracted from prop defs but not used by the trigger. The trigger always renders as a `<button>`. | no |
+| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | no | Drives `data-size` on the trigger. The CSS file consumes `data-size` to adjust trigger min-height and padding. | no |
+| `mode` | `'12h' \| '24h'` | `'24h'` | no | Display mode. In `24h` mode, the hour column shows 00-23. In `12h` mode, the hour column shows 01-12 and a period column (AM/PM) is rendered. The canonical value emitted by `onValueChange` is always 24h format (`HH:MM`). | no |
+| `invalid` | `boolean` | `false` | no | Drives `data-invalid` on the trigger and sets `aria-invalid`. The CSS file consumes `data-invalid='true'` to change the trigger border color. | no |
+| `value` | `string` | `undefined` | no | Controlled time value in `HH:MM` 24h format. Parsed and validated on each render. | no |
+| `defaultValue` | `string` | `undefined` | no | Initial time value for uncontrolled usage. | no |
+| `onValueChange` | `(value: string) => void` | `undefined` | no | Fires when the time value changes. Always receives a canonical `HH:MM` 24h string. | no |
+| `placeholder` | `string` | `'Select time'` | no | Placeholder text shown when no value is set. | no |
+| `minuteStep` | `number` | `5` | no | Step interval for minute options. Must be an integer that divides 60 evenly. Falls back to `5` for invalid values. | no |
+| `name` | `string` | `undefined` | no | When provided, renders a hidden `<input type="hidden">` with the canonical 24h value for form submission. | no |
+| `open` | `boolean` | `undefined` | no | Controlled popover open state. | no |
+| `defaultOpen` | `boolean` | `undefined` | no | Initial open state for uncontrolled usage. | no |
+| `onOpenChange` | `(open: boolean) => void` | `undefined` | no | Fires when the popover open state changes. | no |
+| `disabled` | `boolean` | `false` | no | Disables the trigger button. | no |
+| `className` | `string` | `undefined` | no | Extra classes appended to `dsx-time-picker__trigger`. | no |
+| `type` | `string` | `'button'` | no | Button type attribute. | no |
+
+All other `React.ButtonHTMLAttributes<HTMLButtonElement>` (minus `defaultValue`, `onChange`, `value`) are forwarded to the trigger button.
+
+## CSS class contract
+
+**Root class:** `dsx-time-picker__trigger` (the trigger button is the outermost interactive element).
+
+**Modifier classes** (driven by `data-*` attributes written by the component):
+
+| Attribute | Allowed values | Class | CSS file |
+|---|---|---|---|
+| `data-size` | `sm`, `md`, `lg` | `.dsx-time-picker__trigger[data-size='sm']`, `.dsx-time-picker__trigger[data-size='lg']` | `time-picker.css` |
+| `data-mode` | `12h`, `24h` | `.dsx-time-picker__columns[data-mode='12h']` (3-column grid) | `time-picker.css` |
+| `data-invalid` | `true` | `.dsx-time-picker__trigger[data-invalid='true']` | `time-picker.css` |
+| `data-placeholder` | `true` | `.dsx-time-picker__trigger[data-placeholder='true']` | `time-picker.css` |
+| `data-selected` | `true` | `.dsx-time-picker__option[data-selected='true']` | `time-picker.css` |
+
+**Slot classes:**
+
+| Slot | Class | CSS file |
+|---|---|---|
+| Trigger | `dsx-time-picker__trigger` | `time-picker.css` |
+| Value | `dsx-time-picker__value` | `time-picker.css` |
+| Leading icon | `dsx-time-picker__leading-icon` | `time-picker.css` |
+| Label | `dsx-time-picker__label` | `time-picker.css` |
+| Trailing icon | `dsx-time-picker__icon` | `time-picker.css` |
+| Content | `dsx-time-picker__content` | `time-picker.css` |
+| Columns | `dsx-time-picker__columns` | `time-picker.css` |
+| Column | `dsx-time-picker__column` | `time-picker.css` |
+| Period column | `dsx-time-picker__column--period` | `time-picker.css` |
+| Column label | `dsx-time-picker__column-label` | `time-picker.css` |
+| Scroll area | `dsx-time-picker__scroll` | `time-picker.css` |
+| Viewport | `dsx-time-picker__viewport` | `time-picker.css` |
+| Option button | `dsx-time-picker__option` | `time-picker.css` |
+| Periods | `dsx-time-picker__periods` | `time-picker.css` |
+
+**Responsive behavior:**
+
+- The component does not write `@media` rules. None of its prop defs are `responsive: true`.
+- The component's CSS file is breakpoint-agnostic.
+
+**Reduced motion:**
+
+- The CSS file does not include a `prefers-reduced-motion` gate. The component has no CSS transitions.
+
+## Token mapping
+
+Every CSS value the component paints is a `var(--dsx-*)` token.
+
+| Property | Token | Role |
+|---|---|---|
+| Trigger min-height | `var(--dsx-density-control-height)` | Default trigger height. |
+| Trigger padding | `var(--dsx-density-control-padding-block)` / `var(--dsx-density-control-padding-inline)` | Internal gutter. |
+| Trigger radius | `var(--dsx-rounded-md)` | Corner roundness. |
+| Trigger border | `var(--dsx-border-width-sm)` + `var(--dsx-color-outline)` | Edge. |
+| Trigger background | `var(--dsx-color-surface-overlay)` | Resting surface. |
+| Trigger text | `var(--dsx-color-on-surface)` | Primary labels. |
+| Trigger typography | `var(--dsx-typography-body-medium-*)` | Value text. |
+| Trigger focus border | `var(--dsx-color-primary)` | Focus edge. |
+| Trigger focus ring | `var(--dsx-shadow-focus-ring)` | Focus indicator. |
+| Trigger invalid border | `var(--dsx-color-error)` | Invalid edge. |
+| Trigger disabled | `var(--dsx-opacity-disabled)` | Disabled opacity. |
+| Trigger placeholder | `var(--dsx-color-on-surface-variant)` | Placeholder text. |
+| Content padding | `var(--dsx-space-md)` | Popover internal gutter. |
+| Content min-width | `var(--dsx-size-2xl) * 5` | Minimum popover width. |
+| Column gap | `var(--dsx-space-md)` | Gap between columns. |
+| Column label typography | `var(--dsx-typography-label-medium-*)` | Column header. |
+| Scroll height | `var(--dsx-size-2xl) * 4` | Scrollable area height. |
+| Option min-height | `var(--dsx-size-lg)` | Option tap target. |
+| Option padding | `var(--dsx-space-sm)` / `var(--dsx-space-md)` | Option internal gutter. |
+| Option radius | `var(--dsx-rounded-sm)` | Option corner roundness. |
+| Option typography | `var(--dsx-typography-label-medium-*)` | Option text. |
+| Option hover | `var(--dsx-color-surface)` + `var(--dsx-color-outline-variant)` | Hover background and border. |
+| Option selected | `var(--dsx-color-primary)` + `var(--dsx-color-on-primary)` | Selected background and text. |
+
+## Motion contract
+
+| Region | Token | Default | Reduced |
+|---|---|---|---|
+| (none) | `none` | `none` | `none` |
+
+The component has no CSS transitions or animations. The popover open/close motion is handled by the `Popover` component.
+
+## Accessibility
+
+**Roles:**
+
+- The trigger is a `<button>`.
+- Each column is `role="group"` with `aria-label` ("Hours", "Minutes", or "Period").
+- Each option button has `aria-pressed` for the selected state.
+
+**Keyboard:**
+
+| Key | Action |
+|---|---|
+| `Tab` | Moves focus to the trigger, then into the popover content (hour, minute, and period options). |
+| `Enter`, `Space` | Activates the trigger (opens popover) or an option button (selects value). |
+| `Escape` | Closes the popover (handled by `Popover`). |
+
+**Focus:**
+
+- Visible focus ring via `var(--dsx-shadow-focus-ring)` on the trigger and option buttons.
+
+**Reduced motion:**
+
+- The component has no CSS transitions. The popover open/close motion is handled by `Popover`.
+
+**Color and meaning:**
+
+- The selected option is communicated by the `--dsx-color-primary` background and `--dsx-color-on-primary` text. `aria-pressed` and `data-selected` provide assistive-tech semantics.
+- The invalid state is communicated by the `--dsx-color-error` border on the trigger and `aria-invalid`.
+
+**Naming:**
+
+- The trigger button requires an accessible name via `aria-label` or `aria-labelledby`.
+- The column groups are auto-labeled "Hours", "Minutes", and "Period".
+
+## Playground demo spec
+
+**Default story:**
+
+- Renders `TimePicker` with no props. Asserts the trigger class is `dsx-time-picker__trigger`.
+
+**Variant stories** (one per mode):
+
+- Renders with `mode="24h"` and `mode="12h"`. Asserts `data-mode` matches on the columns.
+
+**Variant stories** (one per size):
+
+- Renders with `size="sm"`, `size="md"`, and `size="lg"`. Asserts `data-size` matches on the trigger.
+
+**State story:**
+
+- Renders with `disabled`. Asserts the trigger is disabled.
+- Renders with `invalid`. Asserts `data-invalid="true"` on the trigger.
+- Renders with a controlled `value`. Asserts the trigger shows the formatted time.
+
+**Composition story:**
+
+- Opens the popover and asserts the hour, minute, and period columns are rendered.
+
+**Props exposed in the playground controls:**
+
+| Prop | Control | Default |
+|---|---|---|
+| `size` | select | `md` |
+| `mode` | select | `24h` |
+| `invalid` | boolean | `false` |
+| `disabled` | boolean | `false` |
+
+## Wiring notes
+
+**Composes from:**
+
+- `Popover`: provides the trigger/content portal structure. The DS shell uses `Popover.Trigger` with `asChild` to wrap the custom trigger button and `Popover.Content` for the popover panel.
+- `ScrollArea`: wraps the hour and minute option lists for bounded scrolling.
+- `Theme`: wraps the popover content with `appearance="inherit"` and `surface="transparent"` to inherit the active theme.
+- `Icon`: renders the clock and chevron-down glyphs.
+
+**Used by:**
+
+- No DS component currently wraps `TimePicker`. The pattern is the intended app-side composition.
+
+**State boundaries:**
+
+- Owned by this component: the popover open state, the parsed time value, the hour/minute/period option lists, the display formatting, and the canonical 24h value emission.
+- Owned by the consumer: the controlled or uncontrolled time value, the `onValueChange` callback, the `minuteStep`, the `mode`, and the `name` for form submission.
+
+**Boundary rules:**
+
+- App-owned data: the selected time value, the `onValueChange` handler, the `minuteStep`, and the form `name`.
+- DS-owned visuals: token bindings, the `dsx-time-picker` class hierarchy, the `data-size`, `data-mode`, `data-invalid`, and `data-placeholder` attributes, the column `aria-label` templates, and the display formatting logic.

package/dist/docs/timeline.md

@@ -0,0 +1,237 @@
+---
+title: Timeline
+status: canonical
+category: Components
+archetype: composite
+package_path: packages/d4gger-design-system/src/components/timeline/Timeline.tsx
+css_path: packages/d4gger-design-system/src/styles/components/timeline.css
+props_path: packages/d4gger-design-system/src/components/timeline/timeline.props.ts
+test_path: packages/d4gger-design-system/src/test/components/Timeline.test.tsx
+demo_path: apps/playground/app/(themeable)/docs/[component]/page.tsx
+playground_registry_path: apps/playground/lib/registry/data.tsx
+playground_manifest_path: apps/playground/lib/component-manifest.ts
+depends_on:
+  - Text
+  - Badge
+  - Icon
+---
+
+# Timeline
+
+> 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 vertical or alternating event timeline for activity feeds, audit logs, and order-of-operations walkthroughs. Each item pairs a marker (dot, icon, or number) with a content block and a connector that links to the next item.
+
+## Anatomy & slots
+
+**Parent:** `Timeline` (alias of `TimelineRoot`). The root is a `<div>` (or `Slot` host when `asChild` is set) that lays out its children in a column with `align-items: flex-start` (variant `left`) or `align-items: center` (variant `alternate`).
+
+**Slots:**
+
+| Slot | Element | Renders | Notes |
+|---|---|---|---|
+| `Timeline` (root) | `<div>` (or `Slot` host) | `dsx-timeline` (with `--left` or `--alternate` modifier) | Root container. Writes `data-size`. |
+| `Timeline.Item` | `<div>` (or `Slot` host) | `dsx-timeline__item` (with `--active` / `--error` / `--disabled` modifier) | One event row. Writes `data-state`. Holds a `Marker`, a `Content`, and (optionally) a `Connector`. |
+| `Timeline.Marker` | `<div>` (or `Slot` host) | `dsx-timeline__marker` | The dot/icon container. Holds an icon or a number; sized `var(--dsx-size-md)` and fully rounded. |
+| `Timeline.Connector` | `<div>` (or `Slot` host) | `dsx-timeline__connector` | The vertical line linking this item to the next. Positioned absolutely inside the item; turned on by the active state when the next step is also active. |
+| `Timeline.Content` | `<div>` (or `Slot` host) | `dsx-timeline__content` | The right-hand content block (title, time, description). |
+
+**Internal layout:**
+
+- The root renders a flex column. Items are stacked vertically.
+- In the `left` variant (the default), every item is a flex row with `gap: var(--dsx-space-lg)`. The marker sits on the left rail; the content fills the remaining space.
+- In the `alternate` variant, every item is a full-width flex row; the consumer is responsible for the alternating side-by-side layout (CSS does not alternate automatically).
+- `Timeline.Marker` is a square (`var(--dsx-size-md)`) fully rounded element with a 1px outline. It accepts arbitrary children, typically an `Icon` or a number from the consumer.
+- `Timeline.Connector` is an absolutely positioned vertical bar inside the item. It begins at the bottom of the marker and extends to the bottom of the item. Width is `var(--dsx-border-width-sm)` and color is `var(--dsx-color-outline-variant)`. The active state recolors it to `var(--dsx-color-primary)`.
+- `Timeline.Content` is the consumer's content surface. The CSS file defines helper classes `dsx-timeline__content-title`, `dsx-timeline__content-description`, and `dsx-timeline__content-time` for the typical title/body/time pattern, but the consumer is free to compose any children.
+
+## Props contract
+
+**Root props (`Timeline`):**
+
+| Prop | Type | Default | Required | Description | Responsive |
+|---|---|---|---|---|---|
+| `variant` | `'left' \| 'alternate'` | `'left'` | no | Layout variant. `left` aligns items to the left rail; `alternate` lets the consumer place content on alternating sides via custom markup. Writes the matching `dsx-timeline--left` / `dsx-timeline--alternate` modifier. | no |
+| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | no | Size scale for marker and content density. Writes `data-size`. | no |
+| `asChild` | `boolean` | `false` | no | Polymorphic host. | no |
+
+**Item props (`Timeline.Item`):**
+
+| Prop | Type | Default | Required | Description | Responsive |
+|---|---|---|---|---|---|
+| `state` | `'default' \| 'active' \| 'error' \| 'disabled'` | `'default'` | no | Visual state. `active` recolors the marker and connector to the primary palette; `error` recolors both to the error palette; `disabled` reduces opacity to `var(--dsx-opacity-disabled)`. Writes `data-state` and the matching `dsx-timeline__item--*` modifier. | no |
+| `asChild` | `boolean` | `false` | no | Polymorphic host. | no |
+
+**Marker / Connector / Content props:**
+
+These three slots accept only `asChild` plus the standard HTML attribute surface for their host elements. The marker is intentionally generic so the consumer can drop an `Icon`, a number, or any other node.
+
+## CSS class contract
+
+**Root class:** `dsx-timeline`
+
+**Modifier classes** (driven by `data-*` and modifier classes written by the component):
+
+| Attribute / class | Allowed values | Class | CSS file |
+|---|---|---|---|
+| Root variant (class) | `left`, `alternate` | `.dsx-timeline--left`, `.dsx-timeline--alternate` | `timeline.css` |
+| Root size | `sm`, `md`, `lg` | (attribute forwarded; size rules live on slot classes when used) | `timeline.css` |
+| Item state (attribute) | `default`, `active`, `error`, `disabled` | `.dsx-timeline__item` (state modifier class) | `timeline.css` |
+| Item state (class) | `active`, `error`, `disabled` | `.dsx-timeline__item--active`, `--error`, `--disabled` | `timeline.css` |
+| Active marker | n/a | `.dsx-timeline__item--active .dsx-timeline__marker` | `timeline.css` |
+| Error marker | n/a | `.dsx-timeline__item--error .dsx-timeline__marker` | `timeline.css` |
+| Disabled marker | n/a | `.dsx-timeline__item--disabled .dsx-timeline__marker` | `timeline.css` |
+| Active connector | n/a | `.dsx-timeline__item--active .dsx-timeline__connector` | `timeline.css` |
+
+**Slot classes:**
+
+| Slot | Class | CSS file |
+|---|---|---|
+| `Timeline` (root) | `dsx-timeline` (+ `--left` / `--alternate` modifier) | `timeline.css` |
+| `Timeline.Item` | `dsx-timeline__item` (+ `--active` / `--error` / `--disabled` modifier) | `timeline.css` |
+| `Timeline.Marker` | `dsx-timeline__marker` | `timeline.css` |
+| `Timeline.Connector` | `dsx-timeline__connector` | `timeline.css` |
+| `Timeline.Content` | `dsx-timeline__content` | `timeline.css` |
+| Title text (consumer-supplied) | `dsx-timeline__content-title` | `timeline.css` |
+| Description text (consumer-supplied) | `dsx-timeline__content-description` | `timeline.css` |
+| Time text (consumer-supplied) | `dsx-timeline__content-time` | `timeline.css` |
+
+**Responsive behavior:**
+
+- The component does not write `@media` rules. Responsive layout comes from the layout primitives' responsive classes when the consumer wraps the timeline in a responsive shell.
+
+**Reduced motion:**
+
+- The component is static. No motion is applied.
+
+## Token mapping
+
+Every CSS value the component paints is a `var(--dsx-*)` token.
+
+| Property | Token | Role |
+|---|---|---|
+| Item gap (left variant) | `var(--dsx-space-lg)` | Horizontal space between marker and content |
+| Marker size | `var(--dsx-size-md)` | Marker width and height |
+| Marker border | `var(--dsx-border-width-sm) solid var(--dsx-color-outline)` | Marker edge |
+| Marker background | `var(--dsx-color-surface)` | Marker surface |
+| Marker radius | `var(--dsx-rounded-full)` | Circular marker |
+| Marker inner icon size | `var(--dsx-space-md)` | Icon inside marker |
+| Active marker border / background | `var(--dsx-color-primary)` | Active palette |
+| Active marker text | `var(--dsx-color-on-primary)` | Active marker text |
+| Error marker border / background | `var(--dsx-color-error)` | Error palette |
+| Error marker text | `var(--dsx-color-on-error)` | Error marker text |
+| Disabled marker | `var(--dsx-opacity-disabled)` | Disabled opacity |
+| Connector width | `var(--dsx-border-width-sm)` | Connector thickness |
+| Connector color | `var(--dsx-color-outline-variant)` | Default connector |
+| Connector active color | `var(--dsx-color-primary)` | Active connector |
+| Content padding-bottom | `var(--dsx-space-lg)` | Spacing between items |
+| Title color | `var(--dsx-color-on-surface)` | Item title text |
+| Title type ramp | `var(--dsx-typography-body-medium-*)` | Item title |
+| Description color | `var(--dsx-color-on-surface-variant)` | Item description |
+| Description type ramp | `var(--dsx-typography-body-medium-*)` | Item description |
+| Time color | `var(--dsx-color-on-surface-variant)` | Time text |
+| Time type ramp | `var(--dsx-typography-label-small-*)` | Time text |
+| Disabled title / description | `var(--dsx-opacity-disabled)` | Disabled content opacity |
+
+## Motion contract
+
+| Region | Token | Default | Reduced |
+|---|---|---|---|
+| (none) | none | none | n/a |
+
+The component has no motion. It is a static read surface.
+
+## Accessibility
+
+**Roles:**
+
+- The root renders as a `<div>` without an explicit `role`. Consumers that need a `feed` / `list` semantics should wrap the timeline themselves; the canonical pattern is a non-semantic visual timeline.
+- Individual items are not focusable. The marker and content are visual; interactivity (e.g. opening a record) belongs on a Button or Link inside `Timeline.Content`.
+
+**Keyboard:**
+
+| Key | Action |
+|---|---|
+| `Tab` | Moves focus through interactive elements placed inside `Timeline.Content` (e.g. links, buttons). |
+
+**Focus:**
+
+- The component does not render a focus ring on items. Interactive content provides its own ring.
+
+**Reduced motion:**
+
+- No motion is applied; no `prefers-reduced-motion` override is needed.
+
+**Color and meaning:**
+
+- State is communicated by both color and the marker icon: `active` uses the primary palette; `error` uses the error palette; `disabled` reduces opacity.
+- Markers can hold an icon (a check, a warning, etc.) to make the state readable without color.
+
+**Naming:**
+
+- The consumer-supplied content inside `Timeline.Content` should be self-describing (a title plus a timestamp, for example). The timeline itself does not impose an accessible name.
+
+## Playground demo spec
+
+**Default story:**
+
+- Renders a `Timeline` with two items: one `state="active"`, one `state="default"`. Asserts the root class is `dsx-timeline`, the variant modifier `dsx-timeline--left` is present, and both item states resolve to the right modifier class.
+
+**Variant story:**
+
+- Renders one `Timeline` with `variant="left"` and one with `variant="alternate"`. Asserts the `dsx-timeline--left` and `dsx-timeline--alternate` classes.
+
+**State story:**
+
+- Renders items with `state="active"`, `state="error"`, and `state="disabled"`. Asserts the matching `data-state` attribute and modifier class on each item.
+
+**Composition story:**
+
+- Renders a `Timeline.Item` with `Timeline.Marker` (holding a number), `Timeline.Content` (with `dsx-timeline__content-title`, `dsx-timeline__content-description`, and `dsx-timeline__content-time` children), and a `Timeline.Connector`. Asserts all slot classes and the helper text classes.
+
+**Token story:**
+
+- Renders the default timeline inside a `Theme` wrapper with `accentColor="silver"` and `accentColor="bronze"`. Asserts the `data-accent-color` attribute is forwarded, but the active marker color tracks `--dsx-color-primary` and is not affected by the accent token.
+
+**A11y story:**
+
+- Uses `vitest-axe` against the default story. Asserts no axe violations.
+
+**Props exposed in the playground controls:**
+
+| Prop | Control | Default |
+|---|---|---|
+| `variant` | select | `left` |
+| `size` | select | `md` |
+
+## Wiring notes
+
+**Composes from:**
+
+- `@radix-ui/react-slot`: enables `asChild` on the root and on every named slot.
+
+**Used by:**
+
+- App-level audit logs, deployment histories, and order-of-operations walkthroughs. `NotificationCenter` is the closer match for inbox-style activity feeds; `Timeline` is the right surface when events have a fixed order and a discrete marker.
+
+**State boundaries:**
+
+- Owned by Timeline: `variant`, `size`, item `state`, and the `dsx-timeline__*` slot classes.
+- Owned by the consumer: the marker content (icon or number), the content text, the order of items, and any interactive elements inside `Timeline.Content`.
+
+**Boundary rules:**
+
+- App-owned data: event payloads, timestamps, and click/select handlers.
+- DS-owned visuals: token bindings, slot classes, state modifier classes, and the active / error / disabled color mapping.
+
+**Anomalies** (open items that this spec flags for the next promotion):
+
+1. **Content block layout collapsed; title, description, time rendered run-together.** The `.dsx-timeline__content` slot had no `display`, `flex-direction`, or `gap`, causing its children (the title `<span>`, description `<span>`, and time `<span>`, typically rendered bare by consumers) to render as inline siblings on a single line ("Project createdInitial scaffold2 hours ago"). FIXED 2026-07-03: added `display: flex; flex-direction: column; gap: var(--dsx-space-2xs);` to `.dsx-timeline__content`, plus `flex: 1; padding-bottom: var(--dsx-space-lg);` to preserve the item gap semantics and support the connector's absolute positioning.
+
+2. **Alternate variant had no CSS implementation; items never alternated.** The `variant="alternate"` prop def wrote the `dsx-timeline--alternate` modifier class on the root, but the CSS file contained no rules targeting that modifier — the layout was identical to the `left` variant. FIXED 2026-07-03: added per-item zigzag rules for the `alternate` variant: even-indexed items get `flex-direction: row-reverse` (marker on the right), `text-align: right` on content, and the connector repositioned from `left` to `right` with size-aware recalculation per `data-size` (sm/md/lg). This is a per-item flip, not a shared centered spine — the connector is item-local, not a continuous centerline. A future polish iteration may introduce a centered-column connector pattern.
+
+3. **Connector appeared missing but was symptom of layout bug, not a separate defect.** The connector (an absolutely positioned vertical bar inside each item) appeared invisible or extremely short (~18px) in rendered demos. Investigation revealed the connector itself was present with correct background color and dimensions; the visual symptom was a side effect of the spacing bug (#1 above). When `.dsx-timeline__content` had no flex layout, its children ran together in ~20px of vertical space, making the item itself tiny, and the connector's absolute `top: marker-bottom; bottom: 0` was proportionally tiny too. Fixing the spacing bug (adding the flex column layout) expanded the item's natural height, and the connector automatically became visible. No separate CSS fix was needed for the connector; it was never the root cause.
+
+4. **Playground fixture uses invalid state values.** The registry fixture at `apps/playground/lib/registry/data.tsx` (Timeline entry, "Default" story) passes `state="complete"` and `state="pending"` to `TimelineItem`, but `timeline.props.ts`'s `timelineItemPropDefs.state` enum only allows `'default' | 'active' | 'error' | 'disabled'`. Invalid enum values silently fall through to the default modifier class (no visible error). This is a fixture-honesty gap (the fixture uses API values that the type definitions reject) and is deferred to the next promotion batch.