@sondalab/ui-kit 0.2.0 → 0.3.0

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).

package/agent/design-language.md

@@ -0,0 +1,168 @@
+# Sondalab Design Language — Family-Resemblance Spec
+
+> **What this file is:** the family-resemblance rules that sit *above* the token contract — the shared grammar of layout, graphic motifs, type treatment, and editorial voice that makes every Sondalab surface (spexr, introspect, daos, future products) read as one package. Where `design-system-spec.md` is the machine contract (the canonical `--sl-*`/terminal values and their generators), this file is the human contract (how to *use* those values so products look related without looking identical).
+> **Audience:** engineers and designers building or migrating any Sondalab UI surface; reviewers checking cross-product coherence.
+> **Owner:** marcellobarile.
+> **Companion files:** `design-system-spec.md` (token contract — the values this language spends), `design-system-plan.md` (token pipeline build sequence), the identity board artifact `https://claude.ai/code/artifact/abbebb7f-5778-4af6-a9b4-2b3f169ae20f` (visual thesis). The per-product application of this language is tracked in a separate implementation plan (writing-plans), not here.
+
+## Legend (status vocabulary)
+
+- **Shipped / Delivered** — merged to the surface's production codebase, available to users.
+- **PoC implemented (not delivered)** — built as a prototype, not merged/released.
+- **Placeholder (not delivered)** — stub or scaffold only.
+
+At authoring time (2026-08-22): spexr consumes the token architecture (delivered); introspect has adopted the shared type (delivered, type-only); daos landing and the sondalab-ui showcase are **not delivered** (this language spec is design only until the pass-1 plan lands).
+
+## Why this exists
+
+Colour and type harmonisation alone (phase 2 tokens) does not make products feel like one suite. introspect after its type swap still "looks the same" because the values converged but the *grammar* did not: the same accent and font can carry two unrelated layouts. This document codifies the grammar — the reusable editorial decisions — so a new product (or a reviewer) can achieve family resemblance without re-deriving it.
+
+The reference implementation is **daos landing** (`daos/docs/daos-landing.html`): it already expresses the intended editorial modernism (hairline structure, mono structural labels, oversized display type, inversion bands, real content over marketing copy). This spec extracts daos's vocabulary and generalises it; daos is the *source*, not the first target.
+
+## Decision 1 — Theme selector policy (two tiers)
+
+Products reach Sondalab colour through one of two blessed patterns. This was previously decided twice, inconsistently (spexr uses `data-sl-theme`; introspect and daos use `[data-theme]`); it is now a policy keyed on substrate, not an ad-hoc per-product call.
+
+- **Tier A — full theme adoption.** Set `data-sl-theme="light|dark|high-contrast"` on the root and consume the generated theme layer (`themes/*.css`) wholesale. Best for greenfield surfaces and chrome-heavy hosts that need every neutral. **Adopter:** spexr (its Theia chrome needs the full neutral set; see `spexr-theme-contribution.ts`).
+- **Tier B — shared-root adoption.** Vendor only the shared `:root` layer of the token CSS (`--sl-*` type/space/radius/motion/etc., theme-independent). The product keeps its own `[data-theme]` colour layer, but **every colour value in that layer must resolve to a Sondalab value** (a product token equals an `--sl-*` value or an accent-registry value; no free-floating hex). Best for surfaces with an existing editorial palette. **Adopters:** introspect, daos.
+
+**Why not one tier:** the generated theme layer is scoped `[data-sl-theme]`; a product on `[data-theme]` can never match that selector, so forcing Tier A on introspect/daos would mean rewriting their working colour layers for no visual gain. Tier B keeps their selector and pins their *values*.
+
+**Compliance test (both tiers):** open the surface, sample any surface/text/accent colour, and confirm it equals a value in `sondalab.tokens.json` or the accent registry below. Tier is an implementation detail; value-equality is the invariant.
+
+**Migration note (the loser):** Tier B is the default for products with a pre-existing palette. A Tier-B product should migrate to Tier A only if it later drops its own colour layer entirely (unlikely for introspect/daos). No forced migration.
+
+## Decision 2 — Product accent registry
+
+Shared grammar, per-product accent. The brand default is amber (with a teal *depth* companion); each product may override the accent hue only. Everything else (neutrals, type, spacing, motion) is shared.
+
+| Product | Accent (light / dark) | Source | Note |
+|---|---|---|---|
+| **Sondalab default / daos** | `#B56A0C` / `#F5A83C` (depth `#14606C` / `#35A0B4`) | `sondalab.tokens.json` `accent.*.default` | daos re-baselines from its near-amber `#9a6a15`/`#d29a44` to the exact token values. |
+| **spexr** | `#5b6cff` / `#8b96ff` | `spexr-overrides.css` | Delivered. |
+| **introspect** | `#2ee6c0` (single) | introspect `--cy` | ⚠ Differs from the Sondalab teal depth `#35A0B4`. **Resolved:** introspect's brighter mint-cyan is registered as its product accent (kept); it is not required to match `depth`. `depth` is the *default* product's teal, not a constraint on cyan-accented products. |
+
+Machine values of this table: `packages/ui-kit/agent/accent-registry.json` (consumed by the compliance audit). The table above stays authoritative for the reasoning; `scripts/accent-registry.test.mjs` asserts product-set parity between the two.
+
+Rule: a product picks **one** accent hue and derives hover/active/subtle from it; it never introduces a second chromatic accent. Semantic status colours (ok/warn/err) are separate from the accent and shared — but the `--sl-status-*` tokens are tuned for **on-canvas** use. On an inverted surface (a block whose background is the strongest neutral, e.g. an ink-on-paper output panel) they lose contrast; there, derive an on-ink status pair locally rather than using the canvas tokens (daos `.artifact .ok`/`.no` are a correct instance of this — kept as light-on-ink greens/reds, not swapped to the darker canvas tokens).
+
+## The family-resemblance layer
+
+Each rule below carries a **compliance level per substrate** (see the matrix). Layout rules are expressed as **invariants** (a spacing scale, a rule weight, a measure, a type-scale relationship) — never as fixed templates — so a data-grid app with hard pixel columns can satisfy them as readily as a marketing page.
+
+### L1 — Type treatment
+
+- **Three roles, fixed pairing.** Display/serif = `--sl-font-display` (Fraunces); body/UI sans = `--sl-font-sans` (Instrument Sans); mono = `--sl-font-mono` (Martian Mono). A surface may substitute the *mono* face for a narrower one where fixed pixel grids demand it (introspect keeps IBM Plex Mono; Martian is materially wider and overflows `ch`-clamped columns) — this is an `adapt`, not a violation, provided the substitute stays monospace and the sans/display roles are unchanged.
+- **Structural labels are mono, uppercase, wide-tracked.** Eyebrows, section indices, meta, wordmark, badges, tags: `--sl-font-mono`, `text-transform: uppercase`, `letter-spacing` in the `0.14em–0.22em` band, size `--sl-text-xs`. This mono-label motif is the single strongest family signal — a surface reads as Sondalab primarily through it.
+- **Headings.** `font-weight: 600`, `text-wrap: balance`, `letter-spacing: -0.02em`, `line-height: --sl-line-tight`. Sizes step off the shared scale (`--sl-text-xl`/`--sl-text-2xl`) for in-flow headings.
+- **Oversized display is a structural element, used sparingly.** Hero/anchor headings scale beyond the fixed token scale via a fluid clamp (pattern: `clamp(2.7rem, 1.6rem + 5vw, 5.4rem)`), not a token — the size is fluid, so it is a documented pattern, not a `--sl-text-*` addition. At most one oversized anchor per screen.
+- **Body measure.** Running text is capped at ~`63ch` (convention var `--sl-measure: 63ch`, defined locally — not a token, it is layout-level). Never let prose run full-bleed.
+
+### L2 — Structure & spacing
+
+- **Spacing rhythm off the scale.** All gaps/padding step off `--sl-space-*` (0.25rem base). No arbitrary spacing values in new work.
+- **Hairline structure.** Structural separation is a single `1px` rule in the theme's line colour — section tops, header/footer borders, card edges, gutter rulers. Weight is always `1px`; no heavy borders, no drop-shadow-as-separator (shadows are reserved for genuinely floating surfaces via `--sl-shadow-*`).
+- **Hairline grid technique.** Card grids are formed by a `1px` gap over a line-colour background (`display: grid; gap: 1px; background: <line>`), cells painting their own surface — producing crisp shared rules between cells instead of doubled borders. This is a signature; prefer it over bordered-card grids (which the house style otherwise avoids).
+- **Gutter & ruler.** Content sits in a max-width wrap (`~78rem`) with a fluid gutter (`clamp(1.25rem, 5vw, 6rem)`, convention var `--sl-gutter`); on wide viewports a `1px` vertical ruler at the gutter edge is an optional editorial accent.
+- **Sections lead with an index.** A section opens with a mono `sec-idx` label (numbered where the content is genuinely a sequence — see the structure-is-information rule) beside its heading, separated from the previous section by a `1px` top rule.
+
+### L3 — Signature components
+
+These recurring parts carry the family look. A surface need not use all, but any it does use should match:
+
+- **Wordmark (official logo)** — the brand is typographic, no pictorial mark. Primary: `sondalab.` set in `--sl-font-display` (Fraunces) weight 500, `letter-spacing: -0.05em`, with the trailing period in the accent (`.dot { color: accent }`). Compact lockup (headers, tight spots): `sonda·lab` in `--sl-font-mono`, uppercase, tracked `0.2em`, with the middle dot in the accent. Source of truth: the identity board artifact `https://claude.ai/code/artifact/abbebb7f-5778-4af6-a9b4-2b3f169ae20f`; reference implementation: `sondalab-ui/showcase/index.html` (`.brand-word` hero + `.wordmark` header).
+- **Eyebrow** — mono uppercase micro-label above a heading (`--sl-text-xs`, tracked `0.22em`, muted).
+- **Tag / tier marker** — inline mono uppercase pill: `1px` border in a soft accent tint, small dot or square glyph before the label, accent-coloured text. Used for status/classification.
+- **Inversion band** — a full-width block flipped to `text-on-*` on the strongest neutral (ink background, paper text), used to punctuate rhythm and mark the thesis or primary call-to-action. The recurring inversion is a core motif; at least one per long page is idiomatic.
+- **Sticky translucent header** — `position: sticky`, background `color-mix(paper 86%, transparent)` + `backdrop-filter: blur()`, `1px` bottom rule; brand wordmark (mono, tracked) left, mono meta/controls right.
+- **Real-content blocks** — where a surface shows output (JSON, terminal, code, data rows), show *actual* content in mono on the ink surface, not illustrative filler. This is both an editorial-voice rule and a visual one.
+
+**Canonical recipe — eyebrow + tag.** These two are the strongest family signal, so their values are fixed here (a convention, like `--sl-measure`; not a token, because products bind them to their own local colour vars). Every implementation cites this recipe rather than re-deriving it; a product substitutes its own token names for the roles in brackets.
+
+```css
+/* eyebrow — mono uppercase micro-label */
+.eyebrow {
+  font-family: var(--sl-font-mono);          /* or the product's mono face */
+  font-size: var(--sl-text-xs);              /* ~9.5–11px in px-scaled UIs */
+  letter-spacing: 0.2em;                      /* band 0.18–0.22em */
+  text-transform: uppercase;
+  color: [text-muted];
+}
+/* tag / tier marker — accent-tinted pill with a leading dot */
+.tag {
+  display: inline-flex; align-items: center; gap: 6px;
+  font-family: var(--sl-font-mono);
+  font-size: var(--sl-text-xs); font-weight: 500;
+  letter-spacing: 0.16em; text-transform: uppercase;
+  color: [accent];
+  border: 1px solid [accent-subtle];
+  background: [accent-subtle];
+  padding: 3px 7px; line-height: 1;
+}
+.tag::before { content: ""; width: 5px; height: 5px; border-radius: 50%; background: [accent]; flex: none; }
+```
+
+Current citations: introspect `.sl-eyebrow`/`.sl-tag` in `introspect/web/src/theme.css`; spexr `.spexr-agent-chat__label`, `.spexr-spec-resources__caption`, and `.spexr-df-card__status` in `packages/theia-extensions/src/browser/style/spexr.css` — these adopt the **eyebrow** half of the recipe (mono uppercase tracked, via spexr's `--sl-font-code`). spexr has **not** adopted the tag/pill half; its existing status pills `.spexr-df-pill--attn/--error` are untouched. In spexr the eyebrow face is the design mono `--sl-font-code`, deliberately distinct from code-content runs (`.spexr-df-card__branch`/`__trail`, which mirror the editor font `--theia-code-font-family`): labels are design-layer, code content mirrors the editor.
+
+### L4 — Motion
+
+- **One easing, three speeds.** All transitions use `--sl-motion-ease` with `--sl-motion-fast|mid|slow`. Entrance reveals use a small rise (`translateY(~6px)` + opacity) on `--sl-motion-mid|slow`.
+- **Stagger, don't fade-everything.** Where multiple related elements enter, stagger them (nth-child delays) rather than fading the whole screen at once.
+- **Respect reduced motion.** The token layer already zeroes durations under `prefers-reduced-motion`; never re-introduce motion that bypasses the tokens.
+- **Interaction, not opacity.** Hover/focus states change colour/border/background meaningfully; `hover:opacity` alone is not a state.
+
+### L5 — Editorial voice (copy)
+
+- **Precise and technical, never marketing.** Name things by what they are and do. Prefer a real measured figure or executed output to an adjective.
+- **Active voice; controls state their effect.** A button says what happens; its confirmation says it happened.
+- **Structure encodes truth.** Numbered markers, eyebrows, dividers appear only where they reflect something real (an actual sequence, a real classification) — not as decoration.
+- **English for product copy and all identifiers**, matching the suite.
+
+## Per-substrate compliance matrix
+
+Substrates: **IDE** (fixed-chrome host, e.g. spexr in Theia), **App** (data-grid web app, e.g. introspect), **Page** (marketing/landing, e.g. daos), **Term** (terminal/CLI, e.g. smartctx). Levels: **R** required · **A** adapt (honour the intent within substrate limits) · **N/A** not applicable.
+
+| Rule | IDE | App | Page | Term |
+|---|---|---|---|---|
+| Theme selector (Tier A/B) | R (A) | R (B) | R (B) | N/A |
+| Accent registry (one hue) | R | R | R | R (roles) |
+| L1 type roles (display/sans/mono) | R | A (mono sub allowed) | R | A (mono only) |
+| L1 mono uppercase structural labels | R | R | R | A (dim/caps where ANSI allows) |
+| L1 heading treatment | A (host headings limited) | R | R | N/A |
+| L1 oversized display anchor | N/A | A (where a hero exists) | R | N/A |
+| L1 body measure ~63ch | A | R | R | R (wrap width) |
+| L2 spacing off `--sl-space-*` | R | R | R | A (char cells) |
+| L2 hairline `1px` structure | A (host chrome fixed) | R | R | A (box-drawing rules) |
+| L2 hairline-grid technique | N/A | R | R | N/A |
+| L2 gutter/ruler | N/A | A | R | N/A |
+| L2 section index | N/A | A | R | N/A |
+| L3 eyebrow / tag / tier | A | R | R | A |
+| L3 inversion band | N/A | A | R | A (inverse video attribute) |
+| L3 sticky translucent header | N/A | R | R | N/A |
+| L3 real-content blocks | R | R | R | R |
+| L4 motion (ease/speeds/stagger) | A | R | R | N/A |
+| L4 reduced-motion respect | R | R | R | N/A |
+| L5 editorial voice | R | R | R | R |
+
+## Reconciling shared grammar with "one unexpected layout decision per screen"
+
+The house aesthetic (personal `CLAUDE.md`, UI Aesthetics) requires ≥1 unexpected, intentional layout decision per screen. That does **not** conflict with this shared grammar: the grammar fixes the *materials* (type roles, spacing scale, rule weight, motifs, motion, voice), while the surprise is spent on *composition* (an asymmetric split, an oversized anchor, a full-bleed inversion, an unexpected adjacency). Family resemblance comes from shared materials; distinctiveness comes from per-screen composition. A screen that satisfies the grammar but reads as a generic centred card grid has failed the house rule; a screen that invents a new type scale or a second accent to be "surprising" has failed the grammar. Spend boldness on layout, keep the materials shared.
+
+## New-token policy
+
+Express the language in **existing** `--sl-*` tokens. A new token forces regenerating `packages/`, satisfying `check-drift.yml`, and bumping **both** `packages/ui-kit/package.json` and `packages/palette-py/pyproject.toml` in the same PR (see `AGENTS.md`). Therefore:
+
+- **Kept as conventions, not tokens** (layout-level, fluid, or product-local): `--sl-measure` (~63ch), `--sl-gutter` (fluid clamp), the oversized-display clamp pattern. Products define these locally with the canonical values above.
+- **A new token is justified only** for a genuine shared, fixed, theme-independent value that recurs across ≥2 products and cannot be a convention — and then it goes through the full regen + dual-bump flow.
+
+## Pass-1 application (scope & order)
+
+Full task breakdown lives in the implementation plan (writing-plans). Order (daos is the source, so it is extracted-from first and re-based later, once the language is written):
+
+1. **Extract from daos** → this spec. *(Done at authoring.)*
+2. **Write this spec** (`design-language.md`). *(This file.)*
+3. **sondalab-ui showcase** — a page that renders the tokens + L3 signature components against this spec. Proves the language at zero user-facing risk. Status target: **PoC implemented (not delivered)**.
+4. **Re-baseline daos landing** — swap its local palette vars onto Sondalab values (Tier B), align accent to the registry, mono-label/measure already conformant. Low risk; aesthetics already correct.
+5. **introspect** — apply beyond the type swap: mono structural labels, hairline structure, section indices, signature header, editorial voice. Most work, most regression surface; done last.
+
+spexr is out of pass 1 (token + chrome already delivered); its remaining margin is L3 signature components inside SPEXR panels, tracked separately.

package/agent/sl-audit.mjs

@@ -0,0 +1,400 @@
+#!/usr/bin/env node
+// sl-audit — deterministic Sondalab design-system compliance audit.
+// Checks only what is decidable from CSS text (colour value-equality, tier
+// consistency). Judgement-level rules (missing labels, editorial voice,
+// layout composition) are out of scope by design — they belong to the
+// sl-ds-auditor subagent. See design-system-agentic-spec.md.
+//
+// Ships inside @sondalab/ui-kit as the `sl-audit` bin. It resolves the colour
+// allowlist from the package's own token CSS (tokens.css + themes/*.css), so it
+// works identically in-repo and when installed in a consumer's node_modules.
+// Surface globs resolve against the caller's cwd.
+
+import { readFileSync, globSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { dirname, resolve, relative } from "node:path";
+
+const HERE = dirname(fileURLToPath(import.meta.url)); // packages/ui-kit/agent
+const PKG_DIR = resolve(HERE, ".."); // packages/ui-kit — holds tokens.css + themes/
+const TOKEN_CSS = ["tokens.css", "themes/light.css", "themes/dark.css", "themes/high-contrast.css"];
+
+// --- colour normalization -------------------------------------------------
+
+/** Canonicalize a CSS colour literal to lowercase `#rrggbb` or `#rrggbbaa`.
+ * Returns null for anything that is not a hex/rgb literal (var(), keywords). */
+export function normalizeColor(raw) {
+  if (typeof raw !== "string") return null;
+  const s = raw.trim().toLowerCase();
+
+  const hex = /^#([0-9a-f]{3,8})$/.exec(s);
+  if (hex) {
+    const h = hex[1];
+    if (h.length === 3) return "#" + [...h].map((c) => c + c).join("");
+    if (h.length === 4) return "#" + [...h].map((c) => c + c).join("");
+    if (h.length === 6) return "#" + h;
+    if (h.length === 8) return "#" + h;
+    return null; // 5 or 7 digits: not a valid colour
+  }
+
+  const rgb = /^rgba?\(([^)]*)\)$/.exec(s);
+  if (rgb) {
+    const body = rgb[1].trim();
+    let rgbPart = body;
+    let alpha = null;
+    if (body.includes("/")) {
+      const [lhs, rhs] = body.split("/");
+      rgbPart = lhs.trim();
+      alpha = rhs.trim();
+    }
+    const parts = rgbPart.split(/[\s,]+/).filter(Boolean);
+    if (parts.length < 3) return null;
+    if (alpha === null && parts.length >= 4) alpha = parts[3];
+    const [r, g, b] = parts.slice(0, 3).map((n) => channelToHex(n));
+    if (r === null || g === null || b === null) return null;
+    let out = "#" + r + g + b;
+    if (alpha !== null) {
+      const a = alphaToHex(alpha);
+      if (a !== null && a !== "ff") out += a;
+    }
+    return out;
+  }
+
+  return null;
+}
+
+function channelToHex(n) {
+  let v;
+  if (n.endsWith("%")) v = Math.round((parseFloat(n) / 100) * 255);
+  else v = Math.round(parseFloat(n));
+  if (!Number.isFinite(v)) return null;
+  v = Math.max(0, Math.min(255, v));
+  return v.toString(16).padStart(2, "0");
+}
+
+function alphaToHex(a) {
+  const v = parseFloat(a);
+  if (!Number.isFinite(v)) return null;
+  return Math.round(Math.max(0, Math.min(1, v)) * 255)
+    .toString(16)
+    .padStart(2, "0");
+}
+
+/** The opaque base (`#rrggbb`) of a normalized colour, dropping any alpha. */
+export function colorBase(normalized) {
+  return normalized.slice(0, 7);
+}
+
+// --- extraction -----------------------------------------------------------
+
+const COLOR_RE = /#(?:[0-9a-fA-F]{8}|[0-9a-fA-F]{6}|[0-9a-fA-F]{4}|[0-9a-fA-F]{3})\b|rgba?\([^)]*\)/g;
+
+/** Every hex/rgb literal in a CSS string, with 1-based line numbers.
+ * var() references are intentionally ignored — they resolve to tokens. */
+export function extractColors(css) {
+  const out = [];
+  for (const m of css.matchAll(COLOR_RE)) {
+    const line = css.slice(0, m.index).split("\n").length;
+    out.push({ value: m[0], line });
+  }
+  return out;
+}
+
+function collectStrings(node, acc) {
+  if (typeof node === "string") acc.push(node);
+  else if (Array.isArray(node)) for (const v of node) collectStrings(v, acc);
+  else if (node && typeof node === "object")
+    for (const v of Object.values(node)) collectStrings(v, acc);
+  return acc;
+}
+
+/** Set of opaque colour bases (`#rrggbb`) appearing anywhere in a tokens.json
+ * object. Kept for unit tests and callers that hold the token object. */
+export function buildAllowlistBases(tokens) {
+  const bases = new Set();
+  for (const s of collectStrings(tokens, [])) {
+    for (const { value } of extractColors(s)) {
+      const norm = normalizeColor(value);
+      if (norm) bases.add(colorBase(norm));
+    }
+  }
+  return bases;
+}
+
+/** Set of opaque colour bases extracted from token CSS text (tokens.css +
+ * themes/*.css). This is the shipped, drift-proof allowlist source — the CSS is
+ * generated from sondalab.tokens.json and always ships with the package. */
+export function buildAllowlistBasesFromCss(cssTexts) {
+  const bases = new Set();
+  for (const css of cssTexts) {
+    for (const { value } of extractColors(css)) {
+      const norm = normalizeColor(value);
+      if (norm) bases.add(colorBase(norm));
+    }
+  }
+  return bases;
+}
+
+function accentColorStrings(accentEntry) {
+  return collectStrings(accentEntry, []).filter((s) => normalizeColor(s));
+}
+
+// --- tier detection -------------------------------------------------------
+
+/** 'A' (data-sl-theme), 'B' (data-theme), or null if neither appears. */
+export function detectTier(css) {
+  if (/\[data-sl-theme/.test(css)) return "A";
+  if (/\[data-theme/.test(css)) return "B";
+  return null;
+}
+
+// --- selector context -----------------------------------------------------
+
+/** For each 1-based line, a context string = the enclosing selector plus the
+ * current declaration (property + value accumulated across lines, reset at
+ * `;`/`{`/`}`). The declaration part carries the property name onto every line
+ * of a multi-line value, so blessed suppression keyed on a custom-property name
+ * (e.g. `--bg-grad`) reaches its continuation lines. Not a full CSS parser. */
+function contextByLine(css) {
+  const lines = css.split("\n");
+  const map = new Array(lines.length + 1).fill("");
+  let selector = "";
+  let selPending = "";
+  let decl = "";
+  lines.forEach((line, i) => {
+    // snapshot the state entering this line, then include the raw line so a
+    // selector or property declared on this same line is matchable too.
+    map[i + 1] = selector + " " + decl + " " + line;
+    for (const ch of line) {
+      if (ch === "{") {
+        selector = selPending.trim();
+        selPending = "";
+        decl = "";
+      } else if (ch === "}") {
+        selector = "";
+        selPending = "";
+        decl = "";
+      } else if (ch === ";") {
+        decl = "";
+        selPending += ch;
+      } else {
+        selPending += ch;
+        decl += ch;
+      }
+    }
+  });
+  return map;
+}
+
+/** Whether a blessed selector appears in a context string, delimited so a
+ * short name does not match a longer one (`--rule` must not match `--rule-2`
+ * or `--ruler`). Empty selectors never match. */
+export function matchesSelector(context, selector) {
+  const sel = selector.trim();
+  if (!sel) return false;
+  const esc = sel.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  return new RegExp(`(?<![\\w-])${esc}(?![\\w-])`).test(context);
+}
+
+// --- audit ----------------------------------------------------------------
+
+function levelFor(matrix, rule, substrate) {
+  if (!matrix || !substrate) return "R";
+  const row = matrix.rules?.[rule];
+  return row?.[substrate] ?? "R";
+}
+
+/** Audit one CSS string. Pure — no I/O. Provide either `allowlistBases` (a Set
+ * of `#rrggbb` bases, the shipped path) or `tokens` (a tokens.json object, the
+ * test path); `allowlistBases` wins when both are given. */
+export function auditCss({
+  css,
+  tokens,
+  allowlistBases,
+  accentEntry = {},
+  blessed = { deviations: [] },
+  declaredTier = null,
+  substrate = null,
+  matrix = null,
+  file = "",
+}) {
+  const findings = [];
+  const bases = allowlistBases ? new Set(allowlistBases) : buildAllowlistBases(tokens);
+  for (const s of accentColorStrings(accentEntry)) bases.add(colorBase(normalizeColor(s)));
+
+  const colorDeviations = (blessed.deviations || []).filter((d) => d.kind === "color");
+  const blessedColorSelectors = colorDeviations
+    .flatMap((d) => d.selectors || [])
+    .map((s) => s.trim())
+    .filter(Boolean); // an empty selector would match every context — drop it
+  // value-based blessing — the honest mechanism for demo data / literals that
+  // do not live under a distinctive selector (e.g. a JS swatch object).
+  const blessedValueBases = new Set(
+    colorDeviations
+      .flatMap((d) => d.values || [])
+      .map((v) => normalizeColor(v))
+      .filter(Boolean)
+      .map(colorBase),
+  );
+
+  // check 2 — tier consistency
+  const detected = detectTier(css);
+  if (declaredTier && detected && detected !== declaredTier) {
+    const level = levelFor(matrix, "theme-selector", substrate);
+    if (level !== "N/A")
+      findings.push({
+        rule: "theme-selector",
+        level,
+        file,
+        line: css.slice(0, css.indexOf(detected === "A" ? "[data-sl-theme" : "[data-theme")).split("\n").length,
+        message: `selector implies Tier ${detected} but product declared Tier ${declaredTier}`,
+      });
+  }
+
+  // check 1 — colour value-equality
+  const ctxMap = contextByLine(css);
+  for (const { value, line } of extractColors(css)) {
+    const norm = normalizeColor(value);
+    if (!norm) continue;
+    if (bases.has(colorBase(norm))) continue;
+    if (blessedValueBases.has(colorBase(norm))) continue;
+    const context = ctxMap[line] || "";
+    const blessedHit = blessedColorSelectors.some((sel) => matchesSelector(context, sel));
+    if (blessedHit) continue;
+    const level = levelFor(matrix, "accent-one-hue", substrate);
+    if (level === "N/A") continue;
+    findings.push({
+      rule: "accent-one-hue",
+      level,
+      file,
+      line,
+      message: `colour ${value} does not resolve to a token, product accent, or blessed value`,
+    });
+  }
+
+  return {
+    file,
+    substrate,
+    tier: { declared: declaredTier, detected },
+    findings,
+  };
+}
+
+// --- registry / config resolution ----------------------------------------
+
+export function resolveAccentEntry(registry, product) {
+  const seen = new Set();
+  let name = product;
+  while (name) {
+    if (seen.has(name)) throw new Error(`accent-registry: circular inherits at "${name}"`);
+    seen.add(name);
+    const entry = registry.products?.[name];
+    if (!entry) return {};
+    if (entry.inherits) {
+      name = entry.inherits;
+      continue;
+    }
+    return entry;
+  }
+  return {};
+}
+
+function loadJson(path) {
+  return JSON.parse(readFileSync(path, "utf8"));
+}
+
+function loadTokenCss() {
+  const texts = [];
+  for (const rel of TOKEN_CSS) {
+    try {
+      texts.push(readFileSync(resolve(PKG_DIR, rel), "utf8"));
+    } catch {
+      /* a theme file may be absent in a trimmed install — skip it */
+    }
+  }
+  return texts;
+}
+
+// --- CLI ------------------------------------------------------------------
+
+function parseArgs(argv) {
+  const args = {};
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a.startsWith("--")) args[a.slice(2)] = argv[i + 1] && !argv[i + 1].startsWith("--") ? argv[++i] : true;
+  }
+  return args;
+}
+
+function group(findings, level) {
+  return findings.filter((f) => f.level === level);
+}
+
+function main() {
+  const args = parseArgs(process.argv.slice(2));
+  if (!args.surface || !args.product) {
+    console.error("usage: sl-audit --surface <glob> --product <name> [--substrate IDE|App|Page|Term] [--fail-on R]");
+    process.exit(2);
+  }
+
+  const allowlistBases = buildAllowlistBasesFromCss(loadTokenCss());
+  const registry = loadJson(resolve(HERE, "accent-registry.json"));
+  const matrix = loadJson(resolve(HERE, "substrate-matrix.json"));
+  let blessed = { deviations: [] };
+  try {
+    blessed = loadJson(resolve(HERE, `blessed/${args.product}.json`));
+  } catch {
+    /* no blessed file yet — treat as none */
+  }
+
+  const substrate = args.substrate || matrix.products?.[args.product] || blessed.substrate || null;
+  const declaredTier = args.tier || matrix.tiers?.[args.product] || blessed.tier || null;
+  if (!declaredTier && substrate && substrate !== "Term")
+    console.warn(`warning: no tier declared for "${args.product}" (add it to substrate-matrix.json "tiers") — tier-consistency check disabled`);
+  const accentEntry = resolveAccentEntry(registry, args.product);
+
+  const cwd = process.cwd();
+  const files = globSync(args.surface, { cwd }).map((f) => resolve(cwd, f));
+  const all = [];
+  for (const file of files) {
+    const css = readFileSync(file, "utf8");
+    const res = auditCss({
+      css,
+      allowlistBases,
+      accentEntry,
+      blessed,
+      declaredTier,
+      substrate,
+      matrix,
+      file: relative(cwd, file),
+    });
+    all.push(...res.findings);
+  }
+
+  const R = group(all, "R");
+  const A = group(all, "A");
+  const naCount = matrix.rules
+    ? Object.values(matrix.rules).filter((r) => r[substrate] === "N/A").length
+    : 0;
+
+  console.log(`\n${args.product}  (${substrate}, Tier ${declaredTier ?? "?"})  —  sl-audit`);
+  console.log(`  ${files.length} file(s) scanned\n`);
+  printBucket("R-violation", R);
+  printBucket("A-deviation", A);
+  console.log(`N/A: ${naCount} rules skipped for substrate ${substrate}\n`);
+
+  if (args["fail-on"] === "R" && R.length > 0) process.exit(1);
+}
+
+function printBucket(label, findings) {
+  if (findings.length === 0) {
+    console.log(`${label} (0)\n`);
+    return;
+  }
+  console.log(`${label} (${findings.length})`);
+  for (const f of findings) console.log(`  ${f.file}:${f.line}   ${f.message}`);
+  console.log("");
+}
+
+if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  main();
+}

