@momoi-labs/kiso 0.1.0 → 0.3.0

package/kiso/AGENTS.md

@@ -45,6 +45,13 @@ documented; it does not become Kiso by repetition or copy-paste.
 6. If no contract fits, describe the gap and propose an addition. Do not
    create a parallel local system.
 
-Kiso is spec-first: its Markdown files are contracts, not implementation code.
+Kiso is spec-first: its Markdown files are contracts and carry no
+implementation code. Two files carry implementation instead —
+[`ui.css`](ui.css), the component layer, published as
+`@momoi-labs/kiso/ui.css`; and [`blocks/`](blocks/README.md), reference
+screens built from it, meant to be copied and not published. Neither is a
+contract: when one disagrees with a contract, the contract is right and the
+implementation is the bug.
+
 Deliberate omissions and the evidence-based growth model are recorded in
 [`docs/evolution.md`](docs/evolution.md).

package/kiso/README.md

@@ -2,9 +2,13 @@
 
 Kiso is the Momoi Labs product design system. It combines product identity,
 semantic tokens, component contracts, and reusable screen patterns so products
-with different purposes still belong to the same family. Kiso v1 is spec-first:
-it documents what to build and how it behaves; it does not ship component
-implementation code.
+with different purposes still belong to the same family. Kiso is spec-first:
+its Markdown files document what to build and how it behaves, and they carry
+no implementation. Two files are the exception: [`ui.css`](ui.css), the
+component layer every contract's visual values resolve through, and
+[`blocks/`](blocks/README.md), reference screens built from it to copy from.
+Neither overrides a contract — if a block and a contract disagree, the
+contract is right.
 
 ## For agents
 
@@ -39,6 +43,7 @@ keyboard flow where relevant.
 | Path | Purpose |
 | --- | --- |
 | [`AGENTS.md`](AGENTS.md) | Consumption contract and decision boundaries |
+| [`ui.css`](ui.css) | Component layer — published as `@momoi-labs/kiso/ui.css` |
 | [`docs/brand.md`](docs/brand.md) | Product personality and visual direction |
 | [`docs/principles.md`](docs/principles.md) | Design principles and tie-breakers |
 | [`docs/voice-and-tone.md`](docs/voice-and-tone.md) | Product UI copy rules |
@@ -48,10 +53,27 @@ keyboard flow where relevant.
 | [`docs/data-interfaces.md`](docs/data-interfaces.md) | Data-heavy interface rules |
 | [`docs/accessibility.md`](docs/accessibility.md) | Accessibility requirements across all layers |
 | [`docs/evolution.md`](docs/evolution.md) | Deliberate deferrals and evidence-based growth |
+| [`blocks/`](blocks/README.md) | Reference screens built from `ui.css` (not published) |
 
 Token sources and generated artifacts live in the repository-level `tokens/`
 directory; validation scripts live in `scripts/`.
 
+## Installing
+
+Contracts, tokens, and the component layer ship in one versioned package, so a
+project pins the whole system to a single version:
+
+```bash
+npm install @momoi-labs/kiso
+```
+
+```css
+@import "@momoi-labs/kiso/tokens.css";
+@import "@momoi-labs/kiso/ui.css";
+```
+
+`ui.css` reads tokens as custom properties, so import it after `tokens.css`.
+
 ## Proposing a change
 
 First confirm that an existing token, component, or pattern cannot express the

package/kiso/docs/accessibility.md

@@ -29,8 +29,24 @@ a keyboard, screen reader, touch input, or reduced-motion preference.
 - Every interactive element must be reachable and operable by keyboard, with a
   visible focus indicator. Keep focus order aligned with reading and visual
   order; do not use positive `tabindex` values.
