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

package/manifest/components/dropdown.md

@@ -0,0 +1,52 @@
+# Dropdown (`dropdown`)
+
+A menu of commands hanging off a trigger. Select's surface, a menu's semantics: real focus, no value.
+
+
+## Anatomy (HTML)
+
+```text
+div.dk-component-dropdown
+  button.dk-component-dropdown__trigger      (aria-haspopup="menu")
+  div.dk-component-menu.dk-component-dropdown__menu   (role="menu", portalled)
+    span.dk-component-dropdown__label        (optional heading)
+    button|a.dk-component-dropdown__item     (role="menuitem"
+      span.dk-component-dropdown__item-icon        | "menuitemradio"
+      span.dk-component-dropdown__item-label       | "menuitemcheckbox")
+      svg.dk-component-dropdown__check       (shown when aria-checked)
+    hr.dk-component-dropdown__separator
+```
+
+## Attributes
+
+| Attribute | Values the stylesheet styles |
+|---|---|
+| `data-destructive` | (present or absent) |
+| `data-dropdown-chevron` | (present or absent) |
+| `data-open` | (present or absent) |
+| `data-sheet-open` | (present or absent) |
+| `data-size` | `large`, `medium` |
+
+## React
+
+```tsx
+import { Dropdown } from '@karmo-co/drift-kit/react';
+```
+
+| Prop | Type | Notes |
+|---|---|---|
+| `items` (required) | `DropdownEntry[]` |  |
+| `label` | `ReactNode` | The words on the default trigger, a raised Button. |
+| `trigger` | `ReactElement<{ className?: string }>` | Your own trigger instead: a Button, an icon button, any element that takes a className. It keeps its look and gains the trigger class; the runtime adds aria-haspopup, aria-controls and aria-expanded to it. |
+| `triggerSize` | `'small' \| 'medium' \| 'large'` | The default trigger's size. The menu's is `size`. |
+| `size` | `'small' \| 'medium' \| 'large'` | The list's type and rows, on Select's three rungs. Small when absent: a menu is chrome. |
+| `selection` | `'none' \| 'single' \| 'multiple'` | 'single' makes every item a menuitemradio with a tick (a switcher, like View as); 'multiple' a menuitemcheckbox. 'none', the default, is a list of commands. |
+| `placement` | `'top' \| 'bottom' \| 'left' \| 'right'` | Where the menu opens, in dk.position's vocabulary. Below and start-aligned by default. |
+| `align` | `'start' \| 'center' \| 'end'` |  |
+| `sheet` | `'auto' \| 'always' \| 'never'` | How it presents on a phone: a bottom sheet below the mobile breakpoint by default; 'never' for a menu already inside a sheet; 'always' to force it. |
+| `onSelect` | `(value: string \| undefined, item: HTMLElement) => void` | Any item chosen: its value (undefined for one without) and the element. |
+| `className` | `string` |  |
+
+## Component tokens
+
+`--dk-component-dropdown-item-padding-block`, `--dk-component-dropdown-item-padding-inline`, `--dk-component-dropdown-item-gap`, `--dk-component-dropdown-item-radius`, `--dk-component-dropdown-item-font-family`, `--dk-component-dropdown-item-font-size`, `--dk-component-dropdown-item-line-height`, `--dk-component-dropdown-item-font-weight`, `--dk-component-dropdown-item-touch-height`, `--dk-component-dropdown-medium-item-font-size`, `--dk-component-dropdown-medium-item-line-height`, `--dk-component-dropdown-medium-item-padding-block`, `--dk-component-dropdown-medium-item-icon-size`, `--dk-component-dropdown-medium-check-size`, `--dk-component-dropdown-large-item-font-size`, `--dk-component-dropdown-large-item-line-height`, `--dk-component-dropdown-large-item-padding-block`, `--dk-component-dropdown-large-item-icon-size`, `--dk-component-dropdown-large-check-size`, `--dk-component-dropdown-item-color`, `--dk-component-dropdown-item-color-active`, `--dk-component-dropdown-item-color-hover`, `--dk-component-dropdown-item-icon-color`, `--dk-component-dropdown-item-icon-color-hover`, `--dk-component-dropdown-item-surface-hover`, `--dk-component-dropdown-item-surface-active`, `--dk-component-dropdown-item-disabled-color`, `--dk-component-dropdown-item-disabled-icon-color`, `--dk-component-dropdown-item-destructive-color`, `--dk-component-dropdown-item-destructive-icon-color`, `--dk-component-dropdown-item-destructive-surface-hover`, `--dk-component-dropdown-item-destructive-surface-active`, `--dk-component-dropdown-check-size`, `--dk-component-dropdown-check-color`, `--dk-component-dropdown-check-stroke-width`, `--dk-component-dropdown-item-icon-size`, `--dk-component-dropdown-label-font-size`, `--dk-component-dropdown-label-line-height`, `--dk-component-dropdown-label-letter-spacing`, `--dk-component-dropdown-label-font-weight`, `--dk-component-dropdown-label-color`, `--dk-component-dropdown-label-padding-block`, `--dk-component-dropdown-separator-color`, `--dk-component-dropdown-separator-width`, `--dk-component-dropdown-separator-spacing`, `--dk-component-dropdown-duration`, `--dk-component-dropdown-easing`, `--dk-component-dropdown-item-transform-scale-active`

package/manifest/components/dropzone.md

