oh-my-opencode 5.1.48 → 5.1.54

package/packages/shared-skills/skills/frontend/references/design/design-system-architecture.md

@@ -16,7 +16,7 @@ Every frontend project MUST have a `DESIGN.md` at its root. This file is the sin
 
 ## DESIGN.md Structure
 
-The file has 8 sections plus a greenfield-only `## 0. Research Log`. Every section is mandatory. Skip nothing.
+The file has 8 sections plus a greenfield-only `## 0. Research Log`, and section 9 once `grounding.md` has run. Every section is mandatory. Skip nothing.
 
 ```markdown
 # [Project Name] Design System
@@ -73,11 +73,11 @@ rather than borders, creating layers you feel more than see."
 | H1 | 36px / 2.25rem | 700 | 1.2 | -0.015em | Section headers |
 | H2 | 28px / 1.75rem | 600 | 1.3 | -0.01em | Subsection headers |
 | H3 | 22px / 1.375rem | 600 | 1.4 | 0 | Card titles |
-| Body/lg | 18px / 1.125rem | 400 | 1.6 | 0 | Lead paragraphs |
+| Body/lg | 18px / 1.125rem | 400 | 1.6 | 0 | Lead paragraphs, in the secondary ink |
 | Body | 16px / 1rem | 400 | 1.6 | 0 | Default text |
-| Body/sm | 14px / 0.875rem | 400 | 1.5 | 0 | Secondary info |
+| Body/sm | 14px / 0.875rem | 400 | 1.5 | 0 | Secondary info, in the secondary ink |
 | Caption | 12px / 0.75rem | 500 | 1.4 | 0.02em | Labels, metadata |
-| Overline | 11px / 0.6875rem | 600 | 1.3 | 0.08em | Section labels, uppercase |
+| Overline | 11px / 0.6875rem | 600 | 1.3 | 0.08em | Field, table and metadata labels, uppercase; by default not a label above a heading, unless the chosen route asks for one (`references/perfection/craft-floor.md`) |
 
 ### Font Stack
 - Primary: [specify — e.g. "Inter, system-ui, -apple-system, sans-serif"]
@@ -201,8 +201,10 @@ Surfaces use progressively lighter/darker shades. No borders, no shadows.
 ## 8. Accessibility Constraints & Accepted Debt
 
 ### Constraints
-- WCAG target: [e.g. 2.2 AA] — contrast floor [4.5:1 body / 3:1 large text], visible focus on every
-  interactive element, full keyboard reachability, `prefers-reduced-motion` respected (Section 6).
+- WCAG 2.2 AA at minimum ([AAA items the brief raises]): contrast 4.5:1 body / 3:1 large text, icons and
+  control edges; visible focus on every interactive element, never entirely hidden by other content; pointer targets at least
+  24x24 CSS px; full keyboard reachability; reflow at 320 CSS px; `prefers-reduced-motion` respected (Section 6).
+  The per-criterion result is stated in every deliverable (`SKILL.md` Verify).
 
 ### Accepted Debt
 | Item | Location | Why accepted | Owner / Exit |
@@ -210,16 +212,27 @@ Surfaces use progressively lighter/darker shades. No borders, no shadows.
 | [debt] | [file/screen] | [reason + user sign-off] | [when it gets fixed] |
 
 New debt is recorded here at the moment it is accepted — never silently.
+
+## 9. Ideal State & Gap Ledger (after grounding)
+
+- Sources read in full: [source → URL, reader count]
+- Personas and journey steps: [persona → steps]
+- Ideal state: [one checkable line per journey step]
+
+| ID | Screen / state | Gap | Principle or rule broken | Evidence | Fix | Proof | Status |
+|----|----------------|-----|--------------------------|----------|-----|-------|--------|
 ```
 
 ## Creation Workflow
 
+Both paths start with `grounding.md`: the guideline source read in full, the ideal state, and the gap ledger in section 9.
+
 ### For New Projects
 
 1. **Select references before taste** — no visual reference means `_INDEX.md` shortlist of 2-3 Layer B candidates, then exactly one Layer A style skill and one Layer B brand/design-system reference. Use `open-design` only when the curated set has no fit.
 2. **Assemble from references** — extract tokens, layout grammar, component anatomy, states, motion, and taste decisions, then recombine them into project-specific primitives. Customize for the user's product; never copy logos, trademarked assets, or brand-specific copy.
