@momoi-labs/kiso 0.1.0

package/kiso/docs/components/header.md

@@ -0,0 +1,79 @@
+# Header
+
+Application-level chrome that keeps primary navigation and global actions in a
+predictable place. Header is a layout container, not a primitive.
+
+## Purpose
+
+Header orients the person and exposes a small set of destinations and actions
+that remain useful across routes. It composes [Link](link.md) for navigation,
+[IconButton](icon-button.md) for icon-only actions, and optionally
+[DropdownMenu](dropdown-menu.md) for overflow. Do not replace those controls with clickable
+containers.
+
+## Anatomy
+
+```
+Header
+├── brand/home Link
+├── primary Navigation
+│   └── Link(s)
+└── actions
+    ├── IconButton(s)
+    └── DropdownMenu (optional, triggered by IconButton)
+```
+
+Use `--color-surface`, `--color-foreground`, and `--color-border`;
+`--spacing-md` block and `--spacing-lg` inline padding; `--spacing-md` item
+gaps; the five property-qualified label typography tokens; `--radius-md` for
+interactive children; `--motion-duration-fast`; and
+`--motion-easing-standard`. The current Link
+uses `aria-current="page"` and `--color-primary`.
+
+## Variants
+
+No visual variants. Header has one structural treatment; its child Navigation
+and actions determine the composition, while narrow-viewport collapse is a
+state rather than a separate variant.
+
+## Sizes
+
+No named sizes. Header spacing adapts responsively with semantic spacing tokens;
+child Links, IconButtons, and DropdownMenu triggers keep their own sizes.
+
+## States
+
+| State | Behavior |
+| --- | --- |
+| default | Brand, primary destinations, and global actions are visible. |
+| hover | Child Links and IconButtons own hover feedback. |
+| focus | Focus follows document order; each child shows `--color-focus`. |
+| active | The current Link is marked; pressed actions keep their component behavior. |
+| disabled | Header itself is never disabled. Unavailable children follow their own specs. |
+| collapsed | At narrow viewports, preserve the home Link and essential actions; move lower-priority destinations into DropdownMenu. |
+
+## Accessibility
+
+Use `<header>` and a labelled `<nav>` for the destination group. Do not add
+`role="banner"` when native `<header>` already provides it. Keep one banner
+landmark per page, label multiple navigation landmarks distinctly, and retain
+normal Link and IconButton keyboard behavior. Opening DropdownMenu moves focus
+according to its own roving-focus behavior; closing returns focus to its
+IconButton trigger.
+
+## When to use
+
+- Persistent product identity, top-level destinations, and global actions.
+- Wide layouts where top navigation is clearer than a Sidebar.
+
+## When NOT to use
+
+- For a page title and page-specific actions; use [PageHeader](page-header.md).
+- As a Card header or decorative masthead.
+- For a long hierarchy; use [Sidebar](sidebar.md) or Breadcrumb.
+
+## Radix/shadcn mapping
+
+No Radix Header primitive. Use native `<header>` + `<nav>`, Kiso Link and
+IconButton, and shadcn Dropdown Menu / Radix Dropdown Menu when overflow is
+needed. shadcn Navigation Menu is not required for a simple set of Links.

package/kiso/docs/components/helper-text.md

