@momoi-labs/kiso 0.1.0

package/kiso/docs/components/badge.md

@@ -0,0 +1,135 @@
+# Badge
+
+A small inline status label. Not a button, not a card, not a count of
+notifications by itself.
+
+## Purpose
+
+Badge names a state or classification next to something else: "New",
+"Beta", "live", "primary", "read replica". It is read, not clicked.
+
+User story #18: Badge is for status labels; [Card](card.md) is for grouping
+related content.
+
+If the person must act on the status, pair the Badge with a
+[Button](button.md) / [Link](link.md). Do not make the Badge the control.
+
+## Anatomy
+
+```
+Badge
+├── leading icon or dot (optional)
+├── label (required)
+└── trailing icon (optional; rarely needed)
+```
+
+- **Label.** One or two words. Lowercase product nouns are fine ("live",
+  "beta"); proper names keep their form. Follow
+  [voice-and-tone](../voice-and-tone.md): direct, no filler.
+- **Dot / icon.** Optional severity or category cue. Decorative
+  (`aria-hidden="true"`) when the label already says the state. If the Badge
+  is icon-only (avoid this), it needs `aria-label`.
+- **No dismiss control.** A dismissible status is an [Alert](alert.md) or a
+  filter chip (not in this slice). Badge is not closable.
+
+## Variants
+
+Variants encode *meaning*, using status and foreground roles. Do not invent
+ad-hoc colors.
+
+| Variant | Meaning | Tokens |
+| --- | --- | --- |
+| `neutral` (default) | Classification without severity: "Beta", "read", "v2". | Text `--color-foreground`, background `--color-surface`, border `--color-border`. |
+| `info` | Informational state: "New", "preview". | Text `--color-info`, border `--color-info`, background `--color-surface`. |
+| `success` | Healthy / complete: "live", "connected", "healthy". | Text `--color-success`, border `--color-success`, background `--color-surface`. |
+| `warning` | Needs attention: "degraded", "stale". | Text `--color-warning`, border `--color-warning`, background `--color-surface`. |
+| `danger` | Failed / blocked: "down", "unhealthy". | Text `--color-danger`, border `--color-danger`, background `--color-surface`. |
+
+Fill stays `--color-surface` so the status color is the text and border.
+That keeps contrast on the AA gate (status roles are checked against
+`surface`). Do not paint the whole Badge `--color-danger` and then guess a
+foreground.
+
+Do not add a `primary` Badge to shout marketing emphasis. If the thing is
+the main object, that is typography and hierarchy, not a Badge.
+
+An optional `outline` look is `neutral` with transparent background — still
+`--color-border`, not a new variant.
+
+## Sizes
+
+| Size | Type role | Padding | Radius |
+| --- | --- | --- | --- |
+| `sm` (default) | Metadata properties (`--type-role-metadata-font-family`, `--type-role-metadata-font-size`, `--type-role-metadata-font-weight`, `--type-role-metadata-letter-spacing`, `--type-role-metadata-line-height`) | `--spacing-xs` | `--radius-sm` |
+| `md` | 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` |
+
+Do not use `--radius-full` (pill). Badges are compact labels, not tags in
+a marketing cluster.
+
+## States
+
+Badge is not interactive by default.
+
+| State | Behavior |
+| --- | --- |
+| default | Static label. |
+| hover / focus / active | None, unless the Badge is wrapped by a Link (see below). |
+| disabled | N/A. Hide a Badge that no longer applies; do not grey it. |
+| loading | Optional: replace the label with a tiny [Spinner](spinner.md) plus a word ("syncing"). Prefer Skeleton on the parent region if the whole status is unknown. |
+| error | Use `danger` as the *meaning*, not a separate error state. |
+
+If a Badge is a Link (filter that navigates to a tagged view), the Link is
+the interactive element: Badge provides appearance only. Focus ring
+`--color-focus` on the Link. Do not put `onClick` on a `span` Badge.
+
+## Accessibility
+
+- Default element: `<span>`. No `role="status"` on every Badge — that would
+  shout every "Beta" as a live region. The surrounding content already
+  includes the object; the Badge is extra words in that name.
+- If the Badge is the only indication of a *changing* live state that the
+  person must notice (connection dropped), the *region* should update via
+  [Alert](alert.md) or `aria-live`, not a silent Badge swap.
+- Color is not the only cue: the label text carries the meaning. A red
+  empty Badge is a fail.
+- Icon-only: `aria-label` required. Prefer text.
+
+### Keyboard
+
+No keymap. A Badge that is a Link follows [Link](link.md) keyboard rules.
+
+## When to use
+
+- A short status or classification next to a title, table cell, or Card
+  title: "New", "Beta", "live", "primary".
+- Several orthogonal labels ("live" + "read replica") — each is its own
+  Badge, not one concatenated string.
+
+## When NOT to use
+
+- **Grouping content.** [Card](card.md).
+- **In-page warnings with explanation and recovery.** [Alert](alert.md).
+- **Actions.** Buttons, IconButtons, and Links. A "Delete" Badge is a
+  mistake.
+- **Counts, notifications, or numeric attention dots.** If Kiso needs a
+  notification count later, that is not this component. A numeric "3" Badge
+  on an icon is chrome, not a status label.
+- **Section headings or filters that look like a pile of pills.** Filters
+  are Controls; they belong with Input/Select or a later pattern.
+- **Long sentences.** If it needs punctuation, it is copy, not a Badge.
+
+## Radix/shadcn mapping
+
+No Radix Badge primitive. Visual reference: shadcn
+[Badge](https://ui.shadcn.com/docs/components/badge).
+
+| Kiso | shadcn |
+| --- | --- |
+| `neutral` | `secondary` or `outline` restyled to `--color-surface` / `--color-border` / `--color-foreground` |
+| `info` / `success` / `warning` / `danger` | Do not use arbitrary `bg-green-*` utilities from the shadcn "Custom Colors" example. Map respectively to `--color-info`, `--color-success`, `--color-warning`, or `--color-danger`. |
+| shadcn `destructive` | Closest to Kiso `danger` |
+| shadcn `default` (accent fill) | Do not use as a status; it competes with primary actions |
+| shadcn `variant="link"` | Do not use; navigation is [Link](link.md) |
+
+If the Badge navigates, compose shadcn Badge visuals on an `<a>` the same
+way Button-look Links do — do not use a Button.

package/kiso/docs/components/breadcrumb.md

@@ -0,0 +1,66 @@
+# Breadcrumb
+
+Shows the current page's position in a hierarchy and links to its ancestors.
+
+## Purpose
+
+Breadcrumb answers “where am I?” across nested routes. Unlike [Tabs](tabs.md),
+it does not switch peer content within the current page.
+
+## Anatomy
+
+```
+Breadcrumb navigation
+└── ordered list
+    ├── ancestor Link
+    ├── separator (decorative)
+    └── current page (text)
+```
+
+Use `--color-muted-foreground` for ancestors, `--color-foreground` for the
+current page, `--color-primary` for Link interaction, and `--color-focus` for
+focus. Separators use the muted role and are hidden from assistive technology.
+
+## Variants
+
+No visual variants. Breadcrumb always represents one hierarchy; overflow is a
+state that collapses middle ancestors, not a separate variant.
+
+## Sizes
+
+One size. Use the standard body/link treatment and semantic spacing; do not
+create compact or large breadcrumb scales.
+
+## States
+
+| State | Behavior |
+| --- | --- |
+| default | Ancestors are Links; the current page is plain text. |
+| hover | Ancestor Link shows its Link hover treatment. |
+| focus | Focused ancestor shows `--color-focus`. |
+| active | Pressing an ancestor follows its URL. Current page carries `aria-current="page"`. |
+| disabled | N/A. Do not render a disabled breadcrumb Link. |
+| overflow | Collapse middle ancestors into an accessible menu; keep the root and current page visible. |
+
+## Accessibility
+
+Use `<nav aria-label="Breadcrumb">` with an `<ol>`. Separators are CSS or
+`aria-hidden="true"`. Do not make the current page a self-link. Keyboard
+behavior is native Link/menu behavior; `Tab` visits Links, not separators.
+
+## When to use
+
+- Routes at least two meaningful levels deep.
+- Technical products where parent context is useful for returning upward.
+
+## When NOT to use
+
+- Switching panels on one page; use Tabs.
+- A flat product with no hierarchy.
+- As a substitute for the page title or browser history.
+
+## Radix/shadcn mapping
+
+Radix has no Breadcrumb primitive. Map structure to shadcn Breadcrumb while
+preserving native `<nav>`, ordered-list, and Link semantics. Use DropdownMenu
+for collapsed middle items.

package/kiso/docs/components/button.md

@@ -0,0 +1,168 @@
+# Button
+
+Triggers an in-page action. It does not change the URL.
+
+## Purpose
+
+Button is the control for *doing something*: submit a form, run a query, open
+a dialog, save, delete. The person activates it; the application performs
+behavior.
+
+If the destination is a URL, use [Link](link.md). If the action is an icon
+with no visible text, use [IconButton](icon-button.md).
+
+### Choose the right control
+
+| Need | Control | Why |
+| --- | --- | --- |
+| Trigger behavior (submit, save, delete, open) | **Button** | Action; URL does not change. |
+| Icon-only action (toolbar, compact chrome) | **[IconButton](icon-button.md)** | Same as Button, but the accessible name is not visible text. |
+| Go to a URL (in-app or external) | **[Link](link.md)** | Navigation; must remain a real link (open in new tab, copy URL). |
+
+A Button that looks like a link is still a Button and is the wrong control for
+navigation. A Link that looks like a Button is still a Link: visual style does
+not change the semantics.
+
+A Button may include an icon *plus* a text label. That is still Button, not
+IconButton.
+
+## Anatomy
+
+```
+Button
+├── leading icon (optional)
+├── label (required visible text)
+├── trailing icon (optional)
+└── Spinner (loading state only; replaces or precedes the label)
+```
+
+- **Label.** Direct verb phrase. Follow
+  [voice-and-tone](../voice-and-tone.md): "Save query", "Delete replica",
+  "Run". Not "Click here", not "Submit" when a specific verb exists.
+- **Icon.** Optional reinforcement of the label. Never the only name — that
+  is IconButton.
+- **Spinner.** Only while the action is pending. See
+  [Spinner](spinner.md).
+
+## Variants
+
+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`. |
+
+`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.
+
+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. |
+
+Do not invent a fourth size. Page-level calls to action still use `md` or
+`lg`. PageHeader (navigation slice) composes Buttons; it is not a Button
+size.
+
+## States
+
+| State | Behavior | Tokens / notes |
+| --- | --- | --- |
+| default | Interactive. | Variant tokens above. |
+| hover | Pointer over the control. | See variant hover. Cursor indicates affordance. Transition: `--motion-duration-fast` / `--motion-easing-standard`. |
+| focus | Keyboard focus. | Visible ring using `--color-focus`. Never remove the ring without an equivalent. |
+| active | Pointer down / activation. | Slightly pressed; keep the same semantic colors. |
+| disabled | Interaction blocked. The person must see *that* it is blocked. User story #12. | Text and chrome `--color-disabled`. Not in the tab order (`disabled` on `<button>`). If the reason is not obvious from context, state it in adjacent copy — not inside a Tooltip. |
+| loading | Interaction pending. User story #12. | `aria-busy="true"`. Show [Spinner](spinner.md); keep the original label or replace with a specific loading verb ("Saving…"). Ignore further activations. Do not swap loading for disabled: disabled means "cannot", loading means "working". |
+| error | Not a Button state. | Failure belongs on [Alert](alert.md) or a field ValidationMessage, not on the Button. After failure, return the Button to default so the person can retry. |
+
+Disabled is exempt from the AA text-contrast gate (`--color-disabled` is
+intentionally outside it). Loading is not exempt: Spinner and remaining text
+must still meet contrast.
+
+## Accessibility
+
+- Native `<button>` (or a component that renders one). Do not put
+  `role="button"` on a link or a `div`.
+- `type="button"` unless the Button submits a form (`type="submit"`) or
+  resets it (`type="reset"`). A Button inside a form without an explicit
+  type is a silent submit — that is a bug.
+- Accessible name is the visible label. Do not override it with a different
+  `aria-label`.
+- Focus visible at all times using `--color-focus`.
+- Disabled uses the native `disabled` attribute (removed from tab order).
+  Loading may also set `disabled` to prevent double-submit; keep `aria-busy`
+  so the pending state is announced.
+- Icon + text: the icon is decorative (`aria-hidden="true"`); the text is the
+  name.
+
+### Keyboard
+
+| Key | Action |
+| --- | --- |
+| `Enter` | Activate. |
+| `Space` | Activate. |
+| `Tab` / `Shift+Tab` | Move focus to the next / previous control. |
+
+## When to use
+
+- The person is causing an action: save, run, create, delete, confirm, retry.
+- The action stays on this URL (including opening a dialog or drawer).
+- Form submit and form-reset controls.
+- PageHeader actions (title + subtitle + Buttons — composition lands in a
+  later slice).
+
+## When NOT to use
+
+- **Navigation.** Anything that should change the URL, support open-in-new-tab,
+  or be copyable as a link — use [Link](link.md), even if it is styled to look
+  like a Button.
+- **Icon with no text.** Use [IconButton](icon-button.md).
+- **A row of mutually exclusive choices.** That is Tabs or a Select, not a
+  Button group pretending to be navigation.
+- **Toggling a boolean.** Use Switch or Checkbox (form primitives), not a
+  Button whose label flips.
+- **In-page warnings.** Use [Alert](alert.md) for the message; the Alert may
+  *contain* a Button for recovery.
+
+## Radix/shadcn mapping
+
+There is no Radix Button primitive. Behavior is the native `<button>`.
+
+| Kiso | Reference |
+| --- | --- |
+| Composition onto a child (rare; prefer a real `<button>`) | Radix [Slot](https://www.radix-ui.com/primitives/docs/utilities/slot) (`asChild`) |
+| Visual system, sizes, variants | shadcn [Button](https://ui.shadcn.com/docs/components/button) |
+
+Map Kiso variants onto shadcn *by intent*, not by name:
+
+| Kiso variant | shadcn `variant` |
+| --- | --- |
+| `primary` | `outline`, restyled: `--color-primary` text and border, `--type-weight-semibold`. Do not use shadcn's filled `default` — that needs an on-primary text role Kiso does not have. |
+| `default` | `outline` with `--color-foreground` / `--color-border` |
+| `destructive` | `outline` restyled with `--color-danger` text and border, not filled `destructive` |
+| `ghost` | `ghost` |
+
+Do **not** use shadcn `variant="link"`. That style is [Link](link.md).
+
+Do **not** use shadcn `size="icon"` here. That is [IconButton](icon-button.md).
+
+shadcn's "As Link" / `buttonVariants` helper is valid when a *navigation*
+control must *look* like a Button: apply the visual classes to a
+[Link](link.md) (`<a>` / router link). Do not render `<button>` or a
+component that forces `role="button"` for navigation.
+
+Loading: compose shadcn Button with shadcn/Kiso [Spinner](spinner.md), as in
+the shadcn Button "Spinner" example. Keep `aria-busy`.

package/kiso/docs/components/card.md

@@ -0,0 +1,154 @@
+# Card
+
+Groups related content with visual separation from the surrounding canvas.
+
+## Purpose
+
+Card is a surface for one unit of related content: a cluster of fields, a
+summary of a replica, a setting group, a login form. It creates hierarchy by
+sitting on `--color-surface` against `--color-background`.
+
+It is not a status label ([Badge](badge.md)), not an in-page warning
+([Alert](alert.md)), and not a layout primitive for the whole app (Header,
+Sidebar, PageHeader belong to a later slice).
+
+User story #18: Badge labels status; Card groups content.
+
+## Anatomy
+
+```
+Card
+├── media (optional, edge-to-edge at the start)
+├── Header (optional)
+│   ├── Title
+│   ├── Description
+│   └── Action (optional: Button, IconButton, Badge, or Link)
+├── Content (optional if Header/Footer already carry the payload)
+└── Footer (optional: actions or supporting meta)
+```
+
+Every part except the root is optional, but a Card with no content is
+decorative and does not belong. Prefer Title + Content as the minimum useful
+shape.
+
+- **Title.** Use the heading typography properties (`--type-role-heading-font-family`,
+  `--type-role-heading-font-size`, `--type-role-heading-font-weight`,
+  `--type-role-heading-letter-spacing`, `--type-role-heading-line-height`) only
+  when the Card is a true section; otherwise use the equivalent 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. One title.
+- **Description.** Use the five body typography properties or the five metadata
+  typography properties listed in `tokens/build/tokens.css`. Secondary;
+  `--color-muted-foreground`.
+- **Action.** One compact control aligned with the title — not a toolbar.
+- **Content.** The payload. Default type uses `--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`; color
+  uses `--color-foreground`.
+- **Footer.** Actions that apply to the whole Card, typically
+  [Button](button.md) `sm` / `md`.
+
+## Variants
+
+| 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. |
+
+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.
+
+Do not add outline/ghost Card variants. If the grouping needs no surface,
+it is a section with a heading, not a Card.
+
+## Sizes
+
+Size changes padding and gap, not type roles.
+
+| Size | Padding / gap | Use |
+| --- | --- | --- |
+| `sm` | `--spacing-md` | Dense dashboards, nested grouping inside a larger region. |
+| `md` (default) | `--spacing-lg` | Standard product Cards. |
+| `lg` | `--spacing-xl` | Rare; a single featured group on an otherwise empty view. |
+
+Media that bleeds to the edges still uses the size token for the remaining
+sections, not for the image itself.
+
+## States
+
+Card is a container. It does not have hover/active/disabled of its own
+unless the *entire Card* is a single destination or action — which is
+usually the wrong pattern (put a Link or Button inside).
+
+| State | Behavior |
+| --- | --- |
+| default | Static grouping. |
+| hover | No chrome change for static Cards. If the whole Card is a Link (rare), use `--color-elevated-surface` on hover and a `--color-focus` ring on focus; the Card *is* the Link, not a Button. |
+| focus | Focus lives on interactive children, not the Card. |
+| active | N/A for static Cards. |
+| disabled | Disable the controls inside; do not grey the whole Card unless every action is unavailable — and then explain why in the Content. |
+| loading | Replace Content with [Skeleton](skeleton.md) shaped like the loaded layout, or set `aria-busy="true"` on the Card. Do not cover a Card with a disconnected [Spinner](spinner.md) if the structure is known. |
+| error | Keep the Card; put an [Alert](alert.md) in Content (or replace Content with the Alert). Do not turn the Card border `--color-danger` as the only error cue. |
+
+## Accessibility
+
+- The Card root is a generic grouping (`<section>` or `<article>` when it is
+  a self-contained unit; `<div>` when it is only visual). Do not set
+  `role="group"` unless the Card is a true composite widget with its own
+  name.
+- If the Card has a Title, point the grouping at it:
+  `aria-labelledby` on the section.
+- Interactive children keep their own roles (Button, Link, IconButton).
+  Do not make the Card clickable *and* nest Buttons — nested interactive
+  elements.
+- Keyboard: no Card-level keymap. Tab moves through the children.
+
+### Keyboard
+
+| Key | Action |
+| --- | --- |
+| `Tab` / `Shift+Tab` | Move between interactive children. |
+
+## When to use
+
+- A bounded cluster of related content that should read as one unit against
+  the canvas.
+- A form or setting group that is one task.
+- A summary tile that still contains structure (title, meta, actions) —
+  not a single status word.
+
+## When NOT to use
+
+- **Status labels** ("Beta", "live"). Use [Badge](badge.md).
+- **Warnings and errors about the page or a section.** Use [Alert](alert.md).
+  An Alert may sit *inside* a Card; it is not a Card variant.
+- **Every block on the page.** If removing the surface, border, and radius
+  does not hurt understanding, it should not be a Card.
+- **Application chrome.** Header, Sidebar, PageHeader, and tables are their
+  own components. A data table does not sit in a Card unless the table is a
+  small embedded summary.
+- **Clickable marketing tiles with overlay badges.** Product Cards contain
+  controls; they are not posters.
+
+## Radix/shadcn mapping
+
+No Radix Card primitive. Structure follows shadcn
+[Card](https://ui.shadcn.com/docs/components/card):
+
+| Kiso | shadcn |
+| --- | --- |
+| Card | `Card` |
+| Header | `CardHeader` |
+| Title | `CardTitle` |
+| Description | `CardDescription` |
+| Action | `CardAction` |
+| Content | `CardContent` |
+| Footer | `CardFooter` |
+| `sm` / `md` | `size="sm"` / default; map padding to `--spacing-md` / `--spacing-lg`, not raw values |
+| `plain` / `elevated` | Default shadcn Card uses its `bg-card` token — restyle to `--color-surface` or `--color-elevated-surface` |
+
+Ignore shadcn's invitation to hard-code spacing utilities. Card spacing
+consumes `--spacing-md`, `--spacing-lg`, or `--spacing-xl` only.

package/kiso/docs/components/checkbox.md

@@ -0,0 +1,91 @@
+# Checkbox
+
+## Purpose
+
+Checkbox represents an independent boolean choice or membership in a list of
+multiple choices. More than one checkbox in a group may be selected.
+
+## Anatomy
+
+1. **Root** — focusable checkbox control and checked-state owner.
+2. **Indicator** — check mark or indeterminate mark.
+3. **Label** — names the choice and enlarges the activation target.
+4. **Description (optional)** — HelperText for consequences or context.
+
+## Variants
+
+- **Unchecked / checked** — independent false/true choice.
+- **Indeterminate** — summarizes mixed child selections; it is a visual and
+  programmatic third presentation, not a submitted business value by itself.
+- **Checkbox group** — multiple related values within `fieldset` and `legend`.
+- **Required acknowledgment** — use sparingly for a genuinely required consent;
+  validation must explain what is needed.
+
+Checkbox is for independent or multiple selections. Switch is for one setting
+that takes effect as on/off; Select is for exactly one value from many.
+
+## Sizes
+
+- **Small** — dense data and compact lists while retaining an adequate combined
+  Label activation target.
+- **Medium** — default.
+
+Indicator follows `--type-role-label-font-size`; its label gap is
+`--spacing-sm`. Avoid a
+large decorative variant; hierarchy belongs in the text and layout.
+
+## States
+
+| State | Behavior |
+| --- | --- |
+| Default | Unchecked outline uses `--color-border`; checked state uses the semantic primary treatment. |
+| Hover | Root/label pair shows subtle interactive emphasis. |
+| Focus | Visible `--color-focus` ring on the root. |
+| Active | Pressed feedback is brief and does not obscure the checked value. |
+| Disabled | Cannot toggle, uses `--color-disabled`, and the Label reflects disabled state. |
+| Loading | Rare; keep the current value visible and announce pending persistence instead of replacing the indicator. |
+| Error | Group or control is invalid, uses `--color-danger`, and references ValidationMessage. |
+
+Loading does not mean unchecked or disabled. For optimistic updates, retain the
+new checked value and expose pending status; on failure, restore or explain the
+actual value with a recovery action.
+
+## Accessibility
+
+- Radix supplies `role="checkbox"`, checked/indeterminate state, and hidden
+  native form participation. Preserve those semantics.
+- Associate Label with the root ID. A group uses `fieldset`/`legend` or an
+  equivalent named group.
+- Use `aria-checked="mixed"` for indeterminate state where not supplied by the
+  primitive. Expose required, invalid, disabled, and busy states.
+- Link HelperText and ValidationMessage through `aria-describedby`.
+- Keyboard: `Tab` focuses each enabled checkbox; `Space` toggles it. Do not add
+  arrow-key exclusivity—that belongs to radio-group behavior.
+
+## When to use
+
+- For independent opt-in/opt-out choices submitted with a form.
+- For selecting zero, one, or many items from a visible list.
+- For a parent “select all” control with a mixed state.
+
+## When NOT to use
+
+- Do not use for an immediate single on/off setting; use Switch.
+- Do not use for exactly one mutually exclusive choice from many; use Select
+  (or a future RadioGroup).
+- Do not make the check mark the only indication of a consequential choice;
+  provide a clear Label and context.
+
+## Tokens
+
+Use `--color-border`, `--color-surface`, `--color-foreground`,
+`--color-primary`, `--color-focus`, `--color-disabled`, and `--color-danger`,
+plus `--spacing-sm`, `--radius-sm`, the five property-qualified label
+typography tokens, `--motion-duration-fast`, and `--motion-easing-standard`.
+
+## Radix/shadcn mapping
+
+Maps to [Radix Checkbox](https://www.radix-ui.com/primitives/docs/components/checkbox)
+and [shadcn/ui Checkbox](https://ui.shadcn.com/docs/components/checkbox).
+Preserve Radix's controlled/uncontrolled and indeterminate behavior, keyboard
+contract, and form participation.