-3. **Define the system** — atmosphere, palette, typography, spacing, and one depth strategy, grounded in the selected references and product semantics. Sanity-check the palette and type pairing with one `ui-ux-db` domain search (CLI in `references/ui-ux-db/README.md`).
-4. **Document initial primitives** — only components you are about to build, including variants and states.
+3. **Define the system** — colour roles first (both themes), then atmosphere, typography, spacing, and one depth strategy, grounded in the selected references and product semantics. Sanity-check the palette and type pairing with one `ui-ux-db` domain search (CLI in `references/ui-ux-db/README.md`).
+4. **Document initial primitives** — only components you are about to build, including variants and states, starting from shadcn/ui anatomy (or the project's own kit) restyled with the tokens.
 5. **Write it to `DESIGN.md`** at project root.
 6. **Build a primitive showcase first** — exercise each primitive's default, hover, active, focus, disabled, loading, empty, and error states at mobile/tablet/desktop widths before composing product screens.
 
@@ -239,7 +252,7 @@ After every component implementation, check:
 - [ ] All colors reference tokens from Section 2. No raw hex outside `DESIGN.md`.
 - [ ] All font sizes match Section 3 scale. No arbitrary sizes.
 - [ ] Spacing intent maps to a token (Section 4); browser mechanics (`clamp()`, intrinsic sizing, container units) stay raw. No arbitrary px.
-- [ ] Interactive elements have all required states from Section 5 and Section 6.
+- [ ] Interactive elements have all required states from Section 5 and Section 6, and keep one box across them: width and height match in every state, and no padding appears for a spinner or arrow.
 - [ ] Depth treatment matches the chosen strategy from Section 7.
 - [ ] Component reused 2+ times? Documented in Section 5.
 - [ ] Motion follows the timing and feedback-threshold tables, and every animation has its reduced-motion path.

package/packages/shared-skills/skills/frontend/references/design/grounding.md

@@ -0,0 +1,29 @@
+# Grounding: guideline source, ideal state, gap ledger
+
+Run this before the brief for a new screen or flow, a redesign ("this looks bad", "make it better", "rework the design system"), and any design-system creation or rework. It replaces taste guesses with a written bar: what a good interface does for its users, and every place the work falls short of it. A small change skips the run and reads the ledger in `DESIGN.md` section 9 when one exists.
+
+The output is `DESIGN.md` section 9 (`design-system-architecture.md` gives the template), or the change description when the project has no `DESIGN.md`.
+
+## 1. Guideline source, read in full
+
+Pick the authoritative sources for the platform and the domain: the platform's guidelines (Apple Human Interface Guidelines, Material 3, Fluent 2), WCAG 2.2, and the project's own `DESIGN.md`. Read every page. If a source is too large for one context (the Apple HIG runs to hundreds of pages), split it across parallel readers with `/mass-ulw`, or with parallel subagents where it is unavailable. Each reader returns the principles from its pages with their URLs. A skimmed or sampled source counts as unread.
+
+## 2. Universal principles
+
+Drop the platform idioms: named materials, system icon sets, platform control chrome, and vendor elevation and motion names. Keep what holds for any interface: hierarchy, feedback, consistency, error prevention and recovery, input effort, density, legibility, and accessibility. Tie each principle to a persona and a journey step. Name who uses the product and what they are trying to get done. Then name the step where the principle decides the experience: first visit, daily use, recovery from an error, or a return after time away.
+
+## 3. Ideal state
+
+For each journey step, write what the product does at its best: what the user sees first, the one action, the feedback after it, and the way back from a mistake. Write it so a reviewer can check it on a screenshot: "the run's status and its one next action are the first thing on the screen" is checkable; "clean and intuitive" is not.
+
+## 4. Gap ledger
+
+Capture the surface under work through `/visual-qa` (on a new screen, the first draft, built after the brief; the ledger then grows as the draft is checked) (every state at 390 and 1440, both themes) and list every difference from the ideal state. Do not rank the small ones away. Then read the rule sources in full and add every violation of each: `SKILL.md`'s build rules and draft guard (plus `check-draft-guard.ts` output), the `/visual-qa` checklist, every reference this request routed to, and the WCAG 2.2 AA items in `SKILL.md` Verify. Capture a screenshot for each row and keep the ledger in a durable record (the `/ulw-loop` ledger when it runs) so no finding lives only in context. One row per gap:
+
+| ID | Screen / state | Gap | Principle or rule broken | Evidence | Fix | Proof | Status |
+|---|---|---|---|---|---|---|---|
+| G1 | Settings / save | Save button widens from 96 to 128 px when its spinner appears | State-stable controls | `before/settings-save-loading.png` | Spinner overlays the hidden label in a fixed-width slot | Width probe equal across idle/loading/done; `/visual-qa` before/after pair | open |
+
+## 5. Close the ledger
+
+Plan the fixes before the first edit (`/ulw-plan` for a large ledger): each row names its fix and, in advance, the `/visual-qa` item or probe that will prove it. Then execute without stopping to ask between rows: independent rows run in parallel (`/mass-ulw`, `/ulw-execute`), each fix is a scoped pass (`SKILL.md` Verify), and a large ledger ships as several PRs grouped by screen or rule. A row closes only with its before/after pair and the passing proof, and the pairs go in the PR body. Report progress often as closed/total ledger rows, naming what closed since the last report.

package/packages/shared-skills/skills/frontend/references/perfection/craft-floor.md

@@ -0,0 +1,59 @@
+# Craft floor: the numbers a build must clear
+
+Adapted from the `craft-floor` reference of [pbakaus/impeccable](https://github.com/pbakaus/impeccable) (Apache-2.0, Copyright 2025 Paul Bakaus), rewritten for this skill; see `ATTRIBUTION.md` section 6 for the license and the list of changes.
+
+Read this with `README.md` for any code change. It sets no direction, and it has two kinds of line. Each line is checked on the rendered page by reading computed values, not by looking at the source. `/visual-qa` checks them again (A3, A13, B8, E7, F8, F9).
+
+- **Floors** (marked *floor* below) hold under every style skill and brand. A project's `DESIGN.md` may raise them, never lower them.
+- **Defaults** (every other line) hold until the brief asks otherwise. That means the brief's own words, a concrete reference, or a route the brief chose that names the value or pattern: a Layer A style skill or Layer B brand under `references/design/`, or the ambience route. Brutalist display scale and tracking, a brand's labels above headings, and the ambience route's blur reveals and glowing-border cards are examples. The route wins for that one item only. Record the deviation in the brief or `DESIGN.md` so `/visual-qa` reads it as chosen, not generated.
+
+## Browser surfaces
+
+*Floor.* The parts of a page the browser draws by default ship with no design unless you give them one. Theme every one that the surface has, from the palette tokens, in both themes:
+
+| Surface | What to set |
+|---|---|
+| Text selection | `::selection { background: <accent at low alpha>; color: <ink> }`; the default system blue never shows. |
+| Caret | `caret-color: <accent or ink>` on inputs, textareas and contenteditable. |
+| Scrollbars | `scrollbar-color: <thumb> <track>` and `scrollbar-width: thin` on scroll containers that keep a visible bar. Overlay scrollbars stay overlay (`/visual-qa` A5); this styles the bar, it never adds a gutter. |
+| Focus ring | `:focus-visible { outline: 2px solid <focus token>; outline-offset: 2px }`, visible on every surface colour. |
+| Underlines | `text-underline-offset: 0.15em` to `0.25em` and `text-decoration-thickness` from the type scale on links, so the line clears descenders. |
+| Numerals | `font-variant-numeric: tabular-nums` on every column, counter, timer, price and table cell that changes or aligns. |
+
+Exempt: a surface with no instance of the element (no inputs means no caret), and a native control the brief keeps unstyled on purpose.
+
+## Type and spacing floor
+
+| Rule | Floor | Read from |
+|---|---|---|
+| Type scale steps (*floor*) | Each step of the heading ladder (display, h1, h2, h3) and the step from the smallest heading to body differ by at least 1.25x in size. The body-family roles (lead, body, small, caption, overline or label) may sit closer, but each also differs from its neighbour by weight, colour or case, never by size alone. | computed `font-size` of each role in use |
+| Space around a heading | The space above a section heading is at least 1.5x the space below it, so the heading belongs to the content it introduces. | computed margin/padding plus the parent gap |
+| Group separation | The gap between groups is at least 2x the gap inside a group. | computed `gap` / margins of siblings |
+| Body measure (*floor*) | Body text runs 65-75 characters per line on desktop; 45 is the lower bound on a phone. | rendered line length at 1440 and 390 |
+| Display size | A display heading stays at or under 6rem unless the chosen route sets a larger display scale. | computed `font-size` |
+| Tracking | Letter spacing stays at or above -0.04em unless the chosen route sets tighter display tracking; -0.02em to -0.03em usually reads better on large type. Body text keeps 0. | computed `letter-spacing` / `font-size` |
+
+Run the real copy at every captured width and fix what overflows or wraps a heading to four lines.
+
+## Patterns kept out of the first draft
+
+These extend the Draft guard in `SKILL.md`. Each one is what a generator reaches for when nothing decided otherwise, so the first draft leaves it out. The brief or its chosen route can still ask for one (see the defaults rule above). The hard offset shadow below is narrower than that.
+
+- **Kicker above a heading.** A small uppercase or accent label sitting on top of a heading ("FEATURES", "01 - OVERVIEW"). Delete it; the heading carries its own weight.
+- **Icon in a tile over a heading.** A rounded square holding an icon, stacked above a heading and a line of text, repeated across a grid of same-size cards. Use the content's own structure (a list, a table, a real image) instead of the card formula.
+- **Hero metric.** One giant number with a small label, flanked by supporting stats and an accent. A number earns that size only when it is the decision the screen exists for.
+- **Cards inside cards.** A bordered or shadowed box inside another. Separate inner groups with space or a neutral 1px rule.
+- **Gray text on a coloured surface.** Secondary text on a tinted or coloured background takes a shade of that hue (or the foreground at reduced alpha), never neutral gray, which looks dirty and fails contrast first.
+- **Monospace as a costume.** A monospace face only for code, data, ids and measurements, never to make a heading or a UI read as "technical".
+- **Glow and halo shadows.** A shadow carries a y-offset and a soft blur. A zero-offset coloured glow around a card or button is decoration, unless the brief asked for glowing-border cards through the ambience route. Hard offset shadows with no blur (`4px 4px 0`) only when the brief chose a neobrutalist direction.
+
+## What this skill does not take from the source
+
+The upstream reference disagrees with rules this skill already holds; ours win:
+
+- Blur, `backdrop-filter` and `filter: blur()` are not general motion materials. They animate only in an ambience reveal the brief asked for (`references/design/ambience-skill.md`), and never under `prefers-reduced-motion` (`/visual-qa` G4).
+- A label above a heading is a default to leave out, not an absolute ban: a style route that allows a limited number of them (`taste-skill.md`) is followed.
+- Both light and dark themes ship (`/visual-qa` E1); the theme is not picked per product category.
+- An intentional spring is allowed where `DESIGN.md` names it; bounce easing is a finding only when no token asked for it.
+- A typeface the project chose (for example Inter in a product that matches its platform) is never a finding because it is common.
+- Scrollbars follow the overlay rule above; this skill never asks for a decorative custom scrollbar.

package/packages/shared-skills/skills/frontend/references/perfection/detect.md

@@ -0,0 +1,52 @@
+# frontend-detect: the after-build lint
+
+`scripts/detect/` is a typed TypeScript SDK that renders a page and lints what the browser actually drew: contrast against the painted background, the type scale in use, spacing, overflow, decoration tells, and copy tells. The rule logic is ported from the detector of [pbakaus/impeccable](https://github.com/pbakaus/impeccable) (Apache-2.0, Copyright 2025 Paul Bakaus) plus one reflow check from [changeroa/StyleGallery](https://github.com/changeroa/StyleGallery) (MIT); see `ATTRIBUTION.md` section 7.
+
+It runs after the draft builds and before `/visual-qa`. `check-draft-guard.ts` stays the first lint on source; this one needs a rendered page and catches what source cannot show: a 4.2:1 table header in dark mode, an h1 followed by an h3, a heading that wraps one word onto its last line, a card that overflows at 390.
+
+## Run it
+
+From code (the primary interface). Import `index.ts`; importing does nothing until you call a function:
+
+```ts
+const detect = await import(`${SKILL_DIR}/scripts/detect/index.ts`)
+const findings = await detect.detectPage({ kind: "url", url: "http://localhost:5173/settings" }, {
+  viewports: [{ width: 1440, height: 900 }, { width: 390, height: 844 }],
+  reflow: true,
+  config: { allowFonts: ["Inter"], designTokens: { radii: [8, 12] } },
+})
+if (detect.hasFailures(findings)) console.log(detect.formatFindingsText(findings))
+```
+
+- `detectPage(target, options)`: `target` is `{ kind: "url", url }` or `{ kind: "html", html }`. Renders at each viewport (default 1440 and 390) and returns sorted, de-duplicated findings.
+- `detectFiles(paths, options)`: HTML files are rendered; CSS/SCSS/Less, JSX/TSX, Vue, Svelte and Astro files run the source-text rules.
+- `lintSnapshot(snapshot, options)` / `lintSources(files, options)`: the pure rule engines, for a snapshot you captured yourself with `collectPageSnapshot` in your own Playwright or omowright page.
+- `renderer`: pass your own `Renderer` to reuse a browser you already drive; the default is `Bun.WebView` (system WebKit on macOS, installed Chrome elsewhere; `createWebViewRenderer({ backend: "chrome" })` matches the upstream engine most closely).
+- Every finding carries `ruleId`, `severity` (`error`, `warning`, `advisory`), `category`, `message`, `fixHint`, and a `location`: an element (`selector`, `rect`, `viewport`), a source position (`file`, `line`, `column`), or the page.
+
+From a shell, the CLI is a thin wrapper over the same calls:
+
+```bash
+bun $SKILL_DIR/scripts/detect/cli.ts [--json] [--reflow] [--config detect.json] <file-or-dir-or-url>...
+```
+
+Exit 0: no error or warning findings. Exit 1: at least one. Exit 2: usage error or a page that failed to render.
+
+## Config
+
+`--config` (or `options.config`) takes JSON:
+
+| Key | Meaning |
+|---|---|
+| `rules` | `{ "<rule-id>": "error" \| "warning" \| "advisory" \| "off" }` per rule |
+| `allowFonts` | Families the project chose on purpose (Inter on a product that matches its platform); never reported as overused |
+| `allowEasings` | Timing functions `DESIGN.md` names on purpose, such as an intentional spring |
+| `designTokens` | `{ fonts, colors, radii, fontSizes }`; the `design-system-*` rules report values outside them and stay silent without them |
+
+Waive one element with `data-detect-ignore="<rule-id> <rule-id>"` on it or an ancestor (upstream's `data-impeccable-ignore` is honoured too). A waiver needs the reason in `DESIGN.md`.
+
+## Reading the result
+
+- `error` and `warning` fail the gate: fix them before `/visual-qa`. `low-contrast` is an error here, stricter than upstream, because a contrast failure is never a taste call.
+- `advisory` findings are review prompts (`hard-offset-shadow` on a page that chose neobrutalism, `bounce-easing` on a named spring). Record the decision; do not delete a deliberate choice to silence one.
+- A finding you believe is wrong: rerun at the viewport it names and read the computed values it quotes. Waive it with the attribute only when `DESIGN.md` explains why.

package/packages/shared-skills/skills/frontend/references/ui-ux-db/scripts/design_system.py

@@ -18,6 +18,8 @@ import json
 import os
 from datetime import datetime
 from pathlib import Path
+import sys
+sys.dont_write_bytecode = True
 from core import search, DATA_DIR
 
 

package/packages/shared-skills/skills/frontend/references/ui-ux-db/scripts/search.py

@@ -17,6 +17,8 @@ Persistence (Master + Overrides pattern):
 import argparse
 import sys
 import io
+import sys
+sys.dont_write_bytecode = True
 from core import CSV_CONFIG, AVAILABLE_STACKS, MAX_RESULTS, search, search_stack
 from design_system import generate_design_system, persist_design_system
 

package/packages/shared-skills/skills/frontend/scripts/detect/cli.ts

@@ -0,0 +1,70 @@
+#!/usr/bin/env bun
+// Thin CLI over the detect SDK (index.ts). Usage:
+//   bun cli.ts [--json] [--reflow] [--config <file.json>] <file-or-dir-or-url>...
+// Exit 0 no error or warning findings, 1 findings that fail the gate, 2 usage or render failure.
+import { readFileSync } from "node:fs"
+import { collectFiles } from "../perfection/collect-files"
+import { type DetectConfig, detectFiles, detectPage, type Finding, formatFindingsText, hasFailures, parseConfig, RenderError, sortFindings } from "./index"
+
+type Args = { readonly json: boolean; readonly reflow: boolean; readonly config: DetectConfig; readonly targets: readonly string[] }
+
+function readConfig(path: string): DetectConfig | string {
+	let raw: unknown
+	try {
+		raw = JSON.parse(readFileSync(path, "utf8"))
+	} catch (error) {
+		// no-excuse-ok: catch (CLI boundary: an unreadable or malformed config file is a usage error reported as exit 2)
+		if (error instanceof Error) return error.message
+		throw error
+	}
+	return parseConfig(raw)
+}
+
+function parseArgs(argv: readonly string[]): Args | string {
+	let json = false
+	let reflow = false
+	let config: DetectConfig = {}
+	const targets: string[] = []
+	for (let i = 0; i < argv.length; i++) {
+		const a = argv[i] ?? ""
+		if (a === "--json") json = true
+		else if (a === "--reflow") reflow = true
+		else if (a === "--config") {
+			const path = argv[++i]
+			if (!path) return "--config needs a file"
+			const parsed = readConfig(path)
+			if (typeof parsed === "string") return `${path}: ${parsed}`
+			config = parsed
+		} else targets.push(a)
+	}
+	return targets.length === 0 ? "no targets" : { json, reflow, config, targets }
+}
+
+async function main(argv: readonly string[]): Promise<number> {
+	const args = parseArgs(argv)
+	if (typeof args === "string") {
+		process.stderr.write(`frontend-detect: ${args}\nusage: cli.ts [--json] [--reflow] [--config <file.json>] <file-or-dir-or-url>...\n`)
+		return 2
+	}
+	const urls = args.targets.filter((t) => /^https?:\/\//.test(t))
+	const { paths, missing } = collectFiles(args.targets.filter((t) => !urls.includes(t)))
+	if (missing.length > 0) {
+		process.stderr.write(`frontend-detect: cannot read ${missing.join(", ")}\n`)
+		return 2
+	}
+	const options = { config: args.config, reflow: args.reflow }
+	const findings: Finding[] = [...(await detectFiles(paths, options))]
+	for (const url of urls) findings.push(...(await detectPage({ kind: "url", url }, { ...options, file: url })))
+	const sorted = sortFindings(findings)
+	process.stdout.write(args.json ? `${JSON.stringify(sorted, null, 2)}\n` : formatFindingsText(sorted))
+	return hasFailures(sorted) ? 1 : 0
+}
+
+try {
+	process.exitCode = await main(process.argv.slice(2))
+} catch (error) {
+	// no-excuse-ok: catch (CLI boundary: a render failure is reported as exit 2, anything else propagates)
+	if (!(error instanceof RenderError)) throw error
+	process.stderr.write(`frontend-detect: ${error.message}\n`)
+	process.exitCode = 2
+}

package/packages/shared-skills/skills/frontend/scripts/detect/config.test.ts

@@ -0,0 +1,26 @@
+import { describe, expect, test } from "bun:test"
+import { parseConfig } from "./config"
+import type { DetectConfig } from "./types"
+
+describe("parseConfig (the CLI's --config trust boundary)", () => {
+	test("#given a full valid config #then every field is kept", () => {
+		const input: DetectConfig = {
+			rules: { "low-contrast": "warning", "bounce-easing": "off" },
+			allowFonts: ["Inter"],
+			allowEasings: ["cubic-bezier(0.34, 1.56, 0.64, 1)"],
+			designTokens: { fonts: ["Inter"], colors: ["#111"], radii: [8, 12], fontSizes: [12, 16, 24] },
+		}
+		expect(parseConfig(input)).toEqual(input)
+	})
+
+	test.each([
+		["a non-object", [], "config must be a JSON object"],
+		["an unknown key", { severity: "error" }, "unknown config key 'severity'"],
+		["a bad rule setting", { rules: { "low-contrast": "fatal" } }, "rules.low-contrast must be one of error, warning, advisory, off"],
+		["a non-string font", { allowFonts: [12] }, "allowFonts must be an array of family names"],
+		["an unknown token key", { designTokens: { shadows: [] } }, "unknown designTokens key 'shadows'"],
+		["a non-numeric radius", { designTokens: { radii: ["8px"] } }, "designTokens.radii must be an array of px numbers"],
+	])("#given %s #then it is refused with a message naming the field", (_name, input, message) => {
+		expect(parseConfig(input)).toBe(message)
+	})
+})

package/packages/shared-skills/skills/frontend/scripts/detect/config.ts

@@ -0,0 +1,53 @@
+import type { DesignTokens, DetectConfig, RuleSetting } from "./types"
+
+const SETTINGS: readonly RuleSetting[] = ["error", "warning", "advisory", "off"]
+
+const isRecord = (v: unknown): v is Record<string, unknown> => typeof v === "object" && v !== null && !Array.isArray(v)
+const isStringArray = (v: unknown): v is readonly string[] => Array.isArray(v) && v.every((x) => typeof x === "string")
+const isNumberArray = (v: unknown): v is readonly number[] => Array.isArray(v) && v.every((x) => typeof x === "number" && Number.isFinite(x))
+
+function parseTokens(v: unknown): DesignTokens | string {
+	if (!isRecord(v)) return "designTokens must be an object"
+	const { fonts, colors, radii, fontSizes, ...rest } = v
+	const extra = Object.keys(rest)[0]
+	if (extra) return `unknown designTokens key '${extra}'`
+	if (fonts !== undefined && !isStringArray(fonts)) return "designTokens.fonts must be an array of family names"
+	if (colors !== undefined && !isStringArray(colors)) return "designTokens.colors must be an array of CSS colors"
+	if (radii !== undefined && !isNumberArray(radii)) return "designTokens.radii must be an array of px numbers"
+	if (fontSizes !== undefined && !isNumberArray(fontSizes)) return "designTokens.fontSizes must be an array of px numbers"
+	return {
+		...(fonts !== undefined ? { fonts } : {}),
+		...(colors !== undefined ? { colors } : {}),
+		...(radii !== undefined ? { radii } : {}),
+		...(fontSizes !== undefined ? { fontSizes } : {}),
+	}
+}
+
+const isSetting = (v: unknown): v is RuleSetting => SETTINGS.some((s) => s === v)
+
+/** Parses a detect config from untrusted JSON; returns the config or a message naming the first bad field. */
+export function parseConfig(input: unknown): DetectConfig | string {
+	if (!isRecord(input)) return "config must be a JSON object"
+	const known = new Set(["rules", "allowFonts", "allowEasings", "designTokens"])
+	const unknownKey = Object.keys(input).find((k) => !known.has(k))
+	if (unknownKey) return `unknown config key '${unknownKey}'`
+	const { rules, allowFonts, allowEasings, designTokens } = input
+	const tokens = designTokens === undefined ? undefined : parseTokens(designTokens)
+	if (typeof tokens === "string") return tokens
+	const parsedRules: Record<string, RuleSetting> = {}
+	if (rules !== undefined) {
+		if (!isRecord(rules)) return "rules must be an object of rule id -> error|warning|advisory|off"
+		for (const [id, setting] of Object.entries(rules)) {
+			if (!isSetting(setting)) return `rules.${id} must be one of ${SETTINGS.join(", ")}`
+			parsedRules[id] = setting
+		}
+	}
+	if (allowFonts !== undefined && !isStringArray(allowFonts)) return "allowFonts must be an array of family names"
+	if (allowEasings !== undefined && !isStringArray(allowEasings)) return "allowEasings must be an array of timing functions"
+	return {
+		...(rules !== undefined ? { rules: parsedRules } : {}),
+		...(allowFonts !== undefined ? { allowFonts } : {}),
+		...(allowEasings !== undefined ? { allowEasings } : {}),
+		...(tokens !== undefined ? { designTokens: tokens } : {}),
+	}
+}

package/packages/shared-skills/skills/frontend/scripts/detect/core/characters.ts

@@ -0,0 +1,2 @@
+/** The em dash, built from its code point so the character never appears as a copy literal in source. */
+export const EM_DASH = String.fromCharCode(0x2014)

package/packages/shared-skills/skills/frontend/scripts/detect/core/color.test.ts

@@ -0,0 +1,29 @@
+import { describe, expect, test } from "bun:test"
+import { colorsIn, parseColor } from "./color"
+
+const rgb = (s: string): readonly number[] | null => {
+	const c = parseColor(s)
+	return c ? [c.r, c.g, c.b].map(Math.round) : null
+}
+
+describe("parseColor modern color spaces", () => {
+	test.each([
+		["color(display-p3 0.2 0.5 0.7)", [0, 130, 183]],
+		["color(display-p3 1 0 0)", [255, 0, 0]],
+		["color(srgb-linear 0.2 0.3 0.4)", [124, 149, 170]],
+		["lab(60 -20 30)", [123, 154, 90]],
+		["lab(29.2345% 39.3825 20.0664)", [125, 35, 41]],
+		["lch(50 30 120)", [105, 126, 73]],
+		["oklch(0.7 0.1 200)", [64, 177, 183]],
+	])("#given %s as getComputedStyle reports it #then it converts to the sRGB Chrome paints", (input, expected) => {
+		expect(rgb(input)).toEqual(expected)
+	})
+
+	test("#given an unsupported predefined space #then the color is unknown, not black", () => {
+		expect(parseColor("color(rec2020 0.5 0.5 0.5)")).toBeNull()
+	})
+
+	test("#given a gradient with lab and lch stops #then colorsIn finds every stop", () => {
+		expect(colorsIn("linear-gradient(lab(60 -20 30), lch(50 30 120) 50%, oklab(0.5 0 0))").length).toBe(3)
+	})
+})

package/packages/shared-skills/skills/frontend/scripts/detect/core/color.ts

@@ -0,0 +1,150 @@
+export type Rgba = { readonly r: number; readonly g: number; readonly b: number; readonly a: number }
+
+export const TRANSPARENT: Rgba = { r: 0, g: 0, b: 0, a: 0 }
+export const WHITE: Rgba = { r: 255, g: 255, b: 255, a: 1 }
+
+const clamp255 = (n: number): number => Math.max(0, Math.min(255, n))
+
+function parseHex(hex: string): Rgba | null {
+	const h = hex.slice(1)
+	const full = h.length === 3 || h.length === 4 ? [...h].map((c) => c + c).join("") : h
+	if (!/^[0-9a-f]{6}([0-9a-f]{2})?$/i.test(full)) return null
+	const n = (i: number): number => Number.parseInt(full.slice(i, i + 2), 16)
+	return { r: n(0), g: n(2), b: n(4), a: full.length === 8 ? n(6) / 255 : 1 }
+}
+
+function channel(token: string, scale: number): number {
+	return token.endsWith("%") ? (Number.parseFloat(token) / 100) * scale : Number.parseFloat(token)
+}
+
+function oklabToRgb(l: number, a: number, b: number): readonly [number, number, number] {
+	const l_ = (l + 0.3963377774 * a + 0.2158037573 * b) ** 3
+	const m_ = (l - 0.1055613458 * a - 0.0638541728 * b) ** 3
+	const s_ = (l - 0.0894841775 * a - 1.291485548 * b) ** 3
+	const lin = [
+		4.0767416621 * l_ - 3.3077115913 * m_ + 0.2309699292 * s_,
+		-1.2684380046 * l_ + 2.6097574011 * m_ - 0.3413193965 * s_,
+		-0.0041960863 * l_ - 0.7034186147 * m_ + 1.707614701 * s_,
+	] as const
+	const gamma = (c: number): number => clamp255(255 * (c <= 0.0031308 ? 12.92 * c : 1.055 * c ** (1 / 2.4) - 0.055))
+	return [gamma(lin[0]), gamma(lin[1]), gamma(lin[2])]
+}
+
+type Vec3 = readonly [number, number, number]
+const mul = (m: readonly Vec3[], v: Vec3): Vec3 => {
+	const row = (i: number): Vec3 => m[i] ?? [0, 0, 0]
+	const dot = (r: Vec3): number => r[0] * v[0] + r[1] * v[1] + r[2] * v[2]
+	return [dot(row(0)), dot(row(1)), dot(row(2))]
+}
+const XYZ_D65_TO_LINEAR_SRGB: readonly Vec3[] = [
+	[3.2409699419, -1.5373831776, -0.4986107603],
+	[-0.9692436363, 1.8759675015, 0.0415550574],
+	[0.0556300797, -0.2039769589, 1.0569715142],
+]
+const LINEAR_P3_TO_XYZ_D65: readonly Vec3[] = [
+	[0.4865709486, 0.2656676932, 0.1982172852],
+	[0.2289745641, 0.6917385218, 0.0792869141],
+	[0, 0.0451133819, 1.0439443689],
+]
+const XYZ_D50_TO_D65: readonly Vec3[] = [
+	[0.9554734528, -0.0230985368, 0.0632593086],
+	[-0.0283697094, 1.0099954580, 0.0210413990],
+	[0.0123140016, -0.0205076964, 1.3303659366],
+]
+const toLinear = (c: number): number => (Math.abs(c) <= 0.04045 ? c / 12.92 : Math.sign(c) * ((Math.abs(c) + 0.055) / 1.055) ** 2.4)
+const encode = (lin: Vec3): Vec3 => {
+	const gamma = (c: number): number => clamp255(255 * (c <= 0.0031308 ? 12.92 * c : 1.055 * c ** (1 / 2.4) - 0.055))
+	return [gamma(lin[0]), gamma(lin[1]), gamma(lin[2])]
+}
+
+function labToRgb(l: number, a: number, b: number): Vec3 {
+	const fy = (l + 16) / 116
+	const [fx, fz] = [fy + a / 500, fy - b / 200]
+	const inv = (t: number): number => (t ** 3 > 216 / 24389 ? t ** 3 : (116 * t - 16) / (24389 / 27))
+	const xyzD50: Vec3 = [0.3457 / 0.3585 * inv(fx), l > 8 ? fy ** 3 : l / (24389 / 27), (1 - 0.3457 - 0.3585) / 0.3585 * inv(fz)]
+	return encode(mul(XYZ_D65_TO_LINEAR_SRGB, mul(XYZ_D50_TO_D65, xyzD50)))
+}
+
+function predefinedToRgb(space: string, c: Vec3): Vec3 | null {
+	if (space === "srgb") return [clamp255(c[0] * 255), clamp255(c[1] * 255), clamp255(c[2] * 255)]
+	if (space === "srgb-linear") return encode(c)
+	if (space === "display-p3") return encode(mul(XYZ_D65_TO_LINEAR_SRGB, mul(LINEAR_P3_TO_XYZ_D65, [toLinear(c[0]), toLinear(c[1]), toLinear(c[2])])))
+	return null
+}
+
+/** Parses the color forms getComputedStyle returns (rgb/rgba, color(srgb | srgb-linear | display-p3), lab/lch, oklab/oklch) plus hex and `transparent`; other spaces return null. Out-of-gamut values are clamped to sRGB. */
+export function parseColor(input: string): Rgba | null {
+	const s = input.trim().toLowerCase()
+	if (s === "transparent") return TRANSPARENT
+	if (s.startsWith("#")) return parseHex(s)
+	const m = /^(rgba?|color|oklab|oklch|lab|lch)\((.*)\)$/.exec(s)
+	if (!m) return null
+	const [, fn, body = ""] = m
+	const [main = "", alphaPart] = body.split("/")
+	const parts = main.replace(/,/g, " ").split(/\s+/).filter(Boolean)
+	const commaAlpha = fn?.startsWith("rgb") && parts.length === 4 ? parts[3] : undefined
+	const alphaToken = alphaPart?.trim() ?? commaAlpha
+	const a = alphaToken === undefined ? 1 : channel(alphaToken, 1)
+	if (fn === "rgb" || fn === "rgba") return { r: channel(parts[0] ?? "0", 255), g: channel(parts[1] ?? "0", 255), b: channel(parts[2] ?? "0", 255), a }
+	if (fn === "color") {
+		const rgb = predefinedToRgb(parts[0] ?? "", [channel(parts[1] ?? "0", 1), channel(parts[2] ?? "0", 1), channel(parts[3] ?? "0", 1)])
+		return rgb ? { r: rgb[0], g: rgb[1], b: rgb[2], a } : null
+	}
+	if (fn === "lab" || fn === "lch") {
+		const l = channel(parts[0] ?? "0", 100)
+		const [q1, q2] = [Number.parseFloat(parts[1] ?? "0"), Number.parseFloat(parts[2] ?? "0")]
+		const [la, lb] = fn === "lch" ? [q1 * Math.cos((q2 * Math.PI) / 180), q1 * Math.sin((q2 * Math.PI) / 180)] : [q1, q2]
+		const [r, g, b] = labToRgb(l, la, lb)
+		return { r, g, b, a }
+	}
+	const l = channel(parts[0] ?? "0", 1)
+	const [p1, p2] = [Number.parseFloat(parts[1] ?? "0"), Number.parseFloat(parts[2] ?? "0")]
+	const [oa, ob] = fn === "oklch" ? [p1 * Math.cos((p2 * Math.PI) / 180), p1 * Math.sin((p2 * Math.PI) / 180)] : [p1, p2]
+	const [r, g, b] = oklabToRgb(l, oa, ob)
+	return { r, g, b, a }
+}
+
+/** Source-over compositing of `top` onto an opaque `bottom`. */
+export function blend(top: Rgba, bottom: Rgba): Rgba {
+	const a = top.a + bottom.a * (1 - top.a)
+	if (a === 0) return TRANSPARENT
+	const mix = (t: number, b: number): number => (t * top.a + b * bottom.a * (1 - top.a)) / a
+	return { r: mix(top.r, bottom.r), g: mix(top.g, bottom.g), b: mix(top.b, bottom.b), a }
+}
+
+/** WCAG 2.x relative luminance. */
+export function luminance(c: Rgba): number {
+	const lin = (v: number): number => {
+		const s = v / 255
+		return s <= 0.04045 ? s / 12.92 : ((s + 0.055) / 1.055) ** 2.4
+	}
+	return 0.2126 * lin(c.r) + 0.7152 * lin(c.g) + 0.0722 * lin(c.b)
+}
+
+/** WCAG 2.x contrast ratio between two opaque colors, 1..21. */
+export function contrastRatio(a: Rgba, b: Rgba): number {
+	const [hi, lo] = [luminance(a), luminance(b)].sort((x, y) => y - x)
+	return ((hi ?? 0) + 0.05) / ((lo ?? 0) + 0.05)
+}
+
+export function toHsl(c: Rgba): { readonly h: number; readonly s: number; readonly l: number } {
+	const [r, g, b] = [c.r / 255, c.g / 255, c.b / 255]
+	const max = Math.max(r, g, b)
+	const min = Math.min(r, g, b)
+	const l = (max + min) / 2
+	if (max === min) return { h: 0, s: 0, l }
+	const d = max - min
+	const s = l > 0.5 ? d / (2 - max - min) : d / (max + min)
+	const h = max === r ? (g - b) / d + (g < b ? 6 : 0) : max === g ? (b - r) / d + 2 : (r - g) / d + 4
+	return { h: h * 60, s, l }
+}
+
+/** Every color literal inside a computed value such as `box-shadow` or `background-image`. */
+export function colorsIn(value: string): readonly Rgba[] {
+	const out: Rgba[] = []
+	for (const m of value.matchAll(/(rgba?|color|oklab|oklch|lab|lch)\([^()]*\)|#[0-9a-f]{3,8}\b/gi)) {
+		const c = parseColor(m[0])
+		if (c) out.push(c)
+	}
+	return out
+}