@@ -0,0 +1,56 @@
+# Dropzone (`dropzone`)
+
+A place to drop or browse for files: one file or a list, with the type, size and count checked on the way in and a plain message when something is refused.
+
+
+## Anatomy (HTML)
+
+```text
+div.dk-component-dropzone[data-layout="row"]?
+  label.__area
+    input.__input[type="file"]
+    span.__icon
+    span.__text > span.__title + span.__hint
+  ul.__list?                  (the chosen files, written by the runtime)
+```
+
+## Attributes
+
+| Attribute | Values the stylesheet styles |
+|---|---|
+| `data-dragover` | (present or absent) |
+| `data-has-file` | (present or absent) |
+| `data-layout` | `compact` |
+| `data-pseudo-class` | `active`, `focus`, `hover` |
+| `data-runtime` | (present or absent) |
+
+## React
+
+```tsx
+import { Dropzone } from '@karmo-co/drift-kit/react';
+```
+
+| Prop | Type | Notes |
+|---|---|---|
+| `label` | `ReactNode` | A field label above the area, the same eyebrow Input uses. |
+| `caption` | `ReactNode` | Helper text under the area, wired as the input's description. |
+| `error` | `ReactNode` | A message from the page (a failed upload, a server check) AND the invalid state, one prop as Input spells it. The runtime's own validation messages are separate and do not need this. |
+| `title` | `ReactNode` | The prompt. Defaults to "Drop a file here" or, with multiple, "Drop files here"; '' leaves it out and the hint names the field. In single mode the chosen file's name shows in its place. |
+| `hint` | `ReactNode` | The line under the prompt; '' leaves it out. In single mode it becomes the chosen file's size. |
+| `icon` | `ReactNode \| null` | Any node; the default is an upload cloud; null leaves the icon out. |
+| `layout` | `'stacked' \| 'compact'` |  |
+| `name` | `string` |  |
+| `accept` | `string` | The same string as the input's accept, enforced on a drop too. |
+| `multiple` | `boolean` | A list that new picks and drops add to. Read when the component mounts: to switch modes, give it a new key. |
+| `maxSize` | `string \| number` | "500KB", "5MB", or a number of bytes. |
+| `maxFiles` | `number` | Multiple only. |
+| `disabled` | `boolean` |  |
+| `required` | `boolean` |  |
+| `id` | `string` | Goes on the input, so a <label htmlFor> elsewhere can point at it. |
+| `className` | `string` |  |
+| `style` | `CSSProperties` | On the root: --dk-component-dropzone-radius and the other tokens. |
+| `onFilesChange` | `(files: File[], rejected: DropzoneRejection[]) => void` | Every change, with the files now held and any that were refused. |
+
+## Component tokens
+
+`--dk-component-dropzone-hint-font-weight`, `--dk-component-dropzone-title-font-weight`, `--dk-component-dropzone-gap`, `--dk-component-dropzone-label-font-family`, `--dk-component-dropzone-label-font-size`, `--dk-component-dropzone-label-line-height`, `--dk-component-dropzone-label-letter-spacing`, `--dk-component-dropzone-label-font-weight`, `--dk-component-dropzone-caption-font-size`, `--dk-component-dropzone-caption-line-height`, `--dk-component-dropzone-error-color`, `--dk-component-dropzone-padding-y`, `--dk-component-dropzone-padding-x`, `--dk-component-dropzone-compact-padding-y`, `--dk-component-dropzone-compact-padding-x`, `--dk-component-dropzone-content-gap`, `--dk-component-dropzone-compact-content-gap`, `--dk-component-dropzone-text-gap`, `--dk-component-dropzone-radius`, `--dk-component-dropzone-border-width`, `--dk-component-dropzone-icon-size`, `--dk-component-dropzone-compact-icon-size`, `--dk-component-dropzone-clear-inset`, `--dk-component-dropzone-active-scale`, `--dk-component-dropzone-surface`, `--dk-component-dropzone-border`, `--dk-component-dropzone-icon-color`, `--dk-component-dropzone-title-color`, `--dk-component-dropzone-hint-color`, `--dk-component-dropzone-surface-hover`, `--dk-component-dropzone-border-hover`, `--dk-component-dropzone-icon-color-hover`, `--dk-component-dropzone-title-color-hover`, `--dk-component-dropzone-hint-color-hover`, `--dk-component-dropzone-surface-active`, `--dk-component-dropzone-border-active`, `--dk-component-dropzone-surface-filled`, `--dk-component-dropzone-border-filled`, `--dk-component-dropzone-border-error`, `--dk-component-dropzone-surface-disabled`, `--dk-component-dropzone-border-disabled`, `--dk-component-dropzone-title-disabled`, `--dk-component-dropzone-hint-disabled`, `--dk-component-dropzone-icon-disabled`, `--dk-component-dropzone-focus-ring-width`, `--dk-component-dropzone-focus-ring`, `--dk-component-dropzone-focus-border`, `--dk-component-dropzone-files-gap`, `--dk-component-dropzone-file-gap`, `--dk-component-dropzone-file-padding-y`, `--dk-component-dropzone-file-padding-x`, `--dk-component-dropzone-file-radius`, `--dk-component-dropzone-file-surface`, `--dk-component-dropzone-file-border`, `--dk-component-dropzone-file-border-width`, `--dk-component-dropzone-file-icon-size`, `--dk-component-dropzone-file-icon-color`, `--dk-component-dropzone-file-name-color`, `--dk-component-dropzone-file-name-font-weight`, `--dk-component-dropzone-file-size-color`

package/manifest/components/eyebrow.md

@@ -0,0 +1,45 @@
+# Eyebrow (`eyebrow`)
+
+Uppercase labels, the component-library's Overline, renamed. Three fixed sizes (12 / 11 / 10 px) with tracking that widens as the size shrinks, bold by default, the Body colour grammar.
+
+
+## Anatomy (HTML)
+
+```text
+span.dk-component-eyebrow[data-size="large|medium|small"]?[data-color]?[data-emphasis="subtle"]?
+```
+
+## Attributes
+
+| Attribute | Values the stylesheet styles |
+|---|---|
+| `data-align` | `center`, `left`, `right` |
+| `data-color` | `black`, `default`, `error`, `information`, `inverse`, `neutral`, `primary`, `success`, `warning`, `white` |
+| `data-disabled` | (present or absent) |
+| `data-emphasis` | `subtle` |
+| `data-size` | `large`, `medium`, `small` |
+| `data-weight` | `bold`, `medium`, `semi-bold` |
+
+## React
+
+```tsx
+import { Eyebrow } from '@karmo-co/drift-kit/react';
+```
+
+| Prop | Type | Notes |
+|---|---|---|
+| `size` | `'large' \| 'medium' \| 'small'` |  |
+| `weight` | `'medium' \| 'semi-bold' \| 'bold'` |  |
+| `textStyle` | `` | React owns `style`, so the data-style axis is `textStyle`. This is the one place the mirror-the-HTML rule cannot hold. |
+| `as` | `ElementType` |  |
+| `color` | `Color` |  |
+| `emphasis` | `Emphasis` |  |
+| `align` | `Align` |  |
+| `trim` | `Trim` |  |
+| `disabled` | `boolean` | A span cannot carry :disabled, so the kit uses [data-disabled]. |
+| `children` | `ReactNode` |  |
+| `className` | `string` |  |
+
+## Component tokens
+
+`--dk-component-eyebrow-font-family`, `--dk-component-eyebrow-transition-duration`, `--dk-component-eyebrow-large-font-size`, `--dk-component-eyebrow-large-line-height`, `--dk-component-eyebrow-medium-font-size`, `--dk-component-eyebrow-medium-line-height`, `--dk-component-eyebrow-small-font-size`, `--dk-component-eyebrow-small-line-height`, `--dk-component-eyebrow-large-letter-spacing`, `--dk-component-eyebrow-medium-letter-spacing`, `--dk-component-eyebrow-small-letter-spacing`, `--dk-component-eyebrow-medium-font-weight`, `--dk-component-eyebrow-semi-bold-font-weight`, `--dk-component-eyebrow-bold-font-weight`, `--dk-component-eyebrow-default-color`, `--dk-component-eyebrow-inverse-color`, `--dk-component-eyebrow-white-color`, `--dk-component-eyebrow-black-color`, `--dk-component-eyebrow-primary-color`, `--dk-component-eyebrow-success-color`, `--dk-component-eyebrow-error-color`, `--dk-component-eyebrow-warning-color`, `--dk-component-eyebrow-information-color`, `--dk-component-eyebrow-neutral-default-color`, `--dk-component-eyebrow-neutral-subtle-color`, `--dk-component-eyebrow-disabled-color`