@@ -0,0 +1,86 @@
+# HelperText
+
+## Purpose
+
+HelperText gives persistent, non-error context for a form control: expected
+format, scope, consequence, or a concise example. It helps a person succeed
+before validation fails.
+
+## Anatomy
+
+1. **Text** — one concise instruction or explanation.
+2. **Identifier** — stable ID referenced by the control's
+   `aria-describedby`.
+3. **Supplementary link (optional)** — a separately named destination when
+   essential documentation cannot fit in concise help.
+
+## Variants
+
+- **Instruction** — explains expected format or constraints.
+- **Context** — explains where or how the value is used.
+- **Example** — shows a representative value without becoming a default value.
+- **With link** — points to deeper documentation; the sentence remains useful
+  without relying on the link text alone.
+
+HelperText is never an error. ValidationMessage owns field-level invalid
+feedback.
+
+## Sizes
+
+HelperText has one typography size: `--type-role-metadata-font-size` with
+`--type-role-metadata-line-height`. Its line length and wrapping follow the
+control width. Use `--spacing-xs` between
+the control, HelperText, and ValidationMessage.
+
+## States
+
+| State | Behavior |
+| --- | --- |
+| Default | Uses `--color-muted-foreground` and remains readable as normal text. |
+| Hover | No state unless it contains a link; only the link responds. |
+| Focus | No state unless it contains a link; the link receives its own focus ring. |
+| Active | No independent state. |
+| Disabled | Usually remains readable to explain why the control is unavailable; do not automatically reduce it to illegibility. |
+| Loading | Remains stable unless the guidance itself has genuinely changed. |
+| Error | Remains visible when still useful; ValidationMessage appears separately with danger semantics. |
+
+## Accessibility
+
+- Give HelperText a stable ID and include it in the associated control's
+  `aria-describedby` value.
+- When both help and validation exist, reference both IDs in meaningful DOM
+  order. Do not overwrite one relationship with the other.
+- Do not use `role="alert"`, `aria-live`, or `aria-invalid`; the text is
+  descriptive, not urgent status.
+- Links use descriptive text and standard keyboard behavior.
+- Keep instructions concise, direct, and available before input—not only on
+  hover or focus.
+
+## When to use
+
+- To state a format, unit, scope, consequence, or short example.
+- When context reduces avoidable validation errors.
+- As the supporting description in FormField.
+
+## When NOT to use
+
+- Do not use for an error; use ValidationMessage.
+- Do not repeat the Label or placeholder.
+- Do not put essential help only in a tooltip or placeholder.
+- Do not add generic advice that does not change how the field is completed.
+
+## Tokens
+
+Use `--color-muted-foreground`; `--type-role-metadata-font-family`,
+`--type-role-metadata-font-size`, `--type-role-metadata-font-weight`,
+`--type-role-metadata-letter-spacing`, and `--type-role-metadata-line-height`;
+and `--spacing-xs`. `--color-subtle-foreground` is not suitable
+for ordinary small helper copy because it is restricted to large or
+non-essential hints. No primitive colors or raw values.
+
+## Radix/shadcn mapping
+
+Radix has no standalone HelperText primitive. In shadcn compositions it maps
+to field description/form description behavior (for example, the description
+part of [shadcn/ui Field](https://ui.shadcn.com/docs/components/field)). Kiso's
+required behavioral contract is the explicit `aria-describedby` relationship.

package/kiso/docs/components/icon-button.md

@@ -0,0 +1,161 @@
+# IconButton
+
+Triggers an in-page action whose only visible content is an icon. It must
+expose an accessible name with `aria-label` (or `aria-labelledby`).
+
+## Purpose
+
+IconButton is Button without a visible text label: compact chrome, toolbars,
+dismiss controls, and header actions where a word would not fit.
+
+It is still an *action*. It does not navigate. If the icon takes the person
+to a URL, use [Link](link.md) with an icon, not IconButton.
+
+### Choose the right control
+
+| Need | Control |
+| --- | --- |
+| Action with a visible text label (icon optional) | **[Button](button.md)** |
+| Action with *only* an icon | **IconButton** |
+| Navigation (URL changes) | **[Link](link.md)** |
+
+If the icon is not universally understood on its own, prefer Button with a
+visible label. IconButton is a density choice, not a decoration choice.
+
+[Tooltip](tooltip.md) may repeat the accessible name on hover/focus. Tooltip
+is progressive enhancement: it is not a substitute for `aria-label`, and it
+is not available on touch. The `aria-label` is the name; the Tooltip is
+optional clarification for pointer and keyboard users.
+
+## Anatomy
+
+```
+IconButton
+├── icon (required, visually only)
+├── accessible name (required, not visible: aria-label or aria-labelledby)
+├── Tooltip (optional; same words as the accessible name)
+└── Spinner (loading state only; replaces the icon)
+```
+
+- **Icon.** Decorative. `aria-hidden="true"` so the name is not announced
+  twice.
+- **Accessible name.** Short verb phrase, same rules as Button labels:
+  "Dismiss", "Open command palette", "Refresh replicas". Not "Button", not
+  the icon's filename.
+- **Tooltip.** If present, its content *equals* the accessible name. Never
+  add extra essential instructions in the Tooltip.
+
+## Variants
+
+Same four variants as [Button](button.md). Same token mapping. Same rule:
+no "link" variant.
+
+| Variant | Typical IconButton use |
+| --- | --- |
+| `default` | Standalone compact action on a surface. |
+| `primary` | Rare. A single icon as the region's main action (e.g. "Run"). Prefer a labeled Button when space allows. |
+| `destructive` | Irreversible icon action (delete). Confirm before committing; the icon alone is easy to hit by mistake. |
+| `ghost` | Default for chrome: Header actions, Card header actions, Alert dismiss, table row actions. |
+
+Header (a later navigation slice) composes Link + IconButton. IconButton in
+that role is `ghost`.
+
+## Sizes
+
+Square hit targets. Icon centered. Radius `--radius-md` (`sm` size uses
+`--radius-sm`).
+
+| Size | Type / icon | Padding | Use |
+| --- | --- | --- | --- |
+| `sm` | Icon scaled to `--type-role-metadata-font-size` | `--spacing-xs` | Inside Alert, Badge-adjacent chrome, dense tables. |
+| `md` (default) | Icon scaled to `--type-role-label-font-size` | `--spacing-sm` | Toolbars, Card actions, Header. |
+| `lg` | Icon scaled to `--type-role-body-font-size` | `--spacing-md` | Rare; empty-state or touch-first primary icon. |
+
+The hit target must remain easy to activate; do not shrink `sm` below the
+spacing tokens above.
+
+## States
+
+Identical in meaning to [Button](button.md):
+
+| State | Notes |
+| --- | --- |
+| default | Interactive. |
+| hover | Variant hover tokens. |
+| focus | Visible ring using `--color-focus`. Tooltip, if any, opens on focus (see Tooltip keyboard). |
+| active | Pressed. |
+| disabled | Native `disabled`. `--color-disabled`. If the person needs to know *why*, put that in adjacent copy — not only in a Tooltip (Tooltip is not on touch and is never essential). |
+| loading | `aria-busy="true"`. Replace the icon with [Spinner](spinner.md) of the matching size. Ignore further activations. Distinct from disabled (user story #12). |
+| error | Not an IconButton state. |
+
+## Accessibility
+
+- Native `<button type="button">` unless it submits (`type="submit"`).
+- **Accessible name is mandatory.** Set `aria-label` or point
+  `aria-labelledby` at visible text elsewhere. An IconButton without a name
+  is a spec violation, not a styling choice.
+- The SVG/icon is `aria-hidden="true"` (and `focusable="false"` if the
+  graphic could take focus).
+- Do not use a different `aria-label` than the Tooltip text.
+- Touch: there is no Tooltip. The icon must be understandable from context
+  (a well-known metaphor next to the thing it affects) or the control must
+  be a labeled Button instead.
+- Focus ring uses `--color-focus`. Never omit it because "the tooltip
+  explains the control".
+
+### Keyboard
+
+| Key | Action |
+| --- | --- |
+| `Enter` | Activate. |
+| `Space` | Activate. |
+| `Tab` / `Shift+Tab` | Move focus. |
+
+Tooltip keyboard (open on focus, dismiss on `Escape`) is defined in
+[Tooltip](tooltip.md). Activation of the IconButton dismisses the Tooltip.
+
+## When to use
+
+- A compact action where a text label would add noise: dismiss, overflow
+  menu, refresh, copy, favorite, close.
+- Header and toolbar actions.
+- The accessible name is a short, specific verb, and the icon is recognizable
+  in context.
+
+## When NOT to use
+
+- **There is room for a text label.** Use [Button](button.md). Density is
+  not a reason to hide the verb on a primary action.
+- **Navigation.** Use [Link](link.md). A "settings gear" that goes to
+  `/settings` is a Link, possibly styled as an icon.
+- **The only explanation of the control is a Tooltip.** Tooltip is never
+  essential (user story #10). If the person cannot succeed without the
+  Tooltip, use a labeled Button.
+- **Touch-first primary actions** that are not standard metaphors (close,
+  search, add). Prefer Button with text.
+- **Toggle with two lasting states** (on/off). Use Switch (form slice).
+
+## Radix/shadcn mapping
+
+No dedicated Radix or shadcn `IconButton` primitive. Implement as shadcn
+[Button](https://ui.shadcn.com/docs/components/button) with an icon size:
+
+| Kiso | shadcn |
+| --- | --- |
+| IconButton `sm` | `size="icon-sm"` (or `icon-xs` only if it still uses `--spacing-xs` padding) |
+| IconButton `md` | `size="icon"` |
+| IconButton `lg` | `size="icon-lg"` |
+| variants | Same Button mapping as [Button](button.md) (Kiso `primary` and `default` both start from shadcn `outline`, restyled) |
+
+Always pass `aria-label`. Do not rely on the icon's title or a Tooltip
+alone.
+
+Radix [Slot](https://www.radix-ui.com/primitives/docs/utilities/slot)
+(`asChild`) is allowed only to merge IconButton props onto a native
+`<button>`. That is the shadcn Button `asChild` path. It must not target
+an `<a>` — that is [Link](link.md).
+
+Optional Tooltip: wrap with shadcn/Radix [Tooltip](tooltip.md) and set the
+content to the same string as `aria-label`.
+
+Do not use shadcn `variant="link"`.

package/kiso/docs/components/input.md

@@ -0,0 +1,99 @@
+# Input
+
+## Purpose
+
+Input collects a single-line text-like value such as a name, email address,
+search term, URL, number, or password. Use the native input type that best
+describes the value so browsers and assistive technology can provide the right
+behavior.
+
+## Anatomy
+
+1. **Native input** — the editable value and browser semantics.
+2. **Leading affordance (optional)** — contextual icon or fixed prefix; never
+   the only label.
+3. **Trailing affordance (optional)** — fixed suffix, clear action, or status.
+4. **Loading affordance (optional)** — Spinner adjacent to the value without
+   replacing it or changing the field width.
+
+Label, HelperText, and ValidationMessage belong to FormField rather than the
+Input root.
+
+## Variants
+
+- **Text** — general single-line entry.
+- **Email, URL, telephone, number** — uses the corresponding native `type` and
+  appropriate `inputmode`; client validation does not replace server validation.
+- **Password** — obscures the value; an optional show/hide action has an
+  accessible name and preserves focus.
+- **Search** — use `type="search"` for a query field. Search behavior is defined
+  by the later Search component, not by Input alone.
+- **Read-only** — value can be focused, selected, and copied but not edited.
+
+## Sizes
+
+- **Small** — compact toolbars and dense technical forms.
+- **Medium** — default for most forms.
+- **Large** — rare, high-emphasis entry points.
+
+Size changes internal padding from `--spacing-xs` / `--spacing-sm` for small,
+to `--spacing-sm` / `--spacing-md` for medium, to `--spacing-md` / `--spacing-lg`
+for large. It does not reduce text or target size below accessible product norms.
+
+## States
+
+| State | Behavior |
+| --- | --- |
+| Default | `--color-surface` background, `--color-border` outline, `--color-foreground` value; placeholder uses `--color-subtle-foreground`. |
+| Hover | Border emphasis may increase without changing layout or implying focus. |
+| Focus | Visible `--color-focus` ring; do not rely on border color alone. |
+| Active | Native text selection and editing behavior; no separate persistent visual state. |
+| Disabled | Native `disabled`; not focusable or submitted, uses `--color-disabled`. |
+| Loading | Remains readable and normally focusable; shows a Spinner, exposes busy status, and prevents conflicting submission-side edits only when necessary. |
+| Error | Uses `aria-invalid="true"`, visible danger treatment with `--color-danger`, and a linked ValidationMessage. |
+
+Disabled and loading are not interchangeable. Disabled means the field is
+unavailable. Loading means work is in progress and must be communicated; do not
+silently disable a field merely to show activity.
+
+## Accessibility
+
+- Associate a visible Label through matching `for` and `id`.
+- Use the correct `type`, `name`, `autocomplete`, `inputmode`, `required`,
+  `min`, `max`, and other native attributes for the data.
+- Link HelperText and ValidationMessage IDs through a space-separated
+  `aria-describedby`. Add `aria-invalid="true"` only when invalid.
+- If loading changes what the person can do, expose it with `aria-busy` on the
+  field or a nearby status region. Spinner alone is not an accessible status.
+- Standard text-input keyboard behavior applies. Do not override selection,
+  cursor, undo, paste, or platform shortcuts. Any trailing action is separately
+  keyboard reachable and named.
+
+## When to use
+
+- For one line of free-form or constrained text-like data.
+- When native input semantics match the requested value.
+- Inside FormField when a label, help, or validation feedback is needed.
+
+## When NOT to use
+
+- Do not use for multi-line prose; use Textarea.
+- Do not use for choosing one predefined option from many; use Select.
+- Do not use for a boolean setting; use Switch, or Checkbox in a list/multi-select.
+- Do not put essential instructions only in placeholder text.
+
+## Tokens
+
+Use only semantic roles: `--color-surface`, `--color-foreground`,
+`--color-subtle-foreground`, `--color-border`, `--color-focus`,
+`--color-disabled`, and `--color-danger`; the five property-qualified body
+typography tokens; `--spacing-xs`, `--spacing-sm`, `--spacing-md`, and
+`--spacing-lg` as mapped above; `--radius-md`; `--shadow-sm` for elevated
+contexts only; `--motion-duration-fast`; and `--motion-easing-standard`. Never
+use palette primitives or raw values.
+
+## Radix/shadcn mapping
+
+Maps to [shadcn/ui Input](https://ui.shadcn.com/docs/components/input), which
+styles the native HTML `input`. Radix has no Input primitive; retain native HTML
+semantics rather than introducing a custom interaction model.

package/kiso/docs/components/label.md

@@ -0,0 +1,88 @@
+# Label
+
+## Purpose
+
+Label names a form control. It tells a person what value to provide and gives
+the control its accessible name. Every visible form control has a persistent,
+specific label; placeholder text is never a substitute.
+
+## Anatomy
+
+1. **Label text** — short, direct name for the value.
+2. **Required indicator (optional)** — textual or otherwise exposed to
+   assistive technology; color alone is insufficient.
+3. **Supplementary text (optional)** — a compact qualifier such as “Optional.”
+
+The label and control are associated with matching `for` and `id` values. A
+control wrapped by a label is valid HTML, but explicit association is the Kiso
+default because it remains clear across composed layouts.
+
+## Variants
+
+- **Default** — names one editable control.
+- **Required** — identifies a required value. Prefer marking the smaller set:
+  if most fields are required, mark optional fields instead.
+- **Optional** — appends a quiet “Optional” qualifier when that distinction is
+  useful.
+- **Group label** — use `legend` inside `fieldset`, not Label, for a related set
+  of Checkbox controls.
+
+## Sizes
+
+Label follows the associated control size rather than exposing an independent
+size API. Use all five property-qualified label typography tokens. Keep the
+label-to-control gap at `--spacing-sm`.
+
+## States
+
+| State | Behavior |
+| --- | --- |
+| Default | Uses `--color-foreground`. |
+| Hover | No independent hover treatment; clicking focuses or activates the associated control. |
+| Focus | The control owns the visible focus indicator. |
+| Active | No independent active treatment. |
+| Disabled | Uses `--color-disabled` and matches the control's disabled semantics. |
+| Loading | Remains readable while the control is loading. |
+| Error | Remains readable; error meaning belongs to ValidationMessage and the control state, not color on the label alone. |
+
+## Accessibility
+
+- Set `for` to the exact `id` of the associated control.
+- Do not hide the only accessible name. A visually hidden label is acceptable
+  only when the visual context is unambiguous and the text remains available
+  to assistive technology.
+- Required controls use native `required` when appropriate or
+  `aria-required="true"`; the visible indicator must also be explained.
+- Clicking or tapping Label moves focus to text controls and toggles Checkbox
+  or Switch through their native/Radix behavior.
+- Label adds no keyboard interaction of its own.
+
+## When to use
+
+- To name Input, Textarea, Select, Checkbox, or Switch.
+- As the Label part of FormField.
+- When a visible prompt must remain available after a value is entered.
+
+## When NOT to use
+
+- Do not use placeholder text as a label.
+- Do not use Label as a section heading or explanatory paragraph.
+- Do not use one Label for a group of controls; use `fieldset` and `legend`.
+- Do not place instructions or errors in Label; use HelperText and
+  ValidationMessage.
+
+## Tokens
+
+Use `--color-foreground` for label text, `--color-muted-foreground` for an
+optional qualifier, `--color-disabled` for disabled text;
+`--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`; and `--spacing-sm`. Do not use primitive colors
+or raw values.
+
+## Radix/shadcn mapping
+
+Maps to [Radix Label](https://www.radix-ui.com/primitives/docs/components/label)
+and [shadcn/ui Label](https://ui.shadcn.com/docs/components/label). Preserve
+Radix Label's control association and prevention of accidental text selection;
+the Kiso contract additionally requires explicit `for`/`id` association.

package/kiso/docs/components/link.md

@@ -0,0 +1,152 @@
+# Link
+
+Navigates to a URL. It does not trigger in-page behavior the way a Button
+does.
+
+## Purpose
+
+Link is the control for *going somewhere*: another route, a hash on this
+page, an external document. The browser (or router) changes location.
+
+That is a different job from [Button](button.md) (action) and
+[IconButton](icon-button.md) (icon-only action). User stories #1 and #29.
+
+### Choose the right control
+
+| Need | Control | Why |
+| --- | --- | --- |
+| Trigger behavior; URL stays put | **[Button](button.md)** | Action. |
+| Icon-only action; URL stays put | **[IconButton](icon-button.md)** | Action without visible text. |
+| Change the URL | **Link** | Navigation. Open in new tab, copy URL, and middle-click must work. |
+
+If it has an `href`, it is a Link. If it only has an `onClick`, it is a
+Button (or it is a broken Link). Do not fake navigation with a Button, and
+do not fake actions with an `<a>` that has no `href`.
+
+A Link may be *styled* to look like a Button (prominent "Open dashboard"
+call to action that still goes to a route). It remains a Link: real `href`,
+link semantics, no `role="button"`.
+
+## Anatomy
+
+```
+Link
+├── leading icon (optional)
+├── text (required, unless the icon Link has an accessible name)
+└── trailing icon (optional; external-indicator is a trailing icon)
+```
+
+- **Text.** The destination or the thing opened, not "click here". In-app:
+  "Replicas", "Query history". External: the resource name.
+- **Icon.** Optional. Decorative (`aria-hidden="true"`) when text is present.
+  An icon-only Link still needs an accessible name (`aria-label`) *and* is
+  still a Link, not IconButton.
+- **External indicator.** When the destination leaves the product, show it
+  visually (trailing icon) and in the accessible name if the visual cue is
+  not announced ("Docs (opens in a new tab)" when `target="_blank"`).
+
+## Variants
+
+Links are distinguished by *context*, not by a Button-like variant enum.
+
+| Variant | Appearance | Tokens |
+| --- | --- | --- |
+| `inline` (default) | In body copy or metadata. | Text `--color-primary`. Underline on hover at minimum; underline always in running body text so color is not the only cue (WCAG 1.4.1). |
+| `standalone` | Nav items, lists of destinations. | Text `--color-foreground` at rest; `--color-primary` on hover/current. No underline required if the placement is unambiguously navigation (Header, sidebar). Focus ring still `--color-focus`. |
+| `button-look` | A destination that must match Button visual weight. | Apply [Button](button.md) visual tokens (`primary` / `default` / `ghost`) to the Link. Keep `<a>` / router link semantics. |
+
+Current-route indication (Header, nav): `aria-current="page"` on the Link
+that matches the location. Color may use `--color-primary`; do not invent a
+"current" token.
+
+Visited: there is no visited semantic token. Keep `--color-primary` (or
+`--color-foreground` for standalone). Do not reach into the primitive
+palette for a visited purple.
+
+## Sizes
+
+Links inherit the surrounding type role. Do not invent a parallel size scale.
+
+| Context | Type role |
+| --- | --- |
+| Body copy | All five property-qualified body typography tokens |
+| Navigation, labels | All five property-qualified label typography tokens |
+| Chrome / metadata | All five property-qualified metadata typography tokens |
+| `button-look` | Same padding, radius, and five property-qualified label typography tokens as the matching [Button](button.md) size (`sm` / `md` / `lg`) |
+
+## States
+
+| State | Behavior | Tokens / notes |
+| --- | --- | --- |
+| default | Navigable. | Variant tokens above. |
+| hover | Pointer over the link. | `--color-primary` (or `--color-accent` on an already-primary inline link). Underline for `inline`. Transition `--motion-duration-fast` / `--motion-easing-standard`. |
+| focus | Keyboard focus. | Visible ring `--color-focus`. Never rely on underline alone for focus. |
+| active | Activation. | Brief press; then navigation proceeds. |
+| disabled | Rare. A destination that exists but is unavailable. | Prefer omitting the Link and explaining why. If it must remain for layout, use `aria-disabled="true"`, remove `href` (or prevent navigation), `--color-disabled`, and keep it out of the tab order. A Link with `href` that does nothing is a trap. |
+| loading | Optional, for client-side transitions. | `aria-busy="true"` on the Link or its region. Do not replace the Link with a [Spinner](spinner.md) that loses the href. |
+| error | Not a Link state. | Failed navigation belongs in [Alert](alert.md). |
+
+## Accessibility
+
+- Render a real `<a href="…">` or the framework equivalent that still
+  produces one (e.g. Next.js `Link`). No `div` + click handler.
+- `href` is required. `#` as a fake href for an action is a Button in
+  disguise — rewrite it as Button.
+- Accessible name: visible text, or `aria-label` for icon-only Links.
+- `target="_blank"` requires `rel="noopener noreferrer"` and an indication
+  that a new context opens.
+- `aria-current="page"` for the current location in a nav set.
+- Do not set `role="button"` on a Link. Do not handle `Space` as activation
+  to mimic Button; Space scrolls, Enter follows the link.
+- Underline (or another non-color cue) in running text.
+
+### Keyboard
+
+| Key | Action |
+| --- | --- |
+| `Enter` | Follow the link. |
+| `Tab` / `Shift+Tab` | Move focus. |
+| `Space` | Does **not** follow the link (page scroll). |
+
+Browser shortcuts (new tab, copy link address, back) must keep working —
+another reason this cannot be a `<button>`.
+
+## When to use
+
+- In-app routing: another view, a record, settings, docs hosted in-product.
+- External URLs.
+- In-page anchors (`#anatomy`).
+- Header navigation. Header composes Link + IconButton (later slice).
+- Any control the person should be able to bookmark, share, or open in a
+  new tab.
+
+## When NOT to use
+
+- **Actions.** Submit, save, delete, open a dialog, run a job —
+  [Button](button.md) or [IconButton](icon-button.md).
+- **A control whose `href` is unknown until click.** If there is no URL
+  until after a side effect, it is an action (Button), then optionally
+  navigate.
+- **Toggles, disclosures, tabs.** Those have their own components; a Link
+  that only swaps a panel without a URL is a Button or a Tab.
+- **Breadcrumb separators or decorative slashes.** Those are not Links;
+  only the path segments that go somewhere are.
+
+## Radix/shadcn mapping
+
+No Radix Link primitive. No shadcn Link component.
+
+| Kiso | Reference |
+| --- | --- |
+| Semantics and keyboard | Native `<a>` / platform router Link |
+| `button-look` visuals | shadcn [Button](https://ui.shadcn.com/docs/components/button) `buttonVariants` (or equivalent classes) applied to `<a>` |
+| Icon-only Link name | Same `aria-label` rule as [IconButton](icon-button.md), but the element is still `<a href>` |
+
+shadcn documents an "As Link" pattern and warns that some Button
+implementations force `role="button"`, which **overrides** link semantics.
+If the chosen Button primitive does that, do not wrap the Link in it. Apply
+visual classes to the anchor instead.
+
+Do not use shadcn `variant="link"` on a `<button>`. That produces a Button
+that looks like a Link — the inverse of this spec, and the usual agent
+mistake for user stories #1 and #29.