package/agent/substrate-matrix.json

@@ -0,0 +1,38 @@
+{
+  "$note": "Machine source of the per-substrate compliance matrix in design-language.md. level ∈ R (required) | A (adapt) | N/A (not applicable). Adaptation nuance (the parentheticals in the doc) stays in design-language.md; this file carries only the level per (rule, substrate) so the audit can decide what is blocking.",
+  "products": {
+    "spexr": "IDE",
+    "introspect": "App",
+    "daos": "Page",
+    "default": "Page",
+    "smartctx": "Term"
+  },
+  "tiers": {
+    "$note": "Theme-selector tier per product (design-language.md §Decision 1). Authoritative machine source for the audit's tier-consistency check. Term products have no tier (no theme selector).",
+    "spexr": "A",
+    "introspect": "B",
+    "daos": "B",
+    "default": "A"
+  },
+  "rules": {
+    "theme-selector":     { "IDE": "R",   "App": "R", "Page": "R", "Term": "N/A" },
+    "accent-one-hue":     { "IDE": "R",   "App": "R", "Page": "R", "Term": "R"   },
+    "l1-type-roles":      { "IDE": "R",   "App": "A", "Page": "R", "Term": "A"   },
+    "l1-mono-labels":     { "IDE": "R",   "App": "R", "Page": "R", "Term": "A"   },
+    "l1-heading":         { "IDE": "A",   "App": "R", "Page": "R", "Term": "N/A" },
+    "l1-oversized-anchor":{ "IDE": "N/A", "App": "A", "Page": "R", "Term": "N/A" },
+    "l1-body-measure":    { "IDE": "A",   "App": "R", "Page": "R", "Term": "R"   },
+    "l2-spacing-scale":   { "IDE": "R",   "App": "R", "Page": "R", "Term": "A"   },
+    "l2-hairline-1px":    { "IDE": "A",   "App": "R", "Page": "R", "Term": "A"   },
+    "l2-hairline-grid":   { "IDE": "N/A", "App": "R", "Page": "R", "Term": "N/A" },
+    "l2-gutter-ruler":    { "IDE": "N/A", "App": "A", "Page": "R", "Term": "N/A" },
+    "l2-section-index":   { "IDE": "N/A", "App": "A", "Page": "R", "Term": "N/A" },
+    "l3-eyebrow-tag":     { "IDE": "A",   "App": "R", "Page": "R", "Term": "A"   },
+    "l3-inversion-band":  { "IDE": "N/A", "App": "A", "Page": "R", "Term": "A"   },
+    "l3-sticky-header":   { "IDE": "N/A", "App": "R", "Page": "R", "Term": "N/A" },
+    "l3-real-content":    { "IDE": "R",   "App": "R", "Page": "R", "Term": "R"   },
+    "l4-motion":          { "IDE": "A",   "App": "R", "Page": "R", "Term": "N/A" },
+    "l4-reduced-motion":  { "IDE": "R",   "App": "R", "Page": "R", "Term": "N/A" },
+    "l5-voice":           { "IDE": "R",   "App": "R", "Page": "R", "Term": "R"   }
+  }
+}