package/manifest/components/feedback-badge.md

@@ -0,0 +1,35 @@
+# Feedback badge (`feedback-badge`)
+
+A status's circle inside its own soft ring, with a white glyph. The big mark at the top of a success screen or an empty state.
+
+
+## Anatomy (HTML)
+
+```text
+div.dk-component-feedback-badge[data-status]?[data-size="small|medium|large"]?
+  (the glyph is drawn by the runtime)
+```
+
+## Attributes
+
+| Attribute | Values the stylesheet styles |
+|---|---|
+| `data-size` | `medium`, `small` |
+| `data-status` | `error`, `information`, `neutral`, `success`, `warning` |
+
+## React
+
+```tsx
+import { FeedbackBadge } from '@karmo-co/drift-kit/react';
+```
+
+| Prop | Type | Notes |
+|---|---|---|
+| `status` | `FeedbackBadgeStatus` |  |
+| `size` | `'small' \| 'medium' \| 'large'` |  |
+| `icon` | `ReactNode` | Any kit icon. Without one, the status's own glyph, as in CL. |
+| `label` | `string` |  |
+
+## Component tokens
+
+`--dk-component-feedback-badge-small-size`, `--dk-component-feedback-badge-small-padding`, `--dk-component-feedback-badge-small-icon`, `--dk-component-feedback-badge-medium-size`, `--dk-component-feedback-badge-medium-padding`, `--dk-component-feedback-badge-medium-icon`, `--dk-component-feedback-badge-large-size`, `--dk-component-feedback-badge-large-padding`, `--dk-component-feedback-badge-large-icon`, `--dk-component-feedback-badge-glyph`

package/manifest/components/glider.md

@@ -0,0 +1,34 @@
+# Glider (`glider`)
+
+One value from a few options side by side, or several: a raised frame with a primary pill that slides to the choice.
+
+
+## Anatomy (HTML)
+
+```text
+div.dk-component-glider[data-variant="raised|plain|inset|ghost"]?[data-multiple]?[role="radiogroup"]
+  button.__option[data-value][aria-checked]
+    span.__icon?
+    span.__label
+```
+
+## Attributes
+
+| Attribute | Values the stylesheet styles |
+|---|---|
+| `data-direction` | `back`, `forward` |
+| `data-full-width` | (present or absent) |
+| `data-multiple` | (present or absent) |
+| `data-size` | `large`, `small` |
+| `data-tone` | `error`, `information`, `primary`, `success`, `warning` |
+| `data-variant` | `ghost`, `inset`, `plain` |
+
+## React
+
+```tsx
+import { Glider } from '@karmo-co/drift-kit/react';
+```
+
+## Component tokens
+
+`--dk-component-glider-height`, `--dk-component-glider-small-height`, `--dk-component-glider-large-height`, `--dk-component-glider-inset`, `--dk-component-glider-gap`, `--dk-component-glider-padding-inline`, `--dk-component-glider-small-padding-inline`, `--dk-component-glider-large-padding-inline`, `--dk-component-glider-font-family`, `--dk-component-glider-font-size`, `--dk-component-glider-line-height`, `--dk-component-glider-small-font-size`, `--dk-component-glider-small-line-height`, `--dk-component-glider-large-font-size`, `--dk-component-glider-large-line-height`, `--dk-component-glider-font-weight`, `--dk-component-glider-icon-size`, `--dk-component-glider-small-icon-size`, `--dk-component-glider-large-icon-size`, `--dk-component-glider-icon-gap`, `--dk-component-glider-surface`, `--dk-component-glider-border`, `--dk-component-glider-border-width`, `--dk-component-glider-radius`, `--dk-component-glider-shadow`, `--dk-component-glider-plain-border`, `--dk-component-glider-inset-surface`, `--dk-component-glider-inset-surface-hover`, `--dk-component-glider-inset-surface-active`, `--dk-component-glider-inset-border`, `--dk-component-glider-inset-toned-color`, `--dk-component-glider-ghost-surface`, `--dk-component-glider-ghost-border`, `--dk-component-glider-ghost-surface-hover`, `--dk-component-glider-ghost-surface-active`, `--dk-component-glider-indicator-surface`, `--dk-component-glider-indicator-surface-hover`, `--dk-component-glider-indicator-surface-active`, `--dk-component-glider-indicator-border`, `--dk-component-glider-indicator-border-hover`, `--dk-component-glider-indicator-border-active`, `--dk-component-glider-indicator-radius`, `--dk-component-glider-selected-color`, `--dk-component-glider-color`, `--dk-component-glider-color-hover`, `--dk-component-glider-surface-hover`, `--dk-component-glider-border-hover`, `--dk-component-glider-surface-active`, `--dk-component-glider-border-active`, `--dk-component-glider-color-disabled`, `--dk-component-glider-transition-duration`, `--dk-component-glider-slide-duration`, `--dk-component-glider-transition-easing`, `--dk-component-glider-slide-lag`, `--dk-component-glider-active-scale`

