@karmo-co/drift-kit-reference 0.0.0-stage → 23.4.0

package/manifest/components/logo.md

@@ -0,0 +1,38 @@
+# Logo (`logo`)
+
+The brand mark, as a symbol or with its wordmark, in three colourways.
+
+
+## Anatomy (HTML)
+
+```text
+span.dk-component-logo[data-brand]?[data-lockup="symbol|symbol-text"]?[data-mode="reverse"]?[data-size]?[role="img"][aria-label]
+  (the vectors are drawn by the runtime)
+```
+
+## Attributes
+
+| Attribute | Values the stylesheet styles |
+|---|---|
+| `data-mode` | `neutral`, `reverse` |
+| `data-part` | `primary`, `secondary` |
+| `data-size` | `large`, `medium`, `small`, `xlarge` |
+
+## React
+
+```tsx
+import { Logo } from '@karmo-co/drift-kit/react';
+```
+
+| Prop | Type | Notes |
+|---|---|---|
+| `lockup` | `'symbol' \| 'symbol-text'` |  |
+| `mode` | `'default' \| 'reverse' \| 'neutral'` |  |
+| `size` | `'small' \| 'medium' \| 'large' \| 'xlarge'` |  |
+| `brand` | `LogoBrand` | The runtime reads the nearest data-brand; React cannot, so it is a prop. |
+| `label` | `string` | The accessible name. Defaults to the brand's name. |
+| `decorative` | `boolean` | Hidden from assistive tech, for a logo beside the brand name in text. |
+
+## Component tokens
+
+`--dk-component-logo-default-secondary`, `--dk-component-logo-default-primary`, `--dk-component-logo-reverse-secondary`, `--dk-component-logo-reverse-primary`, `--dk-component-logo-neutral-secondary`, `--dk-component-logo-neutral-primary`, `--dk-component-logo-small-height`, `--dk-component-logo-medium-height`, `--dk-component-logo-large-height`, `--dk-component-logo-xlarge-height`

package/manifest/components/modal.md

@@ -0,0 +1,53 @@
+# Modal (`modal`)
+
+A dialog on a backdrop, and a bottom sheet on a phone. Focus trap, Escape, scroll lock and focus return included.
+
+
+## Anatomy (HTML)
+
+```text
+div.dk-component-modal[hidden][data-sheet][data-sheet-open][data-closing]
+  div.dk-component-modal__backdrop
+  div.dk-component-modal__box[data-size][role=dialog][aria-modal=true]
+    div.dk-component-modal__header
+      span.dk-component-modal__icon > svg
+      h2.dk-component-modal__title
+      button.dk-component-icon-button[aria-label]
+    div.dk-component-modal__body
+    div.dk-component-modal__footer
+```
+
+## Attributes
+
+| Attribute | Values the stylesheet styles |
+|---|---|
+| `data-closing` | (present or absent) |
+| `data-sheet` | `always`, `never` |
+| `data-sheet-open` | (present or absent) |
+| `data-size` | `large`, `small`, `xlarge` |
+
+## React
+
+```tsx
+import { Modal } from '@karmo-co/drift-kit/react';
+```
+
+| Prop | Type | Notes |
+|---|---|---|
+| `open` (required) | `boolean` | Controlled: true shows it, false plays its exit. |
+| `onClose` | `() => void` | Called once when the dialog closes ITSELF (Escape, the cross, the backdrop), after its exit, so the parent can set open to false. Not called when the parent closed it. |
+| `size` | `'small' \| 'medium' \| 'large' \| 'xlarge'` |  |
+| `sheet` | `'auto' \| 'always' \| 'never'` |  |
+| `dismissible` | `boolean` | false: it has to be answered; Escape and the backdrop are both refused. |
+| `backdropDismiss` | `boolean` | false keeps Escape and refuses a click beside it, for a form. |
+| `initialFocus` | `string` | A selector inside the box to focus on open. |
+| `title` | `ReactNode` |  |
+| `icon` | `ReactNode` |  |
+| `footer` | `ReactNode` |  |
+| `showClose` | `boolean` | The header's cross. On unless dismissible is false. |
+| `closeLabel` | `string` |  |
+| `children` | `ReactNode` |  |
+
+## Component tokens
+
+`--dk-component-modal-small-width`, `--dk-component-modal-width`, `--dk-component-modal-large-width`, `--dk-component-modal-xlarge-width`, `--dk-component-modal-radius`, `--dk-component-modal-surface`, `--dk-component-modal-border`, `--dk-component-modal-border-width`, `--dk-component-modal-shadow`, `--dk-component-modal-inset`, `--dk-component-modal-max-height`, `--dk-component-modal-backdrop`, `--dk-component-modal-padding-inline`, `--dk-component-modal-header-padding-block`, `--dk-component-modal-body-padding-block`, `--dk-component-modal-footer-padding-block`, `--dk-component-modal-body-gap`, `--dk-component-modal-footer-gap`, `--dk-component-modal-header-gap`, `--dk-component-modal-divider`, `--dk-component-modal-title-font-size`, `--dk-component-modal-title-line-height`, `--dk-component-modal-title-font-weight`, `--dk-component-modal-title-color`, `--dk-component-modal-icon-size`, `--dk-component-modal-icon-color`, `--dk-component-modal-sheet-max-height`, `--dk-component-modal-sheet-max-width`, `--dk-component-modal-sheet-radius`, `--dk-component-modal-sheet-action-height`, `--dk-component-modal-sheet-action-min`, `--dk-component-modal-enter-duration`, `--dk-component-modal-exit-duration`, `--dk-component-modal-enter-easing`, `--dk-component-modal-exit-easing`, `--dk-component-modal-enter-travel`

package/manifest/components/pagination.md

