@sondalab/ui-kit 0.2.0 → 0.4.0

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/components.css

@@ -24,9 +24,12 @@
 :root {
   /* accent */
   --slc-accent:        var(--sl-accent-default, #B56A0C);
-  --slc-accent-hover:  var(--sl-accent-hover,   #A05F0A);
-  --slc-accent-active: var(--sl-accent-active,  #8A5109);
-  --slc-accent-subtle: var(--sl-accent-subtle,  rgba(197,122,22,0.12));
+  /* Steps derive from --slc-accent so a bare --sl-accent-default override
+     (or a Tier-B product that maps only --slc-accent) re-derives the whole
+     family — no amber leak. The theme layer still wins when it sets the step. */
+  --slc-accent-hover:  var(--sl-accent-hover,   color-mix(in srgb, var(--slc-accent) 89%, black));
+  --slc-accent-active: var(--sl-accent-active,  color-mix(in srgb, var(--slc-accent) 76%, black));
+  --slc-accent-subtle: var(--sl-accent-subtle,  color-mix(in srgb, var(--slc-accent) 12%, transparent));
   --slc-on-accent:     var(--sl-text-on-accent, #FFFFFF);
   /* surfaces + text */
   --slc-surface:       var(--sl-bg-surface,        #F6F1E6);

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.4.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/"
   ]
 }

package/themes/dark.css

@@ -16,9 +16,9 @@
   --sl-status-danger: #f87171;
   --sl-status-info: #38bdf8;
   --sl-accent-default: #F5A83C;
-  --sl-accent-hover: #F7B863;
+  --sl-accent-hover: color-mix(in srgb, var(--sl-accent-default) 80%, white);
   --sl-accent-active: #E0942A;
-  --sl-accent-subtle: rgba(245,168,60,0.16);
+  --sl-accent-subtle: color-mix(in srgb, var(--sl-accent-default) 16%, transparent);
   --sl-accent-depth: #35A0B4;
   --sl-focus-ring: #F5A83C;
 }

package/themes/high-contrast.css

@@ -16,8 +16,8 @@
   --sl-status-danger: #ff5555;
   --sl-status-info: #00ffff;
   --sl-accent-default: #ffff00;
-  --sl-accent-hover: #ffffa0;
-  --sl-accent-active: #cccc00;
+  --sl-accent-hover: color-mix(in srgb, var(--sl-accent-default) 37%, white);
+  --sl-accent-active: color-mix(in srgb, var(--sl-accent-default) 80%, black);
   --sl-accent-subtle: #1a1a00;
   --sl-accent-depth: #00ffff;
   --sl-focus-ring: #ffff00;

package/themes/light.css

@@ -16,8 +16,8 @@
   --sl-status-danger: #dc2626;
   --sl-status-info: #0284c7;
   --sl-accent-default: #B56A0C;
-  --sl-accent-hover: #A05F0A;
-  --sl-accent-active: #8A5109;
+  --sl-accent-hover: color-mix(in srgb, var(--sl-accent-default) 89%, black);
+  --sl-accent-active: color-mix(in srgb, var(--sl-accent-default) 76%, black);
   --sl-accent-subtle: rgba(197,122,22,0.12);
   --sl-accent-depth: #14606C;
   --sl-focus-ring: #B56A0C;