@momoi-labs/kiso 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Momoi Labs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,63 @@
+# Momoi Labs Blueprint
+
+> The shared foundation every Momoi Labs project builds on — a **design
+> system** (Kiso), a **log format**, and the engineering standards that keep
+> the studio's output consistent, recognizable, and fast to start.
+
+**Blueprint** is the "floor plan" of the house. It stays deliberately small: a
+pillar is added only when a real project needs it, and each pillar is a single
+source of truth that everything else generates from — never a copy.
+
+## Status
+
+| Pillar | What it defines | Status |
+| --- | --- | --- |
+| **Design system** — *Kiso* | brand, tokens, component contracts, product patterns, accessibility | ✅ v1 complete (#1–#5) |
+| **Log format** | one structured JSON shape, levels, privacy rules | 🚧 epic planned |
+| **Code standards** | commits, branches, per-language lint/format | 🔜 later |
+| **Governance** | issue/PR templates, CONTRIBUTING, code of conduct | 🔜 later |
+
+## Design system — Kiso
+
+**Kiso** (基礎, "foundation") is Momoi Labs' design system for *products* — not
+the marketing site. The marketing site ([momoi-labs.dev](https://momoi-labs.dev))
+is a vibe reference; product UI borrows its spirit, not its literal surface.
+
+Kiso v1 is complete and ready to consume. Start with the
+[Kiso entry point](kiso/README.md); agents must also follow the scoped
+[consumption rules](kiso/AGENTS.md). The system includes its conceptual
+foundation, machine-readable tokens and generated CSS, component contracts,
+product patterns, data-interface guidance, and cross-layer accessibility rules.
+
+- Dark theme by default, light ("slate") as the alternate
+- Neutrals carry the interface; one accent carries attention
+- Inter for interface text, JetBrains Mono for code
+
+## Log format
+
+One structured JSON shape across every service, so logs correlate, filter, and
+read the same everywhere. The format and its rationale — levels, `trace_id`,
+privacy rules — are specified in their own epic.
+
+## Roadmap
+
+The design system and log format pillars are driven by GitHub epics:
+
+1. ~~**Brand and principles**~~ ✅ — brand, principles, and voice in
+   [#1](https://github.com/momoi-labs/blueprint/issues/1).
+2. ~~**Design tokens**~~ ✅ — WCAG AA-calibrated semantic tokens and generated
+   CSS in [#2](https://github.com/momoi-labs/blueprint/issues/2).
+3. ~~**Component contracts**~~ ✅ — the spec-first component catalog in
+   [#3](https://github.com/momoi-labs/blueprint/issues/3).
+4. ~~**Product patterns**~~ ✅ — screen compositions and data-heavy interface
+   guidance in [#4](https://github.com/momoi-labs/blueprint/issues/4).
+5. ~~**Consumption layer**~~ ✅ — agent rules, entry point, accessibility, and
+   evolution guidance in [#5](https://github.com/momoi-labs/blueprint/issues/5).
+6. **Log format** — the shape, examples of use, and the reasoning behind it.
+
+## License
+
+Code, config, and templates: **MIT**. Brand assets (name, logo, type):
+**CC BY 4.0** — brand usage rules live in [`kiso/docs/brand.md`](kiso/docs/brand.md).
+
+© 2026 Momoi Labs — [momoi-labs.dev](https://momoi-labs.dev)

package/kiso/AGENTS.md

@@ -0,0 +1,50 @@
+# Kiso consumption rules
+
+These instructions govern how agents consume Kiso when designing or building
+Momoi Labs product interfaces. Engineering rules remain in the repository root
+[`AGENTS.md`](../AGENTS.md).
+
+Read [`README.md`](README.md) for the system map, then consult the relevant
+token, component, and pattern contracts before making interface decisions.
+
+## Hard rules
+
+1. **Before creating a new component, check whether Kiso already has a
+   component or pattern that solves the problem.** Start with the
+   [component catalog](docs/components/README.md) and
+   [pattern catalog](docs/patterns/README.md).
+2. **Do not introduce ad-hoc colors, spacing, radius, typography, or
+   interaction patterns if an equivalent token or pattern already exists.**
+   Use the documented [tokens](docs/tokens.md) and existing contracts. A
+   convenient local default is not permission to fork the system.
+3. **When a new need arises repeatedly, propose its incorporation into Kiso
+   rather than copying it independently across applications.** Record the need
+   and evidence so the system can evolve from real product work.
+
+## Decision boundary
+
+| May decide alone | Must not decide alone |
+| --- | --- |
+| Layout details within the constraints of an existing pattern | Add or change a token |
+| Product copy that follows the [voice and tone](docs/voice-and-tone.md) rules | Add or change a component contract |
+| Which existing component, pattern, or semantic token best fits the documented need | Add or change a pattern contract |
+| Responsive composition when the relevant contracts leave the choice open | Deviate from the [accessibility rules](docs/accessibility.md) |
+
+For a decision in the right-hand column, stop and propose the change instead
+of silently implementing it. A one-off product exception must be explicit and
+documented; it does not become Kiso by repetition or copy-paste.
+
+## Consumption sequence
+
+1. Identify the product task and required states.
+2. Choose the closest existing [pattern](docs/patterns/README.md).
+3. Compose it from documented [components](docs/components/README.md).
+4. Apply semantic [tokens](docs/tokens.md), not raw visual values.
+5. Apply [voice and tone](docs/voice-and-tone.md) and
+   [accessibility](docs/accessibility.md) requirements.
+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.
+Deliberate omissions and the evidence-based growth model are recorded in
+[`docs/evolution.md`](docs/evolution.md).

package/kiso/README.md

@@ -0,0 +1,62 @@
+# Kiso
+
+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.
+
+## For agents
+
+Read [`AGENTS.md`](AGENTS.md) before designing or implementing an interface.
+It defines the reuse rules, the decisions you may make alone, and the changes
+you must propose rather than invent locally.
+
+Use this path through the system:
+
+1. Understand the [brand](docs/brand.md), [principles](docs/principles.md), and
+   [voice and tone](docs/voice-and-tone.md).
+2. Select a screen-level composition from the
+   [pattern catalog](docs/patterns/README.md).
+3. Compose it with contracts from the
+   [component catalog](docs/components/README.md).
+4. Apply the semantic values documented in [tokens](docs/tokens.md).
+5. Verify the cross-layer [accessibility rules](docs/accessibility.md).
+6. For dense technical products, also follow
+   [data-interface guidance](docs/data-interfaces.md).
+
+## For humans
+
+Start with the conceptual documents to understand what makes a product feel
+like Momoi Labs. Browse the component catalog for individual UI contracts and
+the pattern catalog for complete flows and screen compositions. Each component
+document covers anatomy, states, accessibility, usage, and token consumption;
+each pattern document covers composition, behavior, responsive rules, and
+keyboard flow where relevant.
+
+## Directory map
+
+| Path | Purpose |
+| --- | --- |
+| [`AGENTS.md`](AGENTS.md) | Consumption contract and decision boundaries |
+| [`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 |
+| [`docs/tokens.md`](docs/tokens.md) | Semantic token model and generated outputs |
+| [`docs/components/`](docs/components/README.md) | Component contracts and catalog |
+| [`docs/patterns/`](docs/patterns/README.md) | Screen and behavior patterns |
+| [`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 |
+
+Token sources and generated artifacts live in the repository-level `tokens/`
+directory; validation scripts live in `scripts/`.
+
+## Proposing a change
+
+First confirm that an existing token, component, or pattern cannot express the
+need. Then capture the product case, the limitation in the current contract,
+and evidence that the need recurs. Propose the smallest system-level addition
+instead of copying a local solution between applications. See
+[`docs/evolution.md`](docs/evolution.md) for what v1 deliberately defers and
+when those decisions should be reconsidered.

package/kiso/docs/accessibility.md

@@ -0,0 +1,87 @@
+# Accessibility
+
+Accessibility is a requirement at every Kiso layer, not a final review step.
+An implementation is incomplete if it cannot be understood and operated with
+a keyboard, screen reader, touch input, or reduced-motion preference.
+
+## Tokens
+
+- Use semantic color tokens documented in [`tokens.md`](tokens.md); do not
+  substitute raw colors or infer contrast from appearance.
+- Text and meaningful graphical controls must meet the applicable WCAG AA
+  contrast requirement in every supported state, including hover, focus,
+  disabled, selected, warning, and error states.
+- Run `node scripts/check-contrast.mjs` after token changes. The contrast gate
+  validates the committed foreground/background pairs, but it does not excuse
+  checking new product compositions or non-text contrast.
+- Do not communicate meaning with color alone. Pair status and errors with
+  text, an icon with an accessible name, or another programmatic cue.
+- Respect `prefers-reduced-motion`. Remove nonessential movement and replace
+  essential transitions with an immediate or substantially reduced alternative.
+
+## Components
+
+- Start with native semantic HTML. Add ARIA only when native semantics cannot
+  express the required behavior; ARIA does not repair incorrect interaction.
+- Follow the **Accessibility** section in every
+  [component contract](components/README.md). It is the source of truth for
+  roles, accessible names, state attributes, focus behavior, and keystrokes.
+- 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
+  without overlapping another target.
+- Give icon-only controls an accessible name. Decorative icons must be hidden
+  from assistive technology.
+
+## Patterns and focus flows
+
+- Follow the keyboard and focus flow in the relevant
+  [pattern contract](patterns/README.md); do not invent a competing shortcut or
+  navigation model locally.
+- When opening a modal surface, move focus into it, contain focus while it is
+  active, support `Escape` when dismissal is allowed, and restore focus to the
+  trigger when it closes. Use the component contract for exact behavior.
+- On route or major view changes, place focus at the start of the new content or
+  announce the change as appropriate. Do not leave focus on an element that no
+  longer exists.
+- Keyboard shortcuts must not override browser or assistive-technology
+  commands. Make nonstandard shortcuts discoverable and provide an equivalent
+  visible action.
+
+## Content, errors, and updates
+
+- Preserve a logical heading hierarchy, landmarks, lists, tables, labels, and
+  relationships in the HTML. Visual arrangement is not a semantic structure.
+- Associate every form control with a visible label and its instructions.
+  Identify required fields in text or programmatically, not by color alone.
+- Error messages must state what happened and what to do next, following
+  [`voice-and-tone.md`](voice-and-tone.md). Associate field errors with their
+  controls, set the invalid state programmatically, and move or summarize focus
+  so a failed submission is discoverable without scanning the page.
+- Announce asynchronous status changes with the least disruptive suitable live
+  region. Do not move focus merely to announce success, loading, or background
+  updates.
+- Data tables must retain native table relationships and accessible headers.
+  Use the [Table contract](components/table.md), relevant
+  [data-interface guidance](data-interfaces.md), and the
+  [large-data-table pattern](patterns/large-data-tables.md).
+
+## Verification before merge
+
+1. Navigate the complete flow using only the keyboard, including cancellation,
+   recovery, and destructive-action paths.
+2. Check focus visibility, order, containment, and restoration.
+3. Test names, roles, states, labels, errors, and dynamic updates with a screen
+   reader.
+4. Verify text and non-text contrast in every state and run the token contrast
+   gate when tokens are involved.
+5. Enable reduced motion and confirm no essential information depends on
+   animation.
+6. Check touch targets at narrow viewports and zoom the interface to 200%
+   without losing content or operation.
+
+When an existing contract conflicts with these rules, do not silently deviate.
+Document the conflict and propose a Kiso change under the decision boundary in
+[`../AGENTS.md`](../AGENTS.md).

package/kiso/docs/brand.md

@@ -0,0 +1,95 @@
+# Brand — Momoi Labs Product Identity
+
+Kiso (基礎, "foundation") is Momoi Labs' design system for **products**. This
+document defines what "Momoi" means visually in a product interface — the
+personality that every screen inherits.
+
+It is **not** the marketing brand. The marketing site (momoi-labs.dev) has its
+own brand assets, logo usage, and experimental aesthetics. Kiso borrows the
+*spirit* of the site, not its literal surface.
+
+## Personality
+
+Momoi's product identity is **practical, technical, open, calm, precise,
+useful, curious, human, understated.**
+
+| Trait | What it means in a product UI |
+| --- | --- |
+| **Practical** | Every element serves a purpose. Nothing is there just to look good. |
+| **Technical** | Comfortable with dense data, monospace, and precise values. Speaks the developer's language. |
+| **Open** | Transparent about what the system is doing. No hidden state, no mystery. |
+| **Calm** | Low visual noise. Whitespace and hierarchy do the work, not color shouting. |
+| **Precise** | Exact labels, exact values, exact states. "About 3" is not a Momoi number unless the data is genuinely approximate. |
+| **Useful** | The interface helps you do something. Decoration that does not help is removed. |
+| **Curious** | Invites exploration and experimentation, especially in small experimental products. |
+| **Human** | Written by two people, not a committee. The voice acknowledges humans built and use this. |
+| **Understated** | Confident enough not to show off. Lets the work speak. |
+
+## What Momoi is not
+
+- **Corporate.** No enterprise-flat, no stock-photo warmth, no "powered by"
+  flourishes.
+- **Marketing-heavy.** No hero gradients, no call-to-action urgency, no
+  growth-hack copy in the product.
+- **Flashy.** No gratuitous animation, no neon accents, no decorative
+  glassmorphism. Motion serves feedback, not delight for its own sake.
+
+## Relationship to the marketing site
+
+The marketing site has a **terminal aesthetic**: dark background, monospace
+accents, terminal-flavored copy ("~/ABOUT" navigation, "$ export THEME=light"
+theme toggle, "Small, unfinished, useful.").
+
+For products, the site is a **vibe reference, not a literal spec**:
+
+- **Extract:** the directness, the structure, the comfort with technical
+  language, the understated confidence.
+- **Tone down:** the literal terminal flourish. Product UI does not prefix
+  navigation with "~/" or frame actions as shell commands. Directness and
+  structure are universal; terminal flourish is reserved for chrome and
+  metadata only (see [voice-and-tone.md](./voice-and-tone.md)).
+
+The site is more experimental than products need to be. Products are lived in;
+the site is visited.
+
+## Accessibility
+
+Product UIs must meet **WCAG AA** contrast for all text. The marketing site's
+violet accent (`#9184d9`) is acknowledged as insufficient for normal text
+against the site's dark background (~3.8:1). This is acceptable for the
+marketing site's experimental surface but **not** for products.
+
+Kiso's token palette (a later epic) calibrates neutrals and accent to AA-safe
+levels. The brand commitment — accessible contrast as a default, not an
+afterthought — starts here.
+
+## Palette direction (conceptual, not values)
+
+Kiso's palette is dark-first, with a light alternate, mirroring the marketing
+site's spirit:
+
+- **Dark theme** is the default product surface.
+- **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.
+
+Exact token values land in the tokens epic. The brand direction: a calm,
+high-contrast dark surface where one accent does focused work.
+
+## When this document is the authority
+
+Use this document when:
+
+- Deciding whether a UI element "feels Momoi."
+- Choosing between two visual directions and needing a tie-breaker grounded in
+  personality.
+- Onboarding a new product or screen to the Momoi product family.
+
+For *design rules* (useful over decorative, clarity over cleverness, etc.), see
+[principles.md](./principles.md). For *how copy sounds*, see
+[voice-and-tone.md](./voice-and-tone.md).
+
+---
+
+*Small lab, not a 200-person design team. Keep this short. Grow it through real
+product use.*

package/kiso/docs/components/README.md

@@ -0,0 +1,58 @@
+# Kiso component catalog
+
+Kiso defines product UI as markdown contracts rather than implementation code.
+Each contract specifies anatomy, states, accessibility, usage guidance, semantic
+token consumption, and a Radix/shadcn behavioral reference where one exists.
+
+## Nucleus
+
+- [Alert](alert.md) — Communicates persistent in-page information, success, warnings, or errors.
+- [Badge](badge.md) — Labels status or compact metadata without becoming an action.
+- [Button](button.md) — Triggers a visible, text-labeled action without changing the URL.
+- [Card](card.md) — Groups related content and actions with visual separation.
+- [Checkbox](checkbox.md) — Toggles an option in a list or selects multiple values.
+- [FormField](form-field.md) — Composes Label, a form control, HelperText, and ValidationMessage with consistent ID and ARIA wiring.
+- [HelperText](helper-text.md) — Provides persistent, non-error context for a form control.
+- [IconButton](icon-button.md) — Triggers a compact icon-only action with a required accessible name.
+- [Input](input.md) — Collects a single-line text-like value.
+- [Label](label.md) — Gives a form control its visible, programmatically associated name.
+- [Link](link.md) — Navigates to a URL while preserving native link behavior.
+- [Select](select.md) — Chooses one value from a predefined set of options.
+- [Skeleton](skeleton.md) — Preserves known layout while its content is loading.
+- [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.
+- [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.
+
+## Data
+
+- [CommandPalette](command-palette.md) — Searches and runs global actions or navigation from a keyboard-first overlay.
+- [DropdownMenu](dropdown-menu.md) — Presents contextual actions anchored to a specific object or trigger.
+- [EmptyState](empty-state.md) — Replaces an empty collection with an explanation and optional next action.
+- [Search](search.md) — Filters visible content such as a list or table.
+- [Table / DataTable](table.md) — Presents structured records with optional sorting, selection, filtering, and pagination.
+
+## Navigation and structure
+
+- [Breadcrumb](breadcrumb.md) — Shows the current location within a hierarchy.
+- [Header](header.md) — Composes persistent application navigation and global actions.
+- [Navigation](navigation.md) — Provides a generic semantic container for destination links.
+- [PageHeader](page-header.md) — Composes a page title, optional subtitle, and page-scoped action Buttons.
+- [Pagination](pagination.md) — Moves through known pages while exposing the current position.
+- [Sidebar](sidebar.md) — Organizes persistent navigation into optionally collapsible sections.
+- [Tabs](tabs.md) — Switches among related content panels within the same page context.
+
+## Overlay
+
+- [Drawer](drawer.md) — Presents a viewport-adaptive panel, including a mobile alternative to Modal/Dialog.
+- [Modal / Dialog](modal-dialog.md) — Blocks the page for a focused task that requires attention or a decision.
+- [Popover](popover.md) — Shows rich, interactive contextual content anchored to a trigger.
+- [Toast](toast.md) — Reports transient system feedback without replacing in-page status or field errors.
+
+## Required compositions
+
+- [FormField](form-field.md) composes [Label](label.md) + [Input](input.md) (or another form control) + [HelperText](helper-text.md) + [ValidationMessage](validation-message.md).
+- [Header](header.md) composes [Link](link.md) + [IconButton](icon-button.md) + optional [DropdownMenu](dropdown-menu.md).
+- [Table / DataTable](table.md) composes [EmptyState](empty-state.md), [Skeleton](skeleton.md), and [Pagination](pagination.md) for empty, loading, and paged states.
+- [PageHeader](page-header.md) composes a title + optional subtitle + [Buttons](button.md).

package/kiso/docs/components/alert.md

@@ -0,0 +1,158 @@
+# Alert
+
+An in-page message about a condition the person should see in context.
+Severity is explicit. It stays until dismissed or until the condition ends.
+
+## Purpose
+
+Alert explains something about *this view*: a failed load, a degraded
+replica, a successful save that still needs a next step, a warning before
+continuing. It sits in the page flow, not in a corner toast and not on a
+single form field.
+
+User stories #6 and #24.
+
+### Choose the right feedback
+
+| Need | Control | Why |
+| --- | --- | --- |
+| In-page condition, stays in context | **Alert** | Persistent or dismissible, with severity. |
+| Transient system notice (saved, copied, background job) | **Toast** (overlay slice) | Time-limited; must not be the only copy of essential info. |
+| A specific field is invalid | **ValidationMessage** (form slice) | Anchored to the field; not a page banner. |
+
+Do not restyle Alert into a toast. Do not use Alert for every validation
+error in a form.
+
+## Anatomy
+
+```
+Alert
+├── severity icon (required)
+├── Title (required)
+├── Description (required for error and warning; optional for info/success
+│   when the title is already a complete sentence)
+├── Action (optional: recovery Button or Link)
+└── Dismiss (optional IconButton; only when dismissible)
+```
+
+- **Severity icon.** Matches the variant. Decorative if the title names the
+  severity in words; otherwise the accessible name of the Alert must include
+  the severity ("Error: replica unreachable").
+- **Title.** What happened. Direct. Not "Oops", not an error code alone.
+- **Description.** Follow [voice-and-tone](../voice-and-tone.md) for errors:
+  what happened, why when knowable, what the person can do now. Warning uses
+  the same structure with a lower-stakes next step. Info/success: what is
+  true, and a next step if there is one.
+- **Action.** A real [Button](button.md) or [Link](link.md) that performs the
+  recovery ("Retry", "Open settings"). Do not bury the only recovery in
+  Description prose if a control can do it.
+- **Dismiss.** [IconButton](icon-button.md) `ghost` `sm`, `aria-label`
+  "Dismiss". Only on dismissible Alerts.
+
+## Variants
+
+Four severities. There is no extra "destructive" variant — that is `error`.
+
+| Variant | Live region | Tokens |
+| --- | --- | --- |
+| `info` | `role="status"` (polite) | Border and icon `--color-info`. Title `--color-foreground`. Description `--color-muted-foreground`. Background `--color-surface`. |
+| `success` | `role="status"` (polite) | Same structure with `--color-success`. |
+| `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
+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
+`--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` properties.
+
+Do not fill the Alert with the status color. Status color is border, icon,
+and (optionally) title. A solid `--color-danger` panel fights contrast and
+shouts past the content.
+
+### Dismissible vs persistent
+
+| Kind | Behavior |
+| --- | --- |
+| **Persistent** | Stays while the condition is true (replica down, missing permission). No dismiss. Removing it is lying. |
+| **Dismissible** | The person can clear it. Use for success confirmations and informational callouts that do not affect the next action. After dismiss, do not show the same Alert again in this visit unless the condition reoccurs. |
+
+Default for `error` and `warning` that describe a current blocker:
+persistent. Default for `success` and `info`: dismissible.
+
+## Sizes
+
+One size. Do not scale Alert like Button. Density comes from the type roles
+above. In a narrow Card, the Alert still uses `--spacing-md` padding; it
+does not shrink to `sm`.
+
+## States
+
+| State | Behavior |
+| --- | --- |
+| default | Visible, in flow. |
+| hover / active | No Alert-level hover. Children (Action, Dismiss) have their own states. |
+| focus | Focus moves to Action or Dismiss, not the Alert box. When an `error` Alert appears as a result of a submit, move focus to the Alert (or to its Action) so assistive tech and keyboard users land on it. |
+| disabled | N/A. Hide or replace the Alert; do not disable it. |
+| loading | If the condition is being retried, the Action Button shows [Spinner](spinner.md) loading. The Alert remains. |
+| error | `error` is a variant, not a state on top of another variant. |
+
+## Accessibility
+
+- `error`: `role="alert"` (implicit `aria-live="assertive"`). Use sparingly;
+  assertive interruptions stack badly. One error Alert at a time in a view.
+- `info` / `success` / most `warning`: `role="status"` (`aria-live="polite"`).
+- Name the Alert: `aria-labelledby` pointing at Title, `aria-describedby` at
+  Description.
+- Severity is in text (title or prefix), not color alone.
+- Dismiss is an IconButton with `aria-label="Dismiss"`. After dismiss, move
+  focus to a sensible place (the control that caused the Alert, or the main
+  heading) — do not dump focus to `body`.
+- Do not nest interactive content other than Action and Dismiss.
+- Do not use Radix Alert Dialog here. Alert Dialog is a modal. This
+  component never blocks the page.
+
+### Keyboard
+
+| Key | Action |
+| --- | --- |
+| `Tab` / `Shift+Tab` | Move between Action and Dismiss (and the rest of the page). |
+| `Enter` / `Space` | Activate the focused Button / IconButton (including Dismiss). |
+
+## When to use
+
+- A condition about this page or section the person should see before
+  continuing: load failure, permission, degraded dependency, completed save
+  with a next step.
+- Inline, above the affected content (form, table, replica panel).
+- Recovery can be offered as a Button or Link inside the Alert.
+
+## When NOT to use
+
+- **Field-level validation.** ValidationMessage next to the input.
+- **Transient confirmations** that must not block reading ("Copied"). Toast.
+- **Status labels** without explanation ("live"). [Badge](badge.md).
+- **A whole empty dataset.** EmptyState (data slice), optionally with a
+  Button, not an info Alert that says "nothing here".
+- **Blocking work that needs a decision.** Modal/Dialog (overlay slice).
+  Alert does not trap focus and does not block the page.
+- **Marketing callouts.** If it is not a condition of the product state, it
+  does not belong.
+
+## Radix/shadcn mapping
+
+There is **no** Radix primitive for in-page Alert.
+
+| Kiso | Reference |
+| --- | --- |
+| Structure, icon + title + description + action | shadcn [Alert](https://ui.shadcn.com/docs/components/alert) (`Alert`, `AlertTitle`, `AlertDescription`, `AlertAction`) |
+| Dismiss | Compose [IconButton](icon-button.md); shadcn has no dedicated dismiss slot |
+| `error` | shadcn `variant="destructive"` restyled to `--color-danger` (border/icon, not a filled danger panel) |
+| `info` / `success` / `warning` | shadcn `default` plus the matching `--color-info`, `--color-success`, or `--color-warning` — **not** the shadcn "Custom Colors" utility-class example (`bg-amber-50`, etc.) |
+
+Do **not** map this component to Radix
+[Alert Dialog](https://www.radix-ui.com/primitives/docs/components/alert-dialog)
+or shadcn Alert Dialog. Those are modal confirmation overlays (later slice:
+Modal/Dialog). Using them here collapses the Alert vs Modal distinction.