@@ -0,0 +1,54 @@
+# Pagination (`pagination`)
+
+Where a long list is in pages, and the way to the others: a page list between two arrows, with an optional count of what is showing and a rows select.
+
+
+## Anatomy (HTML)
+
+```text
+nav.dk-component-pagination[data-page][data-pages|data-total][data-page-size]
+                           [data-size][data-href]           (aria-label)
+  p.dk-component-pagination__summary          (optional, filled by the runtime)
+  div.dk-component-pagination__rows           (optional)
+    span.dk-component-pagination__rows-label
+    div.dk-component-select[data-size]        (a kit Select: 20, 50, 100)
+  div.dk-component-pagination__pages          (drawn by the runtime)
+    button.dk-component-icon-button.__prev    (ghost, the pagination's size)
+    ol.dk-component-pagination__list
+      li > button.__page[aria-current="page"] (or a.__page in link mode)
+      li > span.__gap                         (aria-hidden)
+    span.dk-component-pagination__status      ("Page 3 of 12", phone only)
+    button.dk-component-icon-button.__next
+```
+
+## Attributes
+
+| Attribute | Values the stylesheet styles |
+|---|---|
+| `data-pseudo-class` | `active`, `focus`, `hover` |
+| `data-size` | `large`, `medium`, `small` |
+
+## React
+
+```tsx
+import { Pagination } from '@karmo-co/drift-kit/react';
+```
+
+| Prop | Type | Notes |
+|---|---|---|
+| `page` (required) | `number` | The current page, from 1. Controlled: it shows what you pass. |
+| `pages` | `number` | The page count. Or pass total and pageSize, and it is worked out. |
+| `total` | `number` |  |
+| `pageSize` | `number` |  |
+| `onPageChange` | `(page: number) => void` | A button was pressed for another page. |
+| `pageSizes` | `number[]` | The choices in the rows select, which shows when onPageSizeChange is passed. [20, 50, 100] when absent. |
+| `onPageSizeChange` | `(pageSize: number, page: number) => void` | The new size, and the page that keeps the first row on screen: row 81 was first on page 5 of 20s, and is on page 2 of 50s. |
+| `rowsLabel` | `ReactNode` | The words beside the rows select. |
+| `summary` | `boolean` | "Showing 41–60 of 234". On when total and pageSize are known. |
+| `href` | `(page: number) => string` | Pages as links: the URL for page n. The page loads the next one itself. |
+| `size` | `'small' \| 'medium' \| 'large'` | medium when absent. The arrows take the same size. |
+| `messages` | `Partial<PaginationMessages>` |  |
+
+## Component tokens
+
+`--dk-component-pagination-small-padding`, `--dk-component-pagination-small-line-height`, `--dk-component-pagination-small-font-size`, `--dk-component-pagination-small-border-radius`, `--dk-component-pagination-padding`, `--dk-component-pagination-line-height`, `--dk-component-pagination-font-size`, `--dk-component-pagination-border-radius`, `--dk-component-pagination-large-padding`, `--dk-component-pagination-large-line-height`, `--dk-component-pagination-large-font-size`, `--dk-component-pagination-large-border-radius`, `--dk-component-pagination-gap`, `--dk-component-pagination-section-gap`, `--dk-component-pagination-font-family`, `--dk-component-pagination-page-font-weight`, `--dk-component-pagination-page-text`, `--dk-component-pagination-page-text-hover`, `--dk-component-pagination-page-surface-hover`, `--dk-component-pagination-page-surface-active`, `--dk-component-pagination-press-scale`, `--dk-component-pagination-current-surface`, `--dk-component-pagination-current-surface-hover`, `--dk-component-pagination-current-surface-active`, `--dk-component-pagination-current-text`, `--dk-component-pagination-current-font-weight`, `--dk-component-pagination-gap-text`, `--dk-component-pagination-summary-text`, `--dk-component-pagination-summary-font-size`, `--dk-component-pagination-summary-line-height`, `--dk-component-pagination-focus-ring-width`, `--dk-component-pagination-focus-ring`

package/manifest/components/payment-form.md