package/manifest/components/heading.md

@@ -0,0 +1,47 @@
+# Heading (`heading`)
+
+The outline tier: Inter, six responsive sizes, nine weights, the Body colour grammar.
+
+
+## Anatomy (HTML)
+
+```text
+h1..h6.dk-component-heading[data-size="xxlarge|xlarge|large|medium|small|xsmall"]?[data-weight]?[data-color]?[data-align]?
+```
+
+## Attributes
+
+| Attribute | Values the stylesheet styles |
+|---|---|
+| `data-align` | `center`, `left`, `right` |
+| `data-color` | `black`, `default`, `error`, `information`, `inverse`, `neutral`, `primary`, `success`, `warning`, `white` |
+| `data-disabled` | (present or absent) |
+| `data-emphasis` | `subtle` |
+| `data-size` | `large`, `medium`, `small`, `xlarge`, `xsmall`, `xxlarge`, `xxsmall` |
+| `data-style` | `italic` |
+| `data-trim` | `both`, `end`, `start` |
+| `data-weight` | `black`, `bold`, `extra-bold`, `extra-light`, `light`, `medium`, `regular`, `semi-bold`, `thin` |
+
+## React
+
+```tsx
+import { Heading } from '@karmo-co/drift-kit/react';
+```
+
+| Prop | Type | Notes |
+|---|---|---|
+| `size` | `\| 'xxlarge' \| 'xlarge' \| 'large' \| 'medium' \| 'small' \| 'xsmall' \| 'xxsmall'` |  |
+| `weight` | `HeadingWeight` |  |
+| `textStyle` | `'italic'` | React owns `style`, so the data-style axis is `textStyle`. This is the one place the mirror-the-HTML rule cannot hold. |
+| `as` | `ElementType` |  |
+| `color` | `Color` |  |
+| `emphasis` | `Emphasis` |  |
+| `align` | `Align` |  |
+| `trim` | `Trim` |  |
+| `disabled` | `boolean` | A span cannot carry :disabled, so the kit uses [data-disabled]. |
+| `children` | `ReactNode` |  |
+| `className` | `string` |  |
+
+## Component tokens
+
+`--dk-component-heading-font-family`, `--dk-component-heading-italic-font-style`, `--dk-component-heading-transition-duration`, `--dk-component-heading-xxlarge-font-size`, `--dk-component-heading-xxlarge-line-height`, `--dk-component-heading-xlarge-font-size`, `--dk-component-heading-xlarge-line-height`, `--dk-component-heading-large-font-size`, `--dk-component-heading-large-line-height`, `--dk-component-heading-medium-font-size`, `--dk-component-heading-medium-line-height`, `--dk-component-heading-small-font-size`, `--dk-component-heading-small-line-height`, `--dk-component-heading-xsmall-font-size`, `--dk-component-heading-xsmall-line-height`, `--dk-component-heading-xxsmall-font-size`, `--dk-component-heading-xxsmall-line-height`, `--dk-component-heading-thin-font-weight`, `--dk-component-heading-extra-light-font-weight`, `--dk-component-heading-light-font-weight`, `--dk-component-heading-regular-font-weight`, `--dk-component-heading-medium-font-weight`, `--dk-component-heading-semi-bold-font-weight`, `--dk-component-heading-bold-font-weight`, `--dk-component-heading-extra-bold-font-weight`, `--dk-component-heading-black-font-weight`, `--dk-component-heading-default-color`, `--dk-component-heading-inverse-color`, `--dk-component-heading-white-color`, `--dk-component-heading-black-color`, `--dk-component-heading-primary-color`, `--dk-component-heading-success-color`, `--dk-component-heading-error-color`, `--dk-component-heading-warning-color`, `--dk-component-heading-information-color`, `--dk-component-heading-neutral-default-color`, `--dk-component-heading-neutral-subtle-color`, `--dk-component-heading-disabled-color`

package/manifest/components/hero.md

@@ -0,0 +1,46 @@
+# Hero (`hero`)
+
+The display tier: Syne on the heading ramp, five responsive sizes, four weights, the Body colour grammar.
+
+
+## Anatomy (HTML)
+
+```text
+h1|h2.dk-component-hero[data-size="xxlarge|xlarge|large|medium|small"]?[data-weight]?[data-color]?[data-align]?
+```
+
+## Attributes
+
+| Attribute | Values the stylesheet styles |
+|---|---|
+| `data-align` | `center`, `left`, `right` |
+| `data-color` | `black`, `default`, `error`, `information`, `inverse`, `neutral`, `primary`, `success`, `warning`, `white` |
+| `data-disabled` | (present or absent) |
+| `data-emphasis` | `subtle` |
+| `data-size` | `large`, `medium`, `small`, `xlarge`, `xxlarge` |
+| `data-trim` | `both`, `end`, `start` |
+| `data-weight` | `bold`, `medium`, `regular`, `semi-bold` |
+
+## React
+
+```tsx
+import { Hero } from '@karmo-co/drift-kit/react';
+```
+
+| Prop | Type | Notes |
+|---|---|---|
+| `size` | `'xxlarge' \| 'xlarge' \| 'large' \| 'medium' \| 'small'` |  |
+| `weight` | `'regular' \| 'medium' \| 'semi-bold' \| 'bold'` |  |
+| `textStyle` | `` | React owns `style`, so the data-style axis is `textStyle`. This is the one place the mirror-the-HTML rule cannot hold. |
+| `as` | `ElementType` |  |
+| `color` | `Color` |  |
+| `emphasis` | `Emphasis` |  |
+| `align` | `Align` |  |
+| `trim` | `Trim` |  |
+| `disabled` | `boolean` | A span cannot carry :disabled, so the kit uses [data-disabled]. |
+| `children` | `ReactNode` |  |
+| `className` | `string` |  |
+
+## Component tokens
+
+`--dk-component-hero-font-family`, `--dk-component-hero-transition-duration`, `--dk-component-hero-xxlarge-font-size`, `--dk-component-hero-xxlarge-line-height`, `--dk-component-hero-xlarge-font-size`, `--dk-component-hero-xlarge-line-height`, `--dk-component-hero-large-font-size`, `--dk-component-hero-large-line-height`, `--dk-component-hero-medium-font-size`, `--dk-component-hero-medium-line-height`, `--dk-component-hero-small-font-size`, `--dk-component-hero-small-line-height`, `--dk-component-hero-regular-font-weight`, `--dk-component-hero-medium-font-weight`, `--dk-component-hero-semi-bold-font-weight`, `--dk-component-hero-bold-font-weight`, `--dk-component-hero-default-color`, `--dk-component-hero-inverse-color`, `--dk-component-hero-white-color`, `--dk-component-hero-black-color`, `--dk-component-hero-primary-color`, `--dk-component-hero-success-color`, `--dk-component-hero-error-color`, `--dk-component-hero-warning-color`, `--dk-component-hero-information-color`, `--dk-component-hero-neutral-default-color`, `--dk-component-hero-neutral-subtle-color`, `--dk-component-hero-disabled-color`