package/agent/workflows/adopt.md

@@ -0,0 +1,35 @@
+# Workflow — Adopt a single Sondalab component
+
+> **What this file is:** the ordered procedure for pulling **one** Sondalab component or signature pattern into an existing app **without** a full migration — the lightest of the three workflows. Companion to `migrate.md` (whole-surface compliance) and `author.md` (greenfield).
+> **Reads:** `catalog.md` + `catalog.json` (the component), `../design-language.md` (grammar), `substrate-matrix.json` (substrate applicability), `sl-audit` (verdict, scoped to the touched file).
+> **Invariant:** adopt touches only what it adds. The rest of the app is out of scope — do not audit or "fix" surrounding code. The change is small and reversible; the gate is showing the diff, not a full migration plan.
+
+## When to use this (vs migrate)
+
+Use adopt when the ask is "add a Sondalab eyebrow/tag/inversion band here", "give this header the house look", "use the DS button on this one screen" — a taste of the family look, not a wholesale adoption. If the ask is "bring this app onto the DS", that is `migrate.md`.
+
+## Steps
+
+### 0 — Identify the component and the host
+Pick the target from `catalog.md` (a primitive like `sl-tag`, or a signature pattern like the inversion band). Note the host app's **substrate** and **tier** — an adopted component must honour the host's tier: on a Tier-B app you bind the component's `--slc-*` role-vars to the app's local colour layer; you do not switch the app to `data-sl-theme`.
+
+### 1 — Bind, don't fork
+Copy the component's markup from `catalog.md`. Resolve its `--slc-*`/`--sl-*` role-vars to the host's existing values — every one must resolve to a Sondalab token or the host's registered accent (Tier-B rule). If the host lacks a role-var the component needs, define it once, mapped to a Sondalab value. Never bind the component to a raw literal.
+
+### 2 — Insert
+Place the component in the host markup. Keep the change minimal and localised — one component, the files it touches, nothing else. Match the host's existing structure and naming.
+
+### 3 — Audit the touched file only
+```sh
+npx sl-audit --surface "<the one file you edited>" --product <host> --substrate <host substrate>
+```
+The **added** component must contribute zero R-violations. Pre-existing findings elsewhere in the file are **not** yours to fix in an adopt — note them (they are migrate's job) but leave them. Populate `blessed/<host>.json` only for a deviation your added component legitimately needs.
+
+### 4 — Judgement check (the one component)
+Against `design-language.md`, scoped to just what you added: does the eyebrow/tag read as mono-uppercase-tracked? Does an adopted inversion band avoid an alpha-on-canvas hairline inside it? Is the copy in the component precise/active (L5)? See `HANDOFF.md` for judgement vs mechanical.
+
+### 5 — Show the diff
+Present the diff (it is small). No full migration plan — the change is localised and reversible. Render the touched screen across the host's themes to confirm the component sits right.
+
+## Output
+One Sondalab component living correctly in the host app, bound to the host's colour layer, auditing clean for what it added — the rest of the app untouched.

package/agent/workflows/author.md

@@ -0,0 +1,33 @@
+# Workflow — Author a new Sondalab surface
+
+> **What this file is:** the ordered procedure an agent follows to author a *new* interface or element that is Sondalab-compliant from the first line, using the component catalog. Companion to `migrate.md` (which brings an *existing* surface into compliance).
+> **Reads:** `catalog.md` + `catalog.json` (components), `../design-language.md` (grammar), the token CSS (`../../tokens.css` + `../../themes/*.css`, the values), `substrate-matrix.json` (what's Required for the substrate), `sl-audit` (verdict).
+> **Invariant:** authoring is greenfield, so the audit should pass on the *first* run — compliance is built in, not retrofitted. If your first audit is dirty, you bound a colour to a literal instead of a role-var.
+
+## Steps
+
+### 0 — Classify substrate
+Decide the substrate (**IDE** / **App** / **Page** / **Term**) and the product (for its accent). The substrate's Required column in `substrate-matrix.json` is your checklist of what this surface must have.
+
+### 1 — Choose components from the catalog
+For each part of the screen, pick the matching entry from `catalog.md`. Prefer the ready primitives (`sl-*` classes) over hand-rolled markup; reach for the signature patterns (sticky header, inversion band, hairline grid, section index, oversized anchor) to carry the family look. `catalog.json` is the machine index if you need to list what exists.
+
+### 2 — Compose (spend the surprise here)
+Assemble the components into a layout. Family resemblance comes from the shared materials (the catalog); distinctiveness comes from composition — every screen needs **≥1 unexpected, intentional layout decision** (an asymmetric split, an oversized anchor, a full-bleed inversion). A generic centred card grid fails the house rule; a second accent or a new type scale fails the grammar. Spend boldness on layout, keep materials shared.
+
+### 3 — Bind role-vars per tier
+- **Tier A** (greenfield is the common case): consume `@sondalab/ui-kit` `components.css` + a theme (`themes/*.css`) under `data-sl-theme`. Components resolve their `--slc-*` role-vars automatically.
+- **Tier B** (you have an existing colour layer): map each `--slc-*` role-var to a value that resolves to a Sondalab token or your registered accent. Never bind a component to a literal.
+
+### 4 — Audit + judgement pass
+Run the audit (must be clean on greenfield):
+```sh
+npx sl-audit --surface "<glob>" --product <name>
+```
+Then the judgement pass the script can't do (delegate to `sl-ds-auditor` or do it yourself against `design-language.md`, scoped to the substrate's Required rules): are the structural mono labels present (eyebrow, section index)? Is there real content, not filler? Is the editorial voice precise/active (L5)? See `HANDOFF.md` for what is judgement vs mechanical.
+
+### 5 — Visual check
+Render across the applicable themes (light / dark / high-contrast); verify reduced-motion and that active/pressed states show the accent, not a neutral.
+
+## Output
+A new surface that passes `sl-audit` clean, satisfies its substrate's Required rules, and reads as Sondalab through the shared components — with its one intentional composition surprise.

package/agent/workflows/migrate.md

@@ -0,0 +1,45 @@
+# Workflow — Migrate a surface onto the Sondalab DS
+
+> **What this file is:** the ordered, harness-agnostic procedure an agent follows to migrate an existing app's UI onto the Sondalab design system. It is the portable core; the Claude Code `sl-migrate` skill loads and executes it. Any other harness can follow it directly.
+> **Reads:** `../design-language.md` (grammar), the token CSS (`../../tokens.css` + `../../themes/*.css`, the values), the agent core (`accent-registry.json`, `substrate-matrix.json`, `blessed/<product>.json`), `sl-audit` (verdict engine).
+> **Invariant:** migrating a live surface is semi-irreversible. Work on a branch; do not edit before the human approves the mapping plan (Step 3 gate).
+
+## Division of labour (do not blur)
+
+- **`sl-audit.mjs`** — the mechanical verdict: colour value-equality and tier consistency, decidable from CSS text. Trust it for those; never re-derive them by eye.
+- **You (the agent)** — the judgement: is a structural label *missing*, is the editorial voice off, is an inversion band warranted, does the composition earn its "one unexpected decision". The audit cannot see these; you read `design-language.md` and decide.
+- **The human** — approves the blessed list (Step 2) and the mapping plan (Step 3). Applies nothing without that yes.
+
+## Steps
+
+### 0 — Classify substrate
+Determine the product name and its substrate: **IDE** (fixed-chrome host), **App** (data-grid web app), **Page** (marketing/landing), **Term** (terminal). Read it from `substrate-matrix.json` `products` if listed, else infer. The substrate selects which rules are Required vs Adapt vs N/A — skip this and you will, e.g., propose a sticky translucent header for a Theia panel the matrix marks N/A.
+
+### 1 — Baseline audit
+Create a branch. Run the audit, no edits:
+```sh
+npx sl-audit --surface "<glob>" --product <name> --substrate <IDE|App|Page|Term>
+```
+Record the grouped baseline (R-violation / A-deviation / N/A counts). This is the before-picture the final report is measured against.
+
+### 2 — Separate blessed deviations from defects  · GATE
+`design-language.md` authorizes colours that fail literal value-equality: accent-derived hover/active/subtle tints, locally-derived on-ink status pairs, alpha-on-canvas hairlines. For each finding decide:
+- **Blessed** → add an entry to `blessed/<product>.json` with a `why` that cites the authorizing `design-language.md` rule. It silences the finding *and* records the intentional deviation.
+- **Defect** → keep it on the list to fix in Step 3.
+
+An accent-derivation swamp (many tints off the product's single accent) is the common case for Tier-B products; bless the derivations as a group rather than mapping each to a token. **Present the blessed list and wait for the human's confirmation before continuing.**
+
+### 3 — Propose the mapping plan  · GATE
+For each remaining R-violation, map the free-floating value to an `--sl-*` role or the product's accent-registry value. Add your judgement-level findings (missing mono labels, hairline structure, section index, editorial voice) scoped to the substrate's Required rules. Present the plan **in chat**: the value→token mapping plus the concrete edits. **Stop. Apply nothing until the human says yes.**
+
+### 4 — Apply
+After approval, edit per the product's tier (A: consume the theme layer; B: keep the local colour layer but pin every value to a Sondalab value). Small, rollback-friendly chunks.
+
+### 5 — Re-audit and diff
+Re-run the audit. R-violations must reach 0 or be blessed. Produce a before/after report (baseline counts vs current).
+
+### 6 — Visual check
+Render the surface across the applicable themes (light / dark / high-contrast). Verify reduced-motion. Check the dark-invert hairline regression explicitly: alpha-on-canvas rules (`--rule` style) can go invisible inside an inverted block — confirm they remain visible.
+
+## Output
+A compliant surface + the before/after compliance report + a populated `blessed/<product>.json` + the CSS diff, all on the branch for review.

package/package.json

@@ -1,11 +1,14 @@
 {
   "name": "@sondalab/ui-kit",
-  "version": "0.2.0",
-  "description": "Sondalab design tokens as CSS custom properties: shared grammar + per-product accent, with light / dark / high-contrast themes.",
+  "version": "0.3.0",
+  "description": "Sondalab design tokens as CSS custom properties + the agentic core: component catalog, compliance audit (sl-audit), and author/migrate/adopt workflows.",
   "license": "MIT",
   "author": "marcellobarile",
   "publishConfig": { "access": "public" },
   "type": "module",
+  "bin": {
+    "sl-audit": "./agent/sl-audit.mjs"
+  },
   "exports": {
     "./tokens.css": "./tokens.css",
     "./components.css": "./components.css",
@@ -15,7 +18,12 @@
     "./assets/wordmark.svg": "./assets/sondalab-wordmark.svg",
     "./assets/lockup.svg": "./assets/sondalab-lockup.svg",
     "./assets/favicon.svg": "./assets/favicon.svg",
-    "./assets/app-icon.svg": "./assets/app-icon.svg"
+    "./assets/app-icon.svg": "./assets/app-icon.svg",
+    "./agent/sl-audit.mjs": "./agent/sl-audit.mjs",
+    "./agent/catalog.json": "./agent/catalog.json",
+    "./agent/accent-registry.json": "./agent/accent-registry.json",
+    "./agent/substrate-matrix.json": "./agent/substrate-matrix.json",
+    "./agent/*": "./agent/*"
   },
   "files": [
     "tokens.css",
@@ -28,6 +36,7 @@
     "assets/favicon.svg",
     "assets/app-icon.svg",
     "assets/README.md",
-    "README.md"
+    "README.md",
+    "agent/"
   ]
 }