@@ -0,0 +1,29 @@
+# Payment form (`payment-form`)
+
+Stripe's Payment Element on the kit's tokens: its fields, labels, tabs and errors follow the theme, the surface and the tone around them, like any kit field.
+
+
+## Anatomy (HTML)
+
+```text
+div.dk-component-payment-form
+  div.dk-component-payment-form__element   (mount the Payment Element here)
+  p.dk-component-payment-form__error       (optional, role="alert")
+  div.dk-component-payment-form__actions   (optional: Pay, Back)
+```
+
+## React
+
+```tsx
+import { PaymentForm } from '@karmo-co/drift-kit/react';
+```
+
+| Prop | Type | Notes |
+|---|---|---|
+| `children` | `ReactNode` | The Payment Element (inside Stripe's <Elements>). |
+| `error` | `ReactNode` | The message under it: a decline, a failed confirmation. |
+| `actions` | `ReactNode` | Pay, Back: usually kit Buttons. |
+
+## Component tokens
+
+`--dk-component-payment-form-font-family`, `--dk-component-payment-form-font-size`, `--dk-component-payment-form-spacing-unit`, `--dk-component-payment-form-radius`, `--dk-component-payment-form-gap`, `--dk-component-payment-form-primary`, `--dk-component-payment-form-surface`, `--dk-component-payment-form-border`, `--dk-component-payment-form-border-hover`, `--dk-component-payment-form-border-focus`, `--dk-component-payment-form-border-width`, `--dk-component-payment-form-ring`, `--dk-component-payment-form-ring-width`, `--dk-component-payment-form-padding-block`, `--dk-component-payment-form-padding-inline`, `--dk-component-payment-form-text`, `--dk-component-payment-form-text-secondary`, `--dk-component-payment-form-placeholder`, `--dk-component-payment-form-danger`, `--dk-component-payment-form-icon`, `--dk-component-payment-form-label-color`, `--dk-component-payment-form-label-font-size`, `--dk-component-payment-form-label-font-weight`, `--dk-component-payment-form-label-letter-spacing`, `--dk-component-payment-form-tab-surface`, `--dk-component-payment-form-tab-surface-hover`, `--dk-component-payment-form-tab-border`, `--dk-component-payment-form-tab-selected-surface`, `--dk-component-payment-form-tab-selected-surface-hover`, `--dk-component-payment-form-tab-selected-border`, `--dk-component-payment-form-tab-selected-text`, `--dk-component-payment-form-error-font-size`, `--dk-component-payment-form-error-line-height`, `--dk-component-payment-form-element-min-height`

package/manifest/components/price-summary.md

@@ -0,0 +1,30 @@
+# Price summary (`price-summary`)
+
+Labelled amounts on hairlines, then their total with a note under it. Credits in the brand tone.
+
+
+## Anatomy (HTML)
+
+```text
+dl.dk-component-price-summary
+  div.__row                    dt.__label + dd.__amount[data-tone="credit"]?
+  …
+  div.__row[data-total]        dt.__label + dd.__amount (+ span.__note?)
+```
+
+## Attributes
+
+| Attribute | Values the stylesheet styles |
+|---|---|
+| `data-tone` | `credit` |
+| `data-total` | (present or absent) |
+
+## React
+
+```tsx
+import { PriceSummary } from '@karmo-co/drift-kit/react';
+```
+
+## Component tokens
+
+`--dk-component-price-summary-font-family`, `--dk-component-price-summary-divider`, `--dk-component-price-summary-divider-width`, `--dk-component-price-summary-row-gap`, `--dk-component-price-summary-row-padding-block`, `--dk-component-price-summary-total-padding-block`, `--dk-component-price-summary-label-font-size`, `--dk-component-price-summary-label-line-height`, `--dk-component-price-summary-label-font-weight`, `--dk-component-price-summary-label-letter-spacing`, `--dk-component-price-summary-label-color`, `--dk-component-price-summary-amount-font-size`, `--dk-component-price-summary-amount-line-height`, `--dk-component-price-summary-amount-font-weight`, `--dk-component-price-summary-amount-color`, `--dk-component-price-summary-credit-color`, `--dk-component-price-summary-total-label-font-size`, `--dk-component-price-summary-total-label-line-height`, `--dk-component-price-summary-total-label-color`, `--dk-component-price-summary-total-amount-font-size`, `--dk-component-price-summary-total-amount-line-height`, `--dk-component-price-summary-total-amount-color`, `--dk-component-price-summary-note-font-size`, `--dk-component-price-summary-note-line-height`, `--dk-component-price-summary-note-font-weight`, `--dk-component-price-summary-note-color`

package/manifest/components/radio.md

@@ -0,0 +1,42 @@
+# Radio (`radio`)
+
+One of these, and only one. Checkbox's twin, with a circular box, a drawn dot and a group that is not optional.
+
+
+## Anatomy (HTML)
+
+```text
+label.dk-component-radio[data-size]
+  span.dk-component-radio__box
+    input.dk-component-radio__input
+    span.dk-component-radio__indicator
+  span.dk-component-radio__text
+    span.dk-component-radio__label
+    span.dk-component-radio__desc                                       
+```
+
+## Attributes
+
+| Attribute | Values the stylesheet styles |
+|---|---|
+| `data-orientation` | `horizontal` |
+| `data-pseudo-class` | `active`, `focus`, `hover` |
+| `data-size` | `large`, `small` |
+
+## React
+
+```tsx
+import { Radio } from '@karmo-co/drift-kit/react';
+```
+
+| Prop | Type | Notes |
+|---|---|---|
+| `label` | `ReactNode` | The visible label. OPTIONAL, unlike Input's, and the difference is real rather than an oversight: a select row checkbox in a table, a select all in its header and a radio in a comparison grid all take their name from the column or the row they sit in, and printing it beside every one of them would be noise. Omit it and the control collapses to its box. WITHOUT IT THE NAME HAS TO COME FROM SOMEWHERE ELSE. Pass aria-label, or aria-labelledby pointing at the heading that already says it. A checkbox with neither is a control a screen reader announces as "checkbox" and nothing more, which is the one shape this must not make easy. |
+| `size` | `'small' \| 'medium' \| 'large'` |  |
+| `description` | `ReactNode` | A second line under the label. The control's DESCRIPTION, never part of its name: it is rendered outside the <label>'s naming path and wired with aria-describedby, so a screen reader announces "Marketing emails, checkbox, not checked" and then the explanation, rather than running the two together. |
+| `invalid` | `boolean` | The invalid state. A boolean here rather than Input's message-carrying `error`, because a single checkbox's message belongs to the group it sits in: see CheckboxGroup and RadioGroup, which render it once for the set. |
+| `className` | `string` |  |
+
+## Component tokens
+
+`--dk-component-radio-size`, `--dk-component-radio-small-size`, `--dk-component-radio-large-size`, `--dk-component-radio-glyph-size`, `--dk-component-radio-glyph-enter-delay`, `--dk-component-radio-glyph-enter-duration`, `--dk-component-radio-glyph-enter-easing`, `--dk-component-radio-glyph-exit-duration`, `--dk-component-radio-glyph-exit-easing`, `--dk-component-radio-small-glyph-size`, `--dk-component-radio-large-glyph-size`, `--dk-component-radio-radius`, `--dk-component-radio-border-width`, `--dk-component-radio-focus-ring-width`, `--dk-component-radio-gap`, `--dk-component-radio-text-gap`, `--dk-component-radio-group-gap`, `--dk-component-radio-group-legend-gap`, `--dk-component-radio-group-row-gap`, `--dk-component-radio-label-font-family`, `--dk-component-radio-label-font-size`, `--dk-component-radio-label-line-height`, `--dk-component-radio-small-label-font-size`, `--dk-component-radio-small-label-line-height`, `--dk-component-radio-large-label-font-size`, `--dk-component-radio-large-label-line-height`, `--dk-component-radio-label-font-weight`, `--dk-component-radio-desc-font-weight`, `--dk-component-radio-surface-default`, `--dk-component-radio-surface-hover`, `--dk-component-radio-surface-active`, `--dk-component-radio-border-default`, `--dk-component-radio-border-hover`, `--dk-component-radio-border-active`, `--dk-component-radio-checked-surface-default`, `--dk-component-radio-checked-surface-hover`, `--dk-component-radio-checked-surface-active`, `--dk-component-radio-checked-border-default`, `--dk-component-radio-checked-border-hover`, `--dk-component-radio-checked-border-active`, `--dk-component-radio-glyph`, `--dk-component-radio-halo`, `--dk-component-radio-halo-width`, `--dk-component-radio-ring`, `--dk-component-radio-focus-border`, `--dk-component-radio-error-border-default`, `--dk-component-radio-error-border-hover`, `--dk-component-radio-error-ring`, `--dk-component-radio-error-color`, `--dk-component-radio-disabled-surface`, `--dk-component-radio-disabled-border`, `--dk-component-radio-disabled-checked-surface`, `--dk-component-radio-disabled-checked-border`, `--dk-component-radio-disabled-glyph`, `--dk-component-radio-label-color`, `--dk-component-radio-desc-color`, `--dk-component-radio-disabled-label-color`, `--dk-component-radio-disabled-desc-color`, `--dk-component-radio-legend-color`

package/manifest/components/section-heading.md

@@ -0,0 +1,41 @@
+# Section heading (`section-heading`)
+
+A glyph beside a title and a line under it, heading a list or a card from outside.
+
+
+## Anatomy (HTML)
+
+```text
+div.dk-component-section-heading[data-size][data-tone]
+  span.__icon?            a kit Icon, a Lucide <i>, an <svg>
+  div.__content
+    h2..h6.__title        the author's level (h1 for a page's at large)
+    p.__description?
+```
+
+## Attributes
+
+| Attribute | Values the stylesheet styles |
+|---|---|
+| `data-size` | `large`, `medium` |
+| `data-tone` | `neutral` |
+
+## React
+
+```tsx
+import { SectionHeading } from '@karmo-co/drift-kit/react';
+```
+
+| Prop | Type | Notes |
+|---|---|---|
+| `title` (required) | `ReactNode` |  |
+| `titleAs` | `'h1' \| 'h2' \| 'h3' \| 'h4' \| 'h5' \| 'h6'` | The level in the page's outline; the size is separate. h2 when absent. |
+| `titleId` | `string` | The title's own id, so a list or card under it can be named by the title alone (aria-labelledby). An id on the component names the whole block, description and all. |
+| `description` | `ReactNode` | A line under the title. |
+| `icon` | `ReactNode` | A glyph beside it, decorative: the title says what the section is. |
+| `size` | `'small' \| 'medium' \| 'large'` | small (the default) heads a list or a card; medium a group of cards; large is a page's own heading. |
+| `tone` | `'neutral'` | The glyph is primary; neutral is the grey one. |
+
+## Component tokens
+
+`--dk-component-section-heading-gap`, `--dk-component-section-heading-content-gap`, `--dk-component-section-heading-title-color`, `--dk-component-section-heading-title-font-family`, `--dk-component-section-heading-title-font-weight`, `--dk-component-section-heading-description-color`, `--dk-component-section-heading-description-font-weight`, `--dk-component-section-heading-icon-color`, `--dk-component-section-heading-icon-neutral-color`, `--dk-component-section-heading-small-icon-size`, `--dk-component-section-heading-small-title-font-size`, `--dk-component-section-heading-small-title-line-height`, `--dk-component-section-heading-small-description-font-size`, `--dk-component-section-heading-small-description-line-height`, `--dk-component-section-heading-medium-icon-size`, `--dk-component-section-heading-medium-title-font-size`, `--dk-component-section-heading-medium-title-line-height`, `--dk-component-section-heading-medium-description-font-size`, `--dk-component-section-heading-medium-description-line-height`, `--dk-component-section-heading-large-gap`, `--dk-component-section-heading-large-content-gap`, `--dk-component-section-heading-large-icon-size`, `--dk-component-section-heading-large-title-font-family`, `--dk-component-section-heading-large-title-font-weight`, `--dk-component-section-heading-large-title-font-size`, `--dk-component-section-heading-large-title-line-height`, `--dk-component-section-heading-large-description-font-size`, `--dk-component-section-heading-large-description-line-height`

package/manifest/components/select.md

@@ -0,0 +1,99 @@
+# Select (`select`)
+
+One value from a list. A field-shaped trigger, a floating listbox, and the keyboard that drives both.
+
+
+## Anatomy (HTML)
+
+```text
+div.dk-component-select[data-size][data-open][data-selected]
+  label.dk-component-select__label            (optional, + __req)
+  input[type=hidden]                          (the form value)
+  button.dk-component-select__trigger         (role=combobox)
+    span.dk-component-select__chips           (built by the behaviour, [data-multiple] only)
+      span.dk-component-select__chip
+        span.dk-component-select__chip-label
+        span.dk-component-select__chip-remove (aria-hidden, a picture not a button)
+    span.dk-component-select__value           ([data-empty] when unchosen)
+      span.dk-component-select__value-icon    (optional)
+      span.dk-component-select__value-label
+    svg.dk-component-select__chevron
+  div.dk-component-select__menu               (role=listbox, portalled)
+    div.dk-component-select__search           (built by the behaviour, [data-search] only)
+      input.dk-component-select__search-input (role=combobox; the menu becomes a
+    div.dk-component-select__list              presentation wrapper and the LIST is the listbox)
+    div.dk-component-select__group            (optional)
+      span.dk-component-select__group-label
+    button.dk-component-select__option        (role=option)
+      span.dk-component-select__option-main
+      span.dk-component-select__option-meta  (optional, right-aligned)
+        span.dk-component-select__option-icon (optional)
+        span.dk-component-select__option-text
+          span.dk-component-select__option-label
+          span.dk-component-select__option-desc  (optional)
+      svg.dk-component-select__check
+    p.dk-component-select__empty              (optional)
+  p.dk-component-select__caption              (optional)
+  p.dk-component-select__error                (optional)                 
+```
+
+## Attributes
+
+| Attribute | Values the stylesheet styles |
+|---|---|
+| `data-active` | (present or absent) |
+| `data-appearance` | `sentence` |
+| `data-clearable` | (present or absent) |
+| `data-closing` | (present or absent) |
+| `data-empty` | (present or absent) |
+| `data-layout` | `grid` |
+| `data-loading` | (present or absent) |
+| `data-multiple` | (present or absent) |
+| `data-nav` | `keyboard` |
+| `data-open` | (present or absent) |
+| `data-pseudo-class` | `active`, `focus`, `hover` |
+| `data-raised` | (present or absent) |
+| `data-searchable` | (present or absent) |
+| `data-selected` | (present or absent) |
+| `data-sheet-closing` | (present or absent) |
+| `data-sheet-open` | (present or absent) |
+| `data-size` | `large`, `small` |
+| `data-tone` | `error`, `information`, `primary`, `success`, `warning` |
+| `data-variant` | `inset`, `raised` |
+
+## React
+
+```tsx
+import { Select } from '@karmo-co/drift-kit/react';
+```
+
+| Prop | Type | Notes |
+|---|---|---|
+| `options` (required) | `SelectOption[]` |  |
+| `label` | `ReactNode` | The visible label. Optional, like Checkbox's and for the same reason: a select in a toolbar takes its name from what it sits in. Without one, pass aria-label. |
+| `size` | `'small' \| 'medium' \| 'large'` |  |
+| `caption` | `ReactNode` | Helper text, wired as the control's description. |
+| `error` | `ReactNode` | The message AND the invalid state, exactly as Input spells it: one prop, so the border, the words and aria-invalid cannot disagree. |
+| `placeholder` | `string` | What the trigger says before anything is chosen. |
+| `defaultValue` | `string \| string[]` | UNCONTROLLED ONLY, and that is deliberate rather than unfinished. The menu is built and mutated by behaviour.js in DOM React does not own, so a `value` prop would be a promise this component cannot keep: React would re-render the trigger's contents from props and the helper would write over them on the next selection. defaultValue seeds it, onChange reports it, and the DOM is the source of truth in between. |
+| `onChange` | `(value: string \| string[]) => void` |  |
+| `multiple` | `boolean` | SEVERAL VALUES AT ONCE. The trigger holds a chip per value and grows as they wrap, choosing does not close the menu, and onChange reports an array. defaultValue takes one too. The control's shape follows the mode rather than making every caller ask, which is why these are unions: a multi-select that reported a string would be lying about what it holds. |
+| `search` | `boolean` | Puts a search field at the top of the POPUP, which keeps this the select-only combobox it already is: the trigger still shows a value and still opens, and the thing that takes typing exists only while the list is up. Worth it once a list stops being readable at a glance — the country case, where typeahead finds what you can spell and nothing else. |
+| `searchPlaceholder` | `string` |  |
+| `clearable` | `boolean` | A cross on the trigger that puts the placeholder back. Without one, unchosen is a state the control can leave and never return to. |
+| `loading` | `boolean` | While the options are still arriving. The list says so rather than saying it is empty, which is a different thing and reads as an answer. |
+| `name` | `string` | The name the hidden input posts under, so the control works in an ordinary form. |
+| `required` | `boolean` |  |
+| `disabled` | `boolean` |  |
+| `raised` | `boolean` | Lifts the trigger off the surface on an elevation instead of sitting flush in it, the same attribute and the same trade as Input's: the shadow is the whole of it, and padding and height still come from the size rung. Kept as an alias of variant="raised". |
+| `variant` | `'plain' \| 'raised' \| 'inset' \| 'default'` | How the trigger separates from the surface, as Input's and Glider's do: plain (the default) sits flush with an edge, raised lifts it on a shadow, inset sinks it into the nested fill with no edge. 'default' is the old name for plain and still renders as it. |
+| `sheet` | `'auto' \| 'always' \| 'never'` | How the menu presents itself on a phone. 'auto', the default, is a bottom sheet below the kit's mobile breakpoint and a dropdown above it. 'never' opts out, for a select inside something that is already a sheet or a full-screen modal. 'always' forces the sheet at any width, which is how the documentation shows it on a desktop. |
+| `layout` | `'list' \| 'grid'` | 'grid' lays the options out as cards in a wider popup, for options that are pictures (VehicleSelect). Up and down move a row, left and right a card. |
+| `appearance` | `'field' \| 'sentence'` | 'sentence' sets the trigger inside a line of text, the value in bold primary ("Every [Monday] of each week"). Name it with label (kept, not shown) or aria-label. |
+| `className` | `string` |  |
+| `id` | `string` |  |
+| `'aria-label'` | `string` |  |
+
+## Component tokens
+
+`--dk-component-select-small-padding-y`, `--dk-component-select-padding-y`, `--dk-component-select-large-padding-y`, `--dk-component-select-small-height`, `--dk-component-select-height`, `--dk-component-select-large-height`, `--dk-component-select-padding-inline`, `--dk-component-select-radius`, `--dk-component-select-border-width`, `--dk-component-select-focus-ring-width`, `--dk-component-select-gap`, `--dk-component-select-slot-gap`, `--dk-component-select-chevron-size`, `--dk-component-select-sentence-border`, `--dk-component-select-sentence-surface`, `--dk-component-select-sentence-text`, `--dk-component-select-sentence-font-weight`, `--dk-component-select-sentence-font-size`, `--dk-component-select-sentence-line-height`, `--dk-component-select-sentence-small-font-size`, `--dk-component-select-sentence-small-line-height`, `--dk-component-select-sentence-large-font-size`, `--dk-component-select-sentence-large-line-height`, `--dk-component-select-sentence-padding-inline`, `--dk-component-select-sentence-chevron-size`, `--dk-component-select-sentence-value-min-width`, `--dk-component-select-sentence-margin-inline`, `--dk-component-select-font-family`, `--dk-component-select-font-size`, `--dk-component-select-line-height`, `--dk-component-select-small-font-size`, `--dk-component-select-small-line-height`, `--dk-component-select-large-font-size`, `--dk-component-select-large-line-height`, `--dk-component-select-value-font-weight`, `--dk-component-select-placeholder-font-weight`, `--dk-component-select-label-font-family`, `--dk-component-select-label-font-size`, `--dk-component-select-label-line-height`, `--dk-component-select-label-letter-spacing`, `--dk-component-select-label-font-weight`, `--dk-component-select-label-color`, `--dk-component-select-caption-font-size`, `--dk-component-select-caption-line-height`, `--dk-component-select-caption-color`, `--dk-component-select-error-color`, `--dk-component-select-required-color`, `--dk-component-select-surface-default`, `--dk-component-select-surface-hover`, `--dk-component-select-surface-active`, `--dk-component-select-inset-surface`, `--dk-component-select-inset-surface-hover`, `--dk-component-select-inset-surface-active`, `--dk-component-select-inset-border`, `--dk-component-select-inset-value-color`, `--dk-component-select-inset-placeholder-color`, `--dk-component-select-inset-chevron-color`, `--dk-component-select-inset-chevron-primary`, `--dk-component-select-inset-chevron-success`, `--dk-component-select-inset-chevron-error`, `--dk-component-select-inset-chevron-warning`, `--dk-component-select-inset-chevron-information`, `--dk-component-select-border-default`, `--dk-component-select-border-hover`, `--dk-component-select-border-focus`, `--dk-component-select-ring`, `--dk-component-select-value-color`, `--dk-component-select-placeholder-color`, `--dk-component-select-chevron-color`, `--dk-component-select-chevron-color-hover`, `--dk-component-select-value-icon-color`, `--dk-component-select-raised-shadow`, `--dk-component-select-raised-shadow-hover`, `--dk-component-select-raised-border-default`, `--dk-component-select-raised-border-hover`, `--dk-component-select-raised-border-focus`, `--dk-component-select-error-border-default`, `--dk-component-select-error-border-focus`, `--dk-component-select-error-ring`, `--dk-component-select-disabled-surface`, `--dk-component-select-disabled-border`, `--dk-component-select-disabled-value-color`, `--dk-component-select-disabled-icon-color`, `--dk-component-select-disabled-label-color`, `--dk-component-menu-surface`, `--dk-component-menu-border`, `--dk-component-menu-border-width`, `--dk-component-menu-radius`, `--dk-component-menu-shadow`, `--dk-component-menu-padding-block`, `--dk-component-menu-padding-inline`, `--dk-component-menu-max-height`, `--dk-component-menu-max-width`, `--dk-component-menu-viewport-gap`, `--dk-component-menu-sheet-max-height`, `--dk-component-menu-sheet-radius`, `--dk-component-menu-sheet-padding-block`, `--dk-component-menu-scrim`, `--dk-component-menu-sheet-exit-duration`, `--dk-component-menu-sheet-exit-easing`, `--dk-component-menu-enter-duration`, `--dk-component-menu-enter-easing`, `--dk-component-menu-exit-duration`, `--dk-component-menu-exit-easing`, `--dk-component-menu-motion-offset`, `--dk-component-select-option-touch-height`, `--dk-component-select-sheet-title-color`, `--dk-component-menu-scrollbar-thumb`, `--dk-component-menu-scrollbar-thumb-hover`, `--dk-component-select-chip-gap`, `--dk-component-select-chip-padding-block`, `--dk-component-select-chip-padding-inline`, `--dk-component-select-chip-radius`, `--dk-component-select-chip-surface`, `--dk-component-select-chip-shadow`, `--dk-component-select-chip-surface-hover`, `--dk-component-select-chip-color`, `--dk-component-select-chip-font-size`, `--dk-component-select-chip-line-height`, `--dk-component-select-small-chip-font-size`, `--dk-component-select-small-chip-line-height`, `--dk-component-select-large-chip-font-size`, `--dk-component-select-large-chip-line-height`, `--dk-component-select-chip-remove-size`, `--dk-component-select-chip-remove-icon-size`, `--dk-component-select-chip-remove-radius`, `--dk-component-select-chip-remove-surface`, `--dk-component-select-chip-remove-surface-hover`, `--dk-component-select-chip-remove-surface-active`, `--dk-component-select-chip-remove-color`, `--dk-component-select-chip-remove-color-hover`, `--dk-component-select-chip-remove-color-active`, `--dk-component-select-chip-remove-transform-scale-active`, `--dk-component-select-chips-padding-block`, `--dk-component-select-option-padding-block`, `--dk-component-select-option-padding-inline`, `--dk-component-select-option-radius`, `--dk-component-select-option-gap`, `--dk-component-select-option-transform-scale-active`, `--dk-component-select-option-font-size`, `--dk-component-select-option-line-height`, `--dk-component-select-small-option-font-size`, `--dk-component-select-small-option-line-height`, `--dk-component-select-large-option-font-size`, `--dk-component-select-large-option-line-height`, `--dk-component-select-option-font-weight`, `--dk-component-select-option-color`, `--dk-component-select-option-color-active`, `--dk-component-select-option-color-hover`, `--dk-component-select-option-icon-size`, `--dk-component-select-option-media-width`, `--dk-component-select-value-media-height`, `--dk-component-select-grid-menu-width`, `--dk-component-select-grid-menu-max-height`, `--dk-component-select-grid-card-min`, `--dk-component-select-grid-media-width`, `--dk-component-select-grid-desc-font-size`, `--dk-component-select-grid-desc-line-height`, `--dk-component-select-grid-gap`, `--dk-component-select-grid-card-padding`, `--dk-component-select-grid-card-radius`, `--dk-component-select-grid-card-selected-surface`, `--dk-component-select-grid-card-selected-surface-hover`, `--dk-component-select-grid-card-selected-border`, `--dk-component-select-grid-label-font-size`, `--dk-component-select-grid-label-line-height`, `--dk-component-select-grid-card-selected-width`, `--dk-component-select-option-icon-color`, `--dk-component-select-option-icon-color-hover`, `--dk-component-select-check-size`, `--dk-component-select-check-color`, `--dk-component-select-check-stroke-width`, `--dk-component-select-option-surface-hover`, `--dk-component-select-option-surface-active`, `--dk-component-select-option-disabled-color`, `--dk-component-select-option-disabled-icon-color`, `--dk-component-select-option-desc-color`, `--dk-component-select-option-desc-font-weight`, `--dk-component-select-option-desc-gap`, `--dk-component-select-group-font-size`, `--dk-component-select-group-line-height`, `--dk-component-select-group-letter-spacing`, `--dk-component-select-group-font-weight`, `--dk-component-select-group-color`, `--dk-component-select-group-padding-block`, `--dk-component-select-group-gap`, `--dk-component-select-search-padding-block`, `--dk-component-select-search-gap`, `--dk-component-select-search-font-size`, `--dk-component-select-search-line-height`, `--dk-component-select-small-search-font-size`, `--dk-component-select-small-search-line-height`, `--dk-component-select-large-search-font-size`, `--dk-component-select-large-search-line-height`, `--dk-component-select-search-color`, `--dk-component-select-search-placeholder-color`, `--dk-component-select-search-icon-size`, `--dk-component-select-search-icon-color`, `--dk-component-select-search-border`, `--dk-component-select-search-border-width`, `--dk-component-select-loading-color`, `--dk-component-select-loading-spinner-size`, `--dk-component-select-loading-spinner-track`, `--dk-component-select-loading-spinner-head`, `--dk-component-select-loading-duration`, `--dk-component-select-clear-size`, `--dk-component-select-clear-icon-size`, `--dk-component-select-clear-radius`, `--dk-component-select-clear-surface-hover`, `--dk-component-select-clear-surface-active`, `--dk-component-select-clear-color`, `--dk-component-select-clear-color-hover`, `--dk-component-select-clear-color-active`, `--dk-component-select-clear-transform-scale-active`, `--dk-component-select-option-meta-color`, `--dk-component-select-empty-color`, `--dk-component-select-duration`, `--dk-component-select-duration-fast`, `--dk-component-select-easing`

package/manifest/components/shield.md

@@ -0,0 +1,34 @@
+# Shield (`shield`)
+
+A shield that scales in, shakes when a code is wrong and pulses a tick in when it is right.
+
+
+## Anatomy (HTML)
+
+```text
+div.dk-component-shield[data-animation="idle|enter|success|error"]?[data-size]?
+  (the vectors are drawn by the runtime)
+```
+
+## Attributes
+
+| Attribute | Values the stylesheet styles |
+|---|---|
+| `data-animation` | `enter`, `error`, `success` |
+| `data-part` | `check`, `fill`, `lock`, `outline` |
+
+## React
+
+```tsx
+import { Shield } from '@karmo-co/drift-kit/react';
+```
+
+| Prop | Type | Notes |
+|---|---|---|
+| `animation` | `'enter' \| 'error' \| 'success'` | Setting the same value again replays it, as in CL. |
+| `replayKey` | `string \| number` | Change it (a counter, an attempt number) to play the same state again: a second wrong code has the same animation as the first, and a prop set to its own value is not a change React can see. |
+| `label` | `string` |  |
+
+## Component tokens
+
+`--dk-component-shield-size`, `--dk-component-shield-disc`, `--dk-component-shield-body`, `--dk-component-shield-glyph`, `--dk-component-shield-check`, `--dk-component-shield-glyph-scale`, `--dk-component-shield-enter-duration`, `--dk-component-shield-enter-delay`, `--dk-component-shield-enter-easing`, `--dk-component-shield-success-duration`, `--dk-component-shield-check-duration`, `--dk-component-shield-check-delay`, `--dk-component-shield-error-duration`, `--dk-component-shield-error-easing`, `--dk-component-shield-glyph-fade`

package/manifest/components/sidebar.md

@@ -0,0 +1,73 @@
+# Sidebar (`sidebar`)
+
+An app's main navigation. A rail on a desktop that collapses to its glyphs, and on a phone a bottom tab bar or a drawer, from one set of markup.
+
+
+## Anatomy (HTML)
+
+```text
+nav.dk-component-sidebar[data-collapsed]?
+  div.__head > a.__brand > span.__mark + span.__wordmark
+  div.__body
+    div.__section > span.__heading? + ul.__list > a|button.__item[aria-current]?
+  div.__foot
+    ul.__list > button.__item.__toggle
+    div.dk-component-dropdown.__account > button.__user (an avatar and __user-text)
+```
+
+## Attributes
+
+| Attribute | Values the stylesheet styles |
+|---|---|
+| `data-bar-hidden` | (present or absent) |
+| `data-bar-shown` | (present or absent) |
+| `data-collapsed` | (present or absent) |
+| `data-current-within` | (present or absent) |
+| `data-indicator` | (present or absent) |
+| `data-level` | `2` |
+| `data-nested` | (present or absent) |
+| `data-open` | (present or absent) |
+| `data-panel` | `closed`, `closing`, `filling` |
+| `data-presentation` | `bar`, `drawer`, `rail` |
+| `data-rising` | (present or absent) |
+| `data-sb-carry` | (present or absent) |
+| `data-sb-instant` | (present or absent) |
+| `data-sb-unit` | (present or absent) |
+| `data-space` | (present or absent) |
+| `data-variant` | `floating` |
+
+## React
+
+```tsx
+import { Sidebar } from '@karmo-co/drift-kit/react';
+```
+
+| Prop | Type | Notes |
+|---|---|---|
+| `'aria-label'` | `string` |  |
+| `id` | `string` |  |
+| `brand` | `{ mark: ReactNode; wordmark?: ReactNode; href?: string; label?: string }` |  |
+| `sections` (required) | `SidebarSection[]` |  |
+| `panel` | `SidebarPanel` | Nested: the current section's pages in a panel beside the rail. Mark the section's own row current: 'section'. |
+| `footer` | `SidebarItem[]` | Utilities above the user row: Settings, Help. On a phone bar they are in More. |
+| `user` | `SidebarUser` |  |
+| `collapsible` | `boolean` | A collapse toggle in the foot. On by default. |
+| `collapsed` | `boolean` |  |
+| `defaultCollapsed` | `boolean` |  |
+| `onCollapsedChange` | `(collapsed: boolean) => void` |  |
+| `persist` | `string` | Remember the collapse in localStorage under this key. |
+| `variant` | `'docked' \| 'floating'` |  |
+| `size` | `'medium' \| 'small'` | 'small' steps everything down for an app that needs the room. Medium when absent. |
+| `phone` | `'bar' \| 'drawer' \| 'rail'` |  |
+| `device` | `'auto' \| 'phone' \| 'desktop'` | Force a presentation regardless of the screen, as the docs do. |
+| `motion` | `'rise' \| 'simple'` | 'simple' skips the letters' rise: the labels fade. |
+| `panelEnter` | `boolean` | Play the panel's opening on mount, not only when a panel arrives later. The page knows how it was reached; the Sidebar does not. |
+| `moreLabel` | `string` |  |
+| `dotLabel` | `string` | What a screen reader hears for an unread dot. "New" when absent. |
+| `renderLink` | `(props: SidebarLinkProps) => ReactElement` |  |
+| `theme` | `'light' \| 'dark'` | Dark chrome: 'dark' makes it dark on a light page and one step deeper than a dark one. Everything inside resolves dark, menus included. |
+| `className` | `string` |  |
+
+## Component tokens
+
+`--dk-component-sidebar-width`, `--dk-component-sidebar-collapsed-width`, `--dk-component-sidebar-padding-block`, `--dk-component-sidebar-padding-inline`, `--dk-component-sidebar-gap`, `--dk-component-sidebar-section-gap`, `--dk-component-sidebar-border-width`, `--dk-component-sidebar-docked-surface`, `--dk-component-sidebar-docked-border`, `--dk-component-sidebar-floating-surface`, `--dk-component-sidebar-floating-border`, `--dk-component-sidebar-floating-radius`, `--dk-component-sidebar-floating-shadow`, `--dk-component-sidebar-floating-inset`, `--dk-component-sidebar-blur`, `--dk-component-sidebar-brand-height`, `--dk-component-sidebar-head-height`, `--dk-component-sidebar-brand-mark-size`, `--dk-component-sidebar-brand-gap`, `--dk-component-sidebar-wordmark-font-family`, `--dk-component-sidebar-wordmark-font-size`, `--dk-component-sidebar-wordmark-font-weight`, `--dk-component-sidebar-wordmark-color`, `--dk-component-sidebar-divider`, `--dk-component-sidebar-item-height`, `--dk-component-sidebar-item-gap`, `--dk-component-sidebar-item-radius`, `--dk-component-sidebar-item-icon-size`, `--dk-component-sidebar-item-font-family`, `--dk-component-sidebar-item-font-size`, `--dk-component-sidebar-item-line-height`, `--dk-component-sidebar-item-font-weight`, `--dk-component-sidebar-item-text`, `--dk-component-sidebar-item-text-hover`, `--dk-component-sidebar-item-text-active`, `--dk-component-sidebar-item-surface-hover`, `--dk-component-sidebar-item-border-hover`, `--dk-component-sidebar-item-surface-active`, `--dk-component-sidebar-item-border-active`, `--dk-component-sidebar-item-text-disabled`, `--dk-component-sidebar-item-press-scale`, `--dk-component-sidebar-bar-press-scale`, `--dk-component-sidebar-focus-ring`, `--dk-component-sidebar-focus-ring-width`, `--dk-component-sidebar-current-surface`, `--dk-component-sidebar-current-surface-hover`, `--dk-component-sidebar-current-border`, `--dk-component-sidebar-current-border-hover`, `--dk-component-sidebar-current-border-active`, `--dk-component-sidebar-current-text`, `--dk-component-sidebar-menu-current-text`, `--dk-component-sidebar-menu-current-font-weight`, `--dk-component-sidebar-child-height`, `--dk-component-sidebar-child-icon-size`, `--dk-component-sidebar-child-inset`, `--dk-component-sidebar-child-gap`, `--dk-component-sidebar-child-font-weight`, `--dk-component-sidebar-guide`, `--dk-component-sidebar-guide-width`, `--dk-component-sidebar-guide-radius`, `--dk-component-sidebar-heading-font-size`, `--dk-component-sidebar-heading-line-height`, `--dk-component-sidebar-heading-font-weight`, `--dk-component-sidebar-heading-letter-spacing`, `--dk-component-sidebar-heading-color`, `--dk-component-sidebar-badge-size`, `--dk-component-sidebar-badge-font-size`, `--dk-component-sidebar-badge-font-weight`, `--dk-component-sidebar-badge-surface`, `--dk-component-sidebar-badge-text`, `--dk-component-sidebar-badge-current-surface`, `--dk-component-sidebar-badge-current-text`, `--dk-component-sidebar-dot-size`, `--dk-component-sidebar-dot-surface`, `--dk-component-sidebar-user-height`, `--dk-component-sidebar-user-avatar-size`, `--dk-component-sidebar-user-text-gap`, `--dk-component-sidebar-user-name-font-size`, `--dk-component-sidebar-user-name-font-weight`, `--dk-component-sidebar-user-name-color`, `--dk-component-sidebar-user-meta-font-size`, `--dk-component-sidebar-user-meta-color`, `--dk-component-sidebar-panel-width`, `--dk-component-sidebar-panel-padding`, `--dk-component-sidebar-panel-radius`, `--dk-component-sidebar-panel-surface`, `--dk-component-sidebar-panel-border`, `--dk-component-sidebar-panel-item-surface-hover`, `--dk-component-sidebar-panel-item-border-hover`, `--dk-component-sidebar-panel-title-font-size`, `--dk-component-sidebar-panel-title-font-weight`, `--dk-component-sidebar-panel-title-color`, `--dk-component-sidebar-scrollbar-size`, `--dk-component-sidebar-scrollbar-thumb`, `--dk-component-sidebar-scrollbar-thumb-hover`, `--dk-component-sidebar-duration`, `--dk-component-sidebar-easing`, `--dk-component-sidebar-rise-duration`, `--dk-component-sidebar-rise-stagger`, `--dk-component-sidebar-rise-row-stagger`, `--dk-component-sidebar-indicator-duration`, `--dk-component-sidebar-group-row-duration`, `--dk-component-sidebar-group-stagger`, `--dk-component-sidebar-group-easing`, `--dk-component-sidebar-panel-duration`, `--dk-component-sidebar-panel-easing`, `--dk-component-sidebar-panel-rows-start`, `--dk-component-sidebar-panel-row-duration`, `--dk-component-sidebar-panel-row-easing`, `--dk-component-sidebar-panel-row-beat`, `--dk-component-sidebar-panel-row-exit-duration`, `--dk-component-sidebar-panel-row-exit-easing`, `--dk-component-sidebar-bar-height`, `--dk-component-sidebar-bar-surface`, `--dk-component-sidebar-bar-border`, `--dk-component-sidebar-bar-shadow`, `--dk-component-sidebar-bar-radius`, `--dk-component-sidebar-bar-inset`, `--dk-component-sidebar-bar-max-width`, `--dk-component-sidebar-bar-font-size`, `--dk-component-sidebar-bar-icon-size`, `--dk-component-sidebar-bar-pill-width`, `--dk-component-sidebar-bar-pill-height`, `--dk-component-sidebar-bar-current-surface`, `--dk-component-sidebar-bar-current-text`, `--dk-component-sidebar-bar-slots`, `--dk-component-sidebar-bar-z-index`, `--dk-component-sidebar-drawer-width`, `--dk-component-sidebar-drawer-shadow`, `--dk-component-sidebar-scrim`, `--dk-component-sidebar-drawer-duration`, `--dk-component-sidebar-drawer-easing`, `--dk-component-sidebar-drawer-z-index`

package/manifest/components/stepper.md

@@ -0,0 +1,53 @@
+# Stepper (`stepper`)
+
+Where someone is in a process with a known number of steps, and what is left.
+
+
+## Anatomy (HTML)
+
+```text
+  nav.dk-component-stepper[aria-label][data-variant][data-orientation][data-labels=hidden][data-size][data-free]
+    ol.dk-component-stepper__list
+      li.dk-component-stepper__step[data-state][data-error][data-optional]
+        button|span.dk-component-stepper__target   (a button where a step can be revisited)
+          span.__indicator  span.__text > span.__label + span.__description?
+        div.__content?      (vertical: shown under the current step)
+── 
+```
+
+## Attributes
+
+| Attribute | Values the stylesheet styles |
+|---|---|
+| `data-error` | (present or absent) |
+| `data-labels` | `hidden` |
+| `data-narrow` | (present or absent) |
+| `data-orientation` | `vertical` |
+| `data-size` | `large`, `small` |
+| `data-state` | `complete`, `current`, `upcoming` |
+| `data-variant` | `dots`, `inline`, `segments` |
+
+## React
+
+```tsx
+import { Stepper } from '@karmo-co/drift-kit/react';
+```
+
+| Prop | Type | Notes |
+|---|---|---|
+| `steps` (required) | `StepperStep[]` |  |
+| `current` (required) | `number` | The current step's index. Controlled: the stepper shows what you pass. |
+| `variant` | `'numbered' \| 'dots' \| 'segments' \| 'inline'` |  |
+| `orientation` | `'horizontal' \| 'vertical'` |  |
+| `narrowOrientation` | `'vertical'` | 'vertical' turns the stepper vertical while it is narrow (a phone), so every step keeps its label; it goes back to orientation when wide. Without it a narrow stepper stays horizontal and shows only the current label. |
+| `labels` | `'visible' \| 'hidden'` | Hidden keeps the words for a screen reader only. Where they sit is the variant's: beside the number for inline, below it for the rest. |
+| `size` | `'small' \| 'medium' \| 'large'` |  |
+| `onStepClick` | `(index: number) => void` | Makes completed steps buttons. You decide whether to go back, and pass the new current. |
+| `free` | `boolean` | Every step is reachable, not only the completed ones. |
+| `onChange` | `(index: number) => void` | After the current step changes (announced to screen readers). |
+| `'aria-label'` (required) | `string` |  |
+| `className` | `string` |  |
+
+## Component tokens
+
+`--dk-component-stepper-small-indicator-size`, `--dk-component-stepper-indicator-size`, `--dk-component-stepper-large-indicator-size`, `--dk-component-stepper-small-number-font-size`, `--dk-component-stepper-number-font-size`, `--dk-component-stepper-large-number-font-size`, `--dk-component-stepper-small-label-font-size`, `--dk-component-stepper-small-label-line-height`, `--dk-component-stepper-label-font-size`, `--dk-component-stepper-label-line-height`, `--dk-component-stepper-large-label-font-size`, `--dk-component-stepper-large-label-line-height`, `--dk-component-stepper-description-font-size`, `--dk-component-stepper-description-line-height`, `--dk-component-stepper-font-family`, `--dk-component-stepper-number-font-weight`, `--dk-component-stepper-label-font-weight`, `--dk-component-stepper-label-font-weight-current`, `--dk-component-stepper-icon-size`, `--dk-component-stepper-indicator-border-width`, `--dk-component-stepper-gap`, `--dk-component-stepper-text-gap`, `--dk-component-stepper-connector-thickness`, `--dk-component-stepper-vertical-step-gap`, `--dk-component-stepper-content-gap`, `--dk-component-stepper-target-radius`, `--dk-component-stepper-target-surface-hover`, `--dk-component-stepper-target-surface-active`, `--dk-component-stepper-inline-gap`, `--dk-component-stepper-target-padding`, `--dk-component-stepper-target-padding-block-interactive`, `--dk-component-stepper-target-padding-inline-interactive`, `--dk-component-stepper-complete-surface`, `--dk-component-stepper-complete-surface-hover`, `--dk-component-stepper-complete-surface-active`, `--dk-component-stepper-complete-icon`, `--dk-component-stepper-complete-icon-hover`, `--dk-component-stepper-complete-icon-active`, `--dk-component-stepper-complete-border`, `--dk-component-stepper-complete-border-hover`, `--dk-component-stepper-complete-border-active`, `--dk-component-stepper-current-surface`, `--dk-component-stepper-current-surface-hover`, `--dk-component-stepper-current-surface-active`, `--dk-component-stepper-current-border`, `--dk-component-stepper-current-text`, `--dk-component-stepper-upcoming-surface`, `--dk-component-stepper-upcoming-border`, `--dk-component-stepper-upcoming-text`, `--dk-component-stepper-error-surface`, `--dk-component-stepper-error-border`, `--dk-component-stepper-error-text`, `--dk-component-stepper-error-label`, `--dk-component-stepper-label-color`, `--dk-component-stepper-label-color-upcoming`, `--dk-component-stepper-label-color-complete`, `--dk-component-stepper-label-color-hover`, `--dk-component-stepper-description-color`, `--dk-component-stepper-optional-color`, `--dk-component-stepper-focus-ring`, `--dk-component-stepper-focus-ring-width`, `--dk-component-stepper-connector-track`, `--dk-component-stepper-connector-fill`, `--dk-component-stepper-fill-duration`, `--dk-component-stepper-easing`, `--dk-component-stepper-state-duration`, `--dk-component-stepper-dot-ring-width`, `--dk-component-stepper-dot-size`, `--dk-component-stepper-segment-thickness`, `--dk-component-stepper-segment-content-gap-start`, `--dk-component-stepper-segment-content-gap-end`, `--dk-component-stepper-segment-length`, `--dk-component-stepper-segment-gap`, `--dk-component-stepper-segment-radius`, `--dk-component-stepper-narrow`, `--dk-component-stepper-narrow-label-max`, `--dk-component-stepper-narrow-inline-gap`