package/manifest/components/icon-button.md

@@ -0,0 +1,41 @@
+# Icon button (`icon-button`)
+
+A button whose whole label is its icon. Same rungs as Button, so the two line up in a row, plus one rung below Button's smallest because compact chrome is where most icon buttons actually live.
+
+
+## Anatomy (HTML)
+
+```text
+button.dk-component-icon-button[data-variant="subtle|ghost|plain|raised"]?[data-size="extra-small|small|medium|large"]?[aria-label][aria-pressed]?[data-pressed-glyph="fill"]?
+  svg | i.dk-component-icon   (the glyph)
+  span.__spinner?             (while .is-loading)
+```
+
+## Attributes
+
+| Attribute | Values the stylesheet styles |
+|---|---|
+| `data-pressed-glyph` | `fill` |
+| `data-pseudo-class` | `active`, `focus`, `hover` |
+| `data-size` | `extra-small`, `large`, `medium`, `small` |
+| `data-variant` | `ghost`, `plain`, `raised`, `subtle` |
+
+## React
+
+```tsx
+import { IconButton } from '@karmo-co/drift-kit/react';
+```
+
+| Prop | Type | Notes |
+|---|---|---|
+| `'aria-label'` | `string` |  |
+| `'aria-labelledby'` | `string` |  |
+| `icon` (required) | `ReactNode` | The glyph: one <svg>, an icon component, or an <i data-lucide>. The component sizes it to its rung. |
+| `variant` | `'subtle' \| 'ghost' \| 'plain' \| 'raised'` | subtle when absent: a tint of the surface it sits on. ghost and plain are transparent at rest; raised lifts it on an elevation. |
+| `size` | `'extra-small' \| 'small' \| 'medium' \| 'large'` | medium when absent. small, medium and large are Button's rungs and land on its heights, so the two line up in a row. |
+| `loading` | `boolean` | Button's loading state: a spinner in place of the glyph, aria-busy and aria-disabled, still focusable, clicks and Enter/Space blocked. |
+| `pressedGlyph` | `'fill'` | With aria-pressed: fill the glyph when on. For closed glyphs only (a heart, a star, a bookmark); a line glyph would fill to a blob. |
+
+## Component tokens
+
+`--dk-component-icon-button-extra-small-padding`, `--dk-component-icon-button-extra-small-line-height`, `--dk-component-icon-button-extra-small-icon-size`, `--dk-component-icon-button-extra-small-border-radius`, `--dk-component-icon-button-small-padding`, `--dk-component-icon-button-small-line-height`, `--dk-component-icon-button-small-icon-size`, `--dk-component-icon-button-small-border-radius`, `--dk-component-icon-button-medium-padding`, `--dk-component-icon-button-medium-line-height`, `--dk-component-icon-button-medium-icon-size`, `--dk-component-icon-button-medium-border-radius`, `--dk-component-icon-button-large-padding`, `--dk-component-icon-button-large-line-height`, `--dk-component-icon-button-large-icon-size`, `--dk-component-icon-button-large-border-radius`, `--dk-component-icon-button-extra-small-spinner-size`, `--dk-component-icon-button-small-spinner-size`, `--dk-component-icon-button-medium-spinner-size`, `--dk-component-icon-button-large-spinner-size`, `--dk-component-icon-button-spinner-border-width`, `--dk-component-icon-button-spinner-track`, `--dk-component-icon-button-spinner-head`, `--dk-component-icon-button-spin-duration`, `--dk-component-icon-button-focus-ring-width`, `--dk-component-icon-button-transform-scale-active`, `--dk-component-icon-button-subtle-surface-default`, `--dk-component-icon-button-subtle-surface-hover`, `--dk-component-icon-button-subtle-surface-active`, `--dk-component-icon-button-subtle-icon-default`, `--dk-component-icon-button-subtle-icon-hover`, `--dk-component-icon-button-subtle-icon-active`, `--dk-component-icon-button-subtle-ring`, `--dk-component-icon-button-ghost-surface-default`, `--dk-component-icon-button-ghost-surface-hover`, `--dk-component-icon-button-ghost-surface-active`, `--dk-component-icon-button-ghost-icon-default`, `--dk-component-icon-button-ghost-icon-hover`, `--dk-component-icon-button-ghost-icon-active`, `--dk-component-icon-button-ghost-ring`, `--dk-component-icon-button-plain-border-width`, `--dk-component-icon-button-plain-surface-default`, `--dk-component-icon-button-plain-surface-hover`, `--dk-component-icon-button-plain-surface-active`, `--dk-component-icon-button-plain-border-default`, `--dk-component-icon-button-plain-border-hover`, `--dk-component-icon-button-plain-border-active`, `--dk-component-icon-button-plain-icon-default`, `--dk-component-icon-button-plain-icon-hover`, `--dk-component-icon-button-plain-icon-active`, `--dk-component-icon-button-plain-ring`, `--dk-component-icon-button-raised-border-width`, `--dk-component-icon-button-raised-shadow`, `--dk-component-icon-button-raised-shadow-hover`, `--dk-component-icon-button-raised-shadow-active`, `--dk-component-icon-button-raised-surface-default`, `--dk-component-icon-button-raised-surface-hover`, `--dk-component-icon-button-raised-surface-active`, `--dk-component-icon-button-raised-border-default`, `--dk-component-icon-button-raised-border-hover`, `--dk-component-icon-button-raised-border-active`, `--dk-component-icon-button-raised-icon-default`, `--dk-component-icon-button-raised-icon-hover`, `--dk-component-icon-button-raised-icon-active`, `--dk-component-icon-button-pressed-icon-default`, `--dk-component-icon-button-pressed-icon-hover`, `--dk-component-icon-button-pressed-icon-active`, `--dk-component-icon-button-preview-fill-hover`, `--dk-component-icon-button-preview-fill-active`, `--dk-component-icon-button-raised-ring`, `--dk-component-icon-button-surface-disabled`, `--dk-component-icon-button-icon-disabled`