-- Interactive touch targets must be at least 44 by 44 CSS pixels. A visible
-  control may be smaller only when its interactive hit area reaches that size
+- <a id="target-size"></a>**Target size applies to coarse pointers.** On a
+  coarse pointer, interactive targets must be at least 44 by 44 CSS pixels
+  (`--size-touch-min`). Apply it as a `min-height` inside
+  `@media (pointer: coarse)`, on top of the control's own
+  own control-size height:
+
+  ```css
+  .btn { height: var(--size-control-md); }        /* 36px */
+
+  @media (pointer: coarse) {
+    .btn { min-height: var(--size-touch-min); }   /* 44px */
+  }
+  ```
+
+  Do not use 44px as the control height on a fine pointer. It is an
+  accessibility floor for fingers, not a design value, and applying it on the
+  desktop is what makes a dense interface look like a toy. A visible control
+  may be smaller than its hit area, provided the hit area reaches the minimum
   without overlapping another target.
 - Give icon-only controls an accessible name. Decorative icons must be hidden
   from assistive technology.

package/kiso/docs/brand.md

@@ -68,7 +68,9 @@ afterthought — starts here.
 Kiso's palette is dark-first, with a light alternate, mirroring the marketing
 site's spirit:
 
-- **Dark theme** is the default product surface.
+- **Dark theme** is the reference surface: the one the palette is designed
+  against. It is not the default *setting* — the default is to follow the
+  operating system. See [ThemeSelector](components/theme-selector.md).
 - **Light theme** ("slate") is a first-class alternate, not an afterthought.
 - **Neutrals** carry the interface; one **accent** carries attention.
 - **Inter** for interface text, **JetBrains Mono** for code and data values.

package/kiso/docs/components/README.md

@@ -22,6 +22,7 @@ token consumption, and a Radix/shadcn behavioral reference where one exists.
 - [Spinner](spinner.md) — Signals indeterminate work when the final layout is not represented.
 - [Switch](switch.md) — Changes one immediately applied boolean setting.
 - [Textarea](textarea.md) — Collects multi-line free-form text.
+- [ThemeSelector](theme-selector.md) — Chooses between following the system colour scheme, forcing light, or forcing dark.
 - [Tooltip](tooltip.md) — Adds nonessential pointer or keyboard context as progressive enhancement.
 - [ValidationMessage](validation-message.md) — Explains a field-level validation error and how to fix it.
 

package/kiso/docs/components/alert.md

@@ -60,7 +60,10 @@ Four severities. There is no extra "destructive" variant — that is `error`.
 | `warning` | `role="status"` (polite) unless the person must stop; then `role="alert"` | `--color-warning`. |
 | `error` | `role="alert"` (assertive) | `--color-danger` (the danger role *is* error). |
 
-Radius `--radius-md`. Padding `--spacing-md`. Gap `--spacing-sm`. Title
+Radius `--radius-lg`; an Alert is a callout inside content, not a panel, so it
+carries no corner marks. Tinted variants use `--color-success-surface` /
+`--color-warning-surface` / `--color-danger-surface` / `--color-info-surface`
+with the matching `*-border`. Padding `--spacing-md`. Gap `--spacing-sm`. Title
 uses the five `--type-role-label-font-family`, `--type-role-label-font-size`,
 `--type-role-label-font-weight`, `--type-role-label-letter-spacing`, and
 `--type-role-label-line-height` properties. Description uses the corresponding

package/kiso/docs/components/button.md

@@ -50,29 +50,39 @@ Four variants. Do not add a "link" variant; navigation is [Link](link.md).
 
 | Variant | When | Tokens |
 | --- | --- | --- |
-| `default` | Secondary action on the current task. Most buttons. | Background `--color-surface`, text `--color-foreground`, border `--color-border`. Hover background `--color-elevated-surface`. |
-| `primary` | The one action that advances the current task. At most one primary Button per region. | Background `--color-surface`, text and border `--color-primary`, label `--type-weight-semibold`. Hover background `--color-elevated-surface`. |
-| `destructive` | Irreversible or destructive action (delete, drop, disconnect). User story #4. | Background `--color-surface`, text and border `--color-danger`. Hover background `--color-elevated-surface`. Match confirmation weight to stakes; see voice-and-tone. |
-| `ghost` | Low-emphasis action in chrome, toolbars, or inside a Card. | Transparent background and border. Text `--color-foreground`. Hover background `--color-surface`. |
+| `default` | Secondary action on the current task. Most buttons. | Background `--color-card`, border `--color-input`, text `--color-foreground`, `--shadow-xs`. Hover background `--color-accent-surface`. |
+| `primary` | The one action that advances the current task. At most one primary Button per region. | Background `--color-primary`, text `--color-primary-foreground`, transparent border, `--shadow-xs`. Hover background `--color-primary-hover`. |
+| `destructive` | Irreversible or destructive action (delete, drop, disconnect). User story #4. | Background `--color-danger`, text `--color-danger-foreground`, transparent border, `--shadow-xs`. Match confirmation weight to stakes; see voice-and-tone. |
+| `ghost` | Low-emphasis action in chrome, toolbars, or inside a Card. | Transparent background and border. Text `--color-muted-foreground`. Hover background `--color-accent-surface-hover`, text `--color-foreground`. |
 
