@teamblind-chorus/ui 1.0.0 → 1.1.0

package/agents/AGENTS.md

@@ -9,10 +9,10 @@ Entrypoint for AI agents, external renderers, and design tools (Lovable, v0, Cur
 Five directives. Apply in order; later directives never override earlier ones.
 
 1. **Design-system-first (Source of Truth).** Chorus is the source of truth for every surface. Start from Chorus tokens, components, and patterns — not generic libraries, screenshot inference, or invented values. Begin every task by reading [`schema/manifest.json`](schema/manifest.json) + [`schema/catalog.md`](schema/catalog.md).
-2. **Component flexibility — extrapolate, don't fork.** Read the intent and respect each component's anatomy invariants (slot grammar, sizing tokens, state contract), but flex composition (slot fill, layout placement, modifier props) to fit context. The contract is the token bindings and spec slot rules, not the example screenshot. The family's `visualReuse` flag in `<family>.family.json` says how far flexibility extends — `"open"` families (section, banner, feed, list, button, chip, badge, navigation-bar, tab-bar, tabs, suggestion-list, avatar-rail, thumbnail) may be picked **on visual-fit grounds even when the brief's intent does not match `useCases` verbatim**; `"locked"` families (dialog, bottom-sheet, toast, tooltip, form-field — interaction-contract primitives) MUST only be used in their canonical role. Never wrap a Chorus component to restyle — re-compose with the slots it already gives you.
+2. **Component flexibility — extrapolate, don't fork.** Read the intent and respect each component's anatomy invariants (slot grammar, sizing tokens, state contract), but flex composition (slot fill, layout placement, modifier props) to fit context. The contract is the token bindings and spec slot rules, not the example screenshot. The family's `visualReuse` flag in `<family>.family.json` says how far flexibility extends — `"open"` families (avatar-rail, badge, banner, bubble, button, carousel, chip, directory-list, divider, feed, header, list, metadata, nav-card, nav-list, navigation-bar, page-shell, pagination, profile-header, progress, side-sheet, skeleton, status-tag, suggestion-list, switch, tab-bar, tabs, thumbnail) may be picked **on visual-fit grounds even when the brief's intent does not match `useCases` verbatim**; `"locked"` families (dialog, bottom-sheet, toast, tooltip, form-field — interaction-contract primitives) MUST only be used in their canonical role. Never wrap a Chorus component to restyle — re-compose with the slots it already gives you.
 3. **New surfaces stay token-true.** When Chorus has no component for what the surface needs, design a new screen or primitive. Every color, spacing, typography, radius, and border-width MUST resolve through Chorus tokens and the foundations in [`schema/DESIGN.md`](schema/DESIGN.md). No raw hex, no off-scale px, no third-party type ramp — regardless of novelty.
 4. **Lego-block composition.** Combine and extend existing components Lego-style — nest, group, sequence, re-purpose. Tokens stay non-negotiable; components are the flexible part. A novel screen should still read as one harmony with the system.
-5. **UX-pattern consistency.** Pick components by expected interaction when interaction is the point — Dialog for modal commits, BottomSheet for committed-sheet flows, Toast for non-blocking feedback, Tooltip for trigger-anchored hints, FormField for real text entry. These five (`visualReuse: "locked"`) MUST NOT be borrowed for shape alone — focus trap, auto-dismiss, ARIA live region, hover/focus trigger, `<input>` semantics are the contract. The other thirteen (`"open"`) carry interaction defaults too — List for menus/pickers, Feed for authored content, Chip vs Button for facet vs commit — but defaults are *suggestions*, not rules; pick by visual fit when the design calls for it. Across a flow, keep behavior/motion/affordance predictable regardless of tier.
+5. **UX-pattern consistency.** Pick components by expected interaction when interaction is the point — Dialog for modal commits, BottomSheet for committed-sheet flows, Toast for non-blocking feedback, Tooltip for trigger-anchored hints, FormField for real text entry. These five (`visualReuse: "locked"`) MUST NOT be borrowed for shape alone — focus trap, auto-dismiss, ARIA live region, hover/focus trigger, `<input>` semantics are the contract. The other twenty-eight (`"open"`) carry interaction defaults too — List for menus/pickers, Feed for authored content, Chip vs Button for facet vs commit — but defaults are *suggestions*, not rules; pick by visual fit when the design calls for it. Across a flow, keep behavior/motion/affordance predictable regardless of tier.
 
 The "Hard rules" below are the machine-checkable carve-outs — principles tell you *how to think*; hard rules tell you *what not to ship*.
 
@@ -27,7 +27,7 @@ MCP server at [`apps/mcp-server`](apps/mcp-server) exposes the schema to any MCP
 1. **[`schema/manifest.json`](schema/manifest.json)** — single entry point. Every family, sub-component, resolved-token bundle, JSON Schema. Never crawl `schema/components/` to infer system shape.
 2. **[`schema/catalog.md`](schema/catalog.md)** — intent → component map. Pick components before reading specs.
 3. **`schema/components/<family>/<sub>.spec.json`** — per-sub-component contract: props, slots, sizes, appearances, states, behavior.
-4. **[`schema/tokens/resolved.light.json`](schema/tokens/resolved.light.json)** / **[`resolved.dark.json`](schema/tokens/resolved.dark.json)** — flat `path → { $value, $type }` for rendering. Fall back to `reference.json` + `system.json` only for the dependency graph. `resolved.web.*.json` are sparse `≥800px` overlays.
+4. **[`schema/tokens/resolved.light.json`](schema/tokens/resolved.light.json)** / **[`resolved.dark.json`](schema/tokens/resolved.dark.json)** — flat `path → { $value, $type }` for rendering. Fall back to `reference.json` + `system.json` only for the dependency graph. `resolved.web.json` / `resolved.web.dark.json` are sparse `≥800px` overlays.
 5. **[`schema/DESIGN.md`](schema/DESIGN.md)** — cross-cutting rules every spec defers to (color quartets, focus rings, no-layout strokes, state overlays). Keep loaded.
 6. **[`patterns/`](patterns)** — canonical pixel references as function-grouped image boards (`actions`, `browsing`, `communications`, `layout`, `modals`, `visual`) + notes. Consult when matching a new composition to a signed-off visual target.
 
@@ -38,7 +38,7 @@ MCP server at [`apps/mcp-server`](apps/mcp-server) exposes the schema to any MCP
 Not expressible in JSON Schemas. Agents MUST encode as guardrails.
 
 1. **Token-only color, type, space, radius.** Every visible value resolves to a `sys.*` (or `ref.*` if no semantic alias) from `resolved.*.json`. No literal hex, no `color-mix()`, no magic numbers. Exception: exact pixel values already in a spec's `sizing` block (e.g. `"160px"` minWidth on `standard`).
-2. **Color pairs travel together.** `sys.color.<role>Container` foreground MUST be `sys.color.on<Role>Container`. Retune the token; never split the pair. See [memory: token pairs].
+2. **Color pairs travel together.** `sys.color.<role>Container` foreground MUST be `sys.color.on<Role>Container`. Retune the token; never split the pair. See [`schema/DESIGN.md`](schema/DESIGN.md) color quartets.
 3. **No-layout strokes & focus rings.** Edge strokes are inset `box-shadow`, never `border:`. Focus rings are `::after` overlays. State/focus MUST NOT reflow the control. Always `box-sizing: border-box`. **Cards hosting a full-bleed child with its own opaque fill (cover band, hero thumbnail, header band under `overflow: hidden`) promote the outline stroke to the same `::after` overlay layer the focus ring uses** — an inset shadow on the card paints below the child and gets masked at edges the child touches. See [`schema/DESIGN.md`](schema/DESIGN.md).
 4. **Slot contract is closed.** `slots` enumerates every region. Do not introduce undeclared slots. Respect `slotCompatibility` when present.
 5. **States compose via overlay, not replacement.** Hover/pressed/focused/disabled overlay the resolved `appearance`. Use `DESIGN.md`'s recipe; do not invent per-component recipes.
@@ -139,5 +139,3 @@ Conventional Commits. Format: `type(scope): subject`.
 - **spec** — `<sub>.spec.json`: machine-readable contract for one sub-component.
 - **family.json** — family-level index: sub-components + family-wide axes (e.g. `flavor: ["default", "destructive"]`).
 - **resolved tokens** — `tokens/resolved.<theme>.json`: flat, fully-dereferenced bundles.
-
-[memory: token pairs]: claude-memory/feedback_token_pairs.md

package/agents/DESIGN.md

@@ -1,5 +1,7 @@
 # Chorus design rationale
 
+> 🇰🇷 한국어: [`i18n/ko/schema/DESIGN.md`](../i18n/ko/schema/DESIGN.md)
+
 > Single source of truth for every design rule in Chorus.
 
 Token JSON files in [`schema/tokens`](schema/tokens) hold values only; their meaning, intent, and usage live here. For an orientation to the repo, see [`README.md`](../README.md).