package/manifest/components/icon-tile.md

@@ -0,0 +1,44 @@
+# Icon tile (`icon-tile`)
+
+A glyph on a small coloured square, subtle or solid, with one corner at every size.
+
+
+## Anatomy (HTML)
+
+```text
+span.dk-component-icon-tile[data-status|data-hue][data-variant][data-size]
+  the glyph: a kit Icon, a Lucide <i>, an <svg> or an <img>
+```
+
+## Attributes
+
+| Attribute | Values the stylesheet styles |
+|---|---|
+| `data-disabled` | (present or absent) |
+| `data-highlighted` | `false` |
+| `data-hue` | `next1`, `next2`, `next3`, `next4`, `prev1`, `prev2`, `prev3`, `prev4`, `primary` |
+| `data-interactive` | (present or absent) |
+| `data-pseudo-class` | `active`, `hover` |
+| `data-size` | `24`, `32`, `40`, `56`, `64` |
+| `data-status` | `error`, `information`, `primary`, `success`, `warning` |
+| `data-tone-fill` | `solid` |
+| `data-variant` | `solid` |
+
+## React
+
+```tsx
+import { IconTile } from '@karmo-co/drift-kit/react';
+```
+
+| Prop | Type | Notes |
+|---|---|---|
+| `icon` (required) | `ReactNode` | The glyph: a kit icon, a Lucide icon, any svg. The tile sizes it. |
+| `status` | `'neutral' \| 'primary' \| 'success' \| 'error' \| 'warning' \| 'information'` | Neutral when absent, as a Tag's is. |
+| `hue` | `IconTileHue` | A category colour instead of a status. With status also set, hue wins. |
+| `variant` | `'subtle' \| 'solid'` | Subtle when absent. |
+| `size` | `24 \| 32 \| 40 \| 48 \| 56 \| 64` | 48 when absent. |
+| `label` | `string` | A name, for a tile that means something on its own. Without one the tile is decorative and hidden from a screen reader. |
+
+## Component tokens
+
+`--dk-component-icon-tile-radius`, `--dk-component-icon-tile-24-size`, `--dk-component-icon-tile-24-icon-size`, `--dk-component-icon-tile-32-size`, `--dk-component-icon-tile-32-icon-size`, `--dk-component-icon-tile-40-size`, `--dk-component-icon-tile-40-icon-size`, `--dk-component-icon-tile-48-size`, `--dk-component-icon-tile-48-icon-size`, `--dk-component-icon-tile-56-size`, `--dk-component-icon-tile-56-icon-size`, `--dk-component-icon-tile-64-size`, `--dk-component-icon-tile-64-icon-size`, `--dk-component-icon-tile-primary-solid`, `--dk-component-icon-tile-success-solid`, `--dk-component-icon-tile-error-solid`, `--dk-component-icon-tile-warning-solid`, `--dk-component-icon-tile-information-solid`

package/manifest/components/icon.md

@@ -0,0 +1,30 @@
+# Icon (`icon`)
+
+The icon primitive, built to behave like text: the same colour grammar, sizes named and fixed like the body rungs, weight as stroke width, and 1em when unsized.
+
+
+## Anatomy (HTML)
+
+```text
+i.dk-component-icon[data-lucide|data-karmo|data-card|...="<glyph>"][data-size="12..48"]?[data-color]?
+  (the runtime swaps in the svg)
+```
+
+## Attributes
+
+| Attribute | Values the stylesheet styles |
+|---|---|
+| `data-color` | `black`, `default`, `error`, `information`, `inverse`, `neutral`, `primary`, `success`, `warning`, `white` |
+| `data-disabled` | (present or absent) |
+| `data-emphasis` | `subtle` |
+| `data-icon-kind` | `picture` |
+| `data-size` | `12`, `14`, `16`, `20`, `24`, `28`, `32`, `40`, `48` |
+| `data-weight` | `bold`, `light`, `regular` |
+
+## React
+
+One component per glyph, per set: `import { Heart } from '@karmo-co/drift-kit/icons/lucide';`
+
+## Component tokens
+
+`--dk-component-icon-transition-duration`, `--dk-component-icon-light-stroke-width`, `--dk-component-icon-regular-stroke-width`, `--dk-component-icon-bold-stroke-width`, `--dk-component-icon-12-size`, `--dk-component-icon-14-size`, `--dk-component-icon-16-size`, `--dk-component-icon-20-size`, `--dk-component-icon-24-size`, `--dk-component-icon-28-size`, `--dk-component-icon-32-size`, `--dk-component-icon-40-size`, `--dk-component-icon-48-size`, `--dk-component-icon-default-color`, `--dk-component-icon-inverse-color`, `--dk-component-icon-white-color`, `--dk-component-icon-black-color`, `--dk-component-icon-primary-color`, `--dk-component-icon-success-color`, `--dk-component-icon-error-color`, `--dk-component-icon-warning-color`, `--dk-component-icon-information-color`, `--dk-component-icon-neutral-default-color`, `--dk-component-icon-neutral-subtle-color`, `--dk-component-icon-disabled-color`

package/manifest/components/input.md

