@d4gger/design-system 2.7.0

package/dist/docs/password-input.md

@@ -0,0 +1,351 @@
+---
+title: PasswordInput
+status: canonical
+category: Components
+archetype: primitive
+package_path: packages/d4gger-design-system/src/components/passwordInput/PasswordInput.tsx
+css_path: packages/d4gger-design-system/src/styles/components/password-input.css
+props_path: packages/d4gger-design-system/src/components/passwordInput/passwordInput.props.ts
+test_path: packages/d4gger-design-system/src/test/components/PasswordInput.test.tsx
+demo_path: apps/playground/app/page.tsx
+depends_on:
+  - Input (the inner `<input>` reuses the body-medium typography and the disabled / autofill contract from `baseInput.css`; the runtime does not import the `Input` component, but the visual treatment is aligned with the `Input` shell)
+  - IconButton (the visibility toggle is a native `<button>` styled to match the `IconButton` primitive at the same size; the TSX does not import `IconButton`)
+  - Icon (lucide-react `Eye`, `EyeOff`)
+  - "_internal/baseInput.css (shared placeholder color, disabled cursor, autofill, and the `dsx-input-shell` styling reused on the inner shell)"
+  - Field (form-row wrapper; `PasswordInput` is the intended leaf inside a `Field.Root` for password form rows)
+  - "@radix-ui/react-slot"
+---
+
+# PasswordInput
+
+> 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 password entry control that pairs a token-aligned text input with a visibility toggle. The component owns the `type="password"` / `type="text"` swap, the toggle button's accessible name, and the local density / variant / radius contract; the surrounding form context (label, description, error) is the consumer's job.
+
+## Anatomy & slots
+
+**Parent:** `PasswordInput` (no compound; flat export).
+
+**Slots:**
+
+No slots: flat export. The component renders a single root wrapper that contains an input shell with the input and the visibility toggle. The toggle is a `<button>` rendered as part of the inner layout, not a slot for the consumer to replace. The runtime does not attach subcomponents via `Object.assign`.
+
+**Internal layout (not slots):**
+
+| Element | Class | Notes |
+|---|---|---|
+| Root wrapper (`<div>`) | `dsx-password-input` (plus `dsx-password-input--{sm\|md\|lg}` modifier class, plus `data-radius`, `data-size`, `data-variant`) | Hosts the shell. |
+| Inner shell (`<div>`) | `dsx-input-shell`, `dsx-password-input__shell` | The token-aligned input border, background, and focus contract, reused from `baseInput.css`. |
+| Input (`<input>` or slotted host) | `dsx-password-input__input` | The actual text entry. The element is `<input type="password">` (or `type="text"` when visible) and is the host of `asChild`. `data-slot="password-input"`. |
+| Toggle button (`<button>`) | `dsx-password-input__toggle` | The visibility affordance. `tabIndex={-1}` so the toggle does not interrupt the natural tab order between fields. `data-slot="password-input-toggle"`. |
+| Toggle icon | `dsx-password-input__toggle-icon` | The `Eye` / `EyeOff` glyph. |
+
+The roster's `Parent / Slots` column lists `-` (flat export) for `PasswordInput`, which matches the runtime: there is no `Object.assign` and no `PasswordInput.Root` / `PasswordInput.Toggle` subcomponent.
+
+## Props contract
+
+| Prop | Type | Default | Required | Description | Responsive |
+|---|---|---|---|---|---|
+| `density` | `'sm' \| 'md' \| 'lg'` | `'md'` | no | Control height and inner padding. Writes `data-size="sm"\|"md"\|"lg"` on the root, plus the `dsx-password-input--{value}` modifier class. Note: the prop is named `density`; the attribute is `data-size`. | no |
+| `variant` | `'surface' \| 'classic' \| 'ghost'` | `'surface'` | no | Visual treatment. `'classic'` and `'ghost'` are declared on the prop bag, but the CSS does not currently declare `[data-variant='classic']` or `[data-variant='ghost']` rules; see the Anomalies section. | no |
+| `radius` | `'none' \| 'sm' \| 'md' \| 'lg' \| 'full'` | `undefined` | no | Corner radius override. Writes `data-radius`. The CSS does not currently declare matching `[data-radius='...']` rules. | no |
+| `asChild` | `boolean` | `false` | no | Renders the inner input through `Slot` from `@radix-ui/react-slot`. The outer `<div>` root and the toggle button stay on their default elements. | no |
+| `visibleLabel` | `string` | `'Show password'` | no | Accessible name for the toggle when the input is currently hidden. Surfaced as `aria-label` on the button. | no |
+| `hiddenLabel` | `string` | `'Hide password'` | no | Accessible name for the toggle when the input is currently visible. Surfaced as `aria-label` on the button. | no |
+| `type` | `'password'` (forced) | `'password'` | no | Always `password` (or `text` while the toggle is active). The native HTML attribute is omitted from the prop bag so consumers cannot change it to other input types. | no |
+| `defaultValue` | `string` | `undefined` | no | Standard uncontrolled initial value. | no |
+| `value` | `string` | `undefined` | no | Controlled value. | no |
+| `onChange` | `React.ChangeEventHandler<HTMLInputElement>` | `undefined` | no | Standard change handler. | no |
+| `disabled` | `boolean` | `undefined` | no | Standard disabled attribute; the toggle button visually disables when set. | no |
+| `readOnly` | `boolean` | `undefined` | no | Standard readonly attribute. | no |
+| `placeholder` | `string` | `undefined` | no | Forwarded to the inner input. | no |
+| `autoComplete` | `string` | `undefined` | no | Standard autocomplete attribute. | no |
+| `required` | `boolean` | `undefined` | no | Standard required attribute. | no |
+| `name` | `string` | `undefined` | no | Forwarded to the inner input. | no |
+| `id` | `string` | `undefined` | no | Forwarded to the inner input. | no |
+| `className` | `string` | `undefined` | no | Extra classes appended to `dsx-password-input__input` (the inner input). | no |
+| `style` | `React.CSSProperties` | `undefined` | no | Inline style forwarded to the inner input. | no |
+| `aria-label` | `string` | `undefined` | no | Required for accessibility. The input has no implicit label. | no |
+| `aria-invalid` | `boolean` | `undefined` | no | Standard aria-invalid; consumers wire it from the form validation state. | no |
+
+Rules that apply to this row:
+
+- `PasswordInputProps` extends `Omit<React.ComponentPropsWithoutRef<'input'>, 'type'>` so the prop bag can override the native `type` attribute. The runtime ignores any consumer-supplied `type` and forces `password` (or `text` when visible).
+- `density` is the prop name on the bag, but the runtime writes `data-size`. The modifier class `dsx-password-input--{value}` is added in the TSX, not via `extractProps`, because the prop def has no `className`.
+- `visibleLabel` and `hiddenLabel` are not on the prop bag as `PropDef`s; they are plain fields on `PasswordInputOwnProps` and are forwarded to `extractProps` only for the `asChild` and the other prop-def keys.
+- `tabIndex={-1}` on the toggle button is hard-coded in the TSX; it is not exposed as a prop. The intent is to keep the natural tab order between fields, but apps that need to keep the toggle in the tab order cannot override it without editing the source.
+
+## CSS class contract
+
+**Root class:** `dsx-password-input` (the outer `<div>` wrapper). The inner input is `dsx-password-input__input`.
+
+**Modifier classes** (driven by the TSX's class merging and `data-*` attributes written by the component):
+
+| Attribute | Allowed values | Class | CSS file |
+|---|---|---|---|
+| `data-size` | `sm`, `md`, `lg` | `dsx-password-input--sm`, `dsx-password-input--md`, `dsx-password-input--lg` (applied in TSX, not via `extractProps`); no CSS rule for `[data-size='...']` | `password-input.css` |
+| `data-variant` | `surface`, `classic`, `ghost` | (no CSS rule declared today; reserved) | `password-input.css` |
+| `data-radius` | `none`, `sm`, `md`, `lg`, `full` | (no CSS rule declared today; reserved) | `password-input.css` |
+
+**Slot classes:**
+
+| Slot | Class | CSS file |
+|---|---|---|
+| Root wrapper | `dsx-password-input` | `password-input.css` |
+| Inner shell | `dsx-input-shell`, `dsx-password-input__shell` | `_internal/baseInput.css` (reused) and `password-input.css` |
+| Inner input | `dsx-password-input__input` | `password-input.css` |
+| Toggle button | `dsx-password-input__toggle` | `password-input.css` |
+| Toggle icon | `dsx-password-input__toggle-icon` | `password-input.css` |
+
+**Data slots** (used by QA and audit tooling, not visual):
+
+| Element | `data-slot` |
+|---|---|
+| Inner input | `password-input` |
+| Toggle button | `password-input-toggle` |
+
+**Responsive behavior:**
+
+- The component does not write `@media` rules. None of its prop defs are `responsive: true`. Density and radius are single-value only.
+- The component's CSS file is breakpoint-agnostic.
+
+**Reduced motion:**
+
+- The toggle button transitions `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 inline end | `var(--dsx-space-xl)` | Room for the toggle on the right. |
+| Density `sm` shell min-height | `var(--dsx-density-control-height-sm, var(--dsx-size-lg))` | Small control. |
+| Density `sm` shell padding inline | `var(--dsx-density-control-padding-inline-sm, var(--dsx-space-sm))` | Small inline gutter. |
+| Density `sm` shell padding block | `var(--dsx-density-control-padding-block-sm, var(--dsx-space-xs))` | Small block gutter. |
+| Density `md` shell min-height | `var(--dsx-density-control-height, var(--dsx-size-xl))` | Default control. |
+| Density `md` shell padding inline | `var(--dsx-density-control-padding-inline, var(--dsx-space-md))` | Default inline gutter. |
+| Density `md` shell padding block | `var(--dsx-density-control-padding-block, var(--dsx-space-sm))` | Default block gutter. |
+| Density `lg` shell min-height | `var(--dsx-density-control-height-lg, var(--dsx-size-2xl))` | Large control. |
+| Density `lg` shell padding inline | `var(--dsx-density-control-padding-inline-lg, var(--dsx-space-lg))` | Large inline gutter. |
+| Density `lg` shell padding block | `var(--dsx-density-control-padding-block-lg, var(--dsx-space-md))` | Large block gutter. |
+| Input | (no painted token; the input is borderless, transparent, and uses the inherited shell colors) | The shell owns the visual surface. |
+| Input placeholder color | `var(--dsx-color-on-surface-variant)` | Placeholder text, from `baseInput.css`. |
+| Input disabled text color | `var(--dsx-color-text-disabled)` | Disabled state, from `baseInput.css`. |
+| Toggle button size | `var(--dsx-size-md)` square | Toggle tap target. |
+| Toggle button margin start | `var(--dsx-space-xs)` | Gap between input and toggle. |
+| Toggle button radius | `var(--dsx-rounded-md)` | Rounded affordance. |
+| Toggle button color | `var(--dsx-color-on-surface-variant)` | Resting state. |
+| Toggle button hover background | `var(--dsx-effect-hover-layer)` | Hover surface. |
+| Toggle button hover text | `var(--dsx-color-on-surface)` | Hover text color. |
+| Toggle button active background | `var(--dsx-effect-pressed-layer)` | Active surface. |
+| Toggle button focus shadow | `var(--dsx-shadow-focus-ring)` | Focus ring. |
+| Toggle button disabled opacity | `var(--dsx-opacity-disabled)` | Disabled fade. |
+| Toggle icon size | `var(--dsx-space-md)` square | Icon box. |
+| Shell border | `var(--dsx-border-width-sm)` + `var(--dsx-color-outline)` (via `baseInput.css`) | Default edge. |
+| Shell background | `var(--dsx-color-surface)` (via `baseInput.css`) | Resting surface. |
+| Shell focus border | `var(--dsx-color-primary)` (via `baseInput.css`) | Focus state. |
+| Shell focus shadow | `var(--dsx-shadow-focus-ring)` (via `baseInput.css`) | Focus ring. |
+| Shell hover border | `var(--dsx-color-outline-variant)` (via `baseInput.css`) | Hover state. |
+| Shell hover background | `var(--dsx-color-surface-hover)` (via `baseInput.css`) | Hover state. |
+| Autofill | `var(--dsx-color-surface-field-autofill)` (via `baseInput.css`) | Browser autofill. |
+| Motion | `var(--dsx-motion-duration-fast)` + `var(--dsx-motion-easing-in-out)` | Toggle transitions. |
+
+Rules:
+
+- Tokens come from `DESIGN.md` and the generated `tokens.css`. The only non-token value in `password-input.css` is the `0` padding override on the inner input and the `transparent` background that lets the shell show through.
+- `data-variant` and `data-radius` are written by the runtime and reserved for future CSS hooks; today there are no matching declarations.
+
+## Motion contract
+
+| Region | Token | Default | Reduced |
+|---|---|---|---|
+| Toggle button color and background | `var(--dsx-motion-duration-fast)` + `var(--dsx-motion-easing-in-out)` | Color shift to `var(--dsx-color-on-surface)` plus hover background; pressed background on active | `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:**
+
+- The root is a `<div>`. The input is a standard `<input type="password">` (or `type="text"` while visible).
+- The toggle button is `<button type="button">` with an `aria-label` that flips between `visibleLabel` and `hiddenLabel` based on the visibility state.
+
+**Keyboard:**
+
+| Key | Action |
+|---|---|
+| `Tab` | Moves focus to the input, then out. The toggle button has `tabIndex={-1}` and is skipped in the natural tab order. |
+| `Enter`, `Space` (while toggle is focused) | Toggles visibility. The toggle is not focusable by default; keyboard users that need to toggle must either focus the input and rely on a screen reader, or use the mouse. The `tabIndex={-1}` decision is a known trade-off — see Anomalies. |
+| Type password characters | Entered into the input; standard input behavior. |
+
+**Focus:**
+
+- Visible focus ring on the inner input 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.
+- The toggle button has its own focus ring via `var(--dsx-shadow-focus-ring)`. With `tabIndex={-1}` the toggle is reachable only when scripted focus is moved to it.
+
+**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:**
+
+- Hidden / visible state is communicated by the `Eye` / `EyeOff` glyph and by the `visibleLabel` / `hiddenLabel` `aria-label` strings. Color is not the only signal.
+
+**Naming:**
+
+- The inner input has no implicit label. Consumers must supply `aria-label` (or wire a visible `<label>` via `htmlFor`).
+- The toggle button always has an `aria-label`. The default strings are `Show password` and `Hide password`; consumers that need localized labels pass `visibleLabel` and `hiddenLabel`.
+
+## 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 `PasswordInput` with `aria-label="Password"`. Asserts the input has `type="password"` and the toggle button has `aria-label="Show password"`.
+
+**Variant story** (one per density):
+
+- Renders with `density="sm"`, `density="md"`, and `density="lg"`. Asserts the matching `dsx-password-input--{value}` modifier class on the root and the `data-size` attribute.
+- Renders with `variant="surface"`, `variant="classic"`, and `variant="ghost"`. Asserts the `data-variant` attribute; visual treatment may be identical today — see Anomalies.
+
+**State story:**
+
+- Clicks the toggle. Asserts the input's `type` flips to `text` and the toggle's `aria-label` flips to `Hide password`.
+- Clicks the toggle a second time. Asserts the input's `type` flips back to `password` and the toggle's `aria-label` flips back to `Show password`.
+- Renders with `disabled={true}`. Asserts the input is disabled and the toggle button is visually disabled (opacity, no pointer events).
+- Renders with `visibleLabel="Reveal"` and `hiddenLabel="Conceal"`. Asserts the toggle button starts with `aria-label="Reveal"`, then `"Conceal"` after one click, then `"Reveal"` again.
+
+**Composition story** (for `asChild`):
+
+- Renders the component with `asChild` wrapping a custom input element. Asserts the input is the consumer's element while the toggle button stays on the standard `<button>` element.
+
+**Token story:**
+
+- Renders inside a `Theme` wrapper with `accentColor="amber"`, `accentColor="silver"`, and `accentColor="bronze"`. Asserts the focus border color tracks `var(--dsx-color-primary)` (which is theme-aware) across all three accent settings.
+
+**A11y story:**
+
+- Uses `vitest-axe` against the rendered default PasswordInput. Asserts the input has an accessible name, the toggle button has an accessible name, and the component has no axe violations.
+
+**Props exposed in the playground controls:**
+
+| Prop | Control | Default |
+|---|---|---|
+| `density` | select | `md` |
+| `variant` | select | `surface` |
+| `radius` | select | (none) |
+| `disabled` | boolean | `false` |
+| `visibleLabel` | text | `Show password` |
+| `hiddenLabel` | text | `Hide password` |
+| `asChild` | boolean | `false` |
+
+## Wiring notes
+
+**Composes from:**
+
+- `Input`: the inner input reuses the body-medium typography and the disabled / autofill contract from `baseInput.css`. The TSX does not import the `Input` component; the shell and placeholder rules are shared via the CSS import.
+- `IconButton`: the toggle button is a native `<button>` 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 `Eye`, `EyeOff`): renders the visibility glyphs.
+- `_internal/baseInput.css`: shared shell, border, hover, focus, disabled, placeholder, and autofill contract.
+- `@radix-ui/react-slot`: enables `asChild` on the inner input.
+- `Field` (consumer pattern, not a runtime import): the intended app-level wrapper for password form rows. The component does not own a `Field` integration; the consumer composes `Field.Root` around `PasswordInput` and supplies label, description, and error wiring.
+
+**Used by:**
+
+- App-level auth flows: sign-in, sign-up, password reset, account settings. No DS component currently wraps `PasswordInput`; the auth form pattern is the intended app-level composition.
+
+**State boundaries:**
+
+- Owned by PasswordInput: the visibility state (`isVisible`), the `type` swap, the toggle button's `aria-label` reflection, and the disabled visual state of the toggle.
+- Owned by the consumer: the value, `onChange`, the `visibleLabel` / `hiddenLabel` strings, the disabled state, the host element when `asChild` is set, and the form-row layout (label, description, error) that wraps the component.
+
+**Boundary rules:**
+
+- App-owned data: the persisted password value, the validation rules, the auth submission semantics, and the surrounding form context.
+- DS-owned visuals: token bindings, the `dsx-password-input` and shell classes, the `data-size`, `data-variant`, and `data-radius` attributes, the toggle's `aria-label` template, and the `Eye` / `EyeOff` glyph swap.
+
+## Anomalies
+
+- **`density` prop writes `data-size`, not `data-density`.** The prop is named `density` on the bag, but the runtime writes `data-size="sm"\|"md"\|"lg"`. The CSS consumes the modifier class `dsx-password-input--{value}` (added in the TSX), not the `data-size` attribute. The naming split is intentional in the source but the attribute name is misleading for consumers that inspect the DOM. A future revision should align the attribute name with the prop name (or rename the prop to `size`).
+- **`data-variant` is not CSS-backed.** `variant` is declared on the prop bag with `surface`, `classic`, and `ghost` values, but `password-input.css` has no `[data-variant='...']` rules. All three variants render with the same shell treatment today; the contract is reserved.
+- **`data-radius` is not CSS-backed.** The attribute is written by the runtime and listed on the prop bag, but `password-input.css` has no `[data-radius='...']` rule. The shell uses the default `var(--dsx-rounded-md)` from `baseInput.css`. The contract is reserved.
+- **Toggle button is not in the tab order.** `tabIndex={-1}` is hard-coded in the TSX. The intent is to keep the natural tab order between fields, but keyboard users that need to toggle visibility (and screen reader users that reach the toggle) cannot focus the button without a script. A future revision should expose `toggleTabIndex` (or remove the `tabIndex={-1}`) so the toggle is reachable by default.
+- **Roster reconciled to primitive.** The roster originally listed `PasswordInput` as `composite` with `Composed From: Input, IconButton`. The runtime is a single forwardRef without `Object.assign`; the inner input and toggle are implementation details, not named slots. The roster was updated to `primitive` and the `Composed From` column was cleared. The spec follows that classification.
+- **The roster's `Composed From` column lists `Input` and `IconButton`, but the TSX does not import either.** The alignment is via shared CSS classes and tokens, not via React composition. The `depends_on` block at the top of this spec records both relationships.
+
+## 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 PasswordInput. Recipe is visual reference only and tracks the CSS contract.
+
+### Root board
+
+- **Name**: `Components / PasswordInput`.
+- **Dimensions**: `240 × 40` (md), `200 × 32` (sm), `280 × 48` (lg).
+- **Layout**: `Flex` (row).
+- **Sizing**: `horizontalSizing = 'fix'`, `verticalSizing = 'fix'`.
+
+### Layer tree
+
+```
+<Root Board: PasswordInput / md>
+  ├── <Frame: input shell>
+  │   └── <Text: input value (masked or visible)>
+  └── <Button: visibility toggle (Eye / EyeOff)>
+```
+
+### 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 (hover) | stroke | `--dsx-color-outline-variant` | Color | `strokes` (state) |
+| Shell (hover) | fill | `--dsx-color-surface-hover` | Color | `fills` (state) |
+| Toggle | size | `--dsx-size-md` square | Sizing | `size` |
+| Toggle | radius | `--dsx-rounded-md` | Radius | `radius` |
+| Toggle | color | `--dsx-color-on-surface-variant` | Color | `fills` |
+| Toggle (hover) | fill | `--dsx-effect-hover-layer` | Effect | `fills` (state) |
+| Toggle (active) | fill | `--dsx-effect-pressed-layer` | Effect | `fills` (state) |
+| Toggle (focus) | shadow | `--dsx-shadow-focus-ring` | Effect | `shadow` (state) |
+| Input | text | `--dsx-color-on-surface` | Color | `fills` |
+| Input | placeholder | `--dsx-color-on-surface-variant` | Color | `fills` (state) |
+
+### State transformations
+
+| State | Shell stroke | Shell fill | Toggle fill | Toggle icon |
+|---|---|---|---|---|
+| `default` (hidden) | `--dsx-color-outline` | `--dsx-color-surface` | `transparent` | `Eye` |
+| `hover` (shell) | `--dsx-color-outline-variant` | `--dsx-color-surface-hover` | `transparent` | `Eye` |
+| `focus` (input) | `--dsx-color-primary` | `--dsx-color-surface` | `transparent` | `Eye` |
+| `visible` (default) | `--dsx-color-outline` | `--dsx-color-surface` | `transparent` | `EyeOff` |
+| `disabled` | `--dsx-effect-disabled-layer` | `--dsx-effect-disabled-layer` | `transparent` (with `--dsx-opacity-disabled` fade) | `Eye` |
+
+### Variant model
+
+- `density`: `sm`, `md`, `lg`. Default `md`.
+- `variant`: `surface`, `classic`, `ghost`. Default `surface`. (See Anomalies — no visual change today.)
+- `radius`: `none`, `sm`, `md`, `lg`, `full`. Default `md` (from the 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.
+- [ ] Toggle `aria-label` strings (`visibleLabel` / `hiddenLabel` defaults) are baked in; do not treat them as themable in Penpot.
+- [ ] `data-variant` and `data-radius` slots exist in Penpot but resolve to no visual change today; document the reservations.
+- [ ] `tabIndex={-1}` on the toggle is documented as a known trade-off; the spec marks it as a future revision target.

package/dist/docs/pills.md

@@ -0,0 +1,252 @@
+---
+title: Pills
+status: canonical
+category: Components
+archetype: composite
+package_path: packages/d4gger-design-system/src/components/pills/Pills.tsx
+css_path: packages/d4gger-design-system/src/styles/components/pills.css
+props_path: packages/d4gger-design-system/src/components/pills/pills.props.ts
+test_path: packages/d4gger-design-system/src/test/components/Pills.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:
+  - Badge
+  - Button
+  - Icon
+---
+
+# Pills
+
+> Source of truth: the package source at `package_path`. The spec file mirrors the source. Edits to the spec must land in the source in the same change, or the QA flags will fire.
+
+## Purpose
+
+A compact cluster of selectable or status pills rendered as a horizontal flex list. Use Pills for filter chips, tag clusters, segmented status indicators, and removable tags. For a single label surface, use `Badge`. For mutually exclusive options rendered as a segmented control, use `SegmentedControl` or `ToggleGroup`.
+
+## Anatomy & slots
+
+**Parent:** `Pills` (alias of `PillsRoot`).
+
+**Slots:**
+
+| Slot | Element | Renders | Notes |
+|---|---|---|---|
+| `Pills` (root) | `<ul>` (or `Slot` host) | List host + class | Renders as a semantic `<ul>` with `list-style: none`. Writes `dsx-pills`, `data-variant`, `data-size`, `data-radius`, and `data-accent-color`. |
+| `Pill` (per-item) | `<li>` (or `Slot` host) | List item + class | A single pill. Writes `dsx-pill` plus a variant modifier class and a size modifier class. When `removable={true}`, the pill appends a `<button aria-label="Remove">` with an `Icon name="x"`. |
+
+The compound is split across two prop-def bags: `pillsPropDefs` for the root and `pillPropDefs` for the per-item pill. The runtime destructures `onRemove` from the per-item props before running `extractProps` so it does not get forwarded to the host element.
+
+## Props contract
+
+**Root props:**
+
+| Prop | Type | Default | Required | Description | Responsive |
+|---|---|---|---|---|---|
+| `variant` | `'solid' \| 'soft' \| 'outline'` | `'solid'` | no | Cluster variant. The root's `data-variant` is informational; the visible variant is set per `Pill` via its own `variant` prop. | no |
+| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | no | Cluster size. The root's `data-size` is informational; the visible size is set per `Pill` via its own `size` prop. | no |
+| `color` | `string` | `undefined` | no | Free-form accent override; writes `data-accent-color` when provided. | no |
+| `radius` | `'none' \| 'sm' \| 'md' \| 'lg' \| 'full'` | `undefined` | no | Corner radius token; writes `data-radius` when provided. The default is the CSS's `var(--dsx-rounded-full)`. | 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-pills`. | no |
+
+**Pill (per-item) props:**
+
+| Prop | Type | Default | Required | Description | Responsive |
+|---|---|---|---|---|---|
+| `variant` | `'default' \| 'secondary' \| 'destructive' \| 'outline' \| 'ghost' \| 'link'` | `'default'` | no | Per-pill variant. Emits one of the modifier classes `dsx-pill--default`, `dsx-pill--secondary`, `dsx-pill--destructive`, `dsx-pill--outline`, `dsx-pill--ghost`, `dsx-pill--link`. | no |
+| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | no | Per-pill size. Emits one of the modifier classes `dsx-pill--sm`, `dsx-pill--md`, `dsx-pill--lg`. | no |
+| `removable` | `boolean` | `false` | no | When `true`, renders a trailing remove button with `aria-label="Remove"`. | no |
+| `onRemove` | `() => void` | `undefined` | no | Click handler for the remove button. Only meaningful when `removable={true}`. | no |
+| `asChild` | `boolean` | `false` | no | Renders the pill through `Slot`; consumer supplies the host element. | no |
+| `className` | `string` | `undefined` | no | Extra classes appended to `dsx-pill`. | no |
+
+Each pill also accepts the standard HTML attributes for its host element. The `color` attribute is omitted from both root and pill props (the root's `color` writes `data-accent-color`; the per-pill `color` is not part of the contract).
+
+## CSS class contract
+
+**Root class:** `dsx-pills`
+
+**Modifier classes** (driven by `data-*` attributes written by the component):
+
+| Attribute | Allowed values | Class | CSS file |
+|---|---|---|---|
+| `data-variant` | `solid`, `soft`, `outline` | (no rule in `pills.css`; attribute is informational) | n/a |
+| `data-size` | `sm`, `md`, `lg` | (no rule in `pills.css`; attribute is informational) | n/a |
+| `data-accent-color` | any string | (no rule in `pills.css`; attribute is forwarded) | n/a |
+| `data-radius` | `none`, `sm`, `md`, `lg`, `full` | (no rule in `pills.css`; attribute is forwarded) | n/a |
+
+**Pill modifier classes** (driven by the per-pill `variant` and `size` prop defs):
+
+| Variant | Class | CSS file |
+|---|---|---|
+| `default` | `dsx-pill--default` | `pills.css` |
+| `secondary` | `dsx-pill--secondary` | `pills.css` |
+| `destructive` | `dsx-pill--destructive` | `pills.css` |
+| `outline` | `dsx-pill--outline` | `pills.css` |
+| `ghost` | `dsx-pill--ghost` | `pills.css` |
+| `link` | `dsx-pill--link` | `pills.css` |
+
+| Size | Class | CSS file |
+|---|---|---|
+| `sm` | `dsx-pill--sm` | `pills.css` |
+| `md` | `dsx-pill--md` | `pills.css` |
+| `lg` | `dsx-pill--lg` | `pills.css` |
+
+**Slot classes:**
+
+| Slot | Class | CSS file |
+|---|---|---|
+| `Pills` (root) | `dsx-pills` | `pills.css` |
+| `Pill` (per-item) | `dsx-pill` | `pills.css` |
+| Remove button (internal) | `dsx-pill__remove` | `pills.css` |
+
+**Responsive behavior:**
+
+- The component does not write `@media` rules. `size`, `variant`, `color`, and `radius` are single-value only.
+
+**Reduced motion:**
+
+- The component is static. No motion is applied. The only interactive element (the remove button) inherits standard browser focus and hover behavior.
+
+## Token mapping
+
+Every CSS value the component paints is a `var(--dsx-*)` token.
+
+| Property | Token | Role |
+|---|---|---|
+| Root display | `flex` (row, wrap) | Layout for the pill cluster |
+| Root gap | `var(--dsx-space-sm)` | Space between pills |
+| Root list-style | `none` | Strip bullet markers |
+| Pill display | `inline-flex` (row, center) | Layout for pill content + remove button |
+| Pill gap | `var(--dsx-space-xs)` | Space between pill content and remove button |
+| Pill cursor | `default` | Non-interactive cursor |
+| Pill border-radius | `var(--dsx-rounded-full)` | Default roundness |
+| Pill type ramp | `var(--dsx-typography-label-medium-*)` | Pill text scale |
+| Pill padding (sm) | `var(--dsx-space-xs) var(--dsx-space-sm)` | Small pill padding |
+| Pill padding (md) | `var(--dsx-space-sm) var(--dsx-space-md)` | Medium pill padding |
+| Pill padding (lg) | `var(--dsx-space-md) var(--dsx-space-lg)` | Large pill padding |
+| Default surface | `var(--dsx-color-surface-raised)` | Default pill background |
+| Default text | `var(--dsx-color-on-surface)` | Default pill text color |
+| Default border | `var(--dsx-border-width-sm) solid var(--dsx-color-outline-variant)` | Default pill border |
+| Secondary surface | `var(--dsx-color-surface)` | Secondary pill background |
+| Secondary text | `var(--dsx-color-on-surface-variant)` | Secondary pill text color |
+| Secondary border | `var(--dsx-border-width-sm) solid var(--dsx-color-outline-variant)` | Secondary pill border |
+| Destructive surface | `var(--dsx-color-error)` | Destructive pill background |
+| Destructive text | `var(--dsx-color-on-error)` | Destructive pill text color |
+| Destructive border | `var(--dsx-border-width-sm) solid var(--dsx-color-error)` | Destructive pill border |
+| Outline background | `transparent` | Outline pill background |
+| Outline text | `var(--dsx-color-on-surface)` | Outline pill text color |
+| Outline border | `var(--dsx-border-width-sm) solid var(--dsx-color-outline)` | Outline pill border |
+| Ghost background | `transparent` | Ghost pill background |
+| Ghost text | `var(--dsx-color-on-surface)` | Ghost pill text color |
+| Ghost border | `var(--dsx-border-width-sm) solid transparent` | Ghost pill border |
+| Ghost hover | `var(--dsx-effect-hover-ghost)` | Ghost pill hover background |
+| Link background | `transparent` | Link pill background |
+| Link text | `var(--dsx-color-primary)` | Link pill text color |
+| Link border | `var(--dsx-border-width-sm) solid transparent` | Link pill border |
+| Link cursor | `pointer` | Link pill pointer cursor |
+| Link hover | `text-decoration: underline` | Link pill hover treatment |
+| Remove button cursor | `pointer` | Remove button pointer cursor |
+| Remove button opacity | `0.6` (default), `1` (hover) | Remove button visual emphasis |
+
+## Motion contract
+
+| Region | Token | Default | Reduced |
+|---|---|---|---|
+| (none) | none | none | n/a |
+
+The component is static. Hover and focus states are instant.
+
+## Accessibility
+
+**Roles:**
+
+- The root renders as a `<ul>`. Each pill renders as a `<li>`. The compound is a semantic list.
+
+**Keyboard:**
+
+| Key | Action |
+|---|---|
+| `Tab` | Moves focus to the next focusable element (typically a remove button or an action inside the pill). |
+| `Enter`, `Space` | Activates the focused control (typically the remove button). |
+
+**Focus:**
+
+- The root is not focusable. The remove button and any other focusable element inside the pill handles its own focus ring.
+
+**Reduced motion:**
+
+- No motion is applied.
+
+**Color and meaning:**
+
+- Variant tone is decorative. The pill's `children` carry the meaning. Consumers should not rely on pill color alone to communicate state; pair it with text.
+
+**Naming:**
+
+- The pill's `children` are the accessible name. The remove button has a hard-coded `aria-label="Remove"`; consumers that need a contextual label should override the `aria-label` via the standard HTML attribute spread.
+
+## Playground demo spec
+
+**Default story:**
+
+- Renders a `Pills` cluster with three pills. Asserts the root is a `<ul>` with `list-style: none` and the pills are `<li>` elements.
+
+**Variant story:**
+
+- Renders a `Pills` cluster with one pill per variant: `default`, `secondary`, `destructive`, `outline`, `ghost`, `link`. Asserts each modifier class is present.
+
+**Size story:**
+
+- Renders a `Pills` cluster with one pill per size: `sm`, `md`, `lg`. Asserts each modifier class is present.
+
+**State story:**
+
+- Renders a `Pills` cluster with a removable pill and an `onRemove` callback. Asserts the `dsx-pill__remove` button is present with `aria-label="Remove"` and that clicking it triggers the callback.
+
+**Composition story:**
+
+- Renders a `Pills` cluster with a mix of variants and sizes. Asserts the modifier classes are present on the correct pills.
+
+**Token story:**
+
+- Renders inside a `Theme` wrapper with `accentColor="silver"` and `accentColor="bronze"`. Pills with a `color` prop track `data-accent-color`; the story asserts the destructive and link pills do not flip color because they read from the error and primary palettes.
+
+**A11y story:**
+
+- Uses `vitest-axe` against the rendered default story. Asserts no axe violations.
+
+**Props exposed in the playground controls:**
+
+| Prop | Control | Default |
+|---|---|---|
+| `variant` (root) | select | `solid` |
+| `size` (root) | select | `md` |
+| `color` (root) | text | (empty) |
+| `radius` (root) | select | `full` |
+| `variant` (pill) | select | `default` |
+| `size` (pill) | select | `md` |
+| `removable` (pill) | boolean | `false` |
+
+## Wiring notes
+
+**Composes from:**
+
+- `Badge`, `Button`, `Icon`: Pills borrows visual intent from `Badge` for the cluster and per-pill surfaces, and from `Button` for the link and ghost variants. The remove button uses the `Icon` for the trailing `x`.
+- `@radix-ui/react-slot`: enables `asChild` on the root and on each `Pill`.
+
+**Used by:**
+
+- `DataTable` filter chips: the toolbar uses `Pills` for active filters.
+- App-level filter bars, tag clusters, and status pill rows.
+
+**State boundaries:**
+
+- Owned by Pills: the root and per-pill variant / size modifier classes, the `data-accent-color` and `data-radius` attributes on the root, the `dsx-pills` and `dsx-pill` classes, and the remove button rendering.
+- Owned by the consumer: the pill content, the per-pill `variant` and `size`, the `onRemove` callback, the root `color` and `radius` overrides, and the surrounding list semantics.
+
+**Boundary rules:**
+
+- App-owned data: the cluster items, the per-pill labels, the selection state (for filter chips), and the dismiss callbacks.
+- DS-owned visuals: token bindings, the modifier classes, the per-pill surface palette, and the remove button.