@d4gger/design-system 2.7.0

package/dist/docs/notification-center.md

@@ -0,0 +1,253 @@
+---
+title: NotificationCenter
+status: canonical
+category: Components
+archetype: composite
+package_path: packages/d4gger-design-system/src/components/notificationCenter/NotificationCenter.tsx
+css_path: packages/d4gger-design-system/src/styles/components/notification-center.css
+props_path: packages/d4gger-design-system/src/components/notificationCenter/notificationCenter.props.ts
+test_path: packages/d4gger-design-system/src/test/components/NotificationCenter.test.tsx
+demo_path: apps/playground/app/(themeable)/docs/[component]/page.tsx
+playground_registry_path: apps/playground/lib/registry/overlay.tsx
+playground_manifest_path: apps/playground/lib/component-manifest.ts
+depends_on:
+  - IconButton
+  - Badge
+---
+
+# NotificationCenter
+
+> 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 inbox-style notification surface that groups header, list, and footer regions with optional unread state on each item. `NotificationCenter` is the visual anatomy of a notifications panel. The package owns the surface and the item states; the consumer owns the notification payload, the polling / streaming, the click-through routing, and the mark-as-read handler.
+
+## Anatomy & slots
+
+**Parent:** `NotificationCenter` (alias of `NotificationCenterRoot`). The root is a `<div>` (or `Slot` host when `asChild` is set) that lays out a `Header` region, a `List` region, and a `Footer` region. The root also writes a `data-unread` attribute when an unread count is provided.
+
+**Slots:**
+
+| Slot | Element | Renders | Notes |
+|---|---|---|---|
+| `NotificationCenter` (root) | `<div>` (or `Slot` host) | `dsx-notification-center` (with `--popover` or `--sidebar` modifier) | Root container. Writes `data-unread` when the `unreadCount` prop is greater than zero. |
+| `NotificationCenter.Header` | `<div>` (or `Slot` host) | `dsx-notification-center__header` | Title row at the top of the panel. The CSS file ships a helper class `dsx-notification-center__header-title` for the title text. |
+| `NotificationCenter.List` | `<div>` (or `Slot` host) | `dsx-notification-center__list` | Vertical list of items. Capped at `max-height: 400px` with `overflow-y: auto`. |
+| `NotificationCenter.Footer` | `<div>` (or `Slot` host) | `dsx-notification-center__footer` | Footer row (typically a "View all" link or button). |
+| `NotificationCenter.Item` | `<div>` (or `Slot` host) | `dsx-notification-center__item` (with `--unread` modifier when `unread` is true) | A single notification row. The CSS file ships helper classes `dsx-notification-center__item-title`, `dsx-notification-center__item-description`, and `dsx-notification-center__item-time` for the typical layout. |
+| `NotificationCenter.Trigger` | `IconButton` + `Badge` fragment | `dsx-notification-center__trigger` and `dsx-notification-center__badge` | Bell-style trigger. Wraps an `IconButton` (size `sm`, variant `ghost`, default `aria-label="Notifications"`) and conditionally renders a `Badge` with the unread count (capped at `'99+'`). The trigger is rendered as a React fragment so it can be placed anywhere. |
+
+**Internal layout:**
+
+- The root is a flex column. The header sits at the top, the list fills the middle, the footer sits at the bottom.
+- In the `popover` variant (the default), the root is sized `width: 320px`, has a `var(--dsx-rounded-lg)` radius, a 1px outline, an `var(--dsx-color-surface-overlay)` background, and a `var(--dsx-shadow-card-md)` shadow.
+- In the `sidebar` variant, the root is full-width / full-height with a flat `var(--dsx-color-surface)` background and no border or shadow.
+- `NotificationCenter.Item` rows have a `var(--dsx-space-md)` padding and a 1px bottom border. The last item drops the bottom border. The item background switches to `var(--dsx-color-surface-raised)` with a 1px primary left border when `unread` is true.
+- `NotificationCenter.Trigger` is a positioned `inline-flex` container. The badge is absolutely positioned in the top-right corner with a `-var(--dsx-space-xs)` offset, a `var(--dsx-rounded-full)` radius, and label-small typography.
+
+## Props contract
+
+**Root props (`NotificationCenter`):**
+
+| Prop | Type | Default | Required | Description | Responsive |
+|---|---|---|---|---|---|
+| `variant` | `'popover' \| 'sidebar'` | `'popover'` | no | Layout variant. `popover` sizes the surface as a 320px wide floating card. `sidebar` expands the surface to fill its parent for use inside a side panel. Writes the matching `dsx-notification-center--*` modifier class. | no |
+| `unreadCount` | `number` | `undefined` | no | Unread count surfaced on the root as a `data-unread="<count>"` attribute. The attribute is only written when the count is greater than zero. The header or trigger typically reads the count and renders the matching label. | no |
+| `asChild` | `boolean` | `false` | no | Polymorphic host. | no |
+
+**Header / List / Footer props:**
+
+These three slots accept only `asChild` plus the standard HTML attribute surface for their host elements.
+
+**Item props (`NotificationCenter.Item`):**
+
+| Prop | Type | Default | Required | Description | Responsive |
+|---|---|---|---|---|---|
+| `unread` | `boolean` | `false` | no | Marks the item as unread. Writes `data-unread="true"` and the `dsx-notification-center__item--unread` modifier. | no |
+| `asChild` | `boolean` | `false` | no | Polymorphic host. | no |
+
+**Trigger props (`NotificationCenter.Trigger`):**
+
+| Prop | Type | Default | Required | Description | Responsive |
+|---|---|---|---|---|---|
+| `unreadCount` | `number` | `undefined` | no | Unread count rendered as a `Badge` (capped at `'99+'`). The badge is only rendered when the count is greater than zero. | no |
+| `aria-label` | `string` | `'Notifications'` | no | Accessible name on the underlying `IconButton`. Override to localize or to disambiguate when more than one trigger is on the page. | no |
+| `asChild` | `boolean` | `false` | no | Polymorphic host. | no |
+
+The trigger is a thin wrapper around `IconButton`; it forwards all of `IconButton`'s standard button props (`onClick`, `disabled`, `type`, etc.).
+
+## CSS class contract
+
+**Root class:** `dsx-notification-center`
+
+**Modifier classes** (driven by `data-*` attributes and variant modifier classes):
+
+| Attribute / class | Allowed values | Class | CSS file |
+|---|---|---|---|
+| Root variant (class) | `popover`, `sidebar` | `.dsx-notification-center--popover`, `.dsx-notification-center--sidebar` | `notification-center.css` |
+| Root unread (attribute) | numeric string | `data-unread="<count>"` on the root | (TSX) |
+| Item unread (attribute) | `true` | `data-unread="true"` | (TSX) |
+| Item unread (class) | n/a | `.dsx-notification-center__item--unread` | `notification-center.css` |
+
+**Slot classes:**
+
+| Slot | Class | CSS file |
+|---|---|---|
+| `NotificationCenter` (root) | `dsx-notification-center` (+ `--popover` / `--sidebar` modifier) | `notification-center.css` |
+| `NotificationCenter.Header` | `dsx-notification-center__header` | `notification-center.css` |
+| `NotificationCenter.List` | `dsx-notification-center__list` | `notification-center.css` |
+| `NotificationCenter.Footer` | `dsx-notification-center__footer` | `notification-center.css` |
+| `NotificationCenter.Item` | `dsx-notification-center__item` (+ `--unread` modifier) | `notification-center.css` |
+| `NotificationCenter.Trigger` | `dsx-notification-center__trigger` | `notification-center.css` |
+| Trigger badge (rendered with `Badge`) | `dsx-notification-center__badge` | `notification-center.css` |
+| Header title (consumer-supplied) | `dsx-notification-center__header-title` | `notification-center.css` |
+| Item title (consumer-supplied) | `dsx-notification-center__item-title` | `notification-center.css` |
+| Item description (consumer-supplied) | `dsx-notification-center__item-description` | `notification-center.css` |
+| Item time (consumer-supplied) | `dsx-notification-center__item-time` | `notification-center.css` |
+
+**Responsive behavior:**
+
+- The component does not write `@media` rules. The `popover` variant uses a fixed 320px width; on small screens the consumer is expected to swap in a different layout (e.g. a full-screen Sheet) and render the same items in `NotificationCenter` with the `sidebar` variant.
+
+**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 |
+|---|---|---|
+| Popover width | `320px` | Popover variant width |
+| Popover border-radius | `var(--dsx-rounded-lg)` | Popover roundness |
+| Popover border | `var(--dsx-border-width-sm) solid var(--dsx-color-outline)` | Popover edge |
+| Popover background | `var(--dsx-color-surface-overlay)` | Popover surface |
+| Popover shadow | `var(--dsx-shadow-card-md)` | Popover elevation |
+| Sidebar background | `var(--dsx-color-surface)` | Sidebar surface |
+| Header padding | `var(--dsx-space-md)` | Header gutter |
+| Header border-bottom | `var(--dsx-border-width-sm) solid var(--dsx-color-outline-variant)` | Header separator |
+| Header title type ramp | `var(--dsx-typography-label-large-*)` | Header title text |
+| Header title color | `var(--dsx-color-on-surface)` | Header title color |
+| List max-height | `400px` | List scroll cap |
+| List overflow | `auto` | Vertical scroll |
+| Item padding | `var(--dsx-space-md)` | Item gutter |
+| Item gap | `var(--dsx-space-xs)` | Item inner gap |
+| Item border-bottom | `var(--dsx-border-width-sm) solid var(--dsx-color-outline-variant)` | Item separator |
+| Item hover | `var(--dsx-effect-hover-ghost)` | Item hover background |
+| Unread item background | `var(--dsx-color-surface-raised)` | Unread background |
+| Unread item border-left | `var(--dsx-border-width-sm) solid var(--dsx-color-primary)` | Unread indicator |
+| Item title type ramp | `var(--dsx-typography-body-medium-*)` | Item title text |
+| Item title color | `var(--dsx-color-on-surface)` | Item title color |
+| Item description color | `var(--dsx-color-on-surface-variant)` | Item description color |
+| Item time color | `var(--dsx-color-on-surface-variant)` | Item time color |
+| Item time type ramp | `var(--dsx-typography-label-small-*)` | Item time text |
+| Footer padding | `var(--dsx-space-sm)` | Footer gutter |
+| Footer border-top | `var(--dsx-border-width-sm) solid var(--dsx-color-outline-variant)` | Footer separator |
+| Trigger position | `relative` | Anchors the badge |
+| Badge position | `absolute` with `-var(--dsx-space-xs)` offsets | Badge placement |
+| Badge min-width | `var(--dsx-size-xs)` | Badge min width |
+| Badge height | `var(--dsx-size-xs)` | Badge height |
+| Badge radius | `var(--dsx-rounded-full)` | Badge roundness |
+| Badge type ramp | `var(--dsx-typography-label-small-*)` | Badge text |
+
+## Motion contract
+
+| Region | Token | Default | Reduced |
+|---|---|---|---|
+| (none) | none | none | n/a |
+
+The component has no motion. The panel itself is static; transitions on open / close are owned by the surrounding trigger surface (`Popover`, `Sheet`, etc.).
+
+## Accessibility
+
+**Roles:**
+
+- The root renders as a `<div>` without an explicit `role`. The canonical pattern is to wrap the panel in a `Popover` or `Sheet`; the wrapping surface is responsible for the modal / non-modal role and focus management.
+- `NotificationCenter.List` is a plain `<div>`. If the consumer wants to expose the list as an `aria-live` region (e.g. for incoming notifications), they can add the `aria-live` and `aria-relevant` attributes manually.
+- `NotificationCenter.Trigger` renders an `IconButton` with `role="button"` and a default `aria-label` of `'Notifications'`. The accompanying badge is announced through the `aria-label` (`Notifications: 5 unread`, or similar — the consumer is responsible for composing the full accessible name when the count is non-zero).
+
+**Keyboard:**
+
+| Key | Action |
+|---|---|
+| `Tab` | Moves focus through interactive elements placed inside items (e.g. links, buttons, or the consumer's row-level button). |
+| `Enter` / `Space` | Activates the focused interactive element. |
+
+**Focus:**
+
+- The component does not render a focus ring on items or panels. Interactive content provides its own ring.
+- The trigger button gets the standard `IconButton` focus ring.
+
+**Reduced motion:**
+
+- No motion is applied by the package CSS. Open / close transitions on the wrapping `Popover` or `Sheet` are out of scope.
+
+**Color and meaning:**
+
+- Unread state is communicated by both the left border accent and the background lift. The text is unchanged; consumers can add an `aria-label="Unread"` to make the state screen-reader-accessible.
+- The trigger badge is a red `Badge` (`variant="error"`). The label is the numeric count.
+
+**Naming:**
+
+- The trigger button has a default `aria-label="Notifications"`. Override it when the trigger is not the only notifications surface, or when the product copy demands a different label.
+- Each item should carry a self-describing title. The description and time are optional context.
+
+## Playground demo spec
+
+**Default story:**
+
+- Renders a `NotificationCenter` with `variant="popover"`, a `Header` containing the title "Notifications (2)", a `List` with two `Item`s, and a `Footer`. Asserts the root class is `dsx-notification-center`, the `--popover` modifier is present, and the header / list / footer slot classes resolve.
+
+**Variant story:**
+
+- Renders one `NotificationCenter` with `variant="popover"` and one with `variant="sidebar"`. Asserts the matching `dsx-notification-center--*` modifier class.
+
+**State story:**
+
+- Renders a `NotificationCenter` with `unreadCount={3}`. Asserts `data-unread="3"` on the root.
+- Renders an `Item` with `unread`. Asserts `data-unread="true"` and the `--unread` modifier class.
+- Renders a `Trigger` with `unreadCount={5}`. Asserts the badge text is `'5'`.
+- Renders a `Trigger` with `unreadCount={150}`. Asserts the badge text is `'99+'`.
+
+**Composition story:**
+
+- Renders a full panel: `Header` with `dsx-notification-center__header-title`, `List` with two `Item`s (one `unread`, one read), each with `dsx-notification-center__item-title`, `dsx-notification-center__item-description`, and `dsx-notification-center__item-time`, plus a `Footer` with a "View all" link. Asserts all slot and helper classes resolve.
+
+**Token story:**
+
+- Renders the default panel inside a `Theme` wrapper with `accentColor="silver"` and `accentColor="bronze"`. Asserts the unread item border 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 | `popover` |
+| `unreadCount` | number | `0` |
+
+## Wiring notes
+
+**Composes from:**
+
+- `IconButton` (`src/components/iconButton`): the trigger renders a small ghost `IconButton`. The trigger forwards all `IconButton` props and defaults `aria-label="Notifications"`.
+- `Badge` (`src/components/badge`): the trigger badge is a `Badge` with `variant="error"`, `size="sm"`. The count is rendered as plain text and is capped at `'99+'` for counts greater than 99.
+- `@radix-ui/react-slot`: enables `asChild` on the root and on the named slots.
+
+**Used by:**
+
+- App-level notification drawers, app-bar bell icons, and the in-app inbox. The package does not ship a streaming / polling integration; the consumer brings the data source and the mark-as-read handler.
+
+**State boundaries:**
+
+- Owned by NotificationCenter: `variant`, `unreadCount` (on the root and on the trigger), `unread` (on `Item`), and the `dsx-notification-center__*` slot classes.
+- Owned by the consumer: the notification payload, the open / close trigger, the mark-as-read handler, the routing on click, and the surrounding `Popover` or `Sheet` if any.
+
+**Boundary rules:**
+
+- App-owned data: notification text, timestamps, action handlers, and the unread count source.
+- DS-owned visuals: token bindings, slot classes, unread state styling, and the trigger badge geometry.

package/dist/docs/number-input.md

@@ -0,0 +1,325 @@
+---
+title: NumberInput
+status: canonical
+category: Components
+archetype: primitive
+package_path: packages/d4gger-design-system/src/components/numberInput/NumberInput.tsx
+css_path: packages/d4gger-design-system/src/styles/components/number-input.css
+props_path: packages/d4gger-design-system/src/components/numberInput/numberInput.props.ts
+test_path: packages/d4gger-design-system/src/test/components/NumberInput.test.tsx
+demo_path: apps/playground/app/page.tsx
+depends_on:
+  - Input (token-aligned input shell; the runtime host shares its visual treatment via `dsx-input-shell`)
+  - IconButton (the increment and decrement steppers; in source they are native `<button>` elements styled to match the DS IconButton surface)
+  - Icon (lucide-react `ChevronUp`, `ChevronDown`)
+---
+
+# NumberInput
+
+> 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 spinbutton-style numeric entry control that pairs a token-aligned text input with `+` / `-` stepper buttons. The component owns min, max, and step clamping and supports both controlled and uncontrolled value modes.
+
+## Anatomy & slots
+
+**Parent:** `NumberInput` (no compound; flat export).
+
+**Slots:**
+
+No slots: flat export. The component renders a `<div>` root that wraps an input shell with an inline stepper. The stepper is a `<div>` containing two `<button>` elements (up and down), each rendering a `ChevronUp` or `ChevronDown` icon from `lucide-react`. The component does not expose named subcomponents; the stepper is an internal layout, not a slot for the consumer to replace.
+
+The implementation is intentionally written in source rather than by composing the `Input` and `IconButton` exports. The `dsx-input-shell` class is reused from `src/_internal/baseInput.css` so the visual treatment stays aligned with the `Input` primitive, but the runtime does not import the `Input` component. The stepper buttons use the same `dsx-number-input__step-up` / `dsx-number-input__step-down` classes the CSS defines and visually match the `IconButton` primitive at the same size.
+
+## Props contract
+
+| Prop | Type | Default | Required | Description | Responsive |
+|---|---|---|---|---|---|
+| `value` | `number` | `undefined` | no | Controlled value. When set, the component is controlled; `onChange` is the only path to update it. | no |
+| `defaultValue` | `number` | `undefined` | no | Initial value for the uncontrolled mode. The component seeds `useState` with this value. | no |
+| `onChange` | `(value: number \| undefined) => void` | `undefined` | no | Called with the parsed value on every change. Emits `undefined` when the input is empty or `-`. | no |
+| `min` | `number` | `undefined` | no | Lower bound. The down stepper is disabled when the current value is at or below `min`. | no |
+| `max` | `number` | `undefined` | no | Upper bound. The up stepper is disabled when the current value is at or above `max`. | no |
+| `step` | `number` | `1` | no | Increment and decrement amount. | no |
+| `variant` | `'surface' \| 'classic' \| 'ghost'` | `'surface'` | no | Visual treatment. `'classic'` adds an elevation shadow; `'ghost'` removes border and background until focused. | no |
+| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | no | Control height and inner padding. Drives the `data-size` attribute and the size-specific CSS overrides. | no |
+| `radius` | `'none' \| 'sm' \| 'md' \| 'lg' \| 'full'` | `undefined` | no | Shell corner radius override. Drives the `data-radius` attribute and the corresponding CSS rules. | no |
+| `asChild` | `boolean` | `false` | no | Renders the inner input through `Slot` from `@radix-ui/react-slot`. Note: the outer `<div>` root is not polymorphic; only the input element is. | no |
+| `disabled` | `boolean` | `false` | no | Disables the input and the stepper buttons. Forwarded from the input's native `disabled` attribute. | no |
+| `placeholder` | `string` | `undefined` | no | Forwarded to the inner input. | no |
+| `aria-label` | `string` | `undefined` | no | Required for accessibility. The input has no implicit label. | no |
+| `className` | `string` | `undefined` | no | Extra classes appended to the inner input's `dsx-number-input__input` class. | no |
+| `style` | `React.CSSProperties` | `undefined` | no | Extra inline style forwarded to the inner input. | no |
+| `id` | `string` | `undefined` | no | Forwarded to the inner input. | no |
+| `name` | `string` | `undefined` | no | Forwarded to the inner input. | no |
+| `inputMode` | `decimal` (default) | `'decimal'` | no | Always set to `'decimal'`; the underlying `<input type="text">` uses `inputMode="decimal"` for mobile keyboards. The native attribute is forwarded if the consumer overrides it. | no |
+| `type` | `'text'` (forced) | `'text'` | no | Always rendered as `type="text"`. The native HTML attribute is omitted from the prop bag so consumers cannot change it. | no |
+
+Rules that apply to this row:
+
+- `Omit<React.ComponentPropsWithoutRef<'input'>, 'type' | 'value' | 'defaultValue' | 'onChange' | 'min' | 'max' | 'step' | 'size'>` removes the conflicting native attributes. The component redefines them with its own typing.
+- `size` is a `PropDef` enum on the package's prop bag; consumers do not get the native HTML `size` attribute on the input. They get the DS size scale instead.
+- `asChild` is the only polymorphic infra. It applies to the inner input, not the wrapping `<div>`.
+- When `controlledValue` is `undefined`, the component runs in uncontrolled mode and seeds `useState` with `defaultValue`. When `controlledValue` is defined, the component never calls the internal setter.
+
+## CSS class contract
+
+**Root class:** `dsx-number-input` (the outer `<div>`). The inner input is `dsx-number-input__input`.
+
+**Modifier classes** (driven by `data-*` attributes written by the component):
+
+| Attribute | Allowed values | Class | CSS file |
+|---|---|---|---|
+| `data-size` | `sm`, `md`, `lg` | `.dsx-number-input[data-size='sm'\|'lg']` overrides for shell and input | `number-input.css` |
+| `data-variant` | `surface`, `classic`, `ghost` | `.dsx-number-input[data-variant='classic']` (elevation), `.dsx-number-input[data-variant='ghost']` (transparent until focused) | `number-input.css` |
+| `data-radius` | `none`, `sm`, `md`, `lg`, `full` | `.dsx-number-input[data-radius='...']` shell radius override | `number-input.css` |
+
+**Slot classes:**
+
+| Slot | Class | CSS file |
+|---|---|---|
+| Shell (input wrapper) | `dsx-input-shell`, `dsx-number-input__shell` | `_internal/baseInput.css` (reused) and `number-input.css` |
+| Input | `dsx-number-input__input` | `number-input.css` |
+| Stepper region | `dsx-number-input__stepper` | `number-input.css` |
+| Step up button | `dsx-number-input__step-up` | `number-input.css` |
+| Step down button | `dsx-number-input__step-down` | `number-input.css` |
+
+**Data slots** (used by QA and audit tooling, not visual):
+
+| Element | `data-slot` |
+|---|---|
+| Inner input | `number-input` |
+| Step up button | `number-input-step-up` |
+| Step down button | `number-input-step-down` |
+
+**Responsive behavior:**
+
+- The component does not write `@media` rules. None of its prop defs are `responsive: true`. Size and radius are single-value only.
+- The component's CSS file is breakpoint-agnostic.
+
+**Reduced motion:**
+
+- Stepper buttons transition `color` and `background` against `var(--dsx-motion-duration-fast)` and `var(--dsx-motion-easing-in-out)`. The runtime does not import `usePrefersReducedMotion`; rely on the global stylesheet to honor the media query.
+
+## Token mapping
+
+Every CSS value the component paints is a `var(--dsx-*)` token.
+
+| Property | Token | Role |
+|---|---|---|
+| Shell padding (end) | `var(--dsx-space-3)` | Right gutter for the stepper column. |
+| Input padding (right) | `0` (overrides the base input padding to make room for the stepper). |
+| Input text color | `var(--dsx-color-on-surface)` | Typed value. |
+| Input placeholder color | `var(--dsx-color-on-surface-variant)` | Placeholder text. |
+| Input disabled text color | `var(--dsx-color-text-disabled)` | Disabled state. |
+| Input disabled cursor | `var(--dsx-cursor-disabled, not-allowed)` | Disabled cursor fallback chain. |
+| Input typography | `var(--dsx-typography-body-medium-*` with size overrides for sm and lg | Body type ramp. |
+| Stepper position | `var(--dsx-space-xs)` from the right, vertically centered | Stepper placement. |
+| Stepper column width | `var(--dsx-space-lg)` | Stepper column width. |
+| Stepper border | `var(--dsx-border-width-sm)` + `var(--dsx-color-outline)` | Vertical separator. |
+| Stepper button size | `var(--dsx-space-md)` square | Stepper tap target. |
+| Stepper button radius | `var(--dsx-rounded-sm)` | Stepper button corners. |
+| Stepper button text color | `var(--dsx-color-on-surface-variant)` | Resting state. |
+| Stepper button hover background | `var(--dsx-effect-hover-layer)` | Hover surface. |
+| Stepper button hover text | `var(--dsx-color-on-surface)` | Hover text color. |
+| Stepper button active background | `var(--dsx-effect-pressed-layer)` | Active surface. |
+| Stepper button disabled opacity | `var(--dsx-opacity-disabled)` | Disabled fade. |
+| Shell hover border | `var(--dsx-color-outline-variant)` + `var(--dsx-color-surface-hover)` (via `baseInput.css`) | Hover surface. |
+| Shell focus border | `var(--dsx-color-primary)` + `var(--dsx-shadow-focus-ring)` | Focus state. |
+| Shell border (default) | `var(--dsx-border-width-sm)` + `var(--dsx-color-outline)` + `var(--dsx-color-surface)` | Default surface. |
+| Shell radius | `var(--dsx-rounded-md)` (default) | Default corner radius. |
+| Shell radius (overrides) | `none`, `--dsx-rounded-sm\|md\|lg\|full` | Driven by `data-radius`. |
+| Shell elevation (`classic`) | `var(--dsx-effect-shadow-1)` | Classic variant shadow. |
+| Shell background (`ghost`) | `transparent` until focus-within, then `--dsx-color-surface` | Ghost variant. |
+| Autofill background | `var(--dsx-color-surface-field-autofill)` (via `baseInput.css`) | Browser autofill. |
+| Motion | `var(--dsx-motion-duration-fast)` + `var(--dsx-motion-easing-in-out)` | Stepper and shell transitions. |
+
+Rules:
+
+- Tokens come from `DESIGN.md` and the generated `tokens.css`. The only intentional non-token value in `number-input.css` is the `0` padding override on the input and the `outline: none` declaration on the input (focus is owned by the shell).
+- `data-variant="ghost"` is a CSS-only state; the TSX never branches on it. The runtime only writes the attribute.
+
+## Motion contract
+
+| Region | Token | Default | Reduced |
+|---|---|---|---|
+| Stepper button color and background | `var(--dsx-motion-duration-fast)` + `var(--dsx-motion-easing-in-out)` | Hover background swap, color shift | `none` — relies on the global `prefers-reduced-motion` stylesheet. |
+| Shell border, background, box-shadow (via `baseInput.css`) | `var(--dsx-motion-duration-fast, 150ms)` + `var(--dsx-motion-easing-standard, ease)` | Hover, focus-within transitions | `none` — relies on the global stylesheet. |
+
+Rules:
+
+- This row does not import `MOTION_TRANSITIONS` from `src/_internal/motion.ts`. All motion is CSS-only.
+- A future promotion that uses framer-motion should pick a preset from `MOTION_TRANSITIONS` and gate it with `usePrefersReducedMotion`.
+
+## Accessibility
+
+**Roles:**
+
+- `spinbutton` is the implied role for the inner input, paired with the stepper buttons. The component does not set `role="spinbutton"` explicitly; the `<input type="text" inputMode="decimal">` does not carry a role, and the buttons next to it act as the up/down affordances.
+- The stepper buttons are `<button type="button">` with `aria-label="Increase value"` and `aria-label="Decrease value"` respectively.
+
+**Keyboard:**
+
+| Key | Action |
+|---|---|
+| `Tab` | Moves focus to the inner input, then to the step-up button, then to the step-down button, then out. The stepper buttons are reachable in tab order. |
+| `Enter`, `Space` | Activates the focused stepper button. |
+| `↑`, `↓` | The component does not implement native arrow-key stepping on the input. Consumers that need that behavior should wrap the component in a spinbutton pattern. |
+| Type `-` | Treated as a transient input; `onChange` fires with `undefined`. |
+| Type digits and `.` | Parsed via `parseFloat`; invalid input does not call `onChange`. |
+
+**Focus:**
+
+- Visible focus ring is owned by the shell via the `dsx-input-shell` rule in `baseInput.css` (border color + `var(--dsx-shadow-focus-ring)`). The inner input is `outline: none` because focus is delegated to the shell.
+
+**Reduced motion:**
+
+- The component does not currently gate motion at runtime. The CSS transitions honor the global `prefers-reduced-motion` media query.
+
+**Color and meaning:**
+
+- Disabled state is communicated by both the disabled attribute and the `var(--dsx-opacity-disabled)` fade on the stepper buttons.
+- Min and max bounds are communicated by the disabled state of the corresponding stepper button at the boundary.
+
+**Naming:**
+
+- The inner input has no implicit label. Consumers must supply `aria-label` (or wire a visible `<label>` via `htmlFor`). The stepper buttons always have their `aria-label`.
+
+## Playground demo spec
+
+The demo file at `demo_path` exposes the component to the playground. The playground lives at `apps/playground/app/` (Next.js app router, no per-component routes today). The `demo_path` recorded here is the current playground root; the spec assumes a single shared page that renders all components. Per-component routes are an aspirational target and not yet present in the repo.
+
+**Default story:**
+
+- Renders `NumberInput` with `aria-label="Quantity"`. Asserts the inner input has `inputMode="decimal"` and an empty value.
+
+**Variant story** (one per variant and size):
+
+- Renders the component with `variant="surface"`, `variant="classic"`, and `variant="ghost"`. Asserts the matching `data-variant` attribute and the corresponding CSS rules.
+- Renders with `size="sm"`, `size="md"`, and `size="lg"`. Asserts the matching `data-size` attribute and shell min-height override.
+
+**State story:**
+
+- Renders the component with `defaultValue={5}`. Clicks the up button and asserts the value becomes `6`; clicks the down button twice and asserts the value becomes `4`.
+- Renders the component with `defaultValue={0}` and `min={0}`. Asserts the down button is disabled.
+- Renders the component with `defaultValue={10}` and `max={10}`. Asserts the up button is disabled.
+
+**Composition story** (for `asChild`):
+
+- Renders the component with `asChild` wrapping a custom input element. Asserts the inner input is the consumer's element while the root and stepper remain on the `<div>` shell.
+
+**Token story:**
+
+- Renders inside a `Theme` wrapper with `accentColor="amber"`, `accentColor="silver"`, and `accentColor="bronze"`. Asserts the focus border color tracks the current `primary` token.
+
+**A11y story:**
+
+- Uses `vitest-axe` against the rendered default NumberInput. Asserts the stepper buttons have accessible names and the input has an accessible name via `aria-label`.
+
+**Props exposed in the playground controls:**
+
+| Prop | Control | Default |
+|---|---|---|
+| `variant` | select | `surface` |
+| `size` | select | `md` |
+| `radius` | select | (none) |
+| `min` | number | (empty) |
+| `max` | number | (empty) |
+| `step` | number | `1` |
+| `defaultValue` | number | (empty) |
+| `asChild` | boolean | `false` |
+| `disabled` | boolean | `false` |
+
+## Wiring notes
+
+**Composes from:**
+
+- `Input`: visual treatment is reused through the `dsx-input-shell` class from `src/_internal/baseInput.css`. The TSX does not import the `Input` component; the shell is a CSS contract, not a React composition.
+- `IconButton`: the stepper buttons are native `<button>` elements styled to match the `IconButton` primitive at the same size. The TSX does not import `IconButton`; the CSS is the alignment contract.
+- `Icon` (lucide-react `ChevronUp`, `ChevronDown`): renders the stepper glyphs.
+- `@radix-ui/react-slot`: enables `asChild` on the inner input.
+
+**Used by:**
+
+- Form rows that need bounded numeric entry, paired with `Field` and `Field.Label` when a label region is required. No DS component currently wraps `NumberInput`; the form pattern is the intended app-side composition.
+
+**State boundaries:**
+
+- Owned by NumberInput: the controlled/uncontrolled value mode, the parsed numeric value, the min/max/step clamping, the disabled state of each stepper button, and the auto-generated `aria-label` for the stepper buttons.
+- Owned by the consumer: the value, `onChange`, `min`, `max`, `step`, the accessible name on the inner input, and the form-row layout (label, description, error) that wraps the component.
+
+**Boundary rules:**
+
+- App-owned data: the persisted value, validation rules beyond min and max, and the surrounding form context.
+- DS-owned visuals: token bindings, the `dsx-number-input` and shell classes, the `data-size`, `data-variant`, and `data-radius` attributes, and the stepper `aria-label` strings.
+- The component does not own a `Field` integration. Wrap in `Field.Root` (or the existing `TextField` composite) at the app level for label, description, and error wiring.
+
+## Penpot build recipe
+
+> Optional. Penpot is a visual reference, not a code authority. Keep this section when the component has a published Penpot asset, or when the spec needs to call out a visual decision the package does not encode. Skip the section when the component is utility or layout-primitive; the package code is the only authority.
+
+The package does not yet publish a Penpot asset for NumberInput. Recipe is visual reference only and tracks the CSS contract.
+
+### Root board
+
+- **Name**: `Components / NumberInput`.
+- **Dimensions**: `240 × 40` (md), `200 × 32` (sm), `280 × 48` (lg).
+- **Layout**: `Flex` (row).
+- **Sizing**: `horizontalSizing = 'fix'`, `verticalSizing = 'fix'`.
+
+### Layer tree
+
+```
+<Root Board: NumberInput / md>
+  ├── <Frame: input shell>
+  │   └── <Text: input value (default empty)>
+  └── <Frame: stepper column>
+      ├── <Button: step up (ChevronUp)>
+      └── <Button: step down (ChevronDown)>
+```
+
+### Token bindings (Penpot properties)
+
+| Shape | Property | Token | Token type | Penpot property name |
+|---|---|---|---|---|
+| Shell | stroke | `--dsx-color-outline` | Color | `strokes` |
+| Shell | fill | `--dsx-color-surface` | Color | `fills` |
+| Shell | radius | `--dsx-rounded-md` | Radius | `radius` |
+| Shell (focus) | stroke | `--dsx-color-primary` | Color | `strokes` (state) |
+| Shell (focus) | shadow | `--dsx-shadow-focus-ring` | Effect | `shadow` (state) |
+| Shell (classic) | shadow | `--dsx-effect-shadow-1` | Effect | `shadow` (variant) |
+| Shell (ghost) | fill | `transparent` | Color | `fills` (variant) |
+| Stepper column | width | `--dsx-space-lg` | Sizing | `width` |
+| Stepper separator | stroke | `--dsx-color-outline` | Color | `strokes` |
+| Stepper button | fill | `transparent` | Color | `fills` |
+| Stepper button (hover) | fill | `--dsx-effect-hover-layer` | Effect | `fills` (state) |
+| Stepper button (active) | fill | `--dsx-effect-pressed-layer` | Effect | `fills` (state) |
+| Input | typography | `--dsx-typography-body-medium-*` | Typography | `typography` |
+| Input | color | `--dsx-color-on-surface` | Color | `fills` |
+
+### State transformations
+
+| State | Shell stroke | Shell fill | Shell shadow | Stepper button fill |
+|---|---|---|---|---|
+| `default` | `--dsx-color-outline` | `--dsx-color-surface` | none | `transparent` |
+| `hover` | `--dsx-color-outline-variant` | `--dsx-color-surface-hover` | none | `transparent` |
+| `focus` | `--dsx-color-primary` | `--dsx-color-surface` | `--dsx-shadow-focus-ring` | `transparent` |
+| `disabled` | `--dsx-effect-disabled-layer` | `--dsx-effect-disabled-layer` | none | `transparent` (with `--dsx-opacity-disabled` fade) |
+| `classic` | `--dsx-color-outline` | `--dsx-color-surface` | `--dsx-effect-shadow-1` | `transparent` |
+| `ghost` (rest) | `transparent` | `transparent` | none | `transparent` |
+| `ghost` (focus) | `--dsx-color-primary` | `--dsx-color-surface` | `--dsx-shadow-focus-ring` | `transparent` |
+
+### Variant model
+
+- `variant`: `surface`, `classic`, `ghost`. Default `surface`.
+- `size`: `sm`, `md`, `lg`. Default `md`.
+- `radius`: `none`, `sm`, `md`, `lg`, `full`. Default `md` (from the base input shell).
+- Total members: 3 × 3 × 5 = 45.
+
+### Validation checklist
+
+- [ ] Token bindings resolve at the values `DESIGN.md` describes.
+- [ ] Component is promoted to Main Component under `Components`.
+- [ ] `penpotUtils.shapeStructure(board, 3)` matches the expected hierarchy.
+- [ ] Stepper buttons have `aria-label` strings baked in; do not treat the labels as themable in Penpot.