@@ -0,0 +1,63 @@
+# Text input (`input`)
+
+Label, field and caption, with leading and trailing slots, three sizes, and error, disabled and read-only states.
+
+
+## Anatomy (HTML)
+
+```text
+div.dk-component-input[data-size="small|medium|large"]?[data-variant="raised"]?[data-leading-control]?
+  label.__label
+  div.__field
+    span.__leading?
+    input|select|textarea
+    span.__trailing?
+    button.__action?
+  p.__caption? | p.__error?
+```
+
+## Attributes
+
+| Attribute | Values the stylesheet styles |
+|---|---|
+| `data-appearance` | `sentence` |
+| `data-input-reveal` | (present or absent) |
+| `data-leading-control` | (present or absent) |
+| `data-open` | (present or absent) |
+| `data-raised` | (present or absent) |
+| `data-size` | `large`, `small` |
+| `data-tone` | `error`, `information`, `primary`, `success`, `warning` |
+| `data-variant` | `inset`, `raised` |
+| `data-when` | `hidden`, `shown` |
+
+## React
+
+```tsx
+import { Input } from '@karmo-co/drift-kit/react';
+```
+
+| Prop | Type | Notes |
+|---|---|---|
+| `label` | `ReactNode` | The visible label. Optional in the TYPE only: see InputProps below, where the union makes an unlabelled field legal exactly when it carries an aria-label or an aria-labelledby instead. A field with no name at all is not a field anyone can use, and that is still unreachable from here. |
+| `size` | `'small' \| 'medium' \| 'large'` |  |
+| `caption` | `ReactNode` | Helper text. Rendered as the control's DESCRIPTION, never part of its name: the markup this component replaces wrapped label, field and caption in one <label>, which made every Karmo field announce its helper text as part of its own name. |
+| `error` | `ReactNode` | The message AND the invalid state. One prop so the border, the words and aria-invalid cannot disagree; there is deliberately no separate `invalid` boolean. |
+| `leading` | `ReactNode` |  |
+| `trailing` | `ReactNode` |  |
+| `required` | `boolean` | Marks the control required and renders the asterisk. The asterisk is decorative; the native attribute is what carries the meaning. |
+| `revealable` | `boolean` | A reveal toggle for type="password". Flips the control to type="text" and back, and moves aria-pressed with it. |
+| `clearable` | `boolean` | A clear button, shown only while there is something to clear. |
+| `clearPrefix` | `string` | Text Clear keeps, a phone field's dial code: Clear sets the value back to it, and a field holding only it has nothing to clear. Rendered as data-input-prefix, as the HTML runtime reads it. |
+| `raised` | `boolean` | Lifts the field off the surface on an elevation instead of sitting flush in it. The shadow is the whole of it: padding and height still come from the size rung. This is what Search bar was until 14.0.0: raised, large, no label, a magnifier in `leading` and a placeholder. See components/input/styles.css for why that component became an attribute on this one. Kept as an alias of variant="raised". |
+| `variant` | `'plain' \| 'raised' \| 'inset'` | How the field separates from the surface, as Select'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. |
+| `help` | `string` | Help text behind an info button in the field. ONE prop, not the reference's three (showHelp, helpIcon, helpTooltipContent): its presence renders the button, its content is the tooltip, so they cannot disagree. Typed string rather than ReactNode because the kit's tooltip renders textContent, and a prop that silently drops the markup you passed it is worse than one that never offered to take it. |
+| `revealLabels` | `{ show: string; hide: string }` | Overridable because these are announced, and a page in another language should not be stuck with English. |
+| `clearLabel` | `string` |  |
+| `helpLabel` | `string` | The help button's NAME, not its tip. Defaults to "Help"; the tip itself reaches a screen reader as the description, wired by the tooltip. |
+| `className` | `string` |  |
+| `'aria-label'` (required) | `string` |  |
+| `'aria-labelledby'` (required) | `string` |  |
+
+## Component tokens
+
+`--dk-component-input-small-padding-y`, `--dk-component-input-padding-y`, `--dk-component-input-large-padding-y`, `--dk-component-input-small-height`, `--dk-component-input-height`, `--dk-component-input-large-height`, `--dk-component-input-label-font-family`, `--dk-component-input-label-font-size`, `--dk-component-input-label-line-height`, `--dk-component-input-label-letter-spacing`, `--dk-component-input-label-font-weight`, `--dk-component-input-border-width`, `--dk-component-input-focus-ring-width`, `--dk-component-input-action-radius`, `--dk-component-input-caption-font-size`, `--dk-component-input-caption-line-height`, `--dk-component-input-font-weight`, `--dk-component-input-padding-inline`, `--dk-component-input-large-padding-inline`, `--dk-component-input-sentence-border`, `--dk-component-input-sentence-surface`, `--dk-component-input-sentence-text`, `--dk-component-input-sentence-font-weight`, `--dk-component-input-sentence-font-size`, `--dk-component-input-sentence-line-height`, `--dk-component-input-sentence-small-font-size`, `--dk-component-input-sentence-small-line-height`, `--dk-component-input-sentence-large-font-size`, `--dk-component-input-sentence-large-line-height`, `--dk-component-input-sentence-padding-inline`, `--dk-component-input-sentence-chevron-size`, `--dk-component-input-sentence-value-min-width`, `--dk-component-input-sentence-margin-inline`, `--dk-component-input-raised-shadow`, `--dk-component-input-raised-shadow-hover`, `--dk-component-input-inset-surface`, `--dk-component-input-inset-surface-hover`, `--dk-component-input-inset-surface-active`, `--dk-component-input-inset-action-hover`, `--dk-component-input-inset-action-active`, `--dk-component-input-inset-border`, `--dk-component-input-inset-text`, `--dk-component-input-inset-placeholder`, `--dk-component-input-inset-icon`, `--dk-component-input-inset-affix`, `--dk-component-input-inset-icon-subtle`, `--dk-component-input-inset-icon-subtle-hover`, `--dk-component-input-inset-icon-primary`, `--dk-component-input-inset-icon-success`, `--dk-component-input-inset-icon-error`, `--dk-component-input-inset-icon-warning`, `--dk-component-input-inset-icon-information`, `--dk-component-input-radius`, `--dk-component-input-gap`, `--dk-component-input-slot-gap`, `--dk-component-input-leading-control-divider`, `--dk-component-input-leading-control-divider-width`, `--dk-component-input-leading-control-gap`, `--dk-component-input-leading-icon-color`, `--dk-component-input-leading-icon-color-hover`, `--dk-component-input-leading-icon-color-focus`, `--dk-component-input-slot-icon-size`, `--dk-component-input-small-slot-icon-size`, `--dk-component-input-large-slot-icon-size`, `--dk-component-input-action-size`, `--dk-component-input-action-glyph-size`, `--dk-component-input-small-action-size`, `--dk-component-input-small-action-glyph-size`, `--dk-component-input-large-action-size`, `--dk-component-input-large-action-glyph-size`, `--dk-component-input-error-color`, `--dk-component-input-obscured-font-family`, `--dk-component-input-font-size`, `--dk-component-input-line-height`, `--dk-component-input-small-font-size`, `--dk-component-input-small-line-height`, `--dk-component-input-large-font-size`, `--dk-component-input-large-line-height`

package/manifest/components/link.md