-`primary` and `danger` are text roles (checked against surfaces in the AA
-gate). `--color-background` is canvas and is never text, so these variants
-are **not** filled inversions. A filled "on-primary" treatment would need a
-new semantic role; do not invent one here and do not borrow the canvas
-role as ink.
+`primary` and `destructive` are **solid fills**. The accent is the fill; the
+label is `--color-primary-foreground` or `--color-danger-foreground`, which
+inverts with the fill and is gated at 4.5:1 against it.
+
+Do not render `primary` as an outline — accent text on a surface with an accent
+border. That treatment reads as a secondary control, and in a violet system it
+is what makes the primary action look grey.
 
 If a destructive action is not irreversible (archive, disable, hide), use
 `default` or `ghost`, not `destructive`.
 
 ## Sizes
 
-| Size | Type role | Padding | Radius | Use |
-| --- | --- | --- | --- | --- |
-| `sm` | Label properties (`--type-role-label-font-family`, `--type-role-label-font-size`, `--type-role-label-font-weight`, `--type-role-label-letter-spacing`, `--type-role-label-line-height`) | `--spacing-xs` block, `--spacing-sm` inline | `--radius-sm` | Dense tables, Card footers, compact filters. |
-| `md` (default) | Same label properties | `--spacing-sm` block, `--spacing-md` inline | `--radius-md` | Forms, page actions, dialogs. |
-| `lg` | Same label properties | `--spacing-md` block, `--spacing-lg` inline | `--radius-md` | Rare; empty-state or onboarding primary actions. |
+Height comes from a control-size token, not from padding. Padding sets the inline
+measure only.
+
+| Size | Height | Type role | Inline padding | Radius | Use |
+| --- | --- | --- | --- | --- | --- |
+| `xs` | `--size-control-xs` | Label properties | `--spacing-sm` | `--radius-sm` | Inline row actions in dense tables. |
+| `sm` | `--size-control-sm` | Label properties (`--type-role-label-font-family`, `--type-role-label-font-size`, `--type-role-label-font-weight`, `--type-role-label-letter-spacing`, `--type-role-label-line-height`) | `--spacing-md` | `--radius-md` | Toolbars, Card footers, compact filters. |
+| `md` (default) | `--size-control-md` | Body properties | `--spacing-md` | `--radius-md` | Forms, page actions, dialogs. |
+| `lg` | `--size-control-lg` | Body properties | `--spacing-lg` | `--radius-md` | Rare; empty-state or onboarding primary actions. |
+
+`md` is 36px. It is **not** `--size-touch-min`: on a coarse pointer, add
+`min-height: var(--size-touch-min)` inside `@media (pointer: coarse)` and leave
+the desktop height alone. See [Accessibility](../accessibility.md#target-size).
 
-Do not invent a fourth size. Page-level calls to action still use `md` or
+Do not invent a fifth size. Page-level calls to action still use `md` or
 `lg`. PageHeader (navigation slice) composes Buttons; it is not a Button
 size.
 

package/kiso/docs/components/card.md

@@ -53,17 +53,53 @@ shape.
 
 | Variant | When | Tokens |
 | --- | --- | --- |
-| `plain` (default) | Grouping on the page canvas. | Background `--color-surface`, border `--color-border`, radius `--radius-lg`, padding `--spacing-lg`. No shadow. |
-| `elevated` | The grouping must lift above nearby surfaces (a floating picker, a featured summary). | Background `--color-elevated-surface`, border `--color-border`, shadow `--shadow-sm`. Same radius and padding. |
+| `plain` (default) | Grouping on the page canvas. | Background `--color-card`, border `--color-border`, radius `--radius-surface`, padding `--spacing-lg`, `--shadow-xs`. |
+| `elevated` | The grouping must lift above nearby surfaces (a floating picker, a featured summary). | Background `--color-popover`, border `--color-border`, shadow `--shadow-sm`. Same radius and padding. |
 
-Default is `plain`. Tokens.md assigns `--color-surface` to "cards, panels,
-and table rows" and `--color-elevated-surface` to "menus, popovers, and
-dialogs". Use `elevated` only when the Card is competing with other surfaces
-and needs that lift — not on every tile.
+Default is `plain`. `--color-card` is the panel fill and `--color-popover` the
+elevated one. Use `elevated` only when the Card is competing with other
+surfaces and needs that lift — not on every tile. A recessed band inside a Card
+— header strip, footer, table head — uses `--color-muted`.
 
 Do not add outline/ghost Card variants. If the grouping needs no surface,
 it is a section with a heading, not a Card.
 
+## Corner marks
+
+This is the shared panel contract. Card, [Table](table.md) wrapper,
+[ModalDialog](modal-dialog.md), [Drawer](drawer.md),
+[CommandPalette](command-palette.md), and code or log blocks are **panels**:
+square (`--radius-surface`) with corner marks. Popover, DropdownMenu, Toast,
+Alert, and Tooltip are transient chrome, not panels: they keep a small radius
+and carry no marks.
+
+A corner mark is an open registration mark: **two 1px ticks per corner**, each
+lying along the frame line it extends and stopping `--corner-mark-gap` short of
+it, so the mark points at the corner without touching it.
+
+| Token | Value | Meaning |
+| --- | --- | --- |
+| `--color-corner-mark` | `--color-border-strong` | Tick colour. |
+| `--corner-mark` | `1` | Opacity: marks on (`1`) or off (`0`). |
+| `--corner-mark-tick` | 4px | Length of one tick. |
+| `--corner-mark-gap` | 2px | Distance from tick end to the frame. |
+
+Two ticks, not four. A full cross puts its other two arms directly on top of
+the panel's 1px border, where they are invisible — the mark reads as a bracket
+regardless. Drawing four is wasted paint and makes the hollow centre look
+accidental.
+
+The gap is the mark. Close it and this is just a thicker border.
+
+Marks go on every panel, without exception. There is no rounded mode and no
+`data-corners` attribute; the corner language was decided once and is not a
+per-product setting.
+
+Draw them on one pseudo-element inset by `calc(-1 * (var(--corner-mark-tick) +
+var(--corner-mark-gap)))`, so no markup and no images are needed. If the panel
+scrolls, move `overflow` to an inner element — the marks sit just outside the
+frame and a scrolling wrapper clips them away.
+
 ## Sizes
 
 Size changes padding and gap, not type roles.

package/kiso/docs/components/command-palette.md

@@ -63,7 +63,8 @@ Do not ship separate palettes per page unless the product truly scopes
 commands; default is one app-level palette.
 
 Surface: `--color-elevated-surface`, border `--color-border`, shadow
-`--shadow-sm`, radius `--radius-lg`. Input and items use foreground /
+`--shadow-lg`, radius `--radius-surface`, with corner marks — the palette is a
+panel. Input and items use foreground /
 muted-foreground roles. Active (highlighted) item uses `--color-surface` or
 a quiet `--color-primary` indicator without filling the row in primary ink.
 
@@ -145,8 +146,10 @@ properties for group headings.
 `--color-elevated-surface`, `--color-surface`, `--color-foreground`,
 `--color-muted-foreground`, `--color-subtle-foreground`, `--color-border`,
 `--color-primary` (highlight affordance only), `--color-focus`,
-`--color-disabled`, `--shadow-sm`, `--spacing-sm` / `--spacing-md`,
-`--radius-lg`, `--motion-duration-fast`, and `--motion-easing-standard`.
+`--color-disabled`, `--shadow-lg`, `--spacing-sm` / `--spacing-md`,
+`--radius-surface`, `--color-popover`, `--color-selected`,
+`--color-corner-mark`, `--corner-mark`, `--corner-mark-tick`,
+`--corner-mark-gap`, `--motion-duration-fast`, and `--motion-easing-standard`.
 Items use `--type-role-body-font-family`, `--type-role-body-font-size`,
 `--type-role-body-font-weight`, `--type-role-body-letter-spacing`, and
 `--type-role-body-line-height`; group headings use the equivalent five

package/kiso/docs/components/drawer.md

@@ -26,7 +26,9 @@ Drawer Root
 ```
 
 Content uses `--color-elevated-surface`, `--color-foreground`,
-`--color-border`, `--spacing-lg` padding, `--radius-lg`, and `--shadow-md`.
+`--color-border`, `--spacing-lg` padding, `--radius-surface`, and
+`--shadow-lg`. The scrim uses `--color-overlay`. Panels are square (`--radius-surface`) and carry corner marks. See
+[Card](card.md#corner-marks) for the shared panel contract.
 Entry/exit uses `--motion-duration-normal` and `--motion-easing-standard`, with
 no travel under reduced motion.
 

package/kiso/docs/components/dropdown-menu.md

@@ -75,7 +75,8 @@ Content tokens: background `--color-elevated-surface`, border
 `--color-border`, text `--color-foreground`, muted hints
 `--color-muted-foreground`, destructive `--color-danger`, focus/highlight
 `--color-focus` / quiet `--color-surface` for the highlighted item. Radius
-`--radius-md`. Padding `--spacing-xs` around the list; item padding
+`--radius-lg` on the menu, `--radius-md` on each item; transient chrome, so no
+corner marks. Padding `--spacing-xs` around the list; item padding
 `--spacing-sm` / `--spacing-md`.
 
 ## Sizes
@@ -156,7 +157,8 @@ Content tokens: background `--color-elevated-surface`, border
 `--color-elevated-surface`, `--color-surface`, `--color-foreground`,
 `--color-muted-foreground`, `--color-border`, `--color-danger`,
 `--color-focus`, `--color-disabled`, `--spacing-xs` list padding,
-`--spacing-sm` / `--spacing-md` item padding, `--radius-md`, `--shadow-sm`,
+`--spacing-sm` / `--spacing-md` item padding, `--radius-lg`, `--radius-md`,
+`--color-popover`, `--color-selected`, `--shadow-md`,
 the five property-qualified body typography tokens for items, the five label
 typography tokens for group labels, `--motion-duration-fast`, and
 `--motion-easing-standard`. Trigger consumes Button/IconButton tokens. No raw

package/kiso/docs/components/empty-state.md

@@ -123,7 +123,9 @@ PageHeader.
 
 `--color-foreground`, `--color-muted-foreground`, `--color-surface` /
 `--color-background`, optional icon `--color-muted-foreground`, `--spacing-lg`
-padding (`--spacing-md` for `sm`), `--spacing-sm` gap, `--radius-md`, and
+padding (`--spacing-md` for `sm`), `--spacing-sm` gap, `--radius-lg` on the
+icon frame, the hatch tokens (`--color-hatch`, `--hatch-line`,
+`--hatch-period`, `--hatch-angle`), and
 `--motion-duration-fast` / `--motion-easing-standard`. Typography uses every
 property of the selected heading, label, and body roles named above. Action consumes Button/Link
 tokens. No raw hex/px.

package/kiso/docs/components/modal-dialog.md

@@ -24,7 +24,10 @@ Dialog Root
 ```
 
 Content uses `--color-elevated-surface`, `--color-foreground`,
-`--color-border`, `--radius-lg`, `--spacing-lg` padding, and `--shadow-md`.
+`--color-border`, `--radius-surface`, `--spacing-lg` padding, and
+`--shadow-lg`. A Dialog is a panel: it carries corner marks. The scrim uses
+`--color-overlay`. Panels are square (`--radius-surface`) and carry corner marks. See
+[Card](card.md#corner-marks) for the shared panel contract.
 Overlay transitions use `--motion-duration-normal` and
 `--motion-easing-standard`.
 

package/kiso/docs/components/popover.md

@@ -21,7 +21,9 @@ Popover
 ```
 
 Content uses `--color-elevated-surface`, `--color-foreground`,
-`--color-border`, `--radius-md`, `--spacing-md` padding, and `--shadow-md`.
+`--color-popover`, `--color-border`, `--radius-lg`, `--spacing-md` padding,
+and `--shadow-md`. A Popover is transient chrome, not a panel: it keeps a small
+radius and carries no corner marks.
 Placement offset uses `--spacing-xs`, collision padding uses `--spacing-md`,
 and motion uses `--motion-duration-fast` with `--motion-easing-standard`.
 

package/kiso/docs/components/skeleton.md

@@ -41,7 +41,7 @@ Variants are shapes, not colors.
 | Variant | Shape tokens | Stands in for |
 | --- | --- | --- |
 | `text` | Height of the target role's `--type-role-body-line-height`, `--type-role-label-line-height`, or `--type-role-heading-line-height`; width a fraction of the column; radius `--radius-sm` | Titles, labels, table cells, descriptions. |
-| `block` | Radius `--radius-md` (or `--radius-lg` when replacing a Card) | Cards, images, chart frames, table bodies as a whole. |
+| `block` | Radius `--radius-md` (or `--radius-surface` when replacing a Card or panel) | Cards, images, chart frames, table bodies as a whole. |
 | `circle` | Radius `--radius-full`, equal width and height | Avatars and circular IconButtons. |
 
 Fill is `--color-border` on the surrounding `--color-surface` or

package/kiso/docs/components/table.md

@@ -111,7 +111,7 @@ Table has no `sm` / `md` / `lg` control scale like Button. Size comes from:
 | --- | --- |
 | Type | All five property-qualified body typography tokens for cells; all five property-qualified label typography tokens for headers. |
 | Cell padding | Density table above (`--spacing-xs`, `--spacing-sm`, and `--spacing-md`). |
-| Radius | Outer wrapper `--radius-md` when the table sits in a framed panel; internal cells are square. |
+| Radius | Outer wrapper `--radius-surface`; internal cells are square. The wrapper is a panel and carries corner marks. Scrolling moves to an inner element so the marks, which sit just outside the frame, are not clipped. |
 | Checkbox / IconButton in cells | `sm` controls so row height stays dense. |
 
 Do not invent a fourth density. Do not set row height in raw pixels.
@@ -231,7 +231,11 @@ Consume only semantic roles: `--color-background`, `--color-surface`,
 `--color-border`, `--color-primary`, `--color-focus`, `--color-disabled`,
 `--color-danger` (via Alert on error); the five property-qualified body and
 label typography tokens; `--spacing-xs`, `--spacing-sm`, `--spacing-md`;
-`--radius-md`; `--motion-duration-fast`; and `--motion-easing-standard`. No
+`--radius-surface`; `--color-muted` for the header and footer bands;
+`--color-selected` for a selected row; `--color-accent-surface` for row hover;
+`--size-control-lg` for row height; `--color-corner-mark`, `--corner-mark`,
+`--corner-mark-tick`, `--corner-mark-gap`; `--motion-duration-fast`; and
+`--motion-easing-standard`. No
 palette primitives, no raw hex/px.
 
 ## Radix/shadcn mapping

package/kiso/docs/components/theme-selector.md

@@ -0,0 +1,114 @@
+# ThemeSelector
+
+## Purpose
+
+ThemeSelector chooses which colour scheme the interface uses: follow the
+operating system, force light, or force dark. It is the only sanctioned control
+for that choice.
+
+## The three values
+
+| Value | Meaning | `data-theme` on `<html>` |
+| --- | --- | --- |
+| `system` (default) | Follow the operating system, and keep following it when it changes. | **No attribute at all.** |
+| `light` | Force light regardless of the OS. | `data-theme="light"` |
+| `dark` | Force dark regardless of the OS. | `data-theme="dark"` |
+
+`system` is the absence of the attribute, not `data-theme="system"`. The tokens
+declare `color-scheme: light dark` on `:root`, so with no attribute present
+every `light-dark()` value already resolves against the OS preference — no
+media query, no JavaScript, no flash. An explicit choice only has to narrow
+`color-scheme` to one keyword. See [tokens](../tokens.md).
+
+Do not implement `system` by reading `prefers-color-scheme` and writing
+`data-theme`. That freezes the choice at page load and stops following the OS.
+
+## Persistence
+
+- An explicit choice persists under the key `kiso-theme`, with the value
+  `light` or `dark`.
+- Choosing `system` persists the literal `system` **and removes** the
+  attribute.
+- Read the stored value in a blocking inline script in `<head>`, before first
+  paint, and apply it only when it is not `system`. Anything later flashes.
+- Storage may be unavailable (private mode, disabled cookies). Wrap reads and
+  writes so a failure degrades to `system` rather than throwing.
+
+## Anatomy
+
+1. **Row label** — the word "Theme", on the left.
+2. **Segmented control** — the three values, on the right, as a group.
+3. **Options** — one per value, each an icon with an accessible name.
+
+| Value | Icon | Accessible name |
+| --- | --- | --- |
+| `system` | monitor | "Follow system" |
+| `light` | sun | "Light theme" |
+| `dark` | moon | "Dark theme" |
+
+Icon-only. The three concepts are conventional enough that icons carry them,
+and visible text would make the row wider than the setting deserves. The
+accessible name is required, not optional — see
+[IconButton](icon-button.md).
+
+## Layout
+
+A single configuration row: label left, control right, aligned to the baseline
+of the label. This is the standard settings row, not a Card of its own. See
+[Settings](../patterns/settings.md#theme).
+
+```text
+Theme                                   [ ▣ ][ ☀ ][ ☾ ]
+```
+
+## Tokens
+
+Track `--color-muted`, border `--color-border`, radius `--radius-lg`, padding
+`--spacing-2xs`, gap `--spacing-2xs`. Each option is `--size-control-sm` high,
+radius `--radius-md`, text `--color-muted-foreground`, icon `--size-icon-sm`.
+
+The selected option takes `--color-card`, `--color-foreground`, and
+`--shadow-xs` — a raised chip inside a recessed track. Transition on
+`--motion-duration-fast` / `--motion-easing-standard`.
+
+Do not fill the selected option with `--color-primary`. This control does not
+advance a task; it is a preference, and a violet chip here competes with the
+page's actual primary action.
+
+## States
+
+| State | Behavior |
+| --- | --- |
+| default | Three options, exactly one selected. |
+| hover | Unselected option raises text to `--color-foreground`. |
+| focus | Visible ring using `--color-ring`. Never remove it. |
+| selected | Raised chip as above, plus the accessible selected state. |
+| disabled | Not a state. The theme is always changeable. |
+
+There is no loading state. The change is local and instant; do not wait on a
+server round-trip to repaint, and do not show a Toast for it.
+
+## Accessibility
+
+- Use a radio group or a tablist — a set of three mutually exclusive options
+  with exactly one selected. Do not use three independent toggle buttons.
+- Each option carries a visible-to-AT name from the table above.
+- Arrow keys move between options; the group is one tab stop.
+- Announce the selection, not the resulting colours.
+- The control must remain operable at the current theme's contrast in both
+  themes; it is chrome, so it is gated like any other control.
+
+## When NOT to use
+
+- A single "dark mode" Switch. A boolean cannot express "follow the system",
+  which is the default and the most common choice.
+- A theme entry buried inside a DropdownMenu as the only access point. A menu
+  may mirror the control, but the setting lives in a settings row.
+- Any control that offers colour options beyond these three. Kiso has two
+  themes.
+
+## Related
+
+- [tokens](../tokens.md) — how `light-dark()` and `color-scheme` resolve.
+- [Settings](../patterns/settings.md#theme) — where the row lives.
+- [Switch](switch.md) — for actual booleans.

package/kiso/docs/components/toast.md

@@ -24,7 +24,8 @@ Toast Provider
 Use `--color-elevated-surface`, `--color-foreground`,
 `--color-muted-foreground`, `--color-border`, `--color-info`, `--color-success`,
 `--color-warning`, or `--color-danger` where severity must be shown;
-`--spacing-md` padding; `--spacing-sm` gap; `--radius-md`; and `--shadow-md`.
+`--spacing-md` padding; `--spacing-sm` gap; `--radius-lg`; and `--shadow-md`.
+Transient chrome, not a panel: no corner marks.
 
 ## Variants
 

package/kiso/docs/data-interfaces.md

@@ -153,7 +153,8 @@ and the detail view contains the same explanation.
 - Use inline code for a value that fits in the surrounding sentence or cell.
   Use a code block for multi-line SQL, logs, config, or any value where line
   breaks and indentation matter.
-- Code blocks use `--color-surface`, `--color-border`, `--radius-md`,
+- Code blocks are panels: `--color-surface`, `--color-border`,
+  `--radius-surface` with corner marks,
   `--spacing-md`, and `--type-role-code`. Inline code uses
   `--color-elevated-surface`, `--radius-sm`, horizontal `--spacing-xs`, and
   `--type-role-code`.

package/kiso/docs/patterns/command-palette.md

@@ -82,7 +82,8 @@ is acceleration, not a bypass for the gate.
 ```
 
 The palette is centered or top-anchored, elevated (`--color-elevated-surface`,
-`--shadow-sm`, `--radius-lg`). The active (highlighted) item uses a quiet
+`--shadow-lg`, `--radius-surface`, with corner marks). The active (highlighted)
+item uses a quiet
 `--color-surface` or `--color-primary` indicator — not a filled primary row.
 
 ## Rules

package/kiso/docs/patterns/onboarding.md

@@ -22,7 +22,7 @@ The issue calls the progress composition “Steps”, but Kiso has no Steps
 component. Represent progress as a semantic ordered list with current and
 completed text states; do not invent a new component in this pattern.
 
-Cards use `--color-surface`, `--color-border`, `--radius-lg`, and semantic
+Cards use `--color-card`, `--color-border`, `--radius-surface`, and semantic
 spacing. Current-step emphasis uses `--color-primary`; completed status may use
 `--color-success`; primary and secondary copy use `--color-foreground` and
 `--color-muted-foreground`. Keyboard focus uses `--color-focus`.

package/kiso/docs/patterns/settings.md

@@ -24,9 +24,32 @@ immediate vs deferred persistence, and unambiguous save feedback.
 | Feedback | [Toast](../components/toast.md), [Alert](../components/alert.md), [ValidationMessage](../components/validation-message.md) | Saved confirmation; section errors; field errors |
 | Shell | [Application shell](application-shell.md) | Authenticated framing |
 
-Tokens: `--color-background` canvas, `--color-surface` Cards, `--color-border`
+Tokens: `--color-background` canvas, `--color-card` Cards, `--color-border`
 separators, `--color-foreground` / `--color-muted-foreground` copy,
-`--color-primary` for current section/nav, `--color-focus` on controls.
+`--color-primary` for current section/nav, `--color-ring` on controls.
+
+## Theme
+
+Appearance is a settings row like any other: label left, control right, inside
+a Card with the rest of the preferences. Use
+[ThemeSelector](../components/theme-selector.md); that contract owns the
+values, persistence, and markup.
+
+Three points bind here rather than there:
+
+- The default is `system` — no `data-theme` attribute on `<html>` — and it
+  keeps following the OS while the page is open.
+- The choice is local and instant. It persists to `localStorage` under
+  `kiso-theme`; it does not go through the section's Save button, and it does
+  not raise a "Settings saved" Toast.
+- It is exempt from the explicit-save rule above for the same reason a Switch
+  is: the person sees the result immediately, so a confirmation would only
+  restate what already happened.
+
+```text
+Card: Appearance
+  Theme                                   [ ▣ ][ ☀ ][ ☾ ]
+```
 
 ## Flow