@sondalab/ui-kit 0.1.0 → 0.3.0

package/README.md

@@ -1,9 +1,10 @@
 # @sondalab/ui-kit
 
-Sondalab design tokens as CSS custom properties (`--sl-*`). CSS-only: no components, no build step — import the stylesheets and theme via a `data-sl-theme` attribute.
+Sondalab design tokens as CSS custom properties (`--sl-*`) plus a CSS-only component layer (`.sl-*`). No build step, no runtime JS — import the stylesheets and theme via a `data-sl-theme` attribute.
 
 ```css
 @import "@sondalab/ui-kit/tokens.css";        /* shared: type, spacing, radii, motion, shadow, z */
+@import "@sondalab/ui-kit/components.css";     /* .sl-* components (reads role-vars, see below) */
 @import "@sondalab/ui-kit/themes/light.css";  /* [data-sl-theme="light"]  surfaces, text, borders, status, accent */
 @import "@sondalab/ui-kit/themes/dark.css";
 @import "@sondalab/ui-kit/themes/high-contrast.css";
@@ -22,4 +23,44 @@ Sondalab design tokens as CSS custom properties (`--sl-*`). CSS-only: no compone
 
 **Fonts** (load separately, e.g. Google Fonts): Fraunces (display), Instrument Sans (body), Martian Mono (mono).
 
-Generated from the canonical `sondalab.tokens.json` — do not hand-edit the CSS.
+## Components (`components.css`)
+
+Primitives: `.sl-eyebrow`, `.sl-tag` (`--plain`), `.sl-btn` (`--primary` / `--ghost` / `--sm`), `.sl-card` (`__title` / `__body`), `.sl-badge` (`--success` / `--warning` / `--danger` / `--info`), `.sl-field` (`__label` / `__input`), `.sl-kbd`, `.sl-code`, `.sl-link`, `.sl-rule` (`--labeled`).
+
+Complex (composed shells — no behaviour JS; the consumer wires interaction): `.sl-callout` (`--success`/`--warning`/`--danger`/`--info`), `.sl-table` (`--numeric`; wrap in an `overflow-x:auto` container), `.sl-dialog` (visual shell for the native `<dialog>` — drive with `.showModal()`/`.close()`), `.sl-tabs` (`__list`/`__tab` — supply your own ARIA + panel switching), `.sl-tooltip` (CSS-only via `data-sl-tooltip`).
+
+### Colour contract — role-vars (`--slc-*`)
+
+Components never read theme tokens directly (those resolve only under `[data-sl-theme]`). They read role-vars that default through a fallback chain to the `--sl-*` token, then to a brand literal. **Tier A** products (full `data-sl-theme`, e.g. spexr) need zero wiring — the role-vars pick up the live theme automatically. **Tier B** products (value-pinned, e.g. daos, introspect) map the role-vars **once** to their own colour layer. That block is the *entire* integration surface:
+
+```css
+:root {
+  --slc-accent:         var(--your-accent);
+  --slc-accent-hover:   var(--your-accent-hover);
+  --slc-accent-active:  var(--your-accent-active);
+  --slc-accent-subtle:  var(--your-accent-tint);   /* ~12% accent over surface */
+  --slc-on-accent:      var(--your-on-accent);     /* text on a filled accent */
+  --slc-surface:        var(--your-surface);
+  --slc-raised:         var(--your-raised);
+  --slc-overlay:        var(--your-overlay);        /* dialog backdrop */
+  --slc-text:           var(--your-text);
+  --slc-text-secondary: var(--your-text-2);
+  --slc-text-muted:     var(--your-text-muted);
+  --slc-border:         var(--your-border);
+  --slc-border-subtle:  var(--your-border-subtle);
+  --slc-border-strong:  var(--your-border-strong);
+  --slc-focus:          var(--your-accent);
+  --slc-success: var(--your-success); --slc-warning: var(--your-warning);
+  --slc-danger:  var(--your-danger);  --slc-info:    var(--your-info);
+}
+```
+
+**Inversion bands.** `--slc-border` defaults to an alpha-over-canvas value; inside a band whose background is the strongest neutral (`.invert`), that alpha sits on the wrong ground and the hairline disappears. Re-derive it at the band from the band's foreground — no new token:
+
+```css
+.invert { --slc-border: color-mix(in srgb, currentColor 22%, transparent); }
+```
+
+The full reference implementation — every component in all three themes — is `showcase/index.html` (§04).
+
+Generated tokens (`tokens.css`, `themes/*.css`) come from the canonical `sondalab.tokens.json` — do not hand-edit them. `components.css` is hand-authored.

package/agent/HANDOFF.md

@@ -0,0 +1,52 @@
+# Agent hand-off — Sondalab DS agentic layer
+
+> **What this file is:** operational guidance for an AI agent working with the Sondalab DS agentic layer. It records what the audit does **not** mechanically check and how to handle those gaps, so you don't either (a) trust the script for things it doesn't cover or (b) mechanically "fix" intentional deviations. Read it before running a migrate/author/adopt job.
+> **Audience:** agents (and their humans) running `sl-audit.mjs` or the migrate workflow.
+> **Companion:** `README.md` (usage), `design-language.md` (the grammar, shipped alongside). The contract with its human-facing "Open decisions" is `docs/design-system-agentic-spec.md` in the source repo (https://github.com/sondalab-ai/sondalab-ui).
+
+## What the script decides — and what it does not
+
+`sl-audit.mjs` (Slice 1) mechanically checks exactly two things:
+
+1. **Colour value-equality** — every hex/rgb literal resolves to a token, the product's accent, or a blessed value.
+2. **Tier consistency** — the theme selector (`[data-sl-theme]` vs `[data-theme]`) matches the product's tier in `substrate-matrix.json`.
+
+**Everything else is your judgement.** The script is silent on it — silence is not a pass. In particular, the checks below were specified but deliberately **not** built, because the design language itself uses "violating" values in blessed places, so a mechanical flag would fire on the DS's own reference. Do not treat their absence as "these are fine"; treat them as *yours to judge*.
+
+## Deferred checks — judge these yourself, do not mechanically flag or fix
+
+### Spacing off the `--sl-space-*` scale  *(check 3 — deferred)*
+The scale is `{0, .25, .5, .75, 1, 1.5, 2, 3}rem`. But off-scale literals are legitimate in places:
+- The **canonical tag recipe** in `design-language.md` L3 is `padding: 3px 7px` — off-scale on purpose.
+- Hairline nudges (`margin-bottom: -1px` to overlap a 1px rule), optical adjustments, and `ch`/`%`/`vw`/`calc()` values.
+
+**How to judge:** new *layout* spacing (section gaps, stack rhythm, card padding) should step off `--sl-space-*`. Recipe-level and optical one-offs are fine. When in doubt, match what the nearest `design-language.md` recipe does; don't invent a new spacing literal for structural rhythm.
+
+### Border width > 1px  *(check 4 — deferred)*
+The hairline rule (L2) is about *structural separators* being 1px. But 2px borders are intentional as **emphasis accents**, not separators — confirmed in the reference: `components.css:208` (a keycap's 2px bottom edge) and `components.css:360` (a 2px active-tab underline). Focus rings also legitimately use the 2px `--sl-focus-ring-width` token (usually on `outline`, which is not a border).
+
+**How to judge:** a 1px rule that *separates* content (section top, card edge, header/footer, gutter ruler) must be 1px. A 2px edge that *emphasizes* (active-tab underline, keycap, measure-tick) is a deliberate accent — leave it. Never bump a separator to 2px; never flatten an emphasis accent to 1px.
+
+**Active/pressed control states resolve to the product accent** (amber for the `default` product; the product's registered hue otherwise) — an active tab, a pressed button, a selected control shows the accent, never a neutral. So a 2px active-state edge is coloured with the accent (or its `active` step), and a colour-value-equality finding there should map to the accent, not be flattened away.
+
+### Eyebrow / tag recipe conformance  *(check 6 — deferred)*
+For elements already named eyebrow/tag, the recipe (mono + uppercase + tracking `0.14–0.22em`) is fixed in `design-language.md` L3. The script does not verify it.
+
+**How to judge:** when you author or touch an eyebrow/tag/section-index, cite the canonical recipe in `design-language.md` and match it — don't re-derive tracking/size. When migrating, check existing eyebrow/tag elements against the recipe by eye.
+
+### Font-family  *(check 5 — dropped, not deferred)*
+Evaluated and **dropped**: the only literal faces across the calibrated surfaces are introspect's IBM Plex Mono (a blessed mono substitute) and spexr's editor font (blessed). A font check would yield nothing. Just keep using `var(--sl-font-display|sans|mono)`; the only allowed substitution is a *narrower mono* where fixed pixel grids demand it (`design-language.md` L1), recorded as a blessed `font` deviation.
+
+## Structural / judgement rules the script never sees
+
+These are always yours (the `sl-ds-auditor` subagent covers them by reading `design-language.md`), scoped to the substrate's Required column in `substrate-matrix.json`:
+
+- **Missing** structural labels (eyebrow, section index, tag) where the substrate requires them.
+- Hairline structure and the hairline-grid technique, gutter/ruler, section-index-leads-section.
+- Signature components present and matching: inversion band, sticky translucent header, real-content blocks.
+- **L5 editorial voice** — precise/technical, active, structure-encodes-truth, English identifiers.
+- The house rule: ≥1 unexpected, intentional *composition* decision per screen (spend boldness on layout, keep materials shared).
+
+## If you think a deferred check should become mechanical
+
+That is a human decision (see the spec's "Open decisions"), because it requires committing to a blessing policy for the legitimate off-scale/2px cases above. Don't add the check to `sl-audit.mjs` on your own initiative — raise it, with the specific reference example it would flag, and let the human decide.

package/agent/README.md

@@ -0,0 +1,119 @@
+# Sondalab DS — Agentic Core
+
+> **What this file is:** the usage guide for the Sondalab design-system *agentic layer* — how an AI agent (in any harness, in this repo or a consumer repo) loads this core and runs the author / migrate / adopt workflows against the shared design system.
+> **Audience:** anyone pointing an agent at a Sondalab surface — the DS maintainer, and engineers on consumer apps (spexr, introspect, daos, and future products) who want their UI to read as Sondalab without re-deriving the grammar.
+> **Status:** shipped in `@sondalab/ui-kit` (v0.3.0+). The migrate / author / adopt workflows, the component catalog, and the `sl-audit` bin all ship in the package; a consumer resolves them from `node_modules/@sondalab/ui-kit/agent/`.
+> **Companion files:** `./design-language.md` (the grammar this tooling enforces — never restated here; shipped alongside). The tooling contract and the token spec live in the source repo: `docs/design-system-agentic-spec.md` and `docs/design-system-spec.md` at https://github.com/sondalab-ai/sondalab-ui.
+
+## What this core is
+
+The design system has always had the *rules* (`design-language.md`) and the *values* (`sondalab.tokens.json`). This core adds the missing third thing: a way for an agent to **act** on them repeatably. It is deliberately thin — it holds only what the prose docs are not:
+
+| File | What it is |
+|---|---|
+| `accent-registry.json` | Machine mirror of the per-product accent table (`design-language.md` §Decision 2). |
+| `substrate-matrix.json` | The per-substrate compliance matrix (IDE/App/Page/Term → R/A/N-A) as a lookup. |
+| `blessed/<product>.json` | Per-product allowlist of authorized deviations, one justification each. |
+| `workflows/migrate.md` | The ordered migrate procedure with human gates. |
+| `workflows/author.md` | The ordered author procedure (greenfield), built on the catalog. |
+| `workflows/adopt.md` | The ordered adopt procedure (one component into an existing app). |
+| `catalog.md` + `catalog.json` | Copy-paste component catalog (primitives + signature patterns) with markup, role-vars, and substrate; its machine index. Snippets are audited clean. |
+| `HANDOFF.md` | What the audit does **not** check mechanically, and how to judge those cases (deferred spacing/border/recipe checks). Read before a job. |
+
+Everything else — the actual rules, why they exist, the compliance philosophy — stays in `design-language.md`. This core **references** it; it never forks it.
+
+The verdict engine is `sl-audit` (`agent/sl-audit.mjs`, exposed as the `sl-audit` bin). It reads this core plus the shipped token CSS (`../tokens.css` + `../themes/*.css`) and reports what is decidable from CSS text. What requires human/agent judgement (missing structural labels, editorial voice, layout composition) is out of the script's scope by design.
+
+**What the script checks today (Slice 1):** colour value-equality and theme-selector tier consistency — only. Spacing-off-scale, border width, font-family, and eyebrow/tag recipe conformance are *specified* (see the agentic spec) but **not yet implemented in the script**; until they land they are judgement-level and belong to the `sl-ds-auditor` subagent, not the audit script. A colour finding can be silenced two ways in `blessed/<product>.json`: `selectors` (a distinctive selector/property the colour sits under) or `values` (an exact colour value — for demo data with no distinctive selector).
+
+## The three workflows
+
+| Workflow | Job | For whom | Status |
+|---|---|---|---|
+| **Migrate** | Move an existing app's UI onto the DS: audit → map values to tokens → pick tier → apply L1–L5. | An app with its own palette adopting the DS wholesale (introspect, daos). | Slice 1 |
+| **Author** | Scaffold a new surface/element DS-compliant from the first line. | Greenfield screens or components. | Slice 2 — catalog + `workflows/author.md` + `sl-author` skill landed |
+| **Adopt** | Pull one signature component (eyebrow, tag, inversion band) into an app without a full migration. | Consumers wanting a taste of the family look. | Slice 3 — `workflows/adopt.md` + `sl-adopt` skill landed |
+
+All three share the same core and the same read-only auditor. Migrate is the deepest; author and adopt are subsets of its machinery.
+
+## How an agent loads the core
+
+**In Claude Code (this repo).** The wrappers do it for you:
+
+- Say *"migrate `<app>` to the Sondalab DS"* or run `/sl-migrate` → the `sl-migrate` skill drives `workflows/migrate.md` and holds the gates.
+- Say *"build a new `<screen>` in the Sondalab DS"* or run `/sl-author` → the `sl-author` skill drives `workflows/author.md` and builds from `catalog.md`.
+- Say *"add a Sondalab `<component>` to this app"* or run `/sl-adopt` → the `sl-adopt` skill drives `workflows/adopt.md` (one component, scoped to the touched file).
+- The `sl-ds-auditor` subagent runs the audit and reads `design-language.md` for the judgement-level findings, returning them grouped by severity with `file:line`.
+
+**In any other harness / a consumer repo.** `npm i @sondalab/ui-kit`, then point the agent at the installed core and give it the relevant workflow as its instructions:
+
+1. `node_modules/@sondalab/ui-kit/agent/` (this core — registry, matrix, blessed, catalog, workflows),
+2. `node_modules/@sondalab/ui-kit/agent/design-language.md` (the grammar),
+3. `node_modules/@sondalab/ui-kit/tokens.css` + `themes/*.css` (the values the audit checks against).
+
+Then run the audit via the shipped bin:
+
+```sh
+npx sl-audit --surface "web/src/**/*.css" --product introspect --substrate App
+```
+
+Surface globs resolve against your current working directory; the audit resolves the token allowlist from the installed package.
+
+## Reading an audit report
+
+Findings are bucketed by enforceability — a flat list would destroy the tier nuance the DS is built on:
+
+- **R-violation (blocking)** — a required rule is broken. Must reach zero (or be blessed) before a migration is done.
+- **A-deviation (needs justification)** — an adapt-level rule diverges. Either bless it (record why in `blessed/<product>.json`) or fix it.
+- **N/A** — not applicable to this substrate. Never printed.
+
+Example (illustrative):
+
+```
+introspect  (App, Tier B)   —  sl-audit
+
+R-violation (2)
+  web/src/theme.css:44   colour #3aa0ff does not resolve to a token, accent, or blessed value
+  web/src/theme.css:12   selector [data-sl-theme] but product declared Tier B ([data-theme])
+
+A-deviation (1)
+  web/src/theme.css:88   #1e2a24 on-ink status green — bless or fix (design-language.md §Decision 2)
+
+N/A: 6 rules skipped for substrate App
+```
+
+## Use cases
+
+### 1 — Maintainer migrates a live app (Migrate, Slice 1)
+
+> *"Migrate daos to the Sondalab DS."*
+
+The agent classifies daos as **Page / Tier B**, runs a **baseline audit**, and separates real defects from blessed deviations. daos's `--rule`/`--rule-2` (alpha-on-canvas hairlines) and its `.artifact .ok`/`.no` (on-ink status pairs) are *authorized* by `design-language.md` — they go into `blessed/daos.json`, not the defect list. The remaining R-violations become a **token-mapping plan**, presented in chat. **Nothing is edited until you say yes.** After approval the agent applies the mapping in small chunks, re-audits (R-violations → 0), and does a visual pass across light/dark/high-contrast — including the dark-invert hairline regression that alpha-on-canvas rules are prone to.
+
+### 2 — Consumer app adopts one component (Adopt, Slice 3)
+
+> *"Add a Sondalab eyebrow + tag to our settings header, we're not migrating everything yet."*
+
+The agent pulls the canonical eyebrow/tag recipe from `design-language.md` L3, binds it to the consumer's local colour vars (Tier B — values must still resolve to Sondalab), and runs the audit scoped to the touched file only. No full migration; the rest of the app is untouched.
+
+### 3 — Greenfield element, compliant from the start (Author, Slice 2)
+
+> *"Scaffold a new empty-state panel for introspect."*
+
+The agent starts from the substrate (App), applies the required rules for that column of the matrix (mono structural labels, hairline structure, spacing off `--sl-space-*`, one accent hue), and the audit passes on first run because compliance was built in, not retrofitted.
+
+### 4 — CI guard (any slice)
+
+The audit is deterministic, so it runs headless:
+
+```sh
+npx sl-audit --surface "web/src/**/*.css" --product introspect --substrate App --fail-on R
+```
+
+A non-zero exit on any unblessed R-violation keeps a merged surface from drifting off the DS — the prose "compliance test" in `design-language.md`, now enforceable.
+
+## Extending the core
+
+- **New product** → add its accent to `accent-registry.json` (and its row to the `design-language.md` table; the parity test enforces both exist), then create `blessed/<product>.json`.
+- **New blessed deviation** → add an entry with a `why` that cites the `design-language.md` rule authorizing it. An unjustified entry is a defect in disguise.
+- **New rule** → it belongs in `design-language.md` first (prose), then in `substrate-matrix.json` (its per-substrate levels), then optionally in the script if it is CSS-text-decidable. Rules that need intent stay with the subagent.

package/agent/accent-registry.json

@@ -0,0 +1,13 @@
+{
+  "$note": "Machine source of the per-product accent table in design-language.md §Decision 2. The prose table stays authoritative for reasoning; this file is the values. scripts/accent-registry.test.mjs asserts product-set parity between the two.",
+  "products": {
+    "default": {
+      "light": "#B56A0C",
+      "dark": "#F5A83C",
+      "depth": { "light": "#14606C", "dark": "#35A0B4" }
+    },
+    "daos": { "inherits": "default" },
+    "spexr": { "light": "#5b6cff", "dark": "#8b96ff" },
+    "introspect": { "single": "#2ee6c0" }
+  }
+}

package/agent/blessed/daos.json

@@ -0,0 +1,24 @@
+{
+  "$note": "Authorized deviations for daos. Each entry cites the design-language.md rule that blesses it. An entry without a justifying rule is a defect in disguise. Populated further during migrate calibration.",
+  "substrate": "Page",
+  "deviations": [
+    {
+      "kind": "color",
+      "selectors": [
+        "--rule",
+        "--rule-2"
+      ],
+      "value": "color-mix alpha-on-canvas hairline",
+      "why": "design-language.md L2 hairline structure: hairlines need alpha over canvas. Dark-invert visibility already handled in daos .invert CSS."
+    },
+    {
+      "kind": "color",
+      "selectors": [
+        ".artifact .ok",
+        ".artifact .no"
+      ],
+      "value": "light-on-ink status greens/reds",
+      "why": "design-language.md §Decision 2: on an inverted surface, derive an on-ink status pair locally rather than using the canvas --sl-status-* tokens. Cited there as a correct instance."
+    }
+  ]
+}

package/agent/blessed/default.json

@@ -0,0 +1,26 @@
+{
+  "$note": "Authorized deviations for the reference implementation (showcase, product=default). Established during Slice 1 calibration: the audit correctly flagged these; review confirmed they are intentional, so they are recorded here rather than 'fixed'.",
+  "substrate": "Page",
+  "deviations": [
+    {
+      "kind": "color",
+      "selectors": [
+        "--bg-grad"
+      ],
+      "value": "near-canvas gradient-field stops (identity board atmospheric field)",
+      "why": "Page-local convention (showcase :root comment 'per spec: not tokens'), keyed per theme, fading to transparent. The identity-board field is the visual thesis; its stops are derived-from-canvas atmosphere, not a palette."
+    },
+    {
+      "kind": "color",
+      "values": [
+        "#8b96ff",
+        "#a3acff",
+        "rgba(139,150,255,0.12)",
+        "#2ee6c0",
+        "#5ad1ff",
+        "rgba(46,230,192,0.12)"
+      ],
+      "why": "The showcase demonstrates the per-product accent registry (design-language.md §Decision 2): spexr's indigo and introspect's cyan (plus derived hover/subtle) appear as demo swatch content, not as a second accent adopted by the showcase. Blessed by exact value, not selector — the swatches live in a JS object with no distinctive selector."
+    }
+  ]
+}

package/agent/blessed/introspect.json

@@ -0,0 +1,15 @@
+{
+  "$note": "Authorized deviations for introspect. Populated during migrate calibration; colour deviations added as the baseline audit surfaces and blesses them.",
+  "substrate": "App",
+  "deviations": [
+    {
+      "kind": "font",
+      "selectors": [
+        "--sl-font-mono",
+        "mono"
+      ],
+      "value": "IBM Plex Mono",
+      "why": "design-language.md L1: a surface may substitute the mono face for a narrower one where fixed pixel grids demand it. Martian Mono overflows ch-clamped columns. sans/display roles unchanged."
+    }
+  ]
+}

package/agent/blessed/spexr.json

@@ -0,0 +1,15 @@
+{
+  "$note": "Authorized deviations for spexr (Tier A, delivered). Presumed compliant; populated only if calibration surfaces a blessed case.",
+  "substrate": "IDE",
+  "deviations": [
+    {
+      "kind": "font",
+      "selectors": [
+        ".spexr-df-card__branch",
+        ".spexr-df-card__trail"
+      ],
+      "value": "--theia-code-font-family (editor mono)",
+      "why": "design-language.md L3: code-content runs mirror the editor font; design-layer labels use --sl-font-code. Deliberate split, not a violation."
+    }
+  ]
+}

package/agent/catalog.json

@@ -0,0 +1,24 @@
+{
+  "$note": "Machine index of catalog.md. Each entry maps a component id to its classes, the --slc-* role-vars it consumes, and its kind. scripts/catalog-audit.test.mjs asserts every id has a section in catalog.md and that every snippet audits clean.",
+  "components": [
+    { "id": "eyebrow",    "kind": "primitive", "classes": ["sl-eyebrow"], "roleVars": ["--slc-text-muted"] },
+    { "id": "tag",        "kind": "primitive", "classes": ["sl-tag", "sl-tag--plain"], "roleVars": ["--slc-accent", "--slc-accent-subtle", "--slc-text-muted", "--slc-border"] },
+    { "id": "button",     "kind": "primitive", "classes": ["sl-btn", "sl-btn--primary", "sl-btn--ghost", "sl-btn--sm"], "roleVars": ["--slc-accent", "--slc-accent-hover", "--slc-accent-active", "--slc-on-accent", "--slc-border", "--slc-text"] },
+    { "id": "link",       "kind": "primitive", "classes": ["sl-link"], "roleVars": ["--slc-accent"] },
+    { "id": "badge",      "kind": "primitive", "classes": ["sl-badge", "sl-badge--success", "sl-badge--warning", "sl-badge--danger", "sl-badge--info"], "roleVars": ["--slc-success", "--slc-warning", "--slc-danger", "--slc-info"] },
+    { "id": "card",       "kind": "primitive", "classes": ["sl-card", "sl-card__title", "sl-card__body"], "roleVars": ["--slc-surface", "--slc-border", "--slc-text", "--slc-text-secondary"] },
+    { "id": "field",      "kind": "primitive", "classes": ["sl-field", "sl-field__label", "sl-field__input"], "roleVars": ["--slc-surface", "--slc-border", "--slc-border-strong", "--slc-text", "--slc-focus"] },
+    { "id": "callout",    "kind": "primitive", "classes": ["sl-callout", "sl-callout--success", "sl-callout--warning", "sl-callout--danger", "sl-callout--info", "sl-callout__title", "sl-callout__body"], "roleVars": ["--slc-surface", "--slc-border", "--slc-info", "--slc-success", "--slc-warning", "--slc-danger"] },
+    { "id": "rule",       "kind": "primitive", "classes": ["sl-rule", "sl-rule--labeled"], "roleVars": ["--slc-border"] },
+    { "id": "table",      "kind": "primitive", "classes": ["sl-table", "sl-table--numeric"], "roleVars": ["--slc-border", "--slc-text", "--slc-text-secondary", "--slc-surface"] },
+    { "id": "tabs",       "kind": "primitive", "classes": ["sl-tabs", "sl-tabs__list", "sl-tabs__tab"], "roleVars": ["--slc-accent", "--slc-text", "--slc-text-muted", "--slc-border"] },
+    { "id": "kbd",        "kind": "primitive", "classes": ["sl-kbd", "sl-code"], "roleVars": ["--slc-surface", "--slc-border", "--slc-text"] },
+    { "id": "dialog",     "kind": "primitive", "classes": ["sl-dialog", "sl-dialog__title", "sl-dialog__body", "sl-dialog__actions"], "roleVars": ["--slc-raised", "--slc-border", "--slc-overlay", "--slc-text", "--slc-text-secondary"] },
+
+    { "id": "sticky-header",   "kind": "signature", "classes": [], "roleVars": ["--sl-bg-canvas", "--sl-border-subtle", "--sl-z-overlay"] },
+    { "id": "inversion-band",  "kind": "signature", "classes": [], "roleVars": ["--sl-text-primary", "--sl-bg-canvas"] },
+    { "id": "hairline-grid",   "kind": "signature", "classes": [], "roleVars": ["--sl-border-subtle", "--sl-bg-surface", "--sl-space-5"] },
+    { "id": "section-index",   "kind": "signature", "classes": [], "roleVars": ["--sl-border-subtle", "--sl-font-mono", "--sl-text-xs", "--sl-text-muted", "--sl-space-8"] },
+    { "id": "oversized-anchor","kind": "signature", "classes": [], "roleVars": ["--sl-font-display", "--sl-line-tight"] }
+  ]
+}

package/agent/catalog.md

@@ -0,0 +1,194 @@
+# Component catalog — Sondalab DS (agent-facing)
+
+> **What this file is:** a copy-paste catalog of Sondalab DS primitives and signature patterns, for an agent authoring a new interface. Each entry gives the canonical markup, the role-vars it consumes, its substrate applicability, and a do/don't. Snippets use only `var(--slc-*/--sl-*)` and `color-mix()` over those — never a colour literal — so every snippet here passes `sl-audit` by construction (`scripts/catalog-audit.test.mjs` enforces it).
+> **Audience:** agents building or extending a Sondalab surface (author workflow); humans reviewing component usage.
+> **How to use:** pick the component, copy the markup, bind it to your product's theme (Tier A: consume `@sondalab/ui-kit` `components.css` + a theme; Tier B: map the `--slc-*` role-vars to your local colour layer). Then run `sl-audit`. The machine index is `catalog.json`.
+> **Companion:** `README.md` (usage), `HANDOFF.md` (what the audit does not check), `./design-language.md` (the grammar these components express), `workflows/author.md` (the procedure that consumes this catalog).
+
+The `--slc-*` role-vars (defined at the top of `components.css`) are the seam: components read them, and they resolve to `--sl-*` tokens (Tier A) or to your product's colour layer (Tier B). Never hardcode a colour into a component — bind the role-var.
+
+## Primitives (ready classes in `components.css`)
+
+### Eyebrow — `sl-eyebrow`
+Mono uppercase micro-label above a heading. The single strongest family signal. Substrate: **R** on App/Page/IDE.
+```html
+<p class="sl-eyebrow">System status</p>
+```
+Consumes: `--slc-text-muted`, `--sl-font-mono`. Don't: sentence-case it or use a sans face.
+
+### Tag / tier marker — `sl-tag` (`--plain`)
+Accent-tinted pill with a leading dot; classification/status. Substrate: **R** App/Page.
+```html
+<span class="sl-tag">Delivered</span>
+<span class="sl-tag sl-tag--plain">Draft</span>
+```
+Consumes: `--slc-accent`, `--slc-accent-subtle` (`--plain`: `--slc-text-muted`, `--slc-border`). Don't: introduce a second accent hue for tags.
+
+### Button — `sl-btn` (`--primary` · `--ghost` · `--sm`)
+Filled-accent primary or bordered ghost. Active/hover track the accent hue. Substrate: **R** App/IDE, **A** Page.
+```html
+<button class="sl-btn sl-btn--primary">Save changes</button>
+<button class="sl-btn sl-btn--ghost">Cancel</button>
+<button class="sl-btn sl-btn--primary sl-btn--sm">Add</button>
+```
+Consumes: `--slc-accent`, `--slc-accent-hover`, `--slc-accent-active`, `--slc-on-accent`, `--slc-border`, `--slc-text`. Do: state the effect in the label (L5 voice). Don't: use a default-blue CTA or `hover:opacity` as the only state.
+
+### Link — `sl-link`
+Underlined, accent on hover. Substrate: **R** App/Page.
+```html
+<a class="sl-link" href="/specs">read the spec</a>
+```
+Consumes: `--slc-accent`. Don't: remove the underline (leave the affordance).
+
+### Badge — `sl-badge` (`--success` · `--warning` · `--danger` · `--info`)
+Semantic status pill. Semantic colour is **independent of the accent hue** and shared. Substrate: **R** App/IDE.
+```html
+<span class="sl-badge sl-badge--success">Passing</span>
+<span class="sl-badge sl-badge--danger">Failed</span>
+```
+Consumes: `--slc-success`, `--slc-warning`, `--slc-danger`, `--slc-info`. Don't: recolour a badge to the accent — status ≠ accent.
+
+### Card — `sl-card` (`__title` · `__body`)
+Surface panel. Substrate: **R** App.
+```html
+<article class="sl-card">
+  <h3 class="sl-card__title">Migration report</h3>
+  <div class="sl-card__body">2 R-violations resolved, 1 blessed.</div>
+</article>
+```
+Consumes: `--slc-surface`, `--slc-border`, `--slc-text`, `--slc-text-secondary`. Don't: make a `rounded-lg` card grid the primary layout — prefer the hairline grid (below).
+
+### Field — `sl-field` (`__label` · `__input`)
+Label + input/textarea/select. Substrate: **R** App.
+```html
+<label class="sl-field">
+  <span class="sl-field__label">Product</span>
+  <input class="sl-field__input" type="text" placeholder="introspect">
+</label>
+```
+Consumes: `--slc-surface`, `--slc-border`, `--slc-border-strong`, `--slc-text`, `--slc-focus`. Do: keep the shared focus ring.
+
+### Callout — `sl-callout` (`--success` · `--warning` · `--danger` · `--info`)
+Banner / admonition. The accent is a short "measure tick" on the top edge (not a left stripe). Substrate: **A** App/Page.
+```html
+<div class="sl-callout sl-callout--info">
+  <p class="sl-callout__title">Tier B</p>
+  <div class="sl-callout__body">Every colour must resolve to a Sondalab value.</div>
+</div>
+```
+Consumes: `--slc-surface`, `--slc-border`, `--slc-info`/`--slc-success`/etc. Don't: reinstate a full left border stripe.
+
+### Rule — `sl-rule` (`--labeled`)
+Hairline divider; `--labeled` centres a mono caption over the line. Substrate: **R** App/Page.
+```html
+<hr class="sl-rule">
+<div class="sl-rule sl-rule--labeled">since 0.2.0</div>
+```
+Consumes: `--slc-border`. Weight is always 1px — never thicken a separator.
+
+### Table — `sl-table` (`--numeric`)
+Data table shell. Wrap in an `overflow-x:auto` container so wide tables never scroll the page. Substrate: **R** App.
+```html
+<div style="overflow-x:auto">
+  <table class="sl-table sl-table--numeric">
+    <thead><tr><th>Product</th><th>R-violations</th></tr></thead>
+    <tbody><tr><td>daos</td><td>2</td></tr></tbody>
+  </table>
+</div>
+```
+Consumes: `--slc-border`, `--slc-text`, `--slc-text-secondary`, `--slc-surface`. Do: `--numeric` for tabular figures.
+
+### Tabs — `sl-tabs` (`__list` · `__tab`)
+Visual-only tabs (consumer wires ARIA + panel switching). Active tab uses a 2px accent underline — an emphasis accent, not a separator. Substrate: **R** App.
+```html
+<div class="sl-tabs">
+  <div class="sl-tabs__list" role="tablist">
+    <button class="sl-tabs__tab" aria-selected="true">Tokens</button>
+    <button class="sl-tabs__tab">Components</button>
+  </div>
+</div>
+```
+Consumes: `--slc-accent`, `--slc-text`, `--slc-text-muted`, `--slc-border`. Active state is the accent (never a neutral).
+
+### Kbd / inline code — `sl-kbd` · `sl-code`
+Keyboard key and inline monospace code. Substrate: **A**.
+```html
+Press <kbd class="sl-kbd">⌘K</kbd>, then run <code class="sl-code">sl-audit</code>.
+```
+Consumes: `--slc-surface`, `--slc-border`, `--slc-text`, `--sl-font-mono`.
+
+### Dialog — `sl-dialog` (`__title` · `__body` · `__actions`)
+Visual shell for the native `<dialog>` (consumer wires open/close). Substrate: **R** App.
+```html
+<dialog class="sl-dialog">
+  <h2 class="sl-dialog__title">Discard changes?</h2>
+  <div class="sl-dialog__body">This cannot be undone.</div>
+  <div class="sl-dialog__actions">
+    <button class="sl-btn sl-btn--ghost">Keep</button>
+    <button class="sl-btn sl-btn--primary">Discard</button>
+  </div>
+</dialog>
+```
+Consumes: `--slc-raised`, `--slc-border`, `--slc-overlay`, `--slc-text`, `--slc-text-secondary`.
+
+## Signature patterns (page-level composition — copy the CSS)
+
+These are not single classes; they are the composition motifs from `design-language.md` L2/L3. Copy the CSS into your surface (they read `--sl-*` tokens directly, theme-independent).
+
+### Sticky translucent header
+Substrate: **R** App/Page. The house header: sticky, translucent, 1px bottom rule; mono wordmark left, mono meta right.
+```css
+.site-header {
+  position: sticky; top: 0; z-index: var(--sl-z-overlay);
+  background: color-mix(in srgb, var(--sl-bg-canvas) 84%, transparent);
+  backdrop-filter: saturate(140%) blur(10px);
+  border-bottom: 1px solid var(--sl-border-subtle);
+}
+```
+Don't: use an opaque header or a drop-shadow instead of the 1px rule.
+
+### Inversion band
+Substrate: **R** Page, **A** App/IDE/Term. A full-width block flipped to paper-on-ink; punctuates rhythm, marks the thesis or primary CTA. At least one per long page.
+```css
+.invert {
+  background: var(--sl-text-primary);
+  color: var(--sl-bg-canvas);
+}
+.invert .sl-eyebrow { color: color-mix(in srgb, var(--sl-bg-canvas) 70%, transparent); }
+```
+Don't: put an alpha-on-canvas hairline inside it (it vanishes) — derive an on-ink rule locally.
+
+### Hairline grid
+Substrate: **R** App/Page. Cards formed by a 1px gap over a line-colour background; cells paint their own surface → crisp shared rules, no doubled borders. Prefer over bordered-card grids.
+```css
+.hgrid {
+  display: grid; gap: 1px;
+  background: var(--sl-border-subtle);
+  grid-template-columns: repeat(auto-fill, minmax(16rem, 1fr));
+}
+.hgrid > * { background: var(--sl-bg-surface); padding: var(--sl-space-5); }
+```
+
+### Section with mono index
+Substrate: **R** Page. A section opens with a mono index label beside its heading, separated from the previous section by a 1px top rule. Number it only where the content is a real sequence.
+```css
+.section { border-top: 1px solid var(--sl-border-subtle); padding-block: var(--sl-space-8); }
+.section__idx { font-family: var(--sl-font-mono); font-size: var(--sl-text-xs); letter-spacing: 0.2em; text-transform: uppercase; color: var(--sl-text-muted); }
+```
+
+### Oversized display anchor
+Substrate: **R** Page (**A** App where a hero exists). One oversized display heading per screen, sized by a fluid clamp (a documented pattern, not a token).
+```css
+.anchor {
+  font-family: var(--sl-font-display); font-weight: 600;
+  letter-spacing: -0.02em; line-height: var(--sl-line-tight);
+  font-size: clamp(2.7rem, 1.6rem + 5vw, 5.4rem);
+}
+```
+Don't: use more than one oversized anchor per screen.
+
+## Rules of use (all components)
+
+- **Bind role-vars, never literals.** A component's colour comes from a `--slc-*`/`--sl-*` var. A raw hex fails `sl-audit`.
+- **One accent hue.** The accent varies per product (see `accent-registry.json`); status colours (success/warning/danger/info) are shared and independent of it.
+- **Spend surprise on composition, not materials.** Family resemblance comes from these shared components; distinctiveness comes from how you compose them (≥1 unexpected layout decision per screen).