@@ -0,0 +1,42 @@
+# Link (`link`)
+
+A way to go somewhere. Inline, it is the sentence it sits in; standalone, it has its own size and room for an icon.
+
+
+## Anatomy (HTML)
+
+```text
+a.dk-component-link[data-variant][data-standalone][data-size][data-show-visited]
+  span.dk-component-link__icon            (standalone only, aria-hidden)
+  the text
+  span.dk-component-link__icon[data-trailing]
+```
+
+## Attributes
+
+| Attribute | Values the stylesheet styles |
+|---|---|
+| `data-pseudo-class` | `active`, `focus`, `hover`, `visited` |
+| `data-show-visited` | (present or absent) |
+| `data-size` | `large`, `small` |
+| `data-standalone` | (present or absent) |
+| `data-trailing` | (present or absent) |
+| `data-variant` | `neutral` |
+
+## React
+
+```tsx
+import { Link } from '@karmo-co/drift-kit/react';
+```
+
+| Prop | Type | Notes |
+|---|---|---|
+| `as` | `C` | The element or component to render, react-router's Link most often, so navigation stays client-side. Its own props (`to`) are typed from it: the props below are Link's, everything else is whatever `as` accepts. |
+| `variant` | `'primary' \| 'neutral'` |  |
+| `showVisited` | `boolean` | Opt-in visited styling, for docs and long-form content. App UI leaves it off. |
+| `disabled` | `boolean` | Renders a plain <a aria-disabled="true"> with no href, whatever `as` is: a router Link always navigates, so it cannot be disabled. Prefer removing a link to disabling it. |
+| `children` | `ReactNode` |  |
+
+## Component tokens
+
+`--dk-component-link-color-default`, `--dk-component-link-color-hover`, `--dk-component-link-color-active`, `--dk-component-link-underline-color-default`, `--dk-component-link-neutral-color-default`, `--dk-component-link-neutral-underline-color`, `--dk-component-link-visited-color`, `--dk-component-link-disabled-color`, `--dk-component-link-underline-thickness-default`, `--dk-component-link-underline-thickness-hover`, `--dk-component-link-underline-offset`, `--dk-component-link-small-font-size`, `--dk-component-link-small-line-height`, `--dk-component-link-medium-font-size`, `--dk-component-link-medium-line-height`, `--dk-component-link-large-font-size`, `--dk-component-link-large-line-height`, `--dk-component-link-font-weight`, `--dk-component-link-small-icon-size`, `--dk-component-link-medium-icon-size`, `--dk-component-link-large-icon-size`, `--dk-component-link-gap`, `--dk-component-link-icon-travel`, `--dk-component-link-focus-ring-width`, `--dk-component-link-focus-ring-offset`, `--dk-component-link-focus-ring-radius`, `--dk-component-link-external-icon-size`, `--dk-component-link-external-icon-gap`, `--dk-component-link-external-icon`, `--dk-component-link-motion-duration`, `--dk-component-link-motion-easing`

package/manifest/components/loading-spinner.md

@@ -0,0 +1,42 @@
+# Loading spinner (`loading-spinner`)
+
+The brand symbol inside a sweeping arc. It spins for at least half a second, so a fast load does not flash, and tells you when it has gone.
+
+
+## Anatomy (HTML)
+
+```text
+div.dk-component-loading-spinner[data-size="small|medium|large"]?
+  span.__message?
+  (the arc and the brand symbol are drawn by the runtime)
+```
+
+## Attributes
+
+| Attribute | Values the stylesheet styles |
+|---|---|
+| `data-animation` | `enter`, `exit` |
+| `data-color` | `neutral` |
+| `data-size` | `large`, `small`, `xsmall` |
+| `data-variant` | `ring` |
+
+## React
+
+```tsx
+import { LoadingSpinner } from '@karmo-co/drift-kit/react';
+```
+
+| Prop | Type | Notes |
+|---|---|---|
+| `size` | `'xsmall' \| 'small' \| 'medium' \| 'large'` |  |
+| `variant` | `'symbol' \| 'ring'` |  |
+| `color` | `'primary' \| 'neutral'` | neutral is grayscale: the arc, and the mark in the symbol variant. |
+| `animation` | `'enter' \| 'exit'` | "enter" shows it; "exit" plays the exit once 500ms have passed since enter, then unmounts and calls onExitComplete. |
+| `onExitComplete` | `() => void` |  |
+| `label` | `string` |  |
+| `message` | `string` | Text under the spinner, "Loading reports". It is also the accessible name unless label is given. |
+| `brand` | `LogoBrand` |  |
+
+## Component tokens
+
+`--dk-component-loading-spinner-color`, `--dk-component-loading-spinner-neutral-color`, `--dk-component-loading-spinner-message-gap`, `--dk-component-loading-spinner-message-font-size`, `--dk-component-loading-spinner-message-line-height`, `--dk-component-loading-spinner-message-font-weight`, `--dk-component-loading-spinner-message-color`, `--dk-component-loading-spinner-message-max-width`, `--dk-component-loading-spinner-tail-start`, `--dk-component-loading-spinner-ring-tail-start`, `--dk-component-loading-spinner-ring-xsmall-size`, `--dk-component-loading-spinner-ring-xsmall-stroke`, `--dk-component-loading-spinner-ring-small-size`, `--dk-component-loading-spinner-ring-medium-size`, `--dk-component-loading-spinner-ring-large-size`, `--dk-component-loading-spinner-small-logo-size`, `--dk-component-loading-spinner-small-gap`, `--dk-component-loading-spinner-small-stroke`, `--dk-component-loading-spinner-medium-logo-size`, `--dk-component-loading-spinner-medium-gap`, `--dk-component-loading-spinner-medium-stroke`, `--dk-component-loading-spinner-large-logo-size`, `--dk-component-loading-spinner-large-gap`, `--dk-component-loading-spinner-large-stroke`, `--dk-component-loading-spinner-spin-duration`, `--dk-component-loading-spinner-ring-spin-duration`, `--dk-component-loading-spinner-enter-duration`, `--dk-component-loading-spinner-exit-duration`, `--dk-component-loading-spinner-exit-delay`, `--dk-component-loading-spinner-fade-duration`, `--dk-component-loading-spinner-fade-delay`, `--dk-component-loading-spinner-enter-easing`, `--dk-component-loading-spinner-exit-easing`