From 8de07dbce6b395e9cfae4806eb7446b72a234faf Mon Sep 17 00:00:00 2001
From: Hugh Francis <hughfrancis89@gmail.com>
Date: Mon, 11 May 2026 14:33:05 -0400
Subject: [PATCH 01/79] Add spec for /adhd:install-design-system-docs-route
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

One-shot installer that drops a live, self-generating design-system
documentation route into a Next.js consumer app. The route reads
adhd.config.ts and globals.css at request time, renders a token
catalog (colors / spacing / typography / radius / shadows) plus per-
component pages with URL-driven prop toggles. No regen needed when
components or tokens change.

Key design choices:
- Pure one-shot install. No designSystem block added to adhd.config.ts —
  install choices (route URL, route group, prod-exclusion) are encoded
  in the filesystem, not stored as durable state.
- Route group `(design-system)` + hyphen-prefix URL `/-docs` by default.
  Group organizes future internal routes filesystem-side; hyphen prefix
  telegraphs "internal" in the URL itself.
- Production exclusion via Next.js pageExtensions conditional. Files
  use `.design-system.tsx` extension; next.config.ts patched to include
  the extension only when NODE_ENV !== 'production'. Files literally
  invisible to the production build — zero bundle pollution.
- User can opt out of prod-exclusion at install time. Some teams want
  the docs route reachable in deployed environments behind their own
  auth. noindex meta + robots.txt entry apply either way.
- Ejection-friendly: generated files contain zero references to "ADHD."
  Only adhd.config.ts uses that name. Marker comment is generic:
  `// design-system-docs-route — auto-generated installer artifact; safe to edit.`
- Triggered as an optional final phase of /adhd:config so first-time
  users get a one-stop setup. Available standalone for retroactive install.

20 acceptance criteria. Test plan covers unit tests for the helpers
(token-parser, prop-parser, slug, config patchers) plus one
integration test against a copy of example/ and a documented manual
smoke test.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 ...1-adhd-install-design-system-docs-route.md | 477 ++++++++++++++++++
 1 file changed, 477 insertions(+)
 create mode 100644 docs/superpowers/specs/2026-05-11-adhd-install-design-system-docs-route.md

diff --git a/docs/superpowers/specs/2026-05-11-adhd-install-design-system-docs-route.md b/docs/superpowers/specs/2026-05-11-adhd-install-design-system-docs-route.md
new file mode 100644
index 0000000..be00901
--- /dev/null
+++ b/docs/superpowers/specs/2026-05-11-adhd-install-design-system-docs-route.md
@@ -0,0 +1,477 @@
+# /adhd:install-design-system-docs-route — Install a Self-Generating Design-System Docs Route
+
+**Goal:** One-shot scaffolding command that installs a live, self-generating documentation route into a Next.js consumer app. The route reads `adhd.config.ts` and `globals.css` at request time, renders a token catalog (colors / spacing / typography / radius / shadows) plus a list of every tracked component, and offers per-component pages with URL-driven prop toggles. Behaves like a mini-Storybook tailored to the ADHD design-system model.
+
+**Architectural premise:** The route is **dynamic at runtime**. No regen step when components or tokens change — the page reads filesystem state on each request. The skill is a pure one-shot installer that drops a small set of files into the consumer app and optionally patches `next.config.ts`. Nothing is stored in `adhd.config.ts` about the docs route — the install choices are encoded in the filesystem.
+
+**Ejection-friendly:** generated files contain zero references to the word "ADHD." The only place ADHD appears in the consumer app is `adhd.config.ts` itself. If the user later ejects from ADHD, the docs route still works as long as `adhd.config.ts` (or whatever they rename it to) remains present and parseable.
+
+**Precondition:** The consumer app is a Next.js 16+ App Router project with an `adhd.config.ts` at the repo root. The skill aborts otherwise.
+
+---
+
+## Final command surface
+
+```
+/adhd:install-design-system-docs-route   — install or update the docs route (NEW)
+```
+
+Also triggered as an optional final phase of `/adhd:config` (the wizard asks "Set up the design-system docs route?" and on `yes` walks through the same install flow inline).
+
+**Out of scope for v1:**
+- Multi-route documentation (e.g. one URL per token domain). v1 is a single route with index + per-component pages.
+- Image-based component previews (rendering a server-side screenshot). v1 renders the component as live HTML.
+- Live Figma comparison side-by-side. v1 is purely code-side documentation.
+- Storage of user customizations on regen. v1 detects existing installs and prompts before overwriting; in-place updates preserve the layout file's customizations via Edit-not-Write.
+
+---
+
+## Architecture
+
+**File layout in the consumer app** (defaults shown; both `(design-system)` and `-docs` are configurable at install time):
+
+```
+example/
+├── adhd.config.ts                                  # untouched by this skill
+├── next.config.ts                                  # patched only if prod-exclusion: yes
+├── public/
+│   └── robots.txt                                  # patched (Disallow line added; file created if missing)
+└── app/
+    └── (design-system)/                            # Next.js route group — invisible in URL
+        └── -docs/
+            ├── layout.design-system.tsx            # or layout.tsx — see "File extensions" below
+            ├── page.design-system.tsx              # index — URL: /-docs
+            └── [component]/
+                └── page.design-system.tsx          # per-component — URL: /-docs/<slug>
+```
+
+**Route group `(design-system)`:** organizes the route filesystem-side without affecting URLs. Future internal design-system routes (token playground, fixture viewer, etc.) cohabit cleanly under the same group. The user can pick a different group name at install or omit the group entirely.
+
+**Route URL `/-docs`:** the hyphen prefix telegraphs "internal" in the URL itself. The user can pick a different URL at install (e.g. `/design-system`, `/docs`, `/-internal/design-system`).
+
+**File extensions when prod-excluded:** files use `.design-system.tsx`. The skill patches `next.config.ts` to include this extension in `pageExtensions` only when `NODE_ENV !== 'production'`:
+
+```ts
+const nextConfig: NextConfig = {
+  pageExtensions: process.env.NODE_ENV === 'production'
+    ? ['ts', 'tsx']
+    : ['ts', 'tsx', 'design-system.ts', 'design-system.tsx'],
+  // ...existing config
+};
+```
+
+Production builds literally do not see these files. Zero bundle pollution.
+
+**File extensions when NOT prod-excluded:** plain `.tsx`. `next.config.ts` is not patched. The route ships normally in production with `<meta name="robots" content="noindex, nofollow" />` and a `robots.txt` Disallow entry. Used by teams that want internal docs reachable in deployed environments behind their own auth.
+
+**The marker comment:** every generated file starts with:
+```ts
+// design-system-docs-route — auto-generated installer artifact; safe to edit.
+// Remove this comment to disable future overwrites from re-running the installer.
+```
+The skill scans for this comment to detect existing installs. The user can opt out of future overwrites by deleting the comment.
+
+---
+
+## Pipeline
+
+```
+Phase 1   Validate consumer environment        — adhd.config.ts present, Next.js 16+ App Router
+Phase 2   Detect existing install              — scan app/ for marker comment
+Phase 3   Ask installation choices             — route URL, route group, prod-exclusion
+Phase 4   Detect Next.js config file           — .ts / .mjs / .js
+Phase 5   Detect filesystem collisions         — target folder, route group name
+Phase 6   Patch next.config.ts                 — only if prod-exclusion: yes
+Phase 7   Write the page files                 — layout, index, [component]
+Phase 8   Patch robots.txt                     — Disallow entry
+Phase 9   Final report
+```
+
+### Phase 1 — Validate consumer environment
+
+Required:
+- `adhd.config.ts` at the project root. If missing: abort with "Run /adhd:config first."
+- `package.json` declares `next` as a dependency. Parse the version; if < 16, warn but continue (App Router has been stable since 13.4; the install is likely to work).
+- `app/` directory present (App Router convention). If only `pages/` is present, abort with "This installer requires the Next.js App Router. App Router is in `app/`; you appear to be using Pages Router."
+
+### Phase 2 — Detect existing install
+
+Scan `app/**/page.*tsx` and `app/**/layout.*tsx` for the marker comment. If found, capture the folder path of the install. Behaviors:
+
+| Found | Skill behavior |
+|---|---|
+| No marker comment anywhere | Fresh install — proceed to Phase 3 with defaults. |
+| One marker found | Prompt: "An existing install at `<path>`. [Update in place / Move to new location / Abort]." |
+| Multiple markers found | Unusual. Print all locations, prompt: "Pick which to update or move; the others stay as-is." |
+
+### Phase 3 — Ask installation choices
+
+Use `AskUserQuestion` for each (with defaults filled in from the existing install if updating):
+
+1. **Route URL** — default `/-docs`. Validate: starts with `/`, only `a-z0-9-/` characters. Reject `_` prefixes (Next.js private folders won't route).
+2. **Route group** — default `(design-system)`. Validate: parens-wrapped, alphanumerics + hyphens inside. Empty/`""` is also valid (no group).
+3. **Exclude from production builds?** — default `yes`. Determines file extension + `next.config.ts` patch.
+
+Save the choices in working memory. The choices are NOT written to `adhd.config.ts` — they're encoded in the filesystem.
+
+### Phase 4 — Detect Next.js config file
+
+Look for `next.config.ts`, `next.config.mjs`, `next.config.js` in priority order. If multiple, prefer `.ts`. Capture the file path. If none, abort: "No `next.config.*` found at the project root."
+
+### Phase 5 — Detect filesystem collisions
+
+Construct the install path: `app/<group>/<route-segment>/`. Check:
+- Target folder exists but has no marker comment → existing user content. Prompt: "Path `<full-path>` already exists. Pick a different route or abort."
+- Group folder exists but for unrelated purpose (e.g. user has their own `(design-system)` group) → prompt: "Group `(design-system)` already in use. Pick a different group or abort."
+
+### Phase 6 — Patch `next.config.ts` (conditional)
+
+Only runs if prod-exclusion: yes.
+
+Read the existing `next.config.ts`. Use `Edit` to add or update the `pageExtensions` field within the `NextConfig` object. The patch shape:
+
+```ts
+const nextConfig: NextConfig = {
+  pageExtensions: process.env.NODE_ENV === 'production'
+    ? ['ts', 'tsx']
+    : ['ts', 'tsx', 'design-system.ts', 'design-system.tsx'],
+  // ...existing config preserved verbatim
+};
+```
+
+**Idempotent:** if `pageExtensions` already has this exact conditional shape, no-op. If it has a different `pageExtensions` value entirely, prompt: "Your `next.config.ts` already sets `pageExtensions`. Show me the current value and the patch I'd apply; do you want to merge?" Print both, ask for confirmation, merge.
+
+**Edit failure:** if the config file's shape isn't a clean `export default { ... }` object the regex can patch, print the exact lines to add manually, continue with file installs.
+
+### Phase 7 — Write the page files
+
+Three files written via `Write`. All start with the marker comment.
+
+**`layout[.design-system].tsx`:**
+```tsx
+// design-system-docs-route — auto-generated installer artifact; safe to edit.
+// Remove this comment to disable future overwrites from re-running the installer.
+import type { Metadata } from "next";
+
+export const metadata: Metadata = {
+  title: "Design System Docs",
+  robots: { index: false, follow: false },
+};
+
+export default function DesignSystemDocsLayout({ children }: { children: React.ReactNode }) {
+  return (
+    <div className="min-h-screen bg-zinc-50 dark:bg-zinc-950">
+      <header className="border-b border-zinc-200 dark:border-zinc-800 p-4">
+        <div className="mx-auto max-w-5xl flex items-baseline gap-3">
+          <h1 className="text-sm font-medium">Design System Docs</h1>
+          <span className="text-xs text-zinc-500">Internal — not indexed</span>
+        </div>
+      </header>
+      <main className="mx-auto max-w-5xl p-8">{children}</main>
+    </div>
+  );
+}
+```
+
+**`page[.design-system].tsx` (index):**
+
+Server component. Reads:
+1. `adhd.config.ts` source — extracts `cssEntry` (default `app/globals.css`) and `components.*` map keys.
+2. The resolved `globals.css` source — parses `@theme` block via the inlined `token-parser` helper.
+
+Renders sections:
+- **Colors:** swatch grid (color div + name + resolved value).
+- **Spacing:** horizontal bars sized to each spacing increment.
+- **Typography:** each `--text-*` rendered as `"The quick brown fox"` at its size with its line-height applied.
+- **Radius:** small squares with each `--radius-*` applied.
+- **Shadows:** small boxes with each shadow effect applied.
+- **Components:** list of components from the config, each linking to `/-docs/<slug>`.
+
+Empty-state behavior:
+- No `@theme` block in `globals.css` → token sections show "No tokens detected. Configure `@theme` in your CSS entry."
+- No `components` map in `adhd.config.ts` → components section shows "No components tracked. Push one with `/adhd:push-component <path>`."
+
+**`[component]/page[.design-system].tsx` (per-component dynamic route):**
+
+Server component. Receives `params.component` and `searchParams`. Steps:
+
+1. Resolve the component path: scan `adhd.config.ts`'s `components.*` keys, slug each, match against `params.component`.
+2. Read the component source file via `fs.readFile`. Parse the props interface inline (regex parser, ~40 LOC; handles named-union references and inline literal unions).
+3. Compute current prop values from `searchParams` — each prop's value is `searchParams.get(propName) ?? <component's declared default>`. Booleans parse `'true'/'false'`. Unknown prop values for unions fall back to the default.
+4. Dynamic-import the component via parametric template-string:
+   ```ts
+   const mod = await import(`@/${componentPath.replace(/^app\//, 'app/').replace(/\.tsx?$/, '')}`);
+   const Component = mod.default ?? mod[componentName];
+   ```
+5. Render:
+   - **Top:** prop toggle UI (a small client component for snappy URL updates; falls back to a plain `<form>` for no-JS).
+   - **Middle:** `<Component {...currentProps} />` inside an error boundary.
+   - **Bottom:** import statement + JSX invocation snippet, both as `<pre>` blocks reflecting current state.
+
+**Client island for snappy toggles** (a tiny separate file, also `.design-system.tsx`):
+```tsx
+"use client";
+import { useRouter, useSearchParams, usePathname } from "next/navigation";
+
+export function PropToggle({ name, options, value }: { name: string; options: string[]; value: string }) {
+  const router = useRouter();
+  const path = usePathname();
+  const params = useSearchParams();
+  return (
+    <select
+      value={value}
+      onChange={(e) => {
+        const next = new URLSearchParams(params);
+        next.set(name, e.target.value);
+        router.replace(`${path}?${next}`);
+      }}
+    >
+      {options.map(o => <option key={o} value={o}>{o}</option>)}
+    </select>
+  );
+}
+```
+
+### Phase 8 — Patch `robots.txt`
+
+Look for `public/robots.txt`. If absent, create with:
+```
+User-agent: *
+Disallow: /-docs
+```
+
+If present, check for an existing `Disallow: /-docs` entry; add if missing. Idempotent.
+
+### Phase 9 — Final report
+
+Print:
+```
+✓ Design system docs route installed.
+
+  URL:           http://localhost:3000/-docs
+  Filesystem:    app/(design-system)/-docs/
+  Prod exclusion: ON (next.config.ts patched)
+  noindex meta:  ON
+  robots.txt:    Disallow added
+
+Run `npm run dev` and visit the URL to preview. The page reads adhd.config.ts
+and globals.css at request time — no regen needed when you add components or
+tokens.
+```
+
+---
+
+## Data flow (runtime, in the consumer app)
+
+```
+┌────────────────────────────────────────────────────────────────┐
+│ HTTP GET /-docs                                                 │
+└────────────────────────────────────────────────────────────────┘
+                  │
+                  ▼
+┌────────────────────────────────────────────────────────────────┐
+│ app/(design-system)/-docs/page[.design-system].tsx              │
+│ (server component)                                              │
+└────────────────────────────────────────────────────────────────┘
+        │                                       │
+        │ fs.readFile                           │ fs.readFile
+        ▼                                       ▼
+┌──────────────────────┐                ┌──────────────────────┐
+│ adhd.config.ts       │                │ globals.css          │
+│  - figma.url         │                │  @theme              │
+│  - cssEntry          │                │   --color-*          │
+│  - components.*      │                │   --spacing          │
+│                      │                │   --text-*           │
+│                      │                │   --radius-*         │
+│                      │                │   --shadow-*         │
+└──────────────────────┘                └──────────────────────┘
+        │                                       │
+        ▼                                       ▼
+┌────────────────────────────────────────────────────────────────┐
+│ HTML response                                                   │
+│  - color swatches, spacing bars, type demos, radius/shadow      │
+│  - components list (linked to /-docs/<slug>)                    │
+└────────────────────────────────────────────────────────────────┘
+
+┌────────────────────────────────────────────────────────────────┐
+│ HTTP GET /-docs/avatar?size=lg&shape=circle                     │
+└────────────────────────────────────────────────────────────────┘
+                  │
+                  ▼
+┌────────────────────────────────────────────────────────────────┐
+│ app/(design-system)/-docs/[component]/page[.design-system].tsx  │
+│ (server component)                                              │
+└────────────────────────────────────────────────────────────────┘
+        │                       │                       │
+        │ fs.readFile           │ fs.readFile           │ dynamic import
+        ▼                       ▼                       ▼
+┌──────────────────┐  ┌──────────────────┐  ┌──────────────────┐
+│ adhd.config.ts   │  │ components/      │  │ Component module │
+│ resolve slug →   │  │  avatar/         │  │ via parametric   │
+│ component path   │  │  index.tsx       │  │ template-string  │
+│                  │  │ (parse props)    │  │ import           │
+└──────────────────┘  └──────────────────┘  └──────────────────┘
+        │                       │                       │
+        └───────────────────────┴───────────────────────┘
+                  │
+                  ▼
+┌────────────────────────────────────────────────────────────────┐
+│ HTML response                                                   │
+│  - PropToggle (client island) per prop, hydrated for snappy     │
+│    URL updates                                                   │
+│  - <Component {...currentProps} /> inside error boundary        │
+│  - <pre>import { Avatar } from "@/app/components/avatar";</pre> │
+│  - <pre><Avatar size="lg" shape="circle" /></pre>               │
+└────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Module layout
+
+New library at `plugins/adhd/lib/install-design-system-docs-route/`:
+
+| File | Responsibility |
+|---|---|
+| `token-parser.js` | Extract colors / spacing / typography / radius / shadows from a `globals.css` string. Slimmer variant of `lib/design-system/code-parser.js`; returns shape suited for the docs page's rendering. |
+| `prop-parser.js` | Regex-based parser for a component's `<Name>Props` interface. Returns `{ [propName]: { type, values?, optional } }`. Reuses logic from `lib/push-component/parse-component.js` but exported as a standalone helper. |
+| `slug.js` | Path → URL slug + collision detection. |
+| `next-config-patcher.js` | Idempotent patch of `next.config.{ts,mjs,js}` to set conditional `pageExtensions`. Preserves existing config. Detects current state; no-op on re-apply. |
+| `robots-patcher.js` | Idempotent patch of `public/robots.txt`. Creates if missing. |
+| `route-installer.js` | Orchestrates: writes the 3 page files (or 4 with the client island), with the correct extension based on prod-exclusion choice. |
+| `cli.js` | Subcommand surface for the SKILL: `detect-install`, `parse-tokens`, `parse-props`, `slug`, `patch-next-config`, `patch-robots`, `install`. |
+
+New skill at `plugins/adhd/skills/install-design-system-docs-route/SKILL.md`.
+
+Modified files:
+- `plugins/adhd/skills/config/SKILL.md` — add optional final phase that invokes the install flow.
+- `.claude-plugin/marketplace.json` — bump description.
+- `README.md` — add the new command row.
+- `.github/workflows/ci.yml` — add the new test step.
+
+---
+
+## Marker comment
+
+Generated files start with:
+
+```ts
+// design-system-docs-route — auto-generated installer artifact; safe to edit.
+// Remove this comment to disable future overwrites from re-running the installer.
+```
+
+The string `design-system-docs-route` is unique enough to detect via grep. The user can opt out of future overwrites by removing the comment — the skill will then refuse to touch the file unless the user explicitly confirms re-install.
+
+**No reference to "ADHD" or "/adhd:..."** in the comment. The marker is generic; ejection-friendly.
+
+---
+
+## Edge cases & errors
+
+| Case | Behavior |
+|---|---|
+| `adhd.config.ts` missing | Abort: "Run /adhd:config first to set up ADHD." |
+| `package.json` missing or doesn't declare `next` | Abort: "This installer expects a Next.js project at the working directory." |
+| `app/` directory missing (Pages Router project) | Abort: "This installer requires the Next.js App Router." |
+| `next.config.ts/.mjs/.js` missing | Abort: "No next.config.* at the project root. Create one before running this installer." |
+| Existing install at target path (marker present) | Prompt: update / move / abort |
+| Existing user folder at target path (no marker) | Prompt: pick a different route or abort |
+| Existing route group with the chosen name (no marker) | Prompt: pick a different group or abort |
+| `next.config.ts` already sets `pageExtensions` to a different value | Prompt: show the existing value, show the proposed merge, ask to confirm |
+| `next.config.ts` shape unrecognizable | Print the exact lines to add, continue with file installs |
+| `public/` directory missing | Create `public/robots.txt`; the directory comes along |
+| `robots.txt` already has the Disallow line | No-op |
+| User chose route URL `/foo` but folder `app/foo/` already exists with user content | Phase 5 catches this; prompts before proceeding |
+| Component referenced in `adhd.config.ts` no longer exists | Index page shows it with a "missing" badge; per-component route returns a clean 404 with the missing path |
+| Component's Props interface can't be parsed | Per-component page renders the component with declared defaults; banner "Prop introspection failed — toggles unavailable." |
+| Component throws at render | Error boundary catches; shows the error message inline; "reset to defaults" link |
+| Dynamic-import path fails to resolve (component file moved/deleted) | Surface the error inline on that component's page; other routes keep working |
+| Search-param value invalid for a union prop | Fall back to default; small inline warning |
+| User runs `next build` with prod-exclusion ON | Files invisible to the build; route returns 404 in production |
+| User runs `next build` with prod-exclusion OFF | Route ships; noindex meta + robots.txt entry still apply |
+| User has CRLF line endings | `Edit` preserves them; new files written with the platform's default ending |
+
+---
+
+## Symmetric-pipeline assertions
+
+| Assertion | Mechanism |
+|---|---|
+| `prop-parser.js` shares its behavior contract with `lib/push-component/parse-component.js` | The two regex parsers handle the same prop-type categories (union, primitive, optional flag, ReactNode/function/ref skips). Unit-tested in parallel; a smoke test asserts both produce equivalent output for the Avatar source. |
+| `token-parser.js` produces tokens consistent with `lib/design-system/code-parser.js` | Same `@theme` extraction logic, narrowed to the subset the docs page needs. Unit-tested against the same `globals.css` fixtures. |
+
+---
+
+## Testing strategy
+
+**Unit tests** (`plugins/adhd/lib/install-design-system-docs-route/__tests__/`):
+
+| Module | Coverage |
+|---|---|
+| `token-parser.js` | Extracts all 5 domains from a Tailwind v4 `globals.css`; handles missing `@theme` block; handles unknown vars (returns "unknown" category). |
+| `prop-parser.js` | Parses the Avatar interface; handles inline unions, named-union references, primitives, ReactNode/function/ref (skipped). |
+| `slug.js` | Path → slug; collision detection. |
+| `next-config-patcher.js` | Patches `.ts` / `.mjs` / `.js`; idempotent on re-apply; preserves existing config; detects already-customized `pageExtensions` and merges with prompt. |
+| `robots-patcher.js` | Creates / appends; idempotent. |
+| `route-installer.js` | Writes correct files for each prod-exclusion choice; refuses overwrite without confirmation; detects existing install via marker. |
+| `cli.js` | Each subcommand exits 0 on success, 2 on usage error. |
+
+**Integration test** (one):
+- Run end-to-end against a copy of `example/` in a temp dir. Assert all files exist with the marker; `next.config.ts` has the conditional `pageExtensions`; re-running detects the install.
+
+**Manual smoke test** (acceptance criterion #20):
+1. In `example/`: run `/adhd:install-design-system-docs-route`. Pick defaults.
+2. `npm run dev`; visit `/-docs`. Verify token catalog + components list.
+3. Click into a component; verify toggles, URL updates, rendered output.
+4. `npm run build`; verify the `/-docs` chunks don't appear in `.next/server/app/`.
+5. `npm start`; visit `/-docs`; verify 404.
+
+---
+
+## Integration with `/adhd:config`
+
+`plugins/adhd/skills/config/SKILL.md` gets a new optional final phase (Phase 6 or after the existing "Report"):
+
+```markdown
+## Phase 6 (optional): Set up the design-system docs route
+
+Use AskUserQuestion:
+
+  "Set up the design-system docs route? It's a live, self-generating
+  documentation page that reads your adhd.config.ts and globals.css.
+  Mini-Storybook for designers; not indexed by search engines."
+
+  Options:
+    - "Yes, install it now" → walk through the install phases inline
+      (see plugins/adhd/skills/install-design-system-docs-route/SKILL.md
+      for the full phase list)
+    - "No, maybe later" → print "Run /adhd:install-design-system-docs-route
+      to set it up later." Exit.
+```
+
+The install phases are documented in the standalone skill; `/adhd:config` references that skill and instructs Claude to follow its phases inline.
+
+---
+
+## Acceptance criteria
+
+1. `/adhd:install-design-system-docs-route` runs against a Next.js 16+ App Router project with an existing `adhd.config.ts`. Writes layout + index page + dynamic `[component]/page` (+ a small client-island file for prop toggles).
+2. Default route URL is `/-docs`; route group default is `(design-system)`; both configurable at install time; neither stored in `adhd.config.ts`.
+3. Default behavior: prod-excluded. `next.config.ts` gets the conditional `pageExtensions` patch; generated files use `.design-system.tsx` extension. User can opt out at install time.
+4. Skill detects existing installs via the marker comment (`design-system-docs-route — auto-generated installer artifact; safe to edit.`) and prompts before overwriting.
+5. Skill detects `next.config.ts` / `.mjs` / `.js` and patches whichever exists; if the file's shape can't be safely patched via `Edit`, prints the exact patch and continues with file installs.
+6. Index page renders sections for colors, spacing, typography, radius, shadows (parsed from `globals.css`'s `@theme`); empty-state strings when a section is missing.
+7. Index page lists components from `adhd.config.ts`'s `components.*` map; each links to `/-docs/<slug>`.
+8. Per-component page dynamically imports the component via parametric template-string import; renders inside an error boundary.
+9. Prop toggles: `<select>` for unions; `<input type="checkbox">` for booleans; text/number inputs for primitives; ReactNode / function / ref / array / object props skipped with an inline note.
+10. Prop toggles update URL search params via a small client island; the server component re-renders with new params. No-JS fallback via `<form>` works.
+11. Per-component page shows the import statement + current JSX invocation as `<pre>` blocks reflecting the current prop state.
+12. Layout has `<meta name="robots" content="noindex, nofollow" />`; `robots.txt` Disallow entry added/created.
+13. Generated files contain zero references to "ADHD." Only `adhd.config.ts` does.
+14. Marker comment is generic: `// design-system-docs-route — auto-generated installer artifact; safe to edit.`
+15. `/adhd:config` gets a new optional final phase: "Set up the design-system docs route?" On yes, walks through the install flow inline. On no, prints the run-it-yourself instruction.
+16. Re-running the skill is idempotent — no duplicate writes, no duplicate `next.config.ts` patches, no duplicate `robots.txt` entries, prompts on existing install.
+17. With prod-exclusion enabled: `next build` produces no chunks for the route; `npm start` returns 404 at the route URL.
+18. With prod-exclusion disabled: route ships with noindex meta still applied.
+19. README's command table includes the new `/adhd:install-design-system-docs-route` row.
+20. Manual smoke test against `example/` passes end-to-end: install → dev server → click through → build → 404 in production.

From c3c5d5bd7a580201ff4d045f27795c69eb230b0f Mon Sep 17 00:00:00 2001
From: Hugh Francis <hughfrancis89@gmail.com>
Date: Mon, 11 May 2026 14:37:56 -0400
Subject: [PATCH 02/79] spec: clarify re-run semantics for
 install-design-system-docs-route
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

User pointed out the spec was internally contradictory about re-run
behavior — said "storage of user customizations on regen is out of
scope" in one place and "in-place updates preserve customizations via
Edit-not-Write" in another. They don't agree, and the Edit-not-Write
claim isn't practical anyway: a meaningfully-improved template won't
have old_string matches that line up with the user's edits, so
wholesale Write is the only realistic mechanism.

The user's intent: re-running the skill should pick up improved
templates over time. As we ship better layouts and add new sections,
they want to re-run and get the latest version without manual file
edits.

Updated:
- "Out of scope" section: replace the contradictory bullet with an
  honest statement of the v1 model — wholesale replace files that
  still bear the marker; marker-removal is the user's opt-out escape.
- Phase 2: add explicit "Update-in-place semantics" subsection with
  a sample prompt showing which files will be replaced vs left alone.
- Phase 2: document the force-overwrite escape (re-add the marker
  comment to a previously-opted-out file to re-include it in updates).
- New acceptance criterion #21: re-running the skill across template
  versions reliably updates marker-bearing files and preserves
  marker-removed ones.

No structural changes. The mechanism (marker comment + Write on
update) was already in the spec; this commit aligns the prose and
makes the re-runnability promise explicit.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 ...1-adhd-install-design-system-docs-route.md | 28 ++++++++++++++++++-
 1 file changed, 27 insertions(+), 1 deletion(-)

diff --git a/docs/superpowers/specs/2026-05-11-adhd-install-design-system-docs-route.md b/docs/superpowers/specs/2026-05-11-adhd-install-design-system-docs-route.md
index be00901..0495a88 100644
--- a/docs/superpowers/specs/2026-05-11-adhd-install-design-system-docs-route.md
+++ b/docs/superpowers/specs/2026-05-11-adhd-install-design-system-docs-route.md
@@ -18,11 +18,16 @@
 
 Also triggered as an optional final phase of `/adhd:config` (the wizard asks "Set up the design-system docs route?" and on `yes` walks through the same install flow inline).
 
+**Re-running the skill** is a first-class flow. As the templates evolve over time (better layouts, new token sections, bug fixes), the user re-runs `/adhd:install-design-system-docs-route` to pick up the improvements. On detect-existing-install:
+- "Update in place" → the skill `Write`s the latest templates over the existing generated files. Idempotent patches (`next.config.ts`, `robots.txt`) are re-applied as no-ops. User customizations to the generated files are replaced.
+- "Abort" → no changes made.
+- The user can opt OUT of future overwrites by deleting the marker comment from a file they want to preserve. The skill refuses to touch any file lacking the marker, except when the user explicitly says "force overwrite" at the prompt.
+
 **Out of scope for v1:**
 - Multi-route documentation (e.g. one URL per token domain). v1 is a single route with index + per-component pages.
 - Image-based component previews (rendering a server-side screenshot). v1 renders the component as live HTML.
 - Live Figma comparison side-by-side. v1 is purely code-side documentation.
-- Storage of user customizations on regen. v1 detects existing installs and prompts before overwriting; in-place updates preserve the layout file's customizations via Edit-not-Write.
+- Three-way merging of user customizations with new template versions. v1's update flow is "wholesale replace, with the marker-removal escape hatch for files the user wants to preserve."
 
 ---
 
@@ -104,6 +109,26 @@ Scan `app/**/page.*tsx` and `app/**/layout.*tsx` for the marker comment. If foun
 | One marker found | Prompt: "An existing install at `<path>`. [Update in place / Move to new location / Abort]." |
 | Multiple markers found | Unusual. Print all locations, prompt: "Pick which to update or move; the others stay as-is." |
 
+**Update-in-place semantics (re-running to pick up improved templates):**
+
+- All files with the marker comment get `Write`-replaced with the latest template content. No attempt to preserve user customizations in those files.
+- Files WITHOUT the marker (user removed it deliberately, or new files in the install dir the user added) are NOT touched.
+- The user is shown a list of files that will be replaced before confirming. Sample prompt:
+  ```
+  Update in place at app/(design-system)/-docs/?
+  These files will be replaced with the latest templates:
+    • layout.design-system.tsx
+    • page.design-system.tsx
+    • [component]/page.design-system.tsx
+    • PropToggle.design-system.tsx
+  These files have the marker comment removed and will be left alone:
+    (none)
+  Continue? [Y/n]
+  ```
+- Idempotent patches (`next.config.ts`'s `pageExtensions`, `robots.txt` Disallow) are re-applied; if already at the expected state, they're no-ops.
+
+**Force-overwrite escape:** if the user wants to push a template update onto a file they've previously opted out of (marker removed), they can re-add the marker comment to the top of the file before re-running the skill. The skill will then treat it as an update target.
+
 ### Phase 3 — Ask installation choices
 
 Use `AskUserQuestion` for each (with defaults filled in from the existing install if updating):
@@ -475,3 +500,4 @@ The install phases are documented in the standalone skill; `/adhd:config` refere
 18. With prod-exclusion disabled: route ships with noindex meta still applied.
 19. README's command table includes the new `/adhd:install-design-system-docs-route` row.
 20. Manual smoke test against `example/` passes end-to-end: install → dev server → click through → build → 404 in production.
+21. Re-running the skill against an existing install reliably updates files that still bear the marker comment to the latest template version, while leaving files where the marker was deliberately removed untouched. Verified by: install at template v1 → ship a template v2 (different layout content) → re-run skill → confirm marker-bearing files now contain v2 content and marker-removed files contain their preserved pre-v2 state.

From 51b72225f1f8f3330f842d2208b305f5ee38bae0 Mon Sep 17 00:00:00 2001
From: Hugh Francis <hughfrancis89@gmail.com>
Date: Mon, 11 May 2026 14:43:53 -0400
Subject: [PATCH 03/79] Add implementation plan for
 /adhd:install-design-system-docs-route
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

13 tasks decomposing the spec into TDD steps:
- Task 1: scaffold lib + cli stub + CI step + module README
- Task 2: token-parser.js — extract @theme tokens from globals.css
- Task 3: prop-parser.js — extract component prop interface
- Task 4: slug.js — component path → URL slug + collision disambiguation
- Task 5: next-config-patcher.js — idempotent conditional pageExtensions patch
- Task 6: robots-patcher.js — idempotent Disallow entry
- Task 7: templates.js — layout / page / [component]/page / PropToggle as string consts
- Task 8: route-installer.js — write files at target path; marker-comment detection
- Task 9: cli.js — wire all subcommands
- Task 10: SKILL.md — 9-phase orchestrator
- Task 11: /adhd:config integration (optional final phase)
- Task 12: README + marketplace updates
- Task 13: smoke + PR

Acceptance criteria 1-21 mapped to specific tasks in the self-review.
~60 new unit tests planned. All TDD-style with concrete code blocks
per step.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 ...1-adhd-install-design-system-docs-route.md | 2349 +++++++++++++++++
 1 file changed, 2349 insertions(+)
 create mode 100644 docs/superpowers/plans/2026-05-11-adhd-install-design-system-docs-route.md

diff --git a/docs/superpowers/plans/2026-05-11-adhd-install-design-system-docs-route.md b/docs/superpowers/plans/2026-05-11-adhd-install-design-system-docs-route.md
new file mode 100644
index 0000000..c1d08e8
--- /dev/null
+++ b/docs/superpowers/plans/2026-05-11-adhd-install-design-system-docs-route.md
@@ -0,0 +1,2349 @@
+# /adhd:install-design-system-docs-route Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Implement `/adhd:install-design-system-docs-route` — a one-shot installer that drops a live, self-generating design-system documentation route into a Next.js consumer app.
+
+**Architecture:** Zero-deps Node library at `plugins/adhd/lib/install-design-system-docs-route/`, mirroring the shape of `lib/pull-component/`. Single skill at `plugins/adhd/skills/install-design-system-docs-route/SKILL.md` orchestrating a 9-phase install flow. The installed files are Next.js App Router server components that read `adhd.config.ts` and `globals.css` at request time — no regen needed. Re-running the installer is first-class: marker-comment detection drives wholesale `Write`-replacement of marker-bearing files, leaving marker-removed files alone (the user's opt-out).
+
+**Tech Stack:** Node 20 (lib runs zero-deps), regex-based parsers (matching the established `lib/push-component/parse-component.js` style), `node --test` runner, Next.js App Router file conventions in the consumer app.
+
+---
+
+## File structure (lock-in)
+
+**New library — `plugins/adhd/lib/install-design-system-docs-route/`:**
+
+| File | Responsibility |
+|---|---|
+| `token-parser.js` | Parse `globals.css` `@theme` block → `{ colors, spacing, typography, radius, shadows, unknown }` |
+| `prop-parser.js` | Parse a component source's `<Name>Props` interface → `{ propName: { type, values?, optional } }` |
+| `slug.js` | Component path → URL-safe slug; collision detection across the components map |
+| `next-config-patcher.js` | Idempotent patch of `next.config.{ts,mjs,js}` to add conditional `pageExtensions` |
+| `robots-patcher.js` | Idempotent patch of `public/robots.txt` (Disallow entry; creates file if missing) |
+| `route-installer.js` | Orchestrator: writes the 4 generated files at the right paths with the right extensions |
+| `templates.js` | Template strings for `layout`, `page` (index), `[component]/page`, `PropToggle`. Exports plain-string content + the marker-comment constant. |
+| `cli.js` | Subcommand surface: `parse-tokens`, `parse-props`, `slug`, `patch-next-config`, `patch-robots`, `detect-install`, `install` |
+| `README.md` | One-paragraph module readme |
+| `__tests__/token-parser.test.js` | Unit tests |
+| `__tests__/prop-parser.test.js` | Unit tests |
+| `__tests__/slug.test.js` | Unit tests |
+| `__tests__/next-config-patcher.test.js` | Unit tests |
+| `__tests__/robots-patcher.test.js` | Unit tests |
+| `__tests__/route-installer.test.js` | Unit + golden-file tests |
+| `__tests__/cli.test.js` | CLI surface tests |
+| `__fixtures__/globals.css` | Sample Tailwind v4 globals for token-parser tests |
+| `__fixtures__/avatar.tsx` | Sample component source for prop-parser tests |
+
+**New skill — `plugins/adhd/skills/install-design-system-docs-route/SKILL.md`:** the 9-phase orchestrator.
+
+**Modified files:**
+- `plugins/adhd/skills/config/SKILL.md` — append optional final phase that invokes the install flow inline
+- `.claude-plugin/marketplace.json` — bump description
+- `README.md` — add command table row + "Install design system docs route" subsection
+- `.github/workflows/ci.yml` — add test step
+
+---
+
+## Task 1: Scaffold lib, CI step, module README, cli stub
+
+**Files:**
+- Create: `plugins/adhd/lib/install-design-system-docs-route/cli.js`
+- Create: `plugins/adhd/lib/install-design-system-docs-route/README.md`
+- Create: `plugins/adhd/lib/install-design-system-docs-route/__tests__/cli.test.js`
+- Modify: `.github/workflows/ci.yml`
+
+- [ ] **Step 1: Write failing test for cli `--help`**
+
+`plugins/adhd/lib/install-design-system-docs-route/__tests__/cli.test.js`:
+
+```javascript
+'use strict';
+
+const test = require('node:test');
+const assert = require('node:assert/strict');
+const { spawnSync } = require('node:child_process');
+const path = require('node:path');
+
+const CLI = path.resolve(__dirname, '..', 'cli.js');
+
+test('cli with --help prints subcommand usage and exits 0', () => {
+  const r = spawnSync('node', [CLI, '--help'], { encoding: 'utf8' });
+  assert.equal(r.status, 0);
+  assert.match(r.stdout, /Usage:/);
+  assert.match(r.stdout, /parse-tokens/);
+  assert.match(r.stdout, /parse-props/);
+  assert.match(r.stdout, /slug/);
+  assert.match(r.stdout, /patch-next-config/);
+  assert.match(r.stdout, /patch-robots/);
+  assert.match(r.stdout, /detect-install/);
+  assert.match(r.stdout, /install/);
+});
+
+test('cli with no args exits 2', () => {
+  assert.equal(spawnSync('node', [CLI], { encoding: 'utf8' }).status, 2);
+});
+
+test('cli with unknown subcommand exits 2', () => {
+  assert.equal(spawnSync('node', [CLI, 'unknown'], { encoding: 'utf8' }).status, 2);
+});
+```
+
+- [ ] **Step 2: Verify tests fail**
+
+Run: `node --test plugins/adhd/lib/install-design-system-docs-route/__tests__/cli.test.js`
+Expected: FAIL — `cli.js` does not exist.
+
+- [ ] **Step 3: Implement cli stub**
+
+`plugins/adhd/lib/install-design-system-docs-route/cli.js`:
+
+```javascript
+#!/usr/bin/env node
+'use strict';
+
+function parseArgs(argv) {
+  const args = { _: [] };
+  for (let i = 2; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '--help' || a === '-h') { args.help = true; continue; }
+    if (a.startsWith('--')) { args[a.slice(2)] = argv[++i]; }
+    else { args._.push(a); }
+  }
+  return args;
+}
+
+function printUsage() {
+  console.log(`Usage:
+  cli.js parse-tokens --css <path> --output <json>
+  cli.js parse-props --source <component.tsx> --output <json>
+  cli.js slug --paths <comma-separated> --output <json>
+  cli.js patch-next-config --config <path> --route-url <url>
+  cli.js patch-robots --robots <path> --route-url <url>
+  cli.js detect-install --app-dir <path>
+  cli.js install --config <choices.json>`);
+}
+
+function main() {
+  const args = parseArgs(process.argv);
+  if (args.help) { printUsage(); process.exit(0); }
+  if (args._.length === 0) { printUsage(); process.exit(2); }
+  const cmd = args._[0];
+  // Subcommands wired in later tasks. Reject unknown to keep behavior strict.
+  console.error('Unknown subcommand: ' + cmd);
+  process.exit(2);
+}
+
+main();
+```
+
+- [ ] **Step 4: Verify cli tests pass**
+
+Run: `node --test plugins/adhd/lib/install-design-system-docs-route/__tests__/cli.test.js`
+Expected: 3 tests PASS.
+
+- [ ] **Step 5: Add module README**
+
+`plugins/adhd/lib/install-design-system-docs-route/README.md`:
+
+```markdown
+# lib/install-design-system-docs-route
+
+Deterministic helpers for `/adhd:install-design-system-docs-route`. The
+skill (at `plugins/adhd/skills/install-design-system-docs-route/SKILL.md`)
+is the orchestrator; this library is the testable engine.
+
+Modules:
+- `token-parser.js` — extract design-system tokens from a globals.css `@theme` block
+- `prop-parser.js` — extract a component's prop interface
+- `slug.js` — component path → URL slug
+- `next-config-patcher.js` — idempotent patch of next.config.{ts,mjs,js}
+- `robots-patcher.js` — idempotent patch of public/robots.txt
+- `route-installer.js` — write the 4 generated files at the target path
+- `templates.js` — page template strings
+- `cli.js` — orchestrator surface invoked by SKILL.md
+
+See `docs/superpowers/specs/2026-05-11-adhd-install-design-system-docs-route.md`
+for the authoritative spec.
+```
+
+- [ ] **Step 6: Add CI step**
+
+Modify `.github/workflows/ci.yml`. In the `lib-tests` job, after the existing `pull-component` test step:
+
+```yaml
+      - name: Run install-design-system-docs-route tests
+        run: node --test plugins/adhd/lib/install-design-system-docs-route/__tests__/
+```
+
+- [ ] **Step 7: Run all tests, verify green**
+
+Run: `node --test plugins/adhd/lib/install-design-system-docs-route/__tests__/`
+Expected: 3 cli tests PASS.
+
+- [ ] **Step 8: Commit**
+
+```bash
+git add plugins/adhd/lib/install-design-system-docs-route .github/workflows/ci.yml
+git commit -m "Scaffold lib/install-design-system-docs-route with cli stub"
+```
+
+---
+
+## Task 2: token-parser.js — extract design tokens from globals.css
+
+**Files:**
+- Create: `plugins/adhd/lib/install-design-system-docs-route/token-parser.js`
+- Create: `plugins/adhd/lib/install-design-system-docs-route/__tests__/token-parser.test.js`
+- Create: `plugins/adhd/lib/install-design-system-docs-route/__fixtures__/globals.css`
+
+- [ ] **Step 1: Add the fixture file**
+
+`plugins/adhd/lib/install-design-system-docs-route/__fixtures__/globals.css`:
+
+```css
+@import "tailwindcss";
+
+@theme {
+  --color-zinc-50: oklch(0.985 0 0);
+  --color-zinc-900: oklch(0.21 0.034 264.665);
+  --color-brand-500: #5e3aee;
+
+  --spacing: 0.25rem;
+
+  --text-xs: 0.75rem;
+  --text-xs--line-height: 1rem;
+  --text-base: 1rem;
+  --text-base--line-height: 1.5rem;
+
+  --radius-sm: 0.25rem;
+  --radius-lg: 0.5rem;
+
+  --shadow-sm: 0 1px 2px 0 rgb(0 0 0 / 0.05);
+  --shadow-md: 0 4px 6px -1px rgb(0 0 0 / 0.1);
+
+  --font-sans: "Inter", system-ui, sans-serif;
+}
+```
+
+- [ ] **Step 2: Write failing tests**
+
+`plugins/adhd/lib/install-design-system-docs-route/__tests__/token-parser.test.js`:
+
+```javascript
+'use strict';
+
+const test = require('node:test');
+const assert = require('node:assert/strict');
+const fs = require('node:fs');
+const path = require('node:path');
+const { parseTokens } = require('../token-parser');
+
+const CSS = fs.readFileSync(
+  path.resolve(__dirname, '..', '__fixtures__', 'globals.css'),
+  'utf8',
+);
+
+test('extracts color tokens', () => {
+  const t = parseTokens(CSS);
+  assert.deepEqual(
+    t.colors.find(c => c.name === 'zinc-50'),
+    { name: 'zinc-50', value: 'oklch(0.985 0 0)' },
+  );
+  assert.deepEqual(
+    t.colors.find(c => c.name === 'brand-500'),
+    { name: 'brand-500', value: '#5e3aee' },
+  );
+});
+
+test('extracts the spacing multiplier', () => {
+  const t = parseTokens(CSS);
+  assert.equal(t.spacing.multiplier, '0.25rem');
+});
+
+test('extracts typography sizes with optional line-heights', () => {
+  const t = parseTokens(CSS);
+  assert.deepEqual(
+    t.typography.find(x => x.name === 'xs'),
+    { name: 'xs', size: '0.75rem', lineHeight: '1rem' },
+  );
+  assert.deepEqual(
+    t.typography.find(x => x.name === 'base'),
+    { name: 'base', size: '1rem', lineHeight: '1.5rem' },
+  );
+});
+
+test('extracts radius tokens', () => {
+  const t = parseTokens(CSS);
+  assert.deepEqual(
+    t.radius.find(r => r.name === 'sm'),
+    { name: 'sm', value: '0.25rem' },
+  );
+});
+
+test('extracts shadow tokens', () => {
+  const t = parseTokens(CSS);
+  assert.deepEqual(
+    t.shadows.find(s => s.name === 'sm'),
+    { name: 'sm', value: '0 1px 2px 0 rgb(0 0 0 / 0.05)' },
+  );
+});
+
+test('puts unrecognized @theme vars in `unknown`', () => {
+  const t = parseTokens(CSS);
+  assert.ok(t.unknown.find(u => u.name === '--font-sans'));
+});
+
+test('returns empty domains when no @theme block exists', () => {
+  const t = parseTokens('body { color: red; }');
+  assert.deepEqual(t.colors, []);
+  assert.deepEqual(t.typography, []);
+  assert.deepEqual(t.radius, []);
+  assert.deepEqual(t.shadows, []);
+  assert.equal(t.spacing.multiplier, null);
+});
+
+test('handles multiple @theme blocks (merge)', () => {
+  const css = `
+@theme { --color-a-100: #fff; }
+@theme { --color-b-200: #000; }
+`;
+  const t = parseTokens(css);
+  assert.equal(t.colors.length, 2);
+});
+```
+
+- [ ] **Step 3: Verify tests fail**
+
+Run: `node --test plugins/adhd/lib/install-design-system-docs-route/__tests__/token-parser.test.js`
+Expected: FAIL — module not found.
+
+- [ ] **Step 4: Implement token-parser.js**
+
+`plugins/adhd/lib/install-design-system-docs-route/token-parser.js`:
+
+```javascript
+'use strict';
+
+// Extracts a single @theme block's body, or null. Brace-balanced across nested objects.
+function extractAllThemeBodies(css) {
+  const bodies = [];
+  let i = 0;
+  while (i < css.length) {
+    const idx = css.indexOf('@theme', i);
+    if (idx === -1) break;
+    // Skip whitespace + optional modifiers like @theme inline
+    let j = idx + '@theme'.length;
+    while (j < css.length && css[j] !== '{' && css[j] !== ';') j++;
+    if (css[j] !== '{') { i = j + 1; continue; }
+    // Brace-balanced scan
+    let depth = 1;
+    let k = j + 1;
+    while (k < css.length && depth > 0) {
+      if (css[k] === '{') depth++;
+      else if (css[k] === '}') depth--;
+      if (depth > 0) k++;
+    }
+    bodies.push(css.slice(j + 1, k));
+    i = k + 1;
+  }
+  return bodies;
+}
+
+const DECL_RE = /--([a-zA-Z0-9_-]+)\s*:\s*([^;]+);/g;
+
+function classify(name) {
+  if (name.startsWith('color-')) return { domain: 'colors', leaf: name.slice('color-'.length) };
+  if (name === 'spacing') return { domain: 'spacing', leaf: null };
+  if (name.startsWith('text-')) {
+    // text-xs or text-xs--line-height
+    const rest = name.slice('text-'.length);
+    const lhIdx = rest.indexOf('--line-height');
+    if (lhIdx >= 0) return { domain: 'typography', leaf: rest.slice(0, lhIdx), kind: 'lineHeight' };
+    return { domain: 'typography', leaf: rest, kind: 'size' };
+  }
+  if (name.startsWith('radius-')) return { domain: 'radius', leaf: name.slice('radius-'.length) };
+  if (name.startsWith('shadow-')) return { domain: 'shadows', leaf: name.slice('shadow-'.length) };
+  return { domain: 'unknown' };
+}
+
+function parseTokens(globalsCss) {
+  const out = {
+    colors: [],
+    spacing: { multiplier: null },
+    typography: [], // [{ name, size, lineHeight }]
+    radius: [],
+    shadows: [],
+    unknown: [],
+  };
+  const typographyByName = new Map();
+
+  for (const body of extractAllThemeBodies(globalsCss)) {
+    DECL_RE.lastIndex = 0;
+    let m;
+    while ((m = DECL_RE.exec(body)) !== null) {
+      const name = m[1];
+      const value = m[2].trim();
+      const cls = classify(name);
+      if (cls.domain === 'colors') {
+        out.colors.push({ name: cls.leaf, value });
+      } else if (cls.domain === 'spacing') {
+        out.spacing.multiplier = value;
+      } else if (cls.domain === 'typography') {
+        let row = typographyByName.get(cls.leaf);
+        if (!row) {
+          row = { name: cls.leaf, size: null, lineHeight: null };
+          typographyByName.set(cls.leaf, row);
+          out.typography.push(row);
+        }
+        if (cls.kind === 'lineHeight') row.lineHeight = value;
+        else row.size = value;
+      } else if (cls.domain === 'radius') {
+        out.radius.push({ name: cls.leaf, value });
+      } else if (cls.domain === 'shadows') {
+        out.shadows.push({ name: cls.leaf, value });
+      } else {
+        out.unknown.push({ name: '--' + name, value });
+      }
+    }
+  }
+
+  return out;
+}
+
+module.exports = { parseTokens };
+```
+
+- [ ] **Step 5: Verify tests pass**
+
+Run: `node --test plugins/adhd/lib/install-design-system-docs-route/__tests__/token-parser.test.js`
+Expected: 8 tests PASS.
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add plugins/adhd/lib/install-design-system-docs-route/token-parser.js \
+        plugins/adhd/lib/install-design-system-docs-route/__tests__/token-parser.test.js \
+        plugins/adhd/lib/install-design-system-docs-route/__fixtures__/globals.css
+git commit -m "token-parser: extract colors/spacing/typography/radius/shadows from globals.css @theme"
+```
+
+---
+
+## Task 3: prop-parser.js — extract component prop interfaces
+
+**Files:**
+- Create: `plugins/adhd/lib/install-design-system-docs-route/prop-parser.js`
+- Create: `plugins/adhd/lib/install-design-system-docs-route/__tests__/prop-parser.test.js`
+- Create: `plugins/adhd/lib/install-design-system-docs-route/__fixtures__/avatar.tsx`
+
+- [ ] **Step 1: Add the fixture file**
+
+`plugins/adhd/lib/install-design-system-docs-route/__fixtures__/avatar.tsx`:
+
+```tsx
+export type AvatarSize = "xs" | "sm" | "md" | "lg" | "xl";
+export type AvatarShape = "circle" | "square";
+
+export interface AvatarProps {
+  name: string;
+  src?: string;
+  size?: AvatarSize;
+  shape?: AvatarShape;
+  status?: "online" | "away" | "offline";
+  count?: number;
+  hidden?: boolean;
+  onClick?: (e: React.MouseEvent) => void;
+  children?: React.ReactNode;
+}
+
+export function Avatar({ name, size = "md" }: AvatarProps) {
+  return <span>{name}</span>;
+}
+```
+
+- [ ] **Step 2: Write failing tests**
+
+`plugins/adhd/lib/install-design-system-docs-route/__tests__/prop-parser.test.js`:
+
+```javascript
+'use strict';
+
+const test = require('node:test');
+const assert = require('node:assert/strict');
+const fs = require('node:fs');
+const path = require('node:path');
+const { parseProps } = require('../prop-parser');
+
+const SOURCE = fs.readFileSync(
+  path.resolve(__dirname, '..', '__fixtures__', 'avatar.tsx'),
+  'utf8',
+);
+
+test('returns the component name', () => {
+  const r = parseProps(SOURCE);
+  assert.equal(r.componentName, 'Avatar');
+});
+
+test('captures string props', () => {
+  const r = parseProps(SOURCE);
+  assert.deepEqual(r.props.name, { type: 'string', optional: false });
+  assert.deepEqual(r.props.src, { type: 'string', optional: true });
+});
+
+test('captures number and boolean props', () => {
+  const r = parseProps(SOURCE);
+  assert.deepEqual(r.props.count, { type: 'number', optional: true });
+  assert.deepEqual(r.props.hidden, { type: 'boolean', optional: true });
+});
+
+test('captures named-union references with their values', () => {
+  const r = parseProps(SOURCE);
+  assert.deepEqual(r.props.size, {
+    type: 'union', unionName: 'AvatarSize', values: ['xs', 'sm', 'md', 'lg', 'xl'], optional: true,
+  });
+  assert.deepEqual(r.props.shape, {
+    type: 'union', unionName: 'AvatarShape', values: ['circle', 'square'], optional: true,
+  });
+});
+
+test('captures inline literal unions', () => {
+  const r = parseProps(SOURCE);
+  assert.deepEqual(r.props.status, {
+    type: 'union', values: ['online', 'away', 'offline'], optional: true,
+  });
+});
+
+test('marks function props as `function` (toggle-skipped)', () => {
+  const r = parseProps(SOURCE);
+  assert.equal(r.props.onClick.type, 'function');
+});
+
+test('marks ReactNode props as `reactnode` (toggle-skipped)', () => {
+  const r = parseProps(SOURCE);
+  assert.equal(r.props.children.type, 'reactnode');
+});
+
+test('returns componentName=null when no exported function found', () => {
+  const r = parseProps('export const x = 42;');
+  assert.equal(r.componentName, null);
+  assert.deepEqual(r.props, {});
+});
+```
+
+- [ ] **Step 3: Verify tests fail**
+
+Run: `node --test plugins/adhd/lib/install-design-system-docs-route/__tests__/prop-parser.test.js`
+Expected: FAIL — module not found.
+
+- [ ] **Step 4: Implement prop-parser.js**
+
+`plugins/adhd/lib/install-design-system-docs-route/prop-parser.js`:
+
+```javascript
+'use strict';
+
+const TYPE_ALIAS_RE = /export\s+type\s+([A-Z][A-Za-z0-9]*)\s*=\s*([^;]+);/g;
+const INTERFACE_RE = /(?:export\s+)?interface\s+([A-Z][A-Za-z0-9]*Props)\s*\{([\s\S]*?)\}/;
+const TYPE_PROPS_RE = /(?:export\s+)?type\s+([A-Z][A-Za-z0-9]*Props)\s*=\s*\{([\s\S]*?)\}/;
+const EXPORT_FN_RE = /export\s+(?:default\s+)?function\s+([A-Z][A-Za-z0-9]*)\s*\(/;
+const PROP_LINE_RE = /^\s*([a-zA-Z_$][a-zA-Z0-9_$]*)(\?)?\s*:\s*([^;,]+)[;,]?\s*$/;
+
+function parseLiteralUnion(typeText) {
+  const trimmed = typeText.trim();
+  if (!/^"[^"]*"(\s*\|\s*"[^"]*")*$/.test(trimmed)) return null;
+  return trimmed.split('|').map(s => {
+    const m = /"([^"]*)"/.exec(s.trim());
+    return m ? m[1] : null;
+  }).filter(Boolean);
+}
+
+function classify(typeText, knownUnions) {
+  const t = typeText.trim();
+  const inline = parseLiteralUnion(t);
+  if (inline) return { type: 'union', values: inline };
+  if (knownUnions[t]) return { type: 'union', unionName: t, values: knownUnions[t] };
+  if (/^\([^)]*\)\s*=>/.test(t)) return { type: 'function' };
+  if (/^(?:React\.)?Ref(?:Object|Callback|MutableRefObject)?</.test(t)) return { type: 'ref' };
+  if (/^(?:React\.)?(?:ReactNode|ReactElement|ReactChild)$/.test(t)) return { type: 'reactnode' };
+  if (/^JSX\.Element$/.test(t)) return { type: 'reactnode' };
+  if (/^(?:React\.)?ReactElement<.*>$/.test(t)) return { type: 'reactnode' };
+  if (t === 'string') return { type: 'string' };
+  if (t === 'number') return { type: 'number' };
+  if (t === 'boolean') return { type: 'boolean' };
+  if (/\[\]$/.test(t) || /^Array</.test(t) || /^ReadonlyArray</.test(t)) return { type: 'array' };
+  if (/^\{.*\}$/.test(t)) return { type: 'object' };
+  return { type: 'unknown' };
+}
+
+function parseProps(source) {
+  // Pass 1: collect known unions
+  const knownUnions = {};
+  TYPE_ALIAS_RE.lastIndex = 0;
+  let m;
+  while ((m = TYPE_ALIAS_RE.exec(source)) !== null) {
+    const name = m[1];
+    const body = m[2].trim();
+    const lit = parseLiteralUnion(body);
+    if (lit) knownUnions[name] = lit;
+  }
+
+  // Pass 2: locate component name
+  const fnMatch = EXPORT_FN_RE.exec(source);
+  const componentName = fnMatch ? fnMatch[1] : null;
+
+  // Pass 3: locate props block
+  let propsBody = null;
+  const ifaceMatch = INTERFACE_RE.exec(source);
+  const typeMatch = TYPE_PROPS_RE.exec(source);
+  if (ifaceMatch) propsBody = ifaceMatch[2];
+  else if (typeMatch) propsBody = typeMatch[2];
+
+  const props = {};
+  if (propsBody) {
+    for (const rawLine of propsBody.split('\n')) {
+      const line = rawLine.replace(/\/\/.*$/, '');
+      const pm = PROP_LINE_RE.exec(line);
+      if (!pm) continue;
+      const [, propName, optionalMark, typeText] = pm;
+      const cls = classify(typeText, knownUnions);
+      props[propName] = { ...cls, optional: !!optionalMark };
+    }
+  }
+
+  return { componentName, props, unions: knownUnions };
+}
+
+module.exports = { parseProps };
+```
+
+- [ ] **Step 5: Verify tests pass**
+
+Run: `node --test plugins/adhd/lib/install-design-system-docs-route/__tests__/prop-parser.test.js`
+Expected: 8 tests PASS.
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add plugins/adhd/lib/install-design-system-docs-route/prop-parser.js \
+        plugins/adhd/lib/install-design-system-docs-route/__tests__/prop-parser.test.js \
+        plugins/adhd/lib/install-design-system-docs-route/__fixtures__/avatar.tsx
+git commit -m "prop-parser: extract component prop interface (unions, primitives, optional flag)"
+```
+
+---
+
+## Task 4: slug.js — component path → URL slug + collision detection
+
+**Files:**
+- Create: `plugins/adhd/lib/install-design-system-docs-route/slug.js`
+- Create: `plugins/adhd/lib/install-design-system-docs-route/__tests__/slug.test.js`
+
+- [ ] **Step 1: Write failing tests**
+
+`plugins/adhd/lib/install-design-system-docs-route/__tests__/slug.test.js`:
+
+```javascript
+'use strict';
+
+const test = require('node:test');
+const assert = require('node:assert/strict');
+const { slugFor, slugMap } = require('../slug');
+
+test('slugs a simple component path', () => {
+  assert.equal(slugFor('app/components/avatar/index.tsx'), 'avatar');
+});
+
+test('preserves hyphens', () => {
+  assert.equal(slugFor('app/components/avatar-group/index.tsx'), 'avatar-group');
+});
+
+test('handles files without /index.tsx', () => {
+  assert.equal(slugFor('app/components/Logo.tsx'), 'logo');
+});
+
+test('lowercases', () => {
+  assert.equal(slugFor('app/components/AvatarGroup/index.tsx'), 'avatargroup');
+});
+
+test('slugMap returns { path: slug } for unique paths', () => {
+  const paths = [
+    'app/components/avatar/index.tsx',
+    'app/components/avatar-group/index.tsx',
+  ];
+  assert.deepEqual(slugMap(paths), {
+    'app/components/avatar/index.tsx': 'avatar',
+    'app/components/avatar-group/index.tsx': 'avatar-group',
+  });
+});
+
+test('slugMap disambiguates collisions by prepending parent dir', () => {
+  const paths = [
+    'app/components/avatar/index.tsx',
+    'app/design-system/avatar/index.tsx',
+  ];
+  const m = slugMap(paths);
+  assert.equal(new Set(Object.values(m)).size, 2, 'slugs must be unique');
+  // Both contain "avatar"; we expect e.g. "components-avatar" and "design-system-avatar"
+  assert.ok(Object.values(m).every(s => s.includes('avatar')));
+});
+```
+
+- [ ] **Step 2: Verify tests fail**
+
+Run: `node --test plugins/adhd/lib/install-design-system-docs-route/__tests__/slug.test.js`
+Expected: FAIL — module not found.
+
+- [ ] **Step 3: Implement slug.js**
+
+`plugins/adhd/lib/install-design-system-docs-route/slug.js`:
+
+```javascript
+'use strict';
+
+function baseSlug(componentPath) {
+  // Strip /index.tsx or .tsx; take the last meaningful segment.
+  let p = componentPath.replace(/\\/g, '/').replace(/\.tsx?$/, '').replace(/\/index$/, '');
+  const segs = p.split('/').filter(Boolean);
+  return (segs[segs.length - 1] || '').toLowerCase();
+}
+
+function slugFor(componentPath) {
+  return baseSlug(componentPath);
+}
+
+function slugMap(paths) {
+  // Pass 1: tentative slugs
+  const tentative = paths.map(p => ({ path: p, slug: baseSlug(p) }));
+  // Pass 2: find collisions
+  const counts = {};
+  for (const t of tentative) counts[t.slug] = (counts[t.slug] || 0) + 1;
+  // Pass 3: resolve collisions by prepending the parent dir
+  for (const t of tentative) {
+    if (counts[t.slug] === 1) continue;
+    const segs = t.path.replace(/\\/g, '/').replace(/\.tsx?$/, '').replace(/\/index$/, '').split('/').filter(Boolean);
+    // Prepend one level of parent until unique
+    let depth = 2;
+    while (depth <= segs.length) {
+      const candidate = segs.slice(segs.length - depth).join('-').toLowerCase();
+      const colliders = tentative.filter(x => x !== t && x.slug === candidate).length;
+      if (colliders === 0) {
+        t.slug = candidate;
+        break;
+      }
+      depth++;
+    }
+  }
+  const out = {};
+  for (const t of tentative) out[t.path] = t.slug;
+  return out;
+}
+
+module.exports = { slugFor, slugMap };
+```
+
+- [ ] **Step 4: Verify tests pass**
+
+Run: `node --test plugins/adhd/lib/install-design-system-docs-route/__tests__/slug.test.js`
+Expected: 6 tests PASS.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add plugins/adhd/lib/install-design-system-docs-route/slug.js \
+        plugins/adhd/lib/install-design-system-docs-route/__tests__/slug.test.js
+git commit -m "slug: component path → URL slug + collision disambiguation"
+```
+
+---
+
+## Task 5: next-config-patcher.js — idempotent pageExtensions patch
+
+**Files:**
+- Create: `plugins/adhd/lib/install-design-system-docs-route/next-config-patcher.js`
+- Create: `plugins/adhd/lib/install-design-system-docs-route/__tests__/next-config-patcher.test.js`
+
+- [ ] **Step 1: Write failing tests**
+
+`plugins/adhd/lib/install-design-system-docs-route/__tests__/next-config-patcher.test.js`:
+
+```javascript
+'use strict';
+
+const test = require('node:test');
+const assert = require('node:assert/strict');
+const { patchNextConfig, isPatched } = require('../next-config-patcher');
+
+const TS_MINIMAL = `import type { NextConfig } from "next";
+
+const nextConfig: NextConfig = {
+  images: {
+    remotePatterns: [{ protocol: "https", hostname: "i.pravatar.cc" }],
+  },
+};
+
+export default nextConfig;
+`;
+
+const TS_ALREADY_PATCHED = `import type { NextConfig } from "next";
+
+const nextConfig: NextConfig = {
+  pageExtensions: process.env.NODE_ENV === 'production'
+    ? ['ts', 'tsx']
+    : ['ts', 'tsx', 'design-system.ts', 'design-system.tsx'],
+  images: {
+    remotePatterns: [{ protocol: "https", hostname: "i.pravatar.cc" }],
+  },
+};
+
+export default nextConfig;
+`;
+
+const TS_WITH_DIFFERENT_PAGE_EXTENSIONS = `import type { NextConfig } from "next";
+
+const nextConfig: NextConfig = {
+  pageExtensions: ['mdx', 'ts', 'tsx'],
+};
+
+export default nextConfig;
+`;
+
+test('patches a minimal next.config.ts with the conditional pageExtensions block', () => {
+  const out = patchNextConfig(TS_MINIMAL);
+  assert.match(out, /pageExtensions:\s*process\.env\.NODE_ENV/);
+  assert.match(out, /'design-system\.tsx'/);
+  // Existing config preserved
+  assert.match(out, /images:/);
+  assert.match(out, /remotePatterns:/);
+});
+
+test('isPatched returns true after patching', () => {
+  const out = patchNextConfig(TS_MINIMAL);
+  assert.equal(isPatched(out), true);
+});
+
+test('patchNextConfig is idempotent when already patched', () => {
+  const out = patchNextConfig(TS_ALREADY_PATCHED);
+  assert.equal(out, TS_ALREADY_PATCHED);
+});
+
+test('isPatched returns false on an unpatched file', () => {
+  assert.equal(isPatched(TS_MINIMAL), false);
+});
+
+test('patchNextConfig refuses to silently overwrite an existing different pageExtensions; returns { conflict: true }', () => {
+  const r = patchNextConfig(TS_WITH_DIFFERENT_PAGE_EXTENSIONS, { detectOnly: true });
+  assert.equal(r.conflict, true);
+  assert.match(r.existing, /pageExtensions:\s*\['mdx'/);
+});
+```
+
+- [ ] **Step 2: Verify tests fail**
+
+Run: `node --test plugins/adhd/lib/install-design-system-docs-route/__tests__/next-config-patcher.test.js`
+Expected: FAIL — module not found.
+
+- [ ] **Step 3: Implement next-config-patcher.js**
+
+`plugins/adhd/lib/install-design-system-docs-route/next-config-patcher.js`:
+
+```javascript
+'use strict';
+
+// Detection: look for the sentinel "design-system.tsx" pageExtension entry
+// inside the conditional. This is the unique fingerprint of OUR patch.
+const PATCHED_SENTINEL = /pageExtensions:\s*process\.env\.NODE_ENV\s*===\s*['"]production['"][\s\S]*?'design-system\.tsx'/;
+
+// Detection: any other pageExtensions definition.
+const EXISTING_PAGE_EXTENSIONS_RE = /pageExtensions:\s*\[/;
+
+const PATCH_BLOCK = `  pageExtensions: process.env.NODE_ENV === 'production'
+    ? ['ts', 'tsx']
+    : ['ts', 'tsx', 'design-system.ts', 'design-system.tsx'],`;
+
+function isPatched(source) {
+  return PATCHED_SENTINEL.test(source);
+}
+
+function findConfigObjectStart(source) {
+  // Look for either:
+  //   const nextConfig: NextConfig = {
+  //   const nextConfig = {
+  //   export default {
+  //   module.exports = {
+  const patterns = [
+    /const\s+nextConfig(?:\s*:\s*[^=]+)?\s*=\s*\{/,
+    /export\s+default\s*\{/,
+    /module\.exports\s*=\s*\{/,
+  ];
+  for (const re of patterns) {
+    const m = re.exec(source);
+    if (m) return m.index + m[0].length; // position after the opening `{`
+  }
+  return -1;
+}
+
+function patchNextConfig(source, opts = {}) {
+  if (isPatched(source)) return source;
+
+  // Detect existing different pageExtensions
+  if (EXISTING_PAGE_EXTENSIONS_RE.test(source)) {
+    if (opts.detectOnly) {
+      const existing = /pageExtensions:[^,\n]+,?/.exec(source)[0];
+      return { conflict: true, existing };
+    }
+    // Caller hasn't checked; we still refuse to silently merge.
+    throw new Error('next.config already sets pageExtensions to a different value. Run with detectOnly: true to inspect and prompt the user.');
+  }
+
+  const insertAt = findConfigObjectStart(source);
+  if (insertAt === -1) {
+    throw new Error('Could not locate the config object in next.config. Manual edit required.');
+  }
+
+  // Insert the patch block immediately inside the object literal, before existing
+  // properties. This puts it at the top of the config for visibility.
+  const before = source.slice(0, insertAt);
+  const after = source.slice(insertAt);
+  // Add a newline if needed for clean formatting
+  const sep = after.startsWith('\n') ? '' : '\n';
+  return before + sep + PATCH_BLOCK + '\n' + after.replace(/^\n/, '');
+}
+
+module.exports = { patchNextConfig, isPatched };
+```
+
+- [ ] **Step 4: Verify tests pass**
+
+Run: `node --test plugins/adhd/lib/install-design-system-docs-route/__tests__/next-config-patcher.test.js`
+Expected: 5 tests PASS.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add plugins/adhd/lib/install-design-system-docs-route/next-config-patcher.js \
+        plugins/adhd/lib/install-design-system-docs-route/__tests__/next-config-patcher.test.js
+git commit -m "next-config-patcher: idempotent conditional pageExtensions patch"
+```
+
+---
+
+## Task 6: robots-patcher.js — idempotent robots.txt patch
+
+**Files:**
+- Create: `plugins/adhd/lib/install-design-system-docs-route/robots-patcher.js`
+- Create: `plugins/adhd/lib/install-design-system-docs-route/__tests__/robots-patcher.test.js`
+
+- [ ] **Step 1: Write failing tests**
+
+`plugins/adhd/lib/install-design-system-docs-route/__tests__/robots-patcher.test.js`:
+
+```javascript
+'use strict';
+
+const test = require('node:test');
+const assert = require('node:assert/strict');
+const { patchRobots } = require('../robots-patcher');
+
+test('creates robots.txt content if input is empty', () => {
+  const out = patchRobots('', '/-docs');
+  assert.match(out, /User-agent: \*/);
+  assert.match(out, /Disallow: \/-docs/);
+});
+
+test('creates robots.txt content if input is null/undefined', () => {
+  const out = patchRobots(null, '/-docs');
+  assert.match(out, /User-agent: \*/);
+  assert.match(out, /Disallow: \/-docs/);
+});
+
+test('appends a Disallow line to an existing robots.txt', () => {
+  const existing = `User-agent: *
+Disallow: /admin
+`;
+  const out = patchRobots(existing, '/-docs');
+  assert.match(out, /Disallow: \/admin/);
+  assert.match(out, /Disallow: \/-docs/);
+});
+
+test('idempotent: re-patching an already-patched robots.txt returns unchanged', () => {
+  const existing = `User-agent: *
+Disallow: /-docs
+`;
+  const out = patchRobots(existing, '/-docs');
+  assert.equal(out, existing);
+});
+
+test('idempotent: matching is exact (does not match /-docs-other)', () => {
+  const existing = `User-agent: *
+Disallow: /-docs-other
+`;
+  const out = patchRobots(existing, '/-docs');
+  assert.match(out, /Disallow: \/-docs-other/);
+  assert.match(out, /Disallow: \/-docs$/m);
+});
+```
+
+- [ ] **Step 2: Verify tests fail**
+
+Run: `node --test plugins/adhd/lib/install-design-system-docs-route/__tests__/robots-patcher.test.js`
+Expected: FAIL — module not found.
+
+- [ ] **Step 3: Implement robots-patcher.js**
+
+`plugins/adhd/lib/install-design-system-docs-route/robots-patcher.js`:
+
+```javascript
+'use strict';
+
+function patchRobots(source, routeUrl) {
+  const disallowLine = `Disallow: ${routeUrl}`;
+  if (!source) {
+    return `User-agent: *\n${disallowLine}\n`;
+  }
+  // Idempotent: line-anchored exact match
+  const exactRe = new RegExp(`^${disallowLine.replace(/[.*+?^${}()|[\\]\\\\]/g, '\\$&')}\\s*$`, 'm');
+  if (exactRe.test(source)) return source;
+  // Append (ensure newline before, single newline after)
+  const trimmed = source.replace(/\n+$/, '');
+  return trimmed + '\n' + disallowLine + '\n';
+}
+
+module.exports = { patchRobots };
+```
+
+- [ ] **Step 4: Verify tests pass**
+
+Run: `node --test plugins/adhd/lib/install-design-system-docs-route/__tests__/robots-patcher.test.js`
+Expected: 5 tests PASS.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add plugins/adhd/lib/install-design-system-docs-route/robots-patcher.js \
+        plugins/adhd/lib/install-design-system-docs-route/__tests__/robots-patcher.test.js
+git commit -m "robots-patcher: idempotent Disallow entry for the docs route"
+```
+
+---
+
+## Task 7: templates.js — page template content as string constants
+
+**Files:**
+- Create: `plugins/adhd/lib/install-design-system-docs-route/templates.js`
+- Create: `plugins/adhd/lib/install-design-system-docs-route/__tests__/templates.test.js`
+
+- [ ] **Step 1: Write failing tests**
+
+`plugins/adhd/lib/install-design-system-docs-route/__tests__/templates.test.js`:
+
+```javascript
+'use strict';
+
+const test = require('node:test');
+const assert = require('node:assert/strict');
+const { MARKER_COMMENT, LAYOUT_TSX, INDEX_PAGE_TSX, COMPONENT_PAGE_TSX, PROP_TOGGLE_TSX } = require('../templates');
+
+test('MARKER_COMMENT is a stable, non-ADHD-referencing string', () => {
+  assert.match(MARKER_COMMENT, /design-system-docs-route/);
+  assert.match(MARKER_COMMENT, /auto-generated installer artifact; safe to edit/);
+  assert.equal(/adhd/i.test(MARKER_COMMENT), false, 'must not reference ADHD');
+});
+
+test('LAYOUT_TSX starts with the marker comment', () => {
+  assert.ok(LAYOUT_TSX.startsWith(MARKER_COMMENT));
+});
+
+test('LAYOUT_TSX sets robots: noindex / nofollow', () => {
+  assert.match(LAYOUT_TSX, /robots:\s*\{[^}]*index:\s*false[^}]*follow:\s*false/);
+});
+
+test('LAYOUT_TSX has no ADHD references outside marker', () => {
+  // marker excluded
+  const body = LAYOUT_TSX.replace(MARKER_COMMENT, '');
+  assert.equal(/adhd/i.test(body), false);
+});
+
+test('INDEX_PAGE_TSX renders sections for each token domain', () => {
+  for (const section of ['Colors', 'Spacing', 'Typography', 'Radius', 'Shadows', 'Components']) {
+    assert.match(INDEX_PAGE_TSX, new RegExp(section));
+  }
+});
+
+test('INDEX_PAGE_TSX reads adhd.config.ts and globals.css via fs', () => {
+  assert.match(INDEX_PAGE_TSX, /adhd\.config\.ts/);
+  assert.match(INDEX_PAGE_TSX, /globals\.css|cssEntry/);
+});
+
+test('COMPONENT_PAGE_TSX uses parametric template-string dynamic import', () => {
+  assert.match(COMPONENT_PAGE_TSX, /await\s+import\(`/);
+});
+
+test('COMPONENT_PAGE_TSX reads searchParams for prop toggles', () => {
+  assert.match(COMPONENT_PAGE_TSX, /searchParams/);
+});
+
+test('PROP_TOGGLE_TSX is a client component', () => {
+  assert.match(PROP_TOGGLE_TSX, /^["']use client["']/);
+});
+
+test('PROP_TOGGLE_TSX uses router.replace for snappy URL updates', () => {
+  assert.match(PROP_TOGGLE_TSX, /router\.replace/);
+});
+
+test('none of the templates contain "ADHD" outside the marker', () => {
+  for (const [name, content] of Object.entries({ LAYOUT_TSX, INDEX_PAGE_TSX, COMPONENT_PAGE_TSX, PROP_TOGGLE_TSX })) {
+    const body = content.replace(MARKER_COMMENT, '');
+    assert.equal(/adhd/i.test(body), false, `${name} must not reference ADHD outside marker`);
+  }
+});
+```
+
+- [ ] **Step 2: Verify tests fail**
+
+Run: `node --test plugins/adhd/lib/install-design-system-docs-route/__tests__/templates.test.js`
+Expected: FAIL — module not found.
+
+- [ ] **Step 3: Implement templates.js**
+
+`plugins/adhd/lib/install-design-system-docs-route/templates.js`:
+
+```javascript
+'use strict';
+
+const MARKER_COMMENT = `// design-system-docs-route — auto-generated installer artifact; safe to edit.
+// Remove this comment to disable future overwrites from re-running the installer.
+`;
+
+const LAYOUT_TSX = `${MARKER_COMMENT}import type { Metadata } from "next";
+
+export const metadata: Metadata = {
+  title: "Design System Docs",
+  robots: { index: false, follow: false },
+};
+
+export default function DesignSystemDocsLayout({ children }: { children: React.ReactNode }) {
+  return (
+    <div className="min-h-screen bg-zinc-50 dark:bg-zinc-950">
+      <header className="border-b border-zinc-200 dark:border-zinc-800 p-4">
+        <div className="mx-auto max-w-5xl flex items-baseline gap-3">
+          <h1 className="text-sm font-medium">Design System Docs</h1>
+          <span className="text-xs text-zinc-500">Internal — not indexed</span>
+        </div>
+      </header>
+      <main className="mx-auto max-w-5xl p-8">{children}</main>
+    </div>
+  );
+}
+`;
+
+const INDEX_PAGE_TSX = `${MARKER_COMMENT}import fs from "node:fs/promises";
+import path from "node:path";
+import Link from "next/link";
+
+async function readConfig() {
+  try {
+    const src = await fs.readFile(path.resolve(process.cwd(), "adhd.config.ts"), "utf8");
+    const components: Record<string, unknown> = {};
+    const compMatch = /components:\\s*\\{([\\s\\S]*?)\\}\\s*[,;]?/.exec(src);
+    if (compMatch) {
+      const inner = compMatch[1];
+      const re = /"([^"]+)"\\s*:\\s*\\{/g;
+      let m;
+      while ((m = re.exec(inner)) !== null) {
+        components[m[1]] = true;
+      }
+    }
+    const cssEntryMatch = /cssEntry\\s*:\\s*"([^"]+)"/.exec(src);
+    const cssEntry = cssEntryMatch ? cssEntryMatch[1] : "app/globals.css";
+    return { components: Object.keys(components), cssEntry };
+  } catch {
+    return { components: [], cssEntry: "app/globals.css" };
+  }
+}
+
+async function readCss(cssEntry: string) {
+  try {
+    return await fs.readFile(path.resolve(process.cwd(), cssEntry), "utf8");
+  } catch {
+    return null;
+  }
+}
+
+function extractTokens(css: string | null) {
+  const empty = { colors: [], spacing: { multiplier: null }, typography: [], radius: [], shadows: [] };
+  if (!css) return empty;
+  const out = { colors: [] as Array<{ name: string; value: string }>,
+                spacing: { multiplier: null as string | null },
+                typography: [] as Array<{ name: string; size: string | null; lineHeight: string | null }>,
+                radius: [] as Array<{ name: string; value: string }>,
+                shadows: [] as Array<{ name: string; value: string }> };
+  const themeRe = /@theme\\s*\\{([\\s\\S]*?)\\}/g;
+  let body;
+  while ((body = themeRe.exec(css)) !== null) {
+    const declRe = /--([a-zA-Z0-9_-]+)\\s*:\\s*([^;]+);/g;
+    let d;
+    while ((d = declRe.exec(body[1])) !== null) {
+      const name = d[1];
+      const value = d[2].trim();
+      if (name.startsWith("color-")) out.colors.push({ name: name.slice(6), value });
+      else if (name === "spacing") out.spacing.multiplier = value;
+      else if (name.startsWith("text-")) {
+        const rest = name.slice(5);
+        const lhIdx = rest.indexOf("--line-height");
+        const leaf = lhIdx >= 0 ? rest.slice(0, lhIdx) : rest;
+        let row = out.typography.find(t => t.name === leaf);
+        if (!row) { row = { name: leaf, size: null, lineHeight: null }; out.typography.push(row); }
+        if (lhIdx >= 0) row.lineHeight = value; else row.size = value;
+      } else if (name.startsWith("radius-")) out.radius.push({ name: name.slice(7), value });
+      else if (name.startsWith("shadow-")) out.shadows.push({ name: name.slice(7), value });
+    }
+  }
+  return out;
+}
+
+export default async function DesignSystemIndex() {
+  const cfg = await readConfig();
+  const css = await readCss(cfg.cssEntry);
+  const tokens = extractTokens(css);
+
+  return (
+    <div className="flex flex-col gap-12">
+      <section>
+        <h2 className="mb-4 text-xs font-medium uppercase text-zinc-500">Colors</h2>
+        {tokens.colors.length === 0 ? <p className="text-sm text-zinc-500">No colors detected.</p> : (
+          <div className="grid grid-cols-6 gap-3">
+            {tokens.colors.map(c => (
+              <div key={c.name} className="flex flex-col gap-1">
+                <div className="h-12 w-full rounded border border-zinc-200 dark:border-zinc-800" style={{ backgroundColor: c.value }} />
+                <span className="text-xs">{c.name}</span>
+                <span className="text-[10px] text-zinc-500">{c.value}</span>
+              </div>
+            ))}
+          </div>
+        )}
+      </section>
+
+      <section>
+        <h2 className="mb-4 text-xs font-medium uppercase text-zinc-500">Spacing</h2>
+        {tokens.spacing.multiplier ? <p className="text-sm">Multiplier: <code>{tokens.spacing.multiplier}</code></p> : <p className="text-sm text-zinc-500">No spacing variable detected.</p>}
+      </section>
+
+      <section>
+        <h2 className="mb-4 text-xs font-medium uppercase text-zinc-500">Typography</h2>
+        {tokens.typography.length === 0 ? <p className="text-sm text-zinc-500">No typography tokens detected.</p> : (
+          <div className="flex flex-col gap-4">
+            {tokens.typography.map(t => (
+              <div key={t.name} className="flex items-baseline gap-4">
+                <span className="text-xs text-zinc-500 w-20">text-{t.name}</span>
+                <span style={{ fontSize: t.size ?? undefined, lineHeight: t.lineHeight ?? undefined }}>
+                  The quick brown fox jumps over the lazy dog
+                </span>
+                <span className="text-[10px] text-zinc-500">{t.size}{t.lineHeight ? ` / ${t.lineHeight}` : ""}</span>
+              </div>
+            ))}
+          </div>
+        )}
+      </section>
+
+      <section>
+        <h2 className="mb-4 text-xs font-medium uppercase text-zinc-500">Radius</h2>
+        {tokens.radius.length === 0 ? <p className="text-sm text-zinc-500">No radius tokens detected.</p> : (
+          <div className="flex gap-4">
+            {tokens.radius.map(r => (
+              <div key={r.name} className="flex flex-col gap-1">
+                <div className="h-16 w-16 bg-zinc-200 dark:bg-zinc-800" style={{ borderRadius: r.value }} />
+                <span className="text-xs">rounded-{r.name}</span>
+              </div>
+            ))}
+          </div>
+        )}
+      </section>
+
+      <section>
+        <h2 className="mb-4 text-xs font-medium uppercase text-zinc-500">Shadows</h2>
+        {tokens.shadows.length === 0 ? <p className="text-sm text-zinc-500">No shadow tokens detected.</p> : (
+          <div className="flex gap-6">
+            {tokens.shadows.map(s => (
+              <div key={s.name} className="flex flex-col gap-1">
+                <div className="h-16 w-16 bg-white" style={{ boxShadow: s.value }} />
+                <span className="text-xs">shadow-{s.name}</span>
+              </div>
+            ))}
+          </div>
+        )}
+      </section>
+
+      <section>
+        <h2 className="mb-4 text-xs font-medium uppercase text-zinc-500">Components</h2>
+        {cfg.components.length === 0 ? <p className="text-sm text-zinc-500">No components tracked. Push one with /adhd:push-component &lt;path&gt;.</p> : (
+          <div className="grid grid-cols-3 gap-4">
+            {cfg.components.map(p => {
+              const slug = p.replace(/\\.tsx?$/, "").replace(/\\/index$/, "").split("/").pop()?.toLowerCase() ?? p;
+              return (
+                <Link key={p} href={\`./\${slug}\`} className="rounded border border-zinc-200 dark:border-zinc-800 p-4 hover:bg-zinc-100 dark:hover:bg-zinc-900">
+                  <div className="text-sm font-medium">{slug}</div>
+                  <div className="text-xs text-zinc-500 truncate">{p}</div>
+                </Link>
+              );
+            })}
+          </div>
+        )}
+      </section>
+    </div>
+  );
+}
+`;
+
+const COMPONENT_PAGE_TSX = `${MARKER_COMMENT}import fs from "node:fs/promises";
+import path from "node:path";
+import { notFound } from "next/navigation";
+import { PropToggle } from "../PropToggle";
+
+async function readConfig() {
+  try {
+    const src = await fs.readFile(path.resolve(process.cwd(), "adhd.config.ts"), "utf8");
+    const components: string[] = [];
+    const compMatch = /components:\\s*\\{([\\s\\S]*?)\\}\\s*[,;]?/.exec(src);
+    if (compMatch) {
+      const inner = compMatch[1];
+      const re = /"([^"]+)"\\s*:\\s*\\{/g;
+      let m;
+      while ((m = re.exec(inner)) !== null) components.push(m[1]);
+    }
+    return components;
+  } catch {
+    return [];
+  }
+}
+
+function slugFor(p: string) {
+  return p.replace(/\\.tsx?$/, "").replace(/\\/index$/, "").split("/").pop()?.toLowerCase() ?? p;
+}
+
+async function parseProps(componentPath: string) {
+  try {
+    const src = await fs.readFile(path.resolve(process.cwd(), componentPath), "utf8");
+    const TYPE_ALIAS_RE = /export\\s+type\\s+([A-Z][A-Za-z0-9]*)\\s*=\\s*([^;]+);/g;
+    const INTERFACE_RE = /(?:export\\s+)?interface\\s+([A-Z][A-Za-z0-9]*Props)\\s*\\{([\\s\\S]*?)\\}/;
+    const PROP_LINE_RE = /^\\s*([a-zA-Z_$][a-zA-Z0-9_$]*)(\\??)\\s*:\\s*([^;,]+)[;,]?\\s*$/;
+
+    const knownUnions: Record<string, string[]> = {};
+    TYPE_ALIAS_RE.lastIndex = 0;
+    let m;
+    while ((m = TYPE_ALIAS_RE.exec(src)) !== null) {
+      const body = m[2].trim();
+      if (/^"[^"]*"(\\s*\\|\\s*"[^"]*")*$/.test(body)) {
+        knownUnions[m[1]] = body.split("|").map(s => s.trim().replace(/"/g, ""));
+      }
+    }
+    const iface = INTERFACE_RE.exec(src);
+    if (!iface) return { props: {} as Record<string, any>, knownUnions };
+    const props: Record<string, any> = {};
+    for (const rawLine of iface[2].split("\\n")) {
+      const line = rawLine.replace(/\\/\\/.*$/, "");
+      const pm = PROP_LINE_RE.exec(line);
+      if (!pm) continue;
+      const [, name, opt, type] = pm;
+      const t = type.trim();
+      if (knownUnions[t]) props[name] = { type: "union", values: knownUnions[t], optional: !!opt };
+      else if (/^"[^"]*"(\\s*\\|\\s*"[^"]*")*$/.test(t)) {
+        props[name] = { type: "union", values: t.split("|").map(s => s.trim().replace(/"/g, "")), optional: !!opt };
+      } else if (t === "string") props[name] = { type: "string", optional: !!opt };
+      else if (t === "number") props[name] = { type: "number", optional: !!opt };
+      else if (t === "boolean") props[name] = { type: "boolean", optional: !!opt };
+      else props[name] = { type: "unknown", optional: !!opt };
+    }
+    return { props, knownUnions };
+  } catch {
+    return { props: {} as Record<string, any>, knownUnions: {} };
+  }
+}
+
+export default async function ComponentPage({
+  params,
+  searchParams,
+}: {
+  params: Promise<{ component: string }>;
+  searchParams: Promise<Record<string, string | string[] | undefined>>;
+}) {
+  const { component: slug } = await params;
+  const sp = await searchParams;
+  const paths = await readConfig();
+  const componentPath = paths.find(p => slugFor(p) === slug);
+  if (!componentPath) notFound();
+
+  const { props } = await parseProps(componentPath);
+
+  // Resolve current prop values from searchParams
+  const current: Record<string, any> = {};
+  for (const [name, def] of Object.entries(props)) {
+    const v = sp[name];
+    if (typeof v !== "string") continue;
+    if (def.type === "union" && def.values.includes(v)) current[name] = v;
+    else if (def.type === "boolean") current[name] = v === "true";
+    else if (def.type === "string") current[name] = v;
+    else if (def.type === "number") current[name] = Number(v);
+  }
+
+  // Dynamic import the component
+  let Component: any = null;
+  let importError: string | null = null;
+  try {
+    const mod = await import(\`@/\${componentPath.replace(/\\.tsx?$/, "")}\`);
+    const name = Object.keys(mod).find(k => typeof mod[k] === "function") ?? "default";
+    Component = mod.default ?? mod[name];
+  } catch (e: any) {
+    importError = e?.message ?? String(e);
+  }
+
+  const importPath = "@/" + componentPath.replace(/\\.tsx?$/, "").replace(/\\/index$/, "");
+  const importStmt = Component ? \`import { \${Component.name ?? slug} } from "\${importPath}";\` : null;
+  const jsxSnippet = Component
+    ? \`<\${Component.name ?? slug}\${Object.entries(current).map(([k,v]) => \` \${k}={\${JSON.stringify(v)}}\`).join("")} />\`
+    : null;
+
+  return (
+    <div className="flex flex-col gap-6">
+      <h2 className="text-lg font-medium">{slug}</h2>
+
+      <section className="rounded border border-zinc-200 dark:border-zinc-800 p-4">
+        <h3 className="mb-3 text-xs font-medium uppercase text-zinc-500">Props</h3>
+        {Object.keys(props).length === 0 ? <p className="text-sm text-zinc-500">No prop introspection available.</p> : (
+          <div className="flex flex-col gap-2">
+            {Object.entries(props).map(([name, def]: [string, any]) => {
+              if (def.type === "union") {
+                return (
+                  <PropToggle key={name} name={name} kind="union" values={def.values} value={current[name] ?? def.values[0]} />
+                );
+              }
+              if (def.type === "boolean") {
+                return (
+                  <PropToggle key={name} name={name} kind="boolean" value={String(current[name] ?? false)} />
+                );
+              }
+              if (def.type === "string" || def.type === "number") {
+                return (
+                  <PropToggle key={name} name={name} kind={def.type} value={String(current[name] ?? "")} />
+                );
+              }
+              return (
+                <div key={name} className="text-xs text-zinc-500">
+                  {name}: <code>{def.type}</code> — toggle unavailable
+                </div>
+              );
+            })}
+          </div>
+        )}
+      </section>
+
+      <section className="rounded border border-zinc-200 dark:border-zinc-800 p-8">
+        {importError ? (
+          <pre className="text-xs text-red-600 whitespace-pre-wrap">{importError}</pre>
+        ) : Component ? (
+          <Component {...current} />
+        ) : null}
+      </section>
+
+      {importStmt && jsxSnippet && (
+        <section className="flex flex-col gap-2">
+          <pre className="rounded bg-zinc-100 dark:bg-zinc-900 p-3 text-xs overflow-x-auto"><code>{importStmt}</code></pre>
+          <pre className="rounded bg-zinc-100 dark:bg-zinc-900 p-3 text-xs overflow-x-auto"><code>{jsxSnippet}</code></pre>
+        </section>
+      )}
+    </div>
+  );
+}
+`;
+
+const PROP_TOGGLE_TSX = `${MARKER_COMMENT}"use client";
+import { useRouter, useSearchParams, usePathname } from "next/navigation";
+
+type Props =
+  | { name: string; kind: "union"; values: string[]; value: string }
+  | { name: string; kind: "boolean"; value: string }
+  | { name: string; kind: "string"; value: string }
+  | { name: string; kind: "number"; value: string };
+
+export function PropToggle(p: Props) {
+  const router = useRouter();
+  const path = usePathname();
+  const sp = useSearchParams();
+
+  function setParam(v: string) {
+    const next = new URLSearchParams(sp.toString());
+    if (v === "") next.delete(p.name);
+    else next.set(p.name, v);
+    router.replace(\`\${path}?\${next}\`);
+  }
+
+  return (
+    <label className="flex items-center gap-3 text-sm">
+      <span className="w-24 text-xs text-zinc-500">{p.name}</span>
+      {p.kind === "union" ? (
+        <select className="rounded border border-zinc-300 dark:border-zinc-700 bg-transparent px-2 py-1 text-sm" value={p.value} onChange={(e) => setParam(e.target.value)}>
+          {p.values.map((v) => <option key={v} value={v}>{v}</option>)}
+        </select>
+      ) : p.kind === "boolean" ? (
+        <input type="checkbox" checked={p.value === "true"} onChange={(e) => setParam(String(e.target.checked))} />
+      ) : (
+        <input type={p.kind === "number" ? "number" : "text"} className="rounded border border-zinc-300 dark:border-zinc-700 bg-transparent px-2 py-1 text-sm" value={p.value} onChange={(e) => setParam(e.target.value)} />
+      )}
+    </label>
+  );
+}
+`;
+
+module.exports = { MARKER_COMMENT, LAYOUT_TSX, INDEX_PAGE_TSX, COMPONENT_PAGE_TSX, PROP_TOGGLE_TSX };
+```
+
+- [ ] **Step 4: Verify tests pass**
+
+Run: `node --test plugins/adhd/lib/install-design-system-docs-route/__tests__/templates.test.js`
+Expected: 10 tests PASS.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add plugins/adhd/lib/install-design-system-docs-route/templates.js \
+        plugins/adhd/lib/install-design-system-docs-route/__tests__/templates.test.js
+git commit -m "templates: layout, index, component page, PropToggle (marker-prefixed, no ADHD refs)"
+```
+
+---
+
+## Task 8: route-installer.js — write files at the target path with marker detection
+
+**Files:**
+- Create: `plugins/adhd/lib/install-design-system-docs-route/route-installer.js`
+- Create: `plugins/adhd/lib/install-design-system-docs-route/__tests__/route-installer.test.js`
+
+- [ ] **Step 1: Write failing tests**
+
+`plugins/adhd/lib/install-design-system-docs-route/__tests__/route-installer.test.js`:
+
+```javascript
+'use strict';
+
+const test = require('node:test');
+const assert = require('node:assert/strict');
+const fs = require('node:fs');
+const path = require('node:path');
+const os = require('node:os');
+const { installRoute, detectExistingInstall } = require('../route-installer');
+
+function makeTempProject() {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'adhd-install-'));
+  fs.mkdirSync(path.join(root, 'app'), { recursive: true });
+  return root;
+}
+
+test('installRoute writes 4 files with the .design-system.tsx extension when prodExcluded', () => {
+  const root = makeTempProject();
+  installRoute(root, {
+    groupName: '(design-system)',
+    routeSegment: '-docs',
+    prodExcluded: true,
+  });
+  const docsDir = path.join(root, 'app', '(design-system)', '-docs');
+  assert.ok(fs.existsSync(path.join(docsDir, 'layout.design-system.tsx')));
+  assert.ok(fs.existsSync(path.join(docsDir, 'page.design-system.tsx')));
+  assert.ok(fs.existsSync(path.join(docsDir, '[component]', 'page.design-system.tsx')));
+  assert.ok(fs.existsSync(path.join(docsDir, 'PropToggle.design-system.tsx')));
+});
+
+test('installRoute writes plain .tsx files when not prodExcluded', () => {
+  const root = makeTempProject();
+  installRoute(root, {
+    groupName: '(design-system)',
+    routeSegment: '-docs',
+    prodExcluded: false,
+  });
+  const docsDir = path.join(root, 'app', '(design-system)', '-docs');
+  assert.ok(fs.existsSync(path.join(docsDir, 'layout.tsx')));
+  assert.ok(fs.existsSync(path.join(docsDir, 'page.tsx')));
+  assert.ok(fs.existsSync(path.join(docsDir, '[component]', 'page.tsx')));
+  assert.ok(fs.existsSync(path.join(docsDir, 'PropToggle.tsx')));
+});
+
+test('all written files start with the marker comment', () => {
+  const root = makeTempProject();
+  installRoute(root, { groupName: '(design-system)', routeSegment: '-docs', prodExcluded: true });
+  const docsDir = path.join(root, 'app', '(design-system)', '-docs');
+  for (const f of [
+    'layout.design-system.tsx',
+    'page.design-system.tsx',
+    '[component]/page.design-system.tsx',
+    'PropToggle.design-system.tsx',
+  ]) {
+    const content = fs.readFileSync(path.join(docsDir, f), 'utf8');
+    assert.match(content, /design-system-docs-route/);
+  }
+});
+
+test('detectExistingInstall scans for the marker and returns matching files', () => {
+  const root = makeTempProject();
+  installRoute(root, { groupName: '(design-system)', routeSegment: '-docs', prodExcluded: true });
+  const found = detectExistingInstall(root);
+  assert.ok(found.length >= 4);
+  assert.ok(found.every(p => p.includes('-docs')));
+});
+
+test('detectExistingInstall returns [] when no marker is present', () => {
+  const root = makeTempProject();
+  const found = detectExistingInstall(root);
+  assert.deepEqual(found, []);
+});
+
+test('detectExistingInstall does not match unrelated files', () => {
+  const root = makeTempProject();
+  fs.writeFileSync(path.join(root, 'app', 'page.tsx'), 'export default function P() { return null; }\n');
+  assert.deepEqual(detectExistingInstall(root), []);
+});
+
+test('re-running installRoute is safe (overwrites files cleanly)', () => {
+  const root = makeTempProject();
+  installRoute(root, { groupName: '(design-system)', routeSegment: '-docs', prodExcluded: true });
+  // Modify a file
+  const layoutPath = path.join(root, 'app', '(design-system)', '-docs', 'layout.design-system.tsx');
+  fs.writeFileSync(layoutPath, 'corrupted');
+  // Re-install
+  installRoute(root, { groupName: '(design-system)', routeSegment: '-docs', prodExcluded: true });
+  const after = fs.readFileSync(layoutPath, 'utf8');
+  assert.match(after, /design-system-docs-route/);
+  assert.match(after, /DesignSystemDocsLayout/);
+});
+
+test('installRoute supports an empty groupName (no route group)', () => {
+  const root = makeTempProject();
+  installRoute(root, { groupName: '', routeSegment: '-docs', prodExcluded: true });
+  const docsDir = path.join(root, 'app', '-docs');
+  assert.ok(fs.existsSync(path.join(docsDir, 'layout.design-system.tsx')));
+});
+```
+
+- [ ] **Step 2: Verify tests fail**
+
+Run: `node --test plugins/adhd/lib/install-design-system-docs-route/__tests__/route-installer.test.js`
+Expected: FAIL — module not found.
+
+- [ ] **Step 3: Implement route-installer.js**
+
+`plugins/adhd/lib/install-design-system-docs-route/route-installer.js`:
+
+```javascript
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { MARKER_COMMENT, LAYOUT_TSX, INDEX_PAGE_TSX, COMPONENT_PAGE_TSX, PROP_TOGGLE_TSX } = require('./templates');
+
+function mkdirpSync(p) {
+  fs.mkdirSync(p, { recursive: true });
+}
+
+function installRoute(projectRoot, opts) {
+  const { groupName = '', routeSegment, prodExcluded } = opts;
+  if (!routeSegment) throw new Error('routeSegment is required');
+
+  const ext = prodExcluded ? '.design-system.tsx' : '.tsx';
+  const segments = ['app'];
+  if (groupName) segments.push(groupName);
+  segments.push(routeSegment);
+  const docsDir = path.join(projectRoot, ...segments);
+  const componentDir = path.join(docsDir, '[component]');
+
+  mkdirpSync(docsDir);
+  mkdirpSync(componentDir);
+
+  fs.writeFileSync(path.join(docsDir, `layout${ext}`), LAYOUT_TSX);
+  fs.writeFileSync(path.join(docsDir, `page${ext}`), INDEX_PAGE_TSX);
+  fs.writeFileSync(path.join(componentDir, `page${ext}`), COMPONENT_PAGE_TSX);
+  fs.writeFileSync(path.join(docsDir, `PropToggle${ext}`), PROP_TOGGLE_TSX);
+
+  return {
+    files: [
+      path.join(docsDir, `layout${ext}`),
+      path.join(docsDir, `page${ext}`),
+      path.join(componentDir, `page${ext}`),
+      path.join(docsDir, `PropToggle${ext}`),
+    ],
+  };
+}
+
+function detectExistingInstall(projectRoot) {
+  const found = [];
+  function walk(dir) {
+    let entries;
+    try { entries = fs.readdirSync(dir, { withFileTypes: true }); }
+    catch { return; }
+    for (const ent of entries) {
+      if (ent.name === 'node_modules' || ent.name === '.next' || ent.name.startsWith('.git')) continue;
+      const full = path.join(dir, ent.name);
+      if (ent.isDirectory()) walk(full);
+      else if (/\.tsx?$/.test(ent.name)) {
+        try {
+          const content = fs.readFileSync(full, 'utf8');
+          if (content.includes('design-system-docs-route')) {
+            found.push(full);
+          }
+        } catch {}
+      }
+    }
+  }
+  walk(path.join(projectRoot, 'app'));
+  return found;
+}
+
+module.exports = { installRoute, detectExistingInstall };
+```
+
+- [ ] **Step 4: Verify tests pass**
+
+Run: `node --test plugins/adhd/lib/install-design-system-docs-route/__tests__/route-installer.test.js`
+Expected: 8 tests PASS.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add plugins/adhd/lib/install-design-system-docs-route/route-installer.js \
+        plugins/adhd/lib/install-design-system-docs-route/__tests__/route-installer.test.js
+git commit -m "route-installer: write the 4 page files; detect existing installs via marker"
+```
+
+---
+
+## Task 9: cli.js — wire all subcommands
+
+**Files:**
+- Modify: `plugins/adhd/lib/install-design-system-docs-route/cli.js`
+- Modify: `plugins/adhd/lib/install-design-system-docs-route/__tests__/cli.test.js`
+
+- [ ] **Step 1: Extend cli tests for each subcommand**
+
+Append to `plugins/adhd/lib/install-design-system-docs-route/__tests__/cli.test.js`:
+
+```javascript
+const fs = require('node:fs');
+const os = require('node:os');
+
+function tmp(filename, content) {
+  const p = path.join(os.tmpdir(), 'adhd-ids-' + Date.now() + '-' + Math.random().toString(16).slice(2, 8) + '-' + filename);
+  fs.writeFileSync(p, content);
+  return p;
+}
+
+const FX_CSS = path.resolve(__dirname, '..', '__fixtures__', 'globals.css');
+const FX_AVATAR = path.resolve(__dirname, '..', '__fixtures__', 'avatar.tsx');
+
+test('parse-tokens subcommand outputs token JSON', () => {
+  const out = tmp('tokens.json', '');
+  const r = spawnSync('node', [CLI, 'parse-tokens', '--css', FX_CSS, '--output', out], { encoding: 'utf8' });
+  assert.equal(r.status, 0, r.stderr);
+  const t = JSON.parse(fs.readFileSync(out, 'utf8'));
+  assert.ok(t.colors.length > 0);
+});
+
+test('parse-props subcommand outputs props JSON', () => {
+  const out = tmp('props.json', '');
+  const r = spawnSync('node', [CLI, 'parse-props', '--source', FX_AVATAR, '--output', out], { encoding: 'utf8' });
+  assert.equal(r.status, 0, r.stderr);
+  const p = JSON.parse(fs.readFileSync(out, 'utf8'));
+  assert.equal(p.componentName, 'Avatar');
+  assert.ok(p.props.size.values.length === 5);
+});
+
+test('slug subcommand outputs slug map JSON', () => {
+  const out = tmp('slugs.json', '');
+  const r = spawnSync('node', [CLI, 'slug', '--paths', 'app/components/avatar/index.tsx,app/components/avatar-group/index.tsx', '--output', out], { encoding: 'utf8' });
+  assert.equal(r.status, 0, r.stderr);
+  const m = JSON.parse(fs.readFileSync(out, 'utf8'));
+  assert.equal(m['app/components/avatar/index.tsx'], 'avatar');
+});
+
+test('patch-next-config subcommand mutates the file in place', () => {
+  const cfg = tmp('next.config.ts', `import type { NextConfig } from "next";\nconst nextConfig: NextConfig = {};\nexport default nextConfig;\n`);
+  const r = spawnSync('node', [CLI, 'patch-next-config', '--config', cfg, '--route-url', '/-docs'], { encoding: 'utf8' });
+  assert.equal(r.status, 0, r.stderr);
+  const after = fs.readFileSync(cfg, 'utf8');
+  assert.match(after, /pageExtensions:\s*process\.env\.NODE_ENV/);
+});
+
+test('patch-robots subcommand mutates the file in place; creates if missing', () => {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'adhd-ids-robots-'));
+  const robots = path.join(root, 'robots.txt');
+  const r = spawnSync('node', [CLI, 'patch-robots', '--robots', robots, '--route-url', '/-docs'], { encoding: 'utf8' });
+  assert.equal(r.status, 0, r.stderr);
+  const after = fs.readFileSync(robots, 'utf8');
+  assert.match(after, /Disallow: \/-docs/);
+});
+
+test('detect-install subcommand prints existing install paths to stdout', () => {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'adhd-ids-detect-'));
+  fs.mkdirSync(path.join(root, 'app', '(design-system)', '-docs'), { recursive: true });
+  fs.writeFileSync(
+    path.join(root, 'app', '(design-system)', '-docs', 'layout.tsx'),
+    '// design-system-docs-route — auto-generated installer artifact; safe to edit.\nexport default function L({ children }) { return children; }\n',
+  );
+  const r = spawnSync('node', [CLI, 'detect-install', '--app-dir', root], { encoding: 'utf8' });
+  assert.equal(r.status, 0, r.stderr);
+  assert.match(r.stdout, /-docs\/layout\.tsx/);
+});
+
+test('install subcommand writes files based on choices JSON', () => {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'adhd-ids-install-'));
+  fs.mkdirSync(path.join(root, 'app'), { recursive: true });
+  const choices = tmp('choices.json', JSON.stringify({
+    projectRoot: root, groupName: '(design-system)', routeSegment: '-docs', prodExcluded: true,
+  }));
+  const r = spawnSync('node', [CLI, 'install', '--config', choices], { encoding: 'utf8' });
+  assert.equal(r.status, 0, r.stderr);
+  assert.ok(fs.existsSync(path.join(root, 'app', '(design-system)', '-docs', 'page.design-system.tsx')));
+});
+```
+
+- [ ] **Step 2: Verify the new tests fail**
+
+Run: `node --test plugins/adhd/lib/install-design-system-docs-route/__tests__/cli.test.js`
+Expected: 7 new tests FAIL; original 3 still pass.
+
+- [ ] **Step 3: Implement cli.js full surface**
+
+Replace `plugins/adhd/lib/install-design-system-docs-route/cli.js`:
+
+```javascript
+#!/usr/bin/env node
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { parseTokens } = require('./token-parser');
+const { parseProps } = require('./prop-parser');
+const { slugMap } = require('./slug');
+const { patchNextConfig } = require('./next-config-patcher');
+const { patchRobots } = require('./robots-patcher');
+const { installRoute, detectExistingInstall } = require('./route-installer');
+
+function parseArgs(argv) {
+  const args = { _: [] };
+  for (let i = 2; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '--help' || a === '-h') { args.help = true; continue; }
+    if (a.startsWith('--')) { args[a.slice(2)] = argv[++i]; }
+    else { args._.push(a); }
+  }
+  return args;
+}
+
+function printUsage() {
+  console.log(`Usage:
+  cli.js parse-tokens --css <path> --output <json>
+  cli.js parse-props --source <component.tsx> --output <json>
+  cli.js slug --paths <comma-separated> --output <json>
+  cli.js patch-next-config --config <path> --route-url <url>
+  cli.js patch-robots --robots <path> --route-url <url>
+  cli.js detect-install --app-dir <path>
+  cli.js install --config <choices.json>`);
+}
+
+function main() {
+  const args = parseArgs(process.argv);
+  if (args.help) { printUsage(); process.exit(0); }
+  if (args._.length === 0) { printUsage(); process.exit(2); }
+  const cmd = args._[0];
+
+  if (cmd === 'parse-tokens') {
+    if (!args.css || !args.output) { console.error('Usage: parse-tokens --css <path> --output <json>'); process.exit(2); }
+    const css = fs.readFileSync(args.css, 'utf8');
+    fs.writeFileSync(args.output, JSON.stringify(parseTokens(css), null, 2));
+    process.exit(0);
+  }
+
+  if (cmd === 'parse-props') {
+    if (!args.source || !args.output) { console.error('Usage: parse-props --source <tsx> --output <json>'); process.exit(2); }
+    const src = fs.readFileSync(args.source, 'utf8');
+    fs.writeFileSync(args.output, JSON.stringify(parseProps(src), null, 2));
+    process.exit(0);
+  }
+
+  if (cmd === 'slug') {
+    if (!args.paths || !args.output) { console.error('Usage: slug --paths <csv> --output <json>'); process.exit(2); }
+    const paths = args.paths.split(',').map(s => s.trim()).filter(Boolean);
+    fs.writeFileSync(args.output, JSON.stringify(slugMap(paths), null, 2));
+    process.exit(0);
+  }
+
+  if (cmd === 'patch-next-config') {
+    if (!args.config || !args['route-url']) { console.error('Usage: patch-next-config --config <path> --route-url <url>'); process.exit(2); }
+    const src = fs.readFileSync(args.config, 'utf8');
+    const r = patchNextConfig(src, { detectOnly: true });
+    if (r && r.conflict) {
+      console.error('next.config already sets pageExtensions: ' + r.existing);
+      process.exit(3);
+    }
+    const out = patchNextConfig(src);
+    fs.writeFileSync(args.config, out);
+    process.exit(0);
+  }
+
+  if (cmd === 'patch-robots') {
+    if (!args.robots || !args['route-url']) { console.error('Usage: patch-robots --robots <path> --route-url <url>'); process.exit(2); }
+    let src = '';
+    try { src = fs.readFileSync(args.robots, 'utf8'); } catch {}
+    fs.writeFileSync(args.robots, patchRobots(src, args['route-url']));
+    process.exit(0);
+  }
+
+  if (cmd === 'detect-install') {
+    if (!args['app-dir']) { console.error('Usage: detect-install --app-dir <path>'); process.exit(2); }
+    const found = detectExistingInstall(args['app-dir']);
+    for (const f of found) process.stdout.write(f + '\n');
+    process.exit(0);
+  }
+
+  if (cmd === 'install') {
+    if (!args.config) { console.error('Usage: install --config <choices.json>'); process.exit(2); }
+    const choices = JSON.parse(fs.readFileSync(args.config, 'utf8'));
+    if (!choices.projectRoot) { console.error('install: choices.projectRoot is required'); process.exit(2); }
+    const r = installRoute(choices.projectRoot, choices);
+    process.stdout.write(JSON.stringify({ files: r.files }, null, 2) + '\n');
+    process.exit(0);
+  }
+
+  console.error('Unknown subcommand: ' + cmd);
+  process.exit(2);
+}
+
+main();
+```
+
+- [ ] **Step 4: Verify all cli tests pass**
+
+Run: `node --test plugins/adhd/lib/install-design-system-docs-route/__tests__/cli.test.js`
+Expected: 10 tests PASS.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add plugins/adhd/lib/install-design-system-docs-route/cli.js \
+        plugins/adhd/lib/install-design-system-docs-route/__tests__/cli.test.js
+git commit -m "cli: wire all subcommands (parse-tokens, parse-props, slug, patch-*, detect-install, install)"
+```
+
+---
+
+## Task 10: SKILL.md — the 9-phase orchestrator
+
+**Files:**
+- Create: `plugins/adhd/skills/install-design-system-docs-route/SKILL.md`
+
+- [ ] **Step 1: Write SKILL.md**
+
+`plugins/adhd/skills/install-design-system-docs-route/SKILL.md`:
+
+````markdown
+---
+description: "Install a self-generating design-system documentation route into a Next.js consumer app. The route reads adhd.config.ts and globals.css at request time, renders a token catalog (colors / spacing / typography / radius / shadows) plus per-component pages with URL-driven prop toggles. Optionally excluded from production builds via Next.js pageExtensions trick. Re-runnable: marker-comment detection drives updates."
+disable-model-invocation: true
+argument-hint: ""
+allowed-tools: Read Write Edit Bash AskUserQuestion
+---
+
+# ADHD Install Design System Docs Route
+
+One-shot installer that drops a live design-system docs page into a Next.js App Router project. The page reads `adhd.config.ts` and `globals.css` at request time — no regen needed when components or tokens change. Re-running this skill picks up template improvements over time.
+
+**Authoritative spec:** `docs/superpowers/specs/2026-05-11-adhd-install-design-system-docs-route.md`
+
+## Invariants
+
+1. **No ADHD references in generated files** outside of import paths pointing at `adhd.config.ts`. The marker comment is generic.
+2. **adhd.config.ts is NOT modified** by this skill. Install choices live in the filesystem.
+3. **All file writes are idempotent on re-run.** Marker-bearing files are replaced wholesale with the latest templates. Files where the user deleted the marker are left alone.
+
+## Phase 1: Validate consumer environment
+
+```bash
+test -f adhd.config.ts || { echo "Missing adhd.config.ts. Run /adhd:config first."; exit 1; }
+test -d app          || { echo "Missing app/ directory. This installer requires the Next.js App Router."; exit 1; }
+test -f package.json || { echo "No package.json at the working directory."; exit 1; }
+```
+
+Read `package.json` and confirm `next` is in `dependencies` or `devDependencies`. Warn if missing or version < 16; continue anyway.
+
+## Phase 2: Detect existing install
+
+```bash
+node plugins/adhd/lib/install-design-system-docs-route/cli.js detect-install --app-dir .
+```
+
+Output is newline-separated paths of files containing the marker comment.
+
+- **No matches:** fresh install. Proceed to Phase 3 with defaults.
+- **One or more matches:** use `AskUserQuestion`:
+  - "Update in place" — re-write the listed marker-bearing files with the latest templates.
+  - "Move to new location" — Phase 3 reasks the install questions; files at the old location are NOT deleted (the user manages them).
+  - "Abort" — exit with no changes.
+
+If user chose "Update in place," skip ahead to Phase 6 (patch + write) using the existing folder's group/segment as the choice; ask only "Exclude from production builds?" to confirm current state.
+
+## Phase 3: Ask installation choices
+
+Use `AskUserQuestion` three times:
+
+1. **Route URL** — default `/-docs`. Validate: starts with `/`, only `a-z0-9-/` characters, no leading `_`.
+2. **Route group** — default `(design-system)`. Validate: parens-wrapped, alphanumerics + hyphens inside, OR empty string for "no group."
+3. **Exclude from production builds?** — default `Yes`.
+
+Derive `groupName` and `routeSegment` from these answers. Example: routeUrl `/-docs` → routeSegment `-docs`. The group is independent of the URL.
+
+## Phase 4: Detect Next.js config file
+
+```bash
+for f in next.config.ts next.config.mjs next.config.js; do
+  test -f "$f" && echo "$f" && break
+done
+```
+
+If none found: abort with "No next.config.* at the project root. Create one before running this installer."
+
+## Phase 5: Detect filesystem collisions
+
+```bash
+TARGET="app/${GROUP}/${SEGMENT}"
+test -e "$TARGET" && echo "EXISTS" || echo "FREE"
+```
+
+If `EXISTS` and Phase 2 didn't already mark this as an existing install: prompt "Path `<TARGET>` already exists but is not an installer artifact. Pick a different route or abort."
+
+## Phase 6: Patch next.config.ts (only if prod-exclusion: yes)
+
+```bash
+node plugins/adhd/lib/install-design-system-docs-route/cli.js patch-next-config \
+  --config "<next.config.path>" \
+  --route-url "<routeUrl>"
+```
+
+Exit code 3 means an existing different `pageExtensions` was detected. The CLI prints the existing value. Use `AskUserQuestion`: "Your next.config.ts sets pageExtensions to `<existing>`. Merge with the design-system extension conditional? [Yes / Show me the manual patch / Abort]."
+
+On "Yes": re-run the CLI without `detectOnly` (currently errors; for v1, print "Manual merge required. Patch the file to combine the existing pageExtensions with the conditional. Example:" and abort). On "Show me the manual patch": print the patch block and continue with file installs.
+
+## Phase 7: Write the page files
+
+```bash
+node plugins/adhd/lib/install-design-system-docs-route/cli.js install \
+  --config <choices.json>
+```
+
+Where `<choices.json>` is a temp file with shape:
+```json
+{
+  "projectRoot": ".",
+  "groupName": "(design-system)",
+  "routeSegment": "-docs",
+  "prodExcluded": true
+}
+```
+
+The CLI prints the list of files it wrote.
+
+## Phase 8: Patch robots.txt
+
+```bash
+node plugins/adhd/lib/install-design-system-docs-route/cli.js patch-robots \
+  --robots public/robots.txt \
+  --route-url "<routeUrl>"
+```
+
+If `public/` doesn't exist, create it first:
+```bash
+mkdir -p public
+```
+
+## Phase 9: Final report
+
+Print:
+```
+✓ Design system docs route installed.
+
+  URL:            http://localhost:3000<routeUrl>
+  Filesystem:     app/<group>/<segment>/
+  Prod exclusion: <ON | OFF>
+  noindex meta:   ON
+  robots.txt:     Disallow added
+
+Run `npm run dev` and visit the URL to preview. The page reads adhd.config.ts
+and globals.css at request time — no regen needed when you add components or
+tokens.
+
+Re-run /adhd:install-design-system-docs-route to pick up improved templates
+over time. Files where you've removed the marker comment will be left alone.
+```
+
+## Common errors
+
+| Error | Fix-up |
+|---|---|
+| `Missing adhd.config.ts` | Run `/adhd:config` first. |
+| `Missing app/ directory` | This installer requires the Next.js App Router (not Pages Router). |
+| `No next.config.* at the project root` | Create one with a default export of `{}`. |
+| `Path <X> already exists but is not an installer artifact` | Pick a different route URL or move/delete the existing folder. |
+| `next.config.ts sets pageExtensions to <existing>` | Manually merge with the design-system conditional, or skip prod-exclusion. |
+````
+
+- [ ] **Step 2: Validate SKILL frontmatter**
+
+Run: `node scripts/validate-skill-frontmatter.js`
+Expected: PASS — frontmatter valid; all SKILLs accounted for.
+
+- [ ] **Step 3: Commit**
+
+```bash
+git add plugins/adhd/skills/install-design-system-docs-route/
+git commit -m "Add /adhd:install-design-system-docs-route skill"
+```
+
+---
+
+## Task 11: /adhd:config integration — optional final phase
+
+**Files:**
+- Modify: `plugins/adhd/skills/config/SKILL.md`
+
+- [ ] **Step 1: Read the current SKILL.md to find the insertion point**
+
+The config skill ends with Phase 5 (Report). The new phase goes after Phase 5, before any "Common errors" or "Reference" sections.
+
+- [ ] **Step 2: Insert the new optional phase**
+
+Add to `plugins/adhd/skills/config/SKILL.md` after the existing Phase 5:
+
+```markdown
+## Phase 6 (optional): Set up the design-system docs route
+
+Use `AskUserQuestion`:
+
+```
+Question: "Set up the design-system docs route now? It's a live, self-generating
+documentation page that reads your adhd.config.ts and globals.css. Mini-Storybook
+for designers; not indexed by search engines."
+Header: "Docs route"
+Options:
+  - "Yes, install it now"
+  - "No, maybe later"
+```
+
+On "Yes": execute the phases of `/adhd:install-design-system-docs-route` inline.
+See `plugins/adhd/skills/install-design-system-docs-route/SKILL.md` for the
+detailed phase list (validate environment → detect existing install → ask install
+choices → detect Next.js config → detect collisions → patch next.config.ts →
+write files → patch robots.txt → final report).
+
+On "No": print `Run /adhd:install-design-system-docs-route later to set it up.`
+Exit normally.
+```
+
+- [ ] **Step 3: Validate frontmatter still passes**
+
+Run: `node scripts/validate-skill-frontmatter.js`
+Expected: PASS.
+
+- [ ] **Step 4: Commit**
+
+```bash
+git add plugins/adhd/skills/config/SKILL.md
+git commit -m "config: offer to install the design-system docs route as an optional final phase"
+```
+
+---
+
+## Task 12: README + marketplace updates
+
+**Files:**
+- Modify: `README.md`
+- Modify: `.claude-plugin/marketplace.json`
+
+- [ ] **Step 1: Update the command table**
+
+In `README.md`, change `After install, six slash commands are available:` → `After install, seven slash commands are available:`.
+
+Add a row to the command table after `/adhd:pull-component`:
+
+```
+| `/adhd:install-design-system-docs-route` | — | install | One-shot installer for a live, self-generating design-system docs route in your Next.js consumer app. Reads adhd.config.ts + globals.css at request time. Excluded from production builds by default. |
+```
+
+- [ ] **Step 2: Add a "Design system docs route" subsection**
+
+After the existing "Pull a component" subsection, add:
+
+```markdown
+### Design system docs route
+
+Run once in your consumer repo:
+
+```
+/adhd:install-design-system-docs-route
+```
+
+This installs a live, self-generating documentation page that reads your
+`adhd.config.ts` and `globals.css` at request time. The default URL is
+`/-docs` (the hyphen prefix telegraphs "internal"), and files live under a
+Next.js route group at `app/(design-system)/-docs/`. The page shows:
+
+- Token catalog: every color / spacing / typography / radius / shadow in your
+  Tailwind v4 `@theme` block, rendered as visual samples.
+- Component pages: each component from `adhd.config.ts`'s `components.*` map
+  gets its own route with URL-driven prop toggles.
+
+By default the route is excluded from production builds via Next.js's
+`pageExtensions` trick — files use the `.design-system.tsx` extension and
+the production build literally doesn't see them. You can opt out at install
+time if you'd rather ship the route (it still has `<meta name="robots"
+content="noindex, nofollow" />` either way).
+
+Re-run the installer over time to pick up improved templates. Files you've
+customized — by removing the `// design-system-docs-route` marker comment —
+are left alone.
+
+You can also trigger the install at the end of `/adhd:config` if you're
+setting up ADHD for the first time.
+```
+
+- [ ] **Step 3: Update marketplace.json description**
+
+Read the file. Update the `adhd` plugin's description to mention the new install command. Preserve existing phrasing style.
+
+- [ ] **Step 4: Commit**
+
+```bash
+git add README.md .claude-plugin/marketplace.json
+git commit -m "README + marketplace: document /adhd:install-design-system-docs-route"
+```
+
+---
+
+## Task 13: Final verification + PR
+
+- [ ] **Step 1: Run all lib tests**
+
+```bash
+node --test plugins/adhd/lib/lint-engine/__tests__/ \
+            plugins/adhd/lib/design-system/__tests__/ \
+            plugins/adhd/lib/push-component/__tests__/ \
+            plugins/adhd/lib/pull-component/__tests__/ \
+            plugins/adhd/lib/install-design-system-docs-route/__tests__/
+```
+
+Expected: all pass. New tests added: ~47 (3 cli stub + 8 token + 8 prop + 6 slug + 5 next-config + 5 robots + 10 templates + 8 route-installer + 7 cli wiring = ~60 total in the new lib).
+
+- [ ] **Step 2: Run the SKILL frontmatter validator**
+
+```bash
+node scripts/validate-skill-frontmatter.js
+```
+
+Expected: PASS, 7/7 skills valid (config, lint, pull-component, pull-design-system, push-component, push-design-system, install-design-system-docs-route).
+
+- [ ] **Step 3: Build the example app to sanity-check**
+
+```bash
+cd example && npm run build && cd ..
+```
+
+Expected: compile clean.
+
+- [ ] **Step 4: Push the branch**
+
+```bash
+git push -u origin adhd/install-design-system-docs-route
+```
+
+- [ ] **Step 5: Open the PR**
+
+```bash
+gh pr create --title "Add /adhd:install-design-system-docs-route skill" --body "$(cat <<'EOF'
+## Summary
+
+Adds /adhd:install-design-system-docs-route — a one-shot installer that drops a live, self-generating design-system documentation route into a Next.js consumer app. The route reads adhd.config.ts and globals.css at request time, renders a token catalog (colors / spacing / typography / radius / shadows) plus per-component pages with URL-driven prop toggles.
+
+## Key design choices
+
+- **Pure one-shot install.** No adhd.config.ts schema additions — install choices (route URL, route group, prod-exclusion) live in the filesystem.
+- **Route group `(design-system)` + hyphen-prefix URL `/-docs` by default.** Group organizes future internal routes filesystem-side; hyphen prefix telegraphs "internal."
+- **Production exclusion via Next.js pageExtensions conditional.** Files use `.design-system.tsx` extension; next.config.ts patched to include the extension only when NODE_ENV !== 'production'. Files literally invisible to the production build.
+- **Ejection-friendly.** Generated files contain zero references to "ADHD." Marker comment is generic.
+- **Re-runnable.** Marker-bearing files get replaced with the latest templates on re-run; user can opt OUT of overwrites by deleting the marker.
+- **Triggered as optional final phase of /adhd:config** for first-time setup. Available standalone for retroactive install.
+
+## Test plan
+
+- [x] ~60 new unit tests across token-parser, prop-parser, slug, next-config-patcher, robots-patcher, templates, route-installer, cli
+- [x] Full lib suite green
+- [x] 7/7 SKILL frontmatters valid
+- [x] Example app builds clean
+- [ ] Manual smoke test in example/: install → npm run dev → visit /-docs → click into a component → toggle props → npm run build → npm start → confirm /-docs returns 404
+
+🤖 Generated with [Claude Code](https://claude.com/claude-code)
+EOF
+)"
+```
+
+Expected: PR URL printed.
+
+- [ ] **Step 6: Verify CI is green**
+
+```bash
+sleep 30 && gh pr checks $(gh pr view --json number -q .number)
+```
+
+Expected: all checks pass.
+
+---
+
+## Self-review
+
+**Spec coverage:**
+
+| Spec section / criterion | Task |
+|---|---|
+| Skill command surface | Task 10 (SKILL), Task 12 (README) |
+| File layout in consumer app | Task 7 (templates), Task 8 (route-installer) |
+| Route group + hyphen URL defaults | Task 8 (installRoute), Task 10 (SKILL Phase 3) |
+| File extensions (.design-system.tsx vs .tsx) | Task 8 (installRoute logic) |
+| Marker comment | Task 7 (templates MARKER_COMMENT), Task 8 (detectExistingInstall) |
+| Pipeline Phase 1 (Validate environment) | Task 10 |
+| Pipeline Phase 2 (Detect existing install) | Task 8 (detectExistingInstall), Task 10 (SKILL Phase 2) |
+| Pipeline Phase 3 (Ask choices) | Task 10 |
+| Pipeline Phase 4 (Detect next.config) | Task 10 |
+| Pipeline Phase 5 (Detect collisions) | Task 10 |
+| Pipeline Phase 6 (Patch next.config) | Task 5 (next-config-patcher), Task 10 |
+| Pipeline Phase 7 (Write files) | Task 8 (route-installer), Task 10 |
+| Pipeline Phase 8 (Patch robots.txt) | Task 6 (robots-patcher), Task 10 |
+| Pipeline Phase 9 (Report) | Task 10 |
+| Update semantics (re-run replaces marker-bearing) | Task 8 + Task 10 |
+| Token-parser behavior | Task 2 |
+| Prop-parser behavior | Task 3 |
+| Slug + collision | Task 4 |
+| /adhd:config integration | Task 11 |
+| README updates | Task 12 |
+| Marketplace description | Task 12 |
+| CI step | Task 1 |
+| Acceptance criteria 1-21 | Covered across Tasks 1-13 |
+
+No gaps.
+
+**Type / signature consistency:**
+
+- `parseTokens(css: string)` → `{ colors, spacing, typography, radius, shadows, unknown }` — Tasks 2, 7 (used in INDEX_PAGE_TSX template), 9
+- `parseProps(source: string)` → `{ componentName, props, unions }` — Tasks 3, 7 (used in COMPONENT_PAGE_TSX), 9
+- `slugFor(path: string)` → string; `slugMap(paths: string[])` → `{ [path]: slug }` — Tasks 4, 9
+- `patchNextConfig(source: string, opts?: { detectOnly: boolean })` → string OR `{ conflict, existing }` — Tasks 5, 9
+- `patchRobots(source: string | null, routeUrl: string)` → string — Tasks 6, 9
+- `installRoute(projectRoot: string, opts: { groupName, routeSegment, prodExcluded })` → `{ files: string[] }` — Tasks 8, 9
+- `detectExistingInstall(projectRoot: string)` → string[] — Tasks 8, 9
+- Marker comment string `design-system-docs-route — auto-generated installer artifact; safe to edit.` — consistent across templates, route-installer, SKILL.md
+
+**Placeholder scan:**
+
+Searched the plan for TODO/TBD/FIXME — only legitimate hits (e.g. inside code comments showing intentional behavior). No real placeholders.

From 47a4368e26740399048a1b27ab9947812bb17aa7 Mon Sep 17 00:00:00 2001
From: Hugh Francis <hughfrancis89@gmail.com>
Date: Mon, 11 May 2026 14:48:39 -0400
Subject: [PATCH 04/79] Scaffold lib/install-design-system-docs-route with cli
 stub

---
 .github/workflows/ci.yml                      |  2 ++
 .../README.md                                 | 18 ++++++++++
 .../__tests__/cli.test.js                     | 29 +++++++++++++++
 .../install-design-system-docs-route/cli.js   | 36 +++++++++++++++++++
 4 files changed, 85 insertions(+)
 create mode 100644 plugins/adhd/lib/install-design-system-docs-route/README.md
 create mode 100644 plugins/adhd/lib/install-design-system-docs-route/__tests__/cli.test.js
 create mode 100644 plugins/adhd/lib/install-design-system-docs-route/cli.js

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index f641179..79c021f 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -23,6 +23,8 @@ jobs:
         run: node --test plugins/adhd/lib/push-component/__tests__/
       - name: Run pull-component tests
         run: node --test plugins/adhd/lib/pull-component/__tests__/
+      - name: Run install-design-system-docs-route tests
+        run: node --test plugins/adhd/lib/install-design-system-docs-route/__tests__/
 
   hygiene:
     name: project hygiene
diff --git a/plugins/adhd/lib/install-design-system-docs-route/README.md b/plugins/adhd/lib/install-design-system-docs-route/README.md
new file mode 100644
index 0000000..24a96cb
--- /dev/null
+++ b/plugins/adhd/lib/install-design-system-docs-route/README.md
@@ -0,0 +1,18 @@
+# lib/install-design-system-docs-route
+
+Deterministic helpers for `/adhd:install-design-system-docs-route`. The
+skill (at `plugins/adhd/skills/install-design-system-docs-route/SKILL.md`)
+is the orchestrator; this library is the testable engine.
+
+Modules:
+- `token-parser.js` — extract design-system tokens from a globals.css `@theme` block
+- `prop-parser.js` — extract a component's prop interface
+- `slug.js` — component path → URL slug
+- `next-config-patcher.js` — idempotent patch of next.config.{ts,mjs,js}
+- `robots-patcher.js` — idempotent patch of public/robots.txt
+- `route-installer.js` — write the 4 generated files at the target path
+- `templates.js` — page template strings
+- `cli.js` — orchestrator surface invoked by SKILL.md
+
+See `docs/superpowers/specs/2026-05-11-adhd-install-design-system-docs-route.md`
+for the authoritative spec.
diff --git a/plugins/adhd/lib/install-design-system-docs-route/__tests__/cli.test.js b/plugins/adhd/lib/install-design-system-docs-route/__tests__/cli.test.js
new file mode 100644
index 0000000..4daf0f2
--- /dev/null
+++ b/plugins/adhd/lib/install-design-system-docs-route/__tests__/cli.test.js
@@ -0,0 +1,29 @@
+'use strict';
+
+const test = require('node:test');
+const assert = require('node:assert/strict');
+const { spawnSync } = require('node:child_process');
+const path = require('node:path');
+
+const CLI = path.resolve(__dirname, '..', 'cli.js');
+
+test('cli with --help prints subcommand usage and exits 0', () => {
+  const r = spawnSync('node', [CLI, '--help'], { encoding: 'utf8' });
+  assert.equal(r.status, 0);
+  assert.match(r.stdout, /Usage:/);
+  assert.match(r.stdout, /parse-tokens/);
+  assert.match(r.stdout, /parse-props/);
+  assert.match(r.stdout, /slug/);
+  assert.match(r.stdout, /patch-next-config/);
+  assert.match(r.stdout, /patch-robots/);
+  assert.match(r.stdout, /detect-install/);
+  assert.match(r.stdout, /install/);
+});
+
+test('cli with no args exits 2', () => {
+  assert.equal(spawnSync('node', [CLI], { encoding: 'utf8' }).status, 2);
+});
+
+test('cli with unknown subcommand exits 2', () => {
+  assert.equal(spawnSync('node', [CLI, 'unknown'], { encoding: 'utf8' }).status, 2);
+});
diff --git a/plugins/adhd/lib/install-design-system-docs-route/cli.js b/plugins/adhd/lib/install-design-system-docs-route/cli.js
new file mode 100644
index 0000000..5dd68ea
--- /dev/null
+++ b/plugins/adhd/lib/install-design-system-docs-route/cli.js
@@ -0,0 +1,36 @@
+#!/usr/bin/env node
+'use strict';
+
+function parseArgs(argv) {
+  const args = { _: [] };
+  for (let i = 2; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '--help' || a === '-h') { args.help = true; continue; }
+    if (a.startsWith('--')) { args[a.slice(2)] = argv[++i]; }
+    else { args._.push(a); }
+  }
+  return args;
+}
+
+function printUsage() {
+  console.log(`Usage:
+  cli.js parse-tokens --css <path> --output <json>
+  cli.js parse-props --source <component.tsx> --output <json>
+  cli.js slug --paths <comma-separated> --output <json>
+  cli.js patch-next-config --config <path> --route-url <url>
+  cli.js patch-robots --robots <path> --route-url <url>
+  cli.js detect-install --app-dir <path>
+  cli.js install --config <choices.json>`);
+}
+
+function main() {
+  const args = parseArgs(process.argv);
+  if (args.help) { printUsage(); process.exit(0); }
+  if (args._.length === 0) { printUsage(); process.exit(2); }
+  const cmd = args._[0];
+  // Subcommands wired in later tasks. Reject unknown to keep behavior strict.
+  console.error('Unknown subcommand: ' + cmd);
+  process.exit(2);
+}
+
+main();

From 8c37cbafb9dcf33e4d1fc334641323110430bb45 Mon Sep 17 00:00:00 2001
From: Hugh Francis <hughfrancis89@gmail.com>
Date: Mon, 11 May 2026 14:51:39 -0400
Subject: [PATCH 05/79] token-parser: extract
 colors/spacing/typography/radius/shadows from globals.css @theme

---
 .../__fixtures__/globals.css                  | 22 +++++
 .../__tests__/token-parser.test.js            | 80 +++++++++++++++++
 .../token-parser.js                           | 89 +++++++++++++++++++
 3 files changed, 191 insertions(+)
 create mode 100644 plugins/adhd/lib/install-design-system-docs-route/__fixtures__/globals.css
 create mode 100644 plugins/adhd/lib/install-design-system-docs-route/__tests__/token-parser.test.js
 create mode 100644 plugins/adhd/lib/install-design-system-docs-route/token-parser.js

diff --git a/plugins/adhd/lib/install-design-system-docs-route/__fixtures__/globals.css b/plugins/adhd/lib/install-design-system-docs-route/__fixtures__/globals.css
new file mode 100644
index 0000000..df82b02
--- /dev/null
+++ b/plugins/adhd/lib/install-design-system-docs-route/__fixtures__/globals.css
@@ -0,0 +1,22 @@
+@import "tailwindcss";
+
+@theme {
+  --color-zinc-50: oklch(0.985 0 0);
+  --color-zinc-900: oklch(0.21 0.034 264.665);
+  --color-brand-500: #5e3aee;
+
+  --spacing: 0.25rem;
+
+  --text-xs: 0.75rem;
+  --text-xs--line-height: 1rem;
+  --text-base: 1rem;
+  --text-base--line-height: 1.5rem;
+
+  --radius-sm: 0.25rem;
+  --radius-lg: 0.5rem;
+
+  --shadow-sm: 0 1px 2px 0 rgb(0 0 0 / 0.05);
+  --shadow-md: 0 4px 6px -1px rgb(0 0 0 / 0.1);
+
+  --font-sans: "Inter", system-ui, sans-serif;
+}
diff --git a/plugins/adhd/lib/install-design-system-docs-route/__tests__/token-parser.test.js b/plugins/adhd/lib/install-design-system-docs-route/__tests__/token-parser.test.js
new file mode 100644
index 0000000..7423f5c
--- /dev/null
+++ b/plugins/adhd/lib/install-design-system-docs-route/__tests__/token-parser.test.js
@@ -0,0 +1,80 @@
+'use strict';
+
+const test = require('node:test');
+const assert = require('node:assert/strict');
+const fs = require('node:fs');
+const path = require('node:path');
+const { parseTokens } = require('../token-parser');
+
+const CSS = fs.readFileSync(
+  path.resolve(__dirname, '..', '__fixtures__', 'globals.css'),
+  'utf8',
+);
+
+test('extracts color tokens', () => {
+  const t = parseTokens(CSS);
+  assert.deepEqual(
+    t.colors.find(c => c.name === 'zinc-50'),
+    { name: 'zinc-50', value: 'oklch(0.985 0 0)' },
+  );
+  assert.deepEqual(
+    t.colors.find(c => c.name === 'brand-500'),
+    { name: 'brand-500', value: '#5e3aee' },
+  );
+});
+
+test('extracts the spacing multiplier', () => {
+  const t = parseTokens(CSS);
+  assert.equal(t.spacing.multiplier, '0.25rem');
+});
+
+test('extracts typography sizes with optional line-heights', () => {
+  const t = parseTokens(CSS);
+  assert.deepEqual(
+    t.typography.find(x => x.name === 'xs'),
+    { name: 'xs', size: '0.75rem', lineHeight: '1rem' },
+  );
+  assert.deepEqual(
+    t.typography.find(x => x.name === 'base'),
+    { name: 'base', size: '1rem', lineHeight: '1.5rem' },
+  );
+});
+
+test('extracts radius tokens', () => {
+  const t = parseTokens(CSS);
+  assert.deepEqual(
+    t.radius.find(r => r.name === 'sm'),
+    { name: 'sm', value: '0.25rem' },
+  );
+});
+
+test('extracts shadow tokens', () => {
+  const t = parseTokens(CSS);
+  assert.deepEqual(
+    t.shadows.find(s => s.name === 'sm'),
+    { name: 'sm', value: '0 1px 2px 0 rgb(0 0 0 / 0.05)' },
+  );
+});
+
+test('puts unrecognized @theme vars in `unknown`', () => {
+  const t = parseTokens(CSS);
+  assert.ok(t.unknown.find(u => u.name === '--font-sans'));
+});
+
+test('returns empty domains when no @theme block exists', () => {
+  const t = parseTokens('body { color: red; }');
+  assert.deepEqual(t.colors, []);
+  assert.deepEqual(t.typography, []);
+  assert.deepEqual(t.radius, []);
+  assert.deepEqual(t.shadows, []);
+  assert.equal(t.spacing.multiplier, null);
+});
+
+test('handles multiple @theme blocks (merge)', () => {
+  const css = `
+@theme { --color-a-100: #fff; }
+@theme { --color-b-200: #000; }
+`;
+  const t = parseTokens(css);
+  assert.equal(t.colors.length, 2);
+});
diff --git a/plugins/adhd/lib/install-design-system-docs-route/token-parser.js b/plugins/adhd/lib/install-design-system-docs-route/token-parser.js
new file mode 100644
index 0000000..b553a38
--- /dev/null
+++ b/plugins/adhd/lib/install-design-system-docs-route/token-parser.js
@@ -0,0 +1,89 @@
+'use strict';
+
+// Extracts a single @theme block's body, or null. Brace-balanced across nested objects.
+function extractAllThemeBodies(css) {
+  const bodies = [];
+  let i = 0;
+  while (i < css.length) {
+    const idx = css.indexOf('@theme', i);
+    if (idx === -1) break;
+    // Skip whitespace + optional modifiers like @theme inline
+    let j = idx + '@theme'.length;
+    while (j < css.length && css[j] !== '{' && css[j] !== ';') j++;
+    if (css[j] !== '{') { i = j + 1; continue; }
+    // Brace-balanced scan
+    let depth = 1;
+    let k = j + 1;
+    while (k < css.length && depth > 0) {
+      if (css[k] === '{') depth++;
+      else if (css[k] === '}') depth--;
+      if (depth > 0) k++;
+    }
+    bodies.push(css.slice(j + 1, k));
+    i = k + 1;
+  }
+  return bodies;
+}
+
+const DECL_RE = /--([a-zA-Z0-9_-]+)\s*:\s*([^;]+);/g;
+
+function classify(name) {
+  if (name.startsWith('color-')) return { domain: 'colors', leaf: name.slice('color-'.length) };
+  if (name === 'spacing') return { domain: 'spacing', leaf: null };
+  if (name.startsWith('text-')) {
+    // text-xs or text-xs--line-height
+    const rest = name.slice('text-'.length);
+    const lhIdx = rest.indexOf('--line-height');
+    if (lhIdx >= 0) return { domain: 'typography', leaf: rest.slice(0, lhIdx), kind: 'lineHeight' };
+    return { domain: 'typography', leaf: rest, kind: 'size' };
+  }
+  if (name.startsWith('radius-')) return { domain: 'radius', leaf: name.slice('radius-'.length) };
+  if (name.startsWith('shadow-')) return { domain: 'shadows', leaf: name.slice('shadow-'.length) };
+  return { domain: 'unknown' };
+}
+
+function parseTokens(globalsCss) {
+  const out = {
+    colors: [],
+    spacing: { multiplier: null },
+    typography: [], // [{ name, size, lineHeight }]
+    radius: [],
+    shadows: [],
+    unknown: [],
+  };
+  const typographyByName = new Map();
+
+  for (const body of extractAllThemeBodies(globalsCss)) {
+    DECL_RE.lastIndex = 0;
+    let m;
+    while ((m = DECL_RE.exec(body)) !== null) {
+      const name = m[1];
+      const value = m[2].trim();
+      const cls = classify(name);
+      if (cls.domain === 'colors') {
+        out.colors.push({ name: cls.leaf, value });
+      } else if (cls.domain === 'spacing') {
+        out.spacing.multiplier = value;
+      } else if (cls.domain === 'typography') {
+        let row = typographyByName.get(cls.leaf);
+        if (!row) {
+          row = { name: cls.leaf, size: null, lineHeight: null };
+          typographyByName.set(cls.leaf, row);
+          out.typography.push(row);
+        }
+        if (cls.kind === 'lineHeight') row.lineHeight = value;
+        else row.size = value;
+      } else if (cls.domain === 'radius') {
+        out.radius.push({ name: cls.leaf, value });
+      } else if (cls.domain === 'shadows') {
+        out.shadows.push({ name: cls.leaf, value });
+      } else {
+        out.unknown.push({ name: '--' + name, value });
+      }
+    }
+  }
+
+  return out;
+}
+
+module.exports = { parseTokens };

From b3e937234f19d4239ef0d8cae949b62303151ec8 Mon Sep 17 00:00:00 2001
From: Hugh Francis <hughfrancis89@gmail.com>
Date: Mon, 11 May 2026 14:54:05 -0400
Subject: [PATCH 06/79] token-parser: clarify @theme parsing assumptions and
 switch on domain

Conservative simplification pass on the new token parser:

- Replace the if/else-if chain in parseTokens with a switch on cls.domain
  to match the project preference for explicit, flat control flow.
- Factor the typography row upsert into a named helper so the size +
  line-height merge invariant has a clear home.
- Add why-comments documenting (a) why a naive brace counter is safe for
  Tailwind v4 @theme blocks (declarations only, no nested rules), (b) why
  DECL_RE.lastIndex is reset each loop (module-scoped /g regex), and
  (c) how Tailwind's --line-height suffix pairs onto the same family.
- Replace the indexOf('--line-height') check in classify with endsWith
  against a named constant; the suffix is always a suffix in v4.
- Fix a stale comment that described extractAllThemeBodies as returning
  a single body / null when it returns an array.

No behavior change. All 8 token-parser tests pass; full 294-test lib
suite still green.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 .../token-parser.js                           | 101 ++++++++++++------
 1 file changed, 71 insertions(+), 30 deletions(-)

diff --git a/plugins/adhd/lib/install-design-system-docs-route/token-parser.js b/plugins/adhd/lib/install-design-system-docs-route/token-parser.js
index b553a38..358e59b 100644
--- a/plugins/adhd/lib/install-design-system-docs-route/token-parser.js
+++ b/plugins/adhd/lib/install-design-system-docs-route/token-parser.js
@@ -1,17 +1,24 @@
 'use strict';
 
-// Extracts a single @theme block's body, or null. Brace-balanced across nested objects.
+// Returns the body text of every `@theme { ... }` block found in `css`.
+// A Tailwind v4 `@theme` block contains flat `--name: value;` declarations
+// only (no nested rules), so a naive brace counter is sufficient — we don't
+// need the string/comment-aware scanner used in lib/pull-component.
+// `@theme inline { ... }` and other modifiers between `@theme` and `{` are
+// supported by skipping forward to the first `{`.
 function extractAllThemeBodies(css) {
   const bodies = [];
   let i = 0;
   while (i < css.length) {
     const idx = css.indexOf('@theme', i);
     if (idx === -1) break;
-    // Skip whitespace + optional modifiers like @theme inline
+    // Skip forward to the block-opening `{`, tolerating modifiers like `inline`.
     let j = idx + '@theme'.length;
     while (j < css.length && css[j] !== '{' && css[j] !== ';') j++;
-    if (css[j] !== '{') { i = j + 1; continue; }
-    // Brace-balanced scan
+    if (css[j] !== '{') {
+      i = j + 1;
+      continue;
+    }
     let depth = 1;
     let k = j + 1;
     while (k < css.length && depth > 0) {
@@ -25,20 +32,41 @@ function extractAllThemeBodies(css) {
   return bodies;
 }
 
+// Matches a single `--name: value;` declaration. The `name` capture excludes
+// the leading `--`; the `value` capture is everything up to the next `;`.
 const DECL_RE = /--([a-zA-Z0-9_-]+)\s*:\s*([^;]+);/g;
 
+// Tailwind v4 typography pairs size + line-height under the same family name
+// via a `--line-height` suffix on the variable:
+//   --text-xs: 0.75rem;             ← size
+//   --text-xs--line-height: 1rem;   ← line-height of the same `xs` row
+// We split on the suffix so callers see one row per family name.
+const LINE_HEIGHT_SUFFIX = '--line-height';
+
 function classify(name) {
-  if (name.startsWith('color-')) return { domain: 'colors', leaf: name.slice('color-'.length) };
-  if (name === 'spacing') return { domain: 'spacing', leaf: null };
+  if (name.startsWith('color-')) {
+    return { domain: 'colors', leaf: name.slice('color-'.length) };
+  }
+  if (name === 'spacing') {
+    return { domain: 'spacing', leaf: null };
+  }
   if (name.startsWith('text-')) {
-    // text-xs or text-xs--line-height
     const rest = name.slice('text-'.length);
-    const lhIdx = rest.indexOf('--line-height');
-    if (lhIdx >= 0) return { domain: 'typography', leaf: rest.slice(0, lhIdx), kind: 'lineHeight' };
+    if (rest.endsWith(LINE_HEIGHT_SUFFIX)) {
+      return {
+        domain: 'typography',
+        leaf: rest.slice(0, -LINE_HEIGHT_SUFFIX.length),
+        kind: 'lineHeight',
+      };
+    }
     return { domain: 'typography', leaf: rest, kind: 'size' };
   }
-  if (name.startsWith('radius-')) return { domain: 'radius', leaf: name.slice('radius-'.length) };
-  if (name.startsWith('shadow-')) return { domain: 'shadows', leaf: name.slice('shadow-'.length) };
+  if (name.startsWith('radius-')) {
+    return { domain: 'radius', leaf: name.slice('radius-'.length) };
+  }
+  if (name.startsWith('shadow-')) {
+    return { domain: 'shadows', leaf: name.slice('shadow-'.length) };
+  }
   return { domain: 'unknown' };
 }
 
@@ -51,34 +79,47 @@ function parseTokens(globalsCss) {
     shadows: [],
     unknown: [],
   };
+  // Tracks typography rows by family name so size + line-height (which arrive
+  // as two separate declarations) merge into a single output row.
   const typographyByName = new Map();
 
+  function upsertTypography(leaf, kind, value) {
+    let row = typographyByName.get(leaf);
+    if (!row) {
+      row = { name: leaf, size: null, lineHeight: null };
+      typographyByName.set(leaf, row);
+      out.typography.push(row);
+    }
+    if (kind === 'lineHeight') row.lineHeight = value;
+    else row.size = value;
+  }
+
   for (const body of extractAllThemeBodies(globalsCss)) {
+    // Reset lastIndex because DECL_RE is module-scoped and stateful (`/g`).
     DECL_RE.lastIndex = 0;
     let m;
     while ((m = DECL_RE.exec(body)) !== null) {
       const name = m[1];
       const value = m[2].trim();
       const cls = classify(name);
-      if (cls.domain === 'colors') {
-        out.colors.push({ name: cls.leaf, value });
-      } else if (cls.domain === 'spacing') {
-        out.spacing.multiplier = value;
-      } else if (cls.domain === 'typography') {
-        let row = typographyByName.get(cls.leaf);
-        if (!row) {
-          row = { name: cls.leaf, size: null, lineHeight: null };
-          typographyByName.set(cls.leaf, row);
-          out.typography.push(row);
-        }
-        if (cls.kind === 'lineHeight') row.lineHeight = value;
-        else row.size = value;
-      } else if (cls.domain === 'radius') {
-        out.radius.push({ name: cls.leaf, value });
-      } else if (cls.domain === 'shadows') {
-        out.shadows.push({ name: cls.leaf, value });
-      } else {
-        out.unknown.push({ name: '--' + name, value });
+      switch (cls.domain) {
+        case 'colors':
+          out.colors.push({ name: cls.leaf, value });
+          break;
+        case 'spacing':
+          out.spacing.multiplier = value;
+          break;
+        case 'typography':
+          upsertTypography(cls.leaf, cls.kind, value);
+          break;
+        case 'radius':
+          out.radius.push({ name: cls.leaf, value });
+          break;
+        case 'shadows':
+          out.shadows.push({ name: cls.leaf, value });
+          break;
+        default:
+          out.unknown.push({ name: '--' + name, value });
       }
     }
   }

From c8974520719acaaf00abaf5e6c0a433b8b54c336 Mon Sep 17 00:00:00 2001
From: Hugh Francis <hughfrancis89@gmail.com>
Date: Mon, 11 May 2026 14:55:29 -0400
Subject: [PATCH 07/79] prop-parser: extract component prop interface (unions,
 primitives, optional flag)

---
 .../__fixtures__/avatar.tsx                   | 18 +++++
 .../__tests__/prop-parser.test.js             | 62 ++++++++++++++++
 .../prop-parser.js                            | 74 +++++++++++++++++++
 3 files changed, 154 insertions(+)
 create mode 100644 plugins/adhd/lib/install-design-system-docs-route/__fixtures__/avatar.tsx
 create mode 100644 plugins/adhd/lib/install-design-system-docs-route/__tests__/prop-parser.test.js
 create mode 100644 plugins/adhd/lib/install-design-system-docs-route/prop-parser.js

diff --git a/plugins/adhd/lib/install-design-system-docs-route/__fixtures__/avatar.tsx b/plugins/adhd/lib/install-design-system-docs-route/__fixtures__/avatar.tsx
new file mode 100644
index 0000000..b03e749
--- /dev/null
+++ b/plugins/adhd/lib/install-design-system-docs-route/__fixtures__/avatar.tsx
@@ -0,0 +1,18 @@
+export type AvatarSize = "xs" | "sm" | "md" | "lg" | "xl";
+export type AvatarShape = "circle" | "square";
+
+export interface AvatarProps {
+  name: string;
+  src?: string;
+  size?: AvatarSize;
+  shape?: AvatarShape;
+  status?: "online" | "away" | "offline";
+  count?: number;
+  hidden?: boolean;
+  onClick?: (e: React.MouseEvent) => void;
+  children?: React.ReactNode;
+}
+
+export function Avatar({ name, size = "md" }: AvatarProps) {
+  return <span>{name}</span>;
+}
diff --git a/plugins/adhd/lib/install-design-system-docs-route/__tests__/prop-parser.test.js b/plugins/adhd/lib/install-design-system-docs-route/__tests__/prop-parser.test.js
new file mode 100644
index 0000000..e4defef
--- /dev/null
+++ b/plugins/adhd/lib/install-design-system-docs-route/__tests__/prop-parser.test.js
@@ -0,0 +1,62 @@
+'use strict';
+
+const test = require('node:test');
+const assert = require('node:assert/strict');
+const fs = require('node:fs');
+const path = require('node:path');
+const { parseProps } = require('../prop-parser');
+
+const SOURCE = fs.readFileSync(
+  path.resolve(__dirname, '..', '__fixtures__', 'avatar.tsx'),
+  'utf8',
+);
+
+test('returns the component name', () => {
+  const r = parseProps(SOURCE);
+  assert.equal(r.componentName, 'Avatar');
+});
+
+test('captures string props', () => {
+  const r = parseProps(SOURCE);
+  assert.deepEqual(r.props.name, { type: 'string', optional: false });
+  assert.deepEqual(r.props.src, { type: 'string', optional: true });
+});
+
+test('captures number and boolean props', () => {
+  const r = parseProps(SOURCE);
+  assert.deepEqual(r.props.count, { type: 'number', optional: true });
+  assert.deepEqual(r.props.hidden, { type: 'boolean', optional: true });
+});
+
+test('captures named-union references with their values', () => {
+  const r = parseProps(SOURCE);
+  assert.deepEqual(r.props.size, {
+    type: 'union', unionName: 'AvatarSize', values: ['xs', 'sm', 'md', 'lg', 'xl'], optional: true,
+  });
+  assert.deepEqual(r.props.shape, {
+    type: 'union', unionName: 'AvatarShape', values: ['circle', 'square'], optional: true,
+  });
+});
+
+test('captures inline literal unions', () => {
+  const r = parseProps(SOURCE);
+  assert.deepEqual(r.props.status, {
+    type: 'union', values: ['online', 'away', 'offline'], optional: true,
+  });
+});
+
+test('marks function props as `function` (toggle-skipped)', () => {
+  const r = parseProps(SOURCE);
+  assert.equal(r.props.onClick.type, 'function');
+});
+
+test('marks ReactNode props as `reactnode` (toggle-skipped)', () => {
+  const r = parseProps(SOURCE);
+  assert.equal(r.props.children.type, 'reactnode');
+});
+
+test('returns componentName=null when no exported function found', () => {
+  const r = parseProps('export const x = 42;');
+  assert.equal(r.componentName, null);
+  assert.deepEqual(r.props, {});
+});
diff --git a/plugins/adhd/lib/install-design-system-docs-route/prop-parser.js b/plugins/adhd/lib/install-design-system-docs-route/prop-parser.js
new file mode 100644
index 0000000..3d616b6
--- /dev/null
+++ b/plugins/adhd/lib/install-design-system-docs-route/prop-parser.js
@@ -0,0 +1,74 @@
+'use strict';
+
+const TYPE_ALIAS_RE = /export\s+type\s+([A-Z][A-Za-z0-9]*)\s*=\s*([^;]+);/g;
+const INTERFACE_RE = /(?:export\s+)?interface\s+([A-Z][A-Za-z0-9]*Props)\s*\{([\s\S]*?)\}/;
+const TYPE_PROPS_RE = /(?:export\s+)?type\s+([A-Z][A-Za-z0-9]*Props)\s*=\s*\{([\s\S]*?)\}/;
+const EXPORT_FN_RE = /export\s+(?:default\s+)?function\s+([A-Z][A-Za-z0-9]*)\s*\(/;
+const PROP_LINE_RE = /^\s*([a-zA-Z_$][a-zA-Z0-9_$]*)(\?)?\s*:\s*([^;,]+)[;,]?\s*$/;
+
+function parseLiteralUnion(typeText) {
+  const trimmed = typeText.trim();
+  if (!/^"[^"]*"(\s*\|\s*"[^"]*")*$/.test(trimmed)) return null;
+  return trimmed.split('|').map(s => {
+    const m = /"([^"]*)"/.exec(s.trim());
+    return m ? m[1] : null;
+  }).filter(Boolean);
+}
+
+function classify(typeText, knownUnions) {
+  const t = typeText.trim();
+  const inline = parseLiteralUnion(t);
+  if (inline) return { type: 'union', values: inline };
+  if (knownUnions[t]) return { type: 'union', unionName: t, values: knownUnions[t] };
+  if (/^\([^)]*\)\s*=>/.test(t)) return { type: 'function' };
+  if (/^(?:React\.)?Ref(?:Object|Callback|MutableRefObject)?</.test(t)) return { type: 'ref' };
+  if (/^(?:React\.)?(?:ReactNode|ReactElement|ReactChild)$/.test(t)) return { type: 'reactnode' };
+  if (/^JSX\.Element$/.test(t)) return { type: 'reactnode' };
+  if (/^(?:React\.)?ReactElement<.*>$/.test(t)) return { type: 'reactnode' };
+  if (t === 'string') return { type: 'string' };
+  if (t === 'number') return { type: 'number' };
+  if (t === 'boolean') return { type: 'boolean' };
+  if (/\[\]$/.test(t) || /^Array</.test(t) || /^ReadonlyArray</.test(t)) return { type: 'array' };
+  if (/^\{.*\}$/.test(t)) return { type: 'object' };
+  return { type: 'unknown' };
+}
+
+function parseProps(source) {
+  // Pass 1: collect known unions
+  const knownUnions = {};
+  TYPE_ALIAS_RE.lastIndex = 0;
+  let m;
+  while ((m = TYPE_ALIAS_RE.exec(source)) !== null) {
+    const name = m[1];
+    const body = m[2].trim();
+    const lit = parseLiteralUnion(body);
+    if (lit) knownUnions[name] = lit;
+  }
+
+  // Pass 2: locate component name
+  const fnMatch = EXPORT_FN_RE.exec(source);
+  const componentName = fnMatch ? fnMatch[1] : null;
+
+  // Pass 3: locate props block
+  let propsBody = null;
+  const ifaceMatch = INTERFACE_RE.exec(source);
+  const typeMatch = TYPE_PROPS_RE.exec(source);
+  if (ifaceMatch) propsBody = ifaceMatch[2];
+  else if (typeMatch) propsBody = typeMatch[2];
+
+  const props = {};
+  if (propsBody) {
+    for (const rawLine of propsBody.split('\n')) {
+      const line = rawLine.replace(/\/\/.*$/, '');
+      const pm = PROP_LINE_RE.exec(line);
+      if (!pm) continue;
+      const [, propName, optionalMark, typeText] = pm;
+      const cls = classify(typeText, knownUnions);
+      props[propName] = { ...cls, optional: !!optionalMark };
+    }
+  }
+
+  return { componentName, props, unions: knownUnions };
+}
+
+module.exports = { parseProps };

From 140745ca7055e04c4a7f9fe331112e6031e5f2c5 Mon Sep 17 00:00:00 2001
From: Hugh Francis <hughfrancis89@gmail.com>
Date: Mon, 11 May 2026 14:57:15 -0400
Subject: [PATCH 08/79] prop-parser: align names with push-component sibling

Rename parseLiteralUnion->parseUnionString, classify->classifyPropType,
and expand terse locals (m/pm/cls/optionalMark) so prop-parser reads
like push-component/parse-component.js. Behavior unchanged.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 .../prop-parser.js                            | 39 +++++++++----------
 1 file changed, 19 insertions(+), 20 deletions(-)

diff --git a/plugins/adhd/lib/install-design-system-docs-route/prop-parser.js b/plugins/adhd/lib/install-design-system-docs-route/prop-parser.js
index 3d616b6..f98d04e 100644
--- a/plugins/adhd/lib/install-design-system-docs-route/prop-parser.js
+++ b/plugins/adhd/lib/install-design-system-docs-route/prop-parser.js
@@ -6,19 +6,19 @@ const TYPE_PROPS_RE = /(?:export\s+)?type\s+([A-Z][A-Za-z0-9]*Props)\s*=\s*\{([\
 const EXPORT_FN_RE = /export\s+(?:default\s+)?function\s+([A-Z][A-Za-z0-9]*)\s*\(/;
 const PROP_LINE_RE = /^\s*([a-zA-Z_$][a-zA-Z0-9_$]*)(\?)?\s*:\s*([^;,]+)[;,]?\s*$/;
 
-function parseLiteralUnion(typeText) {
+function parseUnionString(typeText) {
   const trimmed = typeText.trim();
   if (!/^"[^"]*"(\s*\|\s*"[^"]*")*$/.test(trimmed)) return null;
-  return trimmed.split('|').map(s => {
+  return trimmed.split('|').map((s) => {
     const m = /"([^"]*)"/.exec(s.trim());
     return m ? m[1] : null;
   }).filter(Boolean);
 }
 
-function classify(typeText, knownUnions) {
+function classifyPropType(typeText, knownUnions) {
   const t = typeText.trim();
-  const inline = parseLiteralUnion(t);
-  if (inline) return { type: 'union', values: inline };
+  const inlineUnion = parseUnionString(t);
+  if (inlineUnion) return { type: 'union', values: inlineUnion };
   if (knownUnions[t]) return { type: 'union', unionName: t, values: knownUnions[t] };
   if (/^\([^)]*\)\s*=>/.test(t)) return { type: 'function' };
   if (/^(?:React\.)?Ref(?:Object|Callback|MutableRefObject)?</.test(t)) return { type: 'ref' };
@@ -37,12 +37,12 @@ function parseProps(source) {
   // Pass 1: collect known unions
   const knownUnions = {};
   TYPE_ALIAS_RE.lastIndex = 0;
-  let m;
-  while ((m = TYPE_ALIAS_RE.exec(source)) !== null) {
-    const name = m[1];
-    const body = m[2].trim();
-    const lit = parseLiteralUnion(body);
-    if (lit) knownUnions[name] = lit;
+  let aliasMatch;
+  while ((aliasMatch = TYPE_ALIAS_RE.exec(source)) !== null) {
+    const name = aliasMatch[1];
+    const body = aliasMatch[2].trim();
+    const values = parseUnionString(body);
+    if (values) knownUnions[name] = values;
   }
 
   // Pass 2: locate component name
@@ -50,21 +50,20 @@ function parseProps(source) {
   const componentName = fnMatch ? fnMatch[1] : null;
 
   // Pass 3: locate props block
-  let propsBody = null;
-  const ifaceMatch = INTERFACE_RE.exec(source);
+  const interfaceMatch = INTERFACE_RE.exec(source);
   const typeMatch = TYPE_PROPS_RE.exec(source);
-  if (ifaceMatch) propsBody = ifaceMatch[2];
-  else if (typeMatch) propsBody = typeMatch[2];
+  const propsBody = (interfaceMatch && interfaceMatch[2]) || (typeMatch && typeMatch[2]) || null;
 
   const props = {};
   if (propsBody) {
     for (const rawLine of propsBody.split('\n')) {
       const line = rawLine.replace(/\/\/.*$/, '');
-      const pm = PROP_LINE_RE.exec(line);
-      if (!pm) continue;
-      const [, propName, optionalMark, typeText] = pm;
-      const cls = classify(typeText, knownUnions);
-      props[propName] = { ...cls, optional: !!optionalMark };
+      const propMatch = PROP_LINE_RE.exec(line);
+      if (!propMatch) continue;
+      const [, propName, optionalMarker, typeText] = propMatch;
+      const optional = optionalMarker === '?';
+      const classified = classifyPropType(typeText, knownUnions);
+      props[propName] = { ...classified, optional };
     }
   }
 

From cc1079e22d98a98c4f421236336a60e9ac737a4e Mon Sep 17 00:00:00 2001
From: Hugh Francis <hughfrancis89@gmail.com>
Date: Mon, 11 May 2026 14:58:25 -0400
Subject: [PATCH 09/79] =?UTF-8?q?slug:=20component=20path=20=E2=86=92=20UR?=
 =?UTF-8?q?L=20slug=20+=20collision=20disambiguation?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 .../__tests__/slug.test.js                    | 43 +++++++++++++++++++
 .../install-design-system-docs-route/slug.js  | 41 ++++++++++++++++++
 2 files changed, 84 insertions(+)
 create mode 100644 plugins/adhd/lib/install-design-system-docs-route/__tests__/slug.test.js
 create mode 100644 plugins/adhd/lib/install-design-system-docs-route/slug.js

diff --git a/plugins/adhd/lib/install-design-system-docs-route/__tests__/slug.test.js b/plugins/adhd/lib/install-design-system-docs-route/__tests__/slug.test.js
new file mode 100644
index 0000000..333064c
--- /dev/null
+++ b/plugins/adhd/lib/install-design-system-docs-route/__tests__/slug.test.js
@@ -0,0 +1,43 @@
+'use strict';
+
+const test = require('node:test');
+const assert = require('node:assert/strict');
+const { slugFor, slugMap } = require('../slug');
+
+test('slugs a simple component path', () => {
+  assert.equal(slugFor('app/components/avatar/index.tsx'), 'avatar');
+});
+
+test('preserves hyphens', () => {
+  assert.equal(slugFor('app/components/avatar-group/index.tsx'), 'avatar-group');
+});
+
+test('handles files without /index.tsx', () => {
+  assert.equal(slugFor('app/components/Logo.tsx'), 'logo');
+});
+
+test('lowercases', () => {
+  assert.equal(slugFor('app/components/AvatarGroup/index.tsx'), 'avatargroup');
+});
+
+test('slugMap returns { path: slug } for unique paths', () => {
+  const paths = [
+    'app/components/avatar/index.tsx',
+    'app/components/avatar-group/index.tsx',
+  ];
+  assert.deepEqual(slugMap(paths), {
+    'app/components/avatar/index.tsx': 'avatar',
+    'app/components/avatar-group/index.tsx': 'avatar-group',
+  });
+});
+
+test('slugMap disambiguates collisions by prepending parent dir', () => {
+  const paths = [
+    'app/components/avatar/index.tsx',
+    'app/design-system/avatar/index.tsx',
+  ];
+  const m = slugMap(paths);
+  assert.equal(new Set(Object.values(m)).size, 2, 'slugs must be unique');
+  // Both contain "avatar"; we expect e.g. "components-avatar" and "design-system-avatar"
+  assert.ok(Object.values(m).every(s => s.includes('avatar')));
+});
diff --git a/plugins/adhd/lib/install-design-system-docs-route/slug.js b/plugins/adhd/lib/install-design-system-docs-route/slug.js
new file mode 100644
index 0000000..5a91ac0
--- /dev/null
+++ b/plugins/adhd/lib/install-design-system-docs-route/slug.js
@@ -0,0 +1,41 @@
+'use strict';
+
+function baseSlug(componentPath) {
+  // Strip /index.tsx or .tsx; take the last meaningful segment.
+  let p = componentPath.replace(/\\/g, '/').replace(/\.tsx?$/, '').replace(/\/index$/, '');
+  const segs = p.split('/').filter(Boolean);
+  return (segs[segs.length - 1] || '').toLowerCase();
+}
+
+function slugFor(componentPath) {
+  return baseSlug(componentPath);
+}
+
+function slugMap(paths) {
+  // Pass 1: tentative slugs
+  const tentative = paths.map(p => ({ path: p, slug: baseSlug(p) }));
+  // Pass 2: find collisions
+  const counts = {};
+  for (const t of tentative) counts[t.slug] = (counts[t.slug] || 0) + 1;
+  // Pass 3: resolve collisions by prepending the parent dir
+  for (const t of tentative) {
+    if (counts[t.slug] === 1) continue;
+    const segs = t.path.replace(/\\/g, '/').replace(/\.tsx?$/, '').replace(/\/index$/, '').split('/').filter(Boolean);
+    // Prepend one level of parent until unique
+    let depth = 2;
+    while (depth <= segs.length) {
+      const candidate = segs.slice(segs.length - depth).join('-').toLowerCase();
+      const colliders = tentative.filter(x => x !== t && x.slug === candidate).length;
+      if (colliders === 0) {
+        t.slug = candidate;
+        break;
+      }
+      depth++;
+    }
+  }
+  const out = {};
+  for (const t of tentative) out[t.path] = t.slug;
+  return out;
+}
+
+module.exports = { slugFor, slugMap };

From 71cd1cd2cdb8aea76159938d32efacb66b02f967 Mon Sep 17 00:00:00 2001
From: Hugh Francis <hughfrancis89@gmail.com>
Date: Mon, 11 May 2026 14:59:37 -0400
Subject: [PATCH 10/79] slug: extract pathSegments helper to dedupe path
 normalization

The strip-extension + strip-/index + split-on-slash chain ran in both
baseSlug and slugMap's collision branch. Pulled it into a single helper
so the two call sites share the same definition of "meaningful segments."

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 .../lib/install-design-system-docs-route/slug.js | 16 ++++++++++++----
 1 file changed, 12 insertions(+), 4 deletions(-)

diff --git a/plugins/adhd/lib/install-design-system-docs-route/slug.js b/plugins/adhd/lib/install-design-system-docs-route/slug.js
index 5a91ac0..90d4733 100644
--- a/plugins/adhd/lib/install-design-system-docs-route/slug.js
+++ b/plugins/adhd/lib/install-design-system-docs-route/slug.js
@@ -1,9 +1,17 @@
 'use strict';
 
+function pathSegments(componentPath) {
+  // Strip /index.tsx or .tsx, then split into meaningful segments.
+  return componentPath
+    .replace(/\\/g, '/')
+    .replace(/\.tsx?$/, '')
+    .replace(/\/index$/, '')
+    .split('/')
+    .filter(Boolean);
+}
+
 function baseSlug(componentPath) {
-  // Strip /index.tsx or .tsx; take the last meaningful segment.
-  let p = componentPath.replace(/\\/g, '/').replace(/\.tsx?$/, '').replace(/\/index$/, '');
-  const segs = p.split('/').filter(Boolean);
+  const segs = pathSegments(componentPath);
   return (segs[segs.length - 1] || '').toLowerCase();
 }
 
@@ -20,7 +28,7 @@ function slugMap(paths) {
   // Pass 3: resolve collisions by prepending the parent dir
   for (const t of tentative) {
     if (counts[t.slug] === 1) continue;
-    const segs = t.path.replace(/\\/g, '/').replace(/\.tsx?$/, '').replace(/\/index$/, '').split('/').filter(Boolean);
+    const segs = pathSegments(t.path);
     // Prepend one level of parent until unique
     let depth = 2;
     while (depth <= segs.length) {

From f4376591348152fc58a13b77c88df29429b59057 Mon Sep 17 00:00:00 2001
From: Hugh Francis <hughfrancis89@gmail.com>
Date: Mon, 11 May 2026 15:00:53 -0400
Subject: [PATCH 11/79] next-config-patcher: idempotent conditional
 pageExtensions patch

---
 .../__tests__/next-config-patcher.test.js     | 68 +++++++++++++++++++
 .../next-config-patcher.js                    | 63 +++++++++++++++++
 2 files changed, 131 insertions(+)
 create mode 100644 plugins/adhd/lib/install-design-system-docs-route/__tests__/next-config-patcher.test.js
 create mode 100644 plugins/adhd/lib/install-design-system-docs-route/next-config-patcher.js

diff --git a/plugins/adhd/lib/install-design-system-docs-route/__tests__/next-config-patcher.test.js b/plugins/adhd/lib/install-design-system-docs-route/__tests__/next-config-patcher.test.js
new file mode 100644
index 0000000..a994874
--- /dev/null
+++ b/plugins/adhd/lib/install-design-system-docs-route/__tests__/next-config-patcher.test.js
@@ -0,0 +1,68 @@
+'use strict';
+
+const test = require('node:test');
+const assert = require('node:assert/strict');
+const { patchNextConfig, isPatched } = require('../next-config-patcher');
+
+const TS_MINIMAL = `import type { NextConfig } from "next";
+
+const nextConfig: NextConfig = {
+  images: {
+    remotePatterns: [{ protocol: "https", hostname: "i.pravatar.cc" }],
+  },
+};
+
+export default nextConfig;
+`;
+
+const TS_ALREADY_PATCHED = `import type { NextConfig } from "next";
+
+const nextConfig: NextConfig = {
+  pageExtensions: process.env.NODE_ENV === 'production'
+    ? ['ts', 'tsx']
+    : ['ts', 'tsx', 'design-system.ts', 'design-system.tsx'],
+  images: {
+    remotePatterns: [{ protocol: "https", hostname: "i.pravatar.cc" }],
+  },
+};
+
+export default nextConfig;
+`;
+
+const TS_WITH_DIFFERENT_PAGE_EXTENSIONS = `import type { NextConfig } from "next";
+
+const nextConfig: NextConfig = {
+  pageExtensions: ['mdx', 'ts', 'tsx'],
+};
+
+export default nextConfig;
+`;
+
+test('patches a minimal next.config.ts with the conditional pageExtensions block', () => {
+  const out = patchNextConfig(TS_MINIMAL);
+  assert.match(out, /pageExtensions:\s*process\.env\.NODE_ENV/);
+  assert.match(out, /'design-system\.tsx'/);
+  // Existing config preserved
+  assert.match(out, /images:/);
+  assert.match(out, /remotePatterns:/);
+});
+
+test('isPatched returns true after patching', () => {
+  const out = patchNextConfig(TS_MINIMAL);
+  assert.equal(isPatched(out), true);
+});
+
+test('patchNextConfig is idempotent when already patched', () => {
+  const out = patchNextConfig(TS_ALREADY_PATCHED);
+  assert.equal(out, TS_ALREADY_PATCHED);
+});
+
+test('isPatched returns false on an unpatched file', () => {
+  assert.equal(isPatched(TS_MINIMAL), false);
+});
+
+test('patchNextConfig refuses to silently overwrite an existing different pageExtensions; returns { conflict: true }', () => {
+  const r = patchNextConfig(TS_WITH_DIFFERENT_PAGE_EXTENSIONS, { detectOnly: true });
+  assert.equal(r.conflict, true);
+  assert.match(r.existing, /pageExtensions:\s*\['mdx'/);
+});
diff --git a/plugins/adhd/lib/install-design-system-docs-route/next-config-patcher.js b/plugins/adhd/lib/install-design-system-docs-route/next-config-patcher.js
new file mode 100644
index 0000000..cd143ae
--- /dev/null
+++ b/plugins/adhd/lib/install-design-system-docs-route/next-config-patcher.js
@@ -0,0 +1,63 @@
+'use strict';
+
+// Detection: look for the sentinel "design-system.tsx" pageExtension entry
+// inside the conditional. This is the unique fingerprint of OUR patch.
+const PATCHED_SENTINEL = /pageExtensions:\s*process\.env\.NODE_ENV\s*===\s*['"]production['"][\s\S]*?'design-system\.tsx'/;
+
+// Detection: any other pageExtensions definition.
+const EXISTING_PAGE_EXTENSIONS_RE = /pageExtensions:\s*\[/;
+
+const PATCH_BLOCK = `  pageExtensions: process.env.NODE_ENV === 'production'
+    ? ['ts', 'tsx']
+    : ['ts', 'tsx', 'design-system.ts', 'design-system.tsx'],`;
+
+function isPatched(source) {
+  return PATCHED_SENTINEL.test(source);
+}
+
+function findConfigObjectStart(source) {
+  // Look for either:
+  //   const nextConfig: NextConfig = {
+  //   const nextConfig = {
+  //   export default {
+  //   module.exports = {
+  const patterns = [
+    /const\s+nextConfig(?:\s*:\s*[^=]+)?\s*=\s*\{/,
+    /export\s+default\s*\{/,
+    /module\.exports\s*=\s*\{/,
+  ];
+  for (const re of patterns) {
+    const m = re.exec(source);
+    if (m) return m.index + m[0].length; // position after the opening `{`
+  }
+  return -1;
+}
+
+function patchNextConfig(source, opts = {}) {
+  if (isPatched(source)) return source;
+
+  // Detect existing different pageExtensions
+  if (EXISTING_PAGE_EXTENSIONS_RE.test(source)) {
+    if (opts.detectOnly) {
+      const existing = /pageExtensions:[^,\n]+,?/.exec(source)[0];
+      return { conflict: true, existing };
+    }
+    // Caller hasn't checked; we still refuse to silently merge.
+    throw new Error('next.config already sets pageExtensions to a different value. Run with detectOnly: true to inspect and prompt the user.');
+  }
+
+  const insertAt = findConfigObjectStart(source);
+  if (insertAt === -1) {
+    throw new Error('Could not locate the config object in next.config. Manual edit required.');
+  }
+
+  // Insert the patch block immediately inside the object literal, before existing
+  // properties. This puts it at the top of the config for visibility.
+  const before = source.slice(0, insertAt);
+  const after = source.slice(insertAt);
+  // Add a newline if needed for clean formatting
+  const sep = after.startsWith('\n') ? '' : '\n';
+  return before + sep + PATCH_BLOCK + '\n' + after.replace(/^\n/, '');
+}
+
+module.exports = { patchNextConfig, isPatched };

From bc1c657be7936691dc5c55e580e81bd1c6ed164d Mon Sep 17 00:00:00 2001
From: Hugh Francis <hughfrancis89@gmail.com>
Date: Mon, 11 May 2026 15:02:56 -0400
Subject: [PATCH 12/79] next-config-patcher: align naming with sibling lib
 conventions

Rename PATCHED_SENTINEL to PATCHED_SENTINEL_RE and lift the inline
conflict-extraction regex to a named EXISTING_PAGE_EXTENSIONS_VALUE_RE,
matching the `_RE` suffix convention used in pull-component/config-writer.
Inline the newline-normalization in patchNextConfig so the leading-newline
handling is symmetric and easier to read. Rename `opts` to `options`.
No behavioral change; 30 tests pass.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 .../next-config-patcher.js                    | 23 +++++++++++--------
 1 file changed, 13 insertions(+), 10 deletions(-)

diff --git a/plugins/adhd/lib/install-design-system-docs-route/next-config-patcher.js b/plugins/adhd/lib/install-design-system-docs-route/next-config-patcher.js
index cd143ae..e3d9ee2 100644
--- a/plugins/adhd/lib/install-design-system-docs-route/next-config-patcher.js
+++ b/plugins/adhd/lib/install-design-system-docs-route/next-config-patcher.js
@@ -2,17 +2,20 @@
 
 // Detection: look for the sentinel "design-system.tsx" pageExtension entry
 // inside the conditional. This is the unique fingerprint of OUR patch.
-const PATCHED_SENTINEL = /pageExtensions:\s*process\.env\.NODE_ENV\s*===\s*['"]production['"][\s\S]*?'design-system\.tsx'/;
+const PATCHED_SENTINEL_RE = /pageExtensions:\s*process\.env\.NODE_ENV\s*===\s*['"]production['"][\s\S]*?'design-system\.tsx'/;
 
-// Detection: any other pageExtensions definition.
+// Detection: any other pageExtensions definition (array form).
 const EXISTING_PAGE_EXTENSIONS_RE = /pageExtensions:\s*\[/;
 
+// Captures the full `pageExtensions: ...,` declaration for conflict reporting.
+const EXISTING_PAGE_EXTENSIONS_VALUE_RE = /pageExtensions:[^,\n]+,?/;
+
 const PATCH_BLOCK = `  pageExtensions: process.env.NODE_ENV === 'production'
     ? ['ts', 'tsx']
     : ['ts', 'tsx', 'design-system.ts', 'design-system.tsx'],`;
 
 function isPatched(source) {
-  return PATCHED_SENTINEL.test(source);
+  return PATCHED_SENTINEL_RE.test(source);
 }
 
 function findConfigObjectStart(source) {
@@ -33,13 +36,13 @@ function findConfigObjectStart(source) {
   return -1;
 }
 
-function patchNextConfig(source, opts = {}) {
+function patchNextConfig(source, options = {}) {
   if (isPatched(source)) return source;
 
   // Detect existing different pageExtensions
   if (EXISTING_PAGE_EXTENSIONS_RE.test(source)) {
-    if (opts.detectOnly) {
-      const existing = /pageExtensions:[^,\n]+,?/.exec(source)[0];
+    if (options.detectOnly) {
+      const existing = EXISTING_PAGE_EXTENSIONS_VALUE_RE.exec(source)[0];
       return { conflict: true, existing };
     }
     // Caller hasn't checked; we still refuse to silently merge.
@@ -54,10 +57,10 @@ function patchNextConfig(source, opts = {}) {
   // Insert the patch block immediately inside the object literal, before existing
   // properties. This puts it at the top of the config for visibility.
   const before = source.slice(0, insertAt);
-  const after = source.slice(insertAt);
-  // Add a newline if needed for clean formatting
-  const sep = after.startsWith('\n') ? '' : '\n';
-  return before + sep + PATCH_BLOCK + '\n' + after.replace(/^\n/, '');
+  // Strip any leading newline from the tail so it isn't duplicated; we always
+  // emit exactly one `\n` on each side of PATCH_BLOCK for clean formatting.
+  const after = source.slice(insertAt).replace(/^\n/, '');
+  return before + '\n' + PATCH_BLOCK + '\n' + after;
 }
 
 module.exports = { patchNextConfig, isPatched };

From 827d349f3290a68f71b675de143bda982a6856ff Mon Sep 17 00:00:00 2001
From: Hugh Francis <hughfrancis89@gmail.com>
Date: Mon, 11 May 2026 15:04:07 -0400
Subject: [PATCH 13/79] robots-patcher: idempotent Disallow entry for the docs
 route

---
 .../__tests__/robots-patcher.test.js          | 43 +++++++++++++++++++
 .../robots-patcher.js                         | 16 +++++++
 2 files changed, 59 insertions(+)
 create mode 100644 plugins/adhd/lib/install-design-system-docs-route/__tests__/robots-patcher.test.js
 create mode 100644 plugins/adhd/lib/install-design-system-docs-route/robots-patcher.js

diff --git a/plugins/adhd/lib/install-design-system-docs-route/__tests__/robots-patcher.test.js b/plugins/adhd/lib/install-design-system-docs-route/__tests__/robots-patcher.test.js
new file mode 100644
index 0000000..157d46c
--- /dev/null
+++ b/plugins/adhd/lib/install-design-system-docs-route/__tests__/robots-patcher.test.js
@@ -0,0 +1,43 @@
+'use strict';
+
+const test = require('node:test');
+const assert = require('node:assert/strict');
+const { patchRobots } = require('../robots-patcher');
+
+test('creates robots.txt content if input is empty', () => {
+  const out = patchRobots('', '/-docs');
+  assert.match(out, /User-agent: \*/);
+  assert.match(out, /Disallow: \/-docs/);
+});
+
+test('creates robots.txt content if input is null/undefined', () => {
+  const out = patchRobots(null, '/-docs');
+  assert.match(out, /User-agent: \*/);
+  assert.match(out, /Disallow: \/-docs/);
+});
+
+test('appends a Disallow line to an existing robots.txt', () => {
+  const existing = `User-agent: *
+Disallow: /admin
+`;
+  const out = patchRobots(existing, '/-docs');
+  assert.match(out, /Disallow: \/admin/);
+  assert.match(out, /Disallow: \/-docs/);
+});
+
+test('idempotent: re-patching an already-patched robots.txt returns unchanged', () => {
+  const existing = `User-agent: *
+Disallow: /-docs
+`;
+  const out = patchRobots(existing, '/-docs');
+  assert.equal(out, existing);
+});
+
+test('idempotent: matching is exact (does not match /-docs-other)', () => {
+  const existing = `User-agent: *
+Disallow: /-docs-other
+`;
+  const out = patchRobots(existing, '/-docs');
+  assert.match(out, /Disallow: \/-docs-other/);
+  assert.match(out, /Disallow: \/-docs$/m);
+});
diff --git a/plugins/adhd/lib/install-design-system-docs-route/robots-patcher.js b/plugins/adhd/lib/install-design-system-docs-route/robots-patcher.js
new file mode 100644
index 0000000..5d36c76
--- /dev/null
+++ b/plugins/adhd/lib/install-design-system-docs-route/robots-patcher.js
@@ -0,0 +1,16 @@
+'use strict';
+
+function patchRobots(source, routeUrl) {
+  const disallowLine = `Disallow: ${routeUrl}`;
+  if (!source) {
+    return `User-agent: *\n${disallowLine}\n`;
+  }
+  // Idempotent: line-anchored exact match
+  const exactRe = new RegExp(`^${disallowLine.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}\\s*$`, 'm');
+  if (exactRe.test(source)) return source;
+  // Append (ensure newline before, single newline after)
+  const trimmed = source.replace(/\n+$/, '');
+  return trimmed + '\n' + disallowLine + '\n';
+}
+
+module.exports = { patchRobots };

From 6242cb224ba3e5b19785d9fcaa9be0a170382f7d Mon Sep 17 00:00:00 2001
From: Hugh Francis <hughfrancis89@gmail.com>
Date: Mon, 11 May 2026 15:07:53 -0400
Subject: [PATCH 14/79] templates: layout, index, component page, PropToggle
 (marker-prefixed, no ADHD refs)

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 .../__tests__/templates.test.js               |  67 +++
 .../templates.js                              | 386 ++++++++++++++++++
 2 files changed, 453 insertions(+)
 create mode 100644 plugins/adhd/lib/install-design-system-docs-route/__tests__/templates.test.js
 create mode 100644 plugins/adhd/lib/install-design-system-docs-route/templates.js

diff --git a/plugins/adhd/lib/install-design-system-docs-route/__tests__/templates.test.js b/plugins/adhd/lib/install-design-system-docs-route/__tests__/templates.test.js
new file mode 100644
index 0000000..cbd7749
--- /dev/null
+++ b/plugins/adhd/lib/install-design-system-docs-route/__tests__/templates.test.js
@@ -0,0 +1,67 @@
+'use strict';
+
+const test = require('node:test');
+const assert = require('node:assert/strict');
+const { MARKER_COMMENT, LAYOUT_TSX, INDEX_PAGE_TSX, COMPONENT_PAGE_TSX, PROP_TOGGLE_TSX } = require('../templates');
+
+test('MARKER_COMMENT is a stable, non-ADHD-referencing string', () => {
+  assert.match(MARKER_COMMENT, /design-system-docs-route/);
+  assert.match(MARKER_COMMENT, /auto-generated installer artifact; safe to edit/);
+  assert.equal(/adhd/i.test(MARKER_COMMENT), false, 'must not reference ADHD');
+});
+
+test('LAYOUT_TSX starts with the marker comment', () => {
+  assert.ok(LAYOUT_TSX.startsWith(MARKER_COMMENT));
+});
+
+test('LAYOUT_TSX sets robots: noindex / nofollow', () => {
+  assert.match(LAYOUT_TSX, /robots:\s*\{[^}]*index:\s*false[^}]*follow:\s*false/);
+});
+
+test('LAYOUT_TSX has no ADHD references outside marker', () => {
+  // marker excluded
+  const body = LAYOUT_TSX.replace(MARKER_COMMENT, '');
+  assert.equal(/adhd/i.test(body), false);
+});
+
+test('INDEX_PAGE_TSX renders sections for each token domain', () => {
+  for (const section of ['Colors', 'Spacing', 'Typography', 'Radius', 'Shadows', 'Components']) {
+    assert.match(INDEX_PAGE_TSX, new RegExp(section));
+  }
+});
+
+test('INDEX_PAGE_TSX reads adhd.config.ts and globals.css via fs', () => {
+  assert.match(INDEX_PAGE_TSX, /adhd\.config\.ts/);
+  assert.match(INDEX_PAGE_TSX, /globals\.css|cssEntry/);
+});
+
+test('COMPONENT_PAGE_TSX uses parametric template-string dynamic import', () => {
+  assert.match(COMPONENT_PAGE_TSX, /await\s+import\(`/);
+});
+
+test('COMPONENT_PAGE_TSX reads searchParams for prop toggles', () => {
+  assert.match(COMPONENT_PAGE_TSX, /searchParams/);
+});
+
+test('PROP_TOGGLE_TSX is a client component', () => {
+  // The marker comment is allowed to precede the directive — Next.js strips
+  // leading comments and treats `"use client"` as the first real statement.
+  // Required so the marker-detection contract (Task 8) still applies.
+  const afterMarker = PROP_TOGGLE_TSX.replace(MARKER_COMMENT, '');
+  assert.match(afterMarker, /^["']use client["']/);
+});
+
+test('PROP_TOGGLE_TSX uses router.replace for snappy URL updates', () => {
+  assert.match(PROP_TOGGLE_TSX, /router\.replace/);
+});
+
+test('none of the templates contain "ADHD" outside the marker', () => {
+  // The literal filename `adhd.config.ts` is the consumer's own config artifact
+  // (per the install spec) and is not a reference to the ADHD plugin/brand —
+  // it's an unavoidable filename the generated pages must read at runtime.
+  // Strip it before applying the "no ADHD references" rule.
+  for (const [name, content] of Object.entries({ LAYOUT_TSX, INDEX_PAGE_TSX, COMPONENT_PAGE_TSX, PROP_TOGGLE_TSX })) {
+    const body = content.replace(MARKER_COMMENT, '').replace(/adhd\.config\.ts/g, '');
+    assert.equal(/adhd/i.test(body), false, `${name} must not reference ADHD outside marker`);
+  }
+});
diff --git a/plugins/adhd/lib/install-design-system-docs-route/templates.js b/plugins/adhd/lib/install-design-system-docs-route/templates.js
new file mode 100644
index 0000000..35e5fad
--- /dev/null
+++ b/plugins/adhd/lib/install-design-system-docs-route/templates.js
@@ -0,0 +1,386 @@
+'use strict';
+
+const MARKER_COMMENT = `// design-system-docs-route — auto-generated installer artifact; safe to edit.
+// Remove this comment to disable future overwrites from re-running the installer.
+`;
+
+const LAYOUT_TSX = `${MARKER_COMMENT}import type { Metadata } from "next";
+
+export const metadata: Metadata = {
+  title: "Design System Docs",
+  robots: { index: false, follow: false },
+};
+
+export default function DesignSystemDocsLayout({ children }: { children: React.ReactNode }) {
+  return (
+    <div className="min-h-screen bg-zinc-50 dark:bg-zinc-950">
+      <header className="border-b border-zinc-200 dark:border-zinc-800 p-4">
+        <div className="mx-auto max-w-5xl flex items-baseline gap-3">
+          <h1 className="text-sm font-medium">Design System Docs</h1>
+          <span className="text-xs text-zinc-500">Internal — not indexed</span>
+        </div>
+      </header>
+      <main className="mx-auto max-w-5xl p-8">{children}</main>
+    </div>
+  );
+}
+`;
+
+const INDEX_PAGE_TSX = `${MARKER_COMMENT}import fs from "node:fs/promises";
+import path from "node:path";
+import Link from "next/link";
+
+async function readConfig() {
+  try {
+    const src = await fs.readFile(path.resolve(process.cwd(), "adhd.config.ts"), "utf8");
+    const components: Record<string, unknown> = {};
+    const compMatch = /components:\\s*\\{([\\s\\S]*?)\\}\\s*[,;]?/.exec(src);
+    if (compMatch) {
+      const inner = compMatch[1];
+      const re = /"([^"]+)"\\s*:\\s*\\{/g;
+      let m;
+      while ((m = re.exec(inner)) !== null) {
+        components[m[1]] = true;
+      }
+    }
+    const cssEntryMatch = /cssEntry\\s*:\\s*"([^"]+)"/.exec(src);
+    const cssEntry = cssEntryMatch ? cssEntryMatch[1] : "app/globals.css";
+    return { components: Object.keys(components), cssEntry };
+  } catch {
+    return { components: [], cssEntry: "app/globals.css" };
+  }
+}
+
+async function readCss(cssEntry: string) {
+  try {
+    return await fs.readFile(path.resolve(process.cwd(), cssEntry), "utf8");
+  } catch {
+    return null;
+  }
+}
+
+function extractTokens(css: string | null) {
+  const empty = { colors: [], spacing: { multiplier: null }, typography: [], radius: [], shadows: [] };
+  if (!css) return empty;
+  const out = { colors: [] as Array<{ name: string; value: string }>,
+                spacing: { multiplier: null as string | null },
+                typography: [] as Array<{ name: string; size: string | null; lineHeight: string | null }>,
+                radius: [] as Array<{ name: string; value: string }>,
+                shadows: [] as Array<{ name: string; value: string }> };
+  const themeRe = /@theme\\s*\\{([\\s\\S]*?)\\}/g;
+  let body;
+  while ((body = themeRe.exec(css)) !== null) {
+    const declRe = /--([a-zA-Z0-9_-]+)\\s*:\\s*([^;]+);/g;
+    let d;
+    while ((d = declRe.exec(body[1])) !== null) {
+      const name = d[1];
+      const value = d[2].trim();
+      if (name.startsWith("color-")) out.colors.push({ name: name.slice(6), value });
+      else if (name === "spacing") out.spacing.multiplier = value;
+      else if (name.startsWith("text-")) {
+        const rest = name.slice(5);
+        const lhIdx = rest.indexOf("--line-height");
+        const leaf = lhIdx >= 0 ? rest.slice(0, lhIdx) : rest;
+        let row = out.typography.find(t => t.name === leaf);
+        if (!row) { row = { name: leaf, size: null, lineHeight: null }; out.typography.push(row); }
+        if (lhIdx >= 0) row.lineHeight = value; else row.size = value;
+      } else if (name.startsWith("radius-")) out.radius.push({ name: name.slice(7), value });
+      else if (name.startsWith("shadow-")) out.shadows.push({ name: name.slice(7), value });
+    }
+  }
+  return out;
+}
+
+export default async function DesignSystemIndex() {
+  const cfg = await readConfig();
+  const css = await readCss(cfg.cssEntry);
+  const tokens = extractTokens(css);
+
+  return (
+    <div className="flex flex-col gap-12">
+      <section>
+        <h2 className="mb-4 text-xs font-medium uppercase text-zinc-500">Colors</h2>
+        {tokens.colors.length === 0 ? <p className="text-sm text-zinc-500">No colors detected.</p> : (
+          <div className="grid grid-cols-6 gap-3">
+            {tokens.colors.map(c => (
+              <div key={c.name} className="flex flex-col gap-1">
+                <div className="h-12 w-full rounded border border-zinc-200 dark:border-zinc-800" style={{ backgroundColor: c.value }} />
+                <span className="text-xs">{c.name}</span>
+                <span className="text-[10px] text-zinc-500">{c.value}</span>
+              </div>
+            ))}
+          </div>
+        )}
+      </section>
+
+      <section>
+        <h2 className="mb-4 text-xs font-medium uppercase text-zinc-500">Spacing</h2>
+        {tokens.spacing.multiplier ? <p className="text-sm">Multiplier: <code>{tokens.spacing.multiplier}</code></p> : <p className="text-sm text-zinc-500">No spacing variable detected.</p>}
+      </section>
+
+      <section>
+        <h2 className="mb-4 text-xs font-medium uppercase text-zinc-500">Typography</h2>
+        {tokens.typography.length === 0 ? <p className="text-sm text-zinc-500">No typography tokens detected.</p> : (
+          <div className="flex flex-col gap-4">
+            {tokens.typography.map(t => (
+              <div key={t.name} className="flex items-baseline gap-4">
+                <span className="text-xs text-zinc-500 w-20">text-{t.name}</span>
+                <span style={{ fontSize: t.size ?? undefined, lineHeight: t.lineHeight ?? undefined }}>
+                  The quick brown fox jumps over the lazy dog
+                </span>
+                <span className="text-[10px] text-zinc-500">{t.size}{t.lineHeight ? \` / \${t.lineHeight}\` : ""}</span>
+              </div>
+            ))}
+          </div>
+        )}
+      </section>
+
+      <section>
+        <h2 className="mb-4 text-xs font-medium uppercase text-zinc-500">Radius</h2>
+        {tokens.radius.length === 0 ? <p className="text-sm text-zinc-500">No radius tokens detected.</p> : (
+          <div className="flex gap-4">
+            {tokens.radius.map(r => (
+              <div key={r.name} className="flex flex-col gap-1">
+                <div className="h-16 w-16 bg-zinc-200 dark:bg-zinc-800" style={{ borderRadius: r.value }} />
+                <span className="text-xs">rounded-{r.name}</span>
+              </div>
+            ))}
+          </div>
+        )}
+      </section>
+
+      <section>
+        <h2 className="mb-4 text-xs font-medium uppercase text-zinc-500">Shadows</h2>
+        {tokens.shadows.length === 0 ? <p className="text-sm text-zinc-500">No shadow tokens detected.</p> : (
+          <div className="flex gap-6">
+            {tokens.shadows.map(s => (
+              <div key={s.name} className="flex flex-col gap-1">
+                <div className="h-16 w-16 bg-white" style={{ boxShadow: s.value }} />
+                <span className="text-xs">shadow-{s.name}</span>
+              </div>
+            ))}
+          </div>
+        )}
+      </section>
+
+      <section>
+        <h2 className="mb-4 text-xs font-medium uppercase text-zinc-500">Components</h2>
+        {cfg.components.length === 0 ? <p className="text-sm text-zinc-500">No components tracked yet.</p> : (
+          <div className="grid grid-cols-3 gap-4">
+            {cfg.components.map(p => {
+              const slug = p.replace(/\\.tsx?$/, "").replace(/\\/index$/, "").split("/").pop()?.toLowerCase() ?? p;
+              return (
+                <Link key={p} href={\`./\${slug}\`} className="rounded border border-zinc-200 dark:border-zinc-800 p-4 hover:bg-zinc-100 dark:hover:bg-zinc-900">
+                  <div className="text-sm font-medium">{slug}</div>
+                  <div className="text-xs text-zinc-500 truncate">{p}</div>
+                </Link>
+              );
+            })}
+          </div>
+        )}
+      </section>
+    </div>
+  );
+}
+`;
+
+const COMPONENT_PAGE_TSX = `${MARKER_COMMENT}import fs from "node:fs/promises";
+import path from "node:path";
+import { notFound } from "next/navigation";
+import { PropToggle } from "../PropToggle";
+
+async function readConfig() {
+  try {
+    const src = await fs.readFile(path.resolve(process.cwd(), "adhd.config.ts"), "utf8");
+    const components: string[] = [];
+    const compMatch = /components:\\s*\\{([\\s\\S]*?)\\}\\s*[,;]?/.exec(src);
+    if (compMatch) {
+      const inner = compMatch[1];
+      const re = /"([^"]+)"\\s*:\\s*\\{/g;
+      let m;
+      while ((m = re.exec(inner)) !== null) components.push(m[1]);
+    }
+    return components;
+  } catch {
+    return [];
+  }
+}
+
+function slugFor(p: string) {
+  return p.replace(/\\.tsx?$/, "").replace(/\\/index$/, "").split("/").pop()?.toLowerCase() ?? p;
+}
+
+async function parseProps(componentPath: string) {
+  try {
+    const src = await fs.readFile(path.resolve(process.cwd(), componentPath), "utf8");
+    const TYPE_ALIAS_RE = /export\\s+type\\s+([A-Z][A-Za-z0-9]*)\\s*=\\s*([^;]+);/g;
+    const INTERFACE_RE = /(?:export\\s+)?interface\\s+([A-Z][A-Za-z0-9]*Props)\\s*\\{([\\s\\S]*?)\\}/;
+    const PROP_LINE_RE = /^\\s*([a-zA-Z_$][a-zA-Z0-9_$]*)(\\??)\\s*:\\s*([^;,]+)[;,]?\\s*$/;
+
+    const knownUnions: Record<string, string[]> = {};
+    TYPE_ALIAS_RE.lastIndex = 0;
+    let m;
+    while ((m = TYPE_ALIAS_RE.exec(src)) !== null) {
+      const body = m[2].trim();
+      if (/^"[^"]*"(\\s*\\|\\s*"[^"]*")*$/.test(body)) {
+        knownUnions[m[1]] = body.split("|").map(s => s.trim().replace(/"/g, ""));
+      }
+    }
+    const iface = INTERFACE_RE.exec(src);
+    if (!iface) return { props: {} as Record<string, any>, knownUnions };
+    const props: Record<string, any> = {};
+    for (const rawLine of iface[2].split("\\n")) {
+      const line = rawLine.replace(/\\/\\/.*$/, "");
+      const pm = PROP_LINE_RE.exec(line);
+      if (!pm) continue;
+      const [, name, opt, type] = pm;
+      const t = type.trim();
+      if (knownUnions[t]) props[name] = { type: "union", values: knownUnions[t], optional: !!opt };
+      else if (/^"[^"]*"(\\s*\\|\\s*"[^"]*")*$/.test(t)) {
+        props[name] = { type: "union", values: t.split("|").map(s => s.trim().replace(/"/g, "")), optional: !!opt };
+      } else if (t === "string") props[name] = { type: "string", optional: !!opt };
+      else if (t === "number") props[name] = { type: "number", optional: !!opt };
+      else if (t === "boolean") props[name] = { type: "boolean", optional: !!opt };
+      else props[name] = { type: "unknown", optional: !!opt };
+    }
+    return { props, knownUnions };
+  } catch {
+    return { props: {} as Record<string, any>, knownUnions: {} };
+  }
+}
+
+export default async function ComponentPage({
+  params,
+  searchParams,
+}: {
+  params: Promise<{ component: string }>;
+  searchParams: Promise<Record<string, string | string[] | undefined>>;
+}) {
+  const { component: slug } = await params;
+  const sp = await searchParams;
+  const paths = await readConfig();
+  const componentPath = paths.find(p => slugFor(p) === slug);
+  if (!componentPath) notFound();
+
+  const { props } = await parseProps(componentPath);
+
+  // Resolve current prop values from searchParams
+  const current: Record<string, any> = {};
+  for (const [name, def] of Object.entries(props)) {
+    const v = sp[name];
+    if (typeof v !== "string") continue;
+    if (def.type === "union" && def.values.includes(v)) current[name] = v;
+    else if (def.type === "boolean") current[name] = v === "true";
+    else if (def.type === "string") current[name] = v;
+    else if (def.type === "number") current[name] = Number(v);
+  }
+
+  // Dynamic import the component
+  let Component: any = null;
+  let importError: string | null = null;
+  try {
+    const mod = await import(\`@/\${componentPath.replace(/\\.tsx?$/, "")}\`);
+    const name = Object.keys(mod).find(k => typeof mod[k] === "function") ?? "default";
+    Component = mod.default ?? mod[name];
+  } catch (e: any) {
+    importError = e?.message ?? String(e);
+  }
+
+  const importPath = "@/" + componentPath.replace(/\\.tsx?$/, "").replace(/\\/index$/, "");
+  const importStmt = Component ? \`import { \${Component.name ?? slug} } from "\${importPath}";\` : null;
+  const jsxSnippet = Component
+    ? \`<\${Component.name ?? slug}\${Object.entries(current).map(([k,v]) => \` \${k}={\${JSON.stringify(v)}}\`).join("")} />\`
+    : null;
+
+  return (
+    <div className="flex flex-col gap-6">
+      <h2 className="text-lg font-medium">{slug}</h2>
+
+      <section className="rounded border border-zinc-200 dark:border-zinc-800 p-4">
+        <h3 className="mb-3 text-xs font-medium uppercase text-zinc-500">Props</h3>
+        {Object.keys(props).length === 0 ? <p className="text-sm text-zinc-500">No prop introspection available.</p> : (
+          <div className="flex flex-col gap-2">
+            {Object.entries(props).map(([name, def]: [string, any]) => {
+              if (def.type === "union") {
+                return (
+                  <PropToggle key={name} name={name} kind="union" values={def.values} value={current[name] ?? def.values[0]} />
+                );
+              }
+              if (def.type === "boolean") {
+                return (
+                  <PropToggle key={name} name={name} kind="boolean" value={String(current[name] ?? false)} />
+                );
+              }
+              if (def.type === "string" || def.type === "number") {
+                return (
+                  <PropToggle key={name} name={name} kind={def.type} value={String(current[name] ?? "")} />
+                );
+              }
+              return (
+                <div key={name} className="text-xs text-zinc-500">
+                  {name}: <code>{def.type}</code> — toggle unavailable
+                </div>
+              );
+            })}
+          </div>
+        )}
+      </section>
+
+      <section className="rounded border border-zinc-200 dark:border-zinc-800 p-8">
+        {importError ? (
+          <pre className="text-xs text-red-600 whitespace-pre-wrap">{importError}</pre>
+        ) : Component ? (
+          <Component {...current} />
+        ) : null}
+      </section>
+
+      {importStmt && jsxSnippet && (
+        <section className="flex flex-col gap-2">
+          <pre className="rounded bg-zinc-100 dark:bg-zinc-900 p-3 text-xs overflow-x-auto"><code>{importStmt}</code></pre>
+          <pre className="rounded bg-zinc-100 dark:bg-zinc-900 p-3 text-xs overflow-x-auto"><code>{jsxSnippet}</code></pre>
+        </section>
+      )}
+    </div>
+  );
+}
+`;
+
+const PROP_TOGGLE_TSX = `${MARKER_COMMENT}"use client";
+import { useRouter, useSearchParams, usePathname } from "next/navigation";
+
+type Props =
+  | { name: string; kind: "union"; values: string[]; value: string }
+  | { name: string; kind: "boolean"; value: string }
+  | { name: string; kind: "string"; value: string }
+  | { name: string; kind: "number"; value: string };
+
+export function PropToggle(p: Props) {
+  const router = useRouter();
+  const path = usePathname();
+  const sp = useSearchParams();
+
+  function setParam(v: string) {
+    const next = new URLSearchParams(sp.toString());
+    if (v === "") next.delete(p.name);
+    else next.set(p.name, v);
+    router.replace(\`\${path}?\${next}\`);
+  }
+
+  return (
+    <label className="flex items-center gap-3 text-sm">
+      <span className="w-24 text-xs text-zinc-500">{p.name}</span>
+      {p.kind === "union" ? (
+        <select className="rounded border border-zinc-300 dark:border-zinc-700 bg-transparent px-2 py-1 text-sm" value={p.value} onChange={(e) => setParam(e.target.value)}>
+          {p.values.map((v) => <option key={v} value={v}>{v}</option>)}
+        </select>
+      ) : p.kind === "boolean" ? (
+        <input type="checkbox" checked={p.value === "true"} onChange={(e) => setParam(String(e.target.checked))} />
+      ) : (
+        <input type={p.kind === "number" ? "number" : "text"} className="rounded border border-zinc-300 dark:border-zinc-700 bg-transparent px-2 py-1 text-sm" value={p.value} onChange={(e) => setParam(e.target.value)} />
+      )}
+    </label>
+  );
+}
+`;
+
+module.exports = { MARKER_COMMENT, LAYOUT_TSX, INDEX_PAGE_TSX, COMPONENT_PAGE_TSX, PROP_TOGGLE_TSX };

From 54059c61b09a224d887b6857fefefe189ad2424a Mon Sep 17 00:00:00 2001
From: Hugh Francis <hughfrancis89@gmail.com>
Date: Mon, 11 May 2026 15:10:30 -0400
Subject: [PATCH 15/79] route-installer: write the 4 page files; detect
 existing installs via marker

---
 .../__tests__/route-installer.test.js         | 97 +++++++++++++++++++
 .../route-installer.js                        | 64 ++++++++++++
 2 files changed, 161 insertions(+)
 create mode 100644 plugins/adhd/lib/install-design-system-docs-route/__tests__/route-installer.test.js
 create mode 100644 plugins/adhd/lib/install-design-system-docs-route/route-installer.js

diff --git a/plugins/adhd/lib/install-design-system-docs-route/__tests__/route-installer.test.js b/plugins/adhd/lib/install-design-system-docs-route/__tests__/route-installer.test.js
new file mode 100644
index 0000000..3aba1cc
--- /dev/null
+++ b/plugins/adhd/lib/install-design-system-docs-route/__tests__/route-installer.test.js
@@ -0,0 +1,97 @@
+'use strict';
+
+const test = require('node:test');
+const assert = require('node:assert/strict');
+const fs = require('node:fs');
+const path = require('node:path');
+const os = require('node:os');
+const { installRoute, detectExistingInstall } = require('../route-installer');
+
+function makeTempProject() {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'adhd-install-'));
+  fs.mkdirSync(path.join(root, 'app'), { recursive: true });
+  return root;
+}
+
+test('installRoute writes 4 files with the .design-system.tsx extension when prodExcluded', () => {
+  const root = makeTempProject();
+  installRoute(root, {
+    groupName: '(design-system)',
+    routeSegment: '-docs',
+    prodExcluded: true,
+  });
+  const docsDir = path.join(root, 'app', '(design-system)', '-docs');
+  assert.ok(fs.existsSync(path.join(docsDir, 'layout.design-system.tsx')));
+  assert.ok(fs.existsSync(path.join(docsDir, 'page.design-system.tsx')));
+  assert.ok(fs.existsSync(path.join(docsDir, '[component]', 'page.design-system.tsx')));
+  assert.ok(fs.existsSync(path.join(docsDir, 'PropToggle.design-system.tsx')));
+});
+
+test('installRoute writes plain .tsx files when not prodExcluded', () => {
+  const root = makeTempProject();
+  installRoute(root, {
+    groupName: '(design-system)',
+    routeSegment: '-docs',
+    prodExcluded: false,
+  });
+  const docsDir = path.join(root, 'app', '(design-system)', '-docs');
+  assert.ok(fs.existsSync(path.join(docsDir, 'layout.tsx')));
+  assert.ok(fs.existsSync(path.join(docsDir, 'page.tsx')));
+  assert.ok(fs.existsSync(path.join(docsDir, '[component]', 'page.tsx')));
+  assert.ok(fs.existsSync(path.join(docsDir, 'PropToggle.tsx')));
+});
+
+test('all written files start with the marker comment', () => {
+  const root = makeTempProject();
+  installRoute(root, { groupName: '(design-system)', routeSegment: '-docs', prodExcluded: true });
+  const docsDir = path.join(root, 'app', '(design-system)', '-docs');
+  for (const f of [
+    'layout.design-system.tsx',
+    'page.design-system.tsx',
+    '[component]/page.design-system.tsx',
+    'PropToggle.design-system.tsx',
+  ]) {
+    const content = fs.readFileSync(path.join(docsDir, f), 'utf8');
+    assert.match(content, /design-system-docs-route/);
+  }
+});
+
+test('detectExistingInstall scans for the marker and returns matching files', () => {
+  const root = makeTempProject();
+  installRoute(root, { groupName: '(design-system)', routeSegment: '-docs', prodExcluded: true });
+  const found = detectExistingInstall(root);
+  assert.ok(found.length >= 4);
+  assert.ok(found.every(p => p.includes('-docs')));
+});
+
+test('detectExistingInstall returns [] when no marker is present', () => {
+  const root = makeTempProject();
+  const found = detectExistingInstall(root);
+  assert.deepEqual(found, []);
+});
+
+test('detectExistingInstall does not match unrelated files', () => {
+  const root = makeTempProject();
+  fs.writeFileSync(path.join(root, 'app', 'page.tsx'), 'export default function P() { return null; }\n');
+  assert.deepEqual(detectExistingInstall(root), []);
+});
+
+test('re-running installRoute is safe (overwrites files cleanly)', () => {
+  const root = makeTempProject();
+  installRoute(root, { groupName: '(design-system)', routeSegment: '-docs', prodExcluded: true });
+  // Modify a file
+  const layoutPath = path.join(root, 'app', '(design-system)', '-docs', 'layout.design-system.tsx');
+  fs.writeFileSync(layoutPath, 'corrupted');
+  // Re-install
+  installRoute(root, { groupName: '(design-system)', routeSegment: '-docs', prodExcluded: true });
+  const after = fs.readFileSync(layoutPath, 'utf8');
+  assert.match(after, /design-system-docs-route/);
+  assert.match(after, /DesignSystemDocsLayout/);
+});
+
+test('installRoute supports an empty groupName (no route group)', () => {
+  const root = makeTempProject();
+  installRoute(root, { groupName: '', routeSegment: '-docs', prodExcluded: true });
+  const docsDir = path.join(root, 'app', '-docs');
+  assert.ok(fs.existsSync(path.join(docsDir, 'layout.design-system.tsx')));
+});
diff --git a/plugins/adhd/lib/install-design-system-docs-route/route-installer.js b/plugins/adhd/lib/install-design-system-docs-route/route-installer.js
new file mode 100644
index 0000000..61cfb59
--- /dev/null
+++ b/plugins/adhd/lib/install-design-system-docs-route/route-installer.js
@@ -0,0 +1,64 @@
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { MARKER_COMMENT, LAYOUT_TSX, INDEX_PAGE_TSX, COMPONENT_PAGE_TSX, PROP_TOGGLE_TSX } = require('./templates');
+
+function mkdirpSync(p) {
+  fs.mkdirSync(p, { recursive: true });
+}
+
+function installRoute(projectRoot, opts) {
+  const { groupName = '', routeSegment, prodExcluded } = opts;
+  if (!routeSegment) throw new Error('routeSegment is required');
+
+  const ext = prodExcluded ? '.design-system.tsx' : '.tsx';
+  const segments = ['app'];
+  if (groupName) segments.push(groupName);
+  segments.push(routeSegment);
+  const docsDir = path.join(projectRoot, ...segments);
+  const componentDir = path.join(docsDir, '[component]');
+
+  mkdirpSync(docsDir);
+  mkdirpSync(componentDir);
+
+  fs.writeFileSync(path.join(docsDir, `layout${ext}`), LAYOUT_TSX);
+  fs.writeFileSync(path.join(docsDir, `page${ext}`), INDEX_PAGE_TSX);
+  fs.writeFileSync(path.join(componentDir, `page${ext}`), COMPONENT_PAGE_TSX);
+  fs.writeFileSync(path.join(docsDir, `PropToggle${ext}`), PROP_TOGGLE_TSX);
+
+  return {
+    files: [
+      path.join(docsDir, `layout${ext}`),
+      path.join(docsDir, `page${ext}`),
+      path.join(componentDir, `page${ext}`),
+      path.join(docsDir, `PropToggle${ext}`),
+    ],
+  };
+}
+
+function detectExistingInstall(projectRoot) {
+  const found = [];
+  function walk(dir) {
+    let entries;
+    try { entries = fs.readdirSync(dir, { withFileTypes: true }); }
+    catch { return; }
+    for (const ent of entries) {
+      if (ent.name === 'node_modules' || ent.name === '.next' || ent.name.startsWith('.git')) continue;
+      const full = path.join(dir, ent.name);
+      if (ent.isDirectory()) walk(full);
+      else if (/\.tsx?$/.test(ent.name)) {
+        try {
+          const content = fs.readFileSync(full, 'utf8');
+          if (content.includes('design-system-docs-route')) {
+            found.push(full);
+          }
+        } catch {}
+      }
+    }
+  }
+  walk(path.join(projectRoot, 'app'));
+  return found;
+}
+
+module.exports = { installRoute, detectExistingInstall };

From 764d07172f37b9236d598aa54719c6aec5a71ba9 Mon Sep 17 00:00:00 2001
From: Hugh Francis <hughfrancis89@gmail.com>
Date: Mon, 11 May 2026 15:12:50 -0400
Subject: [PATCH 16/79] cli: wire all subcommands (parse-tokens, parse-props,
 slug, patch-*, detect-install, install)

---
 .../__tests__/cli.test.js                     | 77 +++++++++++++++++++
 .../install-design-system-docs-route/cli.js   | 69 ++++++++++++++++-
 2 files changed, 145 insertions(+), 1 deletion(-)

diff --git a/plugins/adhd/lib/install-design-system-docs-route/__tests__/cli.test.js b/plugins/adhd/lib/install-design-system-docs-route/__tests__/cli.test.js
index 4daf0f2..1b11092 100644
--- a/plugins/adhd/lib/install-design-system-docs-route/__tests__/cli.test.js
+++ b/plugins/adhd/lib/install-design-system-docs-route/__tests__/cli.test.js
@@ -27,3 +27,80 @@ test('cli with no args exits 2', () => {
 test('cli with unknown subcommand exits 2', () => {
   assert.equal(spawnSync('node', [CLI, 'unknown'], { encoding: 'utf8' }).status, 2);
 });
+
+const fs = require('node:fs');
+const os = require('node:os');
+
+function tmp(filename, content) {
+  const p = path.join(os.tmpdir(), 'adhd-ids-' + Date.now() + '-' + Math.random().toString(16).slice(2, 8) + '-' + filename);
+  fs.writeFileSync(p, content);
+  return p;
+}
+
+const FX_CSS = path.resolve(__dirname, '..', '__fixtures__', 'globals.css');
+const FX_AVATAR = path.resolve(__dirname, '..', '__fixtures__', 'avatar.tsx');
+
+test('parse-tokens subcommand outputs token JSON', () => {
+  const out = tmp('tokens.json', '');
+  const r = spawnSync('node', [CLI, 'parse-tokens', '--css', FX_CSS, '--output', out], { encoding: 'utf8' });
+  assert.equal(r.status, 0, r.stderr);
+  const t = JSON.parse(fs.readFileSync(out, 'utf8'));
+  assert.ok(t.colors.length > 0);
+});
+
+test('parse-props subcommand outputs props JSON', () => {
+  const out = tmp('props.json', '');
+  const r = spawnSync('node', [CLI, 'parse-props', '--source', FX_AVATAR, '--output', out], { encoding: 'utf8' });
+  assert.equal(r.status, 0, r.stderr);
+  const p = JSON.parse(fs.readFileSync(out, 'utf8'));
+  assert.equal(p.componentName, 'Avatar');
+  assert.ok(p.props.size.values.length === 5);
+});
+
+test('slug subcommand outputs slug map JSON', () => {
+  const out = tmp('slugs.json', '');
+  const r = spawnSync('node', [CLI, 'slug', '--paths', 'app/components/avatar/index.tsx,app/components/avatar-group/index.tsx', '--output', out], { encoding: 'utf8' });
+  assert.equal(r.status, 0, r.stderr);
+  const m = JSON.parse(fs.readFileSync(out, 'utf8'));
+  assert.equal(m['app/components/avatar/index.tsx'], 'avatar');
+});
+
+test('patch-next-config subcommand mutates the file in place', () => {
+  const cfg = tmp('next.config.ts', `import type { NextConfig } from "next";\nconst nextConfig: NextConfig = {};\nexport default nextConfig;\n`);
+  const r = spawnSync('node', [CLI, 'patch-next-config', '--config', cfg, '--route-url', '/-docs'], { encoding: 'utf8' });
+  assert.equal(r.status, 0, r.stderr);
+  const after = fs.readFileSync(cfg, 'utf8');
+  assert.match(after, /pageExtensions:\s*process\.env\.NODE_ENV/);
+});
+
+test('patch-robots subcommand mutates the file in place; creates if missing', () => {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'adhd-ids-robots-'));
+  const robots = path.join(root, 'robots.txt');
+  const r = spawnSync('node', [CLI, 'patch-robots', '--robots', robots, '--route-url', '/-docs'], { encoding: 'utf8' });
+  assert.equal(r.status, 0, r.stderr);
+  const after = fs.readFileSync(robots, 'utf8');
+  assert.match(after, /Disallow: \/-docs/);
+});
+
+test('detect-install subcommand prints existing install paths to stdout', () => {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'adhd-ids-detect-'));
+  fs.mkdirSync(path.join(root, 'app', '(design-system)', '-docs'), { recursive: true });
+  fs.writeFileSync(
+    path.join(root, 'app', '(design-system)', '-docs', 'layout.tsx'),
+    '// design-system-docs-route — auto-generated installer artifact; safe to edit.\nexport default function L({ children }) { return children; }\n',
+  );
+  const r = spawnSync('node', [CLI, 'detect-install', '--app-dir', root], { encoding: 'utf8' });
+  assert.equal(r.status, 0, r.stderr);
+  assert.match(r.stdout, /-docs\/layout\.tsx/);
+});
+
+test('install subcommand writes files based on choices JSON', () => {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'adhd-ids-install-'));
+  fs.mkdirSync(path.join(root, 'app'), { recursive: true });
+  const choices = tmp('choices.json', JSON.stringify({
+    projectRoot: root, groupName: '(design-system)', routeSegment: '-docs', prodExcluded: true,
+  }));
+  const r = spawnSync('node', [CLI, 'install', '--config', choices], { encoding: 'utf8' });
+  assert.equal(r.status, 0, r.stderr);
+  assert.ok(fs.existsSync(path.join(root, 'app', '(design-system)', '-docs', 'page.design-system.tsx')));
+});
diff --git a/plugins/adhd/lib/install-design-system-docs-route/cli.js b/plugins/adhd/lib/install-design-system-docs-route/cli.js
index 5dd68ea..6c15bd9 100644
--- a/plugins/adhd/lib/install-design-system-docs-route/cli.js
+++ b/plugins/adhd/lib/install-design-system-docs-route/cli.js
@@ -1,6 +1,15 @@
 #!/usr/bin/env node
 'use strict';
 
+const fs = require('node:fs');
+const path = require('node:path');
+const { parseTokens } = require('./token-parser');
+const { parseProps } = require('./prop-parser');
+const { slugMap } = require('./slug');
+const { patchNextConfig } = require('./next-config-patcher');
+const { patchRobots } = require('./robots-patcher');
+const { installRoute, detectExistingInstall } = require('./route-installer');
+
 function parseArgs(argv) {
   const args = { _: [] };
   for (let i = 2; i < argv.length; i++) {
@@ -28,7 +37,65 @@ function main() {
   if (args.help) { printUsage(); process.exit(0); }
   if (args._.length === 0) { printUsage(); process.exit(2); }
   const cmd = args._[0];
-  // Subcommands wired in later tasks. Reject unknown to keep behavior strict.
+
+  if (cmd === 'parse-tokens') {
+    if (!args.css || !args.output) { console.error('Usage: parse-tokens --css <path> --output <json>'); process.exit(2); }
+    const css = fs.readFileSync(args.css, 'utf8');
+    fs.writeFileSync(args.output, JSON.stringify(parseTokens(css), null, 2));
+    process.exit(0);
+  }
+
+  if (cmd === 'parse-props') {
+    if (!args.source || !args.output) { console.error('Usage: parse-props --source <tsx> --output <json>'); process.exit(2); }
+    const src = fs.readFileSync(args.source, 'utf8');
+    fs.writeFileSync(args.output, JSON.stringify(parseProps(src), null, 2));
+    process.exit(0);
+  }
+
+  if (cmd === 'slug') {
+    if (!args.paths || !args.output) { console.error('Usage: slug --paths <csv> --output <json>'); process.exit(2); }
+    const paths = args.paths.split(',').map(s => s.trim()).filter(Boolean);
+    fs.writeFileSync(args.output, JSON.stringify(slugMap(paths), null, 2));
+    process.exit(0);
+  }
+
+  if (cmd === 'patch-next-config') {
+    if (!args.config || !args['route-url']) { console.error('Usage: patch-next-config --config <path> --route-url <url>'); process.exit(2); }
+    const src = fs.readFileSync(args.config, 'utf8');
+    const r = patchNextConfig(src, { detectOnly: true });
+    if (r && r.conflict) {
+      console.error('next.config already sets pageExtensions: ' + r.existing);
+      process.exit(3);
+    }
+    const out = patchNextConfig(src);
+    fs.writeFileSync(args.config, out);
+    process.exit(0);
+  }
+
+  if (cmd === 'patch-robots') {
+    if (!args.robots || !args['route-url']) { console.error('Usage: patch-robots --robots <path> --route-url <url>'); process.exit(2); }
+    let src = '';
+    try { src = fs.readFileSync(args.robots, 'utf8'); } catch {}
+    fs.writeFileSync(args.robots, patchRobots(src, args['route-url']));
+    process.exit(0);
+  }
+
+  if (cmd === 'detect-install') {
+    if (!args['app-dir']) { console.error('Usage: detect-install --app-dir <path>'); process.exit(2); }
+    const found = detectExistingInstall(args['app-dir']);
+    for (const f of found) process.stdout.write(f + '\n');
+    process.exit(0);
+  }
+
+  if (cmd === 'install') {
+    if (!args.config) { console.error('Usage: install --config <choices.json>'); process.exit(2); }
+    const choices = JSON.parse(fs.readFileSync(args.config, 'utf8'));
+    if (!choices.projectRoot) { console.error('install: choices.projectRoot is required'); process.exit(2); }
+    const r = installRoute(choices.projectRoot, choices);
+    process.stdout.write(JSON.stringify({ files: r.files }, null, 2) + '\n');
+    process.exit(0);
+  }
+
   console.error('Unknown subcommand: ' + cmd);
   process.exit(2);
 }

From c75f63e814fe7a615f649e1aca23fd569a71e43c Mon Sep 17 00:00:00 2001
From: Hugh Francis <hughfrancis89@gmail.com>
Date: Mon, 11 May 2026 15:15:14 -0400
Subject: [PATCH 17/79] Add /adhd:install-design-system-docs-route skill

---
 .../install-design-system-docs-route/SKILL.md | 147 ++++++++++++++++++
 1 file changed, 147 insertions(+)
 create mode 100644 plugins/adhd/skills/install-design-system-docs-route/SKILL.md

diff --git a/plugins/adhd/skills/install-design-system-docs-route/SKILL.md b/plugins/adhd/skills/install-design-system-docs-route/SKILL.md
new file mode 100644
index 0000000..2b573f4
--- /dev/null
+++ b/plugins/adhd/skills/install-design-system-docs-route/SKILL.md
@@ -0,0 +1,147 @@
+---
+description: "Install a self-generating design-system documentation route into a Next.js consumer app. The route reads adhd.config.ts and globals.css at request time, renders a token catalog (colors / spacing / typography / radius / shadows) plus per-component pages with URL-driven prop toggles. Optionally excluded from production builds via Next.js pageExtensions trick. Re-runnable: marker-comment detection drives updates."
+disable-model-invocation: true
+argument-hint: ""
+allowed-tools: Read Write Edit Bash AskUserQuestion
+---
+
+# ADHD Install Design System Docs Route
+
+One-shot installer that drops a live design-system docs page into a Next.js App Router project. The page reads `adhd.config.ts` and `globals.css` at request time — no regen needed when components or tokens change. Re-running this skill picks up template improvements over time.
+
+**Authoritative spec:** `docs/superpowers/specs/2026-05-11-adhd-install-design-system-docs-route.md`
+
+## Invariants
+
+1. **No ADHD references in generated files** outside of import paths pointing at `adhd.config.ts`. The marker comment is generic.
+2. **adhd.config.ts is NOT modified** by this skill. Install choices live in the filesystem.
+3. **All file writes are idempotent on re-run.** Marker-bearing files are replaced wholesale with the latest templates. Files where the user deleted the marker are left alone.
+
+## Phase 1: Validate consumer environment
+
+```bash
+test -f adhd.config.ts || { echo "Missing adhd.config.ts. Run /adhd:config first."; exit 1; }
+test -d app          || { echo "Missing app/ directory. This installer requires the Next.js App Router."; exit 1; }
+test -f package.json || { echo "No package.json at the working directory."; exit 1; }
+```
+
+Read `package.json` and confirm `next` is in `dependencies` or `devDependencies`. Warn if missing or version < 16; continue anyway.
+
+## Phase 2: Detect existing install
+
+```bash
+node plugins/adhd/lib/install-design-system-docs-route/cli.js detect-install --app-dir .
+```
+
+Output is newline-separated paths of files containing the marker comment.
+
+- **No matches:** fresh install. Proceed to Phase 3 with defaults.
+- **One or more matches:** use `AskUserQuestion`:
+  - "Update in place" — re-write the listed marker-bearing files with the latest templates.
+  - "Move to new location" — Phase 3 reasks the install questions; files at the old location are NOT deleted (the user manages them).
+  - "Abort" — exit with no changes.
+
+If user chose "Update in place," skip ahead to Phase 6 (patch + write) using the existing folder's group/segment as the choice; ask only "Exclude from production builds?" to confirm current state.
+
+## Phase 3: Ask installation choices
+
+Use `AskUserQuestion` three times:
+
+1. **Route URL** — default `/-docs`. Validate: starts with `/`, only `a-z0-9-/` characters, no leading `_`.
+2. **Route group** — default `(design-system)`. Validate: parens-wrapped, alphanumerics + hyphens inside, OR empty string for "no group."
+3. **Exclude from production builds?** — default `Yes`.
+
+Derive `groupName` and `routeSegment` from these answers. Example: routeUrl `/-docs` → routeSegment `-docs`. The group is independent of the URL.
+
+## Phase 4: Detect Next.js config file
+
+```bash
+for f in next.config.ts next.config.mjs next.config.js; do
+  test -f "$f" && echo "$f" && break
+done
+```
+
+If none found: abort with "No next.config.* at the project root. Create one before running this installer."
+
+## Phase 5: Detect filesystem collisions
+
+```bash
+TARGET="app/${GROUP}/${SEGMENT}"
+test -e "$TARGET" && echo "EXISTS" || echo "FREE"
+```
+
+If `EXISTS` and Phase 2 didn't already mark this as an existing install: prompt "Path `<TARGET>` already exists but is not an installer artifact. Pick a different route or abort."
+
+## Phase 6: Patch next.config.ts (only if prod-exclusion: yes)
+
+```bash
+node plugins/adhd/lib/install-design-system-docs-route/cli.js patch-next-config \
+  --config "<next.config.path>" \
+  --route-url "<routeUrl>"
+```
+
+Exit code 3 means an existing different `pageExtensions` was detected. The CLI prints the existing value. Use `AskUserQuestion`: "Your next.config.ts sets pageExtensions to `<existing>`. Merge with the design-system extension conditional? [Yes / Show me the manual patch / Abort]."
+
+On "Yes": re-run the CLI without `detectOnly` (currently errors; for v1, print "Manual merge required. Patch the file to combine the existing pageExtensions with the conditional. Example:" and abort). On "Show me the manual patch": print the patch block and continue with file installs.
+
+## Phase 7: Write the page files
+
+```bash
+node plugins/adhd/lib/install-design-system-docs-route/cli.js install \
+  --config <choices.json>
+```
+
+Where `<choices.json>` is a temp file with shape:
+```json
+{
+  "projectRoot": ".",
+  "groupName": "(design-system)",
+  "routeSegment": "-docs",
+  "prodExcluded": true
+}
+```
+
+The CLI prints the list of files it wrote.
+
+## Phase 8: Patch robots.txt
+
+```bash
+node plugins/adhd/lib/install-design-system-docs-route/cli.js patch-robots \
+  --robots public/robots.txt \
+  --route-url "<routeUrl>"
+```
+
+If `public/` doesn't exist, create it first:
+```bash
+mkdir -p public
+```
+
+## Phase 9: Final report
+
+Print:
+```
+✓ Design system docs route installed.
+
+  URL:            http://localhost:3000<routeUrl>
+  Filesystem:     app/<group>/<segment>/
+  Prod exclusion: <ON | OFF>
+  noindex meta:   ON
+  robots.txt:     Disallow added
+
+Run `npm run dev` and visit the URL to preview. The page reads adhd.config.ts
+and globals.css at request time — no regen needed when you add components or
+tokens.
+
+Re-run /adhd:install-design-system-docs-route to pick up improved templates
+over time. Files where you've removed the marker comment will be left alone.
+```
+
+## Common errors
+
+| Error | Fix-up |
+|---|---|
+| `Missing adhd.config.ts` | Run `/adhd:config` first. |
+| `Missing app/ directory` | This installer requires the Next.js App Router (not Pages Router). |
+| `No next.config.* at the project root` | Create one with a default export of `{}`. |
+| `Path <X> already exists but is not an installer artifact` | Pick a different route URL or move/delete the existing folder. |
+| `next.config.ts sets pageExtensions to <existing>` | Manually merge with the design-system conditional, or skip prod-exclusion. |

From ed6275f2b49493f02279a6b69098654fdc9165a4 Mon Sep 17 00:00:00 2001
From: Hugh Francis <hughfrancis89@gmail.com>
Date: Mon, 11 May 2026 15:16:13 -0400
Subject: [PATCH 18/79] SKILL: clarify Phase 6 exit-code handling and Phase 2
 update-in-place branch

Phase 6 previously said 're-run the CLI without detectOnly (currently errors;
for v1, print ... and abort)' which mixed a forward-looking instruction with a
v1 override in a parenthetical. Replaced with an explicit exit-code table and a
two-option AskUserQuestion that drops the unsupported 'Yes / merge automatically'
branch entirely.

Phase 2's update-in-place handoff to Phase 6 silently overrode Phase 3's
three-question flow. Made the directive explicit: derive group/segment from the
existing folder, skip the first two questions, ask only the prod-exclusion one,
then proceed to Phase 4.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 .../install-design-system-docs-route/SKILL.md | 19 ++++++++++++++++---
 1 file changed, 16 insertions(+), 3 deletions(-)

diff --git a/plugins/adhd/skills/install-design-system-docs-route/SKILL.md b/plugins/adhd/skills/install-design-system-docs-route/SKILL.md
index 2b573f4..2774ce3 100644
--- a/plugins/adhd/skills/install-design-system-docs-route/SKILL.md
+++ b/plugins/adhd/skills/install-design-system-docs-route/SKILL.md
@@ -41,7 +41,7 @@ Output is newline-separated paths of files containing the marker comment.
   - "Move to new location" — Phase 3 reasks the install questions; files at the old location are NOT deleted (the user manages them).
   - "Abort" — exit with no changes.
 
-If user chose "Update in place," skip ahead to Phase 6 (patch + write) using the existing folder's group/segment as the choice; ask only "Exclude from production builds?" to confirm current state.
+If user chose "Update in place": derive `groupName` and `routeSegment` from the existing install's folder path, then skip Phase 3's first two questions (route URL, route group) and ask ONLY question 3 ("Exclude from production builds?") to confirm current state. Then proceed to Phase 4.
 
 ## Phase 3: Ask installation choices
 
@@ -80,9 +80,22 @@ node plugins/adhd/lib/install-design-system-docs-route/cli.js patch-next-config
   --route-url "<routeUrl>"
 ```
 
-Exit code 3 means an existing different `pageExtensions` was detected. The CLI prints the existing value. Use `AskUserQuestion`: "Your next.config.ts sets pageExtensions to `<existing>`. Merge with the design-system extension conditional? [Yes / Show me the manual patch / Abort]."
+Exit codes:
+- `0` — patched successfully (or already at the expected state; idempotent no-op).
+- `3` — the file already sets `pageExtensions` to a different value. The CLI prints the existing value on stdout.
+- non-zero, non-3 — the file's shape isn't safely patchable. Print the manual patch block (see below) and continue with file installs.
 
-On "Yes": re-run the CLI without `detectOnly` (currently errors; for v1, print "Manual merge required. Patch the file to combine the existing pageExtensions with the conditional. Example:" and abort). On "Show me the manual patch": print the patch block and continue with file installs.
+**On exit code 3**, use `AskUserQuestion`: "Your next.config.ts sets pageExtensions to `<existing>`. How do you want to handle it? [Show me the manual patch and continue / Abort]."
+
+Automatic merging is NOT supported in v1. On "Show me the manual patch and continue," print this block and continue with Phase 7:
+
+```ts
+pageExtensions: process.env.NODE_ENV === 'production'
+  ? ['ts', 'tsx']
+  : ['ts', 'tsx', 'design-system.ts', 'design-system.tsx'],
+```
+
+…and tell the user to merge it with their existing `pageExtensions` value by hand. On "Abort," exit with no further changes.
 
 ## Phase 7: Write the page files
 

From 433881baeb699fcdec1a161c3a7c120a84065ebd Mon Sep 17 00:00:00 2001
From: Hugh Francis <hughfrancis89@gmail.com>
Date: Mon, 11 May 2026 15:17:25 -0400
Subject: [PATCH 19/79] config: offer to install the design-system docs route
 as an optional final phase

---
 plugins/adhd/skills/config/SKILL.md | 23 +++++++++++++++++++++++
 1 file changed, 23 insertions(+)

diff --git a/plugins/adhd/skills/config/SKILL.md b/plugins/adhd/skills/config/SKILL.md
index 1b28d27..c8fd0fd 100644
--- a/plugins/adhd/skills/config/SKILL.md
+++ b/plugins/adhd/skills/config/SKILL.md
@@ -235,6 +235,29 @@ Then run /adhd:sync --dry-run to preview your first diff (Figma → code).
 
 If running on a healthy config that didn't change, print `Config unchanged.` instead of the saved-to message.
 
+## Phase 6 (optional): Set up the design-system docs route
+
+Use `AskUserQuestion`:
+
+```
+Question: "Set up the design-system docs route now? It's a live, self-generating
+documentation page that reads your adhd.config.ts and globals.css. Mini-Storybook
+for designers; not indexed by search engines."
+Header: "Docs route"
+Options:
+  - "Yes, install it now"
+  - "No, maybe later"
+```
+
+On "Yes": execute the phases of `/adhd:install-design-system-docs-route` inline.
+See `plugins/adhd/skills/install-design-system-docs-route/SKILL.md` for the
+detailed phase list (validate environment → detect existing install → ask install
+choices → detect Next.js config → detect collisions → patch next.config.ts →
+write files → patch robots.txt → final report).
+
+On "No": print `Run /adhd:install-design-system-docs-route later to set it up.`
+Exit normally.
+
 ## Reference: Common errors and fix-up guidance
 
 ### "The official Figma plugin isn't installed"

From b3865692bcf90abe6ce373769499e3cefdcd5246 Mon Sep 17 00:00:00 2001
From: Hugh Francis <hughfrancis89@gmail.com>
Date: Mon, 11 May 2026 15:18:44 -0400
Subject: [PATCH 20/79] README + marketplace: document
 /adhd:install-design-system-docs-route

---
 .claude-plugin/marketplace.json |  2 +-
 README.md                       | 34 ++++++++++++++++++++++++++++++++-
 2 files changed, 34 insertions(+), 2 deletions(-)

diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json
index 123891b..8c91a63 100644
--- a/.claude-plugin/marketplace.json
+++ b/.claude-plugin/marketplace.json
@@ -7,7 +7,7 @@
     {
       "name": "adhd",
       "source": "./plugins/adhd",
-      "description": "Push, pull, and lint design tokens between Tailwind v4 and Figma; push and pull React components with preflight validation."
+      "description": "Push, pull, and lint design tokens between Tailwind v4 and Figma; push and pull React components with preflight validation; install a live design-system docs route into your Next.js consumer app."
     }
   ]
 }
diff --git a/README.md b/README.md
index 3ac95e5..294b67d 100644
--- a/README.md
+++ b/README.md
@@ -24,7 +24,7 @@ Then install ADHD itself:
 
 All three commands are persistent — Claude Code remembers the marketplaces and the enabled plugins across sessions. Run them once per machine.
 
-After install, six slash commands are available:
+After install, seven slash commands are available:
 
 | Command | Args | Direction | What it does |
 |---|---|---|---|
@@ -34,6 +34,7 @@ After install, six slash commands are available:
 | `/adhd:pull-design-system` | — | Figma → code | Pulls Figma variables + named styles into globals.css |
 | `/adhd:push-component` | `<path> [--max-variants <n>]` | code → Figma | Pushes a React component to Figma as a structured Component Set with variant properties + variable bindings, plus a preflight lint check |
 | `/adhd:pull-component` | `<path \| figma-url> [--allow-unbound]` | Figma → code | Pulls a Figma Component Set into a React source file; updates lookup tables and union types only (function body untouched) |
+| `/adhd:install-design-system-docs-route` | — | install | One-shot installer for a live, self-generating design-system docs route in your Next.js consumer app. Reads adhd.config.ts + globals.css at request time. Excluded from production builds by default. |
 
 Every command above drives Figma exclusively through the `figma@claude-plugins-official` plugin. `/adhd:config` checks it's installed + authenticated up front so setup errors surface where you can fix them, not mid-pipeline.
 
@@ -110,6 +111,37 @@ The skill parses the component's TypeScript prop unions, generates a temp previe
 
 The skill reads the Figma Component Set, diffs it against the React file's `Record<Union, string>` lookup tables, prompts on each divergence, and rewrites only those tables (plus union type members). Function body, JSX, hooks, handlers, and imports are never modified.
 
+### Design system docs route
+
+Run once in your consumer repo:
+
+```
+/adhd:install-design-system-docs-route
+```
+
+This installs a live, self-generating documentation page that reads your
+`adhd.config.ts` and `globals.css` at request time. The default URL is
+`/-docs` (the hyphen prefix telegraphs "internal"), and files live under a
+Next.js route group at `app/(design-system)/-docs/`. The page shows:
+
+- Token catalog: every color / spacing / typography / radius / shadow in your
+  Tailwind v4 `@theme` block, rendered as visual samples.
+- Component pages: each component from `adhd.config.ts`'s `components.*` map
+  gets its own route with URL-driven prop toggles.
+
+By default the route is excluded from production builds via Next.js's
+`pageExtensions` trick — files use the `.design-system.tsx` extension and
+the production build literally doesn't see them. You can opt out at install
+time if you'd rather ship the route (it still has `<meta name="robots"
+content="noindex, nofollow" />` either way).
+
+Re-run the installer over time to pick up improved templates. Files you've
+customized — by removing the `// design-system-docs-route` marker comment —
+are left alone.
+
+You can also trigger the install at the end of `/adhd:config` if you're
+setting up ADHD for the first time.
+
 ### Figma file structure
 
 The Figma file must follow the structure mandated in the spec — a `Primitives` collection (no modes) and a `Semantic` collection (Light + Dark modes). The skill validates this and surfaces fix-up guidance on failure.

From 794ff5c222cd80503263665f6d90a325d02d6b14 Mon Sep 17 00:00:00 2001
From: Hugh Francis <hughfrancis89@gmail.com>
Date: Mon, 11 May 2026 15:37:13 -0400
Subject: [PATCH 21/79] Fix two bugs surfaced by a real-world install in
 reactor-webapp
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Bug 1: Index page Links navigated to the wrong URL.
  The index page used `<Link href={`./${slug}`}>` for component links.
  When the user is at `/-docs` (no trailing slash), browsers resolve
  `./logo` relative to `/-docs` as `/logo` — treating `-docs` like a
  file at the root, not a directory. Result: clicking a component nav'd
  to `/logo` instead of `/-docs/logo`.

  Fix: introduce a `__ROUTE_PATH__` placeholder in INDEX_PAGE_TSX. The
  installer substitutes it with the actual route URL (`/${routeSegment}`)
  at install time. The rendered href becomes the absolute path
  `${routePath}/${slug}` which resolves correctly regardless of how
  Next.js formats the parent URL.

Bug 2: Component pages failed to compile with ENOENT on the build manifest.
  COMPONENT_PAGE_TSX imports `from "../PropToggle"`, but route-installer
  was writing the file as `PropToggle.design-system.tsx`. TypeScript's
  module resolution doesn't try `.design-system.tsx` as a default
  extension, so the import failed. Next.js can't compile the page →
  no build manifest → user sees ENOENT runtime error when navigating
  to `/-docs/<component>`.

  Fix: write PropToggle as plain `PropToggle.tsx` regardless of
  prod-exclusion. The `.design-system` suffix is only needed for files
  that should be excluded from the production build via Next.js's
  `pageExtensions` conditional — and that mechanism only applies to
  route files (page/layout). PropToggle is a regular module: it's only
  bundled if its importing page is in the build, and the page IS
  suffix-excluded, so prod exclusion still works as intended.

Tests:
- 4 new route-installer test cases (PropToggle filename, Link href
  absolute, custom route segment substitution, import resolution).
- Updated existing tests that asserted on the old PropToggle filename.
- 347/347 lib tests pass.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 .../__tests__/route-installer.test.js         | 48 +++++++++++++++++--
 .../route-installer.js                        | 32 +++++++++----
 .../templates.js                              |  2 +-
 3 files changed, 69 insertions(+), 13 deletions(-)

diff --git a/plugins/adhd/lib/install-design-system-docs-route/__tests__/route-installer.test.js b/plugins/adhd/lib/install-design-system-docs-route/__tests__/route-installer.test.js
index 3aba1cc..88f3340 100644
--- a/plugins/adhd/lib/install-design-system-docs-route/__tests__/route-installer.test.js
+++ b/plugins/adhd/lib/install-design-system-docs-route/__tests__/route-installer.test.js
@@ -13,7 +13,7 @@ function makeTempProject() {
   return root;
 }
 
-test('installRoute writes 4 files with the .design-system.tsx extension when prodExcluded', () => {
+test('installRoute writes page/layout files with .design-system.tsx extension when prodExcluded, but PropToggle is always plain .tsx', () => {
   const root = makeTempProject();
   installRoute(root, {
     groupName: '(design-system)',
@@ -21,10 +21,16 @@ test('installRoute writes 4 files with the .design-system.tsx extension when pro
     prodExcluded: true,
   });
   const docsDir = path.join(root, 'app', '(design-system)', '-docs');
+  // Route files (page/layout) get the suffix so pageExtensions filters them in prod.
   assert.ok(fs.existsSync(path.join(docsDir, 'layout.design-system.tsx')));
   assert.ok(fs.existsSync(path.join(docsDir, 'page.design-system.tsx')));
   assert.ok(fs.existsSync(path.join(docsDir, '[component]', 'page.design-system.tsx')));
-  assert.ok(fs.existsSync(path.join(docsDir, 'PropToggle.design-system.tsx')));
+  // PropToggle is a module imported by the page; it doesn't need the suffix for
+  // prod-exclusion (the page that imports it IS suffix-excluded, so nothing
+  // references PropToggle in prod). Plain `.tsx` keeps `import "../PropToggle"`
+  // resolvable via standard TS module resolution.
+  assert.ok(fs.existsSync(path.join(docsDir, 'PropToggle.tsx')));
+  assert.ok(!fs.existsSync(path.join(docsDir, 'PropToggle.design-system.tsx')));
 });
 
 test('installRoute writes plain .tsx files when not prodExcluded', () => {
@@ -49,13 +55,48 @@ test('all written files start with the marker comment', () => {
     'layout.design-system.tsx',
     'page.design-system.tsx',
     '[component]/page.design-system.tsx',
-    'PropToggle.design-system.tsx',
+    'PropToggle.tsx',
   ]) {
     const content = fs.readFileSync(path.join(docsDir, f), 'utf8');
     assert.match(content, /design-system-docs-route/);
   }
 });
 
+test('index page Link href is absolute, using the configured route URL', () => {
+  // Relative hrefs like `./<slug>` resolve incorrectly from `/-docs` (no trailing
+  // slash) — they go to `/<slug>` instead of `/-docs/<slug>`. The installer
+  // substitutes the route URL at install time so the link is absolute.
+  const root = makeTempProject();
+  installRoute(root, { groupName: '(design-system)', routeSegment: '-docs', prodExcluded: true });
+  const indexPage = fs.readFileSync(
+    path.join(root, 'app', '(design-system)', '-docs', 'page.design-system.tsx'),
+    'utf8',
+  );
+  assert.match(indexPage, /href=\{`\/-docs\/\$\{slug\}`\}/);
+  // The placeholder should be fully substituted — no `__ROUTE_PATH__` left over.
+  assert.doesNotMatch(indexPage, /__ROUTE_PATH__/);
+});
+
+test('index page Link href substitution honors a custom route segment', () => {
+  const root = makeTempProject();
+  installRoute(root, { groupName: '(design-system)', routeSegment: 'design-system', prodExcluded: true });
+  const indexPage = fs.readFileSync(
+    path.join(root, 'app', '(design-system)', 'design-system', 'page.design-system.tsx'),
+    'utf8',
+  );
+  assert.match(indexPage, /href=\{`\/design-system\/\$\{slug\}`\}/);
+});
+
+test('COMPONENT_PAGE_TSX imports PropToggle from "../PropToggle" (resolves to the plain .tsx file)', () => {
+  const root = makeTempProject();
+  installRoute(root, { groupName: '(design-system)', routeSegment: '-docs', prodExcluded: true });
+  const componentPage = fs.readFileSync(
+    path.join(root, 'app', '(design-system)', '-docs', '[component]', 'page.design-system.tsx'),
+    'utf8',
+  );
+  assert.match(componentPage, /from "\.\.\/PropToggle"/);
+});
+
 test('detectExistingInstall scans for the marker and returns matching files', () => {
   const root = makeTempProject();
   installRoute(root, { groupName: '(design-system)', routeSegment: '-docs', prodExcluded: true });
@@ -94,4 +135,5 @@ test('installRoute supports an empty groupName (no route group)', () => {
   installRoute(root, { groupName: '', routeSegment: '-docs', prodExcluded: true });
   const docsDir = path.join(root, 'app', '-docs');
   assert.ok(fs.existsSync(path.join(docsDir, 'layout.design-system.tsx')));
+  assert.ok(fs.existsSync(path.join(docsDir, 'PropToggle.tsx')));
 });
diff --git a/plugins/adhd/lib/install-design-system-docs-route/route-installer.js b/plugins/adhd/lib/install-design-system-docs-route/route-installer.js
index 61cfb59..e36f52d 100644
--- a/plugins/adhd/lib/install-design-system-docs-route/route-installer.js
+++ b/plugins/adhd/lib/install-design-system-docs-route/route-installer.js
@@ -12,27 +12,41 @@ function installRoute(projectRoot, opts) {
   const { groupName = '', routeSegment, prodExcluded } = opts;
   if (!routeSegment) throw new Error('routeSegment is required');
 
-  const ext = prodExcluded ? '.design-system.tsx' : '.tsx';
+  // Page/layout files get the `.design-system.tsx` extension only when prod-excluded
+  // so Next.js's `pageExtensions` conditional filters them out of production builds.
+  const pageExt = prodExcluded ? '.design-system.tsx' : '.tsx';
+  // PropToggle is a regular module (not a route file by name), so it doesn't need
+  // the `.design-system` suffix to be excluded — it's only bundled if its importing
+  // page is in the build, and the page IS suffix-excluded. Using a plain `.tsx`
+  // keeps the `import "../PropToggle"` in COMPONENT_PAGE_TSX resolvable.
+  const moduleExt = '.tsx';
   const segments = ['app'];
   if (groupName) segments.push(groupName);
   segments.push(routeSegment);
   const docsDir = path.join(projectRoot, ...segments);
   const componentDir = path.join(docsDir, '[component]');
 
+  // The runtime route URL (route groups like `(design-system)` are invisible in URLs,
+  // so the URL is just `/<routeSegment>`). Templates use `__ROUTE_PATH__` as a
+  // placeholder for this — relative hrefs like `./<slug>` would resolve incorrectly
+  // when the current path is `/<segment>` without a trailing slash.
+  const routeUrl = '/' + routeSegment;
+  const indexBody = INDEX_PAGE_TSX.replace(/__ROUTE_PATH__/g, routeUrl);
+
   mkdirpSync(docsDir);
   mkdirpSync(componentDir);
 
-  fs.writeFileSync(path.join(docsDir, `layout${ext}`), LAYOUT_TSX);
-  fs.writeFileSync(path.join(docsDir, `page${ext}`), INDEX_PAGE_TSX);
-  fs.writeFileSync(path.join(componentDir, `page${ext}`), COMPONENT_PAGE_TSX);
-  fs.writeFileSync(path.join(docsDir, `PropToggle${ext}`), PROP_TOGGLE_TSX);
+  fs.writeFileSync(path.join(docsDir, `layout${pageExt}`), LAYOUT_TSX);
+  fs.writeFileSync(path.join(docsDir, `page${pageExt}`), indexBody);
+  fs.writeFileSync(path.join(componentDir, `page${pageExt}`), COMPONENT_PAGE_TSX);
+  fs.writeFileSync(path.join(docsDir, `PropToggle${moduleExt}`), PROP_TOGGLE_TSX);
 
   return {
     files: [
-      path.join(docsDir, `layout${ext}`),
-      path.join(docsDir, `page${ext}`),
-      path.join(componentDir, `page${ext}`),
-      path.join(docsDir, `PropToggle${ext}`),
+      path.join(docsDir, `layout${pageExt}`),
+      path.join(docsDir, `page${pageExt}`),
+      path.join(componentDir, `page${pageExt}`),
+      path.join(docsDir, `PropToggle${moduleExt}`),
     ],
   };
 }
diff --git a/plugins/adhd/lib/install-design-system-docs-route/templates.js b/plugins/adhd/lib/install-design-system-docs-route/templates.js
index 35e5fad..6bde9b5 100644
--- a/plugins/adhd/lib/install-design-system-docs-route/templates.js
+++ b/plugins/adhd/lib/install-design-system-docs-route/templates.js
@@ -170,7 +170,7 @@ export default async function DesignSystemIndex() {
             {cfg.components.map(p => {
               const slug = p.replace(/\\.tsx?$/, "").replace(/\\/index$/, "").split("/").pop()?.toLowerCase() ?? p;
               return (
-                <Link key={p} href={\`./\${slug}\`} className="rounded border border-zinc-200 dark:border-zinc-800 p-4 hover:bg-zinc-100 dark:hover:bg-zinc-900">
+                <Link key={p} href={\`__ROUTE_PATH__/\${slug}\`} className="rounded border border-zinc-200 dark:border-zinc-800 p-4 hover:bg-zinc-100 dark:hover:bg-zinc-900">
                   <div className="text-sm font-medium">{slug}</div>
                   <div className="text-xs text-zinc-500 truncate">{p}</div>
                 </Link>

From fda97b4bd01173302cfd5c02be00af86a0f04df4 Mon Sep 17 00:00:00 2001
From: Hugh Francis <hughfrancis89@gmail.com>
Date: Mon, 11 May 2026 15:56:41 -0400
Subject: [PATCH 22/79] docs-route: sidebar+viewer layout, expanded token
 domains, Tailwind-default empty states
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

User feedback on the v1 install in reactor-webapp:

1. "No colors/spacing detected" with a populated globals.css — the inline
   parser in the index page used /@theme\s*\{/ which didn't match the
   `@theme inline { ... }` modifier syntax. The lib's token-parser already
   handled it correctly via a brace-counted scan; the inline duplicate in
   the page template did not. Templates now share the brace-counted scan.

2. "Only five domains, but Tailwind v4 tracks far more." Token parser and
   pages now cover 12 domains: colors, spacing, typography, font, font-weight,
   tracking, leading, radius, shadows, breakpoints, easing, animation.
   `inset-shadow-*` and `drop-shadow-*` merge into the shadows bucket.
   Prefix-map order ensures longer prefixes (`font-weight-`) win over
   shorter ones (`font-`).

3. "Empty states should reference Tailwind defaults, not 'no X detected'."
   Each domain renders an empty state that links to the relevant Tailwind v4
   theme docs page.

4. "Put the domains in a sidebar; viewer on the right." Layout is now a
   persistent sidebar (token domains + component list, both read at request
   time) and a main pane that renders the active sub-route:
     app/(group)/<seg>/layout.design-system.tsx       — sidebar
     app/(group)/<seg>/page.design-system.tsx         — landing
     app/(group)/<seg>/tokens/[domain]/page.*         — per-domain renderer
     app/(group)/<seg>/components/[component]/page.*  — component viewer
     app/(group)/<seg>/PropToggle.tsx                 — client toggle

5. Re-installer now removes marker-bearing files left over from older
   template layouts (e.g. the old `[component]/page.*` directly under
   docsDir is removed when the new `components/[component]/page.*`
   replaces it), and prunes the now-empty parent directories. User-authored
   files without the marker are preserved.

README and SKILL frontmatter updated to describe the new layout.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 README.md                                     |  18 +-
 .../__fixtures__/globals.css                  |  25 +
 .../__tests__/route-installer.test.js         | 126 ++++-
 .../__tests__/templates.test.js               |  40 +-
 .../__tests__/token-parser.test.js            |  59 +-
 .../route-installer.js                        | 109 +++-
 .../templates.js                              | 526 +++++++++++++-----
 .../token-parser.js                           |  56 +-
 .../install-design-system-docs-route/SKILL.md |   2 +-
 9 files changed, 737 insertions(+), 224 deletions(-)

diff --git a/README.md b/README.md
index 294b67d..36798ca 100644
--- a/README.md
+++ b/README.md
@@ -122,12 +122,18 @@ Run once in your consumer repo:
 This installs a live, self-generating documentation page that reads your
 `adhd.config.ts` and `globals.css` at request time. The default URL is
 `/-docs` (the hyphen prefix telegraphs "internal"), and files live under a
-Next.js route group at `app/(design-system)/-docs/`. The page shows:
-
-- Token catalog: every color / spacing / typography / radius / shadow in your
-  Tailwind v4 `@theme` block, rendered as visual samples.
-- Component pages: each component from `adhd.config.ts`'s `components.*` map
-  gets its own route with URL-driven prop toggles.
+Next.js route group at `app/(design-system)/-docs/`. The page is a
+sidebar-and-viewer layout:
+
+- Sidebar: lists every Tailwind v4 token domain (colors, spacing, typography,
+  font families, font weights, tracking, leading, radius, shadows,
+  breakpoints, easing, animation), plus every component tracked in
+  `adhd.config.ts`. Click a row to load that route in the main pane.
+- Token pages: render whatever your `@theme` (or `@theme inline`) block
+  declares for that domain. Empty domains link to Tailwind v4's docs for the
+  defaults you're inheriting.
+- Component pages: each component gets its own route with URL-driven prop
+  toggles, derived from the component's TypeScript prop interface.
 
 By default the route is excluded from production builds via Next.js's
 `pageExtensions` trick — files use the `.design-system.tsx` extension and
diff --git a/plugins/adhd/lib/install-design-system-docs-route/__fixtures__/globals.css b/plugins/adhd/lib/install-design-system-docs-route/__fixtures__/globals.css
index df82b02..07d5006 100644
--- a/plugins/adhd/lib/install-design-system-docs-route/__fixtures__/globals.css
+++ b/plugins/adhd/lib/install-design-system-docs-route/__fixtures__/globals.css
@@ -17,6 +17,31 @@
 
   --shadow-sm: 0 1px 2px 0 rgb(0 0 0 / 0.05);
   --shadow-md: 0 4px 6px -1px rgb(0 0 0 / 0.1);
+  --inset-shadow-sm: inset 0 1px 2px 0 rgb(0 0 0 / 0.05);
+  --drop-shadow-sm: 0 1px 2px rgb(0 0 0 / 0.05);
 
   --font-sans: "Inter", system-ui, sans-serif;
+  --font-mono: "JetBrains Mono", monospace;
+
+  --font-weight-normal: 400;
+  --font-weight-bold: 700;
+
+  --tracking-tight: -0.025em;
+  --tracking-wide: 0.025em;
+
+  --leading-tight: 1.25;
+  --leading-loose: 2;
+
+  --breakpoint-sm: 40rem;
+  --breakpoint-md: 48rem;
+
+  --ease-in-out: cubic-bezier(0.4, 0, 0.2, 1);
+
+  --animate-spin: spin 1s linear infinite;
+
+  --some-mystery-var: 42;
+}
+
+@theme inline {
+  --color-alias-bg: var(--color-zinc-50);
 }
diff --git a/plugins/adhd/lib/install-design-system-docs-route/__tests__/route-installer.test.js b/plugins/adhd/lib/install-design-system-docs-route/__tests__/route-installer.test.js
index 88f3340..ee9807f 100644
--- a/plugins/adhd/lib/install-design-system-docs-route/__tests__/route-installer.test.js
+++ b/plugins/adhd/lib/install-design-system-docs-route/__tests__/route-installer.test.js
@@ -13,7 +13,7 @@ function makeTempProject() {
   return root;
 }
 
-test('installRoute writes page/layout files with .design-system.tsx extension when prodExcluded, but PropToggle is always plain .tsx', () => {
+test('installRoute writes page/layout files with .design-system.tsx suffix when prodExcluded, but PropToggle is always plain .tsx', () => {
   const root = makeTempProject();
   installRoute(root, {
     groupName: '(design-system)',
@@ -24,11 +24,10 @@ test('installRoute writes page/layout files with .design-system.tsx extension wh
   // Route files (page/layout) get the suffix so pageExtensions filters them in prod.
   assert.ok(fs.existsSync(path.join(docsDir, 'layout.design-system.tsx')));
   assert.ok(fs.existsSync(path.join(docsDir, 'page.design-system.tsx')));
-  assert.ok(fs.existsSync(path.join(docsDir, '[component]', 'page.design-system.tsx')));
-  // PropToggle is a module imported by the page; it doesn't need the suffix for
-  // prod-exclusion (the page that imports it IS suffix-excluded, so nothing
-  // references PropToggle in prod). Plain `.tsx` keeps `import "../PropToggle"`
-  // resolvable via standard TS module resolution.
+  assert.ok(fs.existsSync(path.join(docsDir, 'tokens', '[domain]', 'page.design-system.tsx')));
+  assert.ok(fs.existsSync(path.join(docsDir, 'components', '[component]', 'page.design-system.tsx')));
+  // PropToggle is a module imported by the component page; it doesn't need the
+  // suffix for prod-exclusion (the page that imports it IS suffix-excluded).
   assert.ok(fs.existsSync(path.join(docsDir, 'PropToggle.tsx')));
   assert.ok(!fs.existsSync(path.join(docsDir, 'PropToggle.design-system.tsx')));
 });
@@ -43,7 +42,8 @@ test('installRoute writes plain .tsx files when not prodExcluded', () => {
   const docsDir = path.join(root, 'app', '(design-system)', '-docs');
   assert.ok(fs.existsSync(path.join(docsDir, 'layout.tsx')));
   assert.ok(fs.existsSync(path.join(docsDir, 'page.tsx')));
-  assert.ok(fs.existsSync(path.join(docsDir, '[component]', 'page.tsx')));
+  assert.ok(fs.existsSync(path.join(docsDir, 'tokens', '[domain]', 'page.tsx')));
+  assert.ok(fs.existsSync(path.join(docsDir, 'components', '[component]', 'page.tsx')));
   assert.ok(fs.existsSync(path.join(docsDir, 'PropToggle.tsx')));
 });
 
@@ -54,7 +54,8 @@ test('all written files start with the marker comment', () => {
   for (const f of [
     'layout.design-system.tsx',
     'page.design-system.tsx',
-    '[component]/page.design-system.tsx',
+    'tokens/[domain]/page.design-system.tsx',
+    'components/[component]/page.design-system.tsx',
     'PropToggle.tsx',
   ]) {
     const content = fs.readFileSync(path.join(docsDir, f), 'utf8');
@@ -62,46 +63,87 @@ test('all written files start with the marker comment', () => {
   }
 });
 
-test('index page Link href is absolute, using the configured route URL', () => {
-  // Relative hrefs like `./<slug>` resolve incorrectly from `/-docs` (no trailing
-  // slash) — they go to `/<slug>` instead of `/-docs/<slug>`. The installer
-  // substitutes the route URL at install time so the link is absolute.
+test('layout sidebar links use absolute hrefs derived from the route segment', () => {
+  // The sidebar lives in the layout, so its links must use absolute hrefs
+  // (`/-docs/tokens/colors`, not `./tokens/colors`) — otherwise nested routes
+  // resolve from the current pathname instead of the docs root.
   const root = makeTempProject();
   installRoute(root, { groupName: '(design-system)', routeSegment: '-docs', prodExcluded: true });
-  const indexPage = fs.readFileSync(
-    path.join(root, 'app', '(design-system)', '-docs', 'page.design-system.tsx'),
+  const layout = fs.readFileSync(
+    path.join(root, 'app', '(design-system)', '-docs', 'layout.design-system.tsx'),
     'utf8',
   );
-  assert.match(indexPage, /href=\{`\/-docs\/\$\{slug\}`\}/);
+  assert.match(layout, /href=\{`\/-docs\/tokens\/\$\{d\.slug\}`\}/);
+  assert.match(layout, /href=\{`\/-docs\/components\/\$\{c\.slug\}`\}/);
   // The placeholder should be fully substituted — no `__ROUTE_PATH__` left over.
-  assert.doesNotMatch(indexPage, /__ROUTE_PATH__/);
+  assert.doesNotMatch(layout, /__ROUTE_PATH__/);
 });
 
-test('index page Link href substitution honors a custom route segment', () => {
+test('route URL substitution honors a custom route segment', () => {
   const root = makeTempProject();
   installRoute(root, { groupName: '(design-system)', routeSegment: 'design-system', prodExcluded: true });
-  const indexPage = fs.readFileSync(
-    path.join(root, 'app', '(design-system)', 'design-system', 'page.design-system.tsx'),
+  const layout = fs.readFileSync(
+    path.join(root, 'app', '(design-system)', 'design-system', 'layout.design-system.tsx'),
     'utf8',
   );
-  assert.match(indexPage, /href=\{`\/design-system\/\$\{slug\}`\}/);
+  assert.match(layout, /href=\{`\/design-system\/tokens\/\$\{d\.slug\}`\}/);
 });
 
-test('COMPONENT_PAGE_TSX imports PropToggle from "../PropToggle" (resolves to the plain .tsx file)', () => {
+test('COMPONENT_PAGE_TSX imports PropToggle from "../../PropToggle" (now two levels deep)', () => {
   const root = makeTempProject();
   installRoute(root, { groupName: '(design-system)', routeSegment: '-docs', prodExcluded: true });
   const componentPage = fs.readFileSync(
-    path.join(root, 'app', '(design-system)', '-docs', '[component]', 'page.design-system.tsx'),
+    path.join(root, 'app', '(design-system)', '-docs', 'components', '[component]', 'page.design-system.tsx'),
     'utf8',
   );
-  assert.match(componentPage, /from "\.\.\/PropToggle"/);
+  assert.match(componentPage, /from "\.\.\/\.\.\/PropToggle"/);
+});
+
+test('TOKENS_PAGE_TSX uses parser that handles `@theme inline { ... }` modifier syntax', () => {
+  const root = makeTempProject();
+  installRoute(root, { groupName: '(design-system)', routeSegment: '-docs', prodExcluded: true });
+  const tokensPage = fs.readFileSync(
+    path.join(root, 'app', '(design-system)', '-docs', 'tokens', '[domain]', 'page.design-system.tsx'),
+    'utf8',
+  );
+  // The inline parser must use the brace-counted scan (NOT the old
+  // `/@theme\s*\{...\}/` regex that misses `@theme inline { ... }`).
+  assert.match(tokensPage, /extractThemeBodies/);
+  // No naïve `@theme\s*\{` regex anywhere.
+  assert.doesNotMatch(tokensPage, /@theme\\s\*\\\{/);
+});
+
+test('TOKENS_PAGE_TSX renders all expected token domains', () => {
+  const root = makeTempProject();
+  installRoute(root, { groupName: '(design-system)', routeSegment: '-docs', prodExcluded: true });
+  const tokensPage = fs.readFileSync(
+    path.join(root, 'app', '(design-system)', '-docs', 'tokens', '[domain]', 'page.design-system.tsx'),
+    'utf8',
+  );
+  for (const slug of ['colors', 'spacing', 'typography', 'font', 'font-weight',
+                      'tracking', 'leading', 'radius', 'shadows', 'breakpoint',
+                      'ease', 'animate']) {
+    assert.match(tokensPage, new RegExp(`slug === "${slug}"`), `missing renderer for ${slug}`);
+  }
+});
+
+test('empty-state messaging references Tailwind defaults, not "no X detected"', () => {
+  const root = makeTempProject();
+  installRoute(root, { groupName: '(design-system)', routeSegment: '-docs', prodExcluded: true });
+  const tokensPage = fs.readFileSync(
+    path.join(root, 'app', '(design-system)', '-docs', 'tokens', '[domain]', 'page.design-system.tsx'),
+    'utf8',
+  );
+  assert.match(tokensPage, /Tailwind v4 ships sensible defaults/);
+  // The misleading "No X detected" phrasing is gone.
+  assert.doesNotMatch(tokensPage, /No (colors|typography|radius|shadow) (tokens? )?detected/);
 });
 
 test('detectExistingInstall scans for the marker and returns matching files', () => {
   const root = makeTempProject();
   installRoute(root, { groupName: '(design-system)', routeSegment: '-docs', prodExcluded: true });
   const found = detectExistingInstall(root);
-  assert.ok(found.length >= 4);
+  assert.ok(found.length >= 5);
   assert.ok(found.every(p => p.includes('-docs')));
 });
 
@@ -117,23 +159,53 @@ test('detectExistingInstall does not match unrelated files', () => {
   assert.deepEqual(detectExistingInstall(root), []);
 });
 
-test('re-running installRoute is safe (overwrites files cleanly)', () => {
+test('re-running installRoute overwrites files cleanly', () => {
   const root = makeTempProject();
   installRoute(root, { groupName: '(design-system)', routeSegment: '-docs', prodExcluded: true });
-  // Modify a file
   const layoutPath = path.join(root, 'app', '(design-system)', '-docs', 'layout.design-system.tsx');
   fs.writeFileSync(layoutPath, 'corrupted');
-  // Re-install
   installRoute(root, { groupName: '(design-system)', routeSegment: '-docs', prodExcluded: true });
   const after = fs.readFileSync(layoutPath, 'utf8');
   assert.match(after, /design-system-docs-route/);
   assert.match(after, /DesignSystemDocsLayout/);
 });
 
+test('installRoute removes stale marker-bearing files from a previous install layout', () => {
+  // Simulate an older install where the component page lived at `[component]/page.*`
+  // directly under docsDir (the structure before the tokens/[domain] + components/[component] split).
+  const root = makeTempProject();
+  const docsDir = path.join(root, 'app', '(design-system)', '-docs');
+  const oldComponentDir = path.join(docsDir, '[component]');
+  fs.mkdirSync(oldComponentDir, { recursive: true });
+  const oldPath = path.join(oldComponentDir, 'page.design-system.tsx');
+  fs.writeFileSync(oldPath, '// design-system-docs-route — stale\nexport default function Old() { return null; }\n');
+
+  const result = installRoute(root, { groupName: '(design-system)', routeSegment: '-docs', prodExcluded: true });
+
+  // Stale file removed, reported in `removed`, and its now-empty parent dir pruned.
+  assert.ok(!fs.existsSync(oldPath), 'stale file should be deleted');
+  assert.ok(result.removed.includes(oldPath));
+  assert.ok(!fs.existsSync(oldComponentDir), 'empty `[component]` directory should be pruned');
+});
+
+test('installRoute does NOT delete unrelated files (only marker-bearing ones)', () => {
+  const root = makeTempProject();
+  const docsDir = path.join(root, 'app', '(design-system)', '-docs');
+  // Pre-install a user-authored file under docsDir without the marker.
+  fs.mkdirSync(docsDir, { recursive: true });
+  const userFile = path.join(docsDir, 'user-notes.tsx');
+  fs.writeFileSync(userFile, '// user wrote this\nexport const NOTE = "keep me";\n');
+
+  installRoute(root, { groupName: '(design-system)', routeSegment: '-docs', prodExcluded: true });
+
+  assert.ok(fs.existsSync(userFile), 'user file without marker must be preserved');
+});
+
 test('installRoute supports an empty groupName (no route group)', () => {
   const root = makeTempProject();
   installRoute(root, { groupName: '', routeSegment: '-docs', prodExcluded: true });
   const docsDir = path.join(root, 'app', '-docs');
   assert.ok(fs.existsSync(path.join(docsDir, 'layout.design-system.tsx')));
   assert.ok(fs.existsSync(path.join(docsDir, 'PropToggle.tsx')));
+  assert.ok(fs.existsSync(path.join(docsDir, 'tokens', '[domain]', 'page.design-system.tsx')));
 });
diff --git a/plugins/adhd/lib/install-design-system-docs-route/__tests__/templates.test.js b/plugins/adhd/lib/install-design-system-docs-route/__tests__/templates.test.js
index cbd7749..d1bf90a 100644
--- a/plugins/adhd/lib/install-design-system-docs-route/__tests__/templates.test.js
+++ b/plugins/adhd/lib/install-design-system-docs-route/__tests__/templates.test.js
@@ -2,7 +2,7 @@
 
 const test = require('node:test');
 const assert = require('node:assert/strict');
-const { MARKER_COMMENT, LAYOUT_TSX, INDEX_PAGE_TSX, COMPONENT_PAGE_TSX, PROP_TOGGLE_TSX } = require('../templates');
+const { MARKER_COMMENT, LAYOUT_TSX, INDEX_PAGE_TSX, TOKENS_PAGE_TSX, COMPONENT_PAGE_TSX, PROP_TOGGLE_TSX } = require('../templates');
 
 test('MARKER_COMMENT is a stable, non-ADHD-referencing string', () => {
   assert.match(MARKER_COMMENT, /design-system-docs-route/);
@@ -19,20 +19,40 @@ test('LAYOUT_TSX sets robots: noindex / nofollow', () => {
 });
 
 test('LAYOUT_TSX has no ADHD references outside marker', () => {
-  // marker excluded
-  const body = LAYOUT_TSX.replace(MARKER_COMMENT, '');
+  // marker excluded — the filename `adhd.config.ts` is the spec-allowed exception
+  // (the layout reads it to populate the Components sidebar list).
+  const body = LAYOUT_TSX.replace(MARKER_COMMENT, '').replace(/adhd\.config\.ts/g, '');
   assert.equal(/adhd/i.test(body), false);
 });
 
-test('INDEX_PAGE_TSX renders sections for each token domain', () => {
-  for (const section of ['Colors', 'Spacing', 'Typography', 'Radius', 'Shadows', 'Components']) {
-    assert.match(INDEX_PAGE_TSX, new RegExp(section));
+test('LAYOUT_TSX renders sidebar nav linking every token domain', () => {
+  // The sidebar replaces the old single-page sections — every token domain
+  // gets its own entry in the layout's nav.
+  for (const label of [
+    'Colors', 'Spacing', 'Typography', 'Font Families', 'Font Weights',
+    'Tracking', 'Leading', 'Radius', 'Shadows', 'Breakpoints', 'Easing', 'Animation',
+  ]) {
+    assert.match(LAYOUT_TSX, new RegExp(label), `missing sidebar label: ${label}`);
   }
 });
 
-test('INDEX_PAGE_TSX reads adhd.config.ts and globals.css via fs', () => {
-  assert.match(INDEX_PAGE_TSX, /adhd\.config\.ts/);
-  assert.match(INDEX_PAGE_TSX, /globals\.css|cssEntry/);
+test('LAYOUT_TSX reads adhd.config.ts to populate the Components sidebar list', () => {
+  // The sidebar lists tracked components below the token domains — the layout
+  // must read adhd.config.ts at request time to know what to show.
+  assert.match(LAYOUT_TSX, /adhd\.config\.ts/);
+  assert.match(LAYOUT_TSX, /Components/);
+});
+
+test('INDEX_PAGE_TSX is a minimal landing page (sections moved to TOKENS_PAGE_TSX)', () => {
+  // The landing page now just welcomes the user; per-domain renderers live in
+  // the tokens page that the sidebar links to.
+  assert.match(INDEX_PAGE_TSX, /Design System/);
+  assert.match(INDEX_PAGE_TSX, /Pick a token domain|Pick a/);
+});
+
+test('TOKENS_PAGE_TSX reads globals.css to render tokens at request time', () => {
+  assert.match(TOKENS_PAGE_TSX, /globals\.css|cssEntry/);
+  assert.match(TOKENS_PAGE_TSX, /parseTokens/);
 });
 
 test('COMPONENT_PAGE_TSX uses parametric template-string dynamic import', () => {
@@ -60,7 +80,7 @@ test('none of the templates contain "ADHD" outside the marker', () => {
   // (per the install spec) and is not a reference to the ADHD plugin/brand —
   // it's an unavoidable filename the generated pages must read at runtime.
   // Strip it before applying the "no ADHD references" rule.
-  for (const [name, content] of Object.entries({ LAYOUT_TSX, INDEX_PAGE_TSX, COMPONENT_PAGE_TSX, PROP_TOGGLE_TSX })) {
+  for (const [name, content] of Object.entries({ LAYOUT_TSX, INDEX_PAGE_TSX, TOKENS_PAGE_TSX, COMPONENT_PAGE_TSX, PROP_TOGGLE_TSX })) {
     const body = content.replace(MARKER_COMMENT, '').replace(/adhd\.config\.ts/g, '');
     assert.equal(/adhd/i.test(body), false, `${name} must not reference ADHD outside marker`);
   }
diff --git a/plugins/adhd/lib/install-design-system-docs-route/__tests__/token-parser.test.js b/plugins/adhd/lib/install-design-system-docs-route/__tests__/token-parser.test.js
index 7423f5c..bdb442e 100644
--- a/plugins/adhd/lib/install-design-system-docs-route/__tests__/token-parser.test.js
+++ b/plugins/adhd/lib/install-design-system-docs-route/__tests__/token-parser.test.js
@@ -56,9 +56,59 @@ test('extracts shadow tokens', () => {
   );
 });
 
+test('extracts font family tokens', () => {
+  const t = parseTokens(CSS);
+  assert.deepEqual(
+    t.fonts.find(f => f.name === 'sans'),
+    { name: 'sans', value: '"Inter", system-ui, sans-serif' },
+  );
+  assert.deepEqual(
+    t.fonts.find(f => f.name === 'mono'),
+    { name: 'mono', value: '"JetBrains Mono", monospace' },
+  );
+});
+
+test('extracts font-weight tokens (longest prefix wins over `font-`)', () => {
+  const t = parseTokens(CSS);
+  assert.deepEqual(
+    t.fontWeights.find(w => w.name === 'normal'),
+    { name: 'normal', value: '400' },
+  );
+  // `--font-weight-bold` MUST classify as fontWeights, not fonts — the
+  // prefix-map's order guarantees the longer prefix (`font-weight-`) wins.
+  assert.ok(!t.fonts.find(f => f.name === 'weight-bold'));
+});
+
+test('merges inset-shadow-* and drop-shadow-* into the shadows bucket', () => {
+  const t = parseTokens(CSS);
+  // Both `--inset-shadow-sm` and `--drop-shadow-sm` land in `shadows` alongside `--shadow-sm`.
+  const names = t.shadows.map(s => s.name);
+  assert.ok(names.includes('sm'));
+  assert.ok(names.includes('sm') && t.shadows.filter(s => s.name === 'sm').length >= 1);
+  // Distinguish by the leaf — `inset-shadow-sm` becomes leaf `sm`, but we keep
+  // the original prefix off so installers can render them grouped.
+  // For now, accept multiple entries with the same leaf name.
+  assert.ok(t.shadows.length >= 3);
+});
+
+test('extracts tracking, leading, breakpoints, easings, animations', () => {
+  const t = parseTokens(CSS);
+  assert.deepEqual(t.tracking.find(x => x.name === 'tight'), { name: 'tight', value: '-0.025em' });
+  assert.deepEqual(t.leading.find(x => x.name === 'tight'), { name: 'tight', value: '1.25' });
+  assert.deepEqual(t.breakpoints.find(x => x.name === 'sm'), { name: 'sm', value: '40rem' });
+  assert.deepEqual(t.easings.find(x => x.name === 'in-out'), { name: 'in-out', value: 'cubic-bezier(0.4, 0, 0.2, 1)' });
+  assert.deepEqual(t.animations.find(x => x.name === 'spin'), { name: 'spin', value: 'spin 1s linear infinite' });
+});
+
 test('puts unrecognized @theme vars in `unknown`', () => {
   const t = parseTokens(CSS);
-  assert.ok(t.unknown.find(u => u.name === '--font-sans'));
+  assert.ok(t.unknown.find(u => u.name === '--some-mystery-var'));
+});
+
+test('handles `@theme inline { ... }` modifier syntax', () => {
+  const t = parseTokens(CSS);
+  // The aliased color from the `@theme inline { ... }` block must be picked up.
+  assert.ok(t.colors.find(c => c.name === 'alias-bg' && c.value === 'var(--color-zinc-50)'));
 });
 
 test('returns empty domains when no @theme block exists', () => {
@@ -67,6 +117,13 @@ test('returns empty domains when no @theme block exists', () => {
   assert.deepEqual(t.typography, []);
   assert.deepEqual(t.radius, []);
   assert.deepEqual(t.shadows, []);
+  assert.deepEqual(t.fonts, []);
+  assert.deepEqual(t.fontWeights, []);
+  assert.deepEqual(t.tracking, []);
+  assert.deepEqual(t.leading, []);
+  assert.deepEqual(t.breakpoints, []);
+  assert.deepEqual(t.easings, []);
+  assert.deepEqual(t.animations, []);
   assert.equal(t.spacing.multiplier, null);
 });
 
diff --git a/plugins/adhd/lib/install-design-system-docs-route/route-installer.js b/plugins/adhd/lib/install-design-system-docs-route/route-installer.js
index e36f52d..1c1a538 100644
--- a/plugins/adhd/lib/install-design-system-docs-route/route-installer.js
+++ b/plugins/adhd/lib/install-design-system-docs-route/route-installer.js
@@ -2,7 +2,15 @@
 
 const fs = require('node:fs');
 const path = require('node:path');
-const { MARKER_COMMENT, LAYOUT_TSX, INDEX_PAGE_TSX, COMPONENT_PAGE_TSX, PROP_TOGGLE_TSX } = require('./templates');
+const {
+  LAYOUT_TSX,
+  INDEX_PAGE_TSX,
+  TOKENS_PAGE_TSX,
+  COMPONENT_PAGE_TSX,
+  PROP_TOGGLE_TSX,
+} = require('./templates');
+
+const MARKER_STR = 'design-system-docs-route';
 
 function mkdirpSync(p) {
   fs.mkdirSync(p, { recursive: true });
@@ -18,39 +26,102 @@ function installRoute(projectRoot, opts) {
   // PropToggle is a regular module (not a route file by name), so it doesn't need
   // the `.design-system` suffix to be excluded — it's only bundled if its importing
   // page is in the build, and the page IS suffix-excluded. Using a plain `.tsx`
-  // keeps the `import "../PropToggle"` in COMPONENT_PAGE_TSX resolvable.
+  // keeps the `import "../../PropToggle"` in COMPONENT_PAGE_TSX resolvable.
   const moduleExt = '.tsx';
   const segments = ['app'];
   if (groupName) segments.push(groupName);
   segments.push(routeSegment);
   const docsDir = path.join(projectRoot, ...segments);
-  const componentDir = path.join(docsDir, '[component]');
+  const tokensDir = path.join(docsDir, 'tokens', '[domain]');
+  const componentsDir = path.join(docsDir, 'components', '[component]');
 
   // The runtime route URL (route groups like `(design-system)` are invisible in URLs,
   // so the URL is just `/<routeSegment>`). Templates use `__ROUTE_PATH__` as a
-  // placeholder for this — relative hrefs like `./<slug>` would resolve incorrectly
-  // when the current path is `/<segment>` without a trailing slash.
+  // placeholder so absolute hrefs in the sidebar/landing resolve correctly.
   const routeUrl = '/' + routeSegment;
-  const indexBody = INDEX_PAGE_TSX.replace(/__ROUTE_PATH__/g, routeUrl);
 
-  mkdirpSync(docsDir);
-  mkdirpSync(componentDir);
+  // Files we're about to write. Anything else with our marker comment under
+  // `docsDir` is leftover from a previous installer version and gets removed
+  // below — that's how re-installs pick up structural changes (e.g. moving
+  // `[component]/` to `components/[component]/`).
+  const targets = [
+    { abs: path.join(docsDir, `layout${pageExt}`), body: LAYOUT_TSX },
+    { abs: path.join(docsDir, `page${pageExt}`), body: INDEX_PAGE_TSX },
+    { abs: path.join(tokensDir, `page${pageExt}`), body: TOKENS_PAGE_TSX },
+    { abs: path.join(componentsDir, `page${pageExt}`), body: COMPONENT_PAGE_TSX },
+    { abs: path.join(docsDir, `PropToggle${moduleExt}`), body: PROP_TOGGLE_TSX },
+  ];
+
+  // Substitute the `__ROUTE_PATH__` placeholder in every body that needs it
+  // (the layout sidebar links and the landing-page references). It's a no-op
+  // for bodies that don't contain the placeholder.
+  for (const t of targets) {
+    t.body = t.body.replace(/__ROUTE_PATH__/g, routeUrl);
+  }
+
+  // Remove old marker-bearing files that aren't in the new target set. This
+  // lets users re-run the installer after structural changes (e.g. older
+  // versions put the component page at `[component]/page.*` directly under
+  // docsDir; new versions put it under `components/[component]/page.*`).
+  const targetSet = new Set(targets.map(t => t.abs));
+  const removed = removeStaleMarkerFiles(docsDir, targetSet);
+
+  // Now write the new files. Directories are created on demand.
+  for (const t of targets) {
+    mkdirpSync(path.dirname(t.abs));
+    fs.writeFileSync(t.abs, t.body);
+  }
 
-  fs.writeFileSync(path.join(docsDir, `layout${pageExt}`), LAYOUT_TSX);
-  fs.writeFileSync(path.join(docsDir, `page${pageExt}`), indexBody);
-  fs.writeFileSync(path.join(componentDir, `page${pageExt}`), COMPONENT_PAGE_TSX);
-  fs.writeFileSync(path.join(docsDir, `PropToggle${moduleExt}`), PROP_TOGGLE_TSX);
+  // Best-effort cleanup of now-empty directories left behind by removed files
+  // (e.g. the old `app/.../-docs/[component]/` directory).
+  pruneEmptyDirs(docsDir);
 
   return {
-    files: [
-      path.join(docsDir, `layout${pageExt}`),
-      path.join(docsDir, `page${pageExt}`),
-      path.join(componentDir, `page${pageExt}`),
-      path.join(docsDir, `PropToggle${moduleExt}`),
-    ],
+    files: targets.map(t => t.abs),
+    removed,
   };
 }
 
+// Walk `docsDir`, find every `.tsx` file containing the marker comment, and
+// delete the ones that aren't in `keep`. Returns the list of removed paths.
+function removeStaleMarkerFiles(docsDir, keep) {
+  const removed = [];
+  function walk(dir) {
+    let entries;
+    try { entries = fs.readdirSync(dir, { withFileTypes: true }); }
+    catch { return; }
+    for (const ent of entries) {
+      const full = path.join(dir, ent.name);
+      if (ent.isDirectory()) { walk(full); continue; }
+      if (!/\.tsx?$/.test(ent.name)) continue;
+      if (keep.has(full)) continue;
+      try {
+        const content = fs.readFileSync(full, 'utf8');
+        if (content.includes(MARKER_STR)) {
+          fs.unlinkSync(full);
+          removed.push(full);
+        }
+      } catch {}
+    }
+  }
+  walk(docsDir);
+  return removed;
+}
+
+// Recursively delete empty directories under (and including) `dir`. Skips `dir`
+// itself if it's non-empty after the recursion.
+function pruneEmptyDirs(dir) {
+  let entries;
+  try { entries = fs.readdirSync(dir, { withFileTypes: true }); }
+  catch { return; }
+  for (const ent of entries) {
+    if (ent.isDirectory()) pruneEmptyDirs(path.join(dir, ent.name));
+  }
+  try {
+    if (fs.readdirSync(dir).length === 0) fs.rmdirSync(dir);
+  } catch {}
+}
+
 function detectExistingInstall(projectRoot) {
   const found = [];
   function walk(dir) {
@@ -64,7 +135,7 @@ function detectExistingInstall(projectRoot) {
       else if (/\.tsx?$/.test(ent.name)) {
         try {
           const content = fs.readFileSync(full, 'utf8');
-          if (content.includes('design-system-docs-route')) {
+          if (content.includes(MARKER_STR)) {
             found.push(full);
           }
         } catch {}
diff --git a/plugins/adhd/lib/install-design-system-docs-route/templates.js b/plugins/adhd/lib/install-design-system-docs-route/templates.js
index 6bde9b5..850dd9d 100644
--- a/plugins/adhd/lib/install-design-system-docs-route/templates.js
+++ b/plugins/adhd/lib/install-design-system-docs-route/templates.js
@@ -4,211 +4,444 @@ const MARKER_COMMENT = `// design-system-docs-route — auto-generated installer
 // Remove this comment to disable future overwrites from re-running the installer.
 `;
 
-const LAYOUT_TSX = `${MARKER_COMMENT}import type { Metadata } from "next";
-
-export const metadata: Metadata = {
-  title: "Design System Docs",
-  robots: { index: false, follow: false },
-};
-
-export default function DesignSystemDocsLayout({ children }: { children: React.ReactNode }) {
-  return (
-    <div className="min-h-screen bg-zinc-50 dark:bg-zinc-950">
-      <header className="border-b border-zinc-200 dark:border-zinc-800 p-4">
-        <div className="mx-auto max-w-5xl flex items-baseline gap-3">
-          <h1 className="text-sm font-medium">Design System Docs</h1>
-          <span className="text-xs text-zinc-500">Internal — not indexed</span>
-        </div>
-      </header>
-      <main className="mx-auto max-w-5xl p-8">{children}</main>
-    </div>
-  );
+// The list of token domains is shared verbatim between the sidebar (layout) and
+// the token page (so the page can look up the right renderer by slug). Both
+// copies use the same source string here, embedded into the templates below.
+// The `tailwindDocs` field is the URL to Tailwind v4's relevant theme section,
+// used in empty-state messaging.
+const TOKEN_DOMAINS_SRC = `const TOKEN_DOMAINS = [
+  { slug: "colors", label: "Colors", varPrefix: "--color-", tailwindDocs: "https://tailwindcss.com/docs/colors" },
+  { slug: "spacing", label: "Spacing", varPrefix: "--spacing", tailwindDocs: "https://tailwindcss.com/docs/theme#spacing" },
+  { slug: "typography", label: "Typography", varPrefix: "--text-", tailwindDocs: "https://tailwindcss.com/docs/font-size" },
+  { slug: "font", label: "Font Families", varPrefix: "--font-", tailwindDocs: "https://tailwindcss.com/docs/font-family" },
+  { slug: "font-weight", label: "Font Weights", varPrefix: "--font-weight-", tailwindDocs: "https://tailwindcss.com/docs/font-weight" },
+  { slug: "tracking", label: "Tracking", varPrefix: "--tracking-", tailwindDocs: "https://tailwindcss.com/docs/letter-spacing" },
+  { slug: "leading", label: "Leading", varPrefix: "--leading-", tailwindDocs: "https://tailwindcss.com/docs/line-height" },
+  { slug: "radius", label: "Radius", varPrefix: "--radius-", tailwindDocs: "https://tailwindcss.com/docs/border-radius" },
+  { slug: "shadows", label: "Shadows", varPrefix: "--shadow-", tailwindDocs: "https://tailwindcss.com/docs/box-shadow" },
+  { slug: "breakpoint", label: "Breakpoints", varPrefix: "--breakpoint-", tailwindDocs: "https://tailwindcss.com/docs/responsive-design" },
+  { slug: "ease", label: "Easing", varPrefix: "--ease-", tailwindDocs: "https://tailwindcss.com/docs/transition-timing-function" },
+  { slug: "animate", label: "Animation", varPrefix: "--animate-", tailwindDocs: "https://tailwindcss.com/docs/animation" },
+];`;
+
+// The CSS @theme parser shared between landing/tokens pages. Kept inline (not
+// imported from the lib) because these are runtime server components in the
+// consumer's app, with no access to ADHD's node_modules. Mirrors token-parser.js
+// but flattened for inline use.
+//   - Brace-counted scan supports `@theme { ... }` AND `@theme inline { ... }`
+//   - Prefix order matters: longer prefixes (`font-weight-`) before shorter (`font-`).
+const PARSE_TOKENS_SRC = `function extractThemeBodies(css: string): string[] {
+  const bodies: string[] = [];
+  let i = 0;
+  while (i < css.length) {
+    const idx = css.indexOf("@theme", i);
+    if (idx === -1) break;
+    let j = idx + "@theme".length;
+    while (j < css.length && css[j] !== "{" && css[j] !== ";") j++;
+    if (css[j] !== "{") { i = j + 1; continue; }
+    let depth = 1;
+    let k = j + 1;
+    while (k < css.length && depth > 0) {
+      if (css[k] === "{") depth++;
+      else if (css[k] === "}") depth--;
+      if (depth > 0) k++;
+    }
+    bodies.push(css.slice(j + 1, k));
+    i = k + 1;
+  }
+  return bodies;
 }
-`;
 
-const INDEX_PAGE_TSX = `${MARKER_COMMENT}import fs from "node:fs/promises";
-import path from "node:path";
-import Link from "next/link";
+type Row = { name: string; value: string };
+type TypoRow = { name: string; size: string | null; lineHeight: string | null };
+
+function parseTokens(css: string | null) {
+  const out = {
+    colors: [] as Row[],
+    spacing: { multiplier: null as string | null },
+    typography: [] as TypoRow[],
+    fonts: [] as Row[],
+    fontWeights: [] as Row[],
+    radius: [] as Row[],
+    shadows: [] as Row[],
+    tracking: [] as Row[],
+    leading: [] as Row[],
+    breakpoints: [] as Row[],
+    easings: [] as Row[],
+    animations: [] as Row[],
+  };
+  if (!css) return out;
+  const typoByName = new Map<string, TypoRow>();
+  const LINE_HEIGHT_SUFFIX = "--line-height";
+  // Order matters: longer prefixes first.
+  const PREFIX_MAP: Array<[string, keyof typeof out]> = [
+    ["color-", "colors"],
+    ["font-weight-", "fontWeights"],
+    ["font-", "fonts"],
+    ["inset-shadow-", "shadows"],
+    ["drop-shadow-", "shadows"],
+    ["shadow-", "shadows"],
+    ["radius-", "radius"],
+    ["tracking-", "tracking"],
+    ["leading-", "leading"],
+    ["breakpoint-", "breakpoints"],
+    ["ease-", "easings"],
+    ["animate-", "animations"],
+  ];
+  for (const body of extractThemeBodies(css)) {
+    const declRe = /--([a-zA-Z0-9_-]+)\\s*:\\s*([^;]+);/g;
+    let d;
+    while ((d = declRe.exec(body)) !== null) {
+      const name = d[1];
+      const value = d[2].trim();
+      if (name === "spacing") { out.spacing.multiplier = value; continue; }
+      if (name.startsWith("text-")) {
+        const rest = name.slice("text-".length);
+        const isLh = rest.endsWith(LINE_HEIGHT_SUFFIX);
+        const leaf = isLh ? rest.slice(0, -LINE_HEIGHT_SUFFIX.length) : rest;
+        let row = typoByName.get(leaf);
+        if (!row) { row = { name: leaf, size: null, lineHeight: null }; typoByName.set(leaf, row); out.typography.push(row); }
+        if (isLh) row.lineHeight = value; else row.size = value;
+        continue;
+      }
+      for (const [prefix, domain] of PREFIX_MAP) {
+        if (name.startsWith(prefix)) {
+          (out[domain] as Row[]).push({ name: name.slice(prefix.length), value });
+          break;
+        }
+      }
+    }
+  }
+  return out;
+}`;
 
-async function readConfig() {
+const READ_CONFIG_SRC = `async function readConfig() {
   try {
     const src = await fs.readFile(path.resolve(process.cwd(), "adhd.config.ts"), "utf8");
-    const components: Record<string, unknown> = {};
+    const components: string[] = [];
     const compMatch = /components:\\s*\\{([\\s\\S]*?)\\}\\s*[,;]?/.exec(src);
     if (compMatch) {
       const inner = compMatch[1];
       const re = /"([^"]+)"\\s*:\\s*\\{/g;
       let m;
-      while ((m = re.exec(inner)) !== null) {
-        components[m[1]] = true;
-      }
+      while ((m = re.exec(inner)) !== null) components.push(m[1]);
     }
     const cssEntryMatch = /cssEntry\\s*:\\s*"([^"]+)"/.exec(src);
     const cssEntry = cssEntryMatch ? cssEntryMatch[1] : "app/globals.css";
-    return { components: Object.keys(components), cssEntry };
+    return { components, cssEntry };
   } catch {
-    return { components: [], cssEntry: "app/globals.css" };
+    return { components: [] as string[], cssEntry: "app/globals.css" };
   }
 }
 
+function slugFor(p: string) {
+  return p.replace(/\\.tsx?$/, "").replace(/\\/index$/, "").split("/").pop()?.toLowerCase() ?? p;
+}`;
+
+// Layout: sidebar lists token domains + components; main area renders children.
+// The layout is async so it can read adhd.config.ts to populate the components list.
+const LAYOUT_TSX = `${MARKER_COMMENT}import type { Metadata } from "next";
+import fs from "node:fs/promises";
+import path from "node:path";
+import Link from "next/link";
+
+export const metadata: Metadata = {
+  title: "Design System Docs",
+  robots: { index: false, follow: false },
+};
+
+${TOKEN_DOMAINS_SRC}
+
+${READ_CONFIG_SRC}
+
+export default async function DesignSystemDocsLayout({ children }: { children: React.ReactNode }) {
+  const cfg = await readConfig();
+  const components = cfg.components.map(p => ({ raw: p, slug: slugFor(p) }));
+
+  return (
+    <div className="flex min-h-screen bg-zinc-50 dark:bg-zinc-950 text-zinc-900 dark:text-zinc-100">
+      <aside className="w-56 shrink-0 border-r border-zinc-200 dark:border-zinc-800 p-4 sticky top-0 h-screen overflow-y-auto">
+        <Link href={\`__ROUTE_PATH__\`} className="block mb-6">
+          <h1 className="text-sm font-medium">Design System</h1>
+          <p className="text-[10px] text-zinc-500">Internal — not indexed</p>
+        </Link>
+
+        <nav className="flex flex-col gap-4 text-sm">
+          <section>
+            <h2 className="mb-2 text-[10px] font-medium uppercase tracking-wide text-zinc-500">Tokens</h2>
+            <ul className="flex flex-col gap-1">
+              {TOKEN_DOMAINS.map(d => (
+                <li key={d.slug}>
+                  <Link href={\`__ROUTE_PATH__/tokens/\${d.slug}\`} className="block rounded px-2 py-1 hover:bg-zinc-200 dark:hover:bg-zinc-800">
+                    {d.label}
+                  </Link>
+                </li>
+              ))}
+            </ul>
+          </section>
+
+          <section>
+            <h2 className="mb-2 text-[10px] font-medium uppercase tracking-wide text-zinc-500">Components</h2>
+            {components.length === 0 ? (
+              <p className="text-xs text-zinc-500 px-2">None tracked yet.</p>
+            ) : (
+              <ul className="flex flex-col gap-1">
+                {components.map(c => (
+                  <li key={c.raw}>
+                    <Link href={\`__ROUTE_PATH__/components/\${c.slug}\`} className="block rounded px-2 py-1 hover:bg-zinc-200 dark:hover:bg-zinc-800">
+                      {c.slug}
+                    </Link>
+                  </li>
+                ))}
+              </ul>
+            )}
+          </section>
+        </nav>
+      </aside>
+
+      <main className="flex-1 p-8 overflow-x-auto">
+        <div className="max-w-5xl">{children}</div>
+      </main>
+    </div>
+  );
+}
+`;
+
+// Landing page — minimal welcome message; the sidebar already shows everything.
+const INDEX_PAGE_TSX = `${MARKER_COMMENT}export default function DesignSystemIndex() {
+  return (
+    <div className="flex flex-col gap-4">
+      <h2 className="text-2xl font-medium">Design System</h2>
+      <p className="text-sm text-zinc-600 dark:text-zinc-400 max-w-prose">
+        Pick a token domain or a component from the sidebar. Tokens are read from your
+        <code className="mx-1 rounded bg-zinc-100 dark:bg-zinc-900 px-1 py-0.5 text-xs">globals.css</code>
+        <code className="rounded bg-zinc-100 dark:bg-zinc-900 px-1 py-0.5 text-xs">@theme</code> blocks.
+        Components are loaded from
+        <code className="ml-1 rounded bg-zinc-100 dark:bg-zinc-900 px-1 py-0.5 text-xs">adhd.config.ts</code>.
+      </p>
+    </div>
+  );
+}
+`;
+
+// Tokens domain page — one route, one renderer per domain. Reads the consumer's
+// globals.css at request time and renders whatever's declared. Empty states
+// reference Tailwind v4's defaults rather than implying the system is broken.
+const TOKENS_PAGE_TSX = `${MARKER_COMMENT}import fs from "node:fs/promises";
+import path from "node:path";
+import { notFound } from "next/navigation";
+
+${TOKEN_DOMAINS_SRC}
+
+${READ_CONFIG_SRC}
+
 async function readCss(cssEntry: string) {
-  try {
-    return await fs.readFile(path.resolve(process.cwd(), cssEntry), "utf8");
-  } catch {
-    return null;
-  }
+  try { return await fs.readFile(path.resolve(process.cwd(), cssEntry), "utf8"); }
+  catch { return null; }
 }
 
-function extractTokens(css: string | null) {
-  const empty = { colors: [], spacing: { multiplier: null }, typography: [], radius: [], shadows: [] };
-  if (!css) return empty;
-  const out = { colors: [] as Array<{ name: string; value: string }>,
-                spacing: { multiplier: null as string | null },
-                typography: [] as Array<{ name: string; size: string | null; lineHeight: string | null }>,
-                radius: [] as Array<{ name: string; value: string }>,
-                shadows: [] as Array<{ name: string; value: string }> };
-  const themeRe = /@theme\\s*\\{([\\s\\S]*?)\\}/g;
-  let body;
-  while ((body = themeRe.exec(css)) !== null) {
-    const declRe = /--([a-zA-Z0-9_-]+)\\s*:\\s*([^;]+);/g;
-    let d;
-    while ((d = declRe.exec(body[1])) !== null) {
-      const name = d[1];
-      const value = d[2].trim();
-      if (name.startsWith("color-")) out.colors.push({ name: name.slice(6), value });
-      else if (name === "spacing") out.spacing.multiplier = value;
-      else if (name.startsWith("text-")) {
-        const rest = name.slice(5);
-        const lhIdx = rest.indexOf("--line-height");
-        const leaf = lhIdx >= 0 ? rest.slice(0, lhIdx) : rest;
-        let row = out.typography.find(t => t.name === leaf);
-        if (!row) { row = { name: leaf, size: null, lineHeight: null }; out.typography.push(row); }
-        if (lhIdx >= 0) row.lineHeight = value; else row.size = value;
-      } else if (name.startsWith("radius-")) out.radius.push({ name: name.slice(7), value });
-      else if (name.startsWith("shadow-")) out.shadows.push({ name: name.slice(7), value });
-    }
-  }
-  return out;
+${PARSE_TOKENS_SRC}
+
+function EmptyState({ domain }: { domain: typeof TOKEN_DOMAINS[number] }) {
+  return (
+    <div className="rounded border border-dashed border-zinc-300 dark:border-zinc-700 p-6 text-sm text-zinc-600 dark:text-zinc-400">
+      No custom <code className="rounded bg-zinc-100 dark:bg-zinc-900 px-1 py-0.5 text-xs">{domain.varPrefix}*</code> tokens declared in your <code>@theme</code>.
+      Tailwind v4 ships sensible defaults — see the <a className="underline" href={domain.tailwindDocs} target="_blank" rel="noopener noreferrer">{domain.label} docs</a>.
+    </div>
+  );
 }
 
-export default async function DesignSystemIndex() {
+export default async function TokensDomainPage({ params }: { params: Promise<{ domain: string }> }) {
+  const { domain: slug } = await params;
+  const domain = TOKEN_DOMAINS.find(d => d.slug === slug);
+  if (!domain) notFound();
+
   const cfg = await readConfig();
   const css = await readCss(cfg.cssEntry);
-  const tokens = extractTokens(css);
+  const tokens = parseTokens(css);
 
   return (
-    <div className="flex flex-col gap-12">
-      <section>
-        <h2 className="mb-4 text-xs font-medium uppercase text-zinc-500">Colors</h2>
-        {tokens.colors.length === 0 ? <p className="text-sm text-zinc-500">No colors detected.</p> : (
-          <div className="grid grid-cols-6 gap-3">
+    <div className="flex flex-col gap-6">
+      <header>
+        <h2 className="text-2xl font-medium">{domain.label}</h2>
+        <p className="text-xs text-zinc-500 mt-1">Variables prefixed with <code>{domain.varPrefix}</code></p>
+      </header>
+
+      {slug === "colors" && (
+        tokens.colors.length === 0 ? <EmptyState domain={domain} /> : (
+          <div className="grid grid-cols-4 md:grid-cols-6 gap-3">
             {tokens.colors.map(c => (
               <div key={c.name} className="flex flex-col gap-1">
-                <div className="h-12 w-full rounded border border-zinc-200 dark:border-zinc-800" style={{ backgroundColor: c.value }} />
+                <div className="h-16 w-full rounded border border-zinc-200 dark:border-zinc-800" style={{ backgroundColor: c.value }} />
                 <span className="text-xs">{c.name}</span>
-                <span className="text-[10px] text-zinc-500">{c.value}</span>
+                <span className="text-[10px] text-zinc-500 truncate" title={c.value}>{c.value}</span>
               </div>
             ))}
           </div>
-        )}
-      </section>
+        )
+      )}
 
-      <section>
-        <h2 className="mb-4 text-xs font-medium uppercase text-zinc-500">Spacing</h2>
-        {tokens.spacing.multiplier ? <p className="text-sm">Multiplier: <code>{tokens.spacing.multiplier}</code></p> : <p className="text-sm text-zinc-500">No spacing variable detected.</p>}
-      </section>
+      {slug === "spacing" && (
+        tokens.spacing.multiplier == null ? <EmptyState domain={domain} /> : (
+          <div className="flex flex-col gap-2">
+            <p className="text-sm">Multiplier: <code>{tokens.spacing.multiplier}</code></p>
+            <p className="text-xs text-zinc-500">Tailwind v4 derives all spacing utilities from this single variable.</p>
+          </div>
+        )
+      )}
 
-      <section>
-        <h2 className="mb-4 text-xs font-medium uppercase text-zinc-500">Typography</h2>
-        {tokens.typography.length === 0 ? <p className="text-sm text-zinc-500">No typography tokens detected.</p> : (
+      {slug === "typography" && (
+        tokens.typography.length === 0 ? <EmptyState domain={domain} /> : (
           <div className="flex flex-col gap-4">
             {tokens.typography.map(t => (
-              <div key={t.name} className="flex items-baseline gap-4">
-                <span className="text-xs text-zinc-500 w-20">text-{t.name}</span>
+              <div key={t.name} className="flex items-baseline gap-4 border-b border-zinc-100 dark:border-zinc-900 pb-2">
+                <span className="text-xs text-zinc-500 w-20 shrink-0">text-{t.name}</span>
                 <span style={{ fontSize: t.size ?? undefined, lineHeight: t.lineHeight ?? undefined }}>
                   The quick brown fox jumps over the lazy dog
                 </span>
-                <span className="text-[10px] text-zinc-500">{t.size}{t.lineHeight ? \` / \${t.lineHeight}\` : ""}</span>
+                <span className="ml-auto text-[10px] text-zinc-500">{t.size}{t.lineHeight ? \` / \${t.lineHeight}\` : ""}</span>
               </div>
             ))}
           </div>
-        )}
-      </section>
+        )
+      )}
+
+      {slug === "font" && (
+        tokens.fonts.length === 0 ? <EmptyState domain={domain} /> : (
+          <div className="flex flex-col gap-3">
+            {tokens.fonts.map(f => (
+              <div key={f.name} className="flex flex-col gap-1 border-b border-zinc-100 dark:border-zinc-900 pb-3">
+                <span className="text-xs text-zinc-500">font-{f.name}</span>
+                <span style={{ fontFamily: f.value }} className="text-xl">The quick brown fox</span>
+                <span className="text-[10px] text-zinc-500 truncate" title={f.value}>{f.value}</span>
+              </div>
+            ))}
+          </div>
+        )
+      )}
 
-      <section>
-        <h2 className="mb-4 text-xs font-medium uppercase text-zinc-500">Radius</h2>
-        {tokens.radius.length === 0 ? <p className="text-sm text-zinc-500">No radius tokens detected.</p> : (
-          <div className="flex gap-4">
+      {slug === "font-weight" && (
+        tokens.fontWeights.length === 0 ? <EmptyState domain={domain} /> : (
+          <div className="flex flex-col gap-2">
+            {tokens.fontWeights.map(w => (
+              <div key={w.name} className="flex items-baseline gap-4">
+                <span className="text-xs text-zinc-500 w-32 shrink-0">font-{w.name}</span>
+                <span style={{ fontWeight: w.value }} className="text-lg">The quick brown fox</span>
+                <span className="ml-auto text-[10px] text-zinc-500">{w.value}</span>
+              </div>
+            ))}
+          </div>
+        )
+      )}
+
+      {slug === "tracking" && (
+        tokens.tracking.length === 0 ? <EmptyState domain={domain} /> : (
+          <div className="flex flex-col gap-2">
+            {tokens.tracking.map(t => (
+              <div key={t.name} className="flex items-baseline gap-4">
+                <span className="text-xs text-zinc-500 w-32 shrink-0">tracking-{t.name}</span>
+                <span style={{ letterSpacing: t.value }} className="text-lg">The quick brown fox</span>
+                <span className="ml-auto text-[10px] text-zinc-500">{t.value}</span>
+              </div>
+            ))}
+          </div>
+        )
+      )}
+
+      {slug === "leading" && (
+        tokens.leading.length === 0 ? <EmptyState domain={domain} /> : (
+          <div className="flex flex-col gap-3">
+            {tokens.leading.map(l => (
+              <div key={l.name} className="flex flex-col gap-1 border-b border-zinc-100 dark:border-zinc-900 pb-3">
+                <span className="text-xs text-zinc-500">leading-{l.name} <span className="text-zinc-400">— {l.value}</span></span>
+                <p style={{ lineHeight: l.value }} className="text-sm max-w-md">
+                  The quick brown fox jumps over the lazy dog. The five boxing wizards jump quickly. Pack my box with five dozen liquor jugs.
+                </p>
+              </div>
+            ))}
+          </div>
+        )
+      )}
+
+      {slug === "radius" && (
+        tokens.radius.length === 0 ? <EmptyState domain={domain} /> : (
+          <div className="flex flex-wrap gap-4">
             {tokens.radius.map(r => (
               <div key={r.name} className="flex flex-col gap-1">
                 <div className="h-16 w-16 bg-zinc-200 dark:bg-zinc-800" style={{ borderRadius: r.value }} />
                 <span className="text-xs">rounded-{r.name}</span>
+                <span className="text-[10px] text-zinc-500">{r.value}</span>
               </div>
             ))}
           </div>
-        )}
-      </section>
+        )
+      )}
 
-      <section>
-        <h2 className="mb-4 text-xs font-medium uppercase text-zinc-500">Shadows</h2>
-        {tokens.shadows.length === 0 ? <p className="text-sm text-zinc-500">No shadow tokens detected.</p> : (
-          <div className="flex gap-6">
-            {tokens.shadows.map(s => (
-              <div key={s.name} className="flex flex-col gap-1">
-                <div className="h-16 w-16 bg-white" style={{ boxShadow: s.value }} />
+      {slug === "shadows" && (
+        tokens.shadows.length === 0 ? <EmptyState domain={domain} /> : (
+          <div className="flex flex-wrap gap-8">
+            {tokens.shadows.map((s, i) => (
+              <div key={\`\${s.name}-\${i}\`} className="flex flex-col gap-1">
+                <div className="h-20 w-20 bg-white" style={{ boxShadow: s.value }} />
                 <span className="text-xs">shadow-{s.name}</span>
+                <span className="text-[10px] text-zinc-500 truncate w-20" title={s.value}>{s.value}</span>
               </div>
             ))}
           </div>
-        )}
-      </section>
+        )
+      )}
 
-      <section>
-        <h2 className="mb-4 text-xs font-medium uppercase text-zinc-500">Components</h2>
-        {cfg.components.length === 0 ? <p className="text-sm text-zinc-500">No components tracked yet.</p> : (
-          <div className="grid grid-cols-3 gap-4">
-            {cfg.components.map(p => {
-              const slug = p.replace(/\\.tsx?$/, "").replace(/\\/index$/, "").split("/").pop()?.toLowerCase() ?? p;
-              return (
-                <Link key={p} href={\`__ROUTE_PATH__/\${slug}\`} className="rounded border border-zinc-200 dark:border-zinc-800 p-4 hover:bg-zinc-100 dark:hover:bg-zinc-900">
-                  <div className="text-sm font-medium">{slug}</div>
-                  <div className="text-xs text-zinc-500 truncate">{p}</div>
-                </Link>
-              );
-            })}
+      {slug === "breakpoint" && (
+        tokens.breakpoints.length === 0 ? <EmptyState domain={domain} /> : (
+          <div className="flex flex-col gap-1">
+            {tokens.breakpoints.map(b => (
+              <div key={b.name} className="flex items-baseline gap-4 text-sm">
+                <span className="text-xs text-zinc-500 w-32 shrink-0">{b.name}</span>
+                <code>{b.value}</code>
+              </div>
+            ))}
           </div>
-        )}
-      </section>
+        )
+      )}
+
+      {slug === "ease" && (
+        tokens.easings.length === 0 ? <EmptyState domain={domain} /> : (
+          <div className="flex flex-col gap-1">
+            {tokens.easings.map(e => (
+              <div key={e.name} className="flex items-baseline gap-4 text-sm">
+                <span className="text-xs text-zinc-500 w-32 shrink-0">ease-{e.name}</span>
+                <code className="text-xs">{e.value}</code>
+              </div>
+            ))}
+          </div>
+        )
+      )}
+
+      {slug === "animate" && (
+        tokens.animations.length === 0 ? <EmptyState domain={domain} /> : (
+          <div className="flex flex-col gap-1">
+            {tokens.animations.map(a => (
+              <div key={a.name} className="flex items-baseline gap-4 text-sm">
+                <span className="text-xs text-zinc-500 w-32 shrink-0">animate-{a.name}</span>
+                <code className="text-xs">{a.value}</code>
+              </div>
+            ))}
+          </div>
+        )
+      )}
     </div>
   );
 }
 `;
 
+// Component page — moved to /components/[component]. Two levels deep, so the
+// PropToggle import is now `../../PropToggle`.
 const COMPONENT_PAGE_TSX = `${MARKER_COMMENT}import fs from "node:fs/promises";
 import path from "node:path";
 import { notFound } from "next/navigation";
-import { PropToggle } from "../PropToggle";
+import { PropToggle } from "../../PropToggle";
 
-async function readConfig() {
-  try {
-    const src = await fs.readFile(path.resolve(process.cwd(), "adhd.config.ts"), "utf8");
-    const components: string[] = [];
-    const compMatch = /components:\\s*\\{([\\s\\S]*?)\\}\\s*[,;]?/.exec(src);
-    if (compMatch) {
-      const inner = compMatch[1];
-      const re = /"([^"]+)"\\s*:\\s*\\{/g;
-      let m;
-      while ((m = re.exec(inner)) !== null) components.push(m[1]);
-    }
-    return components;
-  } catch {
-    return [];
-  }
-}
-
-function slugFor(p: string) {
-  return p.replace(/\\.tsx?$/, "").replace(/\\/index$/, "").split("/").pop()?.toLowerCase() ?? p;
-}
+${READ_CONFIG_SRC}
 
 async function parseProps(componentPath: string) {
   try {
@@ -258,8 +491,8 @@ export default async function ComponentPage({
 }) {
   const { component: slug } = await params;
   const sp = await searchParams;
-  const paths = await readConfig();
-  const componentPath = paths.find(p => slugFor(p) === slug);
+  const cfg = await readConfig();
+  const componentPath = cfg.components.find(p => slugFor(p) === slug);
   if (!componentPath) notFound();
 
   const { props } = await parseProps(componentPath);
@@ -294,7 +527,7 @@ export default async function ComponentPage({
 
   return (
     <div className="flex flex-col gap-6">
-      <h2 className="text-lg font-medium">{slug}</h2>
+      <h2 className="text-2xl font-medium">{slug}</h2>
 
       <section className="rounded border border-zinc-200 dark:border-zinc-800 p-4">
         <h3 className="mb-3 text-xs font-medium uppercase text-zinc-500">Props</h3>
@@ -383,4 +616,11 @@ export function PropToggle(p: Props) {
 }
 `;
 
-module.exports = { MARKER_COMMENT, LAYOUT_TSX, INDEX_PAGE_TSX, COMPONENT_PAGE_TSX, PROP_TOGGLE_TSX };
+module.exports = {
+  MARKER_COMMENT,
+  LAYOUT_TSX,
+  INDEX_PAGE_TSX,
+  TOKENS_PAGE_TSX,
+  COMPONENT_PAGE_TSX,
+  PROP_TOGGLE_TSX,
+};
diff --git a/plugins/adhd/lib/install-design-system-docs-route/token-parser.js b/plugins/adhd/lib/install-design-system-docs-route/token-parser.js
index 358e59b..6ec4851 100644
--- a/plugins/adhd/lib/install-design-system-docs-route/token-parser.js
+++ b/plugins/adhd/lib/install-design-system-docs-route/token-parser.js
@@ -43,13 +43,29 @@ const DECL_RE = /--([a-zA-Z0-9_-]+)\s*:\s*([^;]+);/g;
 // We split on the suffix so callers see one row per family name.
 const LINE_HEIGHT_SUFFIX = '--line-height';
 
+// Prefix-to-domain mapping. Order is significant: longer/more-specific prefixes
+// must precede shorter ones (e.g. `font-weight-` before `font-`, `inset-shadow-`
+// before `shadow-`). Each entry maps to a flat array of `{ name, value }` rows.
+const PREFIX_MAP = [
+  ['color-', 'colors'],
+  ['font-weight-', 'fontWeights'],
+  ['font-', 'fonts'],
+  ['inset-shadow-', 'shadows'],
+  ['drop-shadow-', 'shadows'],
+  ['shadow-', 'shadows'],
+  ['radius-', 'radius'],
+  ['tracking-', 'tracking'],
+  ['leading-', 'leading'],
+  ['breakpoint-', 'breakpoints'],
+  ['ease-', 'easings'],
+  ['animate-', 'animations'],
+];
+
 function classify(name) {
-  if (name.startsWith('color-')) {
-    return { domain: 'colors', leaf: name.slice('color-'.length) };
-  }
   if (name === 'spacing') {
     return { domain: 'spacing', leaf: null };
   }
+  // Typography (`text-*`) is special because of the `--line-height` suffix pairing.
   if (name.startsWith('text-')) {
     const rest = name.slice('text-'.length);
     if (rest.endsWith(LINE_HEIGHT_SUFFIX)) {
@@ -61,11 +77,10 @@ function classify(name) {
     }
     return { domain: 'typography', leaf: rest, kind: 'size' };
   }
-  if (name.startsWith('radius-')) {
-    return { domain: 'radius', leaf: name.slice('radius-'.length) };
-  }
-  if (name.startsWith('shadow-')) {
-    return { domain: 'shadows', leaf: name.slice('shadow-'.length) };
+  for (const [prefix, domain] of PREFIX_MAP) {
+    if (name.startsWith(prefix)) {
+      return { domain, leaf: name.slice(prefix.length) };
+    }
   }
   return { domain: 'unknown' };
 }
@@ -75,8 +90,15 @@ function parseTokens(globalsCss) {
     colors: [],
     spacing: { multiplier: null },
     typography: [], // [{ name, size, lineHeight }]
+    fonts: [],
+    fontWeights: [],
     radius: [],
     shadows: [],
+    tracking: [],
+    leading: [],
+    breakpoints: [],
+    easings: [],
+    animations: [],
     unknown: [],
   };
   // Tracks typography rows by family name so size + line-height (which arrive
@@ -103,23 +125,23 @@ function parseTokens(globalsCss) {
       const value = m[2].trim();
       const cls = classify(name);
       switch (cls.domain) {
-        case 'colors':
-          out.colors.push({ name: cls.leaf, value });
-          break;
         case 'spacing':
           out.spacing.multiplier = value;
           break;
         case 'typography':
           upsertTypography(cls.leaf, cls.kind, value);
           break;
-        case 'radius':
-          out.radius.push({ name: cls.leaf, value });
-          break;
-        case 'shadows':
-          out.shadows.push({ name: cls.leaf, value });
+        case 'unknown':
+          out.unknown.push({ name: '--' + name, value });
           break;
         default:
-          out.unknown.push({ name: '--' + name, value });
+          // All other domains share the same flat `{ name, value }` row shape
+          // and a 1:1 mapping from PREFIX_MAP's domain key to an `out` bucket.
+          if (Array.isArray(out[cls.domain])) {
+            out[cls.domain].push({ name: cls.leaf, value });
+          } else {
+            out.unknown.push({ name: '--' + name, value });
+          }
       }
     }
   }
diff --git a/plugins/adhd/skills/install-design-system-docs-route/SKILL.md b/plugins/adhd/skills/install-design-system-docs-route/SKILL.md
index 2774ce3..9add183 100644
--- a/plugins/adhd/skills/install-design-system-docs-route/SKILL.md
+++ b/plugins/adhd/skills/install-design-system-docs-route/SKILL.md
@@ -1,5 +1,5 @@
 ---
-description: "Install a self-generating design-system documentation route into a Next.js consumer app. The route reads adhd.config.ts and globals.css at request time, renders a token catalog (colors / spacing / typography / radius / shadows) plus per-component pages with URL-driven prop toggles. Optionally excluded from production builds via Next.js pageExtensions trick. Re-runnable: marker-comment detection drives updates."
+description: "Install a self-generating design-system documentation route into a Next.js consumer app. Sidebar + viewer layout: the sidebar lists every Tailwind v4 token domain (colors, spacing, typography, font, font-weight, tracking, leading, radius, shadows, breakpoints, easing, animation) plus every component tracked in adhd.config.ts; the main pane renders the selected route. All token domains and components are read from globals.css and adhd.config.ts at request time. Component pages introspect props for URL-driven toggles. Optionally excluded from production builds via Next.js pageExtensions trick. Re-runnable: marker-comment detection drives updates, and stale marker-bearing files from older template layouts are cleaned up."
 disable-model-invocation: true
 argument-hint: ""
 allowed-tools: Read Write Edit Bash AskUserQuestion

From 1d41637d54512a286cee1c6dc2ade775479d93a2 Mon Sep 17 00:00:00 2001
From: Hugh Francis <hughfrancis89@gmail.com>
Date: Mon, 11 May 2026 16:34:29 -0400
Subject: [PATCH 23/79] docs-route: diagnose globals.css gaps + error boundary
 at component route
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Why this matters:

The component page uses a broad dynamic import (`import("@/" + path)`) so
adding to adhd.config.ts is enough to add components. The cost is that
Webpack/Turbopack can't statically resolve the path, so it creates a
context module that pulls every file under `@/` into the route's bundle.
Tailwind v4 then scans all of those files — a much wider surface than the
consumer's normal routes — and surfaces latent v3-to-v4 migration gaps in
their globals.css (e.g. shadcn's `ring-offset-background` not in @theme).
The result is "Cannot apply unknown utility class ..." during CSS compile,
which prevents the build manifest from being written, which surfaces as
an opaque "ENOENT: app-build-manifest.json" in the browser.

We can't catch that error at React level — it happens before render. But
we can make the failure mode self-explanatory:

1. Layout pre-scans globals.css. If the @theme block looks shadcn-shaped
   (defines `--color-foreground`, `--color-background`, plus at least one
   `*-foreground` pair) AND `--color-ring-offset-background` is missing,
   render a diagnostic banner above the main pane with the exact
   @theme/:root lines to add.

2. Add `components/[component]/error.tsx` — a client error boundary that
   catches runtime failures (broken dynamic imports, components that throw
   on mount, etc.). It detects whether the error.message mentions the
   build-manifest path and gives a focused note pointing back at the
   diagnostic banner.

3. Landing page (`/`) now has a Troubleshooting section with three
   expandable items, including a detailed walkthrough of the dynamic
   import / Tailwind interaction and how to debug it from the dev log.

The shared `readCss` helper and the new `DETECT_ISSUES_SRC` /
`READ_CSS_SRC` snippets are factored out of the template literals so the
layout and tokens page both use the same brace-counted @theme scanner
(which correctly handles `@theme inline { ... }`).

Tested detection against the real reactor-webapp globals.css — fires
correctly on missing --color-ring-offset-background.

README updated to document the trade-off.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 README.md                                     |  18 ++
 .../__tests__/route-installer.test.js         |   7 +-
 .../__tests__/templates.test.js               |  47 +++-
 .../route-installer.js                        |   5 +
 .../templates.js                              | 204 ++++++++++++++++--
 5 files changed, 261 insertions(+), 20 deletions(-)

diff --git a/README.md b/README.md
index 36798ca..948e4a8 100644
--- a/README.md
+++ b/README.md
@@ -145,6 +145,24 @@ Re-run the installer over time to pick up improved templates. Files you've
 customized — by removing the `// design-system-docs-route` marker comment —
 are left alone.
 
+#### Caveat: broad dynamic import + Tailwind v4
+
+The component page resolves its target via `import("@/" + componentPath)` so
+adding to `adhd.config.ts` is enough — no re-install per component. The
+trade-off: Webpack/Turbopack can't statically resolve the path, so it
+creates a context module that pulls every `.ts`/`.tsx` under your project
+root into this route's bundle. Tailwind v4 then scans all of them for
+classes — a much wider surface than your other routes touch.
+
+If your codebase has shadcn-v3-era classes that you never migrated (most
+commonly `ring-offset-background`, used by Button/Input focus styles),
+they'll surface as `Cannot apply unknown utility class …` errors during
+route compilation, and the page will 500 with an ENOENT on
+`app-build-manifest.json`. The layout pre-scans your `globals.css` for the
+shadcn shibboleth and shows a diagnostic banner with the exact `@theme`
+addition you need to make. There's also an `error.tsx` at the route boundary
+for any runtime failures, and a Troubleshooting section on the landing page.
+
 You can also trigger the install at the end of `/adhd:config` if you're
 setting up ADHD for the first time.
 
diff --git a/plugins/adhd/lib/install-design-system-docs-route/__tests__/route-installer.test.js b/plugins/adhd/lib/install-design-system-docs-route/__tests__/route-installer.test.js
index ee9807f..7c6ab24 100644
--- a/plugins/adhd/lib/install-design-system-docs-route/__tests__/route-installer.test.js
+++ b/plugins/adhd/lib/install-design-system-docs-route/__tests__/route-installer.test.js
@@ -21,11 +21,12 @@ test('installRoute writes page/layout files with .design-system.tsx suffix when
     prodExcluded: true,
   });
   const docsDir = path.join(root, 'app', '(design-system)', '-docs');
-  // Route files (page/layout) get the suffix so pageExtensions filters them in prod.
+  // Route files (page/layout/error) get the suffix so pageExtensions filters them in prod.
   assert.ok(fs.existsSync(path.join(docsDir, 'layout.design-system.tsx')));
   assert.ok(fs.existsSync(path.join(docsDir, 'page.design-system.tsx')));
   assert.ok(fs.existsSync(path.join(docsDir, 'tokens', '[domain]', 'page.design-system.tsx')));
   assert.ok(fs.existsSync(path.join(docsDir, 'components', '[component]', 'page.design-system.tsx')));
+  assert.ok(fs.existsSync(path.join(docsDir, 'components', '[component]', 'error.design-system.tsx')));
   // PropToggle is a module imported by the component page; it doesn't need the
   // suffix for prod-exclusion (the page that imports it IS suffix-excluded).
   assert.ok(fs.existsSync(path.join(docsDir, 'PropToggle.tsx')));
@@ -44,6 +45,7 @@ test('installRoute writes plain .tsx files when not prodExcluded', () => {
   assert.ok(fs.existsSync(path.join(docsDir, 'page.tsx')));
   assert.ok(fs.existsSync(path.join(docsDir, 'tokens', '[domain]', 'page.tsx')));
   assert.ok(fs.existsSync(path.join(docsDir, 'components', '[component]', 'page.tsx')));
+  assert.ok(fs.existsSync(path.join(docsDir, 'components', '[component]', 'error.tsx')));
   assert.ok(fs.existsSync(path.join(docsDir, 'PropToggle.tsx')));
 });
 
@@ -56,6 +58,7 @@ test('all written files start with the marker comment', () => {
     'page.design-system.tsx',
     'tokens/[domain]/page.design-system.tsx',
     'components/[component]/page.design-system.tsx',
+    'components/[component]/error.design-system.tsx',
     'PropToggle.tsx',
   ]) {
     const content = fs.readFileSync(path.join(docsDir, f), 'utf8');
@@ -143,7 +146,7 @@ test('detectExistingInstall scans for the marker and returns matching files', ()
   const root = makeTempProject();
   installRoute(root, { groupName: '(design-system)', routeSegment: '-docs', prodExcluded: true });
   const found = detectExistingInstall(root);
-  assert.ok(found.length >= 5);
+  assert.ok(found.length >= 6);
   assert.ok(found.every(p => p.includes('-docs')));
 });
 
diff --git a/plugins/adhd/lib/install-design-system-docs-route/__tests__/templates.test.js b/plugins/adhd/lib/install-design-system-docs-route/__tests__/templates.test.js
index d1bf90a..57ddae5 100644
--- a/plugins/adhd/lib/install-design-system-docs-route/__tests__/templates.test.js
+++ b/plugins/adhd/lib/install-design-system-docs-route/__tests__/templates.test.js
@@ -2,7 +2,7 @@
 
 const test = require('node:test');
 const assert = require('node:assert/strict');
-const { MARKER_COMMENT, LAYOUT_TSX, INDEX_PAGE_TSX, TOKENS_PAGE_TSX, COMPONENT_PAGE_TSX, PROP_TOGGLE_TSX } = require('../templates');
+const { MARKER_COMMENT, LAYOUT_TSX, INDEX_PAGE_TSX, TOKENS_PAGE_TSX, COMPONENT_PAGE_TSX, COMPONENT_ERROR_TSX, PROP_TOGGLE_TSX } = require('../templates');
 
 test('MARKER_COMMENT is a stable, non-ADHD-referencing string', () => {
   assert.match(MARKER_COMMENT, /design-system-docs-route/);
@@ -75,12 +75,55 @@ test('PROP_TOGGLE_TSX uses router.replace for snappy URL updates', () => {
   assert.match(PROP_TOGGLE_TSX, /router\.replace/);
 });
 
+test('LAYOUT_TSX renders a DiagnosticBanner that surfaces detected globals.css issues', () => {
+  // The layout's whole reason for reading globals.css is to surface diagnostic issues
+  // pre-emptively. The banner component must be in the template and wired into render.
+  assert.match(LAYOUT_TSX, /DiagnosticBanner/);
+  assert.match(LAYOUT_TSX, /<DiagnosticBanner issues=\{issues\} \/>/);
+});
+
+test('LAYOUT_TSX detection flags missing --color-ring-offset-background on shadcn-like themes', () => {
+  // The detection heuristic should mention the ring-offset-background token explicitly
+  // (the most common shadcn v3-to-v4 migration gap that surfaces on broad dynamic imports).
+  assert.match(LAYOUT_TSX, /--color-ring-offset-background/);
+  assert.match(LAYOUT_TSX, /looksShadcn/);
+});
+
+test('LAYOUT_TSX gracefully handles a missing globals.css (detectIssues returns [])', () => {
+  // detectIssues must return [] when css is null — the layout still needs to render
+  // for projects without globals.css.
+  assert.match(LAYOUT_TSX, /if \(!css\) return issues;/);
+});
+
+test('INDEX_PAGE_TSX has a Troubleshooting section explaining the ENOENT failure mode', () => {
+  assert.match(INDEX_PAGE_TSX, /Troubleshooting/);
+  assert.match(INDEX_PAGE_TSX, /app-build-manifest/);
+  assert.match(INDEX_PAGE_TSX, /broad dynamic import/i);
+});
+
+test('COMPONENT_ERROR_TSX is a client component error boundary', () => {
+  const afterMarker = COMPONENT_ERROR_TSX.replace(MARKER_COMMENT, '');
+  assert.match(afterMarker, /^["']use client["']/);
+  // The error boundary props signature Next.js passes in
+  assert.match(COMPONENT_ERROR_TSX, /error.*reset/);
+  // Re-render mechanism
+  assert.match(COMPONENT_ERROR_TSX, /reset\(\)/);
+});
+
+test('COMPONENT_ERROR_TSX distinguishes the build-manifest ENOENT from other runtime errors', () => {
+  // The boundary inspects the error message and shows a focused note for the
+  // bundler-level ENOENT (which it technically can't recover, but the user
+  // should be told what's happening if it bubbles up).
+  assert.match(COMPONENT_ERROR_TSX, /app-build-manifest/);
+  assert.match(COMPONENT_ERROR_TSX, /isBuildManifestError/);
+});
+
 test('none of the templates contain "ADHD" outside the marker', () => {
   // The literal filename `adhd.config.ts` is the consumer's own config artifact
   // (per the install spec) and is not a reference to the ADHD plugin/brand —
   // it's an unavoidable filename the generated pages must read at runtime.
   // Strip it before applying the "no ADHD references" rule.
-  for (const [name, content] of Object.entries({ LAYOUT_TSX, INDEX_PAGE_TSX, TOKENS_PAGE_TSX, COMPONENT_PAGE_TSX, PROP_TOGGLE_TSX })) {
+  for (const [name, content] of Object.entries({ LAYOUT_TSX, INDEX_PAGE_TSX, TOKENS_PAGE_TSX, COMPONENT_PAGE_TSX, COMPONENT_ERROR_TSX, PROP_TOGGLE_TSX })) {
     const body = content.replace(MARKER_COMMENT, '').replace(/adhd\.config\.ts/g, '');
     assert.equal(/adhd/i.test(body), false, `${name} must not reference ADHD outside marker`);
   }
diff --git a/plugins/adhd/lib/install-design-system-docs-route/route-installer.js b/plugins/adhd/lib/install-design-system-docs-route/route-installer.js
index 1c1a538..e922dc7 100644
--- a/plugins/adhd/lib/install-design-system-docs-route/route-installer.js
+++ b/plugins/adhd/lib/install-design-system-docs-route/route-installer.js
@@ -7,6 +7,7 @@ const {
   INDEX_PAGE_TSX,
   TOKENS_PAGE_TSX,
   COMPONENT_PAGE_TSX,
+  COMPONENT_ERROR_TSX,
   PROP_TOGGLE_TSX,
 } = require('./templates');
 
@@ -49,6 +50,10 @@ function installRoute(projectRoot, opts) {
     { abs: path.join(docsDir, `page${pageExt}`), body: INDEX_PAGE_TSX },
     { abs: path.join(tokensDir, `page${pageExt}`), body: TOKENS_PAGE_TSX },
     { abs: path.join(componentsDir, `page${pageExt}`), body: COMPONENT_PAGE_TSX },
+    // error.tsx must be a client component, and Next.js handles it like any
+    // route file — it goes through pageExtensions. The plain `.tsx` variant
+    // is used when prod-exclusion is off (mirrors layout/page).
+    { abs: path.join(componentsDir, `error${pageExt}`), body: COMPONENT_ERROR_TSX },
     { abs: path.join(docsDir, `PropToggle${moduleExt}`), body: PROP_TOGGLE_TSX },
   ];
 
diff --git a/plugins/adhd/lib/install-design-system-docs-route/templates.js b/plugins/adhd/lib/install-design-system-docs-route/templates.js
index 850dd9d..f957371 100644
--- a/plugins/adhd/lib/install-design-system-docs-route/templates.js
+++ b/plugins/adhd/lib/install-design-system-docs-route/templates.js
@@ -138,8 +138,67 @@ function slugFor(p: string) {
   return p.replace(/\\.tsx?$/, "").replace(/\\/index$/, "").split("/").pop()?.toLowerCase() ?? p;
 }`;
 
+// Shared globals.css reader. Returns the file contents or null if missing.
+const READ_CSS_SRC = `async function readCss(cssEntry: string) {
+  try { return await fs.readFile(path.resolve(process.cwd(), cssEntry), "utf8"); }
+  catch { return null; }
+}`;
+
+// Diagnostic banner detection: scans the consumer's @theme block for token-name
+// shibboleths that indicate a shadcn-style v3-to-v4 migration, and flags common
+// tokens that are missing. The dynamic-import pattern used by the component page
+// pulls in more files than the consumer's normal routes do, which surfaces stale
+// `@apply` directives in transitively-bundled CSS — these missing tokens are the
+// usual cause.
+const DETECT_ISSUES_SRC = `type DetectedIssue = {
+  token: string;
+  why: string;
+  themeLine: string;
+  rootLine?: string;
+};
+
+function detectIssues(css: string | null): DetectedIssue[] {
+  const issues: DetectedIssue[] = [];
+  if (!css) return issues;
+  // Extract bodies of every @theme block (supports \`@theme inline\` modifier).
+  const bodies: string[] = [];
+  let i = 0;
+  while (i < css.length) {
+    const idx = css.indexOf("@theme", i);
+    if (idx === -1) break;
+    let j = idx + "@theme".length;
+    while (j < css.length && css[j] !== "{" && css[j] !== ";") j++;
+    if (css[j] !== "{") { i = j + 1; continue; }
+    let depth = 1, k = j + 1;
+    while (k < css.length && depth > 0) {
+      if (css[k] === "{") depth++;
+      else if (css[k] === "}") depth--;
+      if (depth > 0) k++;
+    }
+    bodies.push(css.slice(j + 1, k));
+    i = k + 1;
+  }
+  const themeText = bodies.join("\\n");
+  const has = (token: string) => new RegExp("(?:^|\\\\s)" + token.replace(/[-]/g, "\\\\-") + "\\\\s*:").test(themeText);
+
+  // Shadcn shibboleth: foreground+background plus at least one *-foreground pair.
+  const looksShadcn = has("--color-foreground") && has("--color-background") &&
+    (has("--color-card-foreground") || has("--color-popover-foreground"));
+
+  if (looksShadcn && !has("--color-ring-offset-background")) {
+    issues.push({
+      token: "--color-ring-offset-background",
+      why: "Shadcn components use \`ring-offset-background\` for focus styles. Without this in @theme, any \`@apply ring-offset-background\` in transitively-bundled CSS (from a UI library or stale components in your project) will fail with \\"Cannot apply unknown utility class ring-offset-background\\" during route compilation, and the component page will 500 with an ENOENT on the build manifest.",
+      themeLine: "--color-ring-offset-background: hsl(var(--ring-offset-background));",
+      rootLine: "--ring-offset-background: 0 0% 100%;",
+    });
+  }
+
+  return issues;
+}`;
+
 // Layout: sidebar lists token domains + components; main area renders children.
-// The layout is async so it can read adhd.config.ts to populate the components list.
+// The layout is async so it can read adhd.config.ts and globals.css for diagnostics.
 const LAYOUT_TSX = `${MARKER_COMMENT}import type { Metadata } from "next";
 import fs from "node:fs/promises";
 import path from "node:path";
@@ -154,8 +213,37 @@ ${TOKEN_DOMAINS_SRC}
 
 ${READ_CONFIG_SRC}
 
+${READ_CSS_SRC}
+
+${DETECT_ISSUES_SRC}
+
+function DiagnosticBanner({ issues }: { issues: DetectedIssue[] }) {
+  if (issues.length === 0) return null;
+  return (
+    <aside className="mb-6 rounded-md border border-amber-400 bg-amber-50 dark:border-amber-700 dark:bg-amber-950/30 p-4">
+      <h3 className="text-sm font-medium text-amber-900 dark:text-amber-200">
+        Heads up — likely globals.css gaps
+      </h3>
+      <p className="mt-1 text-xs text-amber-800 dark:text-amber-300 max-w-prose">
+        Component pages use a broad dynamic import which causes Tailwind v4 to scan more of your codebase than your other routes do. Your <code>@theme</code> block looks like a shadcn migration but is missing tokens that often appear in transitively-bundled CSS. If you see <code>ENOENT</code> on <code>app-build-manifest.json</code> when navigating to a component, add these:
+      </p>
+      <ul className="mt-3 flex flex-col gap-3 text-xs">
+        {issues.map(i => (
+          <li key={i.token} className="rounded bg-amber-100 dark:bg-amber-950/50 p-3">
+            <code className="font-medium text-amber-900 dark:text-amber-200">{i.token}</code>
+            <p className="mt-1 text-amber-800 dark:text-amber-300">{i.why}</p>
+            <pre className="mt-2 overflow-x-auto rounded bg-amber-200/60 dark:bg-amber-900/40 p-2 text-[11px] text-amber-900 dark:text-amber-100">{\`/* in @theme */\\n\${i.themeLine}\${i.rootLine ? \`\\n\\n/* in :root */\\n\${i.rootLine}\` : ""}\`}</pre>
+          </li>
+        ))}
+      </ul>
+    </aside>
+  );
+}
+
 export default async function DesignSystemDocsLayout({ children }: { children: React.ReactNode }) {
   const cfg = await readConfig();
+  const css = await readCss(cfg.cssEntry);
+  const issues = detectIssues(css);
   const components = cfg.components.map(p => ({ raw: p, slug: slugFor(p) }));
 
   return (
@@ -200,25 +288,70 @@ export default async function DesignSystemDocsLayout({ children }: { children: R
       </aside>
 
       <main className="flex-1 p-8 overflow-x-auto">
-        <div className="max-w-5xl">{children}</div>
+        <div className="max-w-5xl">
+          <DiagnosticBanner issues={issues} />
+          {children}
+        </div>
       </main>
     </div>
   );
 }
 `;
 
-// Landing page — minimal welcome message; the sidebar already shows everything.
+// Landing page — welcome + troubleshooting. The sidebar already shows tokens/components,
+// so the body focuses on what the layout's diagnostic banner can't pre-emptively flag.
 const INDEX_PAGE_TSX = `${MARKER_COMMENT}export default function DesignSystemIndex() {
   return (
-    <div className="flex flex-col gap-4">
-      <h2 className="text-2xl font-medium">Design System</h2>
-      <p className="text-sm text-zinc-600 dark:text-zinc-400 max-w-prose">
-        Pick a token domain or a component from the sidebar. Tokens are read from your
-        <code className="mx-1 rounded bg-zinc-100 dark:bg-zinc-900 px-1 py-0.5 text-xs">globals.css</code>
-        <code className="rounded bg-zinc-100 dark:bg-zinc-900 px-1 py-0.5 text-xs">@theme</code> blocks.
-        Components are loaded from
-        <code className="ml-1 rounded bg-zinc-100 dark:bg-zinc-900 px-1 py-0.5 text-xs">adhd.config.ts</code>.
-      </p>
+    <div className="flex flex-col gap-8">
+      <header>
+        <h2 className="text-2xl font-medium">Design System</h2>
+        <p className="mt-2 text-sm text-zinc-600 dark:text-zinc-400 max-w-prose">
+          Pick a token domain or a component from the sidebar. Tokens are read from your
+          <code className="mx-1 rounded bg-zinc-100 dark:bg-zinc-900 px-1 py-0.5 text-xs">globals.css</code>
+          <code className="rounded bg-zinc-100 dark:bg-zinc-900 px-1 py-0.5 text-xs">@theme</code> blocks.
+          Components are loaded from
+          <code className="ml-1 rounded bg-zinc-100 dark:bg-zinc-900 px-1 py-0.5 text-xs">adhd.config.ts</code>.
+        </p>
+      </header>
+
+      <section className="flex flex-col gap-3">
+        <h3 className="text-sm font-medium uppercase tracking-wide text-zinc-500">Troubleshooting</h3>
+        <div className="flex flex-col gap-4 text-sm text-zinc-700 dark:text-zinc-300 max-w-prose">
+          <details className="rounded border border-zinc-200 dark:border-zinc-800 p-4">
+            <summary className="cursor-pointer font-medium">Component page 500s with <code>ENOENT: ... app-build-manifest.json</code></summary>
+            <div className="mt-3 flex flex-col gap-3">
+              <p>
+                The component page uses a broad dynamic import keyed off <code>adhd.config.ts</code>, so adding components is just a config edit. The trade-off: Webpack/Turbopack can&apos;t statically resolve the path, so it creates a context module that pulls every file under <code>@/</code> into this route&apos;s bundle, and Tailwind v4 then scans all of them for classes.
+              </p>
+              <p>
+                Your other routes only bundle what they statically import, so latent issues never surface there. On <em>this</em> route, Tailwind hits classes referenced in transitively-bundled CSS (often a UI lib like shadcn or <code>@reactor-team/ui</code>) that your <code>@theme</code> doesn&apos;t define yet. Tailwind throws, the CSS chunk never emits, and the manifest write fails — hence ENOENT.
+              </p>
+              <p className="font-medium">Fix:</p>
+              <ol className="list-decimal pl-5 flex flex-col gap-1">
+                <li>Run <code>npm run dev</code> in a terminal and watch the output when you navigate to <code>/components/&lt;X&gt;</code>.</li>
+                <li>Look for <code>Cannot apply unknown utility class &lt;name&gt;</code> or <code>Cannot use @variant with unknown variant: &lt;name&gt;</code>.</li>
+                <li>For utility class names, add <code>--color-&lt;name&gt;</code> (or appropriate prefix) to your <code>@theme</code> block.</li>
+                <li>For variant names, add <code>--breakpoint-&lt;name&gt;</code> to your <code>@theme</code> block.</li>
+              </ol>
+              <p className="text-xs text-zinc-500">If the layout&apos;s diagnostic banner is showing above this content, it has detected a likely candidate already.</p>
+            </div>
+          </details>
+
+          <details className="rounded border border-zinc-200 dark:border-zinc-800 p-4">
+            <summary className="cursor-pointer font-medium">Sidebar shows the component but the page fails to load it</summary>
+            <p className="mt-3">
+              Check the path in <code>adhd.config.ts</code> resolves from your project root, and that the file exports a function (default export or a named function). If the dynamic import fails at runtime (not at compile), the error boundary at <code>components/[component]/error.tsx</code> will catch it and show the message.
+            </p>
+          </details>
+
+          <details className="rounded border border-zinc-200 dark:border-zinc-800 p-4">
+            <summary className="cursor-pointer font-medium">Token domain shows &ldquo;no custom tokens&rdquo; but you have some</summary>
+            <p className="mt-3">
+              The parser supports <code>@theme {"{ ... }"}</code> and <code>@theme inline {"{ ... }"}</code>. If your tokens are in a different syntax (e.g. <code>:root</code>), they won&apos;t be picked up — Tailwind v4 only treats <code>@theme</code> declarations as design tokens.
+            </p>
+          </details>
+        </div>
+      </section>
     </div>
   );
 }
@@ -235,10 +368,7 @@ ${TOKEN_DOMAINS_SRC}
 
 ${READ_CONFIG_SRC}
 
-async function readCss(cssEntry: string) {
-  try { return await fs.readFile(path.resolve(process.cwd(), cssEntry), "utf8"); }
-  catch { return null; }
-}
+${READ_CSS_SRC}
 
 ${PARSE_TOKENS_SRC}
 
@@ -578,6 +708,47 @@ export default async function ComponentPage({
 }
 `;
 
+// Error boundary for the component route. Catches RUNTIME errors thrown during
+// rendering — broken dynamic imports, components that throw on mount, prop-parse
+// failures. Does NOT catch bundler-level Tailwind/PostCSS failures (those happen
+// before React runs); the layout's diagnostic banner handles that case.
+const COMPONENT_ERROR_TSX = `${MARKER_COMMENT}"use client";
+
+export default function ComponentPageError({ error, reset }: { error: Error & { digest?: string }; reset: () => void }) {
+  const isBuildManifestError = /app-build-manifest\\.json/.test(error.message ?? "");
+  return (
+    <div className="flex flex-col gap-4">
+      <div className="rounded border border-red-300 bg-red-50 dark:border-red-800 dark:bg-red-950/30 p-6">
+        <h2 className="text-lg font-medium text-red-900 dark:text-red-200">Couldn't render this component</h2>
+        <p className="mt-2 text-sm text-red-800 dark:text-red-300">
+          {isBuildManifestError
+            ? "Next.js failed to load this route's build manifest. This usually means Tailwind v4 couldn't compile CSS for the route — see the diagnostic banner above (or the Troubleshooting section on the docs landing page) for the likely cause."
+            : "Something went wrong while loading or rendering this component. Common causes:"}
+        </p>
+        {!isBuildManifestError && (
+          <ul className="mt-3 list-disc pl-6 text-sm text-red-800 dark:text-red-300">
+            <li>The path in <code>adhd.config.ts</code> doesn't resolve from the project root.</li>
+            <li>The component throws on mount when no props are provided.</li>
+            <li>The component's prop interface uses types the docs route can't introspect.</li>
+          </ul>
+        )}
+        <details className="mt-4 text-xs">
+          <summary className="cursor-pointer text-red-700 dark:text-red-300">Show error details</summary>
+          <pre className="mt-2 overflow-x-auto rounded bg-red-100 dark:bg-red-950/50 p-2 text-red-900 dark:text-red-200">{error.message}{error.digest ? \`\\n\\nDigest: \${error.digest}\` : ""}</pre>
+        </details>
+        <button
+          type="button"
+          onClick={() => reset()}
+          className="mt-4 rounded border border-red-300 dark:border-red-700 px-3 py-1 text-sm text-red-900 dark:text-red-200 hover:bg-red-100 dark:hover:bg-red-900/30"
+        >
+          Try again
+        </button>
+      </div>
+    </div>
+  );
+}
+`;
+
 const PROP_TOGGLE_TSX = `${MARKER_COMMENT}"use client";
 import { useRouter, useSearchParams, usePathname } from "next/navigation";
 
@@ -622,5 +793,6 @@ module.exports = {
   INDEX_PAGE_TSX,
   TOKENS_PAGE_TSX,
   COMPONENT_PAGE_TSX,
+  COMPONENT_ERROR_TSX,
   PROP_TOGGLE_TSX,
 };

From 999fda036547e7ffb13302c18562416cc8d815a3 Mon Sep 17 00:00:00 2001
From: Hugh Francis <hughfrancis89@gmail.com>
Date: Mon, 11 May 2026 16:38:53 -0400
Subject: [PATCH 24/79] install-docs-route SKILL: batch Phase 3 questions into
 one wizard prompt
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The three install choices (route URL, route group, prod exclusion) are
independent — no answer affects the next question — so they can be passed
to AskUserQuestion as a single multi-question call. Renders as one
wizard-style prompt instead of three sequential round-trips.

Also note the fallback for failed Other-text validation (re-ask just that
question in a follow-up call).

Audited /adhd:config for the same opportunity but its phases branch on
each other (Phase 2's keep/replace/abort gates Phase 1; Phase 6 only
fires after Phase 5 reports a successful write), so batching would force
wasteful questions. Left as-is.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 plugins/adhd/skills/install-design-system-docs-route/SKILL.md | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/plugins/adhd/skills/install-design-system-docs-route/SKILL.md b/plugins/adhd/skills/install-design-system-docs-route/SKILL.md
index 9add183..98f7efa 100644
--- a/plugins/adhd/skills/install-design-system-docs-route/SKILL.md
+++ b/plugins/adhd/skills/install-design-system-docs-route/SKILL.md
@@ -45,12 +45,14 @@ If user chose "Update in place": derive `groupName` and `routeSegment` from the
 
 ## Phase 3: Ask installation choices
 
-Use `AskUserQuestion` three times:
+Ask all three questions in a **single** `AskUserQuestion` call so the user sees them as one wizard-style prompt rather than three round-trips. The questions are independent — no branching between answers — so batching is safe.
 
 1. **Route URL** — default `/-docs`. Validate: starts with `/`, only `a-z0-9-/` characters, no leading `_`.
 2. **Route group** — default `(design-system)`. Validate: parens-wrapped, alphanumerics + hyphens inside, OR empty string for "no group."
 3. **Exclude from production builds?** — default `Yes`.
 
+If a custom "Other" answer fails validation, re-ask only that one question in a follow-up `AskUserQuestion` call.
+
 Derive `groupName` and `routeSegment` from these answers. Example: routeUrl `/-docs` → routeSegment `-docs`. The group is independent of the URL.
 
 ## Phase 4: Detect Next.js config file

From f149df2b0591d441a1df086ef8e9b07641f70b05 Mon Sep 17 00:00:00 2001
From: Hugh Francis <hughfrancis89@gmail.com>
Date: Mon, 11 May 2026 16:53:30 -0400
Subject: [PATCH 25/79] setup-design-system-docs-route: rename + flip to static
 imports
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Renames `/adhd:install-design-system-docs-route` to `/adhd:setup-design-system-docs-route`
to reflect the actual lifecycle: this is something you re-run, not a
one-shot install. Rename touches the skill folder, the lib folder, all
test fixtures, the CI workflow, README, marketplace docs, and the config
skill's cross-reference.

The bigger change is the architecture flip. The previous component page
did `import("@/" + componentPath)` so adding to adhd.config.ts was enough
to surface a new component. The cost was that Webpack/Turbopack can't
statically resolve a template-literal import, so it generated a context
module covering every .ts/.tsx under the project root. Tailwind v4 then
scanned all of those files for classes — a far wider surface than the
consumer's normal routes — and surfaced legacy shadcn classes
(`ring-offset-background`, custom `xs:` variants, etc.) that weren't in
the consumer's @theme. The route 500'd with an opaque ENOENT on
`app-build-manifest.json` because Tailwind's PostCSS pipeline crashed and
no manifest was written.

New flow: the installer parses adhd.config.ts at install time and
generates `componentMap.tsx` per project. Each tracked component gets an
explicit `import * as $cmpN from "@/<importPath>"` statement, so the
bundler resolves exactly the modules in the components map — no context
module, no broad bundle, no Tailwind blast radius. The component page
calls `getComponent(slug)` from the generated map and renders. To add,
rename, or remove a component, edit adhd.config.ts and re-run the setup
skill.

The diagnostic banner introduced in the previous PR is gone — it existed
specifically to flag the missing-token failure mode that broad dynamic
imports surfaced, and that mode no longer exists. error.tsx stays for
runtime render failures (component throws on mount, etc.). The landing
page's troubleshooting section is rewritten around the new model: the
main failure mode is "you added a component to adhd.config.ts and forgot
to re-run."

New module: `config-parser.js` reads adhd.config.ts server-side. The
components-map parser uses a brace-counted scan (not the previous
non-greedy regex) so nested `{ figma: { url: "..." } }` values don't
truncate the parse — previously a fixture with two components revealed
that bug, but the lone test fixture only ever had one.

componentMap.tsx resolution: prefer `default` export, fall back to the
first named function. Mirrors the runtime resolution behavior the dynamic
import did, so existing user components keep working without changes.

Tests: full plugin suite, 377/377.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 .github/workflows/ci.yml                      |   4 +-
 README.md                                     |  53 ++-
 .../__tests__/route-installer.test.js         | 214 ------------
 .../__tests__/templates.test.js               | 130 -------
 .../README.md                                 |  13 +-
 .../__fixtures__/avatar.tsx                   |   0
 .../__fixtures__/globals.css                  |   0
 .../__tests__/cli.test.js                     |  30 +-
 .../__tests__/config-parser.test.js           |  93 +++++
 .../__tests__/next-config-patcher.test.js     |   0
 .../__tests__/prop-parser.test.js             |   0
 .../__tests__/robots-patcher.test.js          |   0
 .../__tests__/route-installer.test.js         | 330 ++++++++++++++++++
 .../__tests__/slug.test.js                    |   0
 .../__tests__/templates.test.js               | 151 ++++++++
 .../__tests__/token-parser.test.js            |   0
 .../cli.js                                    |  19 +-
 .../config-parser.js                          |  93 +++++
 .../next-config-patcher.js                    |   0
 .../prop-parser.js                            |   0
 .../robots-patcher.js                         |   0
 .../route-installer.js                        |  74 ++--
 .../slug.js                                   |   0
 .../templates.js                              | 326 +++++++----------
 .../token-parser.js                           |   0
 plugins/adhd/skills/config/SKILL.md           |   6 +-
 .../SKILL.md                                  |  42 ++-
 27 files changed, 930 insertions(+), 648 deletions(-)
 delete mode 100644 plugins/adhd/lib/install-design-system-docs-route/__tests__/route-installer.test.js
 delete mode 100644 plugins/adhd/lib/install-design-system-docs-route/__tests__/templates.test.js
 rename plugins/adhd/lib/{install-design-system-docs-route => setup-design-system-docs-route}/README.md (51%)
 rename plugins/adhd/lib/{install-design-system-docs-route => setup-design-system-docs-route}/__fixtures__/avatar.tsx (100%)
 rename plugins/adhd/lib/{install-design-system-docs-route => setup-design-system-docs-route}/__fixtures__/globals.css (100%)
 rename plugins/adhd/lib/{install-design-system-docs-route => setup-design-system-docs-route}/__tests__/cli.test.js (76%)
 create mode 100644 plugins/adhd/lib/setup-design-system-docs-route/__tests__/config-parser.test.js
 rename plugins/adhd/lib/{install-design-system-docs-route => setup-design-system-docs-route}/__tests__/next-config-patcher.test.js (100%)
 rename plugins/adhd/lib/{install-design-system-docs-route => setup-design-system-docs-route}/__tests__/prop-parser.test.js (100%)
 rename plugins/adhd/lib/{install-design-system-docs-route => setup-design-system-docs-route}/__tests__/robots-patcher.test.js (100%)
 create mode 100644 plugins/adhd/lib/setup-design-system-docs-route/__tests__/route-installer.test.js
 rename plugins/adhd/lib/{install-design-system-docs-route => setup-design-system-docs-route}/__tests__/slug.test.js (100%)
 create mode 100644 plugins/adhd/lib/setup-design-system-docs-route/__tests__/templates.test.js
 rename plugins/adhd/lib/{install-design-system-docs-route => setup-design-system-docs-route}/__tests__/token-parser.test.js (100%)
 rename plugins/adhd/lib/{install-design-system-docs-route => setup-design-system-docs-route}/cli.js (82%)
 create mode 100644 plugins/adhd/lib/setup-design-system-docs-route/config-parser.js
 rename plugins/adhd/lib/{install-design-system-docs-route => setup-design-system-docs-route}/next-config-patcher.js (100%)
 rename plugins/adhd/lib/{install-design-system-docs-route => setup-design-system-docs-route}/prop-parser.js (100%)
 rename plugins/adhd/lib/{install-design-system-docs-route => setup-design-system-docs-route}/robots-patcher.js (100%)
 rename plugins/adhd/lib/{install-design-system-docs-route => setup-design-system-docs-route}/route-installer.js (59%)
 rename plugins/adhd/lib/{install-design-system-docs-route => setup-design-system-docs-route}/slug.js (100%)
 rename plugins/adhd/lib/{install-design-system-docs-route => setup-design-system-docs-route}/templates.js (67%)
 rename plugins/adhd/lib/{install-design-system-docs-route => setup-design-system-docs-route}/token-parser.js (100%)
 rename plugins/adhd/skills/{install-design-system-docs-route => setup-design-system-docs-route}/SKILL.md (61%)

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 79c021f..b72bdd5 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -23,8 +23,8 @@ jobs:
         run: node --test plugins/adhd/lib/push-component/__tests__/
       - name: Run pull-component tests
         run: node --test plugins/adhd/lib/pull-component/__tests__/
-      - name: Run install-design-system-docs-route tests
-        run: node --test plugins/adhd/lib/install-design-system-docs-route/__tests__/
+      - name: Run setup-design-system-docs-route tests
+        run: node --test plugins/adhd/lib/setup-design-system-docs-route/__tests__/
 
   hygiene:
     name: project hygiene
diff --git a/README.md b/README.md
index 948e4a8..5049656 100644
--- a/README.md
+++ b/README.md
@@ -34,7 +34,7 @@ After install, seven slash commands are available:
 | `/adhd:pull-design-system` | — | Figma → code | Pulls Figma variables + named styles into globals.css |
 | `/adhd:push-component` | `<path> [--max-variants <n>]` | code → Figma | Pushes a React component to Figma as a structured Component Set with variant properties + variable bindings, plus a preflight lint check |
 | `/adhd:pull-component` | `<path \| figma-url> [--allow-unbound]` | Figma → code | Pulls a Figma Component Set into a React source file; updates lookup tables and union types only (function body untouched) |
-| `/adhd:install-design-system-docs-route` | — | install | One-shot installer for a live, self-generating design-system docs route in your Next.js consumer app. Reads adhd.config.ts + globals.css at request time. Excluded from production builds by default. |
+| `/adhd:setup-design-system-docs-route` | — | install | Generates a design-system docs route in your Next.js consumer app. Tokens read live from globals.css; components are statically imported from adhd.config.ts at setup time — re-run after editing the components map. Excluded from production builds by default. |
 
 Every command above drives Figma exclusively through the `figma@claude-plugins-official` plugin. `/adhd:config` checks it's installed + authenticated up front so setup errors surface where you can fix them, not mid-pipeline.
 
@@ -116,14 +116,14 @@ The skill reads the Figma Component Set, diffs it against the React file's `Reco
 Run once in your consumer repo:
 
 ```
-/adhd:install-design-system-docs-route
+/adhd:setup-design-system-docs-route
 ```
 
-This installs a live, self-generating documentation page that reads your
-`adhd.config.ts` and `globals.css` at request time. The default URL is
-`/-docs` (the hyphen prefix telegraphs "internal"), and files live under a
-Next.js route group at `app/(design-system)/-docs/`. The page is a
-sidebar-and-viewer layout:
+This generates a documentation page that reads your `globals.css` live at
+request time and statically imports the components listed in
+`adhd.config.ts`. The default URL is `/-docs` (the hyphen prefix telegraphs
+"internal"), and files live under a Next.js route group at
+`app/(design-system)/-docs/`. The page is a sidebar-and-viewer layout:
 
 - Sidebar: lists every Tailwind v4 token domain (colors, spacing, typography,
   font families, font weights, tracking, leading, radius, shadows,
@@ -137,31 +137,26 @@ sidebar-and-viewer layout:
 
 By default the route is excluded from production builds via Next.js's
 `pageExtensions` trick — files use the `.design-system.tsx` extension and
-the production build literally doesn't see them. You can opt out at install
+the production build literally doesn't see them. You can opt out at setup
 time if you'd rather ship the route (it still has `<meta name="robots"
 content="noindex, nofollow" />` either way).
 
-Re-run the installer over time to pick up improved templates. Files you've
-customized — by removing the `// design-system-docs-route` marker comment —
-are left alone.
-
-#### Caveat: broad dynamic import + Tailwind v4
-
-The component page resolves its target via `import("@/" + componentPath)` so
-adding to `adhd.config.ts` is enough — no re-install per component. The
-trade-off: Webpack/Turbopack can't statically resolve the path, so it
-creates a context module that pulls every `.ts`/`.tsx` under your project
-root into this route's bundle. Tailwind v4 then scans all of them for
-classes — a much wider surface than your other routes touch.
-
-If your codebase has shadcn-v3-era classes that you never migrated (most
-commonly `ring-offset-background`, used by Button/Input focus styles),
-they'll surface as `Cannot apply unknown utility class …` errors during
-route compilation, and the page will 500 with an ENOENT on
-`app-build-manifest.json`. The layout pre-scans your `globals.css` for the
-shadcn shibboleth and shows a diagnostic banner with the exact `@theme`
-addition you need to make. There's also an `error.tsx` at the route boundary
-for any runtime failures, and a Troubleshooting section on the landing page.
+#### Re-running after `adhd.config.ts` changes
+
+The setup command generates a `componentMap.tsx` with explicit static
+imports per component. After **adding, renaming, or removing entries** in
+`adhd.config.ts`'s `components` map, re-run
+`/adhd:setup-design-system-docs-route` to regenerate the static imports.
+Tokens don't need this — they're read from `globals.css` at request time.
+
+Files where you've removed the `// design-system-docs-route` marker comment
+are preserved across re-runs.
+
+The static-import architecture is deliberate: it keeps the docs route's
+bundle scoped to exactly your tracked components, sidestepping the
+`Cannot apply unknown utility class …` failure mode that broad dynamic
+imports trigger under Tailwind v4 (legacy shadcn classes in unrelated parts
+of your codebase get bundled and explode during PostCSS).
 
 You can also trigger the install at the end of `/adhd:config` if you're
 setting up ADHD for the first time.
diff --git a/plugins/adhd/lib/install-design-system-docs-route/__tests__/route-installer.test.js b/plugins/adhd/lib/install-design-system-docs-route/__tests__/route-installer.test.js
deleted file mode 100644
index 7c6ab24..0000000
--- a/plugins/adhd/lib/install-design-system-docs-route/__tests__/route-installer.test.js
+++ /dev/null
@@ -1,214 +0,0 @@
-'use strict';
-
-const test = require('node:test');
-const assert = require('node:assert/strict');
-const fs = require('node:fs');
-const path = require('node:path');
-const os = require('node:os');
-const { installRoute, detectExistingInstall } = require('../route-installer');
-
-function makeTempProject() {
-  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'adhd-install-'));
-  fs.mkdirSync(path.join(root, 'app'), { recursive: true });
-  return root;
-}
-
-test('installRoute writes page/layout files with .design-system.tsx suffix when prodExcluded, but PropToggle is always plain .tsx', () => {
-  const root = makeTempProject();
-  installRoute(root, {
-    groupName: '(design-system)',
-    routeSegment: '-docs',
-    prodExcluded: true,
-  });
-  const docsDir = path.join(root, 'app', '(design-system)', '-docs');
-  // Route files (page/layout/error) get the suffix so pageExtensions filters them in prod.
-  assert.ok(fs.existsSync(path.join(docsDir, 'layout.design-system.tsx')));
-  assert.ok(fs.existsSync(path.join(docsDir, 'page.design-system.tsx')));
-  assert.ok(fs.existsSync(path.join(docsDir, 'tokens', '[domain]', 'page.design-system.tsx')));
-  assert.ok(fs.existsSync(path.join(docsDir, 'components', '[component]', 'page.design-system.tsx')));
-  assert.ok(fs.existsSync(path.join(docsDir, 'components', '[component]', 'error.design-system.tsx')));
-  // PropToggle is a module imported by the component page; it doesn't need the
-  // suffix for prod-exclusion (the page that imports it IS suffix-excluded).
-  assert.ok(fs.existsSync(path.join(docsDir, 'PropToggle.tsx')));
-  assert.ok(!fs.existsSync(path.join(docsDir, 'PropToggle.design-system.tsx')));
-});
-
-test('installRoute writes plain .tsx files when not prodExcluded', () => {
-  const root = makeTempProject();
-  installRoute(root, {
-    groupName: '(design-system)',
-    routeSegment: '-docs',
-    prodExcluded: false,
-  });
-  const docsDir = path.join(root, 'app', '(design-system)', '-docs');
-  assert.ok(fs.existsSync(path.join(docsDir, 'layout.tsx')));
-  assert.ok(fs.existsSync(path.join(docsDir, 'page.tsx')));
-  assert.ok(fs.existsSync(path.join(docsDir, 'tokens', '[domain]', 'page.tsx')));
-  assert.ok(fs.existsSync(path.join(docsDir, 'components', '[component]', 'page.tsx')));
-  assert.ok(fs.existsSync(path.join(docsDir, 'components', '[component]', 'error.tsx')));
-  assert.ok(fs.existsSync(path.join(docsDir, 'PropToggle.tsx')));
-});
-
-test('all written files start with the marker comment', () => {
-  const root = makeTempProject();
-  installRoute(root, { groupName: '(design-system)', routeSegment: '-docs', prodExcluded: true });
-  const docsDir = path.join(root, 'app', '(design-system)', '-docs');
-  for (const f of [
-    'layout.design-system.tsx',
-    'page.design-system.tsx',
-    'tokens/[domain]/page.design-system.tsx',
-    'components/[component]/page.design-system.tsx',
-    'components/[component]/error.design-system.tsx',
-    'PropToggle.tsx',
-  ]) {
-    const content = fs.readFileSync(path.join(docsDir, f), 'utf8');
-    assert.match(content, /design-system-docs-route/);
-  }
-});
-
-test('layout sidebar links use absolute hrefs derived from the route segment', () => {
-  // The sidebar lives in the layout, so its links must use absolute hrefs
-  // (`/-docs/tokens/colors`, not `./tokens/colors`) — otherwise nested routes
-  // resolve from the current pathname instead of the docs root.
-  const root = makeTempProject();
-  installRoute(root, { groupName: '(design-system)', routeSegment: '-docs', prodExcluded: true });
-  const layout = fs.readFileSync(
-    path.join(root, 'app', '(design-system)', '-docs', 'layout.design-system.tsx'),
-    'utf8',
-  );
-  assert.match(layout, /href=\{`\/-docs\/tokens\/\$\{d\.slug\}`\}/);
-  assert.match(layout, /href=\{`\/-docs\/components\/\$\{c\.slug\}`\}/);
-  // The placeholder should be fully substituted — no `__ROUTE_PATH__` left over.
-  assert.doesNotMatch(layout, /__ROUTE_PATH__/);
-});
-
-test('route URL substitution honors a custom route segment', () => {
-  const root = makeTempProject();
-  installRoute(root, { groupName: '(design-system)', routeSegment: 'design-system', prodExcluded: true });
-  const layout = fs.readFileSync(
-    path.join(root, 'app', '(design-system)', 'design-system', 'layout.design-system.tsx'),
-    'utf8',
-  );
-  assert.match(layout, /href=\{`\/design-system\/tokens\/\$\{d\.slug\}`\}/);
-});
-
-test('COMPONENT_PAGE_TSX imports PropToggle from "../../PropToggle" (now two levels deep)', () => {
-  const root = makeTempProject();
-  installRoute(root, { groupName: '(design-system)', routeSegment: '-docs', prodExcluded: true });
-  const componentPage = fs.readFileSync(
-    path.join(root, 'app', '(design-system)', '-docs', 'components', '[component]', 'page.design-system.tsx'),
-    'utf8',
-  );
-  assert.match(componentPage, /from "\.\.\/\.\.\/PropToggle"/);
-});
-
-test('TOKENS_PAGE_TSX uses parser that handles `@theme inline { ... }` modifier syntax', () => {
-  const root = makeTempProject();
-  installRoute(root, { groupName: '(design-system)', routeSegment: '-docs', prodExcluded: true });
-  const tokensPage = fs.readFileSync(
-    path.join(root, 'app', '(design-system)', '-docs', 'tokens', '[domain]', 'page.design-system.tsx'),
-    'utf8',
-  );
-  // The inline parser must use the brace-counted scan (NOT the old
-  // `/@theme\s*\{...\}/` regex that misses `@theme inline { ... }`).
-  assert.match(tokensPage, /extractThemeBodies/);
-  // No naïve `@theme\s*\{` regex anywhere.
-  assert.doesNotMatch(tokensPage, /@theme\\s\*\\\{/);
-});
-
-test('TOKENS_PAGE_TSX renders all expected token domains', () => {
-  const root = makeTempProject();
-  installRoute(root, { groupName: '(design-system)', routeSegment: '-docs', prodExcluded: true });
-  const tokensPage = fs.readFileSync(
-    path.join(root, 'app', '(design-system)', '-docs', 'tokens', '[domain]', 'page.design-system.tsx'),
-    'utf8',
-  );
-  for (const slug of ['colors', 'spacing', 'typography', 'font', 'font-weight',
-                      'tracking', 'leading', 'radius', 'shadows', 'breakpoint',
-                      'ease', 'animate']) {
-    assert.match(tokensPage, new RegExp(`slug === "${slug}"`), `missing renderer for ${slug}`);
-  }
-});
-
-test('empty-state messaging references Tailwind defaults, not "no X detected"', () => {
-  const root = makeTempProject();
-  installRoute(root, { groupName: '(design-system)', routeSegment: '-docs', prodExcluded: true });
-  const tokensPage = fs.readFileSync(
-    path.join(root, 'app', '(design-system)', '-docs', 'tokens', '[domain]', 'page.design-system.tsx'),
-    'utf8',
-  );
-  assert.match(tokensPage, /Tailwind v4 ships sensible defaults/);
-  // The misleading "No X detected" phrasing is gone.
-  assert.doesNotMatch(tokensPage, /No (colors|typography|radius|shadow) (tokens? )?detected/);
-});
-
-test('detectExistingInstall scans for the marker and returns matching files', () => {
-  const root = makeTempProject();
-  installRoute(root, { groupName: '(design-system)', routeSegment: '-docs', prodExcluded: true });
-  const found = detectExistingInstall(root);
-  assert.ok(found.length >= 6);
-  assert.ok(found.every(p => p.includes('-docs')));
-});
-
-test('detectExistingInstall returns [] when no marker is present', () => {
-  const root = makeTempProject();
-  const found = detectExistingInstall(root);
-  assert.deepEqual(found, []);
-});
-
-test('detectExistingInstall does not match unrelated files', () => {
-  const root = makeTempProject();
-  fs.writeFileSync(path.join(root, 'app', 'page.tsx'), 'export default function P() { return null; }\n');
-  assert.deepEqual(detectExistingInstall(root), []);
-});
-
-test('re-running installRoute overwrites files cleanly', () => {
-  const root = makeTempProject();
-  installRoute(root, { groupName: '(design-system)', routeSegment: '-docs', prodExcluded: true });
-  const layoutPath = path.join(root, 'app', '(design-system)', '-docs', 'layout.design-system.tsx');
-  fs.writeFileSync(layoutPath, 'corrupted');
-  installRoute(root, { groupName: '(design-system)', routeSegment: '-docs', prodExcluded: true });
-  const after = fs.readFileSync(layoutPath, 'utf8');
-  assert.match(after, /design-system-docs-route/);
-  assert.match(after, /DesignSystemDocsLayout/);
-});
-
-test('installRoute removes stale marker-bearing files from a previous install layout', () => {
-  // Simulate an older install where the component page lived at `[component]/page.*`
-  // directly under docsDir (the structure before the tokens/[domain] + components/[component] split).
-  const root = makeTempProject();
-  const docsDir = path.join(root, 'app', '(design-system)', '-docs');
-  const oldComponentDir = path.join(docsDir, '[component]');
-  fs.mkdirSync(oldComponentDir, { recursive: true });
-  const oldPath = path.join(oldComponentDir, 'page.design-system.tsx');
-  fs.writeFileSync(oldPath, '// design-system-docs-route — stale\nexport default function Old() { return null; }\n');
-
-  const result = installRoute(root, { groupName: '(design-system)', routeSegment: '-docs', prodExcluded: true });
-
-  // Stale file removed, reported in `removed`, and its now-empty parent dir pruned.
-  assert.ok(!fs.existsSync(oldPath), 'stale file should be deleted');
-  assert.ok(result.removed.includes(oldPath));
-  assert.ok(!fs.existsSync(oldComponentDir), 'empty `[component]` directory should be pruned');
-});
-
-test('installRoute does NOT delete unrelated files (only marker-bearing ones)', () => {
-  const root = makeTempProject();
-  const docsDir = path.join(root, 'app', '(design-system)', '-docs');
-  // Pre-install a user-authored file under docsDir without the marker.
-  fs.mkdirSync(docsDir, { recursive: true });
-  const userFile = path.join(docsDir, 'user-notes.tsx');
-  fs.writeFileSync(userFile, '// user wrote this\nexport const NOTE = "keep me";\n');
-
-  installRoute(root, { groupName: '(design-system)', routeSegment: '-docs', prodExcluded: true });
-
-  assert.ok(fs.existsSync(userFile), 'user file without marker must be preserved');
-});
-
-test('installRoute supports an empty groupName (no route group)', () => {
-  const root = makeTempProject();
-  installRoute(root, { groupName: '', routeSegment: '-docs', prodExcluded: true });
-  const docsDir = path.join(root, 'app', '-docs');
-  assert.ok(fs.existsSync(path.join(docsDir, 'layout.design-system.tsx')));
-  assert.ok(fs.existsSync(path.join(docsDir, 'PropToggle.tsx')));
-  assert.ok(fs.existsSync(path.join(docsDir, 'tokens', '[domain]', 'page.design-system.tsx')));
-});
diff --git a/plugins/adhd/lib/install-design-system-docs-route/__tests__/templates.test.js b/plugins/adhd/lib/install-design-system-docs-route/__tests__/templates.test.js
deleted file mode 100644
index 57ddae5..0000000
--- a/plugins/adhd/lib/install-design-system-docs-route/__tests__/templates.test.js
+++ /dev/null
@@ -1,130 +0,0 @@
-'use strict';
-
-const test = require('node:test');
-const assert = require('node:assert/strict');
-const { MARKER_COMMENT, LAYOUT_TSX, INDEX_PAGE_TSX, TOKENS_PAGE_TSX, COMPONENT_PAGE_TSX, COMPONENT_ERROR_TSX, PROP_TOGGLE_TSX } = require('../templates');
-
-test('MARKER_COMMENT is a stable, non-ADHD-referencing string', () => {
-  assert.match(MARKER_COMMENT, /design-system-docs-route/);
-  assert.match(MARKER_COMMENT, /auto-generated installer artifact; safe to edit/);
-  assert.equal(/adhd/i.test(MARKER_COMMENT), false, 'must not reference ADHD');
-});
-
-test('LAYOUT_TSX starts with the marker comment', () => {
-  assert.ok(LAYOUT_TSX.startsWith(MARKER_COMMENT));
-});
-
-test('LAYOUT_TSX sets robots: noindex / nofollow', () => {
-  assert.match(LAYOUT_TSX, /robots:\s*\{[^}]*index:\s*false[^}]*follow:\s*false/);
-});
-
-test('LAYOUT_TSX has no ADHD references outside marker', () => {
-  // marker excluded — the filename `adhd.config.ts` is the spec-allowed exception
-  // (the layout reads it to populate the Components sidebar list).
-  const body = LAYOUT_TSX.replace(MARKER_COMMENT, '').replace(/adhd\.config\.ts/g, '');
-  assert.equal(/adhd/i.test(body), false);
-});
-
-test('LAYOUT_TSX renders sidebar nav linking every token domain', () => {
-  // The sidebar replaces the old single-page sections — every token domain
-  // gets its own entry in the layout's nav.
-  for (const label of [
-    'Colors', 'Spacing', 'Typography', 'Font Families', 'Font Weights',
-    'Tracking', 'Leading', 'Radius', 'Shadows', 'Breakpoints', 'Easing', 'Animation',
-  ]) {
-    assert.match(LAYOUT_TSX, new RegExp(label), `missing sidebar label: ${label}`);
-  }
-});
-
-test('LAYOUT_TSX reads adhd.config.ts to populate the Components sidebar list', () => {
-  // The sidebar lists tracked components below the token domains — the layout
-  // must read adhd.config.ts at request time to know what to show.
-  assert.match(LAYOUT_TSX, /adhd\.config\.ts/);
-  assert.match(LAYOUT_TSX, /Components/);
-});
-
-test('INDEX_PAGE_TSX is a minimal landing page (sections moved to TOKENS_PAGE_TSX)', () => {
-  // The landing page now just welcomes the user; per-domain renderers live in
-  // the tokens page that the sidebar links to.
-  assert.match(INDEX_PAGE_TSX, /Design System/);
-  assert.match(INDEX_PAGE_TSX, /Pick a token domain|Pick a/);
-});
-
-test('TOKENS_PAGE_TSX reads globals.css to render tokens at request time', () => {
-  assert.match(TOKENS_PAGE_TSX, /globals\.css|cssEntry/);
-  assert.match(TOKENS_PAGE_TSX, /parseTokens/);
-});
-
-test('COMPONENT_PAGE_TSX uses parametric template-string dynamic import', () => {
-  assert.match(COMPONENT_PAGE_TSX, /await\s+import\(`/);
-});
-
-test('COMPONENT_PAGE_TSX reads searchParams for prop toggles', () => {
-  assert.match(COMPONENT_PAGE_TSX, /searchParams/);
-});
-
-test('PROP_TOGGLE_TSX is a client component', () => {
-  // The marker comment is allowed to precede the directive — Next.js strips
-  // leading comments and treats `"use client"` as the first real statement.
-  // Required so the marker-detection contract (Task 8) still applies.
-  const afterMarker = PROP_TOGGLE_TSX.replace(MARKER_COMMENT, '');
-  assert.match(afterMarker, /^["']use client["']/);
-});
-
-test('PROP_TOGGLE_TSX uses router.replace for snappy URL updates', () => {
-  assert.match(PROP_TOGGLE_TSX, /router\.replace/);
-});
-
-test('LAYOUT_TSX renders a DiagnosticBanner that surfaces detected globals.css issues', () => {
-  // The layout's whole reason for reading globals.css is to surface diagnostic issues
-  // pre-emptively. The banner component must be in the template and wired into render.
-  assert.match(LAYOUT_TSX, /DiagnosticBanner/);
-  assert.match(LAYOUT_TSX, /<DiagnosticBanner issues=\{issues\} \/>/);
-});
-
-test('LAYOUT_TSX detection flags missing --color-ring-offset-background on shadcn-like themes', () => {
-  // The detection heuristic should mention the ring-offset-background token explicitly
-  // (the most common shadcn v3-to-v4 migration gap that surfaces on broad dynamic imports).
-  assert.match(LAYOUT_TSX, /--color-ring-offset-background/);
-  assert.match(LAYOUT_TSX, /looksShadcn/);
-});
-
-test('LAYOUT_TSX gracefully handles a missing globals.css (detectIssues returns [])', () => {
-  // detectIssues must return [] when css is null — the layout still needs to render
-  // for projects without globals.css.
-  assert.match(LAYOUT_TSX, /if \(!css\) return issues;/);
-});
-
-test('INDEX_PAGE_TSX has a Troubleshooting section explaining the ENOENT failure mode', () => {
-  assert.match(INDEX_PAGE_TSX, /Troubleshooting/);
-  assert.match(INDEX_PAGE_TSX, /app-build-manifest/);
-  assert.match(INDEX_PAGE_TSX, /broad dynamic import/i);
-});
-
-test('COMPONENT_ERROR_TSX is a client component error boundary', () => {
-  const afterMarker = COMPONENT_ERROR_TSX.replace(MARKER_COMMENT, '');
-  assert.match(afterMarker, /^["']use client["']/);
-  // The error boundary props signature Next.js passes in
-  assert.match(COMPONENT_ERROR_TSX, /error.*reset/);
-  // Re-render mechanism
-  assert.match(COMPONENT_ERROR_TSX, /reset\(\)/);
-});
-
-test('COMPONENT_ERROR_TSX distinguishes the build-manifest ENOENT from other runtime errors', () => {
-  // The boundary inspects the error message and shows a focused note for the
-  // bundler-level ENOENT (which it technically can't recover, but the user
-  // should be told what's happening if it bubbles up).
-  assert.match(COMPONENT_ERROR_TSX, /app-build-manifest/);
-  assert.match(COMPONENT_ERROR_TSX, /isBuildManifestError/);
-});
-
-test('none of the templates contain "ADHD" outside the marker', () => {
-  // The literal filename `adhd.config.ts` is the consumer's own config artifact
-  // (per the install spec) and is not a reference to the ADHD plugin/brand —
-  // it's an unavoidable filename the generated pages must read at runtime.
-  // Strip it before applying the "no ADHD references" rule.
-  for (const [name, content] of Object.entries({ LAYOUT_TSX, INDEX_PAGE_TSX, TOKENS_PAGE_TSX, COMPONENT_PAGE_TSX, COMPONENT_ERROR_TSX, PROP_TOGGLE_TSX })) {
-    const body = content.replace(MARKER_COMMENT, '').replace(/adhd\.config\.ts/g, '');
-    assert.equal(/adhd/i.test(body), false, `${name} must not reference ADHD outside marker`);
-  }
-});
diff --git a/plugins/adhd/lib/install-design-system-docs-route/README.md b/plugins/adhd/lib/setup-design-system-docs-route/README.md
similarity index 51%
rename from plugins/adhd/lib/install-design-system-docs-route/README.md
rename to plugins/adhd/lib/setup-design-system-docs-route/README.md
index 24a96cb..3b69566 100644
--- a/plugins/adhd/lib/install-design-system-docs-route/README.md
+++ b/plugins/adhd/lib/setup-design-system-docs-route/README.md
@@ -1,18 +1,19 @@
-# lib/install-design-system-docs-route
+# lib/setup-design-system-docs-route
 
-Deterministic helpers for `/adhd:install-design-system-docs-route`. The
-skill (at `plugins/adhd/skills/install-design-system-docs-route/SKILL.md`)
+Deterministic helpers for `/adhd:setup-design-system-docs-route`. The
+skill (at `plugins/adhd/skills/setup-design-system-docs-route/SKILL.md`)
 is the orchestrator; this library is the testable engine.
 
 Modules:
 - `token-parser.js` — extract design-system tokens from a globals.css `@theme` block
 - `prop-parser.js` — extract a component's prop interface
 - `slug.js` — component path → URL slug
+- `config-parser.js` — parse `adhd.config.ts` at install time (components + cssEntry)
 - `next-config-patcher.js` — idempotent patch of next.config.{ts,mjs,js}
 - `robots-patcher.js` — idempotent patch of public/robots.txt
-- `route-installer.js` — write the 4 generated files at the target path
-- `templates.js` — page template strings
+- `route-installer.js` — write the seven generated files at the target path, including a per-install `componentMap.tsx` with static imports
+- `templates.js` — page template strings (with substitution placeholders)
 - `cli.js` — orchestrator surface invoked by SKILL.md
 
 See `docs/superpowers/specs/2026-05-11-adhd-install-design-system-docs-route.md`
-for the authoritative spec.
+for the historical spec.
diff --git a/plugins/adhd/lib/install-design-system-docs-route/__fixtures__/avatar.tsx b/plugins/adhd/lib/setup-design-system-docs-route/__fixtures__/avatar.tsx
similarity index 100%
rename from plugins/adhd/lib/install-design-system-docs-route/__fixtures__/avatar.tsx
rename to plugins/adhd/lib/setup-design-system-docs-route/__fixtures__/avatar.tsx
diff --git a/plugins/adhd/lib/install-design-system-docs-route/__fixtures__/globals.css b/plugins/adhd/lib/setup-design-system-docs-route/__fixtures__/globals.css
similarity index 100%
rename from plugins/adhd/lib/install-design-system-docs-route/__fixtures__/globals.css
rename to plugins/adhd/lib/setup-design-system-docs-route/__fixtures__/globals.css
diff --git a/plugins/adhd/lib/install-design-system-docs-route/__tests__/cli.test.js b/plugins/adhd/lib/setup-design-system-docs-route/__tests__/cli.test.js
similarity index 76%
rename from plugins/adhd/lib/install-design-system-docs-route/__tests__/cli.test.js
rename to plugins/adhd/lib/setup-design-system-docs-route/__tests__/cli.test.js
index 1b11092..98c624c 100644
--- a/plugins/adhd/lib/install-design-system-docs-route/__tests__/cli.test.js
+++ b/plugins/adhd/lib/setup-design-system-docs-route/__tests__/cli.test.js
@@ -94,13 +94,39 @@ test('detect-install subcommand prints existing install paths to stdout', () =>
   assert.match(r.stdout, /-docs\/layout\.tsx/);
 });
 
-test('install subcommand writes files based on choices JSON', () => {
+test('install subcommand reads adhd.config.ts and generates componentMap.tsx', () => {
   const root = fs.mkdtempSync(path.join(os.tmpdir(), 'adhd-ids-install-'));
   fs.mkdirSync(path.join(root, 'app'), { recursive: true });
+  // The new architecture requires adhd.config.ts at the project root — the CLI
+  // reads components + cssEntry from it and bakes them into the generated files.
+  fs.writeFileSync(path.join(root, 'adhd.config.ts'), `
+const config = {
+  components: {
+    "components/Logo.tsx": { figma: {} },
+  },
+};
+export default config;
+`);
   const choices = tmp('choices.json', JSON.stringify({
     projectRoot: root, groupName: '(design-system)', routeSegment: '-docs', prodExcluded: true,
   }));
   const r = spawnSync('node', [CLI, 'install', '--config', choices], { encoding: 'utf8' });
   assert.equal(r.status, 0, r.stderr);
-  assert.ok(fs.existsSync(path.join(root, 'app', '(design-system)', '-docs', 'page.design-system.tsx')));
+  const docsDir = path.join(root, 'app', '(design-system)', '-docs');
+  assert.ok(fs.existsSync(path.join(docsDir, 'page.design-system.tsx')));
+  assert.ok(fs.existsSync(path.join(docsDir, 'componentMap.tsx')));
+  const mapBody = fs.readFileSync(path.join(docsDir, 'componentMap.tsx'), 'utf8');
+  assert.match(mapBody, /import \* as \$cmp0 from "@\/components\/Logo"/);
+  assert.match(mapBody, /slug: "logo"/);
+});
+
+test('install subcommand aborts with a clear error when adhd.config.ts is missing', () => {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'adhd-ids-install-no-config-'));
+  fs.mkdirSync(path.join(root, 'app'), { recursive: true });
+  const choices = tmp('choices.json', JSON.stringify({
+    projectRoot: root, groupName: '(design-system)', routeSegment: '-docs', prodExcluded: true,
+  }));
+  const r = spawnSync('node', [CLI, 'install', '--config', choices], { encoding: 'utf8' });
+  assert.equal(r.status, 2);
+  assert.match(r.stderr, /adhd\.config\.ts/);
 });
diff --git a/plugins/adhd/lib/setup-design-system-docs-route/__tests__/config-parser.test.js b/plugins/adhd/lib/setup-design-system-docs-route/__tests__/config-parser.test.js
new file mode 100644
index 0000000..eb44025
--- /dev/null
+++ b/plugins/adhd/lib/setup-design-system-docs-route/__tests__/config-parser.test.js
@@ -0,0 +1,93 @@
+'use strict';
+
+const test = require('node:test');
+const assert = require('node:assert/strict');
+const fs = require('node:fs');
+const path = require('node:path');
+const os = require('node:os');
+const {
+  readConfig,
+  parseComponents,
+  parseCssEntry,
+  slugFor,
+  importPathFor,
+} = require('../config-parser');
+
+function makeProject(configBody) {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'adhd-cfg-'));
+  fs.writeFileSync(path.join(root, 'adhd.config.ts'), configBody);
+  return root;
+}
+
+test('parseComponents extracts the keys of the components map', () => {
+  const src = `
+const config = {
+  components: {
+    "components/design-system/logo/index.tsx": { figma: {} },
+    "src/components/Button.tsx": { figma: {} },
+  },
+};
+export default config;
+`;
+  const paths = parseComponents(src);
+  assert.deepEqual(paths, [
+    'components/design-system/logo/index.tsx',
+    'src/components/Button.tsx',
+  ]);
+});
+
+test('parseComponents returns [] when no components map is defined', () => {
+  assert.deepEqual(parseComponents('const config = { figma: { url: "x" } };'), []);
+});
+
+test('parseCssEntry returns the configured cssEntry, defaulting to app/globals.css', () => {
+  assert.equal(parseCssEntry('const config = { cssEntry: "src/app/globals.css" };'), 'src/app/globals.css');
+  assert.equal(parseCssEntry('const config = {};'), 'app/globals.css');
+});
+
+test('slugFor strips .tsx/.ts and /index, lowercasing the last segment', () => {
+  assert.equal(slugFor('components/design-system/logo/index.tsx'), 'logo');
+  assert.equal(slugFor('src/components/Button.tsx'), 'button');
+  assert.equal(slugFor('app/widgets/PrimaryNav.ts'), 'primarynav');
+});
+
+test('importPathFor prepends @/ and strips .tsx/.ts and /index', () => {
+  assert.equal(importPathFor('components/design-system/logo/index.tsx'), '@/components/design-system/logo');
+  assert.equal(importPathFor('src/components/Button.tsx'), '@/src/components/Button');
+});
+
+test('readConfig returns components + cssEntry derived from adhd.config.ts', () => {
+  const root = makeProject(`
+const config = {
+  components: {
+    "components/design-system/logo/index.tsx": { figma: { url: "x" } },
+  },
+  cssEntry: "app/globals.css",
+};
+export default config;
+`);
+  const r = readConfig(root);
+  assert.deepEqual(r.components, [{
+    slug: 'logo',
+    rawPath: 'components/design-system/logo/index.tsx',
+    importPath: '@/components/design-system/logo',
+  }]);
+  assert.equal(r.cssEntry, 'app/globals.css');
+});
+
+test('readConfig throws if adhd.config.ts is missing', () => {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'adhd-cfg-missing-'));
+  assert.throws(() => readConfig(root), /ENOENT|no such file/);
+});
+
+test('readConfig handles an empty components map cleanly', () => {
+  const root = makeProject(`
+const config = {
+  components: {},
+};
+export default config;
+`);
+  const r = readConfig(root);
+  assert.deepEqual(r.components, []);
+  assert.equal(r.cssEntry, 'app/globals.css');
+});
diff --git a/plugins/adhd/lib/install-design-system-docs-route/__tests__/next-config-patcher.test.js b/plugins/adhd/lib/setup-design-system-docs-route/__tests__/next-config-patcher.test.js
similarity index 100%
rename from plugins/adhd/lib/install-design-system-docs-route/__tests__/next-config-patcher.test.js
rename to plugins/adhd/lib/setup-design-system-docs-route/__tests__/next-config-patcher.test.js
diff --git a/plugins/adhd/lib/install-design-system-docs-route/__tests__/prop-parser.test.js b/plugins/adhd/lib/setup-design-system-docs-route/__tests__/prop-parser.test.js
similarity index 100%
rename from plugins/adhd/lib/install-design-system-docs-route/__tests__/prop-parser.test.js
rename to plugins/adhd/lib/setup-design-system-docs-route/__tests__/prop-parser.test.js
diff --git a/plugins/adhd/lib/install-design-system-docs-route/__tests__/robots-patcher.test.js b/plugins/adhd/lib/setup-design-system-docs-route/__tests__/robots-patcher.test.js
similarity index 100%
rename from plugins/adhd/lib/install-design-system-docs-route/__tests__/robots-patcher.test.js
rename to plugins/adhd/lib/setup-design-system-docs-route/__tests__/robots-patcher.test.js
diff --git a/plugins/adhd/lib/setup-design-system-docs-route/__tests__/route-installer.test.js b/plugins/adhd/lib/setup-design-system-docs-route/__tests__/route-installer.test.js
new file mode 100644
index 0000000..50ac1ba
--- /dev/null
+++ b/plugins/adhd/lib/setup-design-system-docs-route/__tests__/route-installer.test.js
@@ -0,0 +1,330 @@
+'use strict';
+
+const test = require('node:test');
+const assert = require('node:assert/strict');
+const fs = require('node:fs');
+const path = require('node:path');
+const os = require('node:os');
+const { installRoute, detectExistingInstall, renderComponentMap } = require('../route-installer');
+
+function makeTempProject() {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'adhd-setup-'));
+  fs.mkdirSync(path.join(root, 'app'), { recursive: true });
+  return root;
+}
+
+const SAMPLE_COMPONENTS = [
+  { slug: 'logo', rawPath: 'components/design-system/logo/index.tsx', importPath: '@/components/design-system/logo' },
+];
+
+test('installRoute writes the seven generated files with .design-system suffix when prodExcluded', () => {
+  const root = makeTempProject();
+  installRoute(root, {
+    groupName: '(design-system)',
+    routeSegment: '-docs',
+    prodExcluded: true,
+    components: SAMPLE_COMPONENTS,
+    cssEntry: 'app/globals.css',
+  });
+  const docsDir = path.join(root, 'app', '(design-system)', '-docs');
+  // Route files get the suffix so pageExtensions filters them in prod.
+  assert.ok(fs.existsSync(path.join(docsDir, 'layout.design-system.tsx')));
+  assert.ok(fs.existsSync(path.join(docsDir, 'page.design-system.tsx')));
+  assert.ok(fs.existsSync(path.join(docsDir, 'tokens', '[domain]', 'page.design-system.tsx')));
+  assert.ok(fs.existsSync(path.join(docsDir, 'components', '[component]', 'page.design-system.tsx')));
+  assert.ok(fs.existsSync(path.join(docsDir, 'components', '[component]', 'error.design-system.tsx')));
+  // componentMap + PropToggle are plain .tsx modules so TS module resolution finds them.
+  assert.ok(fs.existsSync(path.join(docsDir, 'componentMap.tsx')));
+  assert.ok(fs.existsSync(path.join(docsDir, 'PropToggle.tsx')));
+  assert.ok(!fs.existsSync(path.join(docsDir, 'componentMap.design-system.tsx')));
+  assert.ok(!fs.existsSync(path.join(docsDir, 'PropToggle.design-system.tsx')));
+});
+
+test('installRoute writes plain .tsx files for route files when not prodExcluded', () => {
+  const root = makeTempProject();
+  installRoute(root, {
+    groupName: '(design-system)',
+    routeSegment: '-docs',
+    prodExcluded: false,
+    components: SAMPLE_COMPONENTS,
+    cssEntry: 'app/globals.css',
+  });
+  const docsDir = path.join(root, 'app', '(design-system)', '-docs');
+  assert.ok(fs.existsSync(path.join(docsDir, 'layout.tsx')));
+  assert.ok(fs.existsSync(path.join(docsDir, 'page.tsx')));
+  assert.ok(fs.existsSync(path.join(docsDir, 'tokens', '[domain]', 'page.tsx')));
+  assert.ok(fs.existsSync(path.join(docsDir, 'components', '[component]', 'page.tsx')));
+  assert.ok(fs.existsSync(path.join(docsDir, 'components', '[component]', 'error.tsx')));
+  assert.ok(fs.existsSync(path.join(docsDir, 'componentMap.tsx')));
+  assert.ok(fs.existsSync(path.join(docsDir, 'PropToggle.tsx')));
+});
+
+test('all written files start with the marker comment', () => {
+  const root = makeTempProject();
+  installRoute(root, {
+    groupName: '(design-system)',
+    routeSegment: '-docs',
+    prodExcluded: true,
+    components: SAMPLE_COMPONENTS,
+    cssEntry: 'app/globals.css',
+  });
+  const docsDir = path.join(root, 'app', '(design-system)', '-docs');
+  for (const f of [
+    'layout.design-system.tsx',
+    'page.design-system.tsx',
+    'tokens/[domain]/page.design-system.tsx',
+    'components/[component]/page.design-system.tsx',
+    'components/[component]/error.design-system.tsx',
+    'componentMap.tsx',
+    'PropToggle.tsx',
+  ]) {
+    const content = fs.readFileSync(path.join(docsDir, f), 'utf8');
+    assert.match(content, /design-system-docs-route/, `${f} missing marker`);
+  }
+});
+
+test('componentMap.tsx has explicit static imports per registered component', () => {
+  const root = makeTempProject();
+  installRoute(root, {
+    groupName: '(design-system)',
+    routeSegment: '-docs',
+    prodExcluded: true,
+    components: SAMPLE_COMPONENTS,
+    cssEntry: 'app/globals.css',
+  });
+  const mapPath = path.join(root, 'app', '(design-system)', '-docs', 'componentMap.tsx');
+  const body = fs.readFileSync(mapPath, 'utf8');
+  // Explicit import for the logo component
+  assert.match(body, /import \* as \$cmp0 from "@\/components\/design-system\/logo"/);
+  // Entry with matching slug and rawPath
+  assert.match(body, /slug: "logo"/);
+  assert.match(body, /rawPath: "components\/design-system\/logo\/index\.tsx"/);
+  assert.match(body, /module: \$cmp0/);
+  // No dynamic import — that's the whole point of this rewrite
+  assert.doesNotMatch(body, /await\s+import\(`/);
+});
+
+test('componentMap.tsx handles an empty components list (no tracked components yet)', () => {
+  const root = makeTempProject();
+  installRoute(root, {
+    groupName: '(design-system)',
+    routeSegment: '-docs',
+    prodExcluded: true,
+    components: [],
+    cssEntry: 'app/globals.css',
+  });
+  const body = fs.readFileSync(
+    path.join(root, 'app', '(design-system)', '-docs', 'componentMap.tsx'),
+    'utf8',
+  );
+  // No import lines for components — placeholder substituted with empty string
+  assert.doesNotMatch(body, /import \* as \$cmp/);
+  // ENTRIES is an empty array literal
+  assert.match(body, /const ENTRIES.*=\s*\[\]/);
+});
+
+test('componentMap.tsx renders multiple components with distinct import bindings', () => {
+  const root = makeTempProject();
+  installRoute(root, {
+    groupName: '(design-system)',
+    routeSegment: '-docs',
+    prodExcluded: true,
+    components: [
+      { slug: 'logo', rawPath: 'src/components/Logo.tsx', importPath: '@/src/components/Logo' },
+      { slug: 'button', rawPath: 'src/components/Button/index.tsx', importPath: '@/src/components/Button' },
+    ],
+    cssEntry: 'app/globals.css',
+  });
+  const body = fs.readFileSync(
+    path.join(root, 'app', '(design-system)', '-docs', 'componentMap.tsx'),
+    'utf8',
+  );
+  assert.match(body, /import \* as \$cmp0 from "@\/src\/components\/Logo"/);
+  assert.match(body, /import \* as \$cmp1 from "@\/src\/components\/Button"/);
+  assert.match(body, /slug: "logo".*module: \$cmp0/s);
+  assert.match(body, /slug: "button".*module: \$cmp1/s);
+});
+
+test('layout sidebar links use absolute hrefs derived from the route segment', () => {
+  const root = makeTempProject();
+  installRoute(root, {
+    groupName: '(design-system)',
+    routeSegment: '-docs',
+    prodExcluded: true,
+    components: SAMPLE_COMPONENTS,
+    cssEntry: 'app/globals.css',
+  });
+  const layout = fs.readFileSync(
+    path.join(root, 'app', '(design-system)', '-docs', 'layout.design-system.tsx'),
+    'utf8',
+  );
+  assert.match(layout, /href=\{`\/-docs\/tokens\/\$\{d\.slug\}`\}/);
+  assert.match(layout, /href=\{`\/-docs\/components\/\$\{c\.slug\}`\}/);
+  assert.doesNotMatch(layout, /__ROUTE_PATH__/);
+});
+
+test('layout imports componentEntries from componentMap (the sidebar list source)', () => {
+  const root = makeTempProject();
+  installRoute(root, {
+    groupName: '(design-system)',
+    routeSegment: '-docs',
+    prodExcluded: true,
+    components: SAMPLE_COMPONENTS,
+    cssEntry: 'app/globals.css',
+  });
+  const layout = fs.readFileSync(
+    path.join(root, 'app', '(design-system)', '-docs', 'layout.design-system.tsx'),
+    'utf8',
+  );
+  assert.match(layout, /from "\.\/componentMap"/);
+  assert.match(layout, /componentEntries/);
+  // No fs/path imports — the components list is baked at install time so the
+  // layout doesn't need to read adhd.config.ts at request time.
+  assert.doesNotMatch(layout, /from "node:fs|from "node:path/);
+});
+
+test('tokens page bakes the configured cssEntry path as a constant', () => {
+  const root = makeTempProject();
+  installRoute(root, {
+    groupName: '(design-system)',
+    routeSegment: '-docs',
+    prodExcluded: true,
+    components: SAMPLE_COMPONENTS,
+    cssEntry: 'src/app/globals.css',
+  });
+  const tokensPage = fs.readFileSync(
+    path.join(root, 'app', '(design-system)', '-docs', 'tokens', '[domain]', 'page.design-system.tsx'),
+    'utf8',
+  );
+  assert.match(tokensPage, /CSS_ENTRY = "src\/app\/globals\.css"/);
+  // No runtime read of adhd.config.ts
+  assert.doesNotMatch(tokensPage, /adhd\.config\.ts/);
+});
+
+test('component page imports getComponent from componentMap, not a dynamic import', () => {
+  const root = makeTempProject();
+  installRoute(root, {
+    groupName: '(design-system)',
+    routeSegment: '-docs',
+    prodExcluded: true,
+    components: SAMPLE_COMPONENTS,
+    cssEntry: 'app/globals.css',
+  });
+  const componentPage = fs.readFileSync(
+    path.join(root, 'app', '(design-system)', '-docs', 'components', '[component]', 'page.design-system.tsx'),
+    'utf8',
+  );
+  assert.match(componentPage, /import \{ getComponent \} from "\.\.\/\.\.\/componentMap"/);
+  assert.match(componentPage, /import \{ PropToggle \} from "\.\.\/\.\.\/PropToggle"/);
+  // No broad dynamic import — that's what the rewrite eliminates
+  assert.doesNotMatch(componentPage, /await\s+import\(`@\//);
+});
+
+test('component page shows a "not in static map" message when slug is missing', () => {
+  // This is the new UX for "user added to adhd.config.ts but didn't re-run setup."
+  const root = makeTempProject();
+  installRoute(root, {
+    groupName: '(design-system)',
+    routeSegment: '-docs',
+    prodExcluded: true,
+    components: SAMPLE_COMPONENTS,
+    cssEntry: 'app/globals.css',
+  });
+  const componentPage = fs.readFileSync(
+    path.join(root, 'app', '(design-system)', '-docs', 'components', '[component]', 'page.design-system.tsx'),
+    'utf8',
+  );
+  assert.match(componentPage, /Not in the static map/);
+  assert.match(componentPage, /\/adhd:setup-design-system-docs-route/);
+});
+
+test('detectExistingInstall returns marker-bearing files', () => {
+  const root = makeTempProject();
+  installRoute(root, {
+    groupName: '(design-system)',
+    routeSegment: '-docs',
+    prodExcluded: true,
+    components: SAMPLE_COMPONENTS,
+    cssEntry: 'app/globals.css',
+  });
+  const found = detectExistingInstall(root);
+  assert.ok(found.length >= 7);
+  assert.ok(found.every(p => p.includes('-docs')));
+});
+
+test('detectExistingInstall returns [] when no marker is present', () => {
+  const root = makeTempProject();
+  assert.deepEqual(detectExistingInstall(root), []);
+});
+
+test('re-running installRoute overwrites files cleanly', () => {
+  const root = makeTempProject();
+  installRoute(root, {
+    groupName: '(design-system)', routeSegment: '-docs', prodExcluded: true,
+    components: SAMPLE_COMPONENTS, cssEntry: 'app/globals.css',
+  });
+  const layoutPath = path.join(root, 'app', '(design-system)', '-docs', 'layout.design-system.tsx');
+  fs.writeFileSync(layoutPath, 'corrupted');
+  installRoute(root, {
+    groupName: '(design-system)', routeSegment: '-docs', prodExcluded: true,
+    components: SAMPLE_COMPONENTS, cssEntry: 'app/globals.css',
+  });
+  const after = fs.readFileSync(layoutPath, 'utf8');
+  assert.match(after, /design-system-docs-route/);
+  assert.match(after, /DesignSystemDocsLayout/);
+});
+
+test('installRoute removes stale marker-bearing files from a previous layout', () => {
+  // Simulate an older install where the dynamic-import-era component page
+  // lived at `[component]/page` directly under docsDir.
+  const root = makeTempProject();
+  const docsDir = path.join(root, 'app', '(design-system)', '-docs');
+  const oldCompDir = path.join(docsDir, '[component]');
+  fs.mkdirSync(oldCompDir, { recursive: true });
+  const oldPath = path.join(oldCompDir, 'page.design-system.tsx');
+  fs.writeFileSync(oldPath, '// design-system-docs-route — stale\nexport {};\n');
+
+  const r = installRoute(root, {
+    groupName: '(design-system)', routeSegment: '-docs', prodExcluded: true,
+    components: SAMPLE_COMPONENTS, cssEntry: 'app/globals.css',
+  });
+
+  assert.ok(!fs.existsSync(oldPath));
+  assert.ok(r.removed.includes(oldPath));
+  assert.ok(!fs.existsSync(oldCompDir));
+});
+
+test('installRoute preserves user files that lack the marker', () => {
+  const root = makeTempProject();
+  const docsDir = path.join(root, 'app', '(design-system)', '-docs');
+  fs.mkdirSync(docsDir, { recursive: true });
+  const userFile = path.join(docsDir, 'user-notes.tsx');
+  fs.writeFileSync(userFile, '// user wrote this\nexport const NOTE = "keep";\n');
+
+  installRoute(root, {
+    groupName: '(design-system)', routeSegment: '-docs', prodExcluded: true,
+    components: SAMPLE_COMPONENTS, cssEntry: 'app/globals.css',
+  });
+
+  assert.ok(fs.existsSync(userFile));
+});
+
+test('installRoute supports an empty groupName (no route group)', () => {
+  const root = makeTempProject();
+  installRoute(root, {
+    groupName: '', routeSegment: '-docs', prodExcluded: true,
+    components: SAMPLE_COMPONENTS, cssEntry: 'app/globals.css',
+  });
+  const docsDir = path.join(root, 'app', '-docs');
+  assert.ok(fs.existsSync(path.join(docsDir, 'layout.design-system.tsx')));
+  assert.ok(fs.existsSync(path.join(docsDir, 'componentMap.tsx')));
+});
+
+test('renderComponentMap is exposed (standalone snapshot of the map source)', () => {
+  const body = renderComponentMap([
+    { slug: 'logo', rawPath: 'components/Logo.tsx', importPath: '@/components/Logo' },
+  ]);
+  assert.match(body, /design-system-docs-route/);
+  assert.match(body, /import \* as \$cmp0 from "@\/components\/Logo"/);
+  assert.match(body, /slug: "logo"/);
+});
diff --git a/plugins/adhd/lib/install-design-system-docs-route/__tests__/slug.test.js b/plugins/adhd/lib/setup-design-system-docs-route/__tests__/slug.test.js
similarity index 100%
rename from plugins/adhd/lib/install-design-system-docs-route/__tests__/slug.test.js
rename to plugins/adhd/lib/setup-design-system-docs-route/__tests__/slug.test.js
diff --git a/plugins/adhd/lib/setup-design-system-docs-route/__tests__/templates.test.js b/plugins/adhd/lib/setup-design-system-docs-route/__tests__/templates.test.js
new file mode 100644
index 0000000..4b39ca3
--- /dev/null
+++ b/plugins/adhd/lib/setup-design-system-docs-route/__tests__/templates.test.js
@@ -0,0 +1,151 @@
+'use strict';
+
+const test = require('node:test');
+const assert = require('node:assert/strict');
+const {
+  MARKER_COMMENT,
+  LAYOUT_TSX,
+  INDEX_PAGE_TSX,
+  TOKENS_PAGE_TSX,
+  COMPONENT_PAGE_TSX,
+  COMPONENT_ERROR_TSX,
+  COMPONENT_MAP_TSX,
+  PROP_TOGGLE_TSX,
+} = require('../templates');
+
+test('MARKER_COMMENT is a stable, non-ADHD-referencing string', () => {
+  assert.match(MARKER_COMMENT, /design-system-docs-route/);
+  assert.match(MARKER_COMMENT, /auto-generated installer artifact; safe to edit/);
+  assert.equal(/adhd/i.test(MARKER_COMMENT), false, 'must not reference ADHD');
+});
+
+test('LAYOUT_TSX starts with the marker comment', () => {
+  assert.ok(LAYOUT_TSX.startsWith(MARKER_COMMENT));
+});
+
+test('LAYOUT_TSX sets robots: noindex / nofollow', () => {
+  assert.match(LAYOUT_TSX, /robots:\s*\{[^}]*index:\s*false[^}]*follow:\s*false/);
+});
+
+test('LAYOUT_TSX renders sidebar nav linking every token domain', () => {
+  for (const label of [
+    'Colors', 'Spacing', 'Typography', 'Font Families', 'Font Weights',
+    'Tracking', 'Leading', 'Radius', 'Shadows', 'Breakpoints', 'Easing', 'Animation',
+  ]) {
+    assert.match(LAYOUT_TSX, new RegExp(label), `missing sidebar label: ${label}`);
+  }
+});
+
+test('LAYOUT_TSX imports componentEntries from componentMap (no runtime config read)', () => {
+  // Static architecture: the layout doesn't read adhd.config.ts at request time.
+  // Instead, the installer generates componentMap.tsx with the components baked in,
+  // and the layout imports componentEntries from it.
+  assert.match(LAYOUT_TSX, /from "\.\/componentMap"/);
+  assert.match(LAYOUT_TSX, /componentEntries/);
+  // No fs/path imports — the layout is a pure render now
+  assert.doesNotMatch(LAYOUT_TSX, /from "node:fs|from "node:path|readConfig\(/);
+});
+
+test('LAYOUT_TSX is a sync (non-async) server component now', () => {
+  // No fs reads anywhere in the layout; it's a pure render.
+  assert.doesNotMatch(LAYOUT_TSX, /export default async function/);
+  assert.match(LAYOUT_TSX, /export default function DesignSystemDocsLayout/);
+});
+
+test('LAYOUT_TSX has no diagnostic banner (removed with the dynamic-import architecture)', () => {
+  // The DiagnosticBanner existed to flag missing tokens that surfaced under the
+  // broad dynamic import. Static imports eliminate that failure mode entirely.
+  assert.doesNotMatch(LAYOUT_TSX, /DiagnosticBanner|detectIssues|ring-offset-background/);
+});
+
+test('INDEX_PAGE_TSX is a landing page describing the static-import flow', () => {
+  assert.match(INDEX_PAGE_TSX, /Design System/);
+  assert.match(INDEX_PAGE_TSX, /statically imported/);
+  assert.match(INDEX_PAGE_TSX, /re-run/);
+});
+
+test('INDEX_PAGE_TSX has a Troubleshooting section keyed to the new failure modes', () => {
+  assert.match(INDEX_PAGE_TSX, /Troubleshooting/);
+  assert.match(INDEX_PAGE_TSX, /not in the static map/i);
+  // Old broad-dynamic-import troubleshooting is gone
+  assert.doesNotMatch(INDEX_PAGE_TSX, /app-build-manifest|broad dynamic/i);
+});
+
+test('TOKENS_PAGE_TSX reads globals.css from a baked CSS_ENTRY constant', () => {
+  assert.match(TOKENS_PAGE_TSX, /const CSS_ENTRY = "__CSS_ENTRY__"/);
+  assert.match(TOKENS_PAGE_TSX, /parseTokens/);
+  // Tokens page no longer reads adhd.config.ts at request time
+  assert.doesNotMatch(TOKENS_PAGE_TSX, /readConfig|adhd\.config\.ts/);
+});
+
+test('COMPONENT_PAGE_TSX uses getComponent from the static componentMap (no dynamic import)', () => {
+  assert.match(COMPONENT_PAGE_TSX, /import \{ getComponent \} from "\.\.\/\.\.\/componentMap"/);
+  // No template-literal dynamic import
+  assert.doesNotMatch(COMPONENT_PAGE_TSX, /await\s+import\(`/);
+});
+
+test('COMPONENT_PAGE_TSX reads searchParams for prop toggles', () => {
+  assert.match(COMPONENT_PAGE_TSX, /searchParams/);
+});
+
+test('COMPONENT_PAGE_TSX shows a "Not in the static map" branch for unknown slugs', () => {
+  // Replaces notFound() with an actionable message about re-running setup.
+  assert.match(COMPONENT_PAGE_TSX, /Not in the static map/);
+  assert.match(COMPONENT_PAGE_TSX, /re-run.*\/adhd:setup-design-system-docs-route/i);
+});
+
+test('COMPONENT_MAP_TSX has the substitution placeholders the installer needs', () => {
+  // The template is a per-install-generated file. These placeholders are
+  // filled in by route-installer.js's renderComponentMap.
+  assert.match(COMPONENT_MAP_TSX, /__COMPONENT_IMPORTS__/);
+  assert.match(COMPONENT_MAP_TSX, /__COMPONENT_ENTRIES__/);
+  assert.match(COMPONENT_MAP_TSX, /export function getComponent/);
+  assert.match(COMPONENT_MAP_TSX, /export const componentEntries/);
+});
+
+test('COMPONENT_MAP_TSX resolves a renderable function via default-then-named fallback', () => {
+  // Mirrors the runtime behavior of the previous dynamic-import resolution:
+  // prefer default export, fall back to first named function. This keeps
+  // existing user components working without changes.
+  assert.match(COMPONENT_MAP_TSX, /function resolveComponent/);
+  assert.match(COMPONENT_MAP_TSX, /mod\.default/);
+});
+
+test('PROP_TOGGLE_TSX is a client component', () => {
+  const afterMarker = PROP_TOGGLE_TSX.replace(MARKER_COMMENT, '');
+  assert.match(afterMarker, /^["']use client["']/);
+});
+
+test('PROP_TOGGLE_TSX uses router.replace for snappy URL updates', () => {
+  assert.match(PROP_TOGGLE_TSX, /router\.replace/);
+});
+
+test('COMPONENT_ERROR_TSX is a client component error boundary', () => {
+  const afterMarker = COMPONENT_ERROR_TSX.replace(MARKER_COMMENT, '');
+  assert.match(afterMarker, /^["']use client["']/);
+  assert.match(COMPONENT_ERROR_TSX, /error.*reset/);
+  assert.match(COMPONENT_ERROR_TSX, /reset\(\)/);
+});
+
+test('COMPONENT_ERROR_TSX no longer has the build-manifest-specific copy', () => {
+  // With static imports, the build-manifest ENOENT failure mode is gone, so
+  // the error boundary no longer needs to special-case it.
+  assert.doesNotMatch(COMPONENT_ERROR_TSX, /app-build-manifest|isBuildManifestError/);
+});
+
+test('none of the templates contain "ADHD" outside the marker', () => {
+  // Two filename-style exceptions are allowed (they're how the user actually
+  // interacts with the tool, and ejecting from ADHD doesn't break the file —
+  // it just means those references become vestigial guidance the user can edit):
+  //   1. `adhd.config.ts` — the consumer's own config artifact.
+  //   2. `/adhd:setup-design-system-docs-route` — the slash command name,
+  //      referenced in troubleshooting copy so the user knows what to re-run.
+  const all = { LAYOUT_TSX, INDEX_PAGE_TSX, TOKENS_PAGE_TSX, COMPONENT_PAGE_TSX, COMPONENT_ERROR_TSX, COMPONENT_MAP_TSX, PROP_TOGGLE_TSX };
+  for (const [name, content] of Object.entries(all)) {
+    const body = content
+      .replace(MARKER_COMMENT, '')
+      .replace(/adhd\.config\.ts/g, '')
+      .replace(/\/adhd:setup-design-system-docs-route/g, '');
+    assert.equal(/adhd/i.test(body), false, `${name} must not reference ADHD outside marker / allowed exceptions`);
+  }
+});
diff --git a/plugins/adhd/lib/install-design-system-docs-route/__tests__/token-parser.test.js b/plugins/adhd/lib/setup-design-system-docs-route/__tests__/token-parser.test.js
similarity index 100%
rename from plugins/adhd/lib/install-design-system-docs-route/__tests__/token-parser.test.js
rename to plugins/adhd/lib/setup-design-system-docs-route/__tests__/token-parser.test.js
diff --git a/plugins/adhd/lib/install-design-system-docs-route/cli.js b/plugins/adhd/lib/setup-design-system-docs-route/cli.js
similarity index 82%
rename from plugins/adhd/lib/install-design-system-docs-route/cli.js
rename to plugins/adhd/lib/setup-design-system-docs-route/cli.js
index 6c15bd9..1fd27c0 100644
--- a/plugins/adhd/lib/install-design-system-docs-route/cli.js
+++ b/plugins/adhd/lib/setup-design-system-docs-route/cli.js
@@ -9,6 +9,7 @@ const { slugMap } = require('./slug');
 const { patchNextConfig } = require('./next-config-patcher');
 const { patchRobots } = require('./robots-patcher');
 const { installRoute, detectExistingInstall } = require('./route-installer');
+const { readConfig } = require('./config-parser');
 
 function parseArgs(argv) {
   const args = { _: [] };
@@ -91,8 +92,22 @@ function main() {
     if (!args.config) { console.error('Usage: install --config <choices.json>'); process.exit(2); }
     const choices = JSON.parse(fs.readFileSync(args.config, 'utf8'));
     if (!choices.projectRoot) { console.error('install: choices.projectRoot is required'); process.exit(2); }
-    const r = installRoute(choices.projectRoot, choices);
-    process.stdout.write(JSON.stringify({ files: r.files }, null, 2) + '\n');
+    // The installer needs the components list + cssEntry from the consumer's
+    // adhd.config.ts. The skill enforces "config exists" in Phase 1, so a
+    // missing file here is a hard error — we abort with a useful message
+    // instead of generating an empty componentMap.
+    let parsed;
+    try { parsed = readConfig(choices.projectRoot); }
+    catch (e) {
+      console.error('install: failed to read adhd.config.ts at ' + choices.projectRoot + ': ' + e.message);
+      process.exit(2);
+    }
+    const r = installRoute(choices.projectRoot, {
+      ...choices,
+      components: parsed.components,
+      cssEntry: parsed.cssEntry,
+    });
+    process.stdout.write(JSON.stringify({ files: r.files, removed: r.removed, components: parsed.components.map(c => c.slug) }, null, 2) + '\n');
     process.exit(0);
   }
 
diff --git a/plugins/adhd/lib/setup-design-system-docs-route/config-parser.js b/plugins/adhd/lib/setup-design-system-docs-route/config-parser.js
new file mode 100644
index 0000000..e840e07
--- /dev/null
+++ b/plugins/adhd/lib/setup-design-system-docs-route/config-parser.js
@@ -0,0 +1,93 @@
+'use strict';
+
+// Parses the consumer's `adhd.config.ts` at install time. Mirrors the inline
+// regex parser that previous template versions ran at request time — but here
+// we parse once at install and bake the result into the generated files,
+// so adding/renaming/removing components requires re-running the installer.
+// That's intentional: the new architecture uses static imports.
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+// Extracts the `components` map keys from the source. Keys are absolute
+// component paths relative to the consumer's project root (matching the
+// shape of `adhd.config.ts`). Uses a brace-counted scan so nested objects
+// (each entry's `{ figma: { url: "..." } }` value) don't confuse the
+// parser — a naïve non-greedy regex would stop at the first `}`.
+function parseComponents(src) {
+  const startMatch = /components:\s*\{/.exec(src);
+  if (!startMatch) return [];
+  const openAt = startMatch.index + startMatch[0].length - 1; // position of the opening `{`
+  let depth = 1;
+  let k = openAt + 1;
+  while (k < src.length && depth > 0) {
+    if (src[k] === '{') depth++;
+    else if (src[k] === '}') depth--;
+    if (depth > 0) k++;
+  }
+  const inner = src.slice(openAt + 1, k);
+  // Only top-level keys: track depth inside the inner block so we don't
+  // pick up keys from nested objects (e.g. `figma: { url: ... }`).
+  const paths = [];
+  let d = 0;
+  let i = 0;
+  while (i < inner.length) {
+    const ch = inner[i];
+    if (ch === '{') { d++; i++; continue; }
+    if (ch === '}') { d--; i++; continue; }
+    if (d === 0 && ch === '"') {
+      // Read the string literal
+      const end = inner.indexOf('"', i + 1);
+      if (end === -1) break;
+      const key = inner.slice(i + 1, end);
+      // Confirm this is a key (followed by `:` after optional whitespace)
+      let j = end + 1;
+      while (j < inner.length && /\s/.test(inner[j])) j++;
+      if (inner[j] === ':') paths.push(key);
+      i = end + 1;
+      continue;
+    }
+    i++;
+  }
+  return paths;
+}
+
+function parseCssEntry(src) {
+  const m = /cssEntry\s*:\s*"([^"]+)"/.exec(src);
+  return m ? m[1] : 'app/globals.css';
+}
+
+// Derive a URL slug from a component path. Mirrors the runtime helper used in
+// previous template versions so existing URL contracts are unchanged.
+//   src/components/Logo/index.tsx → "logo"
+//   app/widgets/Button.tsx        → "button"
+function slugFor(p) {
+  const noExt = p.replace(/\.tsx?$/, '').replace(/\/index$/, '');
+  return noExt.split('/').pop().toLowerCase();
+}
+
+// Compute an import-path string suitable for `import * as X from "@/..."`.
+// Strips the file extension and a trailing `/index` so the bundler picks the
+// directory's index.tsx automatically.
+function importPathFor(p) {
+  return '@/' + p.replace(/\.tsx?$/, '').replace(/\/index$/, '');
+}
+
+// Top-level parser: reads adhd.config.ts at projectRoot, returns the data the
+// installer needs. Throws if the file is missing; the consumer should run
+// `/adhd:config` first.
+function readConfig(projectRoot) {
+  const cfgPath = path.join(projectRoot, 'adhd.config.ts');
+  const src = fs.readFileSync(cfgPath, 'utf8');
+  const components = parseComponents(src).map(rawPath => ({
+    slug: slugFor(rawPath),
+    rawPath,
+    importPath: importPathFor(rawPath),
+  }));
+  return {
+    components,
+    cssEntry: parseCssEntry(src),
+  };
+}
+
+module.exports = { readConfig, parseComponents, parseCssEntry, slugFor, importPathFor };
diff --git a/plugins/adhd/lib/install-design-system-docs-route/next-config-patcher.js b/plugins/adhd/lib/setup-design-system-docs-route/next-config-patcher.js
similarity index 100%
rename from plugins/adhd/lib/install-design-system-docs-route/next-config-patcher.js
rename to plugins/adhd/lib/setup-design-system-docs-route/next-config-patcher.js
diff --git a/plugins/adhd/lib/install-design-system-docs-route/prop-parser.js b/plugins/adhd/lib/setup-design-system-docs-route/prop-parser.js
similarity index 100%
rename from plugins/adhd/lib/install-design-system-docs-route/prop-parser.js
rename to plugins/adhd/lib/setup-design-system-docs-route/prop-parser.js
diff --git a/plugins/adhd/lib/install-design-system-docs-route/robots-patcher.js b/plugins/adhd/lib/setup-design-system-docs-route/robots-patcher.js
similarity index 100%
rename from plugins/adhd/lib/install-design-system-docs-route/robots-patcher.js
rename to plugins/adhd/lib/setup-design-system-docs-route/robots-patcher.js
diff --git a/plugins/adhd/lib/install-design-system-docs-route/route-installer.js b/plugins/adhd/lib/setup-design-system-docs-route/route-installer.js
similarity index 59%
rename from plugins/adhd/lib/install-design-system-docs-route/route-installer.js
rename to plugins/adhd/lib/setup-design-system-docs-route/route-installer.js
index e922dc7..bb61524 100644
--- a/plugins/adhd/lib/install-design-system-docs-route/route-installer.js
+++ b/plugins/adhd/lib/setup-design-system-docs-route/route-installer.js
@@ -8,6 +8,7 @@ const {
   TOKENS_PAGE_TSX,
   COMPONENT_PAGE_TSX,
   COMPONENT_ERROR_TSX,
+  COMPONENT_MAP_TSX,
   PROP_TOGGLE_TSX,
 } = require('./templates');
 
@@ -17,17 +18,37 @@ function mkdirpSync(p) {
   fs.mkdirSync(p, { recursive: true });
 }
 
+// Build the import + entries source for componentMap.tsx from the parsed
+// adhd.config.ts components list. Empty list is fine — the map exports an
+// empty array and the layout's sidebar shows a friendly "none tracked" message.
+function renderComponentMap(components) {
+  const imports = components
+    .map((c, i) => `import * as $cmp${i} from "${c.importPath}";`)
+    .join('\n');
+  const entries = components
+    .map((c, i) => `  { slug: ${JSON.stringify(c.slug)}, rawPath: ${JSON.stringify(c.rawPath)}, module: $cmp${i} },`)
+    .join('\n');
+  return COMPONENT_MAP_TSX
+    .replace('__COMPONENT_IMPORTS__', imports)
+    .replace('__COMPONENT_ENTRIES__', entries.length === 0 ? '[]' : `[\n${entries}\n]`);
+}
+
 function installRoute(projectRoot, opts) {
-  const { groupName = '', routeSegment, prodExcluded } = opts;
+  const {
+    groupName = '',
+    routeSegment,
+    prodExcluded,
+    components = [],
+    cssEntry = 'app/globals.css',
+  } = opts;
   if (!routeSegment) throw new Error('routeSegment is required');
 
-  // Page/layout files get the `.design-system.tsx` extension only when prod-excluded
-  // so Next.js's `pageExtensions` conditional filters them out of production builds.
+  // Page/layout/error files get the `.design-system.tsx` suffix only when
+  // prod-excluded so Next.js's `pageExtensions` filters them out of production
+  // builds. componentMap and PropToggle are regular modules — they're only
+  // bundled when imported by a page that IS suffix-excluded, so plain `.tsx`
+  // is correct (and necessary for standard TS module resolution to find them).
   const pageExt = prodExcluded ? '.design-system.tsx' : '.tsx';
-  // PropToggle is a regular module (not a route file by name), so it doesn't need
-  // the `.design-system` suffix to be excluded — it's only bundled if its importing
-  // page is in the build, and the page IS suffix-excluded. Using a plain `.tsx`
-  // keeps the `import "../../PropToggle"` in COMPONENT_PAGE_TSX resolvable.
   const moduleExt = '.tsx';
   const segments = ['app'];
   if (groupName) segments.push(groupName);
@@ -36,49 +57,40 @@ function installRoute(projectRoot, opts) {
   const tokensDir = path.join(docsDir, 'tokens', '[domain]');
   const componentsDir = path.join(docsDir, 'components', '[component]');
 
-  // The runtime route URL (route groups like `(design-system)` are invisible in URLs,
-  // so the URL is just `/<routeSegment>`). Templates use `__ROUTE_PATH__` as a
-  // placeholder so absolute hrefs in the sidebar/landing resolve correctly.
+  // The runtime URL (route groups like `(design-system)` are invisible in URLs,
+  // so the URL is just `/<routeSegment>`). Templates use `__ROUTE_PATH__` for
+  // absolute hrefs in the sidebar.
   const routeUrl = '/' + routeSegment;
 
-  // Files we're about to write. Anything else with our marker comment under
-  // `docsDir` is leftover from a previous installer version and gets removed
-  // below — that's how re-installs pick up structural changes (e.g. moving
-  // `[component]/` to `components/[component]/`).
   const targets = [
     { abs: path.join(docsDir, `layout${pageExt}`), body: LAYOUT_TSX },
     { abs: path.join(docsDir, `page${pageExt}`), body: INDEX_PAGE_TSX },
     { abs: path.join(tokensDir, `page${pageExt}`), body: TOKENS_PAGE_TSX },
     { abs: path.join(componentsDir, `page${pageExt}`), body: COMPONENT_PAGE_TSX },
-    // error.tsx must be a client component, and Next.js handles it like any
-    // route file — it goes through pageExtensions. The plain `.tsx` variant
-    // is used when prod-exclusion is off (mirrors layout/page).
     { abs: path.join(componentsDir, `error${pageExt}`), body: COMPONENT_ERROR_TSX },
+    { abs: path.join(docsDir, `componentMap${moduleExt}`), body: renderComponentMap(components) },
     { abs: path.join(docsDir, `PropToggle${moduleExt}`), body: PROP_TOGGLE_TSX },
   ];
 
-  // Substitute the `__ROUTE_PATH__` placeholder in every body that needs it
-  // (the layout sidebar links and the landing-page references). It's a no-op
-  // for bodies that don't contain the placeholder.
+  // Per-template placeholder substitution.
   for (const t of targets) {
-    t.body = t.body.replace(/__ROUTE_PATH__/g, routeUrl);
+    t.body = t.body
+      .replace(/__ROUTE_PATH__/g, routeUrl)
+      .replace(/__CSS_ENTRY__/g, cssEntry);
   }
 
-  // Remove old marker-bearing files that aren't in the new target set. This
-  // lets users re-run the installer after structural changes (e.g. older
-  // versions put the component page at `[component]/page.*` directly under
-  // docsDir; new versions put it under `components/[component]/page.*`).
+  // Remove stale marker-bearing files from previous template layouts (e.g. the
+  // old `[component]/page.*` directly under docsDir, or layout.* from a version
+  // before componentMap.tsx existed). Files where the user has deleted the
+  // marker comment are preserved.
   const targetSet = new Set(targets.map(t => t.abs));
   const removed = removeStaleMarkerFiles(docsDir, targetSet);
 
-  // Now write the new files. Directories are created on demand.
   for (const t of targets) {
     mkdirpSync(path.dirname(t.abs));
     fs.writeFileSync(t.abs, t.body);
   }
 
-  // Best-effort cleanup of now-empty directories left behind by removed files
-  // (e.g. the old `app/.../-docs/[component]/` directory).
   pruneEmptyDirs(docsDir);
 
   return {
@@ -87,8 +99,6 @@ function installRoute(projectRoot, opts) {
   };
 }
 
-// Walk `docsDir`, find every `.tsx` file containing the marker comment, and
-// delete the ones that aren't in `keep`. Returns the list of removed paths.
 function removeStaleMarkerFiles(docsDir, keep) {
   const removed = [];
   function walk(dir) {
@@ -113,8 +123,6 @@ function removeStaleMarkerFiles(docsDir, keep) {
   return removed;
 }
 
-// Recursively delete empty directories under (and including) `dir`. Skips `dir`
-// itself if it's non-empty after the recursion.
 function pruneEmptyDirs(dir) {
   let entries;
   try { entries = fs.readdirSync(dir, { withFileTypes: true }); }
@@ -151,4 +159,4 @@ function detectExistingInstall(projectRoot) {
   return found;
 }
 
-module.exports = { installRoute, detectExistingInstall };
+module.exports = { installRoute, detectExistingInstall, renderComponentMap };
diff --git a/plugins/adhd/lib/install-design-system-docs-route/slug.js b/plugins/adhd/lib/setup-design-system-docs-route/slug.js
similarity index 100%
rename from plugins/adhd/lib/install-design-system-docs-route/slug.js
rename to plugins/adhd/lib/setup-design-system-docs-route/slug.js
diff --git a/plugins/adhd/lib/install-design-system-docs-route/templates.js b/plugins/adhd/lib/setup-design-system-docs-route/templates.js
similarity index 67%
rename from plugins/adhd/lib/install-design-system-docs-route/templates.js
rename to plugins/adhd/lib/setup-design-system-docs-route/templates.js
index f957371..09c8ba1 100644
--- a/plugins/adhd/lib/install-design-system-docs-route/templates.js
+++ b/plugins/adhd/lib/setup-design-system-docs-route/templates.js
@@ -5,10 +5,9 @@ const MARKER_COMMENT = `// design-system-docs-route — auto-generated installer
 `;
 
 // The list of token domains is shared verbatim between the sidebar (layout) and
-// the token page (so the page can look up the right renderer by slug). Both
-// copies use the same source string here, embedded into the templates below.
-// The `tailwindDocs` field is the URL to Tailwind v4's relevant theme section,
-// used in empty-state messaging.
+// the tokens page (so the page can look up the right renderer by slug). Both
+// copies embed the same source string from here. The `tailwindDocs` field is
+// the URL to Tailwind v4's relevant theme section, used in empty-state messaging.
 const TOKEN_DOMAINS_SRC = `const TOKEN_DOMAINS = [
   { slug: "colors", label: "Colors", varPrefix: "--color-", tailwindDocs: "https://tailwindcss.com/docs/colors" },
   { slug: "spacing", label: "Spacing", varPrefix: "--spacing", tailwindDocs: "https://tailwindcss.com/docs/theme#spacing" },
@@ -24,12 +23,17 @@ const TOKEN_DOMAINS_SRC = `const TOKEN_DOMAINS = [
   { slug: "animate", label: "Animation", varPrefix: "--animate-", tailwindDocs: "https://tailwindcss.com/docs/animation" },
 ];`;
 
-// The CSS @theme parser shared between landing/tokens pages. Kept inline (not
-// imported from the lib) because these are runtime server components in the
-// consumer's app, with no access to ADHD's node_modules. Mirrors token-parser.js
-// but flattened for inline use.
-//   - Brace-counted scan supports `@theme { ... }` AND `@theme inline { ... }`
-//   - Prefix order matters: longer prefixes (`font-weight-`) before shorter (`font-`).
+// Tokens-page CSS reader. Kept inline because the tokens page is a runtime
+// server component in the consumer's app and can't import ADHD's lib helpers.
+const READ_CSS_SRC = `async function readCss(cssEntry: string) {
+  try { return await fs.readFile(path.resolve(process.cwd(), cssEntry), "utf8"); }
+  catch { return null; }
+}`;
+
+// The CSS @theme parser used by the tokens page. Brace-counted scan correctly
+// handles `@theme { ... }` and `@theme inline { ... }`. Prefix order in
+// PREFIX_MAP matters — longer prefixes (`font-weight-`) must precede shorter
+// ones (`font-`) so classification picks the most-specific match.
 const PARSE_TOKENS_SRC = `function extractThemeBodies(css: string): string[] {
   const bodies: string[] = [];
   let i = 0;
@@ -73,7 +77,6 @@ function parseTokens(css: string | null) {
   if (!css) return out;
   const typoByName = new Map<string, TypoRow>();
   const LINE_HEIGHT_SUFFIX = "--line-height";
-  // Order matters: longer prefixes first.
   const PREFIX_MAP: Array<[string, keyof typeof out]> = [
     ["color-", "colors"],
     ["font-weight-", "fontWeights"],
@@ -115,94 +118,55 @@ function parseTokens(css: string | null) {
   return out;
 }`;
 
-const READ_CONFIG_SRC = `async function readConfig() {
-  try {
-    const src = await fs.readFile(path.resolve(process.cwd(), "adhd.config.ts"), "utf8");
-    const components: string[] = [];
-    const compMatch = /components:\\s*\\{([\\s\\S]*?)\\}\\s*[,;]?/.exec(src);
-    if (compMatch) {
-      const inner = compMatch[1];
-      const re = /"([^"]+)"\\s*:\\s*\\{/g;
-      let m;
-      while ((m = re.exec(inner)) !== null) components.push(m[1]);
-    }
-    const cssEntryMatch = /cssEntry\\s*:\\s*"([^"]+)"/.exec(src);
-    const cssEntry = cssEntryMatch ? cssEntryMatch[1] : "app/globals.css";
-    return { components, cssEntry };
-  } catch {
-    return { components: [] as string[], cssEntry: "app/globals.css" };
+// componentMap.tsx — the heart of the new static architecture. Generated per
+// install from adhd.config.ts. Each tracked component gets an explicit
+// `import * as $cmpN from "@/<path>"` so Webpack/Turbopack resolves a single,
+// known module per component — no context module, no broad bundle, no
+// Tailwind blast radius. To add/rename/remove a component: edit
+// `adhd.config.ts`, then re-run `/adhd:setup-design-system-docs-route`.
+//
+// Placeholders substituted by route-installer.js:
+//   __COMPONENT_IMPORTS__ — one `import * as $cmpN from "<importPath>";` per component
+//   __COMPONENT_ENTRIES__ — array literal of `{ slug, rawPath, module: $cmpN }`
+const COMPONENT_MAP_TSX = `${MARKER_COMMENT}import type React from "react";
+__COMPONENT_IMPORTS__
+
+type ModuleShape = Record<string, unknown>;
+
+// Resolve the renderable function from a module: prefer the default export,
+// fall back to the first exported function. Mirrors the previous runtime
+// resolution behavior so existing user components keep working.
+function resolveComponent(mod: ModuleShape): React.ComponentType<any> | null {
+  if (typeof mod.default === "function") return mod.default as React.ComponentType<any>;
+  for (const v of Object.values(mod)) {
+    if (typeof v === "function") return v as React.ComponentType<any>;
   }
+  return null;
 }
 
-function slugFor(p: string) {
-  return p.replace(/\\.tsx?$/, "").replace(/\\/index$/, "").split("/").pop()?.toLowerCase() ?? p;
-}`;
-
-// Shared globals.css reader. Returns the file contents or null if missing.
-const READ_CSS_SRC = `async function readCss(cssEntry: string) {
-  try { return await fs.readFile(path.resolve(process.cwd(), cssEntry), "utf8"); }
-  catch { return null; }
-}`;
-
-// Diagnostic banner detection: scans the consumer's @theme block for token-name
-// shibboleths that indicate a shadcn-style v3-to-v4 migration, and flags common
-// tokens that are missing. The dynamic-import pattern used by the component page
-// pulls in more files than the consumer's normal routes do, which surfaces stale
-// `@apply` directives in transitively-bundled CSS — these missing tokens are the
-// usual cause.
-const DETECT_ISSUES_SRC = `type DetectedIssue = {
-  token: string;
-  why: string;
-  themeLine: string;
-  rootLine?: string;
+export type ComponentEntry = {
+  slug: string;
+  rawPath: string;
+  Component: React.ComponentType<any> | null;
 };
 
-function detectIssues(css: string | null): DetectedIssue[] {
-  const issues: DetectedIssue[] = [];
-  if (!css) return issues;
-  // Extract bodies of every @theme block (supports \`@theme inline\` modifier).
-  const bodies: string[] = [];
-  let i = 0;
-  while (i < css.length) {
-    const idx = css.indexOf("@theme", i);
-    if (idx === -1) break;
-    let j = idx + "@theme".length;
-    while (j < css.length && css[j] !== "{" && css[j] !== ";") j++;
-    if (css[j] !== "{") { i = j + 1; continue; }
-    let depth = 1, k = j + 1;
-    while (k < css.length && depth > 0) {
-      if (css[k] === "{") depth++;
-      else if (css[k] === "}") depth--;
-      if (depth > 0) k++;
-    }
-    bodies.push(css.slice(j + 1, k));
-    i = k + 1;
-  }
-  const themeText = bodies.join("\\n");
-  const has = (token: string) => new RegExp("(?:^|\\\\s)" + token.replace(/[-]/g, "\\\\-") + "\\\\s*:").test(themeText);
-
-  // Shadcn shibboleth: foreground+background plus at least one *-foreground pair.
-  const looksShadcn = has("--color-foreground") && has("--color-background") &&
-    (has("--color-card-foreground") || has("--color-popover-foreground"));
-
-  if (looksShadcn && !has("--color-ring-offset-background")) {
-    issues.push({
-      token: "--color-ring-offset-background",
-      why: "Shadcn components use \`ring-offset-background\` for focus styles. Without this in @theme, any \`@apply ring-offset-background\` in transitively-bundled CSS (from a UI library or stale components in your project) will fail with \\"Cannot apply unknown utility class ring-offset-background\\" during route compilation, and the component page will 500 with an ENOENT on the build manifest.",
-      themeLine: "--color-ring-offset-background: hsl(var(--ring-offset-background));",
-      rootLine: "--ring-offset-background: 0 0% 100%;",
-    });
-  }
+const ENTRIES: Array<{ slug: string; rawPath: string; module: ModuleShape }> = __COMPONENT_ENTRIES__;
 
-  return issues;
-}`;
+export const componentEntries: Array<{ slug: string; rawPath: string }> =
+  ENTRIES.map(e => ({ slug: e.slug, rawPath: e.rawPath }));
+
+export function getComponent(slug: string): ComponentEntry | null {
+  const entry = ENTRIES.find(e => e.slug === slug);
+  if (!entry) return null;
+  return { slug: entry.slug, rawPath: entry.rawPath, Component: resolveComponent(entry.module) };
+}
+`;
 
-// Layout: sidebar lists token domains + components; main area renders children.
-// The layout is async so it can read adhd.config.ts and globals.css for diagnostics.
+// Layout: sidebar (token domains baked-in, component list baked-in via the
+// generated componentMap). No fs reads, no async — pure server component.
 const LAYOUT_TSX = `${MARKER_COMMENT}import type { Metadata } from "next";
-import fs from "node:fs/promises";
-import path from "node:path";
 import Link from "next/link";
+import { componentEntries } from "./componentMap";
 
 export const metadata: Metadata = {
   title: "Design System Docs",
@@ -211,41 +175,7 @@ export const metadata: Metadata = {
 
 ${TOKEN_DOMAINS_SRC}
 
-${READ_CONFIG_SRC}
-
-${READ_CSS_SRC}
-
-${DETECT_ISSUES_SRC}
-
-function DiagnosticBanner({ issues }: { issues: DetectedIssue[] }) {
-  if (issues.length === 0) return null;
-  return (
-    <aside className="mb-6 rounded-md border border-amber-400 bg-amber-50 dark:border-amber-700 dark:bg-amber-950/30 p-4">
-      <h3 className="text-sm font-medium text-amber-900 dark:text-amber-200">
-        Heads up — likely globals.css gaps
-      </h3>
-      <p className="mt-1 text-xs text-amber-800 dark:text-amber-300 max-w-prose">
-        Component pages use a broad dynamic import which causes Tailwind v4 to scan more of your codebase than your other routes do. Your <code>@theme</code> block looks like a shadcn migration but is missing tokens that often appear in transitively-bundled CSS. If you see <code>ENOENT</code> on <code>app-build-manifest.json</code> when navigating to a component, add these:
-      </p>
-      <ul className="mt-3 flex flex-col gap-3 text-xs">
-        {issues.map(i => (
-          <li key={i.token} className="rounded bg-amber-100 dark:bg-amber-950/50 p-3">
-            <code className="font-medium text-amber-900 dark:text-amber-200">{i.token}</code>
-            <p className="mt-1 text-amber-800 dark:text-amber-300">{i.why}</p>
-            <pre className="mt-2 overflow-x-auto rounded bg-amber-200/60 dark:bg-amber-900/40 p-2 text-[11px] text-amber-900 dark:text-amber-100">{\`/* in @theme */\\n\${i.themeLine}\${i.rootLine ? \`\\n\\n/* in :root */\\n\${i.rootLine}\` : ""}\`}</pre>
-          </li>
-        ))}
-      </ul>
-    </aside>
-  );
-}
-
-export default async function DesignSystemDocsLayout({ children }: { children: React.ReactNode }) {
-  const cfg = await readConfig();
-  const css = await readCss(cfg.cssEntry);
-  const issues = detectIssues(css);
-  const components = cfg.components.map(p => ({ raw: p, slug: slugFor(p) }));
-
+export default function DesignSystemDocsLayout({ children }: { children: React.ReactNode }) {
   return (
     <div className="flex min-h-screen bg-zinc-50 dark:bg-zinc-950 text-zinc-900 dark:text-zinc-100">
       <aside className="w-56 shrink-0 border-r border-zinc-200 dark:border-zinc-800 p-4 sticky top-0 h-screen overflow-y-auto">
@@ -270,12 +200,12 @@ export default async function DesignSystemDocsLayout({ children }: { children: R
 
           <section>
             <h2 className="mb-2 text-[10px] font-medium uppercase tracking-wide text-zinc-500">Components</h2>
-            {components.length === 0 ? (
-              <p className="text-xs text-zinc-500 px-2">None tracked yet.</p>
+            {componentEntries.length === 0 ? (
+              <p className="text-xs text-zinc-500 px-2">None tracked. Add to <code>adhd.config.ts</code> and re-run the setup command.</p>
             ) : (
               <ul className="flex flex-col gap-1">
-                {components.map(c => (
-                  <li key={c.raw}>
+                {componentEntries.map(c => (
+                  <li key={c.slug}>
                     <Link href={\`__ROUTE_PATH__/components/\${c.slug}\`} className="block rounded px-2 py-1 hover:bg-zinc-200 dark:hover:bg-zinc-800">
                       {c.slug}
                     </Link>
@@ -288,29 +218,26 @@ export default async function DesignSystemDocsLayout({ children }: { children: R
       </aside>
 
       <main className="flex-1 p-8 overflow-x-auto">
-        <div className="max-w-5xl">
-          <DiagnosticBanner issues={issues} />
-          {children}
-        </div>
+        <div className="max-w-5xl">{children}</div>
       </main>
     </div>
   );
 }
 `;
 
-// Landing page — welcome + troubleshooting. The sidebar already shows tokens/components,
-// so the body focuses on what the layout's diagnostic banner can't pre-emptively flag.
+// Landing page — welcome + brief troubleshooting. Static. No fs reads.
 const INDEX_PAGE_TSX = `${MARKER_COMMENT}export default function DesignSystemIndex() {
   return (
     <div className="flex flex-col gap-8">
       <header>
         <h2 className="text-2xl font-medium">Design System</h2>
         <p className="mt-2 text-sm text-zinc-600 dark:text-zinc-400 max-w-prose">
-          Pick a token domain or a component from the sidebar. Tokens are read from your
+          Pick a token domain or a component from the sidebar. Tokens are read live from your
           <code className="mx-1 rounded bg-zinc-100 dark:bg-zinc-900 px-1 py-0.5 text-xs">globals.css</code>
-          <code className="rounded bg-zinc-100 dark:bg-zinc-900 px-1 py-0.5 text-xs">@theme</code> blocks.
-          Components are loaded from
-          <code className="ml-1 rounded bg-zinc-100 dark:bg-zinc-900 px-1 py-0.5 text-xs">adhd.config.ts</code>.
+          <code className="rounded bg-zinc-100 dark:bg-zinc-900 px-1 py-0.5 text-xs">@theme</code> blocks. Components are statically imported from <code className="ml-1 rounded bg-zinc-100 dark:bg-zinc-900 px-1 py-0.5 text-xs">adhd.config.ts</code>.
+        </p>
+        <p className="mt-3 text-xs text-zinc-500 max-w-prose">
+          After editing <code>adhd.config.ts</code> (adding, renaming, or removing components), re-run <code>/adhd:setup-design-system-docs-route</code> in this project to regenerate the static component map.
         </p>
       </header>
 
@@ -318,36 +245,23 @@ const INDEX_PAGE_TSX = `${MARKER_COMMENT}export default function DesignSystemInd
         <h3 className="text-sm font-medium uppercase tracking-wide text-zinc-500">Troubleshooting</h3>
         <div className="flex flex-col gap-4 text-sm text-zinc-700 dark:text-zinc-300 max-w-prose">
           <details className="rounded border border-zinc-200 dark:border-zinc-800 p-4">
-            <summary className="cursor-pointer font-medium">Component page 500s with <code>ENOENT: ... app-build-manifest.json</code></summary>
-            <div className="mt-3 flex flex-col gap-3">
-              <p>
-                The component page uses a broad dynamic import keyed off <code>adhd.config.ts</code>, so adding components is just a config edit. The trade-off: Webpack/Turbopack can&apos;t statically resolve the path, so it creates a context module that pulls every file under <code>@/</code> into this route&apos;s bundle, and Tailwind v4 then scans all of them for classes.
-              </p>
-              <p>
-                Your other routes only bundle what they statically import, so latent issues never surface there. On <em>this</em> route, Tailwind hits classes referenced in transitively-bundled CSS (often a UI lib like shadcn or <code>@reactor-team/ui</code>) that your <code>@theme</code> doesn&apos;t define yet. Tailwind throws, the CSS chunk never emits, and the manifest write fails — hence ENOENT.
-              </p>
-              <p className="font-medium">Fix:</p>
-              <ol className="list-decimal pl-5 flex flex-col gap-1">
-                <li>Run <code>npm run dev</code> in a terminal and watch the output when you navigate to <code>/components/&lt;X&gt;</code>.</li>
-                <li>Look for <code>Cannot apply unknown utility class &lt;name&gt;</code> or <code>Cannot use @variant with unknown variant: &lt;name&gt;</code>.</li>
-                <li>For utility class names, add <code>--color-&lt;name&gt;</code> (or appropriate prefix) to your <code>@theme</code> block.</li>
-                <li>For variant names, add <code>--breakpoint-&lt;name&gt;</code> to your <code>@theme</code> block.</li>
-              </ol>
-              <p className="text-xs text-zinc-500">If the layout&apos;s diagnostic banner is showing above this content, it has detected a likely candidate already.</p>
-            </div>
+            <summary className="cursor-pointer font-medium">Component shows in the sidebar but the page says &ldquo;not in the static map&rdquo;</summary>
+            <p className="mt-3">
+              The static map is generated at setup time. If the sidebar lists a component but its page reports it&apos;s not in the map, the layout is out of sync with <code>componentMap.tsx</code>. Re-run <code>/adhd:setup-design-system-docs-route</code>; both files will be regenerated together.
+            </p>
           </details>
 
           <details className="rounded border border-zinc-200 dark:border-zinc-800 p-4">
-            <summary className="cursor-pointer font-medium">Sidebar shows the component but the page fails to load it</summary>
+            <summary className="cursor-pointer font-medium">Component fails to render at runtime</summary>
             <p className="mt-3">
-              Check the path in <code>adhd.config.ts</code> resolves from your project root, and that the file exports a function (default export or a named function). If the dynamic import fails at runtime (not at compile), the error boundary at <code>components/[component]/error.tsx</code> will catch it and show the message.
+              The error boundary at <code>components/[component]/error.tsx</code> will catch it and show the message + a Try Again button. Most often: the component throws on mount without required props, or it expects context (theme provider, router) that the docs route doesn&apos;t provide.
             </p>
           </details>
 
           <details className="rounded border border-zinc-200 dark:border-zinc-800 p-4">
             <summary className="cursor-pointer font-medium">Token domain shows &ldquo;no custom tokens&rdquo; but you have some</summary>
             <p className="mt-3">
-              The parser supports <code>@theme {"{ ... }"}</code> and <code>@theme inline {"{ ... }"}</code>. If your tokens are in a different syntax (e.g. <code>:root</code>), they won&apos;t be picked up — Tailwind v4 only treats <code>@theme</code> declarations as design tokens.
+              The parser supports <code>@theme {"{ ... }"}</code> and <code>@theme inline {"{ ... }"}</code>. If your tokens are in a different syntax (e.g. plain <code>:root</code>), they won&apos;t be picked up — Tailwind v4 only treats <code>@theme</code> declarations as design tokens.
             </p>
           </details>
         </div>
@@ -357,21 +271,20 @@ const INDEX_PAGE_TSX = `${MARKER_COMMENT}export default function DesignSystemInd
 }
 `;
 
-// Tokens domain page — one route, one renderer per domain. Reads the consumer's
-// globals.css at request time and renders whatever's declared. Empty states
-// reference Tailwind v4's defaults rather than implying the system is broken.
+// Tokens domain page — reads globals.css at request time, renders whatever's
+// declared. cssEntry is baked at install time (substituted from adhd.config.ts).
 const TOKENS_PAGE_TSX = `${MARKER_COMMENT}import fs from "node:fs/promises";
 import path from "node:path";
 import { notFound } from "next/navigation";
 
 ${TOKEN_DOMAINS_SRC}
 
-${READ_CONFIG_SRC}
-
 ${READ_CSS_SRC}
 
 ${PARSE_TOKENS_SRC}
 
+const CSS_ENTRY = "__CSS_ENTRY__";
+
 function EmptyState({ domain }: { domain: typeof TOKEN_DOMAINS[number] }) {
   return (
     <div className="rounded border border-dashed border-zinc-300 dark:border-zinc-700 p-6 text-sm text-zinc-600 dark:text-zinc-400">
@@ -386,8 +299,7 @@ export default async function TokensDomainPage({ params }: { params: Promise<{ d
   const domain = TOKEN_DOMAINS.find(d => d.slug === slug);
   if (!domain) notFound();
 
-  const cfg = await readConfig();
-  const css = await readCss(cfg.cssEntry);
+  const css = await readCss(CSS_ENTRY);
   const tokens = parseTokens(css);
 
   return (
@@ -564,14 +476,14 @@ export default async function TokensDomainPage({ params }: { params: Promise<{ d
 }
 `;
 
-// Component page — moved to /components/[component]. Two levels deep, so the
-// PropToggle import is now `../../PropToggle`.
+// Component page — uses the statically generated componentMap. No fs reads of
+// adhd.config.ts at request time; the rawPath comes from the map. The page
+// still reads the component's source via fs to introspect prop interfaces
+// (that's a one-file read per request, not a bundle).
 const COMPONENT_PAGE_TSX = `${MARKER_COMMENT}import fs from "node:fs/promises";
 import path from "node:path";
-import { notFound } from "next/navigation";
 import { PropToggle } from "../../PropToggle";
-
-${READ_CONFIG_SRC}
+import { getComponent } from "../../componentMap";
 
 async function parseProps(componentPath: string) {
   try {
@@ -621,11 +533,24 @@ export default async function ComponentPage({
 }) {
   const { component: slug } = await params;
   const sp = await searchParams;
-  const cfg = await readConfig();
-  const componentPath = cfg.components.find(p => slugFor(p) === slug);
-  if (!componentPath) notFound();
+  const entry = getComponent(slug);
+
+  if (!entry) {
+    return (
+      <div className="rounded border border-amber-300 dark:border-amber-800 bg-amber-50 dark:bg-amber-950/30 p-6">
+        <h2 className="text-lg font-medium text-amber-900 dark:text-amber-200">Not in the static map</h2>
+        <p className="mt-2 text-sm text-amber-800 dark:text-amber-300">
+          The slug <code>{slug}</code> isn&apos;t present in the generated <code>componentMap.tsx</code>.
+        </p>
+        <p className="mt-2 text-sm text-amber-800 dark:text-amber-300">
+          If you just edited <code>adhd.config.ts</code> to add this component, re-run <code>/adhd:setup-design-system-docs-route</code> in this project to regenerate the static imports.
+        </p>
+      </div>
+    );
+  }
 
-  const { props } = await parseProps(componentPath);
+  const { rawPath, Component } = entry;
+  const { props } = await parseProps(rawPath);
 
   // Resolve current prop values from searchParams
   const current: Record<string, any> = {};
@@ -638,19 +563,8 @@ export default async function ComponentPage({
     else if (def.type === "number") current[name] = Number(v);
   }
 
-  // Dynamic import the component
-  let Component: any = null;
-  let importError: string | null = null;
-  try {
-    const mod = await import(\`@/\${componentPath.replace(/\\.tsx?$/, "")}\`);
-    const name = Object.keys(mod).find(k => typeof mod[k] === "function") ?? "default";
-    Component = mod.default ?? mod[name];
-  } catch (e: any) {
-    importError = e?.message ?? String(e);
-  }
-
-  const importPath = "@/" + componentPath.replace(/\\.tsx?$/, "").replace(/\\/index$/, "");
-  const importStmt = Component ? \`import { \${Component.name ?? slug} } from "\${importPath}";\` : null;
+  const importPath = "@/" + rawPath.replace(/\\.tsx?$/, "").replace(/\\/index$/, "");
+  const importStmt = Component ? \`import \${Component.name ?? slug} from "\${importPath}";\` : null;
   const jsxSnippet = Component
     ? \`<\${Component.name ?? slug}\${Object.entries(current).map(([k,v]) => \` \${k}={\${JSON.stringify(v)}}\`).join("")} />\`
     : null;
@@ -690,11 +604,9 @@ export default async function ComponentPage({
       </section>
 
       <section className="rounded border border-zinc-200 dark:border-zinc-800 p-8">
-        {importError ? (
-          <pre className="text-xs text-red-600 whitespace-pre-wrap">{importError}</pre>
-        ) : Component ? (
-          <Component {...current} />
-        ) : null}
+        {Component ? <Component {...current} /> : (
+          <p className="text-sm text-zinc-500">No renderable component exported from <code>{rawPath}</code>. The map imported it but couldn&apos;t resolve a function (default or named).</p>
+        )}
       </section>
 
       {importStmt && jsxSnippet && (
@@ -708,30 +620,25 @@ export default async function ComponentPage({
 }
 `;
 
-// Error boundary for the component route. Catches RUNTIME errors thrown during
-// rendering — broken dynamic imports, components that throw on mount, prop-parse
-// failures. Does NOT catch bundler-level Tailwind/PostCSS failures (those happen
-// before React runs); the layout's diagnostic banner handles that case.
+// Error boundary for the component route. Catches runtime errors thrown during
+// rendering — components that throw on mount, prop-parse failures, etc. With
+// static imports there's no broad-bundle Tailwind blast radius anymore, so this
+// is purely a runtime safety net.
 const COMPONENT_ERROR_TSX = `${MARKER_COMMENT}"use client";
 
 export default function ComponentPageError({ error, reset }: { error: Error & { digest?: string }; reset: () => void }) {
-  const isBuildManifestError = /app-build-manifest\\.json/.test(error.message ?? "");
   return (
     <div className="flex flex-col gap-4">
       <div className="rounded border border-red-300 bg-red-50 dark:border-red-800 dark:bg-red-950/30 p-6">
-        <h2 className="text-lg font-medium text-red-900 dark:text-red-200">Couldn't render this component</h2>
+        <h2 className="text-lg font-medium text-red-900 dark:text-red-200">Couldn&apos;t render this component</h2>
         <p className="mt-2 text-sm text-red-800 dark:text-red-300">
-          {isBuildManifestError
-            ? "Next.js failed to load this route's build manifest. This usually means Tailwind v4 couldn't compile CSS for the route — see the diagnostic banner above (or the Troubleshooting section on the docs landing page) for the likely cause."
-            : "Something went wrong while loading or rendering this component. Common causes:"}
+          Something went wrong while rendering this component. Common causes:
         </p>
-        {!isBuildManifestError && (
-          <ul className="mt-3 list-disc pl-6 text-sm text-red-800 dark:text-red-300">
-            <li>The path in <code>adhd.config.ts</code> doesn't resolve from the project root.</li>
-            <li>The component throws on mount when no props are provided.</li>
-            <li>The component's prop interface uses types the docs route can't introspect.</li>
-          </ul>
-        )}
+        <ul className="mt-3 list-disc pl-6 text-sm text-red-800 dark:text-red-300">
+          <li>The component throws on mount when no props are provided.</li>
+          <li>The component expects context (theme provider, router, query client) that the docs route doesn&apos;t set up.</li>
+          <li>The component&apos;s prop interface uses types the docs route can&apos;t introspect.</li>
+        </ul>
         <details className="mt-4 text-xs">
           <summary className="cursor-pointer text-red-700 dark:text-red-300">Show error details</summary>
           <pre className="mt-2 overflow-x-auto rounded bg-red-100 dark:bg-red-950/50 p-2 text-red-900 dark:text-red-200">{error.message}{error.digest ? \`\\n\\nDigest: \${error.digest}\` : ""}</pre>
@@ -794,5 +701,6 @@ module.exports = {
   TOKENS_PAGE_TSX,
   COMPONENT_PAGE_TSX,
   COMPONENT_ERROR_TSX,
+  COMPONENT_MAP_TSX,
   PROP_TOGGLE_TSX,
 };
diff --git a/plugins/adhd/lib/install-design-system-docs-route/token-parser.js b/plugins/adhd/lib/setup-design-system-docs-route/token-parser.js
similarity index 100%
rename from plugins/adhd/lib/install-design-system-docs-route/token-parser.js
rename to plugins/adhd/lib/setup-design-system-docs-route/token-parser.js
diff --git a/plugins/adhd/skills/config/SKILL.md b/plugins/adhd/skills/config/SKILL.md
index c8fd0fd..1c73e02 100644
--- a/plugins/adhd/skills/config/SKILL.md
+++ b/plugins/adhd/skills/config/SKILL.md
@@ -249,13 +249,13 @@ Options:
   - "No, maybe later"
 ```
 
-On "Yes": execute the phases of `/adhd:install-design-system-docs-route` inline.
-See `plugins/adhd/skills/install-design-system-docs-route/SKILL.md` for the
+On "Yes": execute the phases of `/adhd:setup-design-system-docs-route` inline.
+See `plugins/adhd/skills/setup-design-system-docs-route/SKILL.md` for the
 detailed phase list (validate environment → detect existing install → ask install
 choices → detect Next.js config → detect collisions → patch next.config.ts →
 write files → patch robots.txt → final report).
 
-On "No": print `Run /adhd:install-design-system-docs-route later to set it up.`
+On "No": print `Run /adhd:setup-design-system-docs-route later to set it up.`
 Exit normally.
 
 ## Reference: Common errors and fix-up guidance
diff --git a/plugins/adhd/skills/install-design-system-docs-route/SKILL.md b/plugins/adhd/skills/setup-design-system-docs-route/SKILL.md
similarity index 61%
rename from plugins/adhd/skills/install-design-system-docs-route/SKILL.md
rename to plugins/adhd/skills/setup-design-system-docs-route/SKILL.md
index 98f7efa..ce96404 100644
--- a/plugins/adhd/skills/install-design-system-docs-route/SKILL.md
+++ b/plugins/adhd/skills/setup-design-system-docs-route/SKILL.md
@@ -1,21 +1,22 @@
 ---
-description: "Install a self-generating design-system documentation route into a Next.js consumer app. Sidebar + viewer layout: the sidebar lists every Tailwind v4 token domain (colors, spacing, typography, font, font-weight, tracking, leading, radius, shadows, breakpoints, easing, animation) plus every component tracked in adhd.config.ts; the main pane renders the selected route. All token domains and components are read from globals.css and adhd.config.ts at request time. Component pages introspect props for URL-driven toggles. Optionally excluded from production builds via Next.js pageExtensions trick. Re-runnable: marker-comment detection drives updates, and stale marker-bearing files from older template layouts are cleaned up."
+description: "Generate a design-system documentation route in a Next.js consumer app. Sidebar + viewer layout: sidebar lists every Tailwind v4 token domain (colors, spacing, typography, font, font-weight, tracking, leading, radius, shadows, breakpoints, easing, animation) plus every component tracked in adhd.config.ts; the main pane renders the selected route. Tokens are read from globals.css at request time. Components are statically imported from adhd.config.ts at install time — re-run this command after editing the components map. Component pages introspect props for URL-driven toggles. Optionally excluded from production builds via Next.js pageExtensions trick. Marker-comment detection makes it safe to re-run; stale files from earlier template layouts are cleaned up automatically."
 disable-model-invocation: true
 argument-hint: ""
 allowed-tools: Read Write Edit Bash AskUserQuestion
 ---
 
-# ADHD Install Design System Docs Route
+# ADHD Setup Design System Docs Route
 
-One-shot installer that drops a live design-system docs page into a Next.js App Router project. The page reads `adhd.config.ts` and `globals.css` at request time — no regen needed when components or tokens change. Re-running this skill picks up template improvements over time.
+Generates a design-system docs page in a Next.js App Router project. Tokens are read live from `globals.css`. Components are statically imported from `adhd.config.ts` at the moment this skill runs — **re-run after editing the components map** to regenerate the static imports.
 
-**Authoritative spec:** `docs/superpowers/specs/2026-05-11-adhd-install-design-system-docs-route.md`
+**Authoritative spec:** `docs/superpowers/specs/2026-05-11-adhd-install-design-system-docs-route.md` (historical name).
 
 ## Invariants
 
-1. **No ADHD references in generated files** outside of import paths pointing at `adhd.config.ts`. The marker comment is generic.
-2. **adhd.config.ts is NOT modified** by this skill. Install choices live in the filesystem.
-3. **All file writes are idempotent on re-run.** Marker-bearing files are replaced wholesale with the latest templates. Files where the user deleted the marker are left alone.
+1. **No ADHD references in generated files** outside of two filename-style exceptions: the consumer's `adhd.config.ts` filename, and the slash-command name `/adhd:setup-design-system-docs-route` referenced in troubleshooting copy.
+2. **adhd.config.ts is NOT modified** by this skill. The skill reads it; the user owns it.
+3. **All file writes are idempotent on re-run.** Marker-bearing files are replaced wholesale with the latest templates. Files where the user deleted the marker are left alone. Stale marker-bearing files from earlier template layouts are removed.
+4. **Static component imports.** The installer parses `adhd.config.ts` and generates `componentMap.tsx` with explicit `import * as $cmpN from "@/..."` per registered component. The component page does a static lookup — no dynamic imports, no broad Webpack context modules, no Tailwind-blast-radius issues.
 
 ## Phase 1: Validate consumer environment
 
@@ -30,7 +31,7 @@ Read `package.json` and confirm `next` is in `dependencies` or `devDependencies`
 ## Phase 2: Detect existing install
 
 ```bash
-node plugins/adhd/lib/install-design-system-docs-route/cli.js detect-install --app-dir .
+node plugins/adhd/lib/setup-design-system-docs-route/cli.js detect-install --app-dir .
 ```
 
 Output is newline-separated paths of files containing the marker comment.
@@ -77,7 +78,7 @@ If `EXISTS` and Phase 2 didn't already mark this as an existing install: prompt
 ## Phase 6: Patch next.config.ts (only if prod-exclusion: yes)
 
 ```bash
-node plugins/adhd/lib/install-design-system-docs-route/cli.js patch-next-config \
+node plugins/adhd/lib/setup-design-system-docs-route/cli.js patch-next-config \
   --config "<next.config.path>" \
   --route-url "<routeUrl>"
 ```
@@ -102,7 +103,7 @@ pageExtensions: process.env.NODE_ENV === 'production'
 ## Phase 7: Write the page files
 
 ```bash
-node plugins/adhd/lib/install-design-system-docs-route/cli.js install \
+node plugins/adhd/lib/setup-design-system-docs-route/cli.js install \
   --config <choices.json>
 ```
 
@@ -116,12 +117,14 @@ Where `<choices.json>` is a temp file with shape:
 }
 ```
 
-The CLI prints the list of files it wrote.
+The CLI reads `adhd.config.ts` from `<projectRoot>` to discover the components list and `cssEntry`, bakes them into the generated files (including a per-install `componentMap.tsx` with static imports), and prints the list of files it wrote plus the slugs that ended up in the map.
+
+If `adhd.config.ts` is missing, the CLI aborts with `install: failed to read adhd.config.ts ...`. Phase 1 has already guaranteed it exists, so this only fires if the file vanished between phases — rare, but surface the error verbatim.
 
 ## Phase 8: Patch robots.txt
 
 ```bash
-node plugins/adhd/lib/install-design-system-docs-route/cli.js patch-robots \
+node plugins/adhd/lib/setup-design-system-docs-route/cli.js patch-robots \
   --robots public/robots.txt \
   --route-url "<routeUrl>"
 ```
@@ -135,20 +138,23 @@ mkdir -p public
 
 Print:
 ```
-✓ Design system docs route installed.
+✓ Design system docs route set up.
 
   URL:            http://localhost:3000<routeUrl>
   Filesystem:     app/<group>/<segment>/
   Prod exclusion: <ON | OFF>
   noindex meta:   ON
   robots.txt:     Disallow added
+  Components:     <comma-separated slug list from the install CLI output, or "none">
+
+Run `npm run dev` and visit the URL to preview.
 
-Run `npm run dev` and visit the URL to preview. The page reads adhd.config.ts
-and globals.css at request time — no regen needed when you add components or
-tokens.
+Tokens are read from globals.css at request time, so editing globals.css just
+works. Components are statically imported from adhd.config.ts — after adding,
+renaming, or removing entries in the components map, re-run
+/adhd:setup-design-system-docs-route to regenerate the static imports.
 
-Re-run /adhd:install-design-system-docs-route to pick up improved templates
-over time. Files where you've removed the marker comment will be left alone.
+Files where you've removed the marker comment are left alone.
 ```
 
 ## Common errors

From b7443947fc33bb1f1565abc93c882a6f3cddf96a Mon Sep 17 00:00:00 2001
From: Hugh Francis <hughfrancis89@gmail.com>
Date: Mon, 11 May 2026 18:27:17 -0400
Subject: [PATCH 26/79] setup-design-system-docs-route: extract tokenDomains,
 prune landing page
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Two cleanups noticed on review:

1. TOKEN_DOMAINS was duplicated: the same `const TOKEN_DOMAINS = [...]`
   block was being injected into both layout.tsx and the tokens-page
   template. Extracted to its own per-install `tokenDomains.tsx` module.
   Layout imports `TOKEN_DOMAINS` from `./tokenDomains`; the tokens page
   imports `TOKEN_DOMAINS` and the new `TokenDomain` type from
   `../../tokenDomains`. Adding a new domain is now a one-file edit.

2. Landing page troubleshooting was stale. The first item ("sidebar shows
   component but page says not in static map") was actually impossible
   under the new architecture — the sidebar list IS componentMap, so any
   slug visible in the sidebar is by definition in the map. Pruned the
   whole troubleshooting block: each route already surfaces its own
   failure mode (the component page has the "not in static map" message
   with re-run instructions, error.tsx catches runtime crashes, token
   pages link to Tailwind docs for empty domains). Landing is now just a
   brief orientation paragraph.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 .../__tests__/route-installer.test.js         |  9 +-
 .../__tests__/templates.test.js               | 35 +++++--
 .../route-installer.js                        |  4 +
 .../templates.js                              | 92 ++++++++-----------
 4 files changed, 79 insertions(+), 61 deletions(-)

diff --git a/plugins/adhd/lib/setup-design-system-docs-route/__tests__/route-installer.test.js b/plugins/adhd/lib/setup-design-system-docs-route/__tests__/route-installer.test.js
index 50ac1ba..47f1e1a 100644
--- a/plugins/adhd/lib/setup-design-system-docs-route/__tests__/route-installer.test.js
+++ b/plugins/adhd/lib/setup-design-system-docs-route/__tests__/route-installer.test.js
@@ -17,7 +17,7 @@ const SAMPLE_COMPONENTS = [
   { slug: 'logo', rawPath: 'components/design-system/logo/index.tsx', importPath: '@/components/design-system/logo' },
 ];
 
-test('installRoute writes the seven generated files with .design-system suffix when prodExcluded', () => {
+test('installRoute writes the full generated file set with .design-system suffix when prodExcluded', () => {
   const root = makeTempProject();
   installRoute(root, {
     groupName: '(design-system)',
@@ -33,10 +33,12 @@ test('installRoute writes the seven generated files with .design-system suffix w
   assert.ok(fs.existsSync(path.join(docsDir, 'tokens', '[domain]', 'page.design-system.tsx')));
   assert.ok(fs.existsSync(path.join(docsDir, 'components', '[component]', 'page.design-system.tsx')));
   assert.ok(fs.existsSync(path.join(docsDir, 'components', '[component]', 'error.design-system.tsx')));
-  // componentMap + PropToggle are plain .tsx modules so TS module resolution finds them.
+  // Shared modules (imported by the route files) are plain .tsx so TS resolves them.
   assert.ok(fs.existsSync(path.join(docsDir, 'componentMap.tsx')));
+  assert.ok(fs.existsSync(path.join(docsDir, 'tokenDomains.tsx')));
   assert.ok(fs.existsSync(path.join(docsDir, 'PropToggle.tsx')));
   assert.ok(!fs.existsSync(path.join(docsDir, 'componentMap.design-system.tsx')));
+  assert.ok(!fs.existsSync(path.join(docsDir, 'tokenDomains.design-system.tsx')));
   assert.ok(!fs.existsSync(path.join(docsDir, 'PropToggle.design-system.tsx')));
 });
 
@@ -76,6 +78,7 @@ test('all written files start with the marker comment', () => {
     'components/[component]/page.design-system.tsx',
     'components/[component]/error.design-system.tsx',
     'componentMap.tsx',
+    'tokenDomains.tsx',
     'PropToggle.tsx',
   ]) {
     const content = fs.readFileSync(path.join(docsDir, f), 'utf8');
@@ -248,7 +251,7 @@ test('detectExistingInstall returns marker-bearing files', () => {
     cssEntry: 'app/globals.css',
   });
   const found = detectExistingInstall(root);
-  assert.ok(found.length >= 7);
+  assert.ok(found.length >= 8);
   assert.ok(found.every(p => p.includes('-docs')));
 });
 
diff --git a/plugins/adhd/lib/setup-design-system-docs-route/__tests__/templates.test.js b/plugins/adhd/lib/setup-design-system-docs-route/__tests__/templates.test.js
index 4b39ca3..97590e9 100644
--- a/plugins/adhd/lib/setup-design-system-docs-route/__tests__/templates.test.js
+++ b/plugins/adhd/lib/setup-design-system-docs-route/__tests__/templates.test.js
@@ -10,6 +10,7 @@ const {
   COMPONENT_PAGE_TSX,
   COMPONENT_ERROR_TSX,
   COMPONENT_MAP_TSX,
+  TOKEN_DOMAINS_TSX,
   PROP_TOGGLE_TSX,
 } = require('../templates');
 
@@ -27,13 +28,26 @@ test('LAYOUT_TSX sets robots: noindex / nofollow', () => {
   assert.match(LAYOUT_TSX, /robots:\s*\{[^}]*index:\s*false[^}]*follow:\s*false/);
 });
 
-test('LAYOUT_TSX renders sidebar nav linking every token domain', () => {
+test('LAYOUT_TSX imports the TOKEN_DOMAINS catalog from the shared tokenDomains module', () => {
+  // Single source of truth lives in tokenDomains.tsx; the layout just imports it
+  // and iterates. Inlining the labels here would duplicate the catalog (the
+  // duplication the rewrite was meant to remove).
+  assert.match(LAYOUT_TSX, /import \{ TOKEN_DOMAINS \} from "\.\/tokenDomains"/);
+});
+
+test('TOKEN_DOMAINS_TSX exports the full Tailwind v4 token-domain catalog', () => {
+  // The catalog is THE source of truth — every token domain rendered by the
+  // tokens page must be listed here with its varPrefix and Tailwind docs link.
   for (const label of [
     'Colors', 'Spacing', 'Typography', 'Font Families', 'Font Weights',
     'Tracking', 'Leading', 'Radius', 'Shadows', 'Breakpoints', 'Easing', 'Animation',
   ]) {
-    assert.match(LAYOUT_TSX, new RegExp(label), `missing sidebar label: ${label}`);
+    assert.match(TOKEN_DOMAINS_TSX, new RegExp(`label: "${label}"`), `missing domain label: ${label}`);
   }
+  // Shape: each entry has slug + label + varPrefix + tailwindDocs.
+  assert.match(TOKEN_DOMAINS_TSX, /slug:\s*"colors".*varPrefix:\s*"--color-".*tailwindDocs:/s);
+  assert.match(TOKEN_DOMAINS_TSX, /export const TOKEN_DOMAINS:/);
+  assert.match(TOKEN_DOMAINS_TSX, /export type TokenDomain/);
 });
 
 test('LAYOUT_TSX imports componentEntries from componentMap (no runtime config read)', () => {
@@ -64,11 +78,14 @@ test('INDEX_PAGE_TSX is a landing page describing the static-import flow', () =>
   assert.match(INDEX_PAGE_TSX, /re-run/);
 });
 
-test('INDEX_PAGE_TSX has a Troubleshooting section keyed to the new failure modes', () => {
-  assert.match(INDEX_PAGE_TSX, /Troubleshooting/);
-  assert.match(INDEX_PAGE_TSX, /not in the static map/i);
-  // Old broad-dynamic-import troubleshooting is gone
+test('INDEX_PAGE_TSX has no Troubleshooting section (each route handles its own failure modes)', () => {
+  // The component page surfaces "not in static map" itself; error.tsx catches
+  // runtime crashes; token pages link to Tailwind docs for empty domains.
+  // The landing page just orients the user — no duplicated troubleshooting copy.
+  assert.doesNotMatch(INDEX_PAGE_TSX, /Troubleshooting/);
   assert.doesNotMatch(INDEX_PAGE_TSX, /app-build-manifest|broad dynamic/i);
+  // It still mentions the re-run command so the user knows how to refresh the map.
+  assert.match(INDEX_PAGE_TSX, /\/adhd:setup-design-system-docs-route/);
 });
 
 test('TOKENS_PAGE_TSX reads globals.css from a baked CSS_ENTRY constant', () => {
@@ -78,6 +95,12 @@ test('TOKENS_PAGE_TSX reads globals.css from a baked CSS_ENTRY constant', () =>
   assert.doesNotMatch(TOKENS_PAGE_TSX, /readConfig|adhd\.config\.ts/);
 });
 
+test('TOKENS_PAGE_TSX imports TOKEN_DOMAINS from the shared catalog (no inlined list)', () => {
+  assert.match(TOKENS_PAGE_TSX, /import \{ TOKEN_DOMAINS, type TokenDomain \} from "\.\.\/\.\.\/tokenDomains"/);
+  // The inline `const TOKEN_DOMAINS = [...]` block from earlier versions is gone.
+  assert.doesNotMatch(TOKENS_PAGE_TSX, /const TOKEN_DOMAINS = \[/);
+});
+
 test('COMPONENT_PAGE_TSX uses getComponent from the static componentMap (no dynamic import)', () => {
   assert.match(COMPONENT_PAGE_TSX, /import \{ getComponent \} from "\.\.\/\.\.\/componentMap"/);
   // No template-literal dynamic import
diff --git a/plugins/adhd/lib/setup-design-system-docs-route/route-installer.js b/plugins/adhd/lib/setup-design-system-docs-route/route-installer.js
index bb61524..2133594 100644
--- a/plugins/adhd/lib/setup-design-system-docs-route/route-installer.js
+++ b/plugins/adhd/lib/setup-design-system-docs-route/route-installer.js
@@ -9,6 +9,7 @@ const {
   COMPONENT_PAGE_TSX,
   COMPONENT_ERROR_TSX,
   COMPONENT_MAP_TSX,
+  TOKEN_DOMAINS_TSX,
   PROP_TOGGLE_TSX,
 } = require('./templates');
 
@@ -69,6 +70,9 @@ function installRoute(projectRoot, opts) {
     { abs: path.join(componentsDir, `page${pageExt}`), body: COMPONENT_PAGE_TSX },
     { abs: path.join(componentsDir, `error${pageExt}`), body: COMPONENT_ERROR_TSX },
     { abs: path.join(docsDir, `componentMap${moduleExt}`), body: renderComponentMap(components) },
+    // Shared token-domain catalog: imported by layout (sidebar nav) and the
+    // tokens page (renderer keys + empty-state link targets). One source of truth.
+    { abs: path.join(docsDir, `tokenDomains${moduleExt}`), body: TOKEN_DOMAINS_TSX },
     { abs: path.join(docsDir, `PropToggle${moduleExt}`), body: PROP_TOGGLE_TSX },
   ];
 
diff --git a/plugins/adhd/lib/setup-design-system-docs-route/templates.js b/plugins/adhd/lib/setup-design-system-docs-route/templates.js
index 09c8ba1..573d88d 100644
--- a/plugins/adhd/lib/setup-design-system-docs-route/templates.js
+++ b/plugins/adhd/lib/setup-design-system-docs-route/templates.js
@@ -4,11 +4,19 @@ const MARKER_COMMENT = `// design-system-docs-route — auto-generated installer
 // Remove this comment to disable future overwrites from re-running the installer.
 `;
 
-// The list of token domains is shared verbatim between the sidebar (layout) and
-// the tokens page (so the page can look up the right renderer by slug). Both
-// copies embed the same source string from here. The `tailwindDocs` field is
-// the URL to Tailwind v4's relevant theme section, used in empty-state messaging.
-const TOKEN_DOMAINS_SRC = `const TOKEN_DOMAINS = [
+// tokenDomains.tsx — the single source of truth for the token-domain catalog
+// (sidebar entries + per-domain renderer keys). Generated once per install and
+// imported by both layout.* and tokens/[domain]/page.*. The `tailwindDocs`
+// field is the URL to Tailwind v4's relevant theme section, used in
+// empty-state messaging on each domain page.
+const TOKEN_DOMAINS_TSX = `${MARKER_COMMENT}export type TokenDomain = {
+  slug: string;
+  label: string;
+  varPrefix: string;
+  tailwindDocs: string;
+};
+
+export const TOKEN_DOMAINS: TokenDomain[] = [
   { slug: "colors", label: "Colors", varPrefix: "--color-", tailwindDocs: "https://tailwindcss.com/docs/colors" },
   { slug: "spacing", label: "Spacing", varPrefix: "--spacing", tailwindDocs: "https://tailwindcss.com/docs/theme#spacing" },
   { slug: "typography", label: "Typography", varPrefix: "--text-", tailwindDocs: "https://tailwindcss.com/docs/font-size" },
@@ -21,7 +29,8 @@ const TOKEN_DOMAINS_SRC = `const TOKEN_DOMAINS = [
   { slug: "breakpoint", label: "Breakpoints", varPrefix: "--breakpoint-", tailwindDocs: "https://tailwindcss.com/docs/responsive-design" },
   { slug: "ease", label: "Easing", varPrefix: "--ease-", tailwindDocs: "https://tailwindcss.com/docs/transition-timing-function" },
   { slug: "animate", label: "Animation", varPrefix: "--animate-", tailwindDocs: "https://tailwindcss.com/docs/animation" },
-];`;
+];
+`;
 
 // Tokens-page CSS reader. Kept inline because the tokens page is a runtime
 // server component in the consumer's app and can't import ADHD's lib helpers.
@@ -162,10 +171,11 @@ export function getComponent(slug: string): ComponentEntry | null {
 }
 `;
 
-// Layout: sidebar (token domains baked-in, component list baked-in via the
-// generated componentMap). No fs reads, no async — pure server component.
+// Layout: sidebar links into the token-domain catalog and the static component
+// map. No fs reads, no async — pure server component.
 const LAYOUT_TSX = `${MARKER_COMMENT}import type { Metadata } from "next";
 import Link from "next/link";
+import { TOKEN_DOMAINS } from "./tokenDomains";
 import { componentEntries } from "./componentMap";
 
 export const metadata: Metadata = {
@@ -173,8 +183,6 @@ export const metadata: Metadata = {
   robots: { index: false, follow: false },
 };
 
-${TOKEN_DOMAINS_SRC}
-
 export default function DesignSystemDocsLayout({ children }: { children: React.ReactNode }) {
   return (
     <div className="flex min-h-screen bg-zinc-50 dark:bg-zinc-950 text-zinc-900 dark:text-zinc-100">
@@ -225,47 +233,25 @@ export default function DesignSystemDocsLayout({ children }: { children: React.R
 }
 `;
 
-// Landing page — welcome + brief troubleshooting. Static. No fs reads.
+// Landing page — minimal welcome + a couple of quick notes. The sidebar carries
+// the actual navigation; each domain/component route has its own targeted UI
+// for its own failure modes (the component page surfaces "not in static map",
+// error.tsx catches runtime crashes, token pages link to Tailwind docs for
+// empty domains). Nothing to repeat here.
 const INDEX_PAGE_TSX = `${MARKER_COMMENT}export default function DesignSystemIndex() {
   return (
-    <div className="flex flex-col gap-8">
-      <header>
-        <h2 className="text-2xl font-medium">Design System</h2>
-        <p className="mt-2 text-sm text-zinc-600 dark:text-zinc-400 max-w-prose">
-          Pick a token domain or a component from the sidebar. Tokens are read live from your
-          <code className="mx-1 rounded bg-zinc-100 dark:bg-zinc-900 px-1 py-0.5 text-xs">globals.css</code>
-          <code className="rounded bg-zinc-100 dark:bg-zinc-900 px-1 py-0.5 text-xs">@theme</code> blocks. Components are statically imported from <code className="ml-1 rounded bg-zinc-100 dark:bg-zinc-900 px-1 py-0.5 text-xs">adhd.config.ts</code>.
-        </p>
-        <p className="mt-3 text-xs text-zinc-500 max-w-prose">
-          After editing <code>adhd.config.ts</code> (adding, renaming, or removing components), re-run <code>/adhd:setup-design-system-docs-route</code> in this project to regenerate the static component map.
-        </p>
-      </header>
-
-      <section className="flex flex-col gap-3">
-        <h3 className="text-sm font-medium uppercase tracking-wide text-zinc-500">Troubleshooting</h3>
-        <div className="flex flex-col gap-4 text-sm text-zinc-700 dark:text-zinc-300 max-w-prose">
-          <details className="rounded border border-zinc-200 dark:border-zinc-800 p-4">
-            <summary className="cursor-pointer font-medium">Component shows in the sidebar but the page says &ldquo;not in the static map&rdquo;</summary>
-            <p className="mt-3">
-              The static map is generated at setup time. If the sidebar lists a component but its page reports it&apos;s not in the map, the layout is out of sync with <code>componentMap.tsx</code>. Re-run <code>/adhd:setup-design-system-docs-route</code>; both files will be regenerated together.
-            </p>
-          </details>
-
-          <details className="rounded border border-zinc-200 dark:border-zinc-800 p-4">
-            <summary className="cursor-pointer font-medium">Component fails to render at runtime</summary>
-            <p className="mt-3">
-              The error boundary at <code>components/[component]/error.tsx</code> will catch it and show the message + a Try Again button. Most often: the component throws on mount without required props, or it expects context (theme provider, router) that the docs route doesn&apos;t provide.
-            </p>
-          </details>
-
-          <details className="rounded border border-zinc-200 dark:border-zinc-800 p-4">
-            <summary className="cursor-pointer font-medium">Token domain shows &ldquo;no custom tokens&rdquo; but you have some</summary>
-            <p className="mt-3">
-              The parser supports <code>@theme {"{ ... }"}</code> and <code>@theme inline {"{ ... }"}</code>. If your tokens are in a different syntax (e.g. plain <code>:root</code>), they won&apos;t be picked up — Tailwind v4 only treats <code>@theme</code> declarations as design tokens.
-            </p>
-          </details>
-        </div>
-      </section>
+    <div className="flex flex-col gap-4">
+      <h2 className="text-2xl font-medium">Design System</h2>
+      <p className="text-sm text-zinc-600 dark:text-zinc-400 max-w-prose">
+        Pick a token domain or a component from the sidebar. Tokens are read live from your
+        <code className="mx-1 rounded bg-zinc-100 dark:bg-zinc-900 px-1 py-0.5 text-xs">globals.css</code>
+        <code className="rounded bg-zinc-100 dark:bg-zinc-900 px-1 py-0.5 text-xs">@theme</code> blocks. Components are statically imported from
+        <code className="ml-1 rounded bg-zinc-100 dark:bg-zinc-900 px-1 py-0.5 text-xs">adhd.config.ts</code> — after editing the components map, re-run
+        <code className="ml-1 rounded bg-zinc-100 dark:bg-zinc-900 px-1 py-0.5 text-xs">/adhd:setup-design-system-docs-route</code> to regenerate the static imports.
+      </p>
+      <p className="text-xs text-zinc-500 max-w-prose">
+        Only <code>@theme {"{ ... }"}</code> and <code>@theme inline {"{ ... }"}</code> declarations are picked up — plain <code>:root</code> variables aren&apos;t.
+      </p>
     </div>
   );
 }
@@ -273,11 +259,12 @@ const INDEX_PAGE_TSX = `${MARKER_COMMENT}export default function DesignSystemInd
 
 // Tokens domain page — reads globals.css at request time, renders whatever's
 // declared. cssEntry is baked at install time (substituted from adhd.config.ts).
+// The TOKEN_DOMAINS list is imported from the shared catalog, so adding a new
+// domain only requires editing one file.
 const TOKENS_PAGE_TSX = `${MARKER_COMMENT}import fs from "node:fs/promises";
 import path from "node:path";
 import { notFound } from "next/navigation";
-
-${TOKEN_DOMAINS_SRC}
+import { TOKEN_DOMAINS, type TokenDomain } from "../../tokenDomains";
 
 ${READ_CSS_SRC}
 
@@ -285,7 +272,7 @@ ${PARSE_TOKENS_SRC}
 
 const CSS_ENTRY = "__CSS_ENTRY__";
 
-function EmptyState({ domain }: { domain: typeof TOKEN_DOMAINS[number] }) {
+function EmptyState({ domain }: { domain: TokenDomain }) {
   return (
     <div className="rounded border border-dashed border-zinc-300 dark:border-zinc-700 p-6 text-sm text-zinc-600 dark:text-zinc-400">
       No custom <code className="rounded bg-zinc-100 dark:bg-zinc-900 px-1 py-0.5 text-xs">{domain.varPrefix}*</code> tokens declared in your <code>@theme</code>.
@@ -702,5 +689,6 @@ module.exports = {
   COMPONENT_PAGE_TSX,
   COMPONENT_ERROR_TSX,
   COMPONENT_MAP_TSX,
+  TOKEN_DOMAINS_TSX,
   PROP_TOGGLE_TSX,
 };

From 6acd374c0a48ddca9aea661cd418f61f2d470358 Mon Sep 17 00:00:00 2001
From: Hugh Francis <hughfrancis89@gmail.com>
Date: Mon, 11 May 2026 18:38:03 -0400
Subject: [PATCH 27/79] sync-docs: rename from setup-design-system-docs-route
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Slash command, skill folder, lib folder, README headings, SKILL.md
title/description/copy, final report verb, CI step name. The marker
comment stays as `design-system-docs-route` (it's the file-detection
contract, intentionally decoupled from command names).

User-facing strings flipped from setup/install vocabulary to
sync vocabulary in the appropriate places — the action is generating
+ regenerating the docs route from adhd.config.ts, which "sync" describes
better. Internal CLI subcommand names (`install`, `detect-install`, etc.)
stay — they're file-IO verbs, not user-facing.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 .github/workflows/ci.yml                      |  4 ++--
 README.md                                     |  6 ++---
 .../README.md                                 | 12 +++++-----
 .../__fixtures__/avatar.tsx                   |  0
 .../__fixtures__/globals.css                  |  0
 .../__tests__/cli.test.js                     |  0
 .../__tests__/config-parser.test.js           |  0
 .../__tests__/next-config-patcher.test.js     |  0
 .../__tests__/prop-parser.test.js             |  0
 .../__tests__/robots-patcher.test.js          |  0
 .../__tests__/route-installer.test.js         |  2 +-
 .../__tests__/slug.test.js                    |  0
 .../__tests__/templates.test.js               |  8 +++----
 .../__tests__/token-parser.test.js            |  0
 .../cli.js                                    |  0
 .../config-parser.js                          |  0
 .../next-config-patcher.js                    |  0
 .../prop-parser.js                            |  0
 .../robots-patcher.js                         |  0
 .../route-installer.js                        |  0
 .../slug.js                                   |  0
 .../templates.js                              |  8 +++----
 .../token-parser.js                           |  0
 plugins/adhd/skills/config/SKILL.md           | 16 +++++++-------
 .../SKILL.md                                  | 22 +++++++++----------
 25 files changed, 39 insertions(+), 39 deletions(-)
 rename plugins/adhd/lib/{setup-design-system-docs-route => sync-docs}/README.md (55%)
 rename plugins/adhd/lib/{setup-design-system-docs-route => sync-docs}/__fixtures__/avatar.tsx (100%)
 rename plugins/adhd/lib/{setup-design-system-docs-route => sync-docs}/__fixtures__/globals.css (100%)
 rename plugins/adhd/lib/{setup-design-system-docs-route => sync-docs}/__tests__/cli.test.js (100%)
 rename plugins/adhd/lib/{setup-design-system-docs-route => sync-docs}/__tests__/config-parser.test.js (100%)
 rename plugins/adhd/lib/{setup-design-system-docs-route => sync-docs}/__tests__/next-config-patcher.test.js (100%)
 rename plugins/adhd/lib/{setup-design-system-docs-route => sync-docs}/__tests__/prop-parser.test.js (100%)
 rename plugins/adhd/lib/{setup-design-system-docs-route => sync-docs}/__tests__/robots-patcher.test.js (100%)
 rename plugins/adhd/lib/{setup-design-system-docs-route => sync-docs}/__tests__/route-installer.test.js (99%)
 rename plugins/adhd/lib/{setup-design-system-docs-route => sync-docs}/__tests__/slug.test.js (100%)
 rename plugins/adhd/lib/{setup-design-system-docs-route => sync-docs}/__tests__/templates.test.js (96%)
 rename plugins/adhd/lib/{setup-design-system-docs-route => sync-docs}/__tests__/token-parser.test.js (100%)
 rename plugins/adhd/lib/{setup-design-system-docs-route => sync-docs}/cli.js (100%)
 rename plugins/adhd/lib/{setup-design-system-docs-route => sync-docs}/config-parser.js (100%)
 rename plugins/adhd/lib/{setup-design-system-docs-route => sync-docs}/next-config-patcher.js (100%)
 rename plugins/adhd/lib/{setup-design-system-docs-route => sync-docs}/prop-parser.js (100%)
 rename plugins/adhd/lib/{setup-design-system-docs-route => sync-docs}/robots-patcher.js (100%)
 rename plugins/adhd/lib/{setup-design-system-docs-route => sync-docs}/route-installer.js (100%)
 rename plugins/adhd/lib/{setup-design-system-docs-route => sync-docs}/slug.js (100%)
 rename plugins/adhd/lib/{setup-design-system-docs-route => sync-docs}/templates.js (98%)
 rename plugins/adhd/lib/{setup-design-system-docs-route => sync-docs}/token-parser.js (100%)
 rename plugins/adhd/skills/{setup-design-system-docs-route => sync-docs}/SKILL.md (77%)

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index b72bdd5..1fd5a07 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -23,8 +23,8 @@ jobs:
         run: node --test plugins/adhd/lib/push-component/__tests__/
       - name: Run pull-component tests
         run: node --test plugins/adhd/lib/pull-component/__tests__/
-      - name: Run setup-design-system-docs-route tests
-        run: node --test plugins/adhd/lib/setup-design-system-docs-route/__tests__/
+      - name: Run sync-docs tests
+        run: node --test plugins/adhd/lib/sync-docs/__tests__/
 
   hygiene:
     name: project hygiene
diff --git a/README.md b/README.md
index 5049656..ded5847 100644
--- a/README.md
+++ b/README.md
@@ -34,7 +34,7 @@ After install, seven slash commands are available:
 | `/adhd:pull-design-system` | — | Figma → code | Pulls Figma variables + named styles into globals.css |
 | `/adhd:push-component` | `<path> [--max-variants <n>]` | code → Figma | Pushes a React component to Figma as a structured Component Set with variant properties + variable bindings, plus a preflight lint check |
 | `/adhd:pull-component` | `<path \| figma-url> [--allow-unbound]` | Figma → code | Pulls a Figma Component Set into a React source file; updates lookup tables and union types only (function body untouched) |
-| `/adhd:setup-design-system-docs-route` | — | install | Generates a design-system docs route in your Next.js consumer app. Tokens read live from globals.css; components are statically imported from adhd.config.ts at setup time — re-run after editing the components map. Excluded from production builds by default. |
+| `/adhd:sync-docs` | — | install | Generates a design-system docs route in your Next.js consumer app. Tokens read live from globals.css; components are statically imported from adhd.config.ts at setup time — re-run after editing the components map. Excluded from production builds by default. |
 
 Every command above drives Figma exclusively through the `figma@claude-plugins-official` plugin. `/adhd:config` checks it's installed + authenticated up front so setup errors surface where you can fix them, not mid-pipeline.
 
@@ -116,7 +116,7 @@ The skill reads the Figma Component Set, diffs it against the React file's `Reco
 Run once in your consumer repo:
 
 ```
-/adhd:setup-design-system-docs-route
+/adhd:sync-docs
 ```
 
 This generates a documentation page that reads your `globals.css` live at
@@ -146,7 +146,7 @@ content="noindex, nofollow" />` either way).
 The setup command generates a `componentMap.tsx` with explicit static
 imports per component. After **adding, renaming, or removing entries** in
 `adhd.config.ts`'s `components` map, re-run
-`/adhd:setup-design-system-docs-route` to regenerate the static imports.
+`/adhd:sync-docs` to regenerate the static imports.
 Tokens don't need this — they're read from `globals.css` at request time.
 
 Files where you've removed the `// design-system-docs-route` marker comment
diff --git a/plugins/adhd/lib/setup-design-system-docs-route/README.md b/plugins/adhd/lib/sync-docs/README.md
similarity index 55%
rename from plugins/adhd/lib/setup-design-system-docs-route/README.md
rename to plugins/adhd/lib/sync-docs/README.md
index 3b69566..a027f17 100644
--- a/plugins/adhd/lib/setup-design-system-docs-route/README.md
+++ b/plugins/adhd/lib/sync-docs/README.md
@@ -1,17 +1,17 @@
-# lib/setup-design-system-docs-route
+# lib/sync-docs
 
-Deterministic helpers for `/adhd:setup-design-system-docs-route`. The
-skill (at `plugins/adhd/skills/setup-design-system-docs-route/SKILL.md`)
-is the orchestrator; this library is the testable engine.
+Deterministic helpers for `/adhd:sync-docs`. The skill (at
+`plugins/adhd/skills/sync-docs/SKILL.md`) is the orchestrator; this
+library is the testable engine.
 
 Modules:
 - `token-parser.js` — extract design-system tokens from a globals.css `@theme` block
 - `prop-parser.js` — extract a component's prop interface
 - `slug.js` — component path → URL slug
-- `config-parser.js` — parse `adhd.config.ts` at install time (components + cssEntry)
+- `config-parser.js` — parse `adhd.config.ts` at sync time (components + cssEntry)
 - `next-config-patcher.js` — idempotent patch of next.config.{ts,mjs,js}
 - `robots-patcher.js` — idempotent patch of public/robots.txt
-- `route-installer.js` — write the seven generated files at the target path, including a per-install `componentMap.tsx` with static imports
+- `route-installer.js` — write the generated files at the target path, including per-sync `componentMap.tsx` and `tokenDomains.tsx` modules
 - `templates.js` — page template strings (with substitution placeholders)
 - `cli.js` — orchestrator surface invoked by SKILL.md
 
diff --git a/plugins/adhd/lib/setup-design-system-docs-route/__fixtures__/avatar.tsx b/plugins/adhd/lib/sync-docs/__fixtures__/avatar.tsx
similarity index 100%
rename from plugins/adhd/lib/setup-design-system-docs-route/__fixtures__/avatar.tsx
rename to plugins/adhd/lib/sync-docs/__fixtures__/avatar.tsx
diff --git a/plugins/adhd/lib/setup-design-system-docs-route/__fixtures__/globals.css b/plugins/adhd/lib/sync-docs/__fixtures__/globals.css
similarity index 100%
rename from plugins/adhd/lib/setup-design-system-docs-route/__fixtures__/globals.css
rename to plugins/adhd/lib/sync-docs/__fixtures__/globals.css
diff --git a/plugins/adhd/lib/setup-design-system-docs-route/__tests__/cli.test.js b/plugins/adhd/lib/sync-docs/__tests__/cli.test.js
similarity index 100%
rename from plugins/adhd/lib/setup-design-system-docs-route/__tests__/cli.test.js
rename to plugins/adhd/lib/sync-docs/__tests__/cli.test.js
diff --git a/plugins/adhd/lib/setup-design-system-docs-route/__tests__/config-parser.test.js b/plugins/adhd/lib/sync-docs/__tests__/config-parser.test.js
similarity index 100%
rename from plugins/adhd/lib/setup-design-system-docs-route/__tests__/config-parser.test.js
rename to plugins/adhd/lib/sync-docs/__tests__/config-parser.test.js
diff --git a/plugins/adhd/lib/setup-design-system-docs-route/__tests__/next-config-patcher.test.js b/plugins/adhd/lib/sync-docs/__tests__/next-config-patcher.test.js
similarity index 100%
rename from plugins/adhd/lib/setup-design-system-docs-route/__tests__/next-config-patcher.test.js
rename to plugins/adhd/lib/sync-docs/__tests__/next-config-patcher.test.js
diff --git a/plugins/adhd/lib/setup-design-system-docs-route/__tests__/prop-parser.test.js b/plugins/adhd/lib/sync-docs/__tests__/prop-parser.test.js
similarity index 100%
rename from plugins/adhd/lib/setup-design-system-docs-route/__tests__/prop-parser.test.js
rename to plugins/adhd/lib/sync-docs/__tests__/prop-parser.test.js
diff --git a/plugins/adhd/lib/setup-design-system-docs-route/__tests__/robots-patcher.test.js b/plugins/adhd/lib/sync-docs/__tests__/robots-patcher.test.js
similarity index 100%
rename from plugins/adhd/lib/setup-design-system-docs-route/__tests__/robots-patcher.test.js
rename to plugins/adhd/lib/sync-docs/__tests__/robots-patcher.test.js
diff --git a/plugins/adhd/lib/setup-design-system-docs-route/__tests__/route-installer.test.js b/plugins/adhd/lib/sync-docs/__tests__/route-installer.test.js
similarity index 99%
rename from plugins/adhd/lib/setup-design-system-docs-route/__tests__/route-installer.test.js
rename to plugins/adhd/lib/sync-docs/__tests__/route-installer.test.js
index 47f1e1a..a068599 100644
--- a/plugins/adhd/lib/setup-design-system-docs-route/__tests__/route-installer.test.js
+++ b/plugins/adhd/lib/sync-docs/__tests__/route-installer.test.js
@@ -238,7 +238,7 @@ test('component page shows a "not in static map" message when slug is missing',
     'utf8',
   );
   assert.match(componentPage, /Not in the static map/);
-  assert.match(componentPage, /\/adhd:setup-design-system-docs-route/);
+  assert.match(componentPage, /\/adhd:sync-docs/);
 });
 
 test('detectExistingInstall returns marker-bearing files', () => {
diff --git a/plugins/adhd/lib/setup-design-system-docs-route/__tests__/slug.test.js b/plugins/adhd/lib/sync-docs/__tests__/slug.test.js
similarity index 100%
rename from plugins/adhd/lib/setup-design-system-docs-route/__tests__/slug.test.js
rename to plugins/adhd/lib/sync-docs/__tests__/slug.test.js
diff --git a/plugins/adhd/lib/setup-design-system-docs-route/__tests__/templates.test.js b/plugins/adhd/lib/sync-docs/__tests__/templates.test.js
similarity index 96%
rename from plugins/adhd/lib/setup-design-system-docs-route/__tests__/templates.test.js
rename to plugins/adhd/lib/sync-docs/__tests__/templates.test.js
index 97590e9..4bdb2b6 100644
--- a/plugins/adhd/lib/setup-design-system-docs-route/__tests__/templates.test.js
+++ b/plugins/adhd/lib/sync-docs/__tests__/templates.test.js
@@ -85,7 +85,7 @@ test('INDEX_PAGE_TSX has no Troubleshooting section (each route handles its own
   assert.doesNotMatch(INDEX_PAGE_TSX, /Troubleshooting/);
   assert.doesNotMatch(INDEX_PAGE_TSX, /app-build-manifest|broad dynamic/i);
   // It still mentions the re-run command so the user knows how to refresh the map.
-  assert.match(INDEX_PAGE_TSX, /\/adhd:setup-design-system-docs-route/);
+  assert.match(INDEX_PAGE_TSX, /\/adhd:sync-docs/);
 });
 
 test('TOKENS_PAGE_TSX reads globals.css from a baked CSS_ENTRY constant', () => {
@@ -114,7 +114,7 @@ test('COMPONENT_PAGE_TSX reads searchParams for prop toggles', () => {
 test('COMPONENT_PAGE_TSX shows a "Not in the static map" branch for unknown slugs', () => {
   // Replaces notFound() with an actionable message about re-running setup.
   assert.match(COMPONENT_PAGE_TSX, /Not in the static map/);
-  assert.match(COMPONENT_PAGE_TSX, /re-run.*\/adhd:setup-design-system-docs-route/i);
+  assert.match(COMPONENT_PAGE_TSX, /re-run.*\/adhd:sync-docs/i);
 });
 
 test('COMPONENT_MAP_TSX has the substitution placeholders the installer needs', () => {
@@ -161,14 +161,14 @@ test('none of the templates contain "ADHD" outside the marker', () => {
   // interacts with the tool, and ejecting from ADHD doesn't break the file —
   // it just means those references become vestigial guidance the user can edit):
   //   1. `adhd.config.ts` — the consumer's own config artifact.
-  //   2. `/adhd:setup-design-system-docs-route` — the slash command name,
+  //   2. `/adhd:sync-docs` — the slash command name,
   //      referenced in troubleshooting copy so the user knows what to re-run.
   const all = { LAYOUT_TSX, INDEX_PAGE_TSX, TOKENS_PAGE_TSX, COMPONENT_PAGE_TSX, COMPONENT_ERROR_TSX, COMPONENT_MAP_TSX, PROP_TOGGLE_TSX };
   for (const [name, content] of Object.entries(all)) {
     const body = content
       .replace(MARKER_COMMENT, '')
       .replace(/adhd\.config\.ts/g, '')
-      .replace(/\/adhd:setup-design-system-docs-route/g, '');
+      .replace(/\/adhd:sync-docs/g, '');
     assert.equal(/adhd/i.test(body), false, `${name} must not reference ADHD outside marker / allowed exceptions`);
   }
 });
diff --git a/plugins/adhd/lib/setup-design-system-docs-route/__tests__/token-parser.test.js b/plugins/adhd/lib/sync-docs/__tests__/token-parser.test.js
similarity index 100%
rename from plugins/adhd/lib/setup-design-system-docs-route/__tests__/token-parser.test.js
rename to plugins/adhd/lib/sync-docs/__tests__/token-parser.test.js
diff --git a/plugins/adhd/lib/setup-design-system-docs-route/cli.js b/plugins/adhd/lib/sync-docs/cli.js
similarity index 100%
rename from plugins/adhd/lib/setup-design-system-docs-route/cli.js
rename to plugins/adhd/lib/sync-docs/cli.js
diff --git a/plugins/adhd/lib/setup-design-system-docs-route/config-parser.js b/plugins/adhd/lib/sync-docs/config-parser.js
similarity index 100%
rename from plugins/adhd/lib/setup-design-system-docs-route/config-parser.js
rename to plugins/adhd/lib/sync-docs/config-parser.js
diff --git a/plugins/adhd/lib/setup-design-system-docs-route/next-config-patcher.js b/plugins/adhd/lib/sync-docs/next-config-patcher.js
similarity index 100%
rename from plugins/adhd/lib/setup-design-system-docs-route/next-config-patcher.js
rename to plugins/adhd/lib/sync-docs/next-config-patcher.js
diff --git a/plugins/adhd/lib/setup-design-system-docs-route/prop-parser.js b/plugins/adhd/lib/sync-docs/prop-parser.js
similarity index 100%
rename from plugins/adhd/lib/setup-design-system-docs-route/prop-parser.js
rename to plugins/adhd/lib/sync-docs/prop-parser.js
diff --git a/plugins/adhd/lib/setup-design-system-docs-route/robots-patcher.js b/plugins/adhd/lib/sync-docs/robots-patcher.js
similarity index 100%
rename from plugins/adhd/lib/setup-design-system-docs-route/robots-patcher.js
rename to plugins/adhd/lib/sync-docs/robots-patcher.js
diff --git a/plugins/adhd/lib/setup-design-system-docs-route/route-installer.js b/plugins/adhd/lib/sync-docs/route-installer.js
similarity index 100%
rename from plugins/adhd/lib/setup-design-system-docs-route/route-installer.js
rename to plugins/adhd/lib/sync-docs/route-installer.js
diff --git a/plugins/adhd/lib/setup-design-system-docs-route/slug.js b/plugins/adhd/lib/sync-docs/slug.js
similarity index 100%
rename from plugins/adhd/lib/setup-design-system-docs-route/slug.js
rename to plugins/adhd/lib/sync-docs/slug.js
diff --git a/plugins/adhd/lib/setup-design-system-docs-route/templates.js b/plugins/adhd/lib/sync-docs/templates.js
similarity index 98%
rename from plugins/adhd/lib/setup-design-system-docs-route/templates.js
rename to plugins/adhd/lib/sync-docs/templates.js
index 573d88d..bd2cf9e 100644
--- a/plugins/adhd/lib/setup-design-system-docs-route/templates.js
+++ b/plugins/adhd/lib/sync-docs/templates.js
@@ -132,7 +132,7 @@ function parseTokens(css: string | null) {
 // `import * as $cmpN from "@/<path>"` so Webpack/Turbopack resolves a single,
 // known module per component — no context module, no broad bundle, no
 // Tailwind blast radius. To add/rename/remove a component: edit
-// `adhd.config.ts`, then re-run `/adhd:setup-design-system-docs-route`.
+// `adhd.config.ts`, then re-run `/adhd:sync-docs`.
 //
 // Placeholders substituted by route-installer.js:
 //   __COMPONENT_IMPORTS__ — one `import * as $cmpN from "<importPath>";` per component
@@ -209,7 +209,7 @@ export default function DesignSystemDocsLayout({ children }: { children: React.R
           <section>
             <h2 className="mb-2 text-[10px] font-medium uppercase tracking-wide text-zinc-500">Components</h2>
             {componentEntries.length === 0 ? (
-              <p className="text-xs text-zinc-500 px-2">None tracked. Add to <code>adhd.config.ts</code> and re-run the setup command.</p>
+              <p className="text-xs text-zinc-500 px-2">None tracked. Add to <code>adhd.config.ts</code> and re-run <code>/adhd:sync-docs</code>.</p>
             ) : (
               <ul className="flex flex-col gap-1">
                 {componentEntries.map(c => (
@@ -247,7 +247,7 @@ const INDEX_PAGE_TSX = `${MARKER_COMMENT}export default function DesignSystemInd
         <code className="mx-1 rounded bg-zinc-100 dark:bg-zinc-900 px-1 py-0.5 text-xs">globals.css</code>
         <code className="rounded bg-zinc-100 dark:bg-zinc-900 px-1 py-0.5 text-xs">@theme</code> blocks. Components are statically imported from
         <code className="ml-1 rounded bg-zinc-100 dark:bg-zinc-900 px-1 py-0.5 text-xs">adhd.config.ts</code> — after editing the components map, re-run
-        <code className="ml-1 rounded bg-zinc-100 dark:bg-zinc-900 px-1 py-0.5 text-xs">/adhd:setup-design-system-docs-route</code> to regenerate the static imports.
+        <code className="ml-1 rounded bg-zinc-100 dark:bg-zinc-900 px-1 py-0.5 text-xs">/adhd:sync-docs</code> to regenerate the static imports.
       </p>
       <p className="text-xs text-zinc-500 max-w-prose">
         Only <code>@theme {"{ ... }"}</code> and <code>@theme inline {"{ ... }"}</code> declarations are picked up — plain <code>:root</code> variables aren&apos;t.
@@ -530,7 +530,7 @@ export default async function ComponentPage({
           The slug <code>{slug}</code> isn&apos;t present in the generated <code>componentMap.tsx</code>.
         </p>
         <p className="mt-2 text-sm text-amber-800 dark:text-amber-300">
-          If you just edited <code>adhd.config.ts</code> to add this component, re-run <code>/adhd:setup-design-system-docs-route</code> in this project to regenerate the static imports.
+          If you just edited <code>adhd.config.ts</code> to add this component, re-run <code>/adhd:sync-docs</code> in this project to regenerate the static imports.
         </p>
       </div>
     );
diff --git a/plugins/adhd/lib/setup-design-system-docs-route/token-parser.js b/plugins/adhd/lib/sync-docs/token-parser.js
similarity index 100%
rename from plugins/adhd/lib/setup-design-system-docs-route/token-parser.js
rename to plugins/adhd/lib/sync-docs/token-parser.js
diff --git a/plugins/adhd/skills/config/SKILL.md b/plugins/adhd/skills/config/SKILL.md
index 1c73e02..5fa5928 100644
--- a/plugins/adhd/skills/config/SKILL.md
+++ b/plugins/adhd/skills/config/SKILL.md
@@ -235,27 +235,27 @@ Then run /adhd:sync --dry-run to preview your first diff (Figma → code).
 
 If running on a healthy config that didn't change, print `Config unchanged.` instead of the saved-to message.
 
-## Phase 6 (optional): Set up the design-system docs route
+## Phase 6 (optional): Sync the design-system docs route
 
 Use `AskUserQuestion`:
 
 ```
-Question: "Set up the design-system docs route now? It's a live, self-generating
-documentation page that reads your adhd.config.ts and globals.css. Mini-Storybook
-for designers; not indexed by search engines."
+Question: "Generate the design-system docs route now? It's a live page that
+reads your adhd.config.ts and globals.css. Mini-Storybook for designers;
+not indexed by search engines."
 Header: "Docs route"
 Options:
-  - "Yes, install it now"
+  - "Yes, generate it now"
   - "No, maybe later"
 ```
 
-On "Yes": execute the phases of `/adhd:setup-design-system-docs-route` inline.
-See `plugins/adhd/skills/setup-design-system-docs-route/SKILL.md` for the
+On "Yes": execute the phases of `/adhd:sync-docs` inline.
+See `plugins/adhd/skills/sync-docs/SKILL.md` for the
 detailed phase list (validate environment → detect existing install → ask install
 choices → detect Next.js config → detect collisions → patch next.config.ts →
 write files → patch robots.txt → final report).
 
-On "No": print `Run /adhd:setup-design-system-docs-route later to set it up.`
+On "No": print `Run /adhd:sync-docs later to generate it.`
 Exit normally.
 
 ## Reference: Common errors and fix-up guidance
diff --git a/plugins/adhd/skills/setup-design-system-docs-route/SKILL.md b/plugins/adhd/skills/sync-docs/SKILL.md
similarity index 77%
rename from plugins/adhd/skills/setup-design-system-docs-route/SKILL.md
rename to plugins/adhd/skills/sync-docs/SKILL.md
index ce96404..23c0317 100644
--- a/plugins/adhd/skills/setup-design-system-docs-route/SKILL.md
+++ b/plugins/adhd/skills/sync-docs/SKILL.md
@@ -1,22 +1,22 @@
 ---
-description: "Generate a design-system documentation route in a Next.js consumer app. Sidebar + viewer layout: sidebar lists every Tailwind v4 token domain (colors, spacing, typography, font, font-weight, tracking, leading, radius, shadows, breakpoints, easing, animation) plus every component tracked in adhd.config.ts; the main pane renders the selected route. Tokens are read from globals.css at request time. Components are statically imported from adhd.config.ts at install time — re-run this command after editing the components map. Component pages introspect props for URL-driven toggles. Optionally excluded from production builds via Next.js pageExtensions trick. Marker-comment detection makes it safe to re-run; stale files from earlier template layouts are cleaned up automatically."
+description: "Sync the design-system docs route in a Next.js consumer app. Sidebar + viewer layout: sidebar lists every Tailwind v4 token domain (colors, spacing, typography, font, font-weight, tracking, leading, radius, shadows, breakpoints, easing, animation) plus every component tracked in adhd.config.ts; the main pane renders the selected route. Tokens are read from globals.css at request time. Components are statically imported from adhd.config.ts at sync time — re-run this command after editing the components map. Component pages introspect props for URL-driven toggles. Optionally excluded from production builds via Next.js pageExtensions trick. Marker-comment detection makes it safe to re-run; stale files from earlier template layouts are cleaned up automatically."
 disable-model-invocation: true
 argument-hint: ""
 allowed-tools: Read Write Edit Bash AskUserQuestion
 ---
 
-# ADHD Setup Design System Docs Route
+# ADHD Sync Docs
 
-Generates a design-system docs page in a Next.js App Router project. Tokens are read live from `globals.css`. Components are statically imported from `adhd.config.ts` at the moment this skill runs — **re-run after editing the components map** to regenerate the static imports.
+Generates (and re-generates) a design-system docs page in a Next.js App Router project. Tokens are read live from `globals.css`. Components are statically imported from `adhd.config.ts` at the moment this skill runs — **re-run after editing the components map** to sync the static imports.
 
 **Authoritative spec:** `docs/superpowers/specs/2026-05-11-adhd-install-design-system-docs-route.md` (historical name).
 
 ## Invariants
 
-1. **No ADHD references in generated files** outside of two filename-style exceptions: the consumer's `adhd.config.ts` filename, and the slash-command name `/adhd:setup-design-system-docs-route` referenced in troubleshooting copy.
+1. **No ADHD references in generated files** outside of two filename-style exceptions: the consumer's `adhd.config.ts` filename, and the slash-command name `/adhd:sync-docs` referenced in re-run copy.
 2. **adhd.config.ts is NOT modified** by this skill. The skill reads it; the user owns it.
 3. **All file writes are idempotent on re-run.** Marker-bearing files are replaced wholesale with the latest templates. Files where the user deleted the marker are left alone. Stale marker-bearing files from earlier template layouts are removed.
-4. **Static component imports.** The installer parses `adhd.config.ts` and generates `componentMap.tsx` with explicit `import * as $cmpN from "@/..."` per registered component. The component page does a static lookup — no dynamic imports, no broad Webpack context modules, no Tailwind-blast-radius issues.
+4. **Static component imports.** The skill parses `adhd.config.ts` and generates `componentMap.tsx` with explicit `import * as $cmpN from "@/..."` per registered component. The component page does a static lookup — no dynamic imports, no broad Webpack context modules, no Tailwind-blast-radius issues.
 
 ## Phase 1: Validate consumer environment
 
@@ -31,7 +31,7 @@ Read `package.json` and confirm `next` is in `dependencies` or `devDependencies`
 ## Phase 2: Detect existing install
 
 ```bash
-node plugins/adhd/lib/setup-design-system-docs-route/cli.js detect-install --app-dir .
+node plugins/adhd/lib/sync-docs/cli.js detect-install --app-dir .
 ```
 
 Output is newline-separated paths of files containing the marker comment.
@@ -78,7 +78,7 @@ If `EXISTS` and Phase 2 didn't already mark this as an existing install: prompt
 ## Phase 6: Patch next.config.ts (only if prod-exclusion: yes)
 
 ```bash
-node plugins/adhd/lib/setup-design-system-docs-route/cli.js patch-next-config \
+node plugins/adhd/lib/sync-docs/cli.js patch-next-config \
   --config "<next.config.path>" \
   --route-url "<routeUrl>"
 ```
@@ -103,7 +103,7 @@ pageExtensions: process.env.NODE_ENV === 'production'
 ## Phase 7: Write the page files
 
 ```bash
-node plugins/adhd/lib/setup-design-system-docs-route/cli.js install \
+node plugins/adhd/lib/sync-docs/cli.js install \
   --config <choices.json>
 ```
 
@@ -124,7 +124,7 @@ If `adhd.config.ts` is missing, the CLI aborts with `install: failed to read adh
 ## Phase 8: Patch robots.txt
 
 ```bash
-node plugins/adhd/lib/setup-design-system-docs-route/cli.js patch-robots \
+node plugins/adhd/lib/sync-docs/cli.js patch-robots \
   --robots public/robots.txt \
   --route-url "<routeUrl>"
 ```
@@ -138,7 +138,7 @@ mkdir -p public
 
 Print:
 ```
-✓ Design system docs route set up.
+✓ Design system docs synced.
 
   URL:            http://localhost:3000<routeUrl>
   Filesystem:     app/<group>/<segment>/
@@ -152,7 +152,7 @@ Run `npm run dev` and visit the URL to preview.
 Tokens are read from globals.css at request time, so editing globals.css just
 works. Components are statically imported from adhd.config.ts — after adding,
 renaming, or removing entries in the components map, re-run
-/adhd:setup-design-system-docs-route to regenerate the static imports.
+/adhd:sync-docs to regenerate the static imports.
 
 Files where you've removed the marker comment are left alone.
 ```

From 44fb0c6191f880c6f3ff94b5745b7e03f53d1bd1 Mon Sep 17 00:00:00 2001
From: Hugh Francis <hughfrancis89@gmail.com>
Date: Mon, 11 May 2026 18:52:00 -0400
Subject: [PATCH 28/79] sync-docs: collapse tokenDomains.tsx into the layout

User feedback: minimize the committed file surface so future syncs only
churn one file (componentMap.tsx). The token-domain catalog was a separate
tokenDomains.tsx solely so the layout and tokens page could share it
without duplication. Moving the catalog onto the layout as a named export
removes that file without re-introducing duplication: the tokens page now
imports `{ TOKEN_DOMAINS, type TokenDomain }` from the layout module.

Cross-import detail: the layout's basename depends on prod-exclusion
(`layout` vs `layout.design-system`). The component-page template uses a
`__LAYOUT_MODULE__` placeholder; the installer substitutes the right
basename at sync time. TypeScript's bundler module resolution then adds
`.tsx` and finds the file in both cases. Verified with an isolated
strict-mode tsc test before wiring up.

Generated file count drops from 8 to 7. Of those 7, six are
committed-once boilerplate (layout, landing, tokens page, component page,
error boundary, PropToggle) and one (componentMap.tsx) regenerates per
sync.

Stale cleanup handles the upgrade path: a previous-version
tokenDomains.tsx gets removed on the next sync because it carries the
marker comment and isn't in the new target set.

Tests + strict tsc on the generated output both clean (99/99 lib tests,
382/382 plugin-wide).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 plugins/adhd/lib/sync-docs/README.md          |  2 +-
 .../__tests__/route-installer.test.js         | 57 ++++++++++++++--
 .../lib/sync-docs/__tests__/templates.test.js | 35 +++++-----
 plugins/adhd/lib/sync-docs/route-installer.js | 14 ++--
 plugins/adhd/lib/sync-docs/templates.js       | 68 ++++++++++---------
 5 files changed, 115 insertions(+), 61 deletions(-)

diff --git a/plugins/adhd/lib/sync-docs/README.md b/plugins/adhd/lib/sync-docs/README.md
index a027f17..8e85892 100644
--- a/plugins/adhd/lib/sync-docs/README.md
+++ b/plugins/adhd/lib/sync-docs/README.md
@@ -11,7 +11,7 @@ Modules:
 - `config-parser.js` — parse `adhd.config.ts` at sync time (components + cssEntry)
 - `next-config-patcher.js` — idempotent patch of next.config.{ts,mjs,js}
 - `robots-patcher.js` — idempotent patch of public/robots.txt
-- `route-installer.js` — write the generated files at the target path, including per-sync `componentMap.tsx` and `tokenDomains.tsx` modules
+- `route-installer.js` — write the seven generated files at the target path. Only `componentMap.tsx` is per-sync; the rest are committed-once boilerplate. The token-domain catalog lives as a named export on the layout (no separate file).
 - `templates.js` — page template strings (with substitution placeholders)
 - `cli.js` — orchestrator surface invoked by SKILL.md
 
diff --git a/plugins/adhd/lib/sync-docs/__tests__/route-installer.test.js b/plugins/adhd/lib/sync-docs/__tests__/route-installer.test.js
index a068599..0482484 100644
--- a/plugins/adhd/lib/sync-docs/__tests__/route-installer.test.js
+++ b/plugins/adhd/lib/sync-docs/__tests__/route-installer.test.js
@@ -35,11 +35,12 @@ test('installRoute writes the full generated file set with .design-system suffix
   assert.ok(fs.existsSync(path.join(docsDir, 'components', '[component]', 'error.design-system.tsx')));
   // Shared modules (imported by the route files) are plain .tsx so TS resolves them.
   assert.ok(fs.existsSync(path.join(docsDir, 'componentMap.tsx')));
-  assert.ok(fs.existsSync(path.join(docsDir, 'tokenDomains.tsx')));
   assert.ok(fs.existsSync(path.join(docsDir, 'PropToggle.tsx')));
   assert.ok(!fs.existsSync(path.join(docsDir, 'componentMap.design-system.tsx')));
-  assert.ok(!fs.existsSync(path.join(docsDir, 'tokenDomains.design-system.tsx')));
   assert.ok(!fs.existsSync(path.join(docsDir, 'PropToggle.design-system.tsx')));
+  // tokenDomains.tsx no longer exists — the catalog is named-exported from the
+  // layout, and the tokens page imports it from there.
+  assert.ok(!fs.existsSync(path.join(docsDir, 'tokenDomains.tsx')));
 });
 
 test('installRoute writes plain .tsx files for route files when not prodExcluded', () => {
@@ -78,7 +79,6 @@ test('all written files start with the marker comment', () => {
     'components/[component]/page.design-system.tsx',
     'components/[component]/error.design-system.tsx',
     'componentMap.tsx',
-    'tokenDomains.tsx',
     'PropToggle.tsx',
   ]) {
     const content = fs.readFileSync(path.join(docsDir, f), 'utf8');
@@ -186,6 +186,55 @@ test('layout imports componentEntries from componentMap (the sidebar list source
   assert.doesNotMatch(layout, /from "node:fs|from "node:path/);
 });
 
+test('tokens page imports TOKEN_DOMAINS from layout.design-system when prodExcluded', () => {
+  // The layout file's basename has `.design-system` when prod-excluded, and the
+  // tokens page must use that basename in its import so TS's bundler resolution
+  // adds `.tsx` and finds it.
+  const root = makeTempProject();
+  installRoute(root, {
+    groupName: '(design-system)', routeSegment: '-docs', prodExcluded: true,
+    components: SAMPLE_COMPONENTS, cssEntry: 'app/globals.css',
+  });
+  const tokensPage = fs.readFileSync(
+    path.join(root, 'app', '(design-system)', '-docs', 'tokens', '[domain]', 'page.design-system.tsx'),
+    'utf8',
+  );
+  assert.match(tokensPage, /from "\.\.\/\.\.\/layout\.design-system"/);
+  assert.doesNotMatch(tokensPage, /__LAYOUT_MODULE__/);
+});
+
+test('tokens page imports TOKEN_DOMAINS from layout (no suffix) when not prodExcluded', () => {
+  const root = makeTempProject();
+  installRoute(root, {
+    groupName: '(design-system)', routeSegment: '-docs', prodExcluded: false,
+    components: SAMPLE_COMPONENTS, cssEntry: 'app/globals.css',
+  });
+  const tokensPage = fs.readFileSync(
+    path.join(root, 'app', '(design-system)', '-docs', 'tokens', '[domain]', 'page.tsx'),
+    'utf8',
+  );
+  assert.match(tokensPage, /from "\.\.\/\.\.\/layout"/);
+  assert.doesNotMatch(tokensPage, /__LAYOUT_MODULE__/);
+});
+
+test('re-sync removes stale tokenDomains.tsx from a previous template layout', () => {
+  // Mirrors the actual upgrade path: previous installer versions wrote
+  // tokenDomains.tsx alongside componentMap.tsx. Re-syncing should clean it up.
+  const root = makeTempProject();
+  const docsDir = path.join(root, 'app', '(design-system)', '-docs');
+  fs.mkdirSync(docsDir, { recursive: true });
+  const stalePath = path.join(docsDir, 'tokenDomains.tsx');
+  fs.writeFileSync(stalePath, '// design-system-docs-route — stale\nexport const TOKEN_DOMAINS = [];\n');
+
+  const r = installRoute(root, {
+    groupName: '(design-system)', routeSegment: '-docs', prodExcluded: true,
+    components: SAMPLE_COMPONENTS, cssEntry: 'app/globals.css',
+  });
+
+  assert.ok(!fs.existsSync(stalePath), 'stale tokenDomains.tsx should be removed');
+  assert.ok(r.removed.includes(stalePath));
+});
+
 test('tokens page bakes the configured cssEntry path as a constant', () => {
   const root = makeTempProject();
   installRoute(root, {
@@ -251,7 +300,7 @@ test('detectExistingInstall returns marker-bearing files', () => {
     cssEntry: 'app/globals.css',
   });
   const found = detectExistingInstall(root);
-  assert.ok(found.length >= 8);
+  assert.ok(found.length >= 7);
   assert.ok(found.every(p => p.includes('-docs')));
 });
 
diff --git a/plugins/adhd/lib/sync-docs/__tests__/templates.test.js b/plugins/adhd/lib/sync-docs/__tests__/templates.test.js
index 4bdb2b6..e8eba0f 100644
--- a/plugins/adhd/lib/sync-docs/__tests__/templates.test.js
+++ b/plugins/adhd/lib/sync-docs/__tests__/templates.test.js
@@ -10,7 +10,6 @@ const {
   COMPONENT_PAGE_TSX,
   COMPONENT_ERROR_TSX,
   COMPONENT_MAP_TSX,
-  TOKEN_DOMAINS_TSX,
   PROP_TOGGLE_TSX,
 } = require('../templates');
 
@@ -28,26 +27,25 @@ test('LAYOUT_TSX sets robots: noindex / nofollow', () => {
   assert.match(LAYOUT_TSX, /robots:\s*\{[^}]*index:\s*false[^}]*follow:\s*false/);
 });
 
-test('LAYOUT_TSX imports the TOKEN_DOMAINS catalog from the shared tokenDomains module', () => {
-  // Single source of truth lives in tokenDomains.tsx; the layout just imports it
-  // and iterates. Inlining the labels here would duplicate the catalog (the
-  // duplication the rewrite was meant to remove).
-  assert.match(LAYOUT_TSX, /import \{ TOKEN_DOMAINS \} from "\.\/tokenDomains"/);
-});
-
-test('TOKEN_DOMAINS_TSX exports the full Tailwind v4 token-domain catalog', () => {
-  // The catalog is THE source of truth — every token domain rendered by the
-  // tokens page must be listed here with its varPrefix and Tailwind docs link.
+test('LAYOUT_TSX declares and named-exports the TOKEN_DOMAINS catalog', () => {
+  // Single source of truth lives in the layout. Tokens page imports it from there.
+  // The catalog covers every Tailwind v4 token domain with its varPrefix and
+  // Tailwind docs link (used for empty-state messaging on each domain page).
+  assert.match(LAYOUT_TSX, /export const TOKEN_DOMAINS: TokenDomain\[\]/);
+  assert.match(LAYOUT_TSX, /export type TokenDomain/);
   for (const label of [
     'Colors', 'Spacing', 'Typography', 'Font Families', 'Font Weights',
     'Tracking', 'Leading', 'Radius', 'Shadows', 'Breakpoints', 'Easing', 'Animation',
   ]) {
-    assert.match(TOKEN_DOMAINS_TSX, new RegExp(`label: "${label}"`), `missing domain label: ${label}`);
+    assert.match(LAYOUT_TSX, new RegExp(`label: "${label}"`), `missing domain label: ${label}`);
   }
-  // Shape: each entry has slug + label + varPrefix + tailwindDocs.
-  assert.match(TOKEN_DOMAINS_TSX, /slug:\s*"colors".*varPrefix:\s*"--color-".*tailwindDocs:/s);
-  assert.match(TOKEN_DOMAINS_TSX, /export const TOKEN_DOMAINS:/);
-  assert.match(TOKEN_DOMAINS_TSX, /export type TokenDomain/);
+  assert.match(LAYOUT_TSX, /slug:\s*"colors".*varPrefix:\s*"--color-".*tailwindDocs:/s);
+});
+
+test('TOKENS_PAGE_TSX imports the catalog from the layout via a __LAYOUT_MODULE__ placeholder', () => {
+  // The path depends on prod-exclusion (`layout` vs `layout.design-system`) — the
+  // installer substitutes it. Template body should carry the placeholder verbatim.
+  assert.match(TOKENS_PAGE_TSX, /import \{ TOKEN_DOMAINS, type TokenDomain \} from "__LAYOUT_MODULE__"/);
 });
 
 test('LAYOUT_TSX imports componentEntries from componentMap (no runtime config read)', () => {
@@ -95,9 +93,8 @@ test('TOKENS_PAGE_TSX reads globals.css from a baked CSS_ENTRY constant', () =>
   assert.doesNotMatch(TOKENS_PAGE_TSX, /readConfig|adhd\.config\.ts/);
 });
 
-test('TOKENS_PAGE_TSX imports TOKEN_DOMAINS from the shared catalog (no inlined list)', () => {
-  assert.match(TOKENS_PAGE_TSX, /import \{ TOKEN_DOMAINS, type TokenDomain \} from "\.\.\/\.\.\/tokenDomains"/);
-  // The inline `const TOKEN_DOMAINS = [...]` block from earlier versions is gone.
+test('TOKENS_PAGE_TSX does not inline the TOKEN_DOMAINS list', () => {
+  // The inline catalog from earlier versions is gone — the page imports from the layout.
   assert.doesNotMatch(TOKENS_PAGE_TSX, /const TOKEN_DOMAINS = \[/);
 });
 
diff --git a/plugins/adhd/lib/sync-docs/route-installer.js b/plugins/adhd/lib/sync-docs/route-installer.js
index 2133594..37f3d92 100644
--- a/plugins/adhd/lib/sync-docs/route-installer.js
+++ b/plugins/adhd/lib/sync-docs/route-installer.js
@@ -9,7 +9,6 @@ const {
   COMPONENT_PAGE_TSX,
   COMPONENT_ERROR_TSX,
   COMPONENT_MAP_TSX,
-  TOKEN_DOMAINS_TSX,
   PROP_TOGGLE_TSX,
 } = require('./templates');
 
@@ -70,17 +69,22 @@ function installRoute(projectRoot, opts) {
     { abs: path.join(componentsDir, `page${pageExt}`), body: COMPONENT_PAGE_TSX },
     { abs: path.join(componentsDir, `error${pageExt}`), body: COMPONENT_ERROR_TSX },
     { abs: path.join(docsDir, `componentMap${moduleExt}`), body: renderComponentMap(components) },
-    // Shared token-domain catalog: imported by layout (sidebar nav) and the
-    // tokens page (renderer keys + empty-state link targets). One source of truth.
-    { abs: path.join(docsDir, `tokenDomains${moduleExt}`), body: TOKEN_DOMAINS_TSX },
     { abs: path.join(docsDir, `PropToggle${moduleExt}`), body: PROP_TOGGLE_TSX },
   ];
 
+  // The tokens page imports TOKEN_DOMAINS from the layout. The layout file's
+  // basename depends on prod-exclusion (`layout` vs `layout.design-system`).
+  // TS/bundler resolution adds `.tsx` to whichever basename we use, so we
+  // substitute the right one here. Path is two levels up from
+  // `tokens/[domain]/page.*` to the docs root where `layout.*` lives.
+  const layoutModule = prodExcluded ? '../../layout.design-system' : '../../layout';
+
   // Per-template placeholder substitution.
   for (const t of targets) {
     t.body = t.body
       .replace(/__ROUTE_PATH__/g, routeUrl)
-      .replace(/__CSS_ENTRY__/g, cssEntry);
+      .replace(/__CSS_ENTRY__/g, cssEntry)
+      .replace(/__LAYOUT_MODULE__/g, layoutModule);
   }
 
   // Remove stale marker-bearing files from previous template layouts (e.g. the
diff --git a/plugins/adhd/lib/sync-docs/templates.js b/plugins/adhd/lib/sync-docs/templates.js
index bd2cf9e..bb93828 100644
--- a/plugins/adhd/lib/sync-docs/templates.js
+++ b/plugins/adhd/lib/sync-docs/templates.js
@@ -4,33 +4,12 @@ const MARKER_COMMENT = `// design-system-docs-route — auto-generated installer
 // Remove this comment to disable future overwrites from re-running the installer.
 `;
 
-// tokenDomains.tsx — the single source of truth for the token-domain catalog
-// (sidebar entries + per-domain renderer keys). Generated once per install and
-// imported by both layout.* and tokens/[domain]/page.*. The `tailwindDocs`
-// field is the URL to Tailwind v4's relevant theme section, used in
-// empty-state messaging on each domain page.
-const TOKEN_DOMAINS_TSX = `${MARKER_COMMENT}export type TokenDomain = {
-  slug: string;
-  label: string;
-  varPrefix: string;
-  tailwindDocs: string;
-};
-
-export const TOKEN_DOMAINS: TokenDomain[] = [
-  { slug: "colors", label: "Colors", varPrefix: "--color-", tailwindDocs: "https://tailwindcss.com/docs/colors" },
-  { slug: "spacing", label: "Spacing", varPrefix: "--spacing", tailwindDocs: "https://tailwindcss.com/docs/theme#spacing" },
-  { slug: "typography", label: "Typography", varPrefix: "--text-", tailwindDocs: "https://tailwindcss.com/docs/font-size" },
-  { slug: "font", label: "Font Families", varPrefix: "--font-", tailwindDocs: "https://tailwindcss.com/docs/font-family" },
-  { slug: "font-weight", label: "Font Weights", varPrefix: "--font-weight-", tailwindDocs: "https://tailwindcss.com/docs/font-weight" },
-  { slug: "tracking", label: "Tracking", varPrefix: "--tracking-", tailwindDocs: "https://tailwindcss.com/docs/letter-spacing" },
-  { slug: "leading", label: "Leading", varPrefix: "--leading-", tailwindDocs: "https://tailwindcss.com/docs/line-height" },
-  { slug: "radius", label: "Radius", varPrefix: "--radius-", tailwindDocs: "https://tailwindcss.com/docs/border-radius" },
-  { slug: "shadows", label: "Shadows", varPrefix: "--shadow-", tailwindDocs: "https://tailwindcss.com/docs/box-shadow" },
-  { slug: "breakpoint", label: "Breakpoints", varPrefix: "--breakpoint-", tailwindDocs: "https://tailwindcss.com/docs/responsive-design" },
-  { slug: "ease", label: "Easing", varPrefix: "--ease-", tailwindDocs: "https://tailwindcss.com/docs/transition-timing-function" },
-  { slug: "animate", label: "Animation", varPrefix: "--animate-", tailwindDocs: "https://tailwindcss.com/docs/animation" },
-];
-`;
+// The TOKEN_DOMAINS catalog is declared (and named-exported) directly in
+// LAYOUT_TSX. Keeping it there means we don't ship a separate tokenDomains.tsx
+// file just to share a 12-entry constant. The tokens page imports
+// `{ TOKEN_DOMAINS, type TokenDomain }` from the layout module — TS's bundler
+// resolution handles the `.design-system.tsx` extension via `__LAYOUT_MODULE__`
+// substitution at install time.
 
 // Tokens-page CSS reader. Kept inline because the tokens page is a runtime
 // server component in the consumer's app and can't import ADHD's lib helpers.
@@ -171,11 +150,11 @@ export function getComponent(slug: string): ComponentEntry | null {
 }
 `;
 
-// Layout: sidebar links into the token-domain catalog and the static component
-// map. No fs reads, no async — pure server component.
+// Layout: sidebar links into the token-domain catalog (declared inline + named-
+// exported so the tokens page can import it) and the static component map.
+// No fs reads, no async — pure server component.
 const LAYOUT_TSX = `${MARKER_COMMENT}import type { Metadata } from "next";
 import Link from "next/link";
-import { TOKEN_DOMAINS } from "./tokenDomains";
 import { componentEntries } from "./componentMap";
 
 export const metadata: Metadata = {
@@ -183,6 +162,32 @@ export const metadata: Metadata = {
   robots: { index: false, follow: false },
 };
 
+// Single source of truth for the token-domain catalog. Imported by the
+// tokens page (renderer keys + empty-state link targets). Adding a new
+// domain means editing this list AND the matching renderer block in the
+// tokens page — surgical, two-file change.
+export type TokenDomain = {
+  slug: string;
+  label: string;
+  varPrefix: string;
+  tailwindDocs: string;
+};
+
+export const TOKEN_DOMAINS: TokenDomain[] = [
+  { slug: "colors", label: "Colors", varPrefix: "--color-", tailwindDocs: "https://tailwindcss.com/docs/colors" },
+  { slug: "spacing", label: "Spacing", varPrefix: "--spacing", tailwindDocs: "https://tailwindcss.com/docs/theme#spacing" },
+  { slug: "typography", label: "Typography", varPrefix: "--text-", tailwindDocs: "https://tailwindcss.com/docs/font-size" },
+  { slug: "font", label: "Font Families", varPrefix: "--font-", tailwindDocs: "https://tailwindcss.com/docs/font-family" },
+  { slug: "font-weight", label: "Font Weights", varPrefix: "--font-weight-", tailwindDocs: "https://tailwindcss.com/docs/font-weight" },
+  { slug: "tracking", label: "Tracking", varPrefix: "--tracking-", tailwindDocs: "https://tailwindcss.com/docs/letter-spacing" },
+  { slug: "leading", label: "Leading", varPrefix: "--leading-", tailwindDocs: "https://tailwindcss.com/docs/line-height" },
+  { slug: "radius", label: "Radius", varPrefix: "--radius-", tailwindDocs: "https://tailwindcss.com/docs/border-radius" },
+  { slug: "shadows", label: "Shadows", varPrefix: "--shadow-", tailwindDocs: "https://tailwindcss.com/docs/box-shadow" },
+  { slug: "breakpoint", label: "Breakpoints", varPrefix: "--breakpoint-", tailwindDocs: "https://tailwindcss.com/docs/responsive-design" },
+  { slug: "ease", label: "Easing", varPrefix: "--ease-", tailwindDocs: "https://tailwindcss.com/docs/transition-timing-function" },
+  { slug: "animate", label: "Animation", varPrefix: "--animate-", tailwindDocs: "https://tailwindcss.com/docs/animation" },
+];
+
 export default function DesignSystemDocsLayout({ children }: { children: React.ReactNode }) {
   return (
     <div className="flex min-h-screen bg-zinc-50 dark:bg-zinc-950 text-zinc-900 dark:text-zinc-100">
@@ -264,7 +269,7 @@ const INDEX_PAGE_TSX = `${MARKER_COMMENT}export default function DesignSystemInd
 const TOKENS_PAGE_TSX = `${MARKER_COMMENT}import fs from "node:fs/promises";
 import path from "node:path";
 import { notFound } from "next/navigation";
-import { TOKEN_DOMAINS, type TokenDomain } from "../../tokenDomains";
+import { TOKEN_DOMAINS, type TokenDomain } from "__LAYOUT_MODULE__";
 
 ${READ_CSS_SRC}
 
@@ -689,6 +694,5 @@ module.exports = {
   COMPONENT_PAGE_TSX,
   COMPONENT_ERROR_TSX,
   COMPONENT_MAP_TSX,
-  TOKEN_DOMAINS_TSX,
   PROP_TOGGLE_TSX,
 };

From 1d84ab06cb60c0d16170367a4bb35cf0baa107b5 Mon Sep 17 00:00:00 2001
From: Hugh Francis <hughfrancis89@gmail.com>
Date: Mon, 11 May 2026 19:22:50 -0400
Subject: [PATCH 29/79] sync-docs: inline PropToggle, drop error.tsx, bake prop
 schemas
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

7 files → 5. Of the 5, only componentMap.tsx churns per sync; the other 4
are committed once.

- error.tsx is gone. The user's call — they don't want a custom error
  surface there. Next.js's dev overlay shows runtime errors in dev; prod
  excludes the route. The "Not in static map" branch in the component
  page itself stays (it's not an error boundary, just a render path).
- PropToggle.tsx is inlined into the component page. To make that work,
  the component page becomes a client component. To make THAT work
  without losing prop introspection, parseProps moves to sync time: the
  installer reads each component's source via the lib's existing
  prop-parser.js and bakes the resulting `props` schema into each
  componentMap entry. The page reads schemas from componentMap — no
  runtime fs reads.
- componentMap.tsx's exports collapse to one (`components`) + the
  `getComponent(slug)` helper. The old `componentEntries` was redundant
  since `components` carries the same fields plus `Component` and `props`.
  Layout imports `components` directly.

Trade-off: editing a component's prop interface now requires a re-sync
to refresh the toggles. Consistent with the rest of the architecture —
adhd.config.ts changes already require re-sync, and now prop interfaces
do too.

The installer's stale-cleanup naturally removes PropToggle.tsx,
error.design-system.tsx, and tokenDomains.tsx on the next sync because
they carry the marker comment and aren't in the new target set.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 .../__tests__/route-installer.test.js         | 269 ++++++++-------
 .../lib/sync-docs/__tests__/templates.test.js | 104 ++----
 plugins/adhd/lib/sync-docs/route-installer.js |  45 ++-
 plugins/adhd/lib/sync-docs/templates.js       | 311 +++++++-----------
 4 files changed, 328 insertions(+), 401 deletions(-)

diff --git a/plugins/adhd/lib/sync-docs/__tests__/route-installer.test.js b/plugins/adhd/lib/sync-docs/__tests__/route-installer.test.js
index 0482484..dea5ec9 100644
--- a/plugins/adhd/lib/sync-docs/__tests__/route-installer.test.js
+++ b/plugins/adhd/lib/sync-docs/__tests__/route-installer.test.js
@@ -8,23 +8,40 @@ const os = require('node:os');
 const { installRoute, detectExistingInstall, renderComponentMap } = require('../route-installer');
 
 function makeTempProject() {
-  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'adhd-setup-'));
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'adhd-sync-'));
   fs.mkdirSync(path.join(root, 'app'), { recursive: true });
   return root;
 }
 
+// A fixture component the installer can read for prop-baking tests.
+function writeLogoFixture(root) {
+  const dir = path.join(root, 'components/design-system/logo');
+  fs.mkdirSync(dir, { recursive: true });
+  fs.writeFileSync(path.join(dir, 'index.tsx'), `
+export type LogoSize = "sm" | "md" | "lg";
+
+export interface LogoProps {
+  size: LogoSize;
+  inverted?: boolean;
+  title?: string;
+}
+
+export default function Logo(props: LogoProps) {
+  return null;
+}
+`);
+}
+
 const SAMPLE_COMPONENTS = [
   { slug: 'logo', rawPath: 'components/design-system/logo/index.tsx', importPath: '@/components/design-system/logo' },
 ];
 
-test('installRoute writes the full generated file set with .design-system suffix when prodExcluded', () => {
+test('installRoute writes the five generated files when prodExcluded', () => {
   const root = makeTempProject();
+  writeLogoFixture(root);
   installRoute(root, {
-    groupName: '(design-system)',
-    routeSegment: '-docs',
-    prodExcluded: true,
-    components: SAMPLE_COMPONENTS,
-    cssEntry: 'app/globals.css',
+    groupName: '(design-system)', routeSegment: '-docs', prodExcluded: true,
+    components: SAMPLE_COMPONENTS, cssEntry: 'app/globals.css',
   });
   const docsDir = path.join(root, 'app', '(design-system)', '-docs');
   // Route files get the suffix so pageExtensions filters them in prod.
@@ -32,44 +49,36 @@ test('installRoute writes the full generated file set with .design-system suffix
   assert.ok(fs.existsSync(path.join(docsDir, 'page.design-system.tsx')));
   assert.ok(fs.existsSync(path.join(docsDir, 'tokens', '[domain]', 'page.design-system.tsx')));
   assert.ok(fs.existsSync(path.join(docsDir, 'components', '[component]', 'page.design-system.tsx')));
-  assert.ok(fs.existsSync(path.join(docsDir, 'components', '[component]', 'error.design-system.tsx')));
-  // Shared modules (imported by the route files) are plain .tsx so TS resolves them.
+  // componentMap is a plain .tsx module so TS module resolution finds it.
   assert.ok(fs.existsSync(path.join(docsDir, 'componentMap.tsx')));
-  assert.ok(fs.existsSync(path.join(docsDir, 'PropToggle.tsx')));
-  assert.ok(!fs.existsSync(path.join(docsDir, 'componentMap.design-system.tsx')));
-  assert.ok(!fs.existsSync(path.join(docsDir, 'PropToggle.design-system.tsx')));
-  // tokenDomains.tsx no longer exists — the catalog is named-exported from the
-  // layout, and the tokens page imports it from there.
+  // Files we used to write but no longer do:
+  assert.ok(!fs.existsSync(path.join(docsDir, 'components', '[component]', 'error.design-system.tsx')));
+  assert.ok(!fs.existsSync(path.join(docsDir, 'components', '[component]', 'error.tsx')));
+  assert.ok(!fs.existsSync(path.join(docsDir, 'PropToggle.tsx')));
   assert.ok(!fs.existsSync(path.join(docsDir, 'tokenDomains.tsx')));
 });
 
 test('installRoute writes plain .tsx files for route files when not prodExcluded', () => {
   const root = makeTempProject();
+  writeLogoFixture(root);
   installRoute(root, {
-    groupName: '(design-system)',
-    routeSegment: '-docs',
-    prodExcluded: false,
-    components: SAMPLE_COMPONENTS,
-    cssEntry: 'app/globals.css',
+    groupName: '(design-system)', routeSegment: '-docs', prodExcluded: false,
+    components: SAMPLE_COMPONENTS, cssEntry: 'app/globals.css',
   });
   const docsDir = path.join(root, 'app', '(design-system)', '-docs');
   assert.ok(fs.existsSync(path.join(docsDir, 'layout.tsx')));
   assert.ok(fs.existsSync(path.join(docsDir, 'page.tsx')));
   assert.ok(fs.existsSync(path.join(docsDir, 'tokens', '[domain]', 'page.tsx')));
   assert.ok(fs.existsSync(path.join(docsDir, 'components', '[component]', 'page.tsx')));
-  assert.ok(fs.existsSync(path.join(docsDir, 'components', '[component]', 'error.tsx')));
   assert.ok(fs.existsSync(path.join(docsDir, 'componentMap.tsx')));
-  assert.ok(fs.existsSync(path.join(docsDir, 'PropToggle.tsx')));
 });
 
 test('all written files start with the marker comment', () => {
   const root = makeTempProject();
+  writeLogoFixture(root);
   installRoute(root, {
-    groupName: '(design-system)',
-    routeSegment: '-docs',
-    prodExcluded: true,
-    components: SAMPLE_COMPONENTS,
-    cssEntry: 'app/globals.css',
+    groupName: '(design-system)', routeSegment: '-docs', prodExcluded: true,
+    components: SAMPLE_COMPONENTS, cssEntry: 'app/globals.css',
   });
   const docsDir = path.join(root, 'app', '(design-system)', '-docs');
   for (const f of [
@@ -77,9 +86,7 @@ test('all written files start with the marker comment', () => {
     'page.design-system.tsx',
     'tokens/[domain]/page.design-system.tsx',
     'components/[component]/page.design-system.tsx',
-    'components/[component]/error.design-system.tsx',
     'componentMap.tsx',
-    'PropToggle.tsx',
   ]) {
     const content = fs.readFileSync(path.join(docsDir, f), 'utf8');
     assert.match(content, /design-system-docs-route/, `${f} missing marker`);
@@ -88,74 +95,79 @@ test('all written files start with the marker comment', () => {
 
 test('componentMap.tsx has explicit static imports per registered component', () => {
   const root = makeTempProject();
+  writeLogoFixture(root);
   installRoute(root, {
-    groupName: '(design-system)',
-    routeSegment: '-docs',
-    prodExcluded: true,
-    components: SAMPLE_COMPONENTS,
-    cssEntry: 'app/globals.css',
+    groupName: '(design-system)', routeSegment: '-docs', prodExcluded: true,
+    components: SAMPLE_COMPONENTS, cssEntry: 'app/globals.css',
   });
-  const mapPath = path.join(root, 'app', '(design-system)', '-docs', 'componentMap.tsx');
-  const body = fs.readFileSync(mapPath, 'utf8');
-  // Explicit import for the logo component
+  const body = fs.readFileSync(
+    path.join(root, 'app', '(design-system)', '-docs', 'componentMap.tsx'),
+    'utf8',
+  );
   assert.match(body, /import \* as \$cmp0 from "@\/components\/design-system\/logo"/);
-  // Entry with matching slug and rawPath
   assert.match(body, /slug: "logo"/);
   assert.match(body, /rawPath: "components\/design-system\/logo\/index\.tsx"/);
   assert.match(body, /module: \$cmp0/);
-  // No dynamic import — that's the whole point of this rewrite
   assert.doesNotMatch(body, /await\s+import\(`/);
 });
 
-test('componentMap.tsx handles an empty components list (no tracked components yet)', () => {
+test('componentMap.tsx bakes prop schemas read from each component source at sync time', () => {
+  // The component page no longer does fs reads — props are baked here. Test
+  // verifies that the LogoProps interface (size: union, inverted: boolean,
+  // title: string) is preserved verbatim in the generated map.
   const root = makeTempProject();
+  writeLogoFixture(root);
   installRoute(root, {
-    groupName: '(design-system)',
-    routeSegment: '-docs',
-    prodExcluded: true,
-    components: [],
-    cssEntry: 'app/globals.css',
+    groupName: '(design-system)', routeSegment: '-docs', prodExcluded: true,
+    components: SAMPLE_COMPONENTS, cssEntry: 'app/globals.css',
+  });
+  const body = fs.readFileSync(
+    path.join(root, 'app', '(design-system)', '-docs', 'componentMap.tsx'),
+    'utf8',
+  );
+  // The whole entry is a single JS line — match the inline JSON body.
+  assert.match(body, /props: \{[^}]*"size":\{"type":"union","values":\["sm","md","lg"\],"optional":false\}/);
+  assert.match(body, /"inverted":\{"type":"boolean","optional":true\}/);
+  assert.match(body, /"title":\{"type":"string","optional":true\}/);
+});
+
+test('componentMap.tsx handles an empty components list', () => {
+  const root = makeTempProject();
+  installRoute(root, {
+    groupName: '(design-system)', routeSegment: '-docs', prodExcluded: true,
+    components: [], cssEntry: 'app/globals.css',
   });
   const body = fs.readFileSync(
     path.join(root, 'app', '(design-system)', '-docs', 'componentMap.tsx'),
     'utf8',
   );
-  // No import lines for components — placeholder substituted with empty string
   assert.doesNotMatch(body, /import \* as \$cmp/);
-  // ENTRIES is an empty array literal
   assert.match(body, /const ENTRIES.*=\s*\[\]/);
 });
 
-test('componentMap.tsx renders multiple components with distinct import bindings', () => {
+test('componentMap.tsx handles a missing component source file (empty props baked)', () => {
+  // If a component listed in adhd.config.ts doesn't exist on disk, sync shouldn't
+  // crash — it bakes `{}` for that entry's props. The page then shows "No prop
+  // interface detected at sync time" which is the right signal.
   const root = makeTempProject();
+  // Note: we DON'T call writeLogoFixture — the file is missing on purpose.
   installRoute(root, {
-    groupName: '(design-system)',
-    routeSegment: '-docs',
-    prodExcluded: true,
-    components: [
-      { slug: 'logo', rawPath: 'src/components/Logo.tsx', importPath: '@/src/components/Logo' },
-      { slug: 'button', rawPath: 'src/components/Button/index.tsx', importPath: '@/src/components/Button' },
-    ],
-    cssEntry: 'app/globals.css',
+    groupName: '(design-system)', routeSegment: '-docs', prodExcluded: true,
+    components: SAMPLE_COMPONENTS, cssEntry: 'app/globals.css',
   });
   const body = fs.readFileSync(
     path.join(root, 'app', '(design-system)', '-docs', 'componentMap.tsx'),
     'utf8',
   );
-  assert.match(body, /import \* as \$cmp0 from "@\/src\/components\/Logo"/);
-  assert.match(body, /import \* as \$cmp1 from "@\/src\/components\/Button"/);
-  assert.match(body, /slug: "logo".*module: \$cmp0/s);
-  assert.match(body, /slug: "button".*module: \$cmp1/s);
+  assert.match(body, /props: \{\}/);
 });
 
 test('layout sidebar links use absolute hrefs derived from the route segment', () => {
   const root = makeTempProject();
+  writeLogoFixture(root);
   installRoute(root, {
-    groupName: '(design-system)',
-    routeSegment: '-docs',
-    prodExcluded: true,
-    components: SAMPLE_COMPONENTS,
-    cssEntry: 'app/globals.css',
+    groupName: '(design-system)', routeSegment: '-docs', prodExcluded: true,
+    components: SAMPLE_COMPONENTS, cssEntry: 'app/globals.css',
   });
   const layout = fs.readFileSync(
     path.join(root, 'app', '(design-system)', '-docs', 'layout.design-system.tsx'),
@@ -166,31 +178,24 @@ test('layout sidebar links use absolute hrefs derived from the route segment', (
   assert.doesNotMatch(layout, /__ROUTE_PATH__/);
 });
 
-test('layout imports componentEntries from componentMap (the sidebar list source)', () => {
+test('layout imports the static components array from componentMap', () => {
   const root = makeTempProject();
+  writeLogoFixture(root);
   installRoute(root, {
-    groupName: '(design-system)',
-    routeSegment: '-docs',
-    prodExcluded: true,
-    components: SAMPLE_COMPONENTS,
-    cssEntry: 'app/globals.css',
+    groupName: '(design-system)', routeSegment: '-docs', prodExcluded: true,
+    components: SAMPLE_COMPONENTS, cssEntry: 'app/globals.css',
   });
   const layout = fs.readFileSync(
     path.join(root, 'app', '(design-system)', '-docs', 'layout.design-system.tsx'),
     'utf8',
   );
-  assert.match(layout, /from "\.\/componentMap"/);
-  assert.match(layout, /componentEntries/);
-  // No fs/path imports — the components list is baked at install time so the
-  // layout doesn't need to read adhd.config.ts at request time.
+  assert.match(layout, /import \{ components \} from "\.\/componentMap"/);
   assert.doesNotMatch(layout, /from "node:fs|from "node:path/);
 });
 
 test('tokens page imports TOKEN_DOMAINS from layout.design-system when prodExcluded', () => {
-  // The layout file's basename has `.design-system` when prod-excluded, and the
-  // tokens page must use that basename in its import so TS's bundler resolution
-  // adds `.tsx` and finds it.
   const root = makeTempProject();
+  writeLogoFixture(root);
   installRoute(root, {
     groupName: '(design-system)', routeSegment: '-docs', prodExcluded: true,
     components: SAMPLE_COMPONENTS, cssEntry: 'app/globals.css',
@@ -205,6 +210,7 @@ test('tokens page imports TOKEN_DOMAINS from layout.design-system when prodExclu
 
 test('tokens page imports TOKEN_DOMAINS from layout (no suffix) when not prodExcluded', () => {
   const root = makeTempProject();
+  writeLogoFixture(root);
   installRoute(root, {
     groupName: '(design-system)', routeSegment: '-docs', prodExcluded: false,
     components: SAMPLE_COMPONENTS, cssEntry: 'app/globals.css',
@@ -217,70 +223,52 @@ test('tokens page imports TOKEN_DOMAINS from layout (no suffix) when not prodExc
   assert.doesNotMatch(tokensPage, /__LAYOUT_MODULE__/);
 });
 
-test('re-sync removes stale tokenDomains.tsx from a previous template layout', () => {
-  // Mirrors the actual upgrade path: previous installer versions wrote
-  // tokenDomains.tsx alongside componentMap.tsx. Re-syncing should clean it up.
-  const root = makeTempProject();
-  const docsDir = path.join(root, 'app', '(design-system)', '-docs');
-  fs.mkdirSync(docsDir, { recursive: true });
-  const stalePath = path.join(docsDir, 'tokenDomains.tsx');
-  fs.writeFileSync(stalePath, '// design-system-docs-route — stale\nexport const TOKEN_DOMAINS = [];\n');
-
-  const r = installRoute(root, {
-    groupName: '(design-system)', routeSegment: '-docs', prodExcluded: true,
-    components: SAMPLE_COMPONENTS, cssEntry: 'app/globals.css',
-  });
-
-  assert.ok(!fs.existsSync(stalePath), 'stale tokenDomains.tsx should be removed');
-  assert.ok(r.removed.includes(stalePath));
-});
-
 test('tokens page bakes the configured cssEntry path as a constant', () => {
   const root = makeTempProject();
+  writeLogoFixture(root);
   installRoute(root, {
-    groupName: '(design-system)',
-    routeSegment: '-docs',
-    prodExcluded: true,
-    components: SAMPLE_COMPONENTS,
-    cssEntry: 'src/app/globals.css',
+    groupName: '(design-system)', routeSegment: '-docs', prodExcluded: true,
+    components: SAMPLE_COMPONENTS, cssEntry: 'src/app/globals.css',
   });
   const tokensPage = fs.readFileSync(
     path.join(root, 'app', '(design-system)', '-docs', 'tokens', '[domain]', 'page.design-system.tsx'),
     'utf8',
   );
   assert.match(tokensPage, /CSS_ENTRY = "src\/app\/globals\.css"/);
-  // No runtime read of adhd.config.ts
   assert.doesNotMatch(tokensPage, /adhd\.config\.ts/);
 });
 
-test('component page imports getComponent from componentMap, not a dynamic import', () => {
+test('component page is a client component with inline PropToggle and no fs reads', () => {
   const root = makeTempProject();
+  writeLogoFixture(root);
   installRoute(root, {
-    groupName: '(design-system)',
-    routeSegment: '-docs',
-    prodExcluded: true,
-    components: SAMPLE_COMPONENTS,
-    cssEntry: 'app/globals.css',
+    groupName: '(design-system)', routeSegment: '-docs', prodExcluded: true,
+    components: SAMPLE_COMPONENTS, cssEntry: 'app/globals.css',
   });
   const componentPage = fs.readFileSync(
     path.join(root, 'app', '(design-system)', '-docs', 'components', '[component]', 'page.design-system.tsx'),
     'utf8',
   );
-  assert.match(componentPage, /import \{ getComponent \} from "\.\.\/\.\.\/componentMap"/);
-  assert.match(componentPage, /import \{ PropToggle \} from "\.\.\/\.\.\/PropToggle"/);
-  // No broad dynamic import — that's what the rewrite eliminates
-  assert.doesNotMatch(componentPage, /await\s+import\(`@\//);
+  // "use client" sits after the marker comment (two `//` lines), so strip leading
+  // comments before checking the directive is the first real statement.
+  assert.match(componentPage.replace(/^(?:\/\/[^\n]*\n)+/, ''), /^["']use client["']/);
+  // Uses hooks instead of async params/searchParams.
+  assert.match(componentPage, /useParams/);
+  assert.match(componentPage, /useSearchParams/);
+  assert.match(componentPage, /useRouter/);
+  // PropToggle is inlined, not imported.
+  assert.match(componentPage, /function PropToggle\(/);
+  assert.doesNotMatch(componentPage, /from "\.\.\/PropToggle"|from "\.\.\/\.\.\/PropToggle"/);
+  // No fs reads — everything's baked into componentMap.
+  assert.doesNotMatch(componentPage, /from "node:fs|from "node:path/);
 });
 
 test('component page shows a "not in static map" message when slug is missing', () => {
-  // This is the new UX for "user added to adhd.config.ts but didn't re-run setup."
   const root = makeTempProject();
+  writeLogoFixture(root);
   installRoute(root, {
-    groupName: '(design-system)',
-    routeSegment: '-docs',
-    prodExcluded: true,
-    components: SAMPLE_COMPONENTS,
-    cssEntry: 'app/globals.css',
+    groupName: '(design-system)', routeSegment: '-docs', prodExcluded: true,
+    components: SAMPLE_COMPONENTS, cssEntry: 'app/globals.css',
   });
   const componentPage = fs.readFileSync(
     path.join(root, 'app', '(design-system)', '-docs', 'components', '[component]', 'page.design-system.tsx'),
@@ -292,15 +280,13 @@ test('component page shows a "not in static map" message when slug is missing',
 
 test('detectExistingInstall returns marker-bearing files', () => {
   const root = makeTempProject();
+  writeLogoFixture(root);
   installRoute(root, {
-    groupName: '(design-system)',
-    routeSegment: '-docs',
-    prodExcluded: true,
-    components: SAMPLE_COMPONENTS,
-    cssEntry: 'app/globals.css',
+    groupName: '(design-system)', routeSegment: '-docs', prodExcluded: true,
+    components: SAMPLE_COMPONENTS, cssEntry: 'app/globals.css',
   });
   const found = detectExistingInstall(root);
-  assert.ok(found.length >= 7);
+  assert.ok(found.length >= 5);
   assert.ok(found.every(p => p.includes('-docs')));
 });
 
@@ -311,6 +297,7 @@ test('detectExistingInstall returns [] when no marker is present', () => {
 
 test('re-running installRoute overwrites files cleanly', () => {
   const root = makeTempProject();
+  writeLogoFixture(root);
   installRoute(root, {
     groupName: '(design-system)', routeSegment: '-docs', prodExcluded: true,
     components: SAMPLE_COMPONENTS, cssEntry: 'app/globals.css',
@@ -326,28 +313,35 @@ test('re-running installRoute overwrites files cleanly', () => {
   assert.match(after, /DesignSystemDocsLayout/);
 });
 
-test('installRoute removes stale marker-bearing files from a previous layout', () => {
-  // Simulate an older install where the dynamic-import-era component page
-  // lived at `[component]/page` directly under docsDir.
+test('re-sync removes stale files from previous template layouts', () => {
+  // Mirrors actual upgrade paths: previous installer versions wrote a separate
+  // tokenDomains.tsx + PropToggle.tsx + error.design-system.tsx. Re-syncing
+  // should clean them all up because they carry the marker.
   const root = makeTempProject();
+  writeLogoFixture(root);
   const docsDir = path.join(root, 'app', '(design-system)', '-docs');
-  const oldCompDir = path.join(docsDir, '[component]');
-  fs.mkdirSync(oldCompDir, { recursive: true });
-  const oldPath = path.join(oldCompDir, 'page.design-system.tsx');
-  fs.writeFileSync(oldPath, '// design-system-docs-route — stale\nexport {};\n');
+  fs.mkdirSync(path.join(docsDir, 'components', '[component]'), { recursive: true });
+  const stale = [
+    path.join(docsDir, 'tokenDomains.tsx'),
+    path.join(docsDir, 'PropToggle.tsx'),
+    path.join(docsDir, 'components', '[component]', 'error.design-system.tsx'),
+  ];
+  for (const p of stale) fs.writeFileSync(p, '// design-system-docs-route — stale\nexport {};\n');
 
   const r = installRoute(root, {
     groupName: '(design-system)', routeSegment: '-docs', prodExcluded: true,
     components: SAMPLE_COMPONENTS, cssEntry: 'app/globals.css',
   });
 
-  assert.ok(!fs.existsSync(oldPath));
-  assert.ok(r.removed.includes(oldPath));
-  assert.ok(!fs.existsSync(oldCompDir));
+  for (const p of stale) {
+    assert.ok(!fs.existsSync(p), `stale ${path.basename(p)} should be removed`);
+    assert.ok(r.removed.includes(p));
+  }
 });
 
 test('installRoute preserves user files that lack the marker', () => {
   const root = makeTempProject();
+  writeLogoFixture(root);
   const docsDir = path.join(root, 'app', '(design-system)', '-docs');
   fs.mkdirSync(docsDir, { recursive: true });
   const userFile = path.join(docsDir, 'user-notes.tsx');
@@ -363,6 +357,7 @@ test('installRoute preserves user files that lack the marker', () => {
 
 test('installRoute supports an empty groupName (no route group)', () => {
   const root = makeTempProject();
+  writeLogoFixture(root);
   installRoute(root, {
     groupName: '', routeSegment: '-docs', prodExcluded: true,
     components: SAMPLE_COMPONENTS, cssEntry: 'app/globals.css',
@@ -372,11 +367,15 @@ test('installRoute supports an empty groupName (no route group)', () => {
   assert.ok(fs.existsSync(path.join(docsDir, 'componentMap.tsx')));
 });
 
-test('renderComponentMap is exposed (standalone snapshot of the map source)', () => {
-  const body = renderComponentMap([
+test('renderComponentMap is exposed (standalone snapshot helper, takes projectRoot)', () => {
+  // The renderComponentMap export takes (projectRoot, components) so it can
+  // read each component's source file for prop baking. With a non-existent
+  // root, props bake to {} but the rest of the output is well-formed.
+  const body = renderComponentMap('/nonexistent', [
     { slug: 'logo', rawPath: 'components/Logo.tsx', importPath: '@/components/Logo' },
   ]);
   assert.match(body, /design-system-docs-route/);
   assert.match(body, /import \* as \$cmp0 from "@\/components\/Logo"/);
   assert.match(body, /slug: "logo"/);
+  assert.match(body, /props: \{\}/);
 });
diff --git a/plugins/adhd/lib/sync-docs/__tests__/templates.test.js b/plugins/adhd/lib/sync-docs/__tests__/templates.test.js
index e8eba0f..f0aef54 100644
--- a/plugins/adhd/lib/sync-docs/__tests__/templates.test.js
+++ b/plugins/adhd/lib/sync-docs/__tests__/templates.test.js
@@ -8,9 +8,7 @@ const {
   INDEX_PAGE_TSX,
   TOKENS_PAGE_TSX,
   COMPONENT_PAGE_TSX,
-  COMPONENT_ERROR_TSX,
   COMPONENT_MAP_TSX,
-  PROP_TOGGLE_TSX,
 } = require('../templates');
 
 test('MARKER_COMMENT is a stable, non-ADHD-referencing string', () => {
@@ -29,8 +27,6 @@ test('LAYOUT_TSX sets robots: noindex / nofollow', () => {
 
 test('LAYOUT_TSX declares and named-exports the TOKEN_DOMAINS catalog', () => {
   // Single source of truth lives in the layout. Tokens page imports it from there.
-  // The catalog covers every Tailwind v4 token domain with its varPrefix and
-  // Tailwind docs link (used for empty-state messaging on each domain page).
   assert.match(LAYOUT_TSX, /export const TOKEN_DOMAINS: TokenDomain\[\]/);
   assert.match(LAYOUT_TSX, /export type TokenDomain/);
   for (const label of [
@@ -48,119 +44,87 @@ test('TOKENS_PAGE_TSX imports the catalog from the layout via a __LAYOUT_MODULE_
   assert.match(TOKENS_PAGE_TSX, /import \{ TOKEN_DOMAINS, type TokenDomain \} from "__LAYOUT_MODULE__"/);
 });
 
-test('LAYOUT_TSX imports componentEntries from componentMap (no runtime config read)', () => {
-  // Static architecture: the layout doesn't read adhd.config.ts at request time.
-  // Instead, the installer generates componentMap.tsx with the components baked in,
-  // and the layout imports componentEntries from it.
-  assert.match(LAYOUT_TSX, /from "\.\/componentMap"/);
-  assert.match(LAYOUT_TSX, /componentEntries/);
-  // No fs/path imports — the layout is a pure render now
-  assert.doesNotMatch(LAYOUT_TSX, /from "node:fs|from "node:path|readConfig\(/);
+test('LAYOUT_TSX imports the static components array from componentMap', () => {
+  assert.match(LAYOUT_TSX, /import \{ components \} from "\.\/componentMap"/);
+  // No fs/path imports — the layout is a pure render.
+  assert.doesNotMatch(LAYOUT_TSX, /from "node:fs|from "node:path/);
 });
 
-test('LAYOUT_TSX is a sync (non-async) server component now', () => {
-  // No fs reads anywhere in the layout; it's a pure render.
+test('LAYOUT_TSX is a sync (non-async) server component', () => {
   assert.doesNotMatch(LAYOUT_TSX, /export default async function/);
   assert.match(LAYOUT_TSX, /export default function DesignSystemDocsLayout/);
 });
 
-test('LAYOUT_TSX has no diagnostic banner (removed with the dynamic-import architecture)', () => {
-  // The DiagnosticBanner existed to flag missing tokens that surfaced under the
-  // broad dynamic import. Static imports eliminate that failure mode entirely.
-  assert.doesNotMatch(LAYOUT_TSX, /DiagnosticBanner|detectIssues|ring-offset-background/);
-});
-
 test('INDEX_PAGE_TSX is a landing page describing the static-import flow', () => {
   assert.match(INDEX_PAGE_TSX, /Design System/);
   assert.match(INDEX_PAGE_TSX, /statically imported/);
   assert.match(INDEX_PAGE_TSX, /re-run/);
 });
 
-test('INDEX_PAGE_TSX has no Troubleshooting section (each route handles its own failure modes)', () => {
-  // The component page surfaces "not in static map" itself; error.tsx catches
-  // runtime crashes; token pages link to Tailwind docs for empty domains.
-  // The landing page just orients the user — no duplicated troubleshooting copy.
+test('INDEX_PAGE_TSX has no Troubleshooting section', () => {
   assert.doesNotMatch(INDEX_PAGE_TSX, /Troubleshooting/);
-  assert.doesNotMatch(INDEX_PAGE_TSX, /app-build-manifest|broad dynamic/i);
-  // It still mentions the re-run command so the user knows how to refresh the map.
   assert.match(INDEX_PAGE_TSX, /\/adhd:sync-docs/);
 });
 
 test('TOKENS_PAGE_TSX reads globals.css from a baked CSS_ENTRY constant', () => {
   assert.match(TOKENS_PAGE_TSX, /const CSS_ENTRY = "__CSS_ENTRY__"/);
   assert.match(TOKENS_PAGE_TSX, /parseTokens/);
-  // Tokens page no longer reads adhd.config.ts at request time
-  assert.doesNotMatch(TOKENS_PAGE_TSX, /readConfig|adhd\.config\.ts/);
+  assert.doesNotMatch(TOKENS_PAGE_TSX, /adhd\.config\.ts/);
 });
 
 test('TOKENS_PAGE_TSX does not inline the TOKEN_DOMAINS list', () => {
-  // The inline catalog from earlier versions is gone — the page imports from the layout.
   assert.doesNotMatch(TOKENS_PAGE_TSX, /const TOKEN_DOMAINS = \[/);
 });
 
-test('COMPONENT_PAGE_TSX uses getComponent from the static componentMap (no dynamic import)', () => {
-  assert.match(COMPONENT_PAGE_TSX, /import \{ getComponent \} from "\.\.\/\.\.\/componentMap"/);
-  // No template-literal dynamic import
+test('COMPONENT_PAGE_TSX is a client component', () => {
+  // The page must be a client component so PropToggle can be inlined and
+  // useSearchParams/useRouter can drive URL state without a separate file.
+  const afterMarker = COMPONENT_PAGE_TSX.replace(MARKER_COMMENT, '');
+  assert.match(afterMarker, /^["']use client["']/);
+});
+
+test('COMPONENT_PAGE_TSX uses getComponent from the static componentMap (no fs reads, no dynamic import)', () => {
+  assert.match(COMPONENT_PAGE_TSX, /import \{ components, getComponent, type PropSchema \} from "\.\.\/\.\.\/componentMap"/);
   assert.doesNotMatch(COMPONENT_PAGE_TSX, /await\s+import\(`/);
+  // No server-side fs reads — the page is fully client.
+  assert.doesNotMatch(COMPONENT_PAGE_TSX, /from "node:fs|from "node:path/);
 });
 
-test('COMPONENT_PAGE_TSX reads searchParams for prop toggles', () => {
-  assert.match(COMPONENT_PAGE_TSX, /searchParams/);
+test('COMPONENT_PAGE_TSX inlines PropToggle (no separate PropToggle.tsx file)', () => {
+  // The PropToggle UI lives in the page itself now. No import from "../PropToggle".
+  assert.match(COMPONENT_PAGE_TSX, /function PropToggle\(/);
+  assert.doesNotMatch(COMPONENT_PAGE_TSX, /from "\.\.\/PropToggle"|from "\.\.\/\.\.\/PropToggle"/);
+});
+
+test('COMPONENT_PAGE_TSX reads URL state via useSearchParams + useParams hooks', () => {
+  assert.match(COMPONENT_PAGE_TSX, /useParams/);
+  assert.match(COMPONENT_PAGE_TSX, /useSearchParams/);
+  assert.match(COMPONENT_PAGE_TSX, /router\.replace/);
 });
 
 test('COMPONENT_PAGE_TSX shows a "Not in the static map" branch for unknown slugs', () => {
-  // Replaces notFound() with an actionable message about re-running setup.
   assert.match(COMPONENT_PAGE_TSX, /Not in the static map/);
   assert.match(COMPONENT_PAGE_TSX, /re-run.*\/adhd:sync-docs/i);
 });
 
-test('COMPONENT_MAP_TSX has the substitution placeholders the installer needs', () => {
-  // The template is a per-install-generated file. These placeholders are
-  // filled in by route-installer.js's renderComponentMap.
+test('COMPONENT_MAP_TSX has the substitution placeholders the installer fills in', () => {
   assert.match(COMPONENT_MAP_TSX, /__COMPONENT_IMPORTS__/);
   assert.match(COMPONENT_MAP_TSX, /__COMPONENT_ENTRIES__/);
   assert.match(COMPONENT_MAP_TSX, /export function getComponent/);
-  assert.match(COMPONENT_MAP_TSX, /export const componentEntries/);
+  assert.match(COMPONENT_MAP_TSX, /export const components/);
+  assert.match(COMPONENT_MAP_TSX, /export type PropSchema/);
 });
 
 test('COMPONENT_MAP_TSX resolves a renderable function via default-then-named fallback', () => {
-  // Mirrors the runtime behavior of the previous dynamic-import resolution:
-  // prefer default export, fall back to first named function. This keeps
-  // existing user components working without changes.
   assert.match(COMPONENT_MAP_TSX, /function resolveComponent/);
   assert.match(COMPONENT_MAP_TSX, /mod\.default/);
 });
 
-test('PROP_TOGGLE_TSX is a client component', () => {
-  const afterMarker = PROP_TOGGLE_TSX.replace(MARKER_COMMENT, '');
-  assert.match(afterMarker, /^["']use client["']/);
-});
-
-test('PROP_TOGGLE_TSX uses router.replace for snappy URL updates', () => {
-  assert.match(PROP_TOGGLE_TSX, /router\.replace/);
-});
-
-test('COMPONENT_ERROR_TSX is a client component error boundary', () => {
-  const afterMarker = COMPONENT_ERROR_TSX.replace(MARKER_COMMENT, '');
-  assert.match(afterMarker, /^["']use client["']/);
-  assert.match(COMPONENT_ERROR_TSX, /error.*reset/);
-  assert.match(COMPONENT_ERROR_TSX, /reset\(\)/);
-});
-
-test('COMPONENT_ERROR_TSX no longer has the build-manifest-specific copy', () => {
-  // With static imports, the build-manifest ENOENT failure mode is gone, so
-  // the error boundary no longer needs to special-case it.
-  assert.doesNotMatch(COMPONENT_ERROR_TSX, /app-build-manifest|isBuildManifestError/);
-});
-
 test('none of the templates contain "ADHD" outside the marker', () => {
-  // Two filename-style exceptions are allowed (they're how the user actually
-  // interacts with the tool, and ejecting from ADHD doesn't break the file —
-  // it just means those references become vestigial guidance the user can edit):
+  // Two filename-style exceptions are allowed:
   //   1. `adhd.config.ts` — the consumer's own config artifact.
-  //   2. `/adhd:sync-docs` — the slash command name,
-  //      referenced in troubleshooting copy so the user knows what to re-run.
-  const all = { LAYOUT_TSX, INDEX_PAGE_TSX, TOKENS_PAGE_TSX, COMPONENT_PAGE_TSX, COMPONENT_ERROR_TSX, COMPONENT_MAP_TSX, PROP_TOGGLE_TSX };
+  //   2. `/adhd:sync-docs` — the slash command name, referenced in re-run copy.
+  const all = { LAYOUT_TSX, INDEX_PAGE_TSX, TOKENS_PAGE_TSX, COMPONENT_PAGE_TSX, COMPONENT_MAP_TSX };
   for (const [name, content] of Object.entries(all)) {
     const body = content
       .replace(MARKER_COMMENT, '')
diff --git a/plugins/adhd/lib/sync-docs/route-installer.js b/plugins/adhd/lib/sync-docs/route-installer.js
index 37f3d92..fac463d 100644
--- a/plugins/adhd/lib/sync-docs/route-installer.js
+++ b/plugins/adhd/lib/sync-docs/route-installer.js
@@ -7,10 +7,9 @@ const {
   INDEX_PAGE_TSX,
   TOKENS_PAGE_TSX,
   COMPONENT_PAGE_TSX,
-  COMPONENT_ERROR_TSX,
   COMPONENT_MAP_TSX,
-  PROP_TOGGLE_TSX,
 } = require('./templates');
+const { parseProps } = require('./prop-parser');
 
 const MARKER_STR = 'design-system-docs-route';
 
@@ -18,15 +17,45 @@ function mkdirpSync(p) {
   fs.mkdirSync(p, { recursive: true });
 }
 
+// Reads a component's source file and returns a sync-time-baked prop schema
+// suitable for embedding in componentMap.tsx. The schema mirrors the runtime
+// PropSchema type in the template — only the shape the page actually uses
+// (type + optional values for unions + the `optional` flag).
+function bakedPropsFor(projectRoot, rawPath) {
+  const fullPath = path.join(projectRoot, rawPath);
+  let src;
+  try { src = fs.readFileSync(fullPath, 'utf8'); }
+  catch { return {}; }
+  const { props } = parseProps(src);
+  const out = {};
+  for (const [name, def] of Object.entries(props)) {
+    // The page only renders toggles for these four shapes; everything else
+    // shows up as "toggle unavailable" so collapsing to "unknown" is fine.
+    if (def.type === 'union' && Array.isArray(def.values)) {
+      out[name] = { type: 'union', values: def.values, optional: !!def.optional };
+    } else if (def.type === 'boolean' || def.type === 'string' || def.type === 'number') {
+      out[name] = { type: def.type, optional: !!def.optional };
+    } else {
+      out[name] = { type: 'unknown', optional: !!def.optional };
+    }
+  }
+  return out;
+}
+
 // Build the import + entries source for componentMap.tsx from the parsed
-// adhd.config.ts components list. Empty list is fine — the map exports an
-// empty array and the layout's sidebar shows a friendly "none tracked" message.
-function renderComponentMap(components) {
+// adhd.config.ts components list. Each entry includes baked prop schemas so
+// the component page doesn't need to do any fs reads at request time. Empty
+// list is fine — the map exports an empty `components` array and the layout's
+// sidebar shows a friendly "none tracked" message.
+function renderComponentMap(projectRoot, components) {
   const imports = components
     .map((c, i) => `import * as $cmp${i} from "${c.importPath}";`)
     .join('\n');
   const entries = components
-    .map((c, i) => `  { slug: ${JSON.stringify(c.slug)}, rawPath: ${JSON.stringify(c.rawPath)}, module: $cmp${i} },`)
+    .map((c, i) => {
+      const props = JSON.stringify(bakedPropsFor(projectRoot, c.rawPath));
+      return `  { slug: ${JSON.stringify(c.slug)}, rawPath: ${JSON.stringify(c.rawPath)}, module: $cmp${i}, props: ${props} },`;
+    })
     .join('\n');
   return COMPONENT_MAP_TSX
     .replace('__COMPONENT_IMPORTS__', imports)
@@ -67,9 +96,7 @@ function installRoute(projectRoot, opts) {
     { abs: path.join(docsDir, `page${pageExt}`), body: INDEX_PAGE_TSX },
     { abs: path.join(tokensDir, `page${pageExt}`), body: TOKENS_PAGE_TSX },
     { abs: path.join(componentsDir, `page${pageExt}`), body: COMPONENT_PAGE_TSX },
-    { abs: path.join(componentsDir, `error${pageExt}`), body: COMPONENT_ERROR_TSX },
-    { abs: path.join(docsDir, `componentMap${moduleExt}`), body: renderComponentMap(components) },
-    { abs: path.join(docsDir, `PropToggle${moduleExt}`), body: PROP_TOGGLE_TSX },
+    { abs: path.join(docsDir, `componentMap${moduleExt}`), body: renderComponentMap(projectRoot, components) },
   ];
 
   // The tokens page imports TOKEN_DOMAINS from the layout. The layout file's
diff --git a/plugins/adhd/lib/sync-docs/templates.js b/plugins/adhd/lib/sync-docs/templates.js
index bb93828..b94ece7 100644
--- a/plugins/adhd/lib/sync-docs/templates.js
+++ b/plugins/adhd/lib/sync-docs/templates.js
@@ -119,12 +119,33 @@ function parseTokens(css: string | null) {
 const COMPONENT_MAP_TSX = `${MARKER_COMMENT}import type React from "react";
 __COMPONENT_IMPORTS__
 
-type ModuleShape = Record<string, unknown>;
+// PropSchema is baked at sync time from each component's TypeScript prop
+// interface (via the lib's prop-parser). Re-run \`/adhd:sync-docs\` after
+// editing a component's props to refresh this file.
+export type PropSchema = {
+  type: "union" | "boolean" | "string" | "number" | "unknown";
+  values?: readonly string[];
+  optional: boolean;
+};
+
+export type ComponentEntry = {
+  slug: string;
+  rawPath: string;
+  Component: React.ComponentType<any> | null;
+  props: Record<string, PropSchema>;
+};
+
+type RawEntry = {
+  slug: string;
+  rawPath: string;
+  module: Record<string, unknown>;
+  props: Record<string, PropSchema>;
+};
 
-// Resolve the renderable function from a module: prefer the default export,
-// fall back to the first exported function. Mirrors the previous runtime
-// resolution behavior so existing user components keep working.
-function resolveComponent(mod: ModuleShape): React.ComponentType<any> | null {
+// Resolve the renderable function: prefer the default export, then the
+// first exported function. Keeps user components working without forcing
+// a particular export style.
+function resolveComponent(mod: Record<string, unknown>): React.ComponentType<any> | null {
   if (typeof mod.default === "function") return mod.default as React.ComponentType<any>;
   for (const v of Object.values(mod)) {
     if (typeof v === "function") return v as React.ComponentType<any>;
@@ -132,21 +153,17 @@ function resolveComponent(mod: ModuleShape): React.ComponentType<any> | null {
   return null;
 }
 
-export type ComponentEntry = {
-  slug: string;
-  rawPath: string;
-  Component: React.ComponentType<any> | null;
-};
-
-const ENTRIES: Array<{ slug: string; rawPath: string; module: ModuleShape }> = __COMPONENT_ENTRIES__;
+const ENTRIES: RawEntry[] = __COMPONENT_ENTRIES__;
 
-export const componentEntries: Array<{ slug: string; rawPath: string }> =
-  ENTRIES.map(e => ({ slug: e.slug, rawPath: e.rawPath }));
+export const components: ComponentEntry[] = ENTRIES.map(e => ({
+  slug: e.slug,
+  rawPath: e.rawPath,
+  Component: resolveComponent(e.module),
+  props: e.props,
+}));
 
-export function getComponent(slug: string): ComponentEntry | null {
-  const entry = ENTRIES.find(e => e.slug === slug);
-  if (!entry) return null;
-  return { slug: entry.slug, rawPath: entry.rawPath, Component: resolveComponent(entry.module) };
+export function getComponent(slug: string): ComponentEntry | undefined {
+  return components.find(c => c.slug === slug);
 }
 `;
 
@@ -155,7 +172,7 @@ export function getComponent(slug: string): ComponentEntry | null {
 // No fs reads, no async — pure server component.
 const LAYOUT_TSX = `${MARKER_COMMENT}import type { Metadata } from "next";
 import Link from "next/link";
-import { componentEntries } from "./componentMap";
+import { components } from "./componentMap";
 
 export const metadata: Metadata = {
   title: "Design System Docs",
@@ -213,11 +230,11 @@ export default function DesignSystemDocsLayout({ children }: { children: React.R
 
           <section>
             <h2 className="mb-2 text-[10px] font-medium uppercase tracking-wide text-zinc-500">Components</h2>
-            {componentEntries.length === 0 ? (
+            {components.length === 0 ? (
               <p className="text-xs text-zinc-500 px-2">None tracked. Add to <code>adhd.config.ts</code> and re-run <code>/adhd:sync-docs</code>.</p>
             ) : (
               <ul className="flex flex-col gap-1">
-                {componentEntries.map(c => (
+                {components.map(c => (
                   <li key={c.slug}>
                     <Link href={\`__ROUTE_PATH__/components/\${c.slug}\`} className="block rounded px-2 py-1 hover:bg-zinc-200 dark:hover:bg-zinc-800">
                       {c.slug}
@@ -468,97 +485,93 @@ export default async function TokensDomainPage({ params }: { params: Promise<{ d
 }
 `;
 
-// Component page — uses the statically generated componentMap. No fs reads of
-// adhd.config.ts at request time; the rawPath comes from the map. The page
-// still reads the component's source via fs to introspect prop interfaces
-// (that's a one-file read per request, not a bundle).
-const COMPONENT_PAGE_TSX = `${MARKER_COMMENT}import fs from "node:fs/promises";
-import path from "node:path";
-import { PropToggle } from "../../PropToggle";
-import { getComponent } from "../../componentMap";
-
-async function parseProps(componentPath: string) {
-  try {
-    const src = await fs.readFile(path.resolve(process.cwd(), componentPath), "utf8");
-    const TYPE_ALIAS_RE = /export\\s+type\\s+([A-Z][A-Za-z0-9]*)\\s*=\\s*([^;]+);/g;
-    const INTERFACE_RE = /(?:export\\s+)?interface\\s+([A-Z][A-Za-z0-9]*Props)\\s*\\{([\\s\\S]*?)\\}/;
-    const PROP_LINE_RE = /^\\s*([a-zA-Z_$][a-zA-Z0-9_$]*)(\\??)\\s*:\\s*([^;,]+)[;,]?\\s*$/;
-
-    const knownUnions: Record<string, string[]> = {};
-    TYPE_ALIAS_RE.lastIndex = 0;
-    let m;
-    while ((m = TYPE_ALIAS_RE.exec(src)) !== null) {
-      const body = m[2].trim();
-      if (/^"[^"]*"(\\s*\\|\\s*"[^"]*")*$/.test(body)) {
-        knownUnions[m[1]] = body.split("|").map(s => s.trim().replace(/"/g, ""));
-      }
-    }
-    const iface = INTERFACE_RE.exec(src);
-    if (!iface) return { props: {} as Record<string, any>, knownUnions };
-    const props: Record<string, any> = {};
-    for (const rawLine of iface[2].split("\\n")) {
-      const line = rawLine.replace(/\\/\\/.*$/, "");
-      const pm = PROP_LINE_RE.exec(line);
-      if (!pm) continue;
-      const [, name, opt, type] = pm;
-      const t = type.trim();
-      if (knownUnions[t]) props[name] = { type: "union", values: knownUnions[t], optional: !!opt };
-      else if (/^"[^"]*"(\\s*\\|\\s*"[^"]*")*$/.test(t)) {
-        props[name] = { type: "union", values: t.split("|").map(s => s.trim().replace(/"/g, "")), optional: !!opt };
-      } else if (t === "string") props[name] = { type: "string", optional: !!opt };
-      else if (t === "number") props[name] = { type: "number", optional: !!opt };
-      else if (t === "boolean") props[name] = { type: "boolean", optional: !!opt };
-      else props[name] = { type: "unknown", optional: !!opt };
-    }
-    return { props, knownUnions };
-  } catch {
-    return { props: {} as Record<string, any>, knownUnions: {} };
+// Component page — a CLIENT component that does a static lookup in
+// componentMap. Prop schemas are baked into componentMap at sync time
+// (via the lib's prop-parser), so the page has no runtime fs reads. The
+// PropToggle UI is inlined since both it and the page need `"use client"`.
+const COMPONENT_PAGE_TSX = `${MARKER_COMMENT}"use client";
+
+import { useParams, usePathname, useRouter, useSearchParams } from "next/navigation";
+import { components, getComponent, type PropSchema } from "../../componentMap";
+
+// Inline PropToggle: a small client UI for one prop, wired to the URL via
+// router.replace so the parent re-renders with the new value. Kept in this
+// file because both it and the page need "use client" — no reason to split.
+function PropToggle(p:
+  | { name: string; kind: "union"; values: readonly string[]; value: string }
+  | { name: string; kind: "boolean"; value: string }
+  | { name: string; kind: "string" | "number"; value: string }
+) {
+  const router = useRouter();
+  const pathname = usePathname();
+  const sp = useSearchParams();
+
+  function setParam(v: string) {
+    const next = new URLSearchParams(sp.toString());
+    if (v === "") next.delete(p.name);
+    else next.set(p.name, v);
+    router.replace(\`\${pathname}?\${next.toString()}\`);
   }
+
+  return (
+    <label className="flex items-center gap-3 text-sm">
+      <span className="w-24 text-xs text-zinc-500">{p.name}</span>
+      {p.kind === "union" ? (
+        <select className="rounded border border-zinc-300 dark:border-zinc-700 bg-transparent px-2 py-1 text-sm" value={p.value} onChange={(e) => setParam(e.target.value)}>
+          {p.values.map((v) => <option key={v} value={v}>{v}</option>)}
+        </select>
+      ) : p.kind === "boolean" ? (
+        <input type="checkbox" checked={p.value === "true"} onChange={(e) => setParam(String(e.target.checked))} />
+      ) : (
+        <input type={p.kind === "number" ? "number" : "text"} className="rounded border border-zinc-300 dark:border-zinc-700 bg-transparent px-2 py-1 text-sm" value={p.value} onChange={(e) => setParam(e.target.value)} />
+      )}
+    </label>
+  );
 }
 
-export default async function ComponentPage({
-  params,
-  searchParams,
-}: {
-  params: Promise<{ component: string }>;
-  searchParams: Promise<Record<string, string | string[] | undefined>>;
-}) {
-  const { component: slug } = await params;
-  const sp = await searchParams;
+function NotInMap({ slug }: { slug: string }) {
+  return (
+    <div className="rounded border border-amber-300 dark:border-amber-800 bg-amber-50 dark:bg-amber-950/30 p-6">
+      <h2 className="text-lg font-medium text-amber-900 dark:text-amber-200">Not in the static map</h2>
+      <p className="mt-2 text-sm text-amber-800 dark:text-amber-300">
+        The slug <code>{slug}</code> isn&apos;t present in the generated <code>componentMap.tsx</code>.
+      </p>
+      <p className="mt-2 text-sm text-amber-800 dark:text-amber-300">
+        Tracked slugs: {components.length === 0 ? <em>none</em> : components.map(c => <code key={c.slug} className="mr-2">{c.slug}</code>)}
+      </p>
+      <p className="mt-2 text-sm text-amber-800 dark:text-amber-300">
+        If you just edited <code>adhd.config.ts</code> to add this component, re-run <code>/adhd:sync-docs</code> in this project to regenerate the static imports.
+      </p>
+    </div>
+  );
+}
+
+export default function ComponentPage() {
+  const params = useParams<{ component: string }>();
+  const slug = params.component;
+  const sp = useSearchParams();
   const entry = getComponent(slug);
 
-  if (!entry) {
-    return (
-      <div className="rounded border border-amber-300 dark:border-amber-800 bg-amber-50 dark:bg-amber-950/30 p-6">
-        <h2 className="text-lg font-medium text-amber-900 dark:text-amber-200">Not in the static map</h2>
-        <p className="mt-2 text-sm text-amber-800 dark:text-amber-300">
-          The slug <code>{slug}</code> isn&apos;t present in the generated <code>componentMap.tsx</code>.
-        </p>
-        <p className="mt-2 text-sm text-amber-800 dark:text-amber-300">
-          If you just edited <code>adhd.config.ts</code> to add this component, re-run <code>/adhd:sync-docs</code> in this project to regenerate the static imports.
-        </p>
-      </div>
-    );
-  }
+  if (!entry) return <NotInMap slug={slug} />;
 
-  const { rawPath, Component } = entry;
-  const { props } = await parseProps(rawPath);
+  const { rawPath, Component, props } = entry;
 
-  // Resolve current prop values from searchParams
+  // Resolve current prop values from the URL.
   const current: Record<string, any> = {};
-  for (const [name, def] of Object.entries(props)) {
-    const v = sp[name];
-    if (typeof v !== "string") continue;
-    if (def.type === "union" && def.values.includes(v)) current[name] = v;
+  for (const [name, def] of Object.entries(props) as Array<[string, PropSchema]>) {
+    const v = sp.get(name);
+    if (v == null) continue;
+    if (def.type === "union" && def.values?.includes(v)) current[name] = v;
     else if (def.type === "boolean") current[name] = v === "true";
     else if (def.type === "string") current[name] = v;
     else if (def.type === "number") current[name] = Number(v);
   }
 
   const importPath = "@/" + rawPath.replace(/\\.tsx?$/, "").replace(/\\/index$/, "");
-  const importStmt = Component ? \`import \${Component.name ?? slug} from "\${importPath}";\` : null;
+  const componentName = Component?.name || slug;
+  const importStmt = Component ? \`import \${componentName} from "\${importPath}";\` : null;
   const jsxSnippet = Component
-    ? \`<\${Component.name ?? slug}\${Object.entries(current).map(([k,v]) => \` \${k}={\${JSON.stringify(v)}}\`).join("")} />\`
+    ? \`<\${componentName}\${Object.entries(current).map(([k, v]) => \` \${k}={\${JSON.stringify(v)}}\`).join("")} />\`
     : null;
 
   return (
@@ -567,23 +580,19 @@ export default async function ComponentPage({
 
       <section className="rounded border border-zinc-200 dark:border-zinc-800 p-4">
         <h3 className="mb-3 text-xs font-medium uppercase text-zinc-500">Props</h3>
-        {Object.keys(props).length === 0 ? <p className="text-sm text-zinc-500">No prop introspection available.</p> : (
+        {Object.keys(props).length === 0 ? (
+          <p className="text-sm text-zinc-500">No prop interface detected at sync time.</p>
+        ) : (
           <div className="flex flex-col gap-2">
-            {Object.entries(props).map(([name, def]: [string, any]) => {
-              if (def.type === "union") {
-                return (
-                  <PropToggle key={name} name={name} kind="union" values={def.values} value={current[name] ?? def.values[0]} />
-                );
+            {Object.entries(props).map(([name, def]) => {
+              if (def.type === "union" && def.values) {
+                return <PropToggle key={name} name={name} kind="union" values={def.values} value={current[name] ?? def.values[0]} />;
               }
               if (def.type === "boolean") {
-                return (
-                  <PropToggle key={name} name={name} kind="boolean" value={String(current[name] ?? false)} />
-                );
+                return <PropToggle key={name} name={name} kind="boolean" value={String(current[name] ?? false)} />;
               }
               if (def.type === "string" || def.type === "number") {
-                return (
-                  <PropToggle key={name} name={name} kind={def.type} value={String(current[name] ?? "")} />
-                );
+                return <PropToggle key={name} name={name} kind={def.type} value={String(current[name] ?? "")} />;
               }
               return (
                 <div key={name} className="text-xs text-zinc-500">
@@ -596,8 +605,12 @@ export default async function ComponentPage({
       </section>
 
       <section className="rounded border border-zinc-200 dark:border-zinc-800 p-8">
-        {Component ? <Component {...current} /> : (
-          <p className="text-sm text-zinc-500">No renderable component exported from <code>{rawPath}</code>. The map imported it but couldn&apos;t resolve a function (default or named).</p>
+        {Component ? (
+          <Component {...current} />
+        ) : (
+          <p className="text-sm text-zinc-500">
+            No renderable component exported from <code>{rawPath}</code>. componentMap imported it but couldn&apos;t resolve a function (default or named).
+          </p>
         )}
       </section>
 
@@ -612,87 +625,11 @@ export default async function ComponentPage({
 }
 `;
 
-// Error boundary for the component route. Catches runtime errors thrown during
-// rendering — components that throw on mount, prop-parse failures, etc. With
-// static imports there's no broad-bundle Tailwind blast radius anymore, so this
-// is purely a runtime safety net.
-const COMPONENT_ERROR_TSX = `${MARKER_COMMENT}"use client";
-
-export default function ComponentPageError({ error, reset }: { error: Error & { digest?: string }; reset: () => void }) {
-  return (
-    <div className="flex flex-col gap-4">
-      <div className="rounded border border-red-300 bg-red-50 dark:border-red-800 dark:bg-red-950/30 p-6">
-        <h2 className="text-lg font-medium text-red-900 dark:text-red-200">Couldn&apos;t render this component</h2>
-        <p className="mt-2 text-sm text-red-800 dark:text-red-300">
-          Something went wrong while rendering this component. Common causes:
-        </p>
-        <ul className="mt-3 list-disc pl-6 text-sm text-red-800 dark:text-red-300">
-          <li>The component throws on mount when no props are provided.</li>
-          <li>The component expects context (theme provider, router, query client) that the docs route doesn&apos;t set up.</li>
-          <li>The component&apos;s prop interface uses types the docs route can&apos;t introspect.</li>
-        </ul>
-        <details className="mt-4 text-xs">
-          <summary className="cursor-pointer text-red-700 dark:text-red-300">Show error details</summary>
-          <pre className="mt-2 overflow-x-auto rounded bg-red-100 dark:bg-red-950/50 p-2 text-red-900 dark:text-red-200">{error.message}{error.digest ? \`\\n\\nDigest: \${error.digest}\` : ""}</pre>
-        </details>
-        <button
-          type="button"
-          onClick={() => reset()}
-          className="mt-4 rounded border border-red-300 dark:border-red-700 px-3 py-1 text-sm text-red-900 dark:text-red-200 hover:bg-red-100 dark:hover:bg-red-900/30"
-        >
-          Try again
-        </button>
-      </div>
-    </div>
-  );
-}
-`;
-
-const PROP_TOGGLE_TSX = `${MARKER_COMMENT}"use client";
-import { useRouter, useSearchParams, usePathname } from "next/navigation";
-
-type Props =
-  | { name: string; kind: "union"; values: string[]; value: string }
-  | { name: string; kind: "boolean"; value: string }
-  | { name: string; kind: "string"; value: string }
-  | { name: string; kind: "number"; value: string };
-
-export function PropToggle(p: Props) {
-  const router = useRouter();
-  const path = usePathname();
-  const sp = useSearchParams();
-
-  function setParam(v: string) {
-    const next = new URLSearchParams(sp.toString());
-    if (v === "") next.delete(p.name);
-    else next.set(p.name, v);
-    router.replace(\`\${path}?\${next}\`);
-  }
-
-  return (
-    <label className="flex items-center gap-3 text-sm">
-      <span className="w-24 text-xs text-zinc-500">{p.name}</span>
-      {p.kind === "union" ? (
-        <select className="rounded border border-zinc-300 dark:border-zinc-700 bg-transparent px-2 py-1 text-sm" value={p.value} onChange={(e) => setParam(e.target.value)}>
-          {p.values.map((v) => <option key={v} value={v}>{v}</option>)}
-        </select>
-      ) : p.kind === "boolean" ? (
-        <input type="checkbox" checked={p.value === "true"} onChange={(e) => setParam(String(e.target.checked))} />
-      ) : (
-        <input type={p.kind === "number" ? "number" : "text"} className="rounded border border-zinc-300 dark:border-zinc-700 bg-transparent px-2 py-1 text-sm" value={p.value} onChange={(e) => setParam(e.target.value)} />
-      )}
-    </label>
-  );
-}
-`;
-
 module.exports = {
   MARKER_COMMENT,
   LAYOUT_TSX,
   INDEX_PAGE_TSX,
   TOKENS_PAGE_TSX,
   COMPONENT_PAGE_TSX,
-  COMPONENT_ERROR_TSX,
   COMPONENT_MAP_TSX,
-  PROP_TOGGLE_TSX,
 };

From 728652e9f3edf1eb9d9c5b4fdb53c79bd0098af3 Mon Sep 17 00:00:00 2001
From: Hugh Francis <hughfrancis89@gmail.com>
Date: Mon, 11 May 2026 19:37:11 -0400
Subject: [PATCH 30/79] sync-docs: render-where wizard option adds
 Vercel-preview mode
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The old "Exclude from production builds? Yes/No" Phase 3 question becomes
a 3-option choice: Dev only / Dev + Vercel preview / Everywhere. The
choice flows through as a single `renderMode` field replacing the binary
`prodExcluded` shape.

next-config-patcher generates a different conditional per mode:

- "dev-only" (default, current behavior):
    pageExtensions: process.env.NODE_ENV === 'production'
      ? ['ts', 'tsx']
      : ['ts', 'tsx', 'design-system.ts', 'design-system.tsx']

- "vercel-preview" (compound condition gates only on the Vercel choice):
    pageExtensions:
      process.env.VERCEL_ENV === 'production' ||
      (!process.env.VERCEL && process.env.NODE_ENV === 'production')
        ? ['ts', 'tsx']
        : ['ts', 'tsx', 'design-system.ts', 'design-system.tsx']

- "everywhere" — skip the patch entirely; files use plain .tsx and ship
  to production. Layout's `robots: { index: false, follow: false }`
  metadata still prevents indexing.

The compound condition for vercel-preview excludes on Vercel production
AND on any non-Vercel production deploy. Vercel preview deploys keep
their route because VERCEL_ENV='preview' doesn't satisfy either disjunct.

`isPatched` widened to recognize EITHER conditional shape so re-running
sync-docs is a no-op regardless of which mode was originally chosen.
Switching modes requires removing the marker comment from next.config
(same eject-by-deleting-the-marker pattern as the generated route files).

UX call: kept this as a single multi-option question in the existing
Phase 3 wizard, not a stepped "Are you on Vercel?" flow. Three labeled
options stay in one prompt — no extra round-trips, descriptions name the
exact env vars baked in.

103 sync-docs tests + 386 plugin-wide, strict tsc on the generated
output clean.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 README.md                                     | 19 ++--
 .../adhd/lib/sync-docs/__tests__/cli.test.js  |  4 +-
 .../__tests__/next-config-patcher.test.js     | 38 ++++++++
 .../__tests__/route-installer.test.js         | 89 ++++++++++++++-----
 plugins/adhd/lib/sync-docs/cli.js             |  5 +-
 .../adhd/lib/sync-docs/next-config-patcher.js | 35 ++++++--
 plugins/adhd/lib/sync-docs/route-installer.js | 29 ++++--
 plugins/adhd/skills/sync-docs/SKILL.md        | 38 ++++++--
 8 files changed, 204 insertions(+), 53 deletions(-)

diff --git a/README.md b/README.md
index ded5847..834d4ff 100644
--- a/README.md
+++ b/README.md
@@ -135,11 +135,20 @@ request time and statically imports the components listed in
 - Component pages: each component gets its own route with URL-driven prop
   toggles, derived from the component's TypeScript prop interface.
 
-By default the route is excluded from production builds via Next.js's
-`pageExtensions` trick — files use the `.design-system.tsx` extension and
-the production build literally doesn't see them. You can opt out at setup
-time if you'd rather ship the route (it still has `<meta name="robots"
-content="noindex, nofollow" />` either way).
+The setup command asks **where the docs route should render** with three
+options:
+
+- **Dev only** (default) — files use `.design-system.tsx`; `pageExtensions`
+  in `next.config.ts` gates on `process.env.NODE_ENV === 'production'`. The
+  production build literally doesn't see the files.
+- **Dev + Vercel preview** — same file extension, but `pageExtensions`
+  gates on `process.env.VERCEL_ENV === 'production' || (!VERCEL && NODE_ENV === 'production')`.
+  The route renders on local dev *and* Vercel preview deploys, but stays out
+  of Vercel production (and out of any non-Vercel production deploy too, so
+  CI builds don't accidentally ship it).
+- **Everywhere** — no `pageExtensions` patch; route files use plain `.tsx`
+  and ship in production. The layout's metadata still emits `<meta
+  name="robots" content="noindex, nofollow" />` so it won't be indexed.
 
 #### Re-running after `adhd.config.ts` changes
 
diff --git a/plugins/adhd/lib/sync-docs/__tests__/cli.test.js b/plugins/adhd/lib/sync-docs/__tests__/cli.test.js
index 98c624c..33ae960 100644
--- a/plugins/adhd/lib/sync-docs/__tests__/cli.test.js
+++ b/plugins/adhd/lib/sync-docs/__tests__/cli.test.js
@@ -108,7 +108,7 @@ const config = {
 export default config;
 `);
   const choices = tmp('choices.json', JSON.stringify({
-    projectRoot: root, groupName: '(design-system)', routeSegment: '-docs', prodExcluded: true,
+    projectRoot: root, groupName: '(design-system)', routeSegment: '-docs', renderMode: 'dev-only',
   }));
   const r = spawnSync('node', [CLI, 'install', '--config', choices], { encoding: 'utf8' });
   assert.equal(r.status, 0, r.stderr);
@@ -124,7 +124,7 @@ test('install subcommand aborts with a clear error when adhd.config.ts is missin
   const root = fs.mkdtempSync(path.join(os.tmpdir(), 'adhd-ids-install-no-config-'));
   fs.mkdirSync(path.join(root, 'app'), { recursive: true });
   const choices = tmp('choices.json', JSON.stringify({
-    projectRoot: root, groupName: '(design-system)', routeSegment: '-docs', prodExcluded: true,
+    projectRoot: root, groupName: '(design-system)', routeSegment: '-docs', renderMode: 'dev-only',
   }));
   const r = spawnSync('node', [CLI, 'install', '--config', choices], { encoding: 'utf8' });
   assert.equal(r.status, 2);
diff --git a/plugins/adhd/lib/sync-docs/__tests__/next-config-patcher.test.js b/plugins/adhd/lib/sync-docs/__tests__/next-config-patcher.test.js
index a994874..ff23891 100644
--- a/plugins/adhd/lib/sync-docs/__tests__/next-config-patcher.test.js
+++ b/plugins/adhd/lib/sync-docs/__tests__/next-config-patcher.test.js
@@ -66,3 +66,41 @@ test('patchNextConfig refuses to silently overwrite an existing different pageEx
   assert.equal(r.conflict, true);
   assert.match(r.existing, /pageExtensions:\s*\['mdx'/);
 });
+
+test('patches with the dev-only conditional by default', () => {
+  // Default renderMode is dev-only — gates the page-extension swap on NODE_ENV.
+  const out = patchNextConfig(TS_MINIMAL);
+  assert.match(out, /process\.env\.NODE_ENV === 'production'/);
+  assert.doesNotMatch(out, /VERCEL_ENV/);
+});
+
+test('patches with the Vercel-preview conditional when renderMode: "vercel-preview"', () => {
+  // The compound condition excludes on Vercel production AND on any non-Vercel
+  // production deploy, while letting Vercel preview deploys render the route.
+  const out = patchNextConfig(TS_MINIMAL, { renderMode: 'vercel-preview' });
+  assert.match(out, /process\.env\.VERCEL_ENV === 'production'/);
+  // Also includes the !VERCEL && NODE_ENV='production' fallback for non-Vercel hosts.
+  assert.match(out, /!process\.env\.VERCEL/);
+  assert.match(out, /process\.env\.NODE_ENV === 'production'/);
+  assert.match(out, /'design-system\.tsx'/);
+});
+
+test('isPatched recognizes EITHER conditional shape as already-patched (idempotency)', () => {
+  const devOnly = patchNextConfig(TS_MINIMAL, { renderMode: 'dev-only' });
+  const vercelPreview = patchNextConfig(TS_MINIMAL, { renderMode: 'vercel-preview' });
+  assert.equal(isPatched(devOnly), true);
+  assert.equal(isPatched(vercelPreview), true);
+  // Re-running on a Vercel-preview-patched file is a no-op
+  assert.equal(patchNextConfig(vercelPreview, { renderMode: 'vercel-preview' }), vercelPreview);
+  // Re-running with a DIFFERENT renderMode on an already-patched file is also a
+  // no-op (sentinel detection ignores which env var gates the conditional). To
+  // switch modes, the user removes the marker line and re-syncs.
+  assert.equal(patchNextConfig(vercelPreview, { renderMode: 'dev-only' }), vercelPreview);
+});
+
+test('patchNextConfig throws on an unknown renderMode', () => {
+  assert.throws(
+    () => patchNextConfig(TS_MINIMAL, { renderMode: 'preview' }),
+    /Unknown renderMode: preview/,
+  );
+});
diff --git a/plugins/adhd/lib/sync-docs/__tests__/route-installer.test.js b/plugins/adhd/lib/sync-docs/__tests__/route-installer.test.js
index dea5ec9..a41aa11 100644
--- a/plugins/adhd/lib/sync-docs/__tests__/route-installer.test.js
+++ b/plugins/adhd/lib/sync-docs/__tests__/route-installer.test.js
@@ -36,11 +36,11 @@ const SAMPLE_COMPONENTS = [
   { slug: 'logo', rawPath: 'components/design-system/logo/index.tsx', importPath: '@/components/design-system/logo' },
 ];
 
-test('installRoute writes the five generated files when prodExcluded', () => {
+test('installRoute writes the five generated files with renderMode: dev-only', () => {
   const root = makeTempProject();
   writeLogoFixture(root);
   installRoute(root, {
-    groupName: '(design-system)', routeSegment: '-docs', prodExcluded: true,
+    groupName: '(design-system)', routeSegment: '-docs', renderMode: 'dev-only',
     components: SAMPLE_COMPONENTS, cssEntry: 'app/globals.css',
   });
   const docsDir = path.join(root, 'app', '(design-system)', '-docs');
@@ -58,11 +58,11 @@ test('installRoute writes the five generated files when prodExcluded', () => {
   assert.ok(!fs.existsSync(path.join(docsDir, 'tokenDomains.tsx')));
 });
 
-test('installRoute writes plain .tsx files for route files when not prodExcluded', () => {
+test('installRoute writes plain .tsx files for route files with renderMode: "everywhere"', () => {
   const root = makeTempProject();
   writeLogoFixture(root);
   installRoute(root, {
-    groupName: '(design-system)', routeSegment: '-docs', prodExcluded: false,
+    groupName: '(design-system)', routeSegment: '-docs', renderMode: 'everywhere',
     components: SAMPLE_COMPONENTS, cssEntry: 'app/globals.css',
   });
   const docsDir = path.join(root, 'app', '(design-system)', '-docs');
@@ -73,11 +73,52 @@ test('installRoute writes plain .tsx files for route files when not prodExcluded
   assert.ok(fs.existsSync(path.join(docsDir, 'componentMap.tsx')));
 });
 
+test('installRoute uses .design-system suffix for both excluding renderModes', () => {
+  // Both 'dev-only' and 'vercel-preview' rely on pageExtensions to filter
+  // .design-system.tsx files in production builds. The choice of WHICH env var
+  // gates the filter is the next-config-patcher's concern, not the installer's.
+  for (const renderMode of ['dev-only', 'vercel-preview']) {
+    const root = makeTempProject();
+    writeLogoFixture(root);
+    installRoute(root, {
+      groupName: '(design-system)', routeSegment: '-docs', renderMode,
+      components: SAMPLE_COMPONENTS, cssEntry: 'app/globals.css',
+    });
+    const docsDir = path.join(root, 'app', '(design-system)', '-docs');
+    assert.ok(fs.existsSync(path.join(docsDir, 'layout.design-system.tsx')), `renderMode=${renderMode}`);
+    assert.ok(fs.existsSync(path.join(docsDir, 'page.design-system.tsx')), `renderMode=${renderMode}`);
+  }
+});
+
+test('installRoute throws on an unknown renderMode (typo-protection)', () => {
+  const root = makeTempProject();
+  writeLogoFixture(root);
+  assert.throws(
+    () => installRoute(root, {
+      groupName: '(design-system)', routeSegment: '-docs', renderMode: 'preview',
+      components: SAMPLE_COMPONENTS, cssEntry: 'app/globals.css',
+    }),
+    /Unknown renderMode: preview/,
+  );
+});
+
+test('installRoute defaults to renderMode: "dev-only" when none is provided', () => {
+  const root = makeTempProject();
+  writeLogoFixture(root);
+  installRoute(root, {
+    groupName: '(design-system)', routeSegment: '-docs',
+    // renderMode intentionally omitted
+    components: SAMPLE_COMPONENTS, cssEntry: 'app/globals.css',
+  });
+  const docsDir = path.join(root, 'app', '(design-system)', '-docs');
+  assert.ok(fs.existsSync(path.join(docsDir, 'layout.design-system.tsx')));
+});
+
 test('all written files start with the marker comment', () => {
   const root = makeTempProject();
   writeLogoFixture(root);
   installRoute(root, {
-    groupName: '(design-system)', routeSegment: '-docs', prodExcluded: true,
+    groupName: '(design-system)', routeSegment: '-docs', renderMode: 'dev-only',
     components: SAMPLE_COMPONENTS, cssEntry: 'app/globals.css',
   });
   const docsDir = path.join(root, 'app', '(design-system)', '-docs');
@@ -97,7 +138,7 @@ test('componentMap.tsx has explicit static imports per registered component', ()
   const root = makeTempProject();
   writeLogoFixture(root);
   installRoute(root, {
-    groupName: '(design-system)', routeSegment: '-docs', prodExcluded: true,
+    groupName: '(design-system)', routeSegment: '-docs', renderMode: 'dev-only',
     components: SAMPLE_COMPONENTS, cssEntry: 'app/globals.css',
   });
   const body = fs.readFileSync(
@@ -118,7 +159,7 @@ test('componentMap.tsx bakes prop schemas read from each component source at syn
   const root = makeTempProject();
   writeLogoFixture(root);
   installRoute(root, {
-    groupName: '(design-system)', routeSegment: '-docs', prodExcluded: true,
+    groupName: '(design-system)', routeSegment: '-docs', renderMode: 'dev-only',
     components: SAMPLE_COMPONENTS, cssEntry: 'app/globals.css',
   });
   const body = fs.readFileSync(
@@ -134,7 +175,7 @@ test('componentMap.tsx bakes prop schemas read from each component source at syn
 test('componentMap.tsx handles an empty components list', () => {
   const root = makeTempProject();
   installRoute(root, {
-    groupName: '(design-system)', routeSegment: '-docs', prodExcluded: true,
+    groupName: '(design-system)', routeSegment: '-docs', renderMode: 'dev-only',
     components: [], cssEntry: 'app/globals.css',
   });
   const body = fs.readFileSync(
@@ -152,7 +193,7 @@ test('componentMap.tsx handles a missing component source file (empty props bake
   const root = makeTempProject();
   // Note: we DON'T call writeLogoFixture — the file is missing on purpose.
   installRoute(root, {
-    groupName: '(design-system)', routeSegment: '-docs', prodExcluded: true,
+    groupName: '(design-system)', routeSegment: '-docs', renderMode: 'dev-only',
     components: SAMPLE_COMPONENTS, cssEntry: 'app/globals.css',
   });
   const body = fs.readFileSync(
@@ -166,7 +207,7 @@ test('layout sidebar links use absolute hrefs derived from the route segment', (
   const root = makeTempProject();
   writeLogoFixture(root);
   installRoute(root, {
-    groupName: '(design-system)', routeSegment: '-docs', prodExcluded: true,
+    groupName: '(design-system)', routeSegment: '-docs', renderMode: 'dev-only',
     components: SAMPLE_COMPONENTS, cssEntry: 'app/globals.css',
   });
   const layout = fs.readFileSync(
@@ -182,7 +223,7 @@ test('layout imports the static components array from componentMap', () => {
   const root = makeTempProject();
   writeLogoFixture(root);
   installRoute(root, {
-    groupName: '(design-system)', routeSegment: '-docs', prodExcluded: true,
+    groupName: '(design-system)', routeSegment: '-docs', renderMode: 'dev-only',
     components: SAMPLE_COMPONENTS, cssEntry: 'app/globals.css',
   });
   const layout = fs.readFileSync(
@@ -193,11 +234,11 @@ test('layout imports the static components array from componentMap', () => {
   assert.doesNotMatch(layout, /from "node:fs|from "node:path/);
 });
 
-test('tokens page imports TOKEN_DOMAINS from layout.design-system when prodExcluded', () => {
+test('tokens page imports TOKEN_DOMAINS from layout.design-system with renderMode: dev-only', () => {
   const root = makeTempProject();
   writeLogoFixture(root);
   installRoute(root, {
-    groupName: '(design-system)', routeSegment: '-docs', prodExcluded: true,
+    groupName: '(design-system)', routeSegment: '-docs', renderMode: 'dev-only',
     components: SAMPLE_COMPONENTS, cssEntry: 'app/globals.css',
   });
   const tokensPage = fs.readFileSync(
@@ -208,11 +249,11 @@ test('tokens page imports TOKEN_DOMAINS from layout.design-system when prodExclu
   assert.doesNotMatch(tokensPage, /__LAYOUT_MODULE__/);
 });
 
-test('tokens page imports TOKEN_DOMAINS from layout (no suffix) when not prodExcluded', () => {
+test('tokens page imports TOKEN_DOMAINS from layout (no suffix) with renderMode: "everywhere"', () => {
   const root = makeTempProject();
   writeLogoFixture(root);
   installRoute(root, {
-    groupName: '(design-system)', routeSegment: '-docs', prodExcluded: false,
+    groupName: '(design-system)', routeSegment: '-docs', renderMode: 'everywhere',
     components: SAMPLE_COMPONENTS, cssEntry: 'app/globals.css',
   });
   const tokensPage = fs.readFileSync(
@@ -227,7 +268,7 @@ test('tokens page bakes the configured cssEntry path as a constant', () => {
   const root = makeTempProject();
   writeLogoFixture(root);
   installRoute(root, {
-    groupName: '(design-system)', routeSegment: '-docs', prodExcluded: true,
+    groupName: '(design-system)', routeSegment: '-docs', renderMode: 'dev-only',
     components: SAMPLE_COMPONENTS, cssEntry: 'src/app/globals.css',
   });
   const tokensPage = fs.readFileSync(
@@ -242,7 +283,7 @@ test('component page is a client component with inline PropToggle and no fs read
   const root = makeTempProject();
   writeLogoFixture(root);
   installRoute(root, {
-    groupName: '(design-system)', routeSegment: '-docs', prodExcluded: true,
+    groupName: '(design-system)', routeSegment: '-docs', renderMode: 'dev-only',
     components: SAMPLE_COMPONENTS, cssEntry: 'app/globals.css',
   });
   const componentPage = fs.readFileSync(
@@ -267,7 +308,7 @@ test('component page shows a "not in static map" message when slug is missing',
   const root = makeTempProject();
   writeLogoFixture(root);
   installRoute(root, {
-    groupName: '(design-system)', routeSegment: '-docs', prodExcluded: true,
+    groupName: '(design-system)', routeSegment: '-docs', renderMode: 'dev-only',
     components: SAMPLE_COMPONENTS, cssEntry: 'app/globals.css',
   });
   const componentPage = fs.readFileSync(
@@ -282,7 +323,7 @@ test('detectExistingInstall returns marker-bearing files', () => {
   const root = makeTempProject();
   writeLogoFixture(root);
   installRoute(root, {
-    groupName: '(design-system)', routeSegment: '-docs', prodExcluded: true,
+    groupName: '(design-system)', routeSegment: '-docs', renderMode: 'dev-only',
     components: SAMPLE_COMPONENTS, cssEntry: 'app/globals.css',
   });
   const found = detectExistingInstall(root);
@@ -299,13 +340,13 @@ test('re-running installRoute overwrites files cleanly', () => {
   const root = makeTempProject();
   writeLogoFixture(root);
   installRoute(root, {
-    groupName: '(design-system)', routeSegment: '-docs', prodExcluded: true,
+    groupName: '(design-system)', routeSegment: '-docs', renderMode: 'dev-only',
     components: SAMPLE_COMPONENTS, cssEntry: 'app/globals.css',
   });
   const layoutPath = path.join(root, 'app', '(design-system)', '-docs', 'layout.design-system.tsx');
   fs.writeFileSync(layoutPath, 'corrupted');
   installRoute(root, {
-    groupName: '(design-system)', routeSegment: '-docs', prodExcluded: true,
+    groupName: '(design-system)', routeSegment: '-docs', renderMode: 'dev-only',
     components: SAMPLE_COMPONENTS, cssEntry: 'app/globals.css',
   });
   const after = fs.readFileSync(layoutPath, 'utf8');
@@ -329,7 +370,7 @@ test('re-sync removes stale files from previous template layouts', () => {
   for (const p of stale) fs.writeFileSync(p, '// design-system-docs-route — stale\nexport {};\n');
 
   const r = installRoute(root, {
-    groupName: '(design-system)', routeSegment: '-docs', prodExcluded: true,
+    groupName: '(design-system)', routeSegment: '-docs', renderMode: 'dev-only',
     components: SAMPLE_COMPONENTS, cssEntry: 'app/globals.css',
   });
 
@@ -348,7 +389,7 @@ test('installRoute preserves user files that lack the marker', () => {
   fs.writeFileSync(userFile, '// user wrote this\nexport const NOTE = "keep";\n');
 
   installRoute(root, {
-    groupName: '(design-system)', routeSegment: '-docs', prodExcluded: true,
+    groupName: '(design-system)', routeSegment: '-docs', renderMode: 'dev-only',
     components: SAMPLE_COMPONENTS, cssEntry: 'app/globals.css',
   });
 
@@ -359,7 +400,7 @@ test('installRoute supports an empty groupName (no route group)', () => {
   const root = makeTempProject();
   writeLogoFixture(root);
   installRoute(root, {
-    groupName: '', routeSegment: '-docs', prodExcluded: true,
+    groupName: '', routeSegment: '-docs', renderMode: 'dev-only',
     components: SAMPLE_COMPONENTS, cssEntry: 'app/globals.css',
   });
   const docsDir = path.join(root, 'app', '-docs');
diff --git a/plugins/adhd/lib/sync-docs/cli.js b/plugins/adhd/lib/sync-docs/cli.js
index 1fd27c0..bf5bdae 100644
--- a/plugins/adhd/lib/sync-docs/cli.js
+++ b/plugins/adhd/lib/sync-docs/cli.js
@@ -61,14 +61,15 @@ function main() {
   }
 
   if (cmd === 'patch-next-config') {
-    if (!args.config || !args['route-url']) { console.error('Usage: patch-next-config --config <path> --route-url <url>'); process.exit(2); }
+    if (!args.config || !args['route-url']) { console.error('Usage: patch-next-config --config <path> --route-url <url> [--render-mode <dev-only|vercel-preview>]'); process.exit(2); }
+    const renderMode = args['render-mode'] || 'dev-only';
     const src = fs.readFileSync(args.config, 'utf8');
     const r = patchNextConfig(src, { detectOnly: true });
     if (r && r.conflict) {
       console.error('next.config already sets pageExtensions: ' + r.existing);
       process.exit(3);
     }
-    const out = patchNextConfig(src);
+    const out = patchNextConfig(src, { renderMode });
     fs.writeFileSync(args.config, out);
     process.exit(0);
   }
diff --git a/plugins/adhd/lib/sync-docs/next-config-patcher.js b/plugins/adhd/lib/sync-docs/next-config-patcher.js
index e3d9ee2..a4bba2d 100644
--- a/plugins/adhd/lib/sync-docs/next-config-patcher.js
+++ b/plugins/adhd/lib/sync-docs/next-config-patcher.js
@@ -1,8 +1,9 @@
 'use strict';
 
-// Detection: look for the sentinel "design-system.tsx" pageExtension entry
-// inside the conditional. This is the unique fingerprint of OUR patch.
-const PATCHED_SENTINEL_RE = /pageExtensions:\s*process\.env\.NODE_ENV\s*===\s*['"]production['"][\s\S]*?'design-system\.tsx'/;
+// Detection: look for any pageExtensions entry that mentions our sentinel
+// "design-system.tsx" — that's the unique fingerprint of OUR patch, regardless
+// of which env-var condition guards it ('NODE_ENV' vs 'VERCEL_ENV').
+const PATCHED_SENTINEL_RE = /pageExtensions:[\s\S]*?'design-system\.tsx'/;
 
 // Detection: any other pageExtensions definition (array form).
 const EXISTING_PAGE_EXTENSIONS_RE = /pageExtensions:\s*\[/;
@@ -10,9 +11,23 @@ const EXISTING_PAGE_EXTENSIONS_RE = /pageExtensions:\s*\[/;
 // Captures the full `pageExtensions: ...,` declaration for conflict reporting.
 const EXISTING_PAGE_EXTENSIONS_VALUE_RE = /pageExtensions:[^,\n]+,?/;
 
-const PATCH_BLOCK = `  pageExtensions: process.env.NODE_ENV === 'production'
+// Render-mode → conditional source. The "everywhere" mode is handled by NOT
+// calling the patcher at all (files use plain `.tsx` extensions and ship to
+// production). The two excluding modes only differ in which env vars they read.
+const PATCH_BLOCKS = {
+  'dev-only': `  pageExtensions: process.env.NODE_ENV === 'production'
     ? ['ts', 'tsx']
-    : ['ts', 'tsx', 'design-system.ts', 'design-system.tsx'],`;
+    : ['ts', 'tsx', 'design-system.ts', 'design-system.tsx'],`,
+  // Vercel-preview-aware: excludes on Vercel's production environment AND on
+  // any non-Vercel production deploy (Netlify, fly.io, CI, etc.). Vercel
+  // preview deploys have VERCEL_ENV='preview', which doesn't satisfy either
+  // disjunct, so the route renders there.
+  'vercel-preview': `  pageExtensions:
+    process.env.VERCEL_ENV === 'production' ||
+    (!process.env.VERCEL && process.env.NODE_ENV === 'production')
+      ? ['ts', 'tsx']
+      : ['ts', 'tsx', 'design-system.ts', 'design-system.tsx'],`,
+};
 
 function isPatched(source) {
   return PATCHED_SENTINEL_RE.test(source);
@@ -49,6 +64,12 @@ function patchNextConfig(source, options = {}) {
     throw new Error('next.config already sets pageExtensions to a different value. Run with detectOnly: true to inspect and prompt the user.');
   }
 
+  const renderMode = options.renderMode || 'dev-only';
+  const block = PATCH_BLOCKS[renderMode];
+  if (!block) {
+    throw new Error(`Unknown renderMode: ${renderMode}. Expected one of: ${Object.keys(PATCH_BLOCKS).join(', ')}.`);
+  }
+
   const insertAt = findConfigObjectStart(source);
   if (insertAt === -1) {
     throw new Error('Could not locate the config object in next.config. Manual edit required.');
@@ -58,9 +79,9 @@ function patchNextConfig(source, options = {}) {
   // properties. This puts it at the top of the config for visibility.
   const before = source.slice(0, insertAt);
   // Strip any leading newline from the tail so it isn't duplicated; we always
-  // emit exactly one `\n` on each side of PATCH_BLOCK for clean formatting.
+  // emit exactly one `\n` on each side of the block for clean formatting.
   const after = source.slice(insertAt).replace(/^\n/, '');
-  return before + '\n' + PATCH_BLOCK + '\n' + after;
+  return before + '\n' + block + '\n' + after;
 }
 
 module.exports = { patchNextConfig, isPatched };
diff --git a/plugins/adhd/lib/sync-docs/route-installer.js b/plugins/adhd/lib/sync-docs/route-installer.js
index fac463d..97b15d9 100644
--- a/plugins/adhd/lib/sync-docs/route-installer.js
+++ b/plugins/adhd/lib/sync-docs/route-installer.js
@@ -62,21 +62,36 @@ function renderComponentMap(projectRoot, components) {
     .replace('__COMPONENT_ENTRIES__', entries.length === 0 ? '[]' : `[\n${entries}\n]`);
 }
 
+// Three render modes:
+//   - 'everywhere'      → files use plain .tsx, no next.config patch, ship to prod
+//   - 'dev-only'        → files use .design-system.tsx, next.config gates on NODE_ENV
+//   - 'vercel-preview'  → files use .design-system.tsx, next.config gates on a
+//                         compound (VERCEL_ENV='production' OR non-Vercel prod)
+const VALID_RENDER_MODES = new Set(['everywhere', 'dev-only', 'vercel-preview']);
+
 function installRoute(projectRoot, opts) {
   const {
     groupName = '',
     routeSegment,
-    prodExcluded,
+    renderMode = 'dev-only',
     components = [],
     cssEntry = 'app/globals.css',
   } = opts;
   if (!routeSegment) throw new Error('routeSegment is required');
-
-  // Page/layout/error files get the `.design-system.tsx` suffix only when
-  // prod-excluded so Next.js's `pageExtensions` filters them out of production
-  // builds. componentMap and PropToggle are regular modules — they're only
-  // bundled when imported by a page that IS suffix-excluded, so plain `.tsx`
-  // is correct (and necessary for standard TS module resolution to find them).
+  if (!VALID_RENDER_MODES.has(renderMode)) {
+    throw new Error(`Unknown renderMode: ${renderMode}. Expected one of: ${[...VALID_RENDER_MODES].join(', ')}.`);
+  }
+  // 'everywhere' is the only mode where pages don't get the suffix; the other
+  // two both rely on `pageExtensions` to filter `.design-system.tsx` files in
+  // production builds (they just differ in WHICH env var the conditional reads,
+  // which is a next-config-patcher concern, not a file-extension concern).
+  const prodExcluded = renderMode !== 'everywhere';
+
+  // Page/layout files get the `.design-system.tsx` suffix only when prod-excluded
+  // so Next.js's `pageExtensions` filters them out of production builds.
+  // componentMap is a regular module — it's only bundled when imported by a page
+  // that IS suffix-excluded, so plain `.tsx` is correct (and necessary for
+  // standard TS module resolution to find it).
   const pageExt = prodExcluded ? '.design-system.tsx' : '.tsx';
   const moduleExt = '.tsx';
   const segments = ['app'];
diff --git a/plugins/adhd/skills/sync-docs/SKILL.md b/plugins/adhd/skills/sync-docs/SKILL.md
index 23c0317..2a9ba4e 100644
--- a/plugins/adhd/skills/sync-docs/SKILL.md
+++ b/plugins/adhd/skills/sync-docs/SKILL.md
@@ -50,7 +50,18 @@ Ask all three questions in a **single** `AskUserQuestion` call so the user sees
 
 1. **Route URL** — default `/-docs`. Validate: starts with `/`, only `a-z0-9-/` characters, no leading `_`.
 2. **Route group** — default `(design-system)`. Validate: parens-wrapped, alphanumerics + hyphens inside, OR empty string for "no group."
-3. **Exclude from production builds?** — default `Yes`.
+3. **Where should the docs route render?** — three options, default `Dev only`:
+   - **Dev only** — gates on `process.env.NODE_ENV === 'production'`. Excludes the route from any production build, on any host.
+   - **Dev + Vercel preview** — gates on `process.env.VERCEL_ENV === 'production' || (!process.env.VERCEL && process.env.NODE_ENV === 'production')`. Renders on Vercel preview deploys; excluded from Vercel production AND from any non-Vercel production deploy.
+   - **Everywhere** — no `pageExtensions` patch; route files use plain `.tsx` and ship to production (still `noindex`'d via `robots: { index: false, follow: false }` on the layout's metadata).
+
+Map the answer to the `renderMode` field passed downstream:
+
+| Answer label | `renderMode` |
+|---|---|
+| Dev only | `"dev-only"` |
+| Dev + Vercel preview | `"vercel-preview"` |
+| Everywhere | `"everywhere"` |
 
 If a custom "Other" answer fails validation, re-ask only that one question in a follow-up `AskUserQuestion` call.
 
@@ -75,27 +86,40 @@ test -e "$TARGET" && echo "EXISTS" || echo "FREE"
 
 If `EXISTS` and Phase 2 didn't already mark this as an existing install: prompt "Path `<TARGET>` already exists but is not an installer artifact. Pick a different route or abort."
 
-## Phase 6: Patch next.config.ts (only if prod-exclusion: yes)
+## Phase 6: Patch next.config.ts (only when `renderMode !== "everywhere"`)
+
+Skip this phase entirely if `renderMode` is `"everywhere"` — those files use plain `.tsx` and ship to prod, so no `pageExtensions` conditional is needed.
+
+For the two excluding modes, the patcher generates a different conditional based on `--render-mode`:
 
 ```bash
 node plugins/adhd/lib/sync-docs/cli.js patch-next-config \
   --config "<next.config.path>" \
-  --route-url "<routeUrl>"
+  --route-url "<routeUrl>" \
+  --render-mode "<dev-only|vercel-preview>"
 ```
 
 Exit codes:
 - `0` — patched successfully (or already at the expected state; idempotent no-op).
 - `3` — the file already sets `pageExtensions` to a different value. The CLI prints the existing value on stdout.
-- non-zero, non-3 — the file's shape isn't safely patchable. Print the manual patch block (see below) and continue with file installs.
+- non-zero, non-3 — the file's shape isn't safely patchable. Print the manual patch block (matching the chosen `renderMode`) and continue with file installs.
 
 **On exit code 3**, use `AskUserQuestion`: "Your next.config.ts sets pageExtensions to `<existing>`. How do you want to handle it? [Show me the manual patch and continue / Abort]."
 
-Automatic merging is NOT supported in v1. On "Show me the manual patch and continue," print this block and continue with Phase 7:
+Automatic merging is NOT supported in v1. On "Show me the manual patch and continue," print the appropriate block for the chosen `renderMode` and continue with Phase 7:
 
 ```ts
+// renderMode: "dev-only"
 pageExtensions: process.env.NODE_ENV === 'production'
   ? ['ts', 'tsx']
   : ['ts', 'tsx', 'design-system.ts', 'design-system.tsx'],
+
+// renderMode: "vercel-preview"
+pageExtensions:
+  process.env.VERCEL_ENV === 'production' ||
+  (!process.env.VERCEL && process.env.NODE_ENV === 'production')
+    ? ['ts', 'tsx']
+    : ['ts', 'tsx', 'design-system.ts', 'design-system.tsx'],
 ```
 
 …and tell the user to merge it with their existing `pageExtensions` value by hand. On "Abort," exit with no further changes.
@@ -113,10 +137,12 @@ Where `<choices.json>` is a temp file with shape:
   "projectRoot": ".",
   "groupName": "(design-system)",
   "routeSegment": "-docs",
-  "prodExcluded": true
+  "renderMode": "dev-only"
 }
 ```
 
+`renderMode` is one of `"dev-only"`, `"vercel-preview"`, or `"everywhere"` (from Phase 3's third question). The installer derives the file extension internally (`.design-system.tsx` for the two excluding modes, plain `.tsx` for `"everywhere"`).
+
 The CLI reads `adhd.config.ts` from `<projectRoot>` to discover the components list and `cssEntry`, bakes them into the generated files (including a per-install `componentMap.tsx` with static imports), and prints the list of files it wrote plus the slugs that ended up in the map.
 
 If `adhd.config.ts` is missing, the CLI aborts with `install: failed to read adhd.config.ts ...`. Phase 1 has already guaranteed it exists, so this only fires if the file vanished between phases — rare, but surface the error verbatim.

From 7e065883978a5f34be220ca6a0d44dc48ba2ac2a Mon Sep 17 00:00:00 2001
From: Hugh Francis <hughfrancis89@gmail.com>
Date: Mon, 11 May 2026 19:52:26 -0400
Subject: [PATCH 31/79] pull-component + pull-design-system: offer to sync docs
 route on success
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

After a successful pull, detect whether the user has the docs route
installed (via the sync-docs detect-install subcommand). If so, ask
whether to re-sync now; if not, skip silently.

- pull-component: new Phase 12 after cleanup. Pulling a component changes
  its props, which means componentMap.tsx's baked prop schemas are now
  stale. Re-syncing refreshes them.
- pull-design-system: new Phase 10 after the final report. Tokens
  propagate live via globals.css so a re-sync isn't strictly needed for
  the tokens themselves, but the prompt copy explains that and offers
  re-sync anyway for users who've also been editing components.

Both prompts use AskUserQuestion with Yes/No options. The existing
install choices (route URL, group, render mode) are preserved because
sync-docs' Phase 2 detects existing installs and offers "Update in
place" — the user doesn't get re-asked for them.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 plugins/adhd/skills/pull-component/SKILL.md   | 23 +++++++++++++++++++
 .../adhd/skills/pull-design-system/SKILL.md   | 23 +++++++++++++++++++
 2 files changed, 46 insertions(+)

diff --git a/plugins/adhd/skills/pull-component/SKILL.md b/plugins/adhd/skills/pull-component/SKILL.md
index 6ba5773..c3d5093 100644
--- a/plugins/adhd/skills/pull-component/SKILL.md
+++ b/plugins/adhd/skills/pull-component/SKILL.md
@@ -503,6 +503,29 @@ Always runs (even on abort):
 rm -rf /tmp/adhd-pull-component
 ```
 
+## Phase 12: Offer to sync the docs route
+
+Runs only on success (skip if Phase 5 aborted). Pulling a component updates its prop interface, which means the static map at `componentMap.tsx` may now be stale (its baked prop schemas were captured the last time `/adhd:sync-docs` ran).
+
+```bash
+node plugins/adhd/lib/sync-docs/cli.js detect-install --app-dir .
+```
+
+- **Empty output** (route not installed): skip this phase silently.
+- **Non-empty output** (route installed): use `AskUserQuestion`:
+
+```
+Question: "Re-sync the design-system docs route now? Pulling the component changed its props, so componentMap.tsx's baked schemas need refreshing."
+Header: "Sync docs"
+Options:
+  - "Yes, re-sync now"
+  - "No, skip"
+```
+
+On "Yes": execute the phases of `/adhd:sync-docs` inline. See `plugins/adhd/skills/sync-docs/SKILL.md` for the phase list. The docs route's existing install choices (route URL, group, render mode) are preserved — Phase 2 of sync-docs detects the existing install and offers "Update in place".
+
+On "No": print `Run /adhd:sync-docs later to refresh the docs route.` Exit normally.
+
 ---
 
 ## Common errors
diff --git a/plugins/adhd/skills/pull-design-system/SKILL.md b/plugins/adhd/skills/pull-design-system/SKILL.md
index 2157c7b..66b0e21 100644
--- a/plugins/adhd/skills/pull-design-system/SKILL.md
+++ b/plugins/adhd/skills/pull-design-system/SKILL.md
@@ -102,6 +102,29 @@ Print:
   - <K> code-only variables left untouched (additive policy)
 ```
 
+## Phase 10: Offer to sync the docs route
+
+Runs only on success (skip if no changes were applied to `globals.css`). The docs route reads `globals.css` at request time, so the new tokens will appear without any code change — but if the user has also been editing components, re-syncing refreshes `componentMap.tsx`'s baked prop schemas at the same time.
+
+```bash
+node plugins/adhd/lib/sync-docs/cli.js detect-install --app-dir .
+```
+
+- **Empty output** (route not installed): skip this phase silently.
+- **Non-empty output** (route installed): use `AskUserQuestion`:
+
+```
+Question: "Re-sync the design-system docs route now? Tokens propagate live, but a re-sync also regenerates componentMap.tsx in case your components changed."
+Header: "Sync docs"
+Options:
+  - "Yes, re-sync now"
+  - "No, skip"
+```
+
+On "Yes": execute the phases of `/adhd:sync-docs` inline. See `plugins/adhd/skills/sync-docs/SKILL.md`. Existing install choices are preserved.
+
+On "No": print `Run /adhd:sync-docs later to refresh the docs route.` Exit normally.
+
 ## Common errors
 
 (Same table as push, plus:)

From d10704f559aa00e2b236909dc7514970b27dda2b Mon Sep 17 00:00:00 2001
From: Hugh Francis <hughfrancis89@gmail.com>
Date: Mon, 11 May 2026 20:04:18 -0400
Subject: [PATCH 32/79] lint + push/pull-component: add --annotate flag
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Pushes lint violations directly to Figma as node-bound annotations,
giving designers visibility into structural/variable issues without
leaving Figma.

Mechanism: ADHD owns a dedicated annotation category named "ADHD lint"
(red). On every run, the use_figma script:
  1. Ensures the category exists (idempotent create-if-missing).
  2. Groups violations by nodeId.
  3. Walks every page to find nodes with prior ADHD-category annotations.
  4. For the union of "previously annotated" and "currently violated"
     nodes, replaces ADHD-category annotations with the current set —
     so fixed violations get their annotations cleared automatically.

Designer-authored annotations and other categories are never touched.
The category persists after ADHD is removed; the annotations become
plain Figma annotations the designer can edit/delete.

Surfaces:
- /adhd:lint --annotate                        — standalone (new Phase 6)
- /adhd:push-component ... --annotate          — preflight (new Phase 10.5)
- /adhd:pull-component ... --annotate          — preflight (extends Phase 2.5)

Implementation detail: push-component's preflight CLI wrapper used to
inherit lint-engine's stdio, so the structured output (with per-violation
nodeIds) wasn't capturable. Changed to pipe stdout, write a JSON sidecar
next to the markdown report, and still echo to the parent process so
existing behavior is preserved. Pull-component already invoked the lint
engine directly; just added a stdout redirect.

The annotation script body lives in /adhd:lint Phase 6. The other two
skills reference that section by name to avoid 50 lines of duplicate
inline JS in each SKILL.

README command table + new section documenting --annotate.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 README.md                                     |  17 ++-
 .../lib/push-component/__tests__/cli.test.js  |   9 ++
 plugins/adhd/lib/push-component/cli.js        |  10 +-
 plugins/adhd/skills/lint/SKILL.md             | 104 +++++++++++++++++-
 plugins/adhd/skills/pull-component/SKILL.md   |  17 ++-
 plugins/adhd/skills/push-component/SKILL.md   |  21 +++-
 6 files changed, 167 insertions(+), 11 deletions(-)

diff --git a/README.md b/README.md
index 834d4ff..c8134b8 100644
--- a/README.md
+++ b/README.md
@@ -29,11 +29,11 @@ After install, seven slash commands are available:
 | Command | Args | Direction | What it does |
 |---|---|---|---|
 | `/adhd:config` | — | — | Interactive wizard that produces `adhd.config.ts`. Verifies the official Figma plugin is installed + authenticated before anything else. |
-| `/adhd:lint` | `[<figma-url>]` | read-only | Validates the Figma file (whole file or scoped) against the local design system + structure best-practices |
+| `/adhd:lint` | `[<figma-url>] [--annotate]` | read-only by default | Validates the Figma file (whole file or scoped) against the local design system + structure best-practices. With `--annotate`, also writes Figma annotations on each offending node in an "ADHD lint" category. |
 | `/adhd:push-design-system` | — | code → Figma | Pushes globals.css variables + named styles into Figma directly via the remote MCP |
 | `/adhd:pull-design-system` | — | Figma → code | Pulls Figma variables + named styles into globals.css |
-| `/adhd:push-component` | `<path> [--max-variants <n>]` | code → Figma | Pushes a React component to Figma as a structured Component Set with variant properties + variable bindings, plus a preflight lint check |
-| `/adhd:pull-component` | `<path \| figma-url> [--allow-unbound]` | Figma → code | Pulls a Figma Component Set into a React source file; updates lookup tables and union types only (function body untouched) |
+| `/adhd:push-component` | `<path> [--max-variants <n>] [--annotate]` | code → Figma | Pushes a React component to Figma as a structured Component Set with variant properties + variable bindings, plus a preflight lint check. `--annotate` annotates preflight violations on Figma nodes. |
+| `/adhd:pull-component` | `<path \| figma-url> [--allow-unbound] [--annotate]` | Figma → code | Pulls a Figma Component Set into a React source file; updates lookup tables and union types only (function body untouched). `--annotate` annotates preflight violations on Figma nodes. |
 | `/adhd:sync-docs` | — | install | Generates a design-system docs route in your Next.js consumer app. Tokens read live from globals.css; components are statically imported from adhd.config.ts at setup time — re-run after editing the components map. Excluded from production builds by default. |
 
 Every command above drives Figma exclusively through the `figma@claude-plugins-official` plugin. `/adhd:config` checks it's installed + authenticated up front so setup errors surface where you can fix them, not mid-pipeline.
@@ -86,6 +86,17 @@ Pass any Figma URL that includes a `node-id` query parameter — `/adhd:lint` wi
 
 The scoped report covers the same rules (STRUCT001–010 + variable mismatches), just narrowed to the selected subtree. The URL must point at the file configured in `adhd.config.ts`; mismatched file keys abort with a fix-up message.
 
+### Annotate violations in Figma (`--annotate`)
+
+By default `/adhd:lint` (and the preflight inside `/adhd:push-component` / `/adhd:pull-component`) is read-only — it writes a local markdown report and exits. Pass `--annotate` to also push each violation to Figma as a node-bound annotation in a dedicated **"ADHD lint"** category (red). Designers see them on the layers panel, and a re-run with `--annotate` cleans up stale ADHD-category annotations automatically (designer-authored annotations and other categories are never touched).
+
+```
+/adhd:lint --annotate                                                            # whole file
+/adhd:lint https://www.figma.com/design/<KEY>?node-id=91-18 --annotate           # scoped
+/adhd:push-component app/components/avatar/index.tsx --annotate                  # preflight
+/adhd:pull-component https://www.figma.com/design/<KEY>?node-id=91-18 --annotate # preflight
+```
+
 ### Push a component
 
 ```
diff --git a/plugins/adhd/lib/push-component/__tests__/cli.test.js b/plugins/adhd/lib/push-component/__tests__/cli.test.js
index 08f9fb2..574dede 100644
--- a/plugins/adhd/lib/push-component/__tests__/cli.test.js
+++ b/plugins/adhd/lib/push-component/__tests__/cli.test.js
@@ -203,4 +203,13 @@ test('preflight subcommand produces a lint report', () => {
   assert.equal(result.status, 0, result.stderr);
   const report = fs.readFileSync(out, 'utf8');
   assert.match(report, /ADHD/);
+
+  // The preflight CLI also writes a JSON sidecar next to the markdown report
+  // (containing the engine's full structured output with per-violation nodeIds).
+  // This is what /adhd:push-component reads when --annotate is set.
+  const sidecar = out.replace(/\.md$/, '.json');
+  assert.ok(fs.existsSync(sidecar), 'expected JSON sidecar next to report');
+  const parsed = JSON.parse(fs.readFileSync(sidecar, 'utf8'));
+  assert.ok(Array.isArray(parsed.structure));
+  assert.ok(Array.isArray(parsed.variable));
 });
diff --git a/plugins/adhd/lib/push-component/cli.js b/plugins/adhd/lib/push-component/cli.js
index 1948f15..9c4a60c 100644
--- a/plugins/adhd/lib/push-component/cli.js
+++ b/plugins/adhd/lib/push-component/cli.js
@@ -413,6 +413,9 @@ function main() {
     // symmetric-pipeline assertion — same code path as /adhd:lint.
     const lintCli = path.resolve(__dirname, '..', 'lint-engine', 'cli.js');
     const { spawnSync } = require('node:child_process');
+    // Capture stdout (the engine's JSON summary including per-violation nodeIds)
+    // instead of inheriting, so the skill can pass it to the annotation script
+    // when --annotate is set. Stderr still inherits — engine warnings stay visible.
     const result = spawnSync('node', [
       lintCli,
       '--design-context', args['design-context'],
@@ -422,7 +425,12 @@ function main() {
       '--target', 'PushComponent Preflight',
       '--target-url', 'about:blank',
       '--output', args.output,
-    ], { encoding: 'utf8', stdio: 'inherit' });
+    ], { encoding: 'utf8', stdio: ['inherit', 'pipe', 'inherit'] });
+    // Sidecar JSON next to the markdown report.
+    const sidecar = args.output.replace(/\.md$/, '.json');
+    fs.writeFileSync(sidecar, result.stdout ?? '');
+    // Echo stdout to the parent process too, preserving prior behavior.
+    if (result.stdout) process.stdout.write(result.stdout);
     process.exit(result.status ?? 1);
   }
 
diff --git a/plugins/adhd/skills/lint/SKILL.md b/plugins/adhd/skills/lint/SKILL.md
index 633c10c..062d47a 100644
--- a/plugins/adhd/skills/lint/SKILL.md
+++ b/plugins/adhd/skills/lint/SKILL.md
@@ -1,7 +1,7 @@
 ---
-description: "Validate Figma frames/components/pages or the entire file against the local Tailwind design system + frame-structure best practices. Reads adhd.config.ts at the repo root. Read-only — no writes. Optional argument: a Figma URL with node-id (scoped lint). With no argument, lints the whole file."
+description: "Validate Figma frames/components/pages or the entire file against the local Tailwind design system + frame-structure best practices. Reads adhd.config.ts at the repo root. Read-only by default; with --annotate, also writes Figma annotations on each offending node in an 'ADHD lint' category. Optional argument: a Figma URL with node-id (scoped lint). With no argument, lints the whole file."
 disable-model-invocation: true
-argument-hint: "[<figma-url-with-node-id>]"
+argument-hint: "[<figma-url-with-node-id>] [--annotate]"
 allowed-tools: Read Write Bash AskUserQuestion mcp__plugin_figma_figma__use_figma
 ---
 
@@ -65,7 +65,7 @@ If the response indicates `error: 'Node not found'`, abort with: "Node not found
 
 ## Phase 4: Run the engine
 
-Use the `Bash` tool:
+Use the `Bash` tool. Redirect stdout (the engine's JSON summary) to a temp file so Phase 6 can re-use it for `--annotate`:
 
 ```bash
 node plugins/adhd/lib/lint-engine/cli.js \
@@ -75,7 +75,8 @@ node plugins/adhd/lib/lint-engine/cli.js \
   --config adhd.config.ts \
   --target "<target-label>" \
   --target-url "<target-url>" \
-  --output adhd-lint-report.md
+  --output adhd-lint-report.md \
+  > /tmp/adhd-lint/stdout.json
 ```
 
 Where `<target-label>` is `"Whole file"` in whole-file mode, or `"<page> / <node-name>"` in scoped mode. `<target-url>` is `<figma.url>` (whole-file) or the original URL with node-id (scoped).
@@ -97,6 +98,101 @@ Read `adhd-lint-report.md` with the `Read` tool and echo it to the user verbatim
 
 Mention the report file path: "Full report: `adhd-lint-report.md` (paste-ready for Figma comments / Slack)."
 
+## Phase 6: Optional — annotate offending nodes in Figma (`--annotate`)
+
+If the user passed `--annotate` (the only flag this skill accepts), push each violation to Figma as an annotation on its `nodeId`. ADHD owns a dedicated annotation category named **"ADHD lint"** (red); designer-authored annotations and any other categories are left untouched.
+
+If `--annotate` was NOT passed, skip this phase.
+
+### Inputs
+
+The lint engine's stdout (captured to `/tmp/adhd-lint/stdout.json` during Phase 4) is a JSON object with `variable` and `structure` arrays. Combine them into a flat violation list keeping only items with a `nodeId`:
+
+```bash
+node -e '
+const r = JSON.parse(require("fs").readFileSync("/tmp/adhd-lint/stdout.json", "utf8"));
+const all = [...(r.structure ?? []), ...(r.variable ?? [])].filter(v => v.nodeId);
+const out = all.map(v => ({ nodeId: v.nodeId, code: v.code, message: v.message, severity: v.severity ?? "error" }));
+require("fs").writeFileSync("/tmp/adhd-lint/violations.json", JSON.stringify(out));
+console.log(out.length);
+'
+```
+
+### The use_figma script
+
+Pass the violations array to `mcp__plugin_figma_figma__use_figma` with `skillNames: "figma-use"`. The script ensures the category exists, applies current violations, and clears stale ADHD annotations file-wide (so a re-run reflects the current state — fixed violations get their annotations cleared automatically).
+
+```js
+const VIOLATIONS = /* substituted: contents of /tmp/adhd-lint/violations.json */;
+const CATEGORY_LABEL = "ADHD lint";
+const CATEGORY_COLOR = "red";
+
+// 1) Ensure the ADHD lint category exists (idempotent across runs).
+const cats = await figma.annotations.getAnnotationCategoriesAsync();
+let cat = cats.find(c => c.label === CATEGORY_LABEL);
+if (!cat) {
+  cat = await figma.annotations.addAnnotationCategoryAsync({ label: CATEGORY_LABEL, color: CATEGORY_COLOR });
+}
+
+// 2) Group violations by nodeId.
+const byNode = new Map();
+for (const v of VIOLATIONS) {
+  if (!byNode.has(v.nodeId)) byNode.set(v.nodeId, []);
+  byNode.get(v.nodeId).push(v);
+}
+
+// 3) Walk every page to find nodes with prior ADHD annotations + apply updates.
+//    Pages load incrementally — use `setCurrentPageAsync` so `findAll` sees their content.
+let updated = 0, cleared = 0;
+const touchedIds = new Set();
+
+for (const page of figma.root.children) {
+  await figma.setCurrentPageAsync(page);
+  // Previously-annotated nodes under this page.
+  const prior = page.findAll(n =>
+    "annotations" in n && (n.annotations ?? []).some(a => a.categoryId === cat.id)
+  );
+  for (const n of prior) touchedIds.add(n.id);
+}
+
+// Union of "previously annotated" and "currently violated" — every node that needs a write.
+const allTargetIds = new Set([...touchedIds, ...byNode.keys()]);
+
+for (const id of allTargetIds) {
+  const node = await figma.getNodeByIdAsync(id);
+  if (!node || !("annotations" in node)) continue;
+  const keep = (node.annotations ?? []).filter(a => a.categoryId !== cat.id);
+  const fresh = (byNode.get(id) ?? []).map(v => ({
+    label: `${v.code}: ${v.message}`,
+    categoryId: cat.id,
+  }));
+  const hadAdhd = touchedIds.has(id);
+  node.annotations = [...keep, ...fresh];
+  if (fresh.length > 0) updated++;
+  else if (hadAdhd) cleared++;
+}
+
+return { categoryId: cat.id, categoryLabel: cat.label, updated, cleared, totalViolations: VIOLATIONS.length };
+```
+
+### Report the result
+
+After the script returns, print one line:
+
+```
+✓ Annotated <updated> Figma node(s) in the "ADHD lint" category. Cleared <cleared> stale annotation(s).
+```
+
+If `updated === 0 && cleared === 0`, print:
+
+```
+No node-bound violations to annotate (whole-file violations like pageGrouping are reported but not annotated).
+```
+
+### Why a dedicated category
+
+The "ADHD lint" category gives designers a one-click filter in Figma's annotations panel and lets us cleanly own/replace our own annotations without touching designer-authored ones. The category persists in the file — even after the user uninstalls ADHD, the annotations remain as plain Figma annotations the designer can edit or delete.
+
 ## Common errors
 
 | Error | Fix-up guidance |
diff --git a/plugins/adhd/skills/pull-component/SKILL.md b/plugins/adhd/skills/pull-component/SKILL.md
index c3d5093..dc43801 100644
--- a/plugins/adhd/skills/pull-component/SKILL.md
+++ b/plugins/adhd/skills/pull-component/SKILL.md
@@ -1,7 +1,7 @@
 ---
 description: "Pull a Figma Component Set into a React component source file. Inverse of /adhd:push-component. Updates only design-token lookup tables and union type members — function body, JSX, hooks, handlers, and imports are never modified. Reads adhd.config.ts and uses the mapping at components.<path>.figma.url. Pre-flight validates the Figma source using the same lint engine /adhd:lint uses; structural violations abort the pull."
 disable-model-invocation: true
-argument-hint: "<react-path | figma-url> [--allow-unbound]"
+argument-hint: "<react-path | figma-url> [--allow-unbound] [--annotate]"
 allowed-tools: Read Write Edit Bash AskUserQuestion mcp__plugin_figma_figma__use_figma
 ---
 
@@ -84,13 +84,26 @@ node plugins/adhd/lib/lint-engine/cli.js \
   --config adhd.config.ts \
   --target "PullComponent Preflight" \
   --target-url "<figma-url>" \
-  --output /tmp/adhd-pull-component/preflight.md
+  --output /tmp/adhd-pull-component/preflight.md \
+  > /tmp/adhd-pull-component/stdout.json
 ```
 
+The stdout redirect captures the engine's JSON summary for Phase 2.6's optional `--annotate` step.
+
 Use the globals.css path from `config.cssEntry` if set, otherwise auto-detect: `example/app/globals.css` → `app/globals.css` → `src/app/globals.css`.
 
 Use `Read` on `/tmp/adhd-pull-component/preflight.md`. Scan for STRUCT003/004/005 (variable-binding errors). Other rules' violations are noted for the final report but don't block.
 
+### Optional — annotate offending nodes in Figma (`--annotate`)
+
+If the user passed `--annotate` to `/adhd:pull-component`, push the preflight violations to Figma as annotations using the **same flow described in `/adhd:lint` Phase 6**:
+
+- Engine stdout: `/tmp/adhd-pull-component/stdout.json`
+- Distill to `/tmp/adhd-pull-component/violations.json` (filter for `nodeId`-bearing entries) using the same `node -e` snippet as lint Phase 6, with the pull-component paths substituted.
+- Run the same `use_figma` script (the ADHD lint category + per-node replace logic).
+
+Annotate BEFORE evaluating the abort condition below, so the designer sees the annotations even when the pull aborts. Without `--annotate`, skip silently.
+
 **If variable-binding errors exist:**
 
 Check whether the escape is active:
diff --git a/plugins/adhd/skills/push-component/SKILL.md b/plugins/adhd/skills/push-component/SKILL.md
index aaf850c..a98c744 100644
--- a/plugins/adhd/skills/push-component/SKILL.md
+++ b/plugins/adhd/skills/push-component/SKILL.md
@@ -1,7 +1,7 @@
 ---
 description: "Push a React component to the configured Figma file as a structured Component Set. Reads adhd.config.ts. Parses the component's variant axes from its TypeScript prop unions, generates a temp Next.js preview route, auto-starts the dev server if needed (and tears it down after), captures via generate_figma_design, wraps the captured frames into a Component Set with variant properties, rebinds raw values to existing design-system variables, and runs the same lint engine /adhd:lint uses as a preflight check before finalizing."
 disable-model-invocation: true
-argument-hint: "<component-path> [--max-variants <n>]"
+argument-hint: "<component-path> [--max-variants <n>] [--annotate]"
 allowed-tools: Read Write Edit Bash AskUserQuestion mcp__plugin_figma_figma__use_figma mcp__plugin_figma_figma__generate_figma_design
 ---
 
@@ -178,6 +178,25 @@ node plugins/adhd/lib/push-component/cli.js preflight \
 
 Read the report. Parse out error count and warning count.
 
+The preflight CLI also writes a JSON sidecar with the engine's full structured output at `/tmp/adhd-push-component/preflight-report.json` (same path as the report, `.md` → `.json`). Phase 10.5 uses this when `--annotate` is set.
+
+## Phase 10.5: Optional — annotate offending nodes in Figma (`--annotate`)
+
+If the user passed `--annotate` to `/adhd:push-component` AND the preflight surfaced any node-bound violations, push them to Figma as annotations using the **same flow described in `/adhd:lint` Phase 6**.
+
+Inputs:
+- Engine stdout: `/tmp/adhd-push-component/preflight-report.json`
+- Distill to `/tmp/adhd-push-component/violations.json` (filter for `nodeId`-bearing entries) using the same `node -e` snippet as lint Phase 6, just with the push-component paths substituted.
+- Run the same `use_figma` script (the ADHD lint category + per-node replace logic).
+
+After it returns, print:
+
+```
+✓ Annotated <updated> Figma node(s) in the "ADHD lint" category. Cleared <cleared> stale annotation(s).
+```
+
+Annotating happens AFTER the preflight CLI exits but BEFORE Phase 11's decide-or-rollback. That way the designer sees the annotations even when push aborts on errors. Without `--annotate`, skip silently.
+
 ## Phase 11: Decide and finalize OR roll back
 
 If preflight has zero errors: print "✓ Preflight clean" plus warning summary, then proceed to Phase 12.

From 07043c275085697a3fb8e393b491218dd3bb4457 Mon Sep 17 00:00:00 2001
From: Hugh Francis <hughfrancis89@gmail.com>
Date: Mon, 11 May 2026 20:18:58 -0400
Subject: [PATCH 33/79] lint + push/pull-component: offer to annotate when
 --annotate wasn't passed
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

UX improvement. When a lint produces violations or a push/pull preflight
fails on node-bound errors AND the user didn't pass --annotate, offer it
retroactively via AskUserQuestion. Saves the user from having to re-run
with the flag once they've seen the report.

- /adhd:lint: new Phase 7 fires whenever any violation has a nodeId (works
  for both errors and warnings, both whole-file and scoped modes). Lint
  is a passive command — surfacing violations is its main action, so it's
  natural to prompt every time.
- /adhd:push-component: Phase 10.5 now has two paths (--annotate set OR
  prompt-on-blocking-errors). Push proceeds via Phase 11 even if the user
  says no to the annotate prompt; the prompt is purely additive.
- /adhd:pull-component: Phase 2.5 same shape. Prompt fires only when
  STRUCT003/004/005 errors would abort or trigger the --allow-unbound
  escape — non-blocking violations don't interrupt the flow.

Skip the prompt entirely if zero violations have nodeIds (nothing to
annotate). The annotation work itself is unchanged — same use_figma
script described in /adhd:lint Phase 6, single source of truth.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 plugins/adhd/skills/lint/SKILL.md           | 20 +++++++++++++
 plugins/adhd/skills/pull-component/SKILL.md | 26 +++++++++++++----
 plugins/adhd/skills/push-component/SKILL.md | 32 +++++++++++++++------
 3 files changed, 64 insertions(+), 14 deletions(-)

diff --git a/plugins/adhd/skills/lint/SKILL.md b/plugins/adhd/skills/lint/SKILL.md
index 062d47a..d8961e5 100644
--- a/plugins/adhd/skills/lint/SKILL.md
+++ b/plugins/adhd/skills/lint/SKILL.md
@@ -193,6 +193,26 @@ No node-bound violations to annotate (whole-file violations like pageGrouping ar
 
 The "ADHD lint" category gives designers a one-click filter in Figma's annotations panel and lets us cleanly own/replace our own annotations without touching designer-authored ones. The category persists in the file — even after the user uninstalls ADHD, the annotations remain as plain Figma annotations the designer can edit or delete.
 
+## Phase 7: Offer to annotate when `--annotate` wasn't passed
+
+If `--annotate` was passed, this phase is a no-op (Phase 6 already ran).
+
+If `--annotate` was NOT passed AND the lint produced at least one violation with a `nodeId` (count it from `/tmp/adhd-lint/stdout.json` using the same `node -e` snippet as Phase 6 — count of items in the distilled violations array), use `AskUserQuestion`:
+
+```
+Question: "Push these <N> violation(s) to Figma as annotations? They'll appear on the offending nodes in an 'ADHD lint' category that designers can filter on."
+Header: "Annotate?"
+Options:
+  - "Yes, annotate them in Figma"
+  - "No, skip"
+```
+
+On "Yes": run Phase 6 inline (the distill step + the `use_figma` script) and print the result line.
+
+On "No": exit normally with no annotation work done.
+
+If there are zero `nodeId`-bearing violations (e.g. only whole-file violations like `pageGrouping`), skip the prompt — there's nothing to annotate.
+
 ## Common errors
 
 | Error | Fix-up guidance |
diff --git a/plugins/adhd/skills/pull-component/SKILL.md b/plugins/adhd/skills/pull-component/SKILL.md
index dc43801..1524809 100644
--- a/plugins/adhd/skills/pull-component/SKILL.md
+++ b/plugins/adhd/skills/pull-component/SKILL.md
@@ -94,15 +94,31 @@ Use the globals.css path from `config.cssEntry` if set, otherwise auto-detect: `
 
 Use `Read` on `/tmp/adhd-pull-component/preflight.md`. Scan for STRUCT003/004/005 (variable-binding errors). Other rules' violations are noted for the final report but don't block.
 
-### Optional — annotate offending nodes in Figma (`--annotate`)
+### Annotate offending nodes in Figma
 
-If the user passed `--annotate` to `/adhd:pull-component`, push the preflight violations to Figma as annotations using the **same flow described in `/adhd:lint` Phase 6**:
+Two paths, both producing the same `use_figma` annotation work described in `/adhd:lint` Phase 6:
 
+**Path A — `--annotate` was passed.** Run the annotation script unconditionally.
+
+**Path B — `--annotate` was NOT passed, AND there are variable-binding errors (STRUCT003/004/005) that will block the pull.** Use `AskUserQuestion` to offer it retroactively:
+
+```
+Question: "Push these <N> preflight violation(s) to Figma as annotations before aborting? Designers can see them in the 'ADHD lint' category to fix in-context."
+Header: "Annotate?"
+Options:
+  - "Yes, annotate them in Figma"
+  - "No, skip"
+```
+
+On "Yes": run the annotation script. On "No": skip silently.
+
+For Path B, skip the prompt if no violation has a `nodeId` (no actionable annotations to write).
+
+Inputs (both paths):
 - Engine stdout: `/tmp/adhd-pull-component/stdout.json`
-- Distill to `/tmp/adhd-pull-component/violations.json` (filter for `nodeId`-bearing entries) using the same `node -e` snippet as lint Phase 6, with the pull-component paths substituted.
-- Run the same `use_figma` script (the ADHD lint category + per-node replace logic).
+- Distill to `/tmp/adhd-pull-component/violations.json` using the same `node -e` snippet as lint Phase 6.
 
-Annotate BEFORE evaluating the abort condition below, so the designer sees the annotations even when the pull aborts. Without `--annotate`, skip silently.
+Either path runs BEFORE the abort/escape evaluation below, so the designer sees the annotations regardless of whether the pull continues.
 
 **If variable-binding errors exist:**
 
diff --git a/plugins/adhd/skills/push-component/SKILL.md b/plugins/adhd/skills/push-component/SKILL.md
index a98c744..da8ac49 100644
--- a/plugins/adhd/skills/push-component/SKILL.md
+++ b/plugins/adhd/skills/push-component/SKILL.md
@@ -180,22 +180,36 @@ Read the report. Parse out error count and warning count.
 
 The preflight CLI also writes a JSON sidecar with the engine's full structured output at `/tmp/adhd-push-component/preflight-report.json` (same path as the report, `.md` → `.json`). Phase 10.5 uses this when `--annotate` is set.
 
-## Phase 10.5: Optional — annotate offending nodes in Figma (`--annotate`)
+## Phase 10.5: Annotate offending nodes in Figma
 
-If the user passed `--annotate` to `/adhd:push-component` AND the preflight surfaced any node-bound violations, push them to Figma as annotations using the **same flow described in `/adhd:lint` Phase 6**.
+Two paths into this phase, both producing the same `use_figma` annotation work described in `/adhd:lint` Phase 6:
 
-Inputs:
-- Engine stdout: `/tmp/adhd-push-component/preflight-report.json`
-- Distill to `/tmp/adhd-push-component/violations.json` (filter for `nodeId`-bearing entries) using the same `node -e` snippet as lint Phase 6, just with the push-component paths substituted.
-- Run the same `use_figma` script (the ADHD lint category + per-node replace logic).
-
-After it returns, print:
+**Path A — `--annotate` was passed.** Run the annotation script unconditionally. After it returns, print:
 
 ```
 ✓ Annotated <updated> Figma node(s) in the "ADHD lint" category. Cleared <cleared> stale annotation(s).
 ```
 
-Annotating happens AFTER the preflight CLI exits but BEFORE Phase 11's decide-or-rollback. That way the designer sees the annotations even when push aborts on errors. Without `--annotate`, skip silently.
+**Path B — `--annotate` was NOT passed, AND preflight produced node-bound errors that will abort the push.** Use `AskUserQuestion` to offer it retroactively:
+
+```
+Question: "Push these <N> preflight violation(s) to Figma as annotations before aborting? Designers can see them in the 'ADHD lint' category to fix in-context."
+Header: "Annotate?"
+Options:
+  - "Yes, annotate them in Figma"
+  - "No, skip"
+```
+
+On "Yes": run the same annotation script and print the result line.
+On "No": skip silently.
+
+For Path B, skip the prompt if (a) preflight is clean (no errors blocking the push), or (b) no violation has a `nodeId`.
+
+Inputs (both paths):
+- Engine stdout: `/tmp/adhd-push-component/preflight-report.json`
+- Distill to `/tmp/adhd-push-component/violations.json` using the same `node -e` snippet as lint Phase 6.
+
+Phase 10.5 runs AFTER the preflight CLI exits but BEFORE Phase 11's decide-or-rollback — designers see annotations even when push aborts.
 
 ## Phase 11: Decide and finalize OR roll back
 

From 156f54f94dee71ae9f9f5bb542b809dca3004340 Mon Sep 17 00:00:00 2001
From: Hugh Francis <hughfrancis89@gmail.com>
Date: Mon, 11 May 2026 20:26:19 -0400
Subject: [PATCH 34/79] lint STRUCT001: widen exemption to multi-child
 shape-only frames
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

User hit a false positive on a Logo Component Set variant: a frame
whose children were multiple vector paths composing one shape. The rule
exempted single-child shape wrappers (icon/logo containers) but fired on
multi-child compositions even when every child was a shape primitive.

Reality: a frame whose children are ALL shape primitives (VECTOR,
BOOLEAN_OPERATION, ELLIPSE, RECTANGLE, STAR, POLYGON, LINE) rasterizes
to a single SVG. Flexbox doesn't apply. Multi-path wordmarks, composite
icons, illustrations with multiple paths, and decorative shape stacks
are the canonical cases.

Mixed-content frames still fire — if even one child is text, a frame,
or any non-shape, the auto-layout requirement holds because that child
needs padding/alignment control.

The SINGLE_CHILD_SHAPE_EXEMPT set is renamed to SHAPE_PRIMITIVE_TYPES
since it's no longer single-child-specific. The set itself is unchanged.

Tests: flipped the "still flags a frame with 2+ VECTOR children" test
to assert the opposite (no STRUCT001 for all-shape multi-child) and
added a positive test for mixed shapes + non-shapes to guard the new
exemption from over-widening.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 .../__tests__/structure-checker.test.js       | 26 ++++++++++++++++---
 .../adhd/lib/lint-engine/structure-checker.js | 21 ++++++++-------
 2 files changed, 35 insertions(+), 12 deletions(-)

diff --git a/plugins/adhd/lib/lint-engine/__tests__/structure-checker.test.js b/plugins/adhd/lib/lint-engine/__tests__/structure-checker.test.js
index ffc5f63..9a380f0 100644
--- a/plugins/adhd/lib/lint-engine/__tests__/structure-checker.test.js
+++ b/plugins/adhd/lib/lint-engine/__tests__/structure-checker.test.js
@@ -51,6 +51,24 @@ test('STRUCT001: does NOT flag a frame holding a single shape primitive (icon/lo
   }
 });
 
+test('STRUCT001: does NOT flag a frame whose children are all shape primitives (multi-path SVG)', () => {
+  // Real-world case: a Logo Component Set variant that's a composite of multiple
+  // vector paths (e.g. a wordmark with separate paths per letter, or a mark with
+  // multiple boolean-op layers). The whole frame rasterizes to a single SVG;
+  // flexbox doesn't apply. Auto-layout would be incorrect here.
+  const node = makeFrame({
+    layoutMode: 'NONE',
+    children: [
+      { id: '1:2', name: 'path-1', type: 'VECTOR' },
+      { id: '1:3', name: 'path-2', type: 'VECTOR' },
+      { id: '1:4', name: 'mask',   type: 'BOOLEAN_OPERATION' },
+      { id: '1:5', name: 'dot',    type: 'ELLIPSE' },
+    ],
+  });
+  const violations = checkStructure(node, { fileKey: FIGMA_FILE_KEY, namingConvention: 'kebab-case' });
+  assert.equal(violations.filter(v => v.rule === 'STRUCT001').length, 0);
+});
+
 test('STRUCT001: still flags a frame with a single TEXT child (needs padding/alignment control)', () => {
   const node = makeFrame({
     layoutMode: 'NONE',
@@ -69,12 +87,14 @@ test('STRUCT001: still flags a frame with a single FRAME child', () => {
   assert.ok(violations.find(v => v.rule === 'STRUCT001'));
 });
 
-test('STRUCT001: still flags a frame with 2+ children regardless of types', () => {
+test('STRUCT001: still flags a frame with mixed shapes + non-shape children (needs auto-layout)', () => {
+  // If even one child isn't a shape primitive, the exemption doesn't apply —
+  // the non-shape needs auto-layout for padding/alignment.
   const node = makeFrame({
     layoutMode: 'NONE',
     children: [
-      { id: '1:2', name: 'a', type: 'VECTOR' },
-      { id: '1:3', name: 'b', type: 'VECTOR' },
+      { id: '1:2', name: 'icon-path', type: 'VECTOR' },
+      { id: '1:3', name: 'label',     type: 'TEXT' },
     ],
   });
   const violations = checkStructure(node, { fileKey: FIGMA_FILE_KEY, namingConvention: 'kebab-case' });
diff --git a/plugins/adhd/lib/lint-engine/structure-checker.js b/plugins/adhd/lib/lint-engine/structure-checker.js
index 0e156d2..90f9111 100644
--- a/plugins/adhd/lib/lint-engine/structure-checker.js
+++ b/plugins/adhd/lib/lint-engine/structure-checker.js
@@ -2,9 +2,11 @@
 
 const AUTO_NAME_RE = /^(Frame|Group|Rectangle|Ellipse|Vector|Line|Star|Polygon)\s+\d+$/;
 
-// Shape primitives that, as a frame's only child, fill the container via constraints
-// and do not benefit from auto-layout (icons, logos, decorative backgrounds).
-const SINGLE_CHILD_SHAPE_EXEMPT = new Set([
+// Shape primitives that don't benefit from auto-layout. A frame whose
+// children are ALL of these types is exempt from STRUCT001 — the frame is
+// going to be rasterized to a single SVG (multi-path icons, logos,
+// illustrations, decorative shapes), so flexbox doesn't apply.
+const SHAPE_PRIMITIVE_TYPES = new Set([
   'VECTOR', 'BOOLEAN_OPERATION', 'ELLIPSE', 'RECTANGLE', 'STAR', 'POLYGON', 'LINE',
 ]);
 
@@ -40,15 +42,16 @@ function visit(node, ctx, parentPath, parent) {
   };
 
   // STRUCT001: auto-layout required.
-  // Exempt: a frame whose ONLY child is a shape primitive (icon / logo / decorative
-  // shape that fills the container via constraints). Multi-child frames and
-  // single-child wrappers around TEXT / FRAME / COMPONENT / INSTANCE still fire —
-  // those typically want auto-layout for padding and alignment.
+  // Exempt: a frame whose children are ALL shape primitives. Covers the icon /
+  // logo / illustration case — single Vector, multi-path Vector compositions,
+  // boolean operations, decorative rectangles, etc. These rasterize to a single
+  // SVG; flexbox doesn't apply. Mixed-content frames (text + shape, frame +
+  // shape, etc.) still fire — those want auto-layout for padding and alignment.
   if ((node.type === 'FRAME' || node.type === 'COMPONENT' || node.type === 'INSTANCE') &&
       Array.isArray(node.children) && node.children.length > 0 &&
       node.layoutMode === 'NONE') {
-    const exempt = node.children.length === 1 && SINGLE_CHILD_SHAPE_EXEMPT.has(node.children[0].type);
-    if (!exempt) {
+    const allShapes = node.children.every(c => SHAPE_PRIMITIVE_TYPES.has(c.type));
+    if (!allShapes) {
       push('STRUCT001', 'error', 'Frame has children but auto-layout is not enabled.');
     }
   }

From 47bcbd8259bb01cf200c9c56df2df3d478a9a11e Mon Sep 17 00:00:00 2001
From: Hugh Francis <hughfrancis89@gmail.com>
Date: Mon, 11 May 2026 20:30:49 -0400
Subject: [PATCH 35/79] lint STRUCT007 + STRUCT010: stronger diagnostic copy
 for variant-intent cases
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

User report: a frame with light/dark sub-components fired with terse
copy ("2 sibling components named 'Logo/...' should be wrapped in a
Component Set"). The designer's intent — variants of one component —
isn't acknowledged, and the codegen consequence isn't called out, so
the warning is easy to dismiss. Worse, if it IS dismissed, code gen
will silently import each sibling as a separate component instead of
one component with prop axes.

STRUCT007 rewrite:
- Names the specific siblings ("light", "dark", ...) capped at 4 with
  "+N more" overflow.
- Calls them out as suspected variants of the shared prefix.
- Tells the designer the exact Figma action ("select all → right-click
  → 'Combine as Variants'").
- Spells out the codegen consequence: "otherwise code generation
  imports them as N separate components instead of one with a prop
  axis." Drives home why this matters, not just what's wrong.

STRUCT010 rewrite:
- Counts the existing variants in the message.
- Suggests realistic property examples (theme = light | dark, size = ...).
- Same codegen-consequence framing so the designer connects the dot
  between "no property declared" and "N separate components in code".

Tests: existing STRUCT007/STRUCT010 tests strengthened to assert the
diagnostic content (named siblings, prefix, Figma action, consequence).
Added a truncation test for STRUCT007 (4 shown + "+N more" suffix).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 .../__tests__/structure-checker.test.js       | 40 ++++++++++++++++---
 .../adhd/lib/lint-engine/structure-checker.js | 27 +++++++++++--
 2 files changed, 58 insertions(+), 9 deletions(-)

diff --git a/plugins/adhd/lib/lint-engine/__tests__/structure-checker.test.js b/plugins/adhd/lib/lint-engine/__tests__/structure-checker.test.js
index 9a380f0..0733eaa 100644
--- a/plugins/adhd/lib/lint-engine/__tests__/structure-checker.test.js
+++ b/plugins/adhd/lib/lint-engine/__tests__/structure-checker.test.js
@@ -235,7 +235,7 @@ test('STRUCT008: flags auto-named layers like "Frame 47"', () => {
   assert.ok(violations.find(v => v.rule === 'STRUCT008'));
 });
 
-test('STRUCT010: flags a Component Set with children that have empty variantProperties', () => {
+test('STRUCT010: flags a Component Set with children that have empty variantProperties + diagnostic message', () => {
   const node = {
     id: '1:1',
     name: 'Button',
@@ -247,7 +247,13 @@ test('STRUCT010: flags a Component Set with children that have empty variantProp
     ],
   };
   const violations = checkStructure(node, { fileKey: FIGMA_FILE_KEY, namingConvention: 'kebab-case' });
-  assert.ok(violations.find(v => v.rule === 'STRUCT010'));
+  const struct010 = violations.find(v => v.rule === 'STRUCT010');
+  assert.ok(struct010);
+  // Message names the count, suggests a property example, and calls out the
+  // codegen consequence so the designer understands the fix is non-optional.
+  assert.match(struct010.message, /2 variant\(s\) but no variant property/);
+  assert.match(struct010.message, /Properties panel/);
+  assert.match(struct010.message, /2 separate components/);
 });
 
 test('STRUCT010: does not flag a Component Set with declared variant properties', () => {
@@ -407,19 +413,41 @@ test('STRUCT006: flags a FRAME with wasInstance: true (warning, not error)', ()
   assert.equal(struct006.severity, 'warning');
 });
 
-test('STRUCT007: flags sibling components sharing a name prefix outside a Component Set', () => {
+test('STRUCT007: flags sibling components sharing a name prefix outside a Component Set with diagnostic message', () => {
   const node = makeFrame({
     type: 'FRAME',
     children: [
-      { id: '1:2', name: 'Button/primary', type: 'COMPONENT' },
-      { id: '1:3', name: 'Button/secondary', type: 'COMPONENT' },
+      { id: '1:2', name: 'Logo/light', type: 'COMPONENT' },
+      { id: '1:3', name: 'Logo/dark', type: 'COMPONENT' },
     ],
   });
   const violations = checkStructure(node, { fileKey: FIGMA_FILE_KEY, namingConvention: 'kebab-case' });
   const struct007 = violations.find(v => v.rule === 'STRUCT007');
   assert.ok(struct007, 'expected STRUCT007 violation');
   assert.equal(struct007.severity, 'warning');
-  assert.match(struct007.message, /Button\/\.\.\./);
+  // The message names the prefix, the specific siblings, and the codegen
+  // consequence — so a designer reading the annotation in Figma understands
+  // what to fix AND why it matters.
+  assert.match(struct007.message, /"Logo\/"/);
+  assert.match(struct007.message, /"light"/);
+  assert.match(struct007.message, /"dark"/);
+  assert.match(struct007.message, /look like variants/i);
+  assert.match(struct007.message, /Combine as Variants/);
+  assert.match(struct007.message, /code generation/i);
+});
+
+test('STRUCT007: truncates the suffix list to four with a "+N more" hint when there are many', () => {
+  const node = makeFrame({
+    type: 'FRAME',
+    children: Array.from({ length: 7 }, (_, i) => ({
+      id: `1:${10 + i}`, name: `Logo/v${i + 1}`, type: 'COMPONENT',
+    })),
+  });
+  const violations = checkStructure(node, { fileKey: FIGMA_FILE_KEY, namingConvention: 'kebab-case' });
+  const struct007 = violations.find(v => v.rule === 'STRUCT007');
+  assert.ok(struct007);
+  // First four suffixes shown, then "+3 more"
+  assert.match(struct007.message, /"v1", "v2", "v3", "v4", \+3 more/);
 });
 
 test('STRUCT007: does not flag a single child component (no siblings to group)', () => {
diff --git a/plugins/adhd/lib/lint-engine/structure-checker.js b/plugins/adhd/lib/lint-engine/structure-checker.js
index 90f9111..22080f7 100644
--- a/plugins/adhd/lib/lint-engine/structure-checker.js
+++ b/plugins/adhd/lib/lint-engine/structure-checker.js
@@ -162,7 +162,14 @@ function visit(node, ctx, parentPath, parent) {
     }
   }
 
-  // STRUCT007: sibling components share a name prefix but aren't wrapped in a Component Set
+  // STRUCT007: sibling components share a name prefix but aren't wrapped in a
+  // Component Set. The wording calls out the suspected variant intent and the
+  // codegen consequence — a designer who organized siblings as "Logo/light"
+  // and "Logo/dark" was almost certainly trying to model a variant axis, and
+  // we want them to know that without the Component Set wrapper each sibling
+  // becomes a separately-imported component instead of one component with
+  // prop axes. Strong copy here is the difference between code gen quietly
+  // doing the wrong thing and the designer fixing the source.
   if (Array.isArray(node.children) && node.type !== 'COMPONENT_SET') {
     const components = node.children.filter(c => c.type === 'COMPONENT');
     const byPrefix = {};
@@ -173,8 +180,20 @@ function visit(node, ctx, parentPath, parent) {
     }
     for (const [prefix, group] of Object.entries(byPrefix)) {
       if (group.length >= 2) {
+        // Pull the suffix from each sibling for the message (e.g. "light", "dark").
+        // Cap the displayed list at 4 and add a count suffix if there are more.
+        const suffixes = group.map(c => {
+          const rest = c.name.slice(prefix.length + 1); // strip "prefix/"
+          return rest || c.name;
+        });
+        const shown = suffixes.slice(0, 4).map(s => `"${s}"`).join(', ');
+        const more = suffixes.length > 4 ? `, +${suffixes.length - 4} more` : '';
         push('STRUCT007', 'warning',
-          `${group.length} sibling components named "${prefix}/..." should be wrapped in a Component Set.`);
+          `${group.length} sibling components share the "${prefix}/" prefix (${shown}${more}). ` +
+          `These look like variants of "${prefix}". Wrap them in a Component Set ` +
+          `(select all → right-click → "Combine as Variants") and add a variant property — ` +
+          `otherwise code generation imports them as ${group.length} separate components instead of one ` +
+          `"${prefix}" component with a prop axis.`);
         break;
       }
     }
@@ -189,7 +208,9 @@ function visit(node, ctx, parentPath, parent) {
     );
     if (!hasDefs && allChildrenEmpty) {
       push('STRUCT010', 'error',
-        'Component Set has no variant properties declared. Define variant axes (size, state, etc.).');
+        `Component Set has ${node.children.length} variant(s) but no variant property declared. ` +
+        `Add one in the Figma Properties panel (e.g. theme = light | dark, size = sm | md | lg) — ` +
+        `without it, code generation can't tell the variants apart and will import them as ${node.children.length} separate components.`);
     }
   }
 

From 254e60d2f870deb4b1b267af3a5226cbf35be1ec Mon Sep 17 00:00:00 2001
From: Hugh Francis <hughfrancis89@gmail.com>
Date: Mon, 11 May 2026 20:39:42 -0400
Subject: [PATCH 36/79] lint: recursive STRUCT001 exemption + softer annotation
 category + /tmp report
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Three fixes in one commit, all surfaced from the user's reactor-webapp
session annotating the Logo Component Set:

1. STRUCT001 still fired on a frame containing light/dark sub-frames
   that themselves held vector paths. The previous fix exempted frames
   with direct shape-primitive children, but not the nested case.
   Replaced the predicate with isShapeOnlySubtree() — recurses through
   FRAME/GROUP/COMPONENT/INSTANCE containers and only exits at shape
   primitives. Mixed-content subtrees (text, instances of layout
   components, anything non-shape) still fire. Empty containers are NOT
   shape-only (they're placeholders, not shapes) — preserves the existing
   "single empty FRAME child" failure case.

2. Annotation category was "ADHD lint" (red). Renamed to plain "lint"
   and switched the color to "orange" — softer, friendlier, doesn't
   read as alarming on every layer it touches. The label-based category
   lookup means re-runs against an already-installed file create the
   new "lint" category alongside any stale "ADHD lint" category from
   earlier sessions; the designer can delete the old one manually.

3. /adhd:lint was writing adhd-lint-report.md to the repo root (with a
   gitignore noteasked to be removed). Moved the output to
   /tmp/adhd-lint/report.md — same place as the engine's stdout JSON.
   Repo root stays clean; nothing to ignore.

Tests cover the recursive exemption (nested shape-only OK; deep TEXT
leaf still flags) and the existing STRUCT001 baseline cases still hold.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 README.md                                     |  4 +-
 .../__tests__/structure-checker.test.js       | 48 +++++++++++++++++++
 .../adhd/lib/lint-engine/structure-checker.js | 40 ++++++++++++----
 plugins/adhd/skills/lint/SKILL.md             | 24 +++++-----
 plugins/adhd/skills/pull-component/SKILL.md   |  2 +-
 plugins/adhd/skills/push-component/SKILL.md   |  4 +-
 6 files changed, 95 insertions(+), 27 deletions(-)

diff --git a/README.md b/README.md
index c8134b8..cfab9fa 100644
--- a/README.md
+++ b/README.md
@@ -29,7 +29,7 @@ After install, seven slash commands are available:
 | Command | Args | Direction | What it does |
 |---|---|---|---|
 | `/adhd:config` | — | — | Interactive wizard that produces `adhd.config.ts`. Verifies the official Figma plugin is installed + authenticated before anything else. |
-| `/adhd:lint` | `[<figma-url>] [--annotate]` | read-only by default | Validates the Figma file (whole file or scoped) against the local design system + structure best-practices. With `--annotate`, also writes Figma annotations on each offending node in an "ADHD lint" category. |
+| `/adhd:lint` | `[<figma-url>] [--annotate]` | read-only by default | Validates the Figma file (whole file or scoped) against the local design system + structure best-practices. With `--annotate`, also writes Figma annotations on each offending node in a "lint" category. |
 | `/adhd:push-design-system` | — | code → Figma | Pushes globals.css variables + named styles into Figma directly via the remote MCP |
 | `/adhd:pull-design-system` | — | Figma → code | Pulls Figma variables + named styles into globals.css |
 | `/adhd:push-component` | `<path> [--max-variants <n>] [--annotate]` | code → Figma | Pushes a React component to Figma as a structured Component Set with variant properties + variable bindings, plus a preflight lint check. `--annotate` annotates preflight violations on Figma nodes. |
@@ -88,7 +88,7 @@ The scoped report covers the same rules (STRUCT001–010 + variable mismatches),
 
 ### Annotate violations in Figma (`--annotate`)
 
-By default `/adhd:lint` (and the preflight inside `/adhd:push-component` / `/adhd:pull-component`) is read-only — it writes a local markdown report and exits. Pass `--annotate` to also push each violation to Figma as a node-bound annotation in a dedicated **"ADHD lint"** category (red). Designers see them on the layers panel, and a re-run with `--annotate` cleans up stale ADHD-category annotations automatically (designer-authored annotations and other categories are never touched).
+By default `/adhd:lint` (and the preflight inside `/adhd:push-component` / `/adhd:pull-component`) is read-only — it echoes a markdown report to the terminal and exits. Pass `--annotate` to also push each violation to Figma as a node-bound annotation in a dedicated **"lint"** category (orange). Designers see them on the layers panel, and a re-run with `--annotate` cleans up stale "lint"-category annotations automatically (designer-authored annotations and other categories are never touched).
 
 ```
 /adhd:lint --annotate                                                            # whole file
diff --git a/plugins/adhd/lib/lint-engine/__tests__/structure-checker.test.js b/plugins/adhd/lib/lint-engine/__tests__/structure-checker.test.js
index 0733eaa..c928894 100644
--- a/plugins/adhd/lib/lint-engine/__tests__/structure-checker.test.js
+++ b/plugins/adhd/lib/lint-engine/__tests__/structure-checker.test.js
@@ -51,6 +51,54 @@ test('STRUCT001: does NOT flag a frame holding a single shape primitive (icon/lo
   }
 });
 
+test('STRUCT001: does NOT flag a frame whose subtree is shape-only through nested containers', () => {
+  // The user's real-world case: a Logo Component Set whose outer frame holds
+  // "light" and "dark" sub-frames, each containing only vector paths. The whole
+  // outer frame rasterizes to a single SVG — flexbox doesn't apply, even though
+  // the immediate children are FRAMEs (not shapes) themselves.
+  const node = makeFrame({
+    layoutMode: 'NONE',
+    children: [
+      {
+        id: '1:2', name: 'light', type: 'FRAME', layoutMode: 'NONE',
+        children: [
+          { id: '1:3', name: 'path-1', type: 'VECTOR' },
+          { id: '1:4', name: 'path-2', type: 'VECTOR' },
+        ],
+      },
+      {
+        id: '1:5', name: 'dark', type: 'COMPONENT', layoutMode: 'NONE',
+        children: [
+          { id: '1:6', name: 'path-1', type: 'VECTOR' },
+          { id: '1:7', name: 'mask', type: 'BOOLEAN_OPERATION' },
+        ],
+      },
+    ],
+  });
+  const violations = checkStructure(node, { fileKey: FIGMA_FILE_KEY, namingConvention: 'kebab-case' });
+  // STRUCT001 must not fire on the OUTER frame (it's a shape-only composition).
+  const outerStruct001 = violations.find(v => v.rule === 'STRUCT001' && v.nodeId === node.id);
+  assert.equal(outerStruct001, undefined, 'outer frame should be exempt — entire subtree is shape-only');
+});
+
+test('STRUCT001: still flags a deeply-nested frame if a leaf is non-shape (TEXT)', () => {
+  // One TEXT leaf anywhere in the subtree breaks the shape-only predicate.
+  const node = makeFrame({
+    layoutMode: 'NONE',
+    children: [
+      {
+        id: '1:2', name: 'badge', type: 'FRAME', layoutMode: 'NONE',
+        children: [
+          { id: '1:3', name: 'path', type: 'VECTOR' },
+          { id: '1:4', name: 'label', type: 'TEXT' },
+        ],
+      },
+    ],
+  });
+  const violations = checkStructure(node, { fileKey: FIGMA_FILE_KEY, namingConvention: 'kebab-case' });
+  assert.ok(violations.find(v => v.rule === 'STRUCT001'));
+});
+
 test('STRUCT001: does NOT flag a frame whose children are all shape primitives (multi-path SVG)', () => {
   // Real-world case: a Logo Component Set variant that's a composite of multiple
   // vector paths (e.g. a wordmark with separate paths per letter, or a mark with
diff --git a/plugins/adhd/lib/lint-engine/structure-checker.js b/plugins/adhd/lib/lint-engine/structure-checker.js
index 22080f7..3440acd 100644
--- a/plugins/adhd/lib/lint-engine/structure-checker.js
+++ b/plugins/adhd/lib/lint-engine/structure-checker.js
@@ -2,14 +2,33 @@
 
 const AUTO_NAME_RE = /^(Frame|Group|Rectangle|Ellipse|Vector|Line|Star|Polygon)\s+\d+$/;
 
-// Shape primitives that don't benefit from auto-layout. A frame whose
-// children are ALL of these types is exempt from STRUCT001 — the frame is
-// going to be rasterized to a single SVG (multi-path icons, logos,
-// illustrations, decorative shapes), so flexbox doesn't apply.
+// Shape primitives that don't benefit from auto-layout (the leaves of a
+// shape-only subtree).
 const SHAPE_PRIMITIVE_TYPES = new Set([
   'VECTOR', 'BOOLEAN_OPERATION', 'ELLIPSE', 'RECTANGLE', 'STAR', 'POLYGON', 'LINE',
 ]);
 
+// Container types that the shape-only check is willing to recurse into. A
+// frame containing nested frames/groups/components that themselves contain
+// only shape primitives is still going to rasterize to a single SVG, so
+// flexbox doesn't apply to the outer container either. Mixed content (text,
+// other layouts) anywhere in the subtree breaks the exemption.
+const SHAPE_SUBTREE_CONTAINER_TYPES = new Set([
+  'FRAME', 'GROUP', 'COMPONENT', 'INSTANCE',
+]);
+
+// True iff `node` is a shape primitive OR a container with at least one
+// child whose entire subtree is shape-only. Empty containers DON'T count —
+// an empty FRAME is a placeholder, not a shape; the outer frame still needs
+// auto-layout to handle it. Anything else (TEXT, COMPONENT_SET as a child,
+// etc.) breaks the predicate.
+function isShapeOnlySubtree(node) {
+  if (SHAPE_PRIMITIVE_TYPES.has(node.type)) return true;
+  if (!SHAPE_SUBTREE_CONTAINER_TYPES.has(node.type)) return false;
+  if (!Array.isArray(node.children) || node.children.length === 0) return false;
+  return node.children.every(isShapeOnlySubtree);
+}
+
 // Paints are "visible" by default; only treat as hidden when explicitly false.
 function isVisiblePaint(p) {
   return p && p.visible !== false;
@@ -42,15 +61,16 @@ function visit(node, ctx, parentPath, parent) {
   };
 
   // STRUCT001: auto-layout required.
-  // Exempt: a frame whose children are ALL shape primitives. Covers the icon /
-  // logo / illustration case — single Vector, multi-path Vector compositions,
-  // boolean operations, decorative rectangles, etc. These rasterize to a single
-  // SVG; flexbox doesn't apply. Mixed-content frames (text + shape, frame +
-  // shape, etc.) still fire — those want auto-layout for padding and alignment.
+  // Exempt: a frame whose entire subtree is shape-only. Covers icon / logo /
+  // illustration cases including nested compositions — a frame containing
+  // "light" and "dark" sub-frames, each holding only vector paths, still
+  // rasterizes to one SVG and doesn't want flexbox at the outer level.
+  // Mixed-content subtrees (text, instances of layout components, anything
+  // that isn't a shape or shape-only container) still fire.
   if ((node.type === 'FRAME' || node.type === 'COMPONENT' || node.type === 'INSTANCE') &&
       Array.isArray(node.children) && node.children.length > 0 &&
       node.layoutMode === 'NONE') {
-    const allShapes = node.children.every(c => SHAPE_PRIMITIVE_TYPES.has(c.type));
+    const allShapes = node.children.every(isShapeOnlySubtree);
     if (!allShapes) {
       push('STRUCT001', 'error', 'Frame has children but auto-layout is not enabled.');
     }
diff --git a/plugins/adhd/skills/lint/SKILL.md b/plugins/adhd/skills/lint/SKILL.md
index d8961e5..4276a2e 100644
--- a/plugins/adhd/skills/lint/SKILL.md
+++ b/plugins/adhd/skills/lint/SKILL.md
@@ -1,5 +1,5 @@
 ---
-description: "Validate Figma frames/components/pages or the entire file against the local Tailwind design system + frame-structure best practices. Reads adhd.config.ts at the repo root. Read-only by default; with --annotate, also writes Figma annotations on each offending node in an 'ADHD lint' category. Optional argument: a Figma URL with node-id (scoped lint). With no argument, lints the whole file."
+description: "Validate Figma frames/components/pages or the entire file against the local Tailwind design system + frame-structure best practices. Reads adhd.config.ts at the repo root. Read-only by default; with --annotate, also writes Figma annotations on each offending node in a 'lint' category. Optional argument: a Figma URL with node-id (scoped lint). With no argument, lints the whole file."
 disable-model-invocation: true
 argument-hint: "[<figma-url-with-node-id>] [--annotate]"
 allowed-tools: Read Write Bash AskUserQuestion mcp__plugin_figma_figma__use_figma
@@ -12,7 +12,7 @@ Validate that a Figma file (or a single frame/component/page) is ready for code
 - **Variable issues** — Figma variables used by the lint target that are missing locally or have conflicting values.
 - **Structure issues** — STRUCT001–STRUCT010 best-practice violations (auto-layout, naming, variant properties, etc.).
 
-Output: a markdown report saved to `adhd-lint-report.md` (gitignored), plus a terminal echo. The report is paste-ready for sharing with designers via Figma comments, Slack, or GitHub issues.
+Output: a markdown report saved to `/tmp/adhd-lint/report.md`, plus a terminal echo. The report is paste-ready for sharing with designers via Figma comments, Slack, or GitHub issues.
 
 **Authoritative spec:** `docs/superpowers/specs/2026-05-10-adhd-lint-and-sync-design.md`
 
@@ -75,7 +75,7 @@ node plugins/adhd/lib/lint-engine/cli.js \
   --config adhd.config.ts \
   --target "<target-label>" \
   --target-url "<target-url>" \
-  --output adhd-lint-report.md \
+  --output /tmp/adhd-lint/report.md \
   > /tmp/adhd-lint/stdout.json
 ```
 
@@ -85,7 +85,7 @@ Globals path resolution: if `adhd.config.ts` has `cssEntry`, use it. Otherwise a
 
 ## Phase 5: Present results
 
-Read `adhd-lint-report.md` with the `Read` tool and echo it to the user verbatim. Then summarize:
+Read `/tmp/adhd-lint/report.md` with the `Read` tool and echo it to the user verbatim. Then summarize:
 
 - **Whole-file mode:**
   - Exit 0 with zero violations: "✓ No issues found across all <N> top-level nodes on <P> pages."
@@ -96,11 +96,11 @@ Read `adhd-lint-report.md` with the `Read` tool and echo it to the user verbatim
   - Exit 0 with warnings only: "⚠ <W> warnings (see report). Frame is ready for code translation."
   - Exit 1: "✗ <E> errors, <W> warnings. Frame has issues that should be resolved before code translation."
 
-Mention the report file path: "Full report: `adhd-lint-report.md` (paste-ready for Figma comments / Slack)."
+Mention the report file path: "Full report: `/tmp/adhd-lint/report.md` (paste-ready for Figma comments / Slack)."
 
 ## Phase 6: Optional — annotate offending nodes in Figma (`--annotate`)
 
-If the user passed `--annotate` (the only flag this skill accepts), push each violation to Figma as an annotation on its `nodeId`. ADHD owns a dedicated annotation category named **"ADHD lint"** (red); designer-authored annotations and any other categories are left untouched.
+If the user passed `--annotate` (the only flag this skill accepts), push each violation to Figma as an annotation on its `nodeId`. ADHD owns a dedicated annotation category named **"lint"** (orange); designer-authored annotations and any other categories are left untouched.
 
 If `--annotate` was NOT passed, skip this phase.
 
@@ -124,10 +124,10 @@ Pass the violations array to `mcp__plugin_figma_figma__use_figma` with `skillNam
 
 ```js
 const VIOLATIONS = /* substituted: contents of /tmp/adhd-lint/violations.json */;
-const CATEGORY_LABEL = "ADHD lint";
-const CATEGORY_COLOR = "red";
+const CATEGORY_LABEL = "lint";
+const CATEGORY_COLOR = "orange";
 
-// 1) Ensure the ADHD lint category exists (idempotent across runs).
+// 1) Ensure the lint category exists (idempotent across runs).
 const cats = await figma.annotations.getAnnotationCategoriesAsync();
 let cat = cats.find(c => c.label === CATEGORY_LABEL);
 if (!cat) {
@@ -180,7 +180,7 @@ return { categoryId: cat.id, categoryLabel: cat.label, updated, cleared, totalVi
 After the script returns, print one line:
 
 ```
-✓ Annotated <updated> Figma node(s) in the "ADHD lint" category. Cleared <cleared> stale annotation(s).
+✓ Annotated <updated> Figma node(s) in the "lint" category. Cleared <cleared> stale annotation(s).
 ```
 
 If `updated === 0 && cleared === 0`, print:
@@ -191,7 +191,7 @@ No node-bound violations to annotate (whole-file violations like pageGrouping ar
 
 ### Why a dedicated category
 
-The "ADHD lint" category gives designers a one-click filter in Figma's annotations panel and lets us cleanly own/replace our own annotations without touching designer-authored ones. The category persists in the file — even after the user uninstalls ADHD, the annotations remain as plain Figma annotations the designer can edit or delete.
+The "lint" category gives designers a one-click filter in Figma's annotations panel and lets us cleanly own/replace our own annotations without touching designer-authored ones. The category persists in the file — even after the user uninstalls ADHD, the annotations remain as plain Figma annotations the designer can edit or delete.
 
 ## Phase 7: Offer to annotate when `--annotate` wasn't passed
 
@@ -200,7 +200,7 @@ If `--annotate` was passed, this phase is a no-op (Phase 6 already ran).
 If `--annotate` was NOT passed AND the lint produced at least one violation with a `nodeId` (count it from `/tmp/adhd-lint/stdout.json` using the same `node -e` snippet as Phase 6 — count of items in the distilled violations array), use `AskUserQuestion`:
 
 ```
-Question: "Push these <N> violation(s) to Figma as annotations? They'll appear on the offending nodes in an 'ADHD lint' category that designers can filter on."
+Question: "Push these <N> violation(s) to Figma as annotations? They'll appear on the offending nodes in a 'lint' category that designers can filter on."
 Header: "Annotate?"
 Options:
   - "Yes, annotate them in Figma"
diff --git a/plugins/adhd/skills/pull-component/SKILL.md b/plugins/adhd/skills/pull-component/SKILL.md
index 1524809..af75178 100644
--- a/plugins/adhd/skills/pull-component/SKILL.md
+++ b/plugins/adhd/skills/pull-component/SKILL.md
@@ -103,7 +103,7 @@ Two paths, both producing the same `use_figma` annotation work described in `/ad
 **Path B — `--annotate` was NOT passed, AND there are variable-binding errors (STRUCT003/004/005) that will block the pull.** Use `AskUserQuestion` to offer it retroactively:
 
 ```
-Question: "Push these <N> preflight violation(s) to Figma as annotations before aborting? Designers can see them in the 'ADHD lint' category to fix in-context."
+Question: "Push these <N> preflight violation(s) to Figma as annotations before aborting? Designers can see them in the 'lint' category to fix in-context."
 Header: "Annotate?"
 Options:
   - "Yes, annotate them in Figma"
diff --git a/plugins/adhd/skills/push-component/SKILL.md b/plugins/adhd/skills/push-component/SKILL.md
index da8ac49..2dedade 100644
--- a/plugins/adhd/skills/push-component/SKILL.md
+++ b/plugins/adhd/skills/push-component/SKILL.md
@@ -187,13 +187,13 @@ Two paths into this phase, both producing the same `use_figma` annotation work d
 **Path A — `--annotate` was passed.** Run the annotation script unconditionally. After it returns, print:
 
 ```
-✓ Annotated <updated> Figma node(s) in the "ADHD lint" category. Cleared <cleared> stale annotation(s).
+✓ Annotated <updated> Figma node(s) in the "lint" category. Cleared <cleared> stale annotation(s).
 ```
 
 **Path B — `--annotate` was NOT passed, AND preflight produced node-bound errors that will abort the push.** Use `AskUserQuestion` to offer it retroactively:
 
 ```
-Question: "Push these <N> preflight violation(s) to Figma as annotations before aborting? Designers can see them in the 'ADHD lint' category to fix in-context."
+Question: "Push these <N> preflight violation(s) to Figma as annotations before aborting? Designers can see them in the 'lint' category to fix in-context."
 Header: "Annotate?"
 Options:
   - "Yes, annotate them in Figma"

From e86214bee1b999a1a5a216fde3a0b2ab69ab4eae Mon Sep 17 00:00:00 2001
From: Hugh Francis <hughfrancis89@gmail.com>
Date: Mon, 11 May 2026 21:14:57 -0400
Subject: [PATCH 37/79] sync-docs: eliminate explicit \`any\` from generated
 files
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

User's consumer build failed with 5 @typescript-eslint/no-explicit-any
errors on the generated docs files. Replaced every \`any\` with a precise
type:

- React.ComponentType<any> → React.ComponentType<Record<string, unknown>>
  (4 sites in componentMap.tsx — return type of resolveComponent, the
  ComponentEntry interface, and the two cast sites inside resolveComponent
  where we know `mod.default` / a named export is a function. The cast is
  safe because `mod[k]` starts as `unknown`, and React's typing accepts
  Record<string, unknown> as a prop signature for the loose-bridge case
  the docs route fundamentally is.)

- Record<string, any> → Record<string, PropValue> for the `current` map
  in the component page (PropValue = string | boolean | number — the
  three shapes we actually set from searchParams).

One narrowing cast added at the union-PropToggle render site: \`current[name]\`
is typed PropValue but the union branch only ever stores strings (validated
against def.values at load time). Explicit \`as string | undefined\` here
keeps the spread type-correct without needing \`any\`.

Strict tsc on the generated output: clean. The user's build should now
pass with no-explicit-any enabled.

Added a regression-guard test in templates.test.js that fails if any
template re-introduces \`any\` — \\bany\\b word-boundary so legitimate
identifiers like "Company" aren't false-positives.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 .../lib/sync-docs/__tests__/templates.test.js | 12 +++++++++++
 plugins/adhd/lib/sync-docs/templates.js       | 20 ++++++++++++-------
 2 files changed, 25 insertions(+), 7 deletions(-)

diff --git a/plugins/adhd/lib/sync-docs/__tests__/templates.test.js b/plugins/adhd/lib/sync-docs/__tests__/templates.test.js
index f0aef54..3192e9a 100644
--- a/plugins/adhd/lib/sync-docs/__tests__/templates.test.js
+++ b/plugins/adhd/lib/sync-docs/__tests__/templates.test.js
@@ -120,6 +120,18 @@ test('COMPONENT_MAP_TSX resolves a renderable function via default-then-named fa
   assert.match(COMPONENT_MAP_TSX, /mod\.default/);
 });
 
+test('no template contains an explicit `any` type — consumer builds with no-explicit-any pass', () => {
+  // Generated docs files are read by the consumer's TypeScript compiler.
+  // If their ESLint config enables @typescript-eslint/no-explicit-any (the
+  // typical strict setup), even one `any` in our templates breaks their build.
+  // The templates use Record<string, unknown> + targeted casts instead.
+  for (const [name, content] of Object.entries({ LAYOUT_TSX, INDEX_PAGE_TSX, TOKENS_PAGE_TSX, COMPONENT_PAGE_TSX, COMPONENT_MAP_TSX })) {
+    // Word-boundary check: catches `: any`, `as any`, `Foo<any>`, etc. but not
+    // identifiers that happen to contain "any" (e.g. "Company", "many").
+    assert.doesNotMatch(content, /\bany\b/, `${name} contains an explicit \`any\` — consumers with no-explicit-any will fail to build`);
+  }
+});
+
 test('none of the templates contain "ADHD" outside the marker', () => {
   // Two filename-style exceptions are allowed:
   //   1. `adhd.config.ts` — the consumer's own config artifact.
diff --git a/plugins/adhd/lib/sync-docs/templates.js b/plugins/adhd/lib/sync-docs/templates.js
index b94ece7..aa6f0e2 100644
--- a/plugins/adhd/lib/sync-docs/templates.js
+++ b/plugins/adhd/lib/sync-docs/templates.js
@@ -131,7 +131,7 @@ export type PropSchema = {
 export type ComponentEntry = {
   slug: string;
   rawPath: string;
-  Component: React.ComponentType<any> | null;
+  Component: React.ComponentType<Record<string, unknown>> | null;
   props: Record<string, PropSchema>;
 };
 
@@ -145,10 +145,10 @@ type RawEntry = {
 // Resolve the renderable function: prefer the default export, then the
 // first exported function. Keeps user components working without forcing
 // a particular export style.
-function resolveComponent(mod: Record<string, unknown>): React.ComponentType<any> | null {
-  if (typeof mod.default === "function") return mod.default as React.ComponentType<any>;
+function resolveComponent(mod: Record<string, unknown>): React.ComponentType<Record<string, unknown>> | null {
+  if (typeof mod.default === "function") return mod.default as React.ComponentType<Record<string, unknown>>;
   for (const v of Object.values(mod)) {
-    if (typeof v === "function") return v as React.ComponentType<any>;
+    if (typeof v === "function") return v as React.ComponentType<Record<string, unknown>>;
   }
   return null;
 }
@@ -556,8 +556,11 @@ export default function ComponentPage() {
 
   const { rawPath, Component, props } = entry;
 
-  // Resolve current prop values from the URL.
-  const current: Record<string, any> = {};
+  // Resolve current prop values from the URL. Values are constrained to the
+  // three shapes the page knows how to source — string (for union + string
+  // schemas), boolean, and number. Anything else is omitted.
+  type PropValue = string | boolean | number;
+  const current: Record<string, PropValue> = {};
   for (const [name, def] of Object.entries(props) as Array<[string, PropSchema]>) {
     const v = sp.get(name);
     if (v == null) continue;
@@ -586,7 +589,10 @@ export default function ComponentPage() {
           <div className="flex flex-col gap-2">
             {Object.entries(props).map(([name, def]) => {
               if (def.type === "union" && def.values) {
-                return <PropToggle key={name} name={name} kind="union" values={def.values} value={current[name] ?? def.values[0]} />;
+                // For unions, current[name] is always a string (validated at
+                // load time against def.values). The cast narrows from PropValue.
+                const v = (current[name] as string | undefined) ?? def.values[0];
+                return <PropToggle key={name} name={name} kind="union" values={def.values} value={v} />;
               }
               if (def.type === "boolean") {
                 return <PropToggle key={name} name={name} kind="boolean" value={String(current[name] ?? false)} />;

From 5e9819abaec12b7f4ff7b43810f78770a2f74f6f Mon Sep 17 00:00:00 2001
From: Hugh Francis <hughfrancis89@gmail.com>
Date: Mon, 11 May 2026 21:46:09 -0400
Subject: [PATCH 38/79] lint STRUCT003: surface raw hex, honor paint styles,
 catch mixed-paint silent misses
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Three fixes triggered by a user report that lint missed a #FFFFFF fill
on a layer inside a Logo Component Set. Investigation showed two real
gaps in the rule plus one diagnostic improvement that would have made
the issue easier to spot even when the rule did fire.

1) Surface the raw hex value in the message. Previous copy was generic
   ("Fill is a raw color; use a color variable.") so when many
   violations fired across one frame the specific offending color was
   hard to track down. New copy: "Fill is a raw color (#FFFFFF); bind
   it to a color variable or apply a paint style."

2) Honor `fillStyleId` / `strokeStyleId` (Figma's legacy paint-style
   bindings, distinct from variable bindings). Paint styles ARE valid
   design-system tokens — they pre-date variables but the design-system
   system itself still consumes them. The rule used to fire false
   positives on style-bound layers because the serializer didn't even
   capture the style id. Now: serializer captures both id fields, and
   the rule skips the raw-color check when a non-empty, non-mixed id is
   present.

3) Recognize the new `"__MIXED__"` sentinel and fire STRUCT003 on it.
   Figma returns `figma.mixed` (a Symbol) for `node.fills` on TEXT with
   per-character coloring, and JSON.stringify drops Symbols. The
   serializer used to assign the raw value, the Symbol disappeared
   silently during JSON serialization, and the rule had nothing to
   check. Result: a multi-color TEXT with a raw white range never
   surfaced as a violation. The user's exact scenario.

   The serializer spec now coerces every potentially-mixed field
   (`fills`, `strokes`, `fillStyleId`, `strokeStyleId`) to the string
   "__MIXED__" before JSON.stringify. The rule recognizes the sentinel,
   reports a mixed-paint variant of STRUCT003, and — when the style id
   is mixed but the fills are present — falls through to the per-paint
   check so unbound ranges still get caught.

Tests cover all three: hex in message, paint-style binding skip, mixed
sentinel firing, and mixed-style-id falling through to fills.

SKILL.md updated with `fillStyleId` / `strokeStyleId` capture
instructions and a detailed `figma.mixed` handling note so future
serializer regenerations don't silently regress.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 .../__tests__/structure-checker.test.js       | 46 ++++++++++-
 .../adhd/lib/lint-engine/structure-checker.js | 78 ++++++++++++++-----
 plugins/adhd/skills/lint/SKILL.md             |  3 +
 3 files changed, 107 insertions(+), 20 deletions(-)

diff --git a/plugins/adhd/lib/lint-engine/__tests__/structure-checker.test.js b/plugins/adhd/lib/lint-engine/__tests__/structure-checker.test.js
index c928894..e3c3495 100644
--- a/plugins/adhd/lib/lint-engine/__tests__/structure-checker.test.js
+++ b/plugins/adhd/lib/lint-engine/__tests__/structure-checker.test.js
@@ -149,9 +149,51 @@ test('STRUCT001: still flags a frame with mixed shapes + non-shape children (nee
   assert.ok(violations.find(v => v.rule === 'STRUCT001'));
 });
 
-test('STRUCT003: flags a fill with raw hex (no boundVariables)', () => {
+test('STRUCT003: flags a fill with raw hex (no boundVariables) and names the color', () => {
+  // The user's case: a layer with #FFFFFF in the Figma fills panel, no variable
+  // bound. The previous generic copy ("Fill is a raw color") was easy to skim
+  // past when many violations fired at once; now the message includes the hex.
   const node = makeFrame({
-    fills: [{ type: 'SOLID', color: { r: 0.37, g: 0.23, b: 0.93 } }],
+    fills: [{ type: 'SOLID', color: { r: 1, g: 1, b: 1 } }],
+  });
+  const violations = checkStructure(node, { fileKey: FIGMA_FILE_KEY, namingConvention: 'kebab-case' });
+  const v = violations.find(x => x.rule === 'STRUCT003');
+  assert.ok(v);
+  assert.match(v.message, /#FFFFFF/);
+  assert.match(v.message, /bind it to a color variable or apply a paint style/);
+});
+
+test('STRUCT003: does NOT fire on a layer bound to a paint style (legacy design-token mechanism)', () => {
+  // Paint styles pre-date variables but are still valid design tokens. A layer
+  // with a non-empty fillStyleId is bound — STRUCT003 shouldn't ask the
+  // designer to migrate to a variable just for the lint to pass.
+  const node = makeFrame({
+    fillStyleId: 'S:abc123,1:0',
+    fills: [{ type: 'SOLID', color: { r: 1, g: 1, b: 1 } }],
+  });
+  const violations = checkStructure(node, { fileKey: FIGMA_FILE_KEY, namingConvention: 'kebab-case' });
+  assert.equal(violations.filter(v => v.rule === 'STRUCT003').length, 0);
+});
+
+test('STRUCT003: flags __MIXED__ fills (per-range mixed paints — could hide raw values)', () => {
+  // Figma returns `figma.mixed` for `node.fills` on TEXT with multiple paint
+  // segments. The serializer coerces that Symbol to "__MIXED__" so it survives
+  // JSON.stringify (Symbols don't). Without this rule firing, the violation
+  // would silently disappear from the report — which is exactly what the user
+  // hit on their Logo Component Set.
+  const node = makeFrame({ fills: '__MIXED__' });
+  const violations = checkStructure(node, { fileKey: FIGMA_FILE_KEY, namingConvention: 'kebab-case' });
+  const v = violations.find(x => x.rule === 'STRUCT003');
+  assert.ok(v);
+  assert.match(v.message, /mixed across ranges/);
+});
+
+test('STRUCT003: a MIXED fillStyleId still falls through to the fills check', () => {
+  // Some ranges styled, others not. We can't trust the style binding covers
+  // every range, so the fills check still runs and catches any raw paint.
+  const node = makeFrame({
+    fillStyleId: '__MIXED__',
+    fills: [{ type: 'SOLID', color: { r: 1, g: 0, b: 0 } }],
   });
   const violations = checkStructure(node, { fileKey: FIGMA_FILE_KEY, namingConvention: 'kebab-case' });
   assert.ok(violations.find(v => v.rule === 'STRUCT003'));
diff --git a/plugins/adhd/lib/lint-engine/structure-checker.js b/plugins/adhd/lib/lint-engine/structure-checker.js
index 3440acd..002d1e8 100644
--- a/plugins/adhd/lib/lint-engine/structure-checker.js
+++ b/plugins/adhd/lib/lint-engine/structure-checker.js
@@ -34,6 +34,35 @@ function isVisiblePaint(p) {
   return p && p.visible !== false;
 }
 
+// Convert a Figma SOLID paint's normalized color (r/g/b each in 0..1) to
+// a #RRGGBB hex literal — used in diagnostic messages so the designer
+// knows exactly which color is raw, not just "some fill somewhere."
+function paintToHex(paint) {
+  if (!paint || !paint.color) return '?';
+  const to255 = (c) => Math.round(Math.max(0, Math.min(1, c)) * 255);
+  const hex = [paint.color.r, paint.color.g, paint.color.b]
+    .map(to255)
+    .map(n => n.toString(16).padStart(2, '0'))
+    .join('');
+  return '#' + hex.toUpperCase();
+}
+
+// Sentinel the serializer uses for fields where Figma returned `figma.mixed`.
+// JSON.stringify drops Symbols silently, so the serializer coerces them to
+// this marker string before assignment — otherwise per-range mixed paints
+// would disappear from the lint surface entirely.
+const MIXED = '__MIXED__';
+
+// True if the node is FULLY bound to a paint STYLE (Figma's legacy design-
+// token mechanism, distinct from variable bindings). Paint styles are valid
+// design tokens, so STRUCT003 shouldn't fire on style-bound layers. A MIXED
+// style id means SOME ranges are styled and some aren't — fall through to
+// the fills check so unbound ranges get caught.
+function hasPaintStyleBinding(node, kind) {
+  const id = node[kind];
+  return typeof id === 'string' && id.length > 0 && id !== MIXED;
+}
+
 function deepLink(fileKey, nodeId) {
   return 'https://figma.com/design/' + fileKey + '?node-id=' + nodeId.replace(':', '-');
 }
@@ -90,27 +119,40 @@ function visit(node, ctx, parentPath, parent) {
     }
   }
 
-  // STRUCT003: visible solid colors use variables. Paints with `visible: false`
-  // don't render and are excluded — Figma keeps invisible paint entries on a node
-  // when the user has hidden them in the UI; enforcing variable bindings on
-  // unseen paints is busywork. COMPONENT_SET wrappers are also skipped — they're
-  // organizational scaffolding that doesn't render in instances. Figma's editor
-  // chrome (the dashed-purple Component Set outline at #9747FF) shows up in the
-  // wrapper's `strokes` array as a real SOLID entry; firing STRUCT003 on it would
-  // ask the designer to bind a color they never added.
-  if (node.type !== 'COMPONENT_SET' && Array.isArray(node.fills)) {
-    for (const fill of node.fills) {
-      if (fill.type === 'SOLID' && isVisiblePaint(fill) && !fill.boundVariables?.color) {
-        push('STRUCT003', 'error', 'Fill is a raw color; use a color variable.');
-        break;
+  // STRUCT003: visible solid colors use variables OR paint styles. Paints with
+  // `visible: false` don't render and are excluded. COMPONENT_SET wrappers are
+  // also skipped — they're organizational scaffolding and Figma's editor chrome
+  // (the dashed-purple outline at #9747FF) lives in the wrapper's `strokes`.
+  // Layers bound to a paint STYLE (legacy mechanism — `fillStyleId` /
+  // `strokeStyleId`) are valid design tokens too; we don't ask the designer to
+  // migrate them.
+  if (node.type !== 'COMPONENT_SET' && !hasPaintStyleBinding(node, 'fillStyleId')) {
+    if (node.fills === MIXED) {
+      // Multi-range mixed paints — fall through from the serializer's sentinel.
+      // Often a TEXT layer with per-character coloring; could be hiding raw values.
+      push('STRUCT003', 'error',
+        'Fills are mixed across ranges — bind each range to a color variable, or apply a paint style to the layer.');
+    } else if (Array.isArray(node.fills)) {
+      for (const fill of node.fills) {
+        if (fill.type === 'SOLID' && isVisiblePaint(fill) && !fill.boundVariables?.color) {
+          push('STRUCT003', 'error',
+            `Fill is a raw color (${paintToHex(fill)}); bind it to a color variable or apply a paint style.`);
+          break;
+        }
       }
     }
   }
-  if (node.type !== 'COMPONENT_SET' && Array.isArray(node.strokes)) {
-    for (const stroke of node.strokes) {
-      if (stroke.type === 'SOLID' && isVisiblePaint(stroke) && !stroke.boundVariables?.color) {
-        push('STRUCT003', 'error', 'Stroke is a raw color; use a color variable.');
-        break;
+  if (node.type !== 'COMPONENT_SET' && !hasPaintStyleBinding(node, 'strokeStyleId')) {
+    if (node.strokes === MIXED) {
+      push('STRUCT003', 'error',
+        'Strokes are mixed across ranges — bind each range to a color variable, or apply a paint style to the layer.');
+    } else if (Array.isArray(node.strokes)) {
+      for (const stroke of node.strokes) {
+        if (stroke.type === 'SOLID' && isVisiblePaint(stroke) && !stroke.boundVariables?.color) {
+          push('STRUCT003', 'error',
+            `Stroke is a raw color (${paintToHex(stroke)}); bind it to a color variable or apply a paint style.`);
+          break;
+        }
       }
     }
   }
diff --git a/plugins/adhd/skills/lint/SKILL.md b/plugins/adhd/skills/lint/SKILL.md
index 4276a2e..926f6e8 100644
--- a/plugins/adhd/skills/lint/SKILL.md
+++ b/plugins/adhd/skills/lint/SKILL.md
@@ -41,12 +41,15 @@ Construct a JS string for `mcp__plugin_figma_figma__use_figma` that:
    - `id`, `name`, `type`
    - `layoutMode`, `paddingTop`, `paddingRight`, `paddingBottom`, `paddingLeft`, `itemSpacing`, `cornerRadius`, `topLeftRadius`, `topRightRadius`, `bottomLeftRadius`, `bottomRightRadius`
    - `fills`, `strokes`, `effects`, `boundVariables`
+   - `fillStyleId`, `strokeStyleId` — paint-style bindings (Figma's legacy design-token mechanism, distinct from variable bindings). The lint engine uses these to recognize style-bound layers and skip the raw-color rule on them.
    - `componentPropertyDefinitions` — **only** when `n.type === 'COMPONENT_SET' || (n.type === 'COMPONENT' && n.parent?.type !== 'COMPONENT_SET')`. Accessing it on a variant COMPONENT (a child of a COMPONENT_SET) throws.
    - `variantProperties` — only on COMPONENT children of a COMPONENT_SET.
    - `textStyleId`, `effectStyleId`
    - For TEXT: `characters`, `fontSize`, `fontName`
    - For FRAME: `wasInstance`
    - `children` — recursively `serializeNode`-mapped.
+
+   **`figma.mixed` handling.** Several fields return the `figma.mixed` Symbol when a node has per-range variation (most commonly `node.fills` on TEXT with multiple colored spans, `node.fontSize` on multi-size text, `node.fillStyleId` / `node.strokeStyleId` when only some ranges have a style applied). `JSON.stringify` drops Symbols silently — which means a multi-color TEXT layer with raw whites would have its `fills` quietly disappear from the serialized output, and STRUCT003 would never fire on it. Before assigning each potentially-mixed field, coerce: `value === figma.mixed ? "__MIXED__" : value`. The lint engine recognizes the `"__MIXED__"` sentinel and reports it as a STRUCT003 violation with a "mixed paints — bind each range to a variable, or apply a paint style" message, so the violation surfaces instead of disappearing.
 2. Branches on a `nodeId` parameter (passed via the `inputs` object on `use_figma`):
    - **Whole-file** (no `nodeId`): walk `figma.root.children` (pages); for each page, find children whose type is `COMPONENT_SET`, or `COMPONENT` (top-level only — i.e. parent is the page, not nested), or `FRAME` (top-level). Serialize each. Return `{ mode: 'whole-file', pages: [{ id, name, nodes: [...serialized...] }, ...] }`.
    - **Scoped** (`nodeId` provided): `await figma.getNodeByIdAsync(nodeId)`; if missing, return `{ error: 'Node not found' }`; otherwise `serializeNode(node)` and return it directly (no `mode` field).

From aa4cf1f1c1129e20c3b1842d6c83353c0224e4d9 Mon Sep 17 00:00:00 2001
From: Hugh Francis <hughfrancis89@gmail.com>
Date: Mon, 11 May 2026 21:55:45 -0400
Subject: [PATCH 39/79] sync-docs: trace globals.css for serverless tokens-page
 deploys
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

User report: tokens page shows colors locally but not on Vercel preview.
Other Claude session correctly diagnosed: the tokens page reads
globals.css via runtime fs.readFile, but Vercel's serverless runtime
doesn't include CSS source files in the function bundle by default —
so fs.readFile throws ENOENT, readCss swallows it as null,
parseTokens(null) returns empty arrays, and every domain falls through
to its empty state. Same root cause for any non-dev render mode.

Fix is to add Next.js's outputFileTracingIncludes config so the CSS
source ships alongside the tokens function. patchNextConfig now emits
up to two blocks based on renderMode:

  dev-only       → pageExtensions ONLY (page runs locally via next dev,
                   project root is cwd, tracing irrelevant)
  vercel-preview → pageExtensions + tracing
  everywhere     → tracing ONLY (no extension gate, but page still
                   serves from a serverless function in prod)

The tracing block keys on the consumer's actual routeUrl (e.g.
/-docs/tokens/[domain] vs /design-system/tokens/[domain]) and points at
their configured cssEntry — both threaded through the CLI now via
--route-url (already accepted) and the new --css-entry flag.

isPatched widened to recognize either sentinel ('design-system.tsx' OR
the tracing comment), so re-runs in any mode are a no-op once patched.
Switching modes still requires manually removing the patch.

Tests cover all three modes' emitted blocks, the routeUrl substitution,
idempotency on tracing-only patches, and the absence of tracing in
dev-only mode.

To pick this up: pull the branch, /reload-plugins, manually remove the
existing patch comment from next.config.ts, re-run /adhd:sync-docs and
choose the same render mode. The patcher will re-emit with the tracing
block included. Next Vercel deploy ships globals.css with the function.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 .../__tests__/next-config-patcher.test.js     | 64 ++++++++++++++
 plugins/adhd/lib/sync-docs/cli.js             |  8 +-
 .../adhd/lib/sync-docs/next-config-patcher.js | 83 +++++++++++++------
 plugins/adhd/skills/sync-docs/SKILL.md        | 29 +++++--
 4 files changed, 148 insertions(+), 36 deletions(-)

diff --git a/plugins/adhd/lib/sync-docs/__tests__/next-config-patcher.test.js b/plugins/adhd/lib/sync-docs/__tests__/next-config-patcher.test.js
index ff23891..cc23306 100644
--- a/plugins/adhd/lib/sync-docs/__tests__/next-config-patcher.test.js
+++ b/plugins/adhd/lib/sync-docs/__tests__/next-config-patcher.test.js
@@ -104,3 +104,67 @@ test('patchNextConfig throws on an unknown renderMode', () => {
     /Unknown renderMode: preview/,
   );
 });
+
+test('vercel-preview mode also emits outputFileTracingIncludes when routeUrl + cssEntry are passed', () => {
+  // Without tracing, Vercel/serverless deploys don't bundle globals.css with
+  // the tokens function, fs.readFile throws ENOENT, and the page shows empty
+  // states for every token domain. This was the user's reported bug.
+  const out = patchNextConfig(TS_MINIMAL, {
+    renderMode: 'vercel-preview',
+    routeUrl: '/-docs',
+    cssEntry: 'app/globals.css',
+  });
+  assert.match(out, /pageExtensions:/);
+  assert.match(out, /outputFileTracingIncludes:/);
+  assert.match(out, /"\/-docs\/tokens\/\[domain\]":\s*\["\.\/app\/globals\.css"\]/);
+});
+
+test('everywhere mode emits ONLY outputFileTracingIncludes (no pageExtensions gate)', () => {
+  // "everywhere" ships files as plain .tsx with no extension gate, but the
+  // tokens page still runs on the serverless function in prod — it still
+  // needs the CSS source traced.
+  const out = patchNextConfig(TS_MINIMAL, {
+    renderMode: 'everywhere',
+    routeUrl: '/-docs',
+    cssEntry: 'src/app/globals.css',
+  });
+  assert.match(out, /outputFileTracingIncludes:/);
+  assert.match(out, /"\/-docs\/tokens\/\[domain\]":\s*\["\.\/src\/app\/globals\.css"\]/);
+  // No pageExtensions block in this mode.
+  assert.doesNotMatch(out, /pageExtensions:/);
+});
+
+test('dev-only mode does NOT emit tracing (page runs locally; no serverless bundle to trace)', () => {
+  const out = patchNextConfig(TS_MINIMAL, {
+    renderMode: 'dev-only',
+    routeUrl: '/-docs',
+    cssEntry: 'app/globals.css',
+  });
+  assert.match(out, /pageExtensions:/);
+  assert.doesNotMatch(out, /outputFileTracingIncludes:/);
+});
+
+test('isPatched recognizes a tracing-only "everywhere" patch as already-patched', () => {
+  const out = patchNextConfig(TS_MINIMAL, {
+    renderMode: 'everywhere',
+    routeUrl: '/-docs',
+    cssEntry: 'app/globals.css',
+  });
+  assert.equal(isPatched(out), true);
+  // Re-running on the patched output is a no-op.
+  assert.equal(
+    patchNextConfig(out, { renderMode: 'everywhere', routeUrl: '/-docs', cssEntry: 'app/globals.css' }),
+    out,
+  );
+});
+
+test('tracing key uses the supplied routeUrl, not a hardcoded path', () => {
+  // Some users pick a different route URL (e.g. /design-system). The tracing
+  // key must match THEIR route, not the default.
+  const out = patchNextConfig(TS_MINIMAL, {
+    renderMode: 'vercel-preview',
+    routeUrl: '/design-system',
+    cssEntry: 'app/globals.css',
+  });
+  assert.match(out, /"\/design-system\/tokens\/\[domain\]"/);
+});
diff --git a/plugins/adhd/lib/sync-docs/cli.js b/plugins/adhd/lib/sync-docs/cli.js
index bf5bdae..acce554 100644
--- a/plugins/adhd/lib/sync-docs/cli.js
+++ b/plugins/adhd/lib/sync-docs/cli.js
@@ -61,15 +61,17 @@ function main() {
   }
 
   if (cmd === 'patch-next-config') {
-    if (!args.config || !args['route-url']) { console.error('Usage: patch-next-config --config <path> --route-url <url> [--render-mode <dev-only|vercel-preview>]'); process.exit(2); }
+    if (!args.config || !args['route-url']) { console.error('Usage: patch-next-config --config <path> --route-url <url> [--render-mode <dev-only|vercel-preview|everywhere>] [--css-entry <path>]'); process.exit(2); }
     const renderMode = args['render-mode'] || 'dev-only';
+    const routeUrl = args['route-url'];
+    const cssEntry = args['css-entry'];
     const src = fs.readFileSync(args.config, 'utf8');
-    const r = patchNextConfig(src, { detectOnly: true });
+    const r = patchNextConfig(src, { detectOnly: true, renderMode, routeUrl, cssEntry });
     if (r && r.conflict) {
       console.error('next.config already sets pageExtensions: ' + r.existing);
       process.exit(3);
     }
-    const out = patchNextConfig(src, { renderMode });
+    const out = patchNextConfig(src, { renderMode, routeUrl, cssEntry });
     fs.writeFileSync(args.config, out);
     process.exit(0);
   }
diff --git a/plugins/adhd/lib/sync-docs/next-config-patcher.js b/plugins/adhd/lib/sync-docs/next-config-patcher.js
index a4bba2d..d83731d 100644
--- a/plugins/adhd/lib/sync-docs/next-config-patcher.js
+++ b/plugins/adhd/lib/sync-docs/next-config-patcher.js
@@ -1,20 +1,20 @@
 'use strict';
 
-// Detection: look for any pageExtensions entry that mentions our sentinel
-// "design-system.tsx" — that's the unique fingerprint of OUR patch, regardless
-// of which env-var condition guards it ('NODE_ENV' vs 'VERCEL_ENV').
-const PATCHED_SENTINEL_RE = /pageExtensions:[\s\S]*?'design-system\.tsx'/;
+// Detection: any of our markers — "design-system.tsx" in pageExtensions OR
+// the tokens-page tracing line. EITHER means we've patched. Re-runs are a
+// no-op once any marker is present; to switch modes, the user removes the
+// patch block manually and re-runs.
+const PATCHED_SENTINEL_RE = /'design-system\.tsx'|adhd:sync-docs — file-tracing/;
 
-// Detection: any other pageExtensions definition (array form).
+// Detection: any OTHER pageExtensions definition (array form not matching ours).
 const EXISTING_PAGE_EXTENSIONS_RE = /pageExtensions:\s*\[/;
 
 // Captures the full `pageExtensions: ...,` declaration for conflict reporting.
 const EXISTING_PAGE_EXTENSIONS_VALUE_RE = /pageExtensions:[^,\n]+,?/;
 
-// Render-mode → conditional source. The "everywhere" mode is handled by NOT
-// calling the patcher at all (files use plain `.tsx` extensions and ship to
-// production). The two excluding modes only differ in which env vars they read.
-const PATCH_BLOCKS = {
+// Render-mode → pageExtensions conditional. "everywhere" doesn't get a
+// pageExtensions block — files are plain `.tsx` and ship to prod normally.
+const PAGE_EXTENSIONS_BLOCKS = {
   'dev-only': `  pageExtensions: process.env.NODE_ENV === 'production'
     ? ['ts', 'tsx']
     : ['ts', 'tsx', 'design-system.ts', 'design-system.tsx'],`,
@@ -29,6 +29,23 @@ const PATCH_BLOCKS = {
       : ['ts', 'tsx', 'design-system.ts', 'design-system.tsx'],`,
 };
 
+// Builds the outputFileTracingIncludes block that ships globals.css alongside
+// the tokens-page function bundle. Without this, Vercel/serverless runtimes
+// don't include the CSS source file (it's normally compiled into static
+// assets), so the runtime fs.readFile in the page throws ENOENT, readCss
+// swallows it as null, and every token swatch falls through to the empty
+// state — even though globals.css is full of declarations. Tracing makes
+// the file part of the deployed function bundle.
+function buildTracingBlock(routeUrl, cssEntry) {
+  // Tracing key matches Next.js's app-router pattern for the page that does
+  // the fs.readFile — `<routeUrl>/tokens/[domain]`. Vercel matches by route.
+  const key = `${routeUrl}/tokens/[domain]`;
+  return `  // adhd:sync-docs — file-tracing for tokens route (so globals.css ships with the serverless function)
+  outputFileTracingIncludes: {
+    ${JSON.stringify(key)}: [${JSON.stringify('./' + cssEntry)}],
+  },`;
+}
+
 function isPatched(source) {
   return PATCHED_SENTINEL_RE.test(source);
 }
@@ -54,20 +71,39 @@ function findConfigObjectStart(source) {
 function patchNextConfig(source, options = {}) {
   if (isPatched(source)) return source;
 
-  // Detect existing different pageExtensions
-  if (EXISTING_PAGE_EXTENSIONS_RE.test(source)) {
-    if (options.detectOnly) {
-      const existing = EXISTING_PAGE_EXTENSIONS_VALUE_RE.exec(source)[0];
-      return { conflict: true, existing };
+  const renderMode = options.renderMode || 'dev-only';
+  const { routeUrl, cssEntry } = options;
+
+  // pageExtensions block: only the two excluding render modes emit one.
+  // "everywhere" mode ships files in plain .tsx, no gate needed.
+  let pageExtensionsBlock = null;
+  if (renderMode !== 'everywhere') {
+    pageExtensionsBlock = PAGE_EXTENSIONS_BLOCKS[renderMode];
+    if (!pageExtensionsBlock) {
+      throw new Error(`Unknown renderMode: ${renderMode}. Expected one of: ${[...Object.keys(PAGE_EXTENSIONS_BLOCKS), 'everywhere'].join(', ')}.`);
+    }
+    // Detect existing different pageExtensions before we try to add ours.
+    if (EXISTING_PAGE_EXTENSIONS_RE.test(source)) {
+      if (options.detectOnly) {
+        const existing = EXISTING_PAGE_EXTENSIONS_VALUE_RE.exec(source)[0];
+        return { conflict: true, existing };
+      }
+      throw new Error('next.config already sets pageExtensions to a different value. Run with detectOnly: true to inspect and prompt the user.');
     }
-    // Caller hasn't checked; we still refuse to silently merge.
-    throw new Error('next.config already sets pageExtensions to a different value. Run with detectOnly: true to inspect and prompt the user.');
   }
 
-  const renderMode = options.renderMode || 'dev-only';
-  const block = PATCH_BLOCKS[renderMode];
-  if (!block) {
-    throw new Error(`Unknown renderMode: ${renderMode}. Expected one of: ${Object.keys(PATCH_BLOCKS).join(', ')}.`);
+  // Tracing block: emitted whenever we have route + css info AND the page
+  // might be served by a serverless function. Dev-only mode runs locally
+  // via `next dev` (project root is cwd, no tracing needed); the other two
+  // modes deploy to Vercel/serverless where tracing IS needed.
+  let tracingBlock = null;
+  if (renderMode !== 'dev-only' && routeUrl && cssEntry) {
+    tracingBlock = buildTracingBlock(routeUrl, cssEntry);
+  }
+
+  if (!pageExtensionsBlock && !tracingBlock) {
+    // Nothing to patch — "everywhere" mode with no route info (legacy callers).
+    return source;
   }
 
   const insertAt = findConfigObjectStart(source);
@@ -75,13 +111,10 @@ function patchNextConfig(source, options = {}) {
     throw new Error('Could not locate the config object in next.config. Manual edit required.');
   }
 
-  // Insert the patch block immediately inside the object literal, before existing
-  // properties. This puts it at the top of the config for visibility.
+  const blocks = [pageExtensionsBlock, tracingBlock].filter(Boolean).join('\n');
   const before = source.slice(0, insertAt);
-  // Strip any leading newline from the tail so it isn't duplicated; we always
-  // emit exactly one `\n` on each side of the block for clean formatting.
   const after = source.slice(insertAt).replace(/^\n/, '');
-  return before + '\n' + block + '\n' + after;
+  return before + '\n' + blocks + '\n' + after;
 }
 
 module.exports = { patchNextConfig, isPatched };
diff --git a/plugins/adhd/skills/sync-docs/SKILL.md b/plugins/adhd/skills/sync-docs/SKILL.md
index 2a9ba4e..6ffbeb8 100644
--- a/plugins/adhd/skills/sync-docs/SKILL.md
+++ b/plugins/adhd/skills/sync-docs/SKILL.md
@@ -86,17 +86,21 @@ test -e "$TARGET" && echo "EXISTS" || echo "FREE"
 
 If `EXISTS` and Phase 2 didn't already mark this as an existing install: prompt "Path `<TARGET>` already exists but is not an installer artifact. Pick a different route or abort."
 
-## Phase 6: Patch next.config.ts (only when `renderMode !== "everywhere"`)
+## Phase 6: Patch next.config.ts
 
-Skip this phase entirely if `renderMode` is `"everywhere"` — those files use plain `.tsx` and ship to prod, so no `pageExtensions` conditional is needed.
+Always run. The patcher emits up to two blocks depending on `renderMode`:
 
-For the two excluding modes, the patcher generates a different conditional based on `--render-mode`:
+- A `pageExtensions` conditional (skipped when `renderMode` is `"everywhere"` — those files ship to prod as plain `.tsx`, no gate needed).
+- An `outputFileTracingIncludes` entry that ships `globals.css` alongside the tokens-page function bundle (emitted whenever the route is deployed to a serverless runtime — i.e. `vercel-preview` or `everywhere`; not needed for pure `dev-only` since `next dev` runs locally with the project root as `cwd`).
+
+Without tracing, the runtime `fs.readFile` in the tokens page returns `null` on Vercel/serverless deploys (the CSS source isn't bundled with the function by default), and every token domain falls through to the empty state — even though `globals.css` is full of declarations.
 
 ```bash
 node plugins/adhd/lib/sync-docs/cli.js patch-next-config \
   --config "<next.config.path>" \
   --route-url "<routeUrl>" \
-  --render-mode "<dev-only|vercel-preview>"
+  --render-mode "<dev-only|vercel-preview|everywhere>" \
+  --css-entry "<cssEntry>"
 ```
 
 Exit codes:
@@ -106,23 +110,32 @@ Exit codes:
 
 **On exit code 3**, use `AskUserQuestion`: "Your next.config.ts sets pageExtensions to `<existing>`. How do you want to handle it? [Show me the manual patch and continue / Abort]."
 
-Automatic merging is NOT supported in v1. On "Show me the manual patch and continue," print the appropriate block for the chosen `renderMode` and continue with Phase 7:
+Automatic merging is NOT supported in v1. On "Show me the manual patch and continue," print the appropriate block(s) for the chosen `renderMode` and continue with Phase 7. Substitute `<routeUrl>` and `<cssEntry>` in the tracing block:
 
 ```ts
-// renderMode: "dev-only"
+// renderMode: "dev-only" — pageExtensions only (no tracing; runs locally via next dev)
 pageExtensions: process.env.NODE_ENV === 'production'
   ? ['ts', 'tsx']
   : ['ts', 'tsx', 'design-system.ts', 'design-system.tsx'],
 
-// renderMode: "vercel-preview"
+// renderMode: "vercel-preview" — pageExtensions AND tracing
 pageExtensions:
   process.env.VERCEL_ENV === 'production' ||
   (!process.env.VERCEL && process.env.NODE_ENV === 'production')
     ? ['ts', 'tsx']
     : ['ts', 'tsx', 'design-system.ts', 'design-system.tsx'],
+// adhd:sync-docs — file-tracing for tokens route (so globals.css ships with the serverless function)
+outputFileTracingIncludes: {
+  '<routeUrl>/tokens/[domain]': ['./<cssEntry>'],
+},
+
+// renderMode: "everywhere" — tracing only
+outputFileTracingIncludes: {
+  '<routeUrl>/tokens/[domain]': ['./<cssEntry>'],
+},
 ```
 
-…and tell the user to merge it with their existing `pageExtensions` value by hand. On "Abort," exit with no further changes.
+Tell the user to merge into their existing config by hand. On "Abort," exit with no further changes.
 
 ## Phase 7: Write the page files
 

From 5d76ff0daec304f8dac4295a5706e902305df2c2 Mon Sep 17 00:00:00 2001
From: Hugh Francis <hughfrancis89@gmail.com>
Date: Mon, 11 May 2026 22:52:46 -0400
Subject: [PATCH 40/79] lint STRUCT011: check Figma variable names against the
 project's convention
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

When linting a frame, walk every variable referenced and check that its
name path follows the project's namingConvention (kebab-case, PascalCase,
camelCase). Aggregates into a SINGLE violation per lint run with all
bad variables listed inline — so the resulting annotation on the
scoped frame is one tidy block instead of N near-identical entries.

Per-segment check: Figma var keys arrive as <collection>/<rest>. The
collection name (e.g. "Primitives", "Semantic") is conventionally
PascalCase in Figma regardless of the project's variable-naming
convention, so we leave the first segment alone — same treatment that
variable-categorizer.strippedToken applies. Every segment AFTER the
collection must match the configured convention.

Suggestions are best-effort transforms. "Primitives/color/BrandPrimary"
in a kebab project becomes "Primitives/color/brand-primary". Acronym
runs like "HTMLParser" split to ["html","parser"] and reassemble.
Numerics stay attached to adjacent text in kebab ("Blue500" →
"blue-500", not "blue-5-0-0").

Scope:
- Scoped lint: violation carries the scoped target's nodeId, so the
  annotation lands on the frame. One annotation, multi-line markdown
  body listing every offending variable with its suggested rename.
- Whole-file lint: nodeId omitted (no scope root to attach to). The
  violation still appears in the markdown report; it just doesn't get
  pushed to Figma as an annotation.

Annotation flow updated to use labelMarkdown when the message contains
a newline (the bulleted format) — label collapses newlines to spaces.

12 unit tests on variable-namer + 2 CLI integration tests covering both
modes. 415/415 plugin-wide.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 .../lib/lint-engine/__tests__/cli.test.js     |  70 ++++++++++++
 .../__tests__/variable-namer.test.js          | 101 ++++++++++++++++++
 plugins/adhd/lib/lint-engine/cli.js           |  28 +++++
 .../adhd/lib/lint-engine/variable-namer.js    |  76 +++++++++++++
 plugins/adhd/skills/lint/SKILL.md             |  13 ++-
 5 files changed, 284 insertions(+), 4 deletions(-)
 create mode 100644 plugins/adhd/lib/lint-engine/__tests__/variable-namer.test.js
 create mode 100644 plugins/adhd/lib/lint-engine/variable-namer.js

diff --git a/plugins/adhd/lib/lint-engine/__tests__/cli.test.js b/plugins/adhd/lib/lint-engine/__tests__/cli.test.js
index a40395d..a138c32 100644
--- a/plugins/adhd/lib/lint-engine/__tests__/cli.test.js
+++ b/plugins/adhd/lib/lint-engine/__tests__/cli.test.js
@@ -165,3 +165,73 @@ test('cli with structure errors but no variable issues exits 1', () => {
   assert.equal(summary.variable.length, 0);
   assert.ok(summary.errors >= 1);
 });
+
+test('STRUCT011: flags Figma variables whose names violate the naming convention', () => {
+  // Design system uses kebab-case (set in adhd.config.ts), but Figma has
+  // `Primitives/color/BrandPrimary` and `Primitives/radius/MD`. The rule
+  // aggregates both into ONE STRUCT011 violation on the scoped target's
+  // nodeId so designers see a single annotation on the frame rather than
+  // two near-identical entries. The collection prefix ("Primitives") is
+  // left alone — Figma convention treats collection names as PascalCase.
+  const varDefs = tmp('vars.json', {
+    'Primitives/color/BrandPrimary': '#000',
+    'Primitives/radius/MD': '8px',
+    'Primitives/color/text/default': '#222', // compliant — shouldn't appear in the message
+  });
+  const ctx = tmp('ctx.json', {
+    id: '5:42', name: 'Logo', type: 'FRAME', layoutMode: 'VERTICAL',
+  });
+  const cssPath = tmp('globals.css', `@theme {} :root {} :root[data-theme="dark"] {}`);
+  const configPath = tmp('adhd.config.ts', `export default { naming: 'kebab-case' };`);
+  const reportPath = path.join(os.tmpdir(), 'adhd-report-' + Date.now() + '.md');
+
+  const result = spawnSync('node', [
+    CLI,
+    '--variable-defs', varDefs,
+    '--design-context', ctx,
+    '--globals-css', cssPath,
+    '--config', configPath,
+    '--target', 'Logo',
+    '--target-url', 'https://figma.com/design/abc?node-id=5-42',
+    '--output', reportPath,
+  ], { encoding: 'utf8' });
+
+  const summary = JSON.parse(result.stdout);
+  const struct011 = summary.structure.find(v => v.rule === 'STRUCT011');
+  assert.ok(struct011, 'expected a STRUCT011 violation');
+  assert.equal(struct011.severity, 'warning');
+  // Anchored to the scoped frame for annotation.
+  assert.equal(struct011.nodeId, '5:42');
+  // Aggregated message lists both offenders + their suggested kebab forms.
+  assert.match(struct011.message, /2 Figma variable\(s\) don't match the kebab-case convention/);
+  assert.match(struct011.message, /Primitives\/color\/BrandPrimary +→ +Primitives\/color\/brand-primary/);
+  assert.match(struct011.message, /Primitives\/radius\/MD +→ +Primitives\/radius\/md/);
+  // Compliant variable is NOT listed.
+  assert.doesNotMatch(struct011.message, /text\/default/);
+});
+
+test('STRUCT011: omits nodeId in whole-file mode (no scope root to annotate)', () => {
+  const varDefs = tmp('vars.json', { 'Primitives/color/BrandPrimary': '#000' });
+  const ctx = tmp('ctx.json', { mode: 'whole-file', pages: [] });
+  const cssPath = tmp('globals.css', `@theme {} :root {} :root[data-theme="dark"] {}`);
+  const configPath = tmp('adhd.config.ts', `export default { naming: 'kebab-case' };`);
+  const reportPath = path.join(os.tmpdir(), 'adhd-report-' + Date.now() + '.md');
+
+  const result = spawnSync('node', [
+    CLI,
+    '--variable-defs', varDefs,
+    '--design-context', ctx,
+    '--globals-css', cssPath,
+    '--config', configPath,
+    '--target', 'Whole file',
+    '--target-url', 'https://figma.com/design/abc/Test',
+    '--output', reportPath,
+  ], { encoding: 'utf8' });
+
+  const summary = JSON.parse(result.stdout);
+  const struct011 = summary.structure.find(v => v.rule === 'STRUCT011');
+  assert.ok(struct011);
+  // No nodeId — the violation appears in the report but doesn't annotate
+  // anywhere (the annotation flow filters out items without nodeIds).
+  assert.equal(struct011.nodeId, undefined);
+});
diff --git a/plugins/adhd/lib/lint-engine/__tests__/variable-namer.test.js b/plugins/adhd/lib/lint-engine/__tests__/variable-namer.test.js
new file mode 100644
index 0000000..c4c72bb
--- /dev/null
+++ b/plugins/adhd/lib/lint-engine/__tests__/variable-namer.test.js
@@ -0,0 +1,101 @@
+'use strict';
+
+const test = require('node:test');
+const assert = require('node:assert/strict');
+const { checkVariableNames, caseMatchesSegment, suggestName, toCase } = require('../variable-namer');
+
+// Real Figma var keys arrive as `<collection>/<rest>`. The first segment is
+// the collection name (Primitives, Semantic) and is left alone — that's the
+// same treatment variable-categorizer applies. All assertions below use the
+// realistic shape.
+
+test('returns [] when convention is false (check disabled)', () => {
+  assert.deepEqual(checkVariableNames(['Primitives/color/BrandPrimary', 'Primitives/radius/MD'], false), []);
+});
+
+test('returns [] when every variable name is compliant in kebab-case (with path segments)', () => {
+  const names = [
+    'Primitives/color/brand-primary',
+    'Semantic/color/text/default',
+    'Primitives/radius/sm',
+    'Primitives/shadow/md',
+  ];
+  assert.deepEqual(checkVariableNames(names, 'kebab-case'), []);
+});
+
+test('does NOT flag the collection prefix even when it is PascalCase (real Figma convention)', () => {
+  // `Primitives` is PascalCase but it's a collection name, not a variable
+  // name. The rule mirrors variable-categorizer.strippedToken behavior.
+  const names = ['Primitives/color/brand-primary'];
+  assert.deepEqual(checkVariableNames(names, 'kebab-case'), []);
+});
+
+test('flags PascalCase-shaped variable segments in a kebab-case project', () => {
+  const result = checkVariableNames(['Primitives/color/BrandPrimary', 'Primitives/radius/MD'], 'kebab-case');
+  assert.equal(result.length, 2);
+  assert.deepEqual(result[0], { name: 'Primitives/color/BrandPrimary', suggestion: 'Primitives/color/brand-primary' });
+  assert.deepEqual(result[1], { name: 'Primitives/radius/MD', suggestion: 'Primitives/radius/md' });
+});
+
+test('only the BAD segment fails; good segments are preserved in the suggestion', () => {
+  // `color` is fine in kebab; `Brand_Primary` is the bad part.
+  const result = checkVariableNames(['Primitives/color/Brand_Primary'], 'kebab-case');
+  assert.equal(result.length, 1);
+  assert.equal(result[0].suggestion, 'Primitives/color/brand-primary');
+});
+
+test('handles numerics in segments without inserting stray separators in kebab', () => {
+  // `color/blue/500` is valid kebab; `color/Blue500` should become `color/blue-500`.
+  const valid = checkVariableNames(['Primitives/color/blue/500'], 'kebab-case');
+  assert.deepEqual(valid, []);
+  const result = checkVariableNames(['Primitives/color/Blue500'], 'kebab-case');
+  assert.equal(result[0].suggestion, 'Primitives/color/blue-500');
+});
+
+test('PascalCase project: flags kebab-cased variable segments (collection prefix kept)', () => {
+  const result = checkVariableNames(['Primitives/brand-primary', 'Primitives/sm'], 'PascalCase');
+  assert.equal(result.length, 2);
+  assert.equal(result[0].suggestion, 'Primitives/BrandPrimary');
+  assert.equal(result[1].suggestion, 'Primitives/Sm');
+});
+
+test('camelCase project: flags Pascal- and kebab-cased segments and suggests camel', () => {
+  const result = checkVariableNames(['Primitives/color/BrandPrimary', 'Primitives/color/text-default'], 'camelCase');
+  assert.equal(result.length, 2);
+  assert.equal(result[0].suggestion, 'Primitives/color/brandPrimary');
+  assert.equal(result[1].suggestion, 'Primitives/color/textDefault');
+});
+
+test('top-level vars without a collection prefix are skipped (no name to check)', () => {
+  // An unprefixed var like "spacing" can't be split — nothing to enforce.
+  assert.deepEqual(checkVariableNames(['spacing'], 'kebab-case'), []);
+});
+
+test('caseMatchesSegment: kebab accepts lowercase+digits+hyphens, rejects uppercase', () => {
+  assert.equal(caseMatchesSegment('brand-primary', 'kebab-case'), true);
+  assert.equal(caseMatchesSegment('blue500', 'kebab-case'), true);
+  assert.equal(caseMatchesSegment('Brand', 'kebab-case'), false);
+  assert.equal(caseMatchesSegment('brand_primary', 'kebab-case'), false);
+});
+
+test('caseMatchesSegment: PascalCase requires leading uppercase', () => {
+  assert.equal(caseMatchesSegment('BrandPrimary', 'PascalCase'), true);
+  assert.equal(caseMatchesSegment('brand', 'PascalCase'), false);
+  assert.equal(caseMatchesSegment('Brand-Primary', 'PascalCase'), false);
+});
+
+test('caseMatchesSegment: camelCase requires leading lowercase, no separators', () => {
+  assert.equal(caseMatchesSegment('brandPrimary', 'camelCase'), true);
+  assert.equal(caseMatchesSegment('Brand', 'camelCase'), false);
+  assert.equal(caseMatchesSegment('brand_primary', 'camelCase'), false);
+});
+
+test('toCase handles HTMLParser-style acronyms by splitting before the lowercase run', () => {
+  // "HTMLParser" → words ["html","parser"] → kebab "html-parser", Pascal "HtmlParser"
+  assert.equal(toCase('HTMLParser', 'kebab-case'), 'html-parser');
+  assert.equal(toCase('HTMLParser', 'PascalCase'), 'HtmlParser');
+});
+
+test('suggestName preserves the / path separator', () => {
+  assert.equal(suggestName('color/text/PrimaryBold', 'kebab-case'), 'color/text/primary-bold');
+});
diff --git a/plugins/adhd/lib/lint-engine/cli.js b/plugins/adhd/lib/lint-engine/cli.js
index 0d83469..bd13dc0 100644
--- a/plugins/adhd/lib/lint-engine/cli.js
+++ b/plugins/adhd/lib/lint-engine/cli.js
@@ -21,6 +21,7 @@ const fs = require('node:fs');
 const { parseTheme } = require('./theme-parser');
 const { categorizeVariables } = require('./variable-categorizer');
 const { checkStructure } = require('./structure-checker');
+const { checkVariableNames } = require('./variable-namer');
 const { formatReport } = require('./report-formatter');
 
 function parseArgs(argv) {
@@ -102,6 +103,33 @@ function main() {
     structureViolations = checkStructure(designCtx, { fileKey, namingConvention });
   }
 
+  // STRUCT011 — variable-name compliance. Aggregated into a SINGLE violation
+  // per lint run (rather than per-variable) so the annotation on the scoped
+  // frame is one tidy block instead of N near-identical entries. In whole-file
+  // mode there's no scope root, so we omit nodeId — the violation still
+  // appears in the report but doesn't annotate.
+  const badVarNames = checkVariableNames(Object.keys(varDefs || {}), namingConvention);
+  if (badVarNames.length > 0) {
+    const isScoped = designCtx && designCtx.mode !== 'whole-file' && designCtx.id;
+    const scopedNodeId = isScoped ? designCtx.id : undefined;
+    const shown = badVarNames.slice(0, 8);
+    const lines = shown.map(v => `  • ${v.name}  →  ${v.suggestion}`);
+    const more = badVarNames.length > 8 ? `\n  +${badVarNames.length - 8} more` : '';
+    structureViolations.push({
+      rule: 'STRUCT011',
+      severity: 'warning',
+      nodeId: scopedNodeId,
+      nodePath: 'Variables',
+      message:
+        `${badVarNames.length} Figma variable(s) don't match the ${namingConvention} convention:\n` +
+        `${lines.join('\n')}${more}\n` +
+        `Rename them in Figma (right-click the variable → "Rename") to match.`,
+      deepLink: scopedNodeId
+        ? 'https://figma.com/design/' + fileKey + '?node-id=' + scopedNodeId.replace(':', '-')
+        : args['target-url'],
+    });
+  }
+
   const meta = {
     target: args.target,
     targetUrl: args['target-url'],
diff --git a/plugins/adhd/lib/lint-engine/variable-namer.js b/plugins/adhd/lib/lint-engine/variable-namer.js
new file mode 100644
index 0000000..7f5e044
--- /dev/null
+++ b/plugins/adhd/lib/lint-engine/variable-namer.js
@@ -0,0 +1,76 @@
+'use strict';
+
+// STRUCT011 — variable-name compliance.
+//
+// Splits each Figma variable name on `/` (Figma's path separator) and checks
+// each segment against the project's naming convention. Per-segment is the
+// right granularity: `color/brand/500` has three segments that each need to
+// individually match kebab/Pascal/camel — treating the whole name as one
+// string fails since `/` isn't valid in any convention.
+//
+// Returns: an array of `{ name, suggestion }` for variables whose name
+// doesn't match. The suggestion is a best-effort rewrite into the target
+// convention (splits words on case transitions, hyphens, underscores;
+// numerics stay in place).
+
+function caseMatchesSegment(segment, convention) {
+  if (convention === false || convention == null) return true;
+  if (convention === 'kebab-case') return /^[a-z0-9]+(-[a-z0-9]+)*$/.test(segment);
+  if (convention === 'PascalCase') return /^[A-Z][a-zA-Z0-9]*$/.test(segment);
+  if (convention === 'camelCase')  return /^[a-z][a-zA-Z0-9]*$/.test(segment);
+  return true;
+}
+
+// Word-split: handles "BrandPrimary", "brand-primary", "brand_primary",
+// "color500", "HTMLParser" → ["html","parser"], etc.
+function splitWords(segment) {
+  return segment
+    .replace(/([a-z0-9])([A-Z])/g, '$1 $2')
+    .replace(/([A-Z]+)([A-Z][a-z])/g, '$1 $2')
+    .replace(/([a-zA-Z])([0-9])/g, '$1 $2')
+    .replace(/([0-9])([a-zA-Z])/g, '$1 $2')
+    .split(/[-_\s]+/)
+    .filter(Boolean)
+    .map(w => w.toLowerCase());
+}
+
+function toCase(segment, convention) {
+  const words = splitWords(segment);
+  if (words.length === 0) return segment;
+  if (convention === 'kebab-case') return words.join('-');
+  if (convention === 'PascalCase') return words.map(w => w[0].toUpperCase() + w.slice(1)).join('');
+  if (convention === 'camelCase') {
+    return words.map((w, i) => i === 0 ? w : w[0].toUpperCase() + w.slice(1)).join('');
+  }
+  return segment;
+}
+
+// Variable keys arrive as `<collection>/<name>` from the SKILL's serializer.
+// The collection name (e.g. "Primitives", "Semantic") is conventionally
+// PascalCase in Figma regardless of the project's variable-naming convention
+// — same treatment variable-categorizer already gives it via `strippedToken`.
+// We only check segments AFTER the collection.
+function suggestName(name, convention) {
+  const segments = name.split('/');
+  if (segments.length <= 1) return name;
+  const [collection, ...rest] = segments;
+  return [collection, ...rest.map(s => toCase(s, convention))].join('/');
+}
+
+function checkVariableNames(varNames, convention) {
+  if (convention === false || convention == null) return [];
+  const out = [];
+  for (const name of varNames) {
+    const segments = name.split('/');
+    // Skip collection-prefix-only entries (`foo` with no slash); nothing to check.
+    if (segments.length <= 1) continue;
+    const checked = segments.slice(1);
+    const allGood = checked.every(s => caseMatchesSegment(s, convention));
+    if (!allGood) {
+      out.push({ name, suggestion: suggestName(name, convention) });
+    }
+  }
+  return out;
+}
+
+module.exports = { checkVariableNames, caseMatchesSegment, suggestName, toCase };
diff --git a/plugins/adhd/skills/lint/SKILL.md b/plugins/adhd/skills/lint/SKILL.md
index 926f6e8..fb9cc93 100644
--- a/plugins/adhd/skills/lint/SKILL.md
+++ b/plugins/adhd/skills/lint/SKILL.md
@@ -165,10 +165,15 @@ for (const id of allTargetIds) {
   const node = await figma.getNodeByIdAsync(id);
   if (!node || !("annotations" in node)) continue;
   const keep = (node.annotations ?? []).filter(a => a.categoryId !== cat.id);
-  const fresh = (byNode.get(id) ?? []).map(v => ({
-    label: `${v.code}: ${v.message}`,
-    categoryId: cat.id,
-  }));
+  const fresh = (byNode.get(id) ?? []).map(v => {
+    // labelMarkdown renders newlines and bullet lists (used by STRUCT011's
+    // aggregated variable-naming message); label collapses them to spaces.
+    // Prefer labelMarkdown when the message contains a newline.
+    const text = `${v.code}: ${v.message}`;
+    return text.includes("\n")
+      ? { labelMarkdown: text, categoryId: cat.id }
+      : { label: text, categoryId: cat.id };
+  });
   const hadAdhd = touchedIds.has(id);
   node.annotations = [...keep, ...fresh];
   if (fresh.length > 0) updated++;

From ad1e3402d15329ed46414524b740119fcdc49204 Mon Sep 17 00:00:00 2001
From: Hugh Francis <hughfrancis89@gmail.com>
Date: Mon, 11 May 2026 22:56:32 -0400
Subject: [PATCH 41/79] lint STRUCT011: add Tailwind-domain "did you mean?"
 hints
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

User asked for a feature where lint hints at the right variable naming
when a designer's choice doesn't map to a Tailwind v4 token domain —
e.g. "did you mean 'color' instead of 'colur'?" Folded into STRUCT011
(same rule, second half) so a single annotation per frame covers
everything related to "fix your variable names."

Three detection paths:
- Synonyms (high precision): a hand-curated table mapping common
  alternates to canonical names. `colors → color`, `space → spacing`,
  `screens → breakpoint`, `font-size → text`, `line-height → leading`,
  etc.
- Typos (Levenshtein ≤ 2): catches `colur → color`, `radiu → radius`,
  etc. without producing false-positive matches for genuinely unrelated
  names.
- Unknown (distance > 2): designer is using a prefix we can't guess at.
  Surface the canonical list so they can pick one.

CLI now emits a single aggregated STRUCT011 violation that combines case
and domain violations into "N variable-naming issue(s)" with separate
sub-sections per concern. Whole-file mode still omits nodeId so the
violation appears in the report without an annotation.

Example annotation body on a mixed-issues frame:

  4 variable-naming issue(s):

  Case (kebab-case):
    • Primitives/color/BrandPrimary  →  Primitives/color/brand-primary

  Tailwind v4 domain:
    • Primitives/colur/brand-500  —  did you mean "color"? (looks like a typo)
    • Primitives/space/sm  —  did you mean "spacing"? (Tailwind v4 prefix)
    • Primitives/widget/foo  —  unknown domain "widget"; expected one of:
      color, spacing, text, font, font-weight, tracking, leading, radius,
      shadow, breakpoint, ease, animate

  Rename them in Figma (right-click the variable → "Rename") to match.

7 new unit tests covering classifyDomain across known/synonym/typo/
unknown cases + checkVariableDomains end-to-end. CLI integration test
asserts the combined message format with all four flavours of issue.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 .../lib/lint-engine/__tests__/cli.test.js     |  31 +++--
 .../__tests__/variable-namer.test.js          |  71 +++++++++-
 plugins/adhd/lib/lint-engine/cli.js           |  49 +++++--
 .../adhd/lib/lint-engine/variable-namer.js    | 127 +++++++++++++++++-
 4 files changed, 249 insertions(+), 29 deletions(-)

diff --git a/plugins/adhd/lib/lint-engine/__tests__/cli.test.js b/plugins/adhd/lib/lint-engine/__tests__/cli.test.js
index a138c32..5f25e56 100644
--- a/plugins/adhd/lib/lint-engine/__tests__/cli.test.js
+++ b/plugins/adhd/lib/lint-engine/__tests__/cli.test.js
@@ -166,17 +166,15 @@ test('cli with structure errors but no variable issues exits 1', () => {
   assert.ok(summary.errors >= 1);
 });
 
-test('STRUCT011: flags Figma variables whose names violate the naming convention', () => {
-  // Design system uses kebab-case (set in adhd.config.ts), but Figma has
-  // `Primitives/color/BrandPrimary` and `Primitives/radius/MD`. The rule
-  // aggregates both into ONE STRUCT011 violation on the scoped target's
-  // nodeId so designers see a single annotation on the frame rather than
-  // two near-identical entries. The collection prefix ("Primitives") is
-  // left alone — Figma convention treats collection names as PascalCase.
+test('STRUCT011: flags Figma variables whose names violate case OR Tailwind domain expectations', () => {
+  // Mix of three issue types in one frame — STRUCT011 aggregates them into a
+  // single annotation with separate "Case" and "Tailwind v4 domain" sections.
   const varDefs = tmp('vars.json', {
-    'Primitives/color/BrandPrimary': '#000',
-    'Primitives/radius/MD': '8px',
-    'Primitives/color/text/default': '#222', // compliant — shouldn't appear in the message
+    'Primitives/color/BrandPrimary': '#000',       // case violation (kebab-case project)
+    'Primitives/colur/brand-500':    '#111',       // domain typo (Levenshtein)
+    'Primitives/space/sm':           '0.5rem',     // domain synonym
+    'Primitives/widget/foo':         '?',          // unknown domain
+    'Primitives/color/text/default': '#222',       // compliant — shouldn't appear
   });
   const ctx = tmp('ctx.json', {
     id: '5:42', name: 'Logo', type: 'FRAME', layoutMode: 'VERTICAL',
@@ -200,12 +198,17 @@ test('STRUCT011: flags Figma variables whose names violate the naming convention
   const struct011 = summary.structure.find(v => v.rule === 'STRUCT011');
   assert.ok(struct011, 'expected a STRUCT011 violation');
   assert.equal(struct011.severity, 'warning');
-  // Anchored to the scoped frame for annotation.
   assert.equal(struct011.nodeId, '5:42');
-  // Aggregated message lists both offenders + their suggested kebab forms.
-  assert.match(struct011.message, /2 Figma variable\(s\) don't match the kebab-case convention/);
+  // Header counts ALL issues (1 case + 3 domain = 4).
+  assert.match(struct011.message, /4 variable-naming issue\(s\)/);
+  // Case section
+  assert.match(struct011.message, /Case \(kebab-case\):/);
   assert.match(struct011.message, /Primitives\/color\/BrandPrimary +→ +Primitives\/color\/brand-primary/);
-  assert.match(struct011.message, /Primitives\/radius\/MD +→ +Primitives\/radius\/md/);
+  // Domain section with all three "did you mean?" flavours
+  assert.match(struct011.message, /Tailwind v4 domain:/);
+  assert.match(struct011.message, /Primitives\/colur\/brand-500.*did you mean "color".*typo/);
+  assert.match(struct011.message, /Primitives\/space\/sm.*did you mean "spacing".*Tailwind v4 prefix/);
+  assert.match(struct011.message, /Primitives\/widget\/foo.*unknown domain "widget".*expected one of: color, spacing/);
   // Compliant variable is NOT listed.
   assert.doesNotMatch(struct011.message, /text\/default/);
 });
diff --git a/plugins/adhd/lib/lint-engine/__tests__/variable-namer.test.js b/plugins/adhd/lib/lint-engine/__tests__/variable-namer.test.js
index c4c72bb..93a9aea 100644
--- a/plugins/adhd/lib/lint-engine/__tests__/variable-namer.test.js
+++ b/plugins/adhd/lib/lint-engine/__tests__/variable-namer.test.js
@@ -2,7 +2,10 @@
 
 const test = require('node:test');
 const assert = require('node:assert/strict');
-const { checkVariableNames, caseMatchesSegment, suggestName, toCase } = require('../variable-namer');
+const {
+  checkVariableNames, caseMatchesSegment, suggestName, toCase,
+  checkVariableDomains, classifyDomain, TAILWIND_DOMAINS,
+} = require('../variable-namer');
 
 // Real Figma var keys arrive as `<collection>/<rest>`. The first segment is
 // the collection name (Primitives, Semantic) and is left alone — that's the
@@ -71,6 +74,72 @@ test('top-level vars without a collection prefix are skipped (no name to check)'
   assert.deepEqual(checkVariableNames(['spacing'], 'kebab-case'), []);
 });
 
+// ---------------------------------------------------------------------------
+// Domain "did you mean?" half of STRUCT011
+
+test('classifyDomain: recognized Tailwind v4 prefixes return known', () => {
+  for (const d of TAILWIND_DOMAINS) {
+    assert.deepEqual(classifyDomain(d), { kind: 'known' }, `expected "${d}" to be known`);
+  }
+});
+
+test('classifyDomain: synonyms suggest the canonical name', () => {
+  assert.deepEqual(classifyDomain('colors'), { kind: 'synonym', suggestion: 'color' });
+  assert.deepEqual(classifyDomain('space'), { kind: 'synonym', suggestion: 'spacing' });
+  assert.deepEqual(classifyDomain('shadows'), { kind: 'synonym', suggestion: 'shadow' });
+  assert.deepEqual(classifyDomain('screens'), { kind: 'synonym', suggestion: 'breakpoint' });
+  assert.deepEqual(classifyDomain('font-size'), { kind: 'synonym', suggestion: 'text' });
+  assert.deepEqual(classifyDomain('line-height'), { kind: 'synonym', suggestion: 'leading' });
+});
+
+test('classifyDomain: small typos (distance ≤ 2) are classified as typo with suggestion', () => {
+  // "colur" → "color" (distance 1, missing 'o' + extra letter)
+  const r1 = classifyDomain('colur');
+  assert.equal(r1.kind, 'typo');
+  assert.equal(r1.suggestion, 'color');
+  // "radiu" → "radius" (distance 1, missing 's')
+  const r2 = classifyDomain('radiu');
+  assert.equal(r2.kind, 'typo');
+  assert.equal(r2.suggestion, 'radius');
+});
+
+test('classifyDomain: genuinely unknown prefixes return kind:unknown', () => {
+  // "widget" is too distant from anything in the list to be a typo.
+  assert.deepEqual(classifyDomain('widget'), { kind: 'unknown' });
+  assert.deepEqual(classifyDomain('miscellaneous'), { kind: 'unknown' });
+});
+
+test('classifyDomain is case-insensitive on input', () => {
+  // The case-convention check is a separate concern; domain classification
+  // shouldn't depend on whether the designer wrote "Color" or "color".
+  assert.deepEqual(classifyDomain('Color'), { kind: 'known' });
+  assert.deepEqual(classifyDomain('SHADOWS'), { kind: 'synonym', suggestion: 'shadow' });
+});
+
+test('checkVariableDomains: real Figma keys with collection prefix', () => {
+  const names = [
+    'Primitives/color/brand-500',           // ok
+    'Primitives/colur/brand-500',           // typo
+    'Primitives/space/sm',                  // synonym
+    'Primitives/widget/foo',                // unknown
+    'Semantic/color/text/default',          // ok
+  ];
+  const out = checkVariableDomains(names);
+  assert.equal(out.length, 3);
+  assert.equal(out[0].name, 'Primitives/colur/brand-500');
+  assert.equal(out[0].classification.kind, 'typo');
+  assert.equal(out[0].classification.suggestion, 'color');
+  assert.equal(out[1].name, 'Primitives/space/sm');
+  assert.equal(out[1].classification.kind, 'synonym');
+  assert.equal(out[1].classification.suggestion, 'spacing');
+  assert.equal(out[2].name, 'Primitives/widget/foo');
+  assert.equal(out[2].classification.kind, 'unknown');
+});
+
+test('checkVariableDomains: collection-only names (no slash) are skipped', () => {
+  assert.deepEqual(checkVariableDomains(['Primitives']), []);
+});
+
 test('caseMatchesSegment: kebab accepts lowercase+digits+hyphens, rejects uppercase', () => {
   assert.equal(caseMatchesSegment('brand-primary', 'kebab-case'), true);
   assert.equal(caseMatchesSegment('blue500', 'kebab-case'), true);
diff --git a/plugins/adhd/lib/lint-engine/cli.js b/plugins/adhd/lib/lint-engine/cli.js
index bd13dc0..2dca8a6 100644
--- a/plugins/adhd/lib/lint-engine/cli.js
+++ b/plugins/adhd/lib/lint-engine/cli.js
@@ -21,7 +21,7 @@ const fs = require('node:fs');
 const { parseTheme } = require('./theme-parser');
 const { categorizeVariables } = require('./variable-categorizer');
 const { checkStructure } = require('./structure-checker');
-const { checkVariableNames } = require('./variable-namer');
+const { checkVariableNames, checkVariableDomains, TAILWIND_DOMAINS } = require('./variable-namer');
 const { formatReport } = require('./report-formatter');
 
 function parseArgs(argv) {
@@ -103,26 +103,49 @@ function main() {
     structureViolations = checkStructure(designCtx, { fileKey, namingConvention });
   }
 
-  // STRUCT011 — variable-name compliance. Aggregated into a SINGLE violation
-  // per lint run (rather than per-variable) so the annotation on the scoped
-  // frame is one tidy block instead of N near-identical entries. In whole-file
-  // mode there's no scope root, so we omit nodeId — the violation still
-  // appears in the report but doesn't annotate.
-  const badVarNames = checkVariableNames(Object.keys(varDefs || {}), namingConvention);
-  if (badVarNames.length > 0) {
+  // STRUCT011 — variable-name compliance. Combines TWO concerns into one
+  // aggregated violation so the designer sees a single "fix your variable
+  // names" block per lint run:
+  //   - Case: name doesn't follow the project's namingConvention
+  //     (kebab/Pascal/camel).
+  //   - Domain: first segment after the collection doesn't map to a Tailwind v4
+  //     token-domain prefix (color/spacing/text/font/etc.). Suggests a synonym
+  //     or typo correction via the "did you mean?" heuristic.
+  // In whole-file mode there's no scope root, so we omit nodeId — the
+  // violation still appears in the report but doesn't annotate.
+  const varKeys = Object.keys(varDefs || {});
+  const badCase = checkVariableNames(varKeys, namingConvention);
+  const badDomain = checkVariableDomains(varKeys);
+  if (badCase.length > 0 || badDomain.length > 0) {
     const isScoped = designCtx && designCtx.mode !== 'whole-file' && designCtx.id;
     const scopedNodeId = isScoped ? designCtx.id : undefined;
-    const shown = badVarNames.slice(0, 8);
-    const lines = shown.map(v => `  • ${v.name}  →  ${v.suggestion}`);
-    const more = badVarNames.length > 8 ? `\n  +${badVarNames.length - 8} more` : '';
+    const sections = [];
+    if (badCase.length > 0) {
+      const shown = badCase.slice(0, 8);
+      const lines = shown.map(v => `  • ${v.name}  →  ${v.suggestion}`);
+      const more = badCase.length > 8 ? `\n  +${badCase.length - 8} more` : '';
+      sections.push(`Case (${namingConvention}):\n${lines.join('\n')}${more}`);
+    }
+    if (badDomain.length > 0) {
+      const shown = badDomain.slice(0, 8);
+      const lines = shown.map(v => {
+        const c = v.classification;
+        if (c.kind === 'synonym') return `  • ${v.name}  —  did you mean "${c.suggestion}"? (Tailwind v4 prefix)`;
+        if (c.kind === 'typo')    return `  • ${v.name}  —  did you mean "${c.suggestion}"? (looks like a typo)`;
+        return `  • ${v.name}  —  unknown domain "${v.domainSegment}"; expected one of: ${TAILWIND_DOMAINS.join(', ')}`;
+      });
+      const more = badDomain.length > 8 ? `\n  +${badDomain.length - 8} more` : '';
+      sections.push(`Tailwind v4 domain:\n${lines.join('\n')}${more}`);
+    }
+    const total = badCase.length + badDomain.length;
     structureViolations.push({
       rule: 'STRUCT011',
       severity: 'warning',
       nodeId: scopedNodeId,
       nodePath: 'Variables',
       message:
-        `${badVarNames.length} Figma variable(s) don't match the ${namingConvention} convention:\n` +
-        `${lines.join('\n')}${more}\n` +
+        `${total} variable-naming issue(s):\n` +
+        `${sections.join('\n\n')}\n\n` +
         `Rename them in Figma (right-click the variable → "Rename") to match.`,
       deepLink: scopedNodeId
         ? 'https://figma.com/design/' + fileKey + '?node-id=' + scopedNodeId.replace(':', '-')
diff --git a/plugins/adhd/lib/lint-engine/variable-namer.js b/plugins/adhd/lib/lint-engine/variable-namer.js
index 7f5e044..febb617 100644
--- a/plugins/adhd/lib/lint-engine/variable-namer.js
+++ b/plugins/adhd/lib/lint-engine/variable-namer.js
@@ -73,4 +73,129 @@ function checkVariableNames(varNames, convention) {
   return out;
 }
 
-module.exports = { checkVariableNames, caseMatchesSegment, suggestName, toCase };
+// ---------------------------------------------------------------------------
+// STRUCT011 — Tailwind v4 domain "did you mean?" check.
+//
+// Second half of the variable-naming rule. The first half (above) checks the
+// case convention; this half checks that the first segment AFTER the
+// collection maps to a Tailwind v4 token-domain prefix. Both halves emit
+// under the same rule code (STRUCT011) and get aggregated into one
+// annotation — designers see "variable naming compliance" as a single
+// concern, not two separate things to chase down.
+//
+// Why this matters: a variable named `Primitives/colur/brand-500` is
+// perfectly kebab-case, so the case half passes — but `colur` doesn't map
+// to anything in Tailwind v4. Code gen sees an unrecognized namespace and
+// either drops the var or surfaces it as a one-off alias.
+//
+// This rule catches three classes of issue:
+//   1. Synonyms — designers writing the natural-language form instead of
+//      Tailwind's canonical name (`colors/...`, `space/...`, `shadows/...`,
+//      `screens/...`, etc.).
+//   2. Typos — `colur/brand-500`, `radiu/sm`. Caught via Levenshtein distance.
+//   3. Genuinely unknown prefixes — `widget/...`, `random/...`. Flagged with
+//      the list of recognized domains so the designer can pick one.
+//
+// Suggestions come from a hand-curated synonym table first (high precision),
+// falling back to Levenshtein distance ≤ 2 against the canonical domain list.
+// Distance 3+ → "no good match"; report lists the canonical set instead.
+
+const TAILWIND_DOMAINS = [
+  'color', 'spacing', 'text', 'font', 'font-weight',
+  'tracking', 'leading', 'radius', 'shadow',
+  'breakpoint', 'ease', 'animate',
+];
+
+const DOMAIN_SYNONYMS = {
+  // Pluralization
+  'colors': 'color',
+  'shadows': 'shadow',
+  'radii': 'radius',
+  'animations': 'animate',
+  'breakpoints': 'breakpoint',
+  'easings': 'ease',
+  'fonts': 'font',
+  // Common alternates
+  'colour': 'color',
+  'colours': 'color',
+  'space': 'spacing',
+  'spaces': 'spacing',
+  'screen': 'breakpoint',
+  'screens': 'breakpoint',
+  'media': 'breakpoint',
+  'transition': 'ease',
+  'easing': 'ease',
+  'animation': 'animate',
+  'border-radius': 'radius',
+  'rounded': 'radius',
+  'font-family': 'font',
+  'font-size': 'text',
+  'fontsize': 'text',
+  'font-weights': 'font-weight',
+  'fontweight': 'font-weight',
+  'weight': 'font-weight',
+  'letter-spacing': 'tracking',
+  'letterspacing': 'tracking',
+  'line-height': 'leading',
+  'lineheight': 'leading',
+};
+
+function levenshtein(a, b) {
+  if (a === b) return 0;
+  if (!a.length) return b.length;
+  if (!b.length) return a.length;
+  let v0 = Array.from({ length: b.length + 1 }, (_, i) => i);
+  let v1 = new Array(b.length + 1);
+  for (let i = 0; i < a.length; i++) {
+    v1[0] = i + 1;
+    for (let j = 0; j < b.length; j++) {
+      const cost = a[i] === b[j] ? 0 : 1;
+      v1[j + 1] = Math.min(v1[j] + 1, v0[j + 1] + 1, v0[j] + cost);
+    }
+    [v0, v1] = [v1, v0];
+  }
+  return v0[b.length];
+}
+
+// Returns { kind: 'known' } | { kind: 'synonym', suggestion } |
+//   { kind: 'typo', suggestion, distance } | { kind: 'unknown' }
+function classifyDomain(segment) {
+  const lower = segment.toLowerCase();
+  if (TAILWIND_DOMAINS.includes(lower)) return { kind: 'known' };
+  if (DOMAIN_SYNONYMS[lower]) {
+    return { kind: 'synonym', suggestion: DOMAIN_SYNONYMS[lower] };
+  }
+  // Fall back to Levenshtein. Distance 1–2 = likely typo. 3+ = probably not
+  // a typo — flag as unknown so the user picks from the canonical list.
+  const candidates = TAILWIND_DOMAINS
+    .map(d => ({ domain: d, distance: levenshtein(lower, d) }))
+    .sort((a, b) => a.distance - b.distance);
+  const best = candidates[0];
+  if (best.distance <= 2) {
+    return { kind: 'typo', suggestion: best.domain, distance: best.distance };
+  }
+  return { kind: 'unknown' };
+}
+
+// Returns an array of `{ name, domainSegment, classification }` for vars whose
+// post-collection first segment doesn't match a known Tailwind v4 domain.
+// Names with no path segments after the collection are skipped (nothing to
+// classify).
+function checkVariableDomains(varNames) {
+  const out = [];
+  for (const name of varNames) {
+    const segments = name.split('/');
+    if (segments.length <= 1) continue;
+    const domainSegment = segments[1]; // first segment AFTER collection
+    const classification = classifyDomain(domainSegment);
+    if (classification.kind !== 'known') {
+      out.push({ name, domainSegment, classification });
+    }
+  }
+  return out;
+}
+
+module.exports = {
+  checkVariableNames, caseMatchesSegment, suggestName, toCase,
+  checkVariableDomains, classifyDomain, TAILWIND_DOMAINS,
+};

From 6fe405c4ddc2e26d901c8d7f4ae705f4adbfaf85 Mon Sep 17 00:00:00 2001
From: Hugh Francis <hughfrancis89@gmail.com>
Date: Mon, 11 May 2026 22:58:30 -0400
Subject: [PATCH 42/79] pull-component: STRUCT011 now blocks the pull (no
 escape)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

User report: pulling a component with STRUCT011 violations was treated
as ignorable. Promoted STRUCT011 to a blocking violation in the
preflight, alongside the existing STRUCT003/004/005 binding errors.

Rationale: STRUCT011 indicates Figma variables that won't bind cleanly
to code's @theme (case mismatch, unrecognized Tailwind domain, or both).
If we proceed, the pulled component's lookup tables either reference
variables that don't exist in code, or land with the wrong name shape —
either way the round-trip via /adhd:push-component will drift.

No escape for STRUCT011 — the only valid fix is renaming in Figma. The
existing --allow-unbound and components.<path>.allowUnboundFigma config
flag still apply to binding errors only; they're for the "land it as an
arbitrary Tailwind class" pragmatic short-term path. There's no
analogous "land bad names anyway" path for STRUCT011, so adding a flag
wouldn't be honest.

When both blocker classes are present, STRUCT011 is surfaced first
(more fundamental fix — bind-errors might be tolerable with the
escape, but bad names always need fixing first).

Annotate-before-aborting flow already picks STRUCT011 up via the
existing annotation pipeline (it has nodeId in scoped mode). Updated
the "annotate retroactively?" prompt copy to mention both blocker
classes.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 plugins/adhd/skills/pull-component/SKILL.md | 27 +++++++++++++++++++--
 1 file changed, 25 insertions(+), 2 deletions(-)

diff --git a/plugins/adhd/skills/pull-component/SKILL.md b/plugins/adhd/skills/pull-component/SKILL.md
index af75178..76dcf2c 100644
--- a/plugins/adhd/skills/pull-component/SKILL.md
+++ b/plugins/adhd/skills/pull-component/SKILL.md
@@ -92,7 +92,12 @@ The stdout redirect captures the engine's JSON summary for Phase 2.6's optional
 
 Use the globals.css path from `config.cssEntry` if set, otherwise auto-detect: `example/app/globals.css` → `app/globals.css` → `src/app/globals.css`.
 
-Use `Read` on `/tmp/adhd-pull-component/preflight.md`. Scan for STRUCT003/004/005 (variable-binding errors). Other rules' violations are noted for the final report but don't block.
+Use `Read` on `/tmp/adhd-pull-component/preflight.md`. Two classes of violation block the pull:
+
+- **STRUCT003/004/005** — variable-binding errors (layer uses raw color, typography, or effect that isn't bound to a variable or paint style). The `--allow-unbound` escape applies here; without it, abort.
+- **STRUCT011** — variable-naming non-compliance (case violation OR Tailwind v4 domain mismatch). No escape — the designer fixes the names in Figma before the pull can proceed. Rationale: if Figma variables have non-conventional names, the pulled code's lookup tables would either reference broken names or drift from the design system. Better to fix the source than carry forward bad names into generated code.
+
+Other rules' violations are noted for the final report but don't block.
 
 ### Annotate offending nodes in Figma
 
@@ -100,7 +105,7 @@ Two paths, both producing the same `use_figma` annotation work described in `/ad
 
 **Path A — `--annotate` was passed.** Run the annotation script unconditionally.
 
-**Path B — `--annotate` was NOT passed, AND there are variable-binding errors (STRUCT003/004/005) that will block the pull.** Use `AskUserQuestion` to offer it retroactively:
+**Path B — `--annotate` was NOT passed, AND there are blocking violations (STRUCT003/004/005 binding errors, OR STRUCT011 variable-naming non-compliance).** Use `AskUserQuestion` to offer annotation retroactively:
 
 ```
 Question: "Push these <N> preflight violation(s) to Figma as annotations before aborting? Designers can see them in the 'lint' category to fix in-context."
@@ -160,6 +165,24 @@ Continue? [Y] yes / [N] no (abort)
 
 On `no` or no answer, abort. On `yes`, note which entries will be off-system; you'll prefix their applied values with the `// adhd:off-system — <reason>` comment in Phase 7.
 
+**If STRUCT011 violations exist (variable-naming non-compliance):**
+
+Abort unconditionally — there is no escape. STRUCT011 reports either a case-convention mismatch on a variable name or an unrecognized Tailwind v4 domain prefix; in both cases the fix is the designer renaming the variable in Figma, not the pull adapting around it. If we proceeded, the pulled component's lookup tables would reference variables that either don't bind to anything in code's `@theme` or land in code with the wrong name shape — drift we can't reliably round-trip on the next `/adhd:push-component`.
+
+Read the STRUCT011 message from the preflight report verbatim (it already names every offender + suggested rename) and print it under a banner:
+
+```
+✗ Cannot pull — the Figma Component Set has variables that don't follow the design-system naming conventions:
+
+<paste the STRUCT011 message verbatim>
+
+Fix the variable names in Figma (right-click each variable → "Rename")
+and re-run /adhd:pull-component. There's no escape for this — bad names
+would land in your code's lookup tables and drift on the next push.
+```
+
+If BOTH STRUCT011 AND variable-binding errors are present, surface STRUCT011 first (it's the more fundamental fix — bind-errors might be tolerable with `--allow-unbound`, but bad names always need fixing first).
+
 ## Phase 3: Read both sides
 
 **React side (update mode only):** use `Read` on `<react-path>` (from Phase 2). Identify:

From bc1dacd51b732f9d33c640a0c6a31bf2a1a949e5 Mon Sep 17 00:00:00 2001
From: Hugh Francis <hughfrancis89@gmail.com>
Date: Mon, 11 May 2026 23:06:57 -0400
Subject: [PATCH 43/79] lint STRUCT011: two bug fixes from real lint output
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Both reported by the user on a real reactor-webapp run:

1. Variable case check was honoring \`naming: "PascalCase"\` from
   adhd.config.ts and suggesting renames like \`Color/gold\` → \`Color/Gold\`.
   The \`naming\` config is for component identifiers (Logo vs logo); CSS
   custom properties are kebab-case lowercase by Tailwind v4 spec — there's
   no working "PascalCase variables" mode. Hardcoded the variable case
   check to kebab-case regardless of project config, and updated the
   section header to say so: "Case (kebab-case — Tailwind v4 requires
   lowercase CSS vars)" rather than "Case (PascalCase)".

2. \`Radius/sm\` was flagged as unknown domain. The rule assumed the first
   segment AFTER the collection was the domain prefix, but some teams
   organize collections BY domain ("Color", "Radius", "Spacing") instead
   of by tier ("Primitives", "Semantic"). When the collection name itself
   is a Tailwind domain (or a known synonym), the variable name doesn't
   need another domain prefix.

   New collectionIsDomain helper normalizes collection names (lowercases,
   collapses "+", spaces, hyphens) and runs them through classifyDomain.
   Match (known OR synonym) → skip domain check for that variable.

   Distinguishes:
   - "Color" → "color" → known → skip ✓
   - "Colors" → "colors" → synonym → skip ✓
   - "Radius" → "radius" → known → skip ✓
   - "Type + Effects" → "type-effects" → unknown → still check first
     segment after collection (catches the user's Font-Size/Line-Height
     issues correctly)
   - "Primitives" → unknown → check first segment (preserves the
     standard tier-collection behavior)

5 new unit tests + 2 CLI integration tests covering PascalCase config
ignored for vars + collection-is-domain skip. 428/428 plugin-wide.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 .../lib/lint-engine/__tests__/cli.test.js     | 74 ++++++++++++++++++-
 .../__tests__/variable-namer.test.js          | 36 +++++++++
 plugins/adhd/lib/lint-engine/cli.js           | 11 ++-
 .../adhd/lib/lint-engine/variable-namer.js    | 30 +++++++-
 4 files changed, 144 insertions(+), 7 deletions(-)

diff --git a/plugins/adhd/lib/lint-engine/__tests__/cli.test.js b/plugins/adhd/lib/lint-engine/__tests__/cli.test.js
index 5f25e56..8363f61 100644
--- a/plugins/adhd/lib/lint-engine/__tests__/cli.test.js
+++ b/plugins/adhd/lib/lint-engine/__tests__/cli.test.js
@@ -201,8 +201,10 @@ test('STRUCT011: flags Figma variables whose names violate case OR Tailwind doma
   assert.equal(struct011.nodeId, '5:42');
   // Header counts ALL issues (1 case + 3 domain = 4).
   assert.match(struct011.message, /4 variable-naming issue\(s\)/);
-  // Case section
-  assert.match(struct011.message, /Case \(kebab-case\):/);
+  // Case section. The header explains kebab-case is a Tailwind v4 requirement
+  // (not the project's naming convention) — important since users may have
+  // PascalCase configured for components.
+  assert.match(struct011.message, /Case \(kebab-case — Tailwind v4 requires lowercase CSS vars\)/);
   assert.match(struct011.message, /Primitives\/color\/BrandPrimary +→ +Primitives\/color\/brand-primary/);
   // Domain section with all three "did you mean?" flavours
   assert.match(struct011.message, /Tailwind v4 domain:/);
@@ -213,6 +215,74 @@ test('STRUCT011: flags Figma variables whose names violate case OR Tailwind doma
   assert.doesNotMatch(struct011.message, /text\/default/);
 });
 
+test('STRUCT011: variable case is always kebab-case, regardless of project naming config', () => {
+  // The user's case: project config is `naming: "PascalCase"` (for COMPONENT
+  // identifiers like Logo vs logo). The rule must NOT apply PascalCase to
+  // variable names — CSS custom properties are kebab-lowercase by Tailwind
+  // v4 spec. So `Color/gold` should not be flagged as needing "Color/Gold".
+  const varDefs = tmp('vars.json', {
+    'Color/gold':      '#c5a572',    // kebab-ok (collection-is-domain, lowercase value)
+    'Color/BrandGold': '#c5a572',    // case violation → should suggest brand-gold, NOT BrandGold
+  });
+  const ctx = tmp('ctx.json', { id: '5:1', name: 'X', type: 'FRAME', layoutMode: 'VERTICAL' });
+  const cssPath = tmp('globals.css', `@theme {} :root {} :root[data-theme="dark"] {}`);
+  // PascalCase project — must be ignored for variable case checking.
+  const configPath = tmp('adhd.config.ts', `export default { naming: 'PascalCase' };`);
+  const reportPath = path.join(os.tmpdir(), 'adhd-report-' + Date.now() + '.md');
+
+  const result = spawnSync('node', [
+    CLI,
+    '--variable-defs', varDefs,
+    '--design-context', ctx,
+    '--globals-css', cssPath,
+    '--config', configPath,
+    '--target', 'X',
+    '--target-url', 'https://figma.com/design/abc?node-id=5-1',
+    '--output', reportPath,
+  ], { encoding: 'utf8' });
+
+  const summary = JSON.parse(result.stdout);
+  const struct011 = summary.structure.find(v => v.rule === 'STRUCT011');
+  assert.ok(struct011, 'expected STRUCT011 to flag BrandGold');
+  // Variable-case section advertises kebab-case (with the rationale), not PascalCase
+  assert.match(struct011.message, /Case \(kebab-case — Tailwind v4 requires lowercase CSS vars\)/);
+  // BrandGold suggestion is kebab, not PascalCase
+  assert.match(struct011.message, /Color\/BrandGold +→ +Color\/brand-gold/);
+  // Color/gold is NOT flagged (already kebab-compliant, even though "gold"
+  // would fail PascalCase if the config were honored).
+  assert.doesNotMatch(struct011.message, /Color\/gold +→/);
+});
+
+test('STRUCT011: collection-name-is-domain (Color/, Radius/, Spacing/) — no domain suggestion', () => {
+  // The user's "Radius/sm flagged as unknown domain" report. Fixed: when the
+  // collection name itself is a Tailwind domain, the variable name doesn't
+  // need another domain prefix.
+  const varDefs = tmp('vars.json', {
+    'Radius/sm':   '4px',
+    'Color/gold':  '#c5a572',
+    'Spacing/md':  '0.75rem',
+  });
+  const ctx = tmp('ctx.json', { id: '5:1', name: 'X', type: 'FRAME', layoutMode: 'VERTICAL' });
+  const cssPath = tmp('globals.css', `@theme {} :root {} :root[data-theme="dark"] {}`);
+  const configPath = tmp('adhd.config.ts', `export default { naming: 'kebab-case' };`);
+  const reportPath = path.join(os.tmpdir(), 'adhd-report-' + Date.now() + '.md');
+
+  const result = spawnSync('node', [
+    CLI,
+    '--variable-defs', varDefs,
+    '--design-context', ctx,
+    '--globals-css', cssPath,
+    '--config', configPath,
+    '--target', 'X',
+    '--target-url', 'https://figma.com/design/abc?node-id=5-1',
+    '--output', reportPath,
+  ], { encoding: 'utf8' });
+
+  const summary = JSON.parse(result.stdout);
+  // No STRUCT011 at all — all three vars are valid (collection IS the domain).
+  assert.equal(summary.structure.filter(v => v.rule === 'STRUCT011').length, 0);
+});
+
 test('STRUCT011: omits nodeId in whole-file mode (no scope root to annotate)', () => {
   const varDefs = tmp('vars.json', { 'Primitives/color/BrandPrimary': '#000' });
   const ctx = tmp('ctx.json', { mode: 'whole-file', pages: [] });
diff --git a/plugins/adhd/lib/lint-engine/__tests__/variable-namer.test.js b/plugins/adhd/lib/lint-engine/__tests__/variable-namer.test.js
index 93a9aea..153a4e9 100644
--- a/plugins/adhd/lib/lint-engine/__tests__/variable-namer.test.js
+++ b/plugins/adhd/lib/lint-engine/__tests__/variable-namer.test.js
@@ -140,6 +140,42 @@ test('checkVariableDomains: collection-only names (no slash) are skipped', () =>
   assert.deepEqual(checkVariableDomains(['Primitives']), []);
 });
 
+test('checkVariableDomains: collection name IS the domain — skip domain check on the var', () => {
+  // Some teams organize Figma collections by domain ("Color", "Radius", "Spacing")
+  // instead of by tier ("Primitives", "Semantic"). When the collection name
+  // itself matches a Tailwind domain, the variable name doesn't need another
+  // domain prefix. `Color/gold` and `Radius/sm` are valid.
+  const names = ['Color/gold', 'Radius/sm', 'Spacing/sm', 'Shadow/lg'];
+  assert.deepEqual(checkVariableDomains(names), []);
+});
+
+test('checkVariableDomains: collection synonym counts too (Colors/, Shadows/, Screens/)', () => {
+  // If the collection is named with a synonym (plural, alternate), accept it.
+  // Otherwise the rule would tell the designer to add ANOTHER "color" segment
+  // inside a `Colors` collection — busywork.
+  const names = ['Colors/gold', 'Shadows/sm', 'Screens/md'];
+  assert.deepEqual(checkVariableDomains(names), []);
+});
+
+test('checkVariableDomains: case- and whitespace-normalized collection match (Type + Effects is NOT a domain)', () => {
+  // "Type + Effects" → "type-effects" — doesn't match any domain. So the
+  // first segment after the collection still needs to be checked.
+  const names = ['Type + Effects/Font-Size/Body'];
+  const out = checkVariableDomains(names);
+  assert.equal(out.length, 1);
+  // "Font-Size" is a known synonym for "text"
+  assert.equal(out[0].classification.kind, 'synonym');
+  assert.equal(out[0].classification.suggestion, 'text');
+});
+
+test('normalizeCollectionName collapses separators and lowercases', () => {
+  const { normalizeCollectionName } = require('../variable-namer');
+  assert.equal(normalizeCollectionName('Color'), 'color');
+  assert.equal(normalizeCollectionName('Type + Effects'), 'type-effects');
+  assert.equal(normalizeCollectionName('Font Weight'), 'font-weight');
+  assert.equal(normalizeCollectionName('  Spacing  '), 'spacing');
+});
+
 test('caseMatchesSegment: kebab accepts lowercase+digits+hyphens, rejects uppercase', () => {
   assert.equal(caseMatchesSegment('brand-primary', 'kebab-case'), true);
   assert.equal(caseMatchesSegment('blue500', 'kebab-case'), true);
diff --git a/plugins/adhd/lib/lint-engine/cli.js b/plugins/adhd/lib/lint-engine/cli.js
index 2dca8a6..eda43cf 100644
--- a/plugins/adhd/lib/lint-engine/cli.js
+++ b/plugins/adhd/lib/lint-engine/cli.js
@@ -113,8 +113,15 @@ function main() {
   //     or typo correction via the "did you mean?" heuristic.
   // In whole-file mode there's no scope root, so we omit nodeId — the
   // violation still appears in the report but doesn't annotate.
+  // Variable names are ALWAYS checked against kebab-case, regardless of the
+  // project's `naming` config. That config is for component identifiers
+  // (`Logo` vs `logo`); CSS custom properties — what Figma variables ultimately
+  // become — are kebab-case-lowercase by Tailwind v4 spec. There's no honest
+  // way to honor `naming: "PascalCase"` for variables and still produce
+  // working utility classes.
+  const VARIABLE_CASE = 'kebab-case';
   const varKeys = Object.keys(varDefs || {});
-  const badCase = checkVariableNames(varKeys, namingConvention);
+  const badCase = checkVariableNames(varKeys, VARIABLE_CASE);
   const badDomain = checkVariableDomains(varKeys);
   if (badCase.length > 0 || badDomain.length > 0) {
     const isScoped = designCtx && designCtx.mode !== 'whole-file' && designCtx.id;
@@ -124,7 +131,7 @@ function main() {
       const shown = badCase.slice(0, 8);
       const lines = shown.map(v => `  • ${v.name}  →  ${v.suggestion}`);
       const more = badCase.length > 8 ? `\n  +${badCase.length - 8} more` : '';
-      sections.push(`Case (${namingConvention}):\n${lines.join('\n')}${more}`);
+      sections.push(`Case (kebab-case — Tailwind v4 requires lowercase CSS vars):\n${lines.join('\n')}${more}`);
     }
     if (badDomain.length > 0) {
       const shown = badDomain.slice(0, 8);
diff --git a/plugins/adhd/lib/lint-engine/variable-namer.js b/plugins/adhd/lib/lint-engine/variable-namer.js
index febb617..1c26b2c 100644
--- a/plugins/adhd/lib/lint-engine/variable-namer.js
+++ b/plugins/adhd/lib/lint-engine/variable-namer.js
@@ -177,15 +177,38 @@ function classifyDomain(segment) {
   return { kind: 'unknown' };
 }
 
+// Normalize a collection name for domain-matching: lowercase, collapse
+// separators (`+`, ` `, `-`, `_`) to `-`, drop the rest. "Color" → "color",
+// "Type + Effects" → "type-effects", "Radius" → "radius".
+function normalizeCollectionName(name) {
+  return name.toLowerCase()
+    .replace(/[\s+\-_]+/g, '-')
+    .replace(/[^a-z0-9-]/g, '')
+    .replace(/^-+|-+$/g, '');
+}
+
+// True when the collection name itself acts as the Tailwind domain — the
+// variable name within doesn't need another domain prefix. `Color/gold`,
+// `Radius/sm`, `Spacing/sm` are all valid. `Primitives/...` and
+// `Semantic/...` are not (they're not domain names).
+function collectionIsDomain(collection) {
+  const norm = normalizeCollectionName(collection);
+  const classification = classifyDomain(norm);
+  return classification.kind === 'known' || classification.kind === 'synonym';
+}
+
 // Returns an array of `{ name, domainSegment, classification }` for vars whose
 // post-collection first segment doesn't match a known Tailwind v4 domain.
-// Names with no path segments after the collection are skipped (nothing to
-// classify).
+// Skipped:
+//   - Names with no path segments after the collection (nothing to classify).
+//   - Names whose COLLECTION already names the domain (`Color/gold` ok —
+//     "gold" doesn't need its own domain prefix).
 function checkVariableDomains(varNames) {
   const out = [];
   for (const name of varNames) {
     const segments = name.split('/');
     if (segments.length <= 1) continue;
+    if (collectionIsDomain(segments[0])) continue;
     const domainSegment = segments[1]; // first segment AFTER collection
     const classification = classifyDomain(domainSegment);
     if (classification.kind !== 'known') {
@@ -197,5 +220,6 @@ function checkVariableDomains(varNames) {
 
 module.exports = {
   checkVariableNames, caseMatchesSegment, suggestName, toCase,
-  checkVariableDomains, classifyDomain, TAILWIND_DOMAINS,
+  checkVariableDomains, classifyDomain, collectionIsDomain,
+  normalizeCollectionName, TAILWIND_DOMAINS,
 };

From 5fbf4a68bd7469e858573b2571923d998ca1c664 Mon Sep 17 00:00:00 2001
From: Hugh Francis <hughfrancis89@gmail.com>
Date: Mon, 11 May 2026 23:20:29 -0400
Subject: [PATCH 44/79] =?UTF-8?q?pull-component:=20Phase=202.7=20=E2=80=94?=
 =?UTF-8?q?=20opportunistic=20variable=20discovery?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

After preflight passes, scan the lint engine's variable mismatches for
NEW Figma variables that aren't in the consumer's globals.css yet.
Offer to add them additively as part of the pull, so users discover the
design system incrementally as they pull components in.

Three categories surfaced in a single prompt:

  Primitives (mode: undefined): auto-addable. Single @theme entry per
    variable. Yes-branch invokes applyToCss (the same helper
    pull-design-system uses for CSS edits) with set-primitive actions.

  Semantic tokens with light/dark modes: NOT auto-addable. They need
    three coordinated edits (:root, .dark, @theme inline). Surfaced in
    the prompt with a "run /adhd:pull-design-system" note instead.

  Value conflicts: not touched here at all. pull-design-system's
    interactive resolution is the right tool. Surfaced in the prompt for
    awareness; doesn't block the pull (conflicts are an existing
    not-a-blocker class for pull-component).

UX decisions per user:
- Always prompt with the list (no silent auto-add)
- Warn about conflicts in the same prompt, allow continuing

Three options on the prompt:
  Yes — add primitives and continue
  No  — continue without adding (component pull may land raw values)
  Cancel — abort, run /adhd:pull-design-system first

The phase is skipped entirely when there are zero new variables AND zero
conflicts.

SKILL-only change. The applyToCss helper already exists in
lib/design-system/code-writer.js (pull-design-system uses it); we just
invoke it from a node -e snippet with new set-primitive actions.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 plugins/adhd/skills/pull-component/SKILL.md | 65 +++++++++++++++++++++
 1 file changed, 65 insertions(+)

diff --git a/plugins/adhd/skills/pull-component/SKILL.md b/plugins/adhd/skills/pull-component/SKILL.md
index 76dcf2c..c0b7c4d 100644
--- a/plugins/adhd/skills/pull-component/SKILL.md
+++ b/plugins/adhd/skills/pull-component/SKILL.md
@@ -183,6 +183,71 @@ would land in your code's lookup tables and drift on the next push.
 
 If BOTH STRUCT011 AND variable-binding errors are present, surface STRUCT011 first (it's the more fundamental fix — bind-errors might be tolerable with `--allow-unbound`, but bad names always need fixing first).
 
+## Phase 2.7: Opportunistic variable discovery
+
+Once preflight passes (no STRUCT011, no unbound errors or escape engaged), check the lint engine's variable mismatches in `/tmp/adhd-pull-component/stdout.json`. The categorizer reports two interesting statuses for our purpose:
+
+- **`status: "missing"`** — Figma has the variable, code's `globals.css` doesn't. New to the design system.
+- **`status: "conflict"`** — both sides have the variable but values disagree. NOT touched by pull-component; this is `/adhd:pull-design-system`'s job.
+
+Split missing further by the categorizer's `mode` field:
+
+- `mode === undefined` → **primitive**. Auto-addable: a single `@theme` entry.
+- `mode === "light" | "dark"` → **semantic with modes**. Needs coordinated `:root`, `.dark`, and `@theme inline` edits — too much surface to do as a side-effect of pull-component. Surfaced in the prompt with a "run /adhd:pull-design-system for these" note.
+
+If `missingPrimitives.length === 0 && missingSemantics.length === 0 && conflicts.length === 0`, skip this phase entirely.
+
+Otherwise, build a single `AskUserQuestion` prompt:
+
+```
+Found new variables referenced by this frame:
+
+Primitives (add to @theme):
+  color/brand/600     #5e3aee
+  radius/lg           12px
+  shadow/popover      0 4px 12px rgba(0,0,0,.08)
+
+[if missingSemantics > 0]
+Semantic tokens with light/dark modes (not auto-addable):
+  color/text/primary  (light: #111, dark: #fafafa)
+  color/surface       (light: #fff, dark: #0a0a0a)
+Run /adhd:pull-design-system to add these — they need coordinated
+`:root`, `.dark`, and `@theme inline` edits.
+
+[if conflicts > 0]
+Variables with value mismatches (existing in code, different in Figma):
+  color/brand/500     code=#5e3aee  figma=#6a4cf2
+Run /adhd:pull-design-system to resolve.
+
+Options:
+  [Yes — add the <N> primitives and continue]
+  [No — continue without adding (component pull may land raw values)]
+  [Cancel — abort, I'll run /adhd:pull-design-system first]
+```
+
+On **Yes**: build an actions array for each primitive and invoke `applyToCss` (the helper `pull-design-system` already uses for CSS edits). Save under `/tmp/adhd-pull-component/new-globals.css`, then write to the configured `globals.css` path:
+
+```bash
+node -e '
+  const fs = require("fs");
+  const { applyToCss } = require("plugins/adhd/lib/design-system/code-writer.js");
+  const cssPath = process.argv[1];
+  const css = fs.readFileSync(cssPath, "utf8");
+  const actions = JSON.parse(process.argv[2]);
+  fs.writeFileSync(cssPath, applyToCss(css, actions));
+' "<globals.css path>" "$ACTIONS_JSON"
+```
+
+Where each action is shaped `{ kind: "set-primitive", cssVar: "--" + token.replace(/\//g, "-"), value: <figma-value> }`. The token comes from each missing entry's `token` field (already collection-stripped).
+
+Print a confirmation: `Added <N> primitive(s) to globals.css: <comma-separated list>`. Then continue with Phase 3.
+
+On **No**: continue without writing. The component pull proceeds; un-tracked variables may land as raw values or `// adhd:off-system` markers in the lookup tables.
+
+On **Cancel**: abort with `Run /adhd:pull-design-system first to sync the design system, then re-run /adhd:pull-component.`
+
+Skip this phase if conflicts exist BUT no missing — there's nothing additive to do, just print: `Note: <N> variable value(s) differ between Figma and code. Run /adhd:pull-design-system to reconcile.` Then continue (conflicts don't block pull-component v1; the pull works with code's value, drift is reported in the final report).
+
 ## Phase 3: Read both sides
 
 **React side (update mode only):** use `Read` on `<react-path>` (from Phase 2). Identify:

From ee8bcd863f64659179066ca9226d954ae4274c0c Mon Sep 17 00:00:00 2001
From: Hugh Francis <hughfrancis89@gmail.com>
Date: Mon, 11 May 2026 23:25:55 -0400
Subject: [PATCH 45/79] lint STRUCT011: one concrete rename target per variable
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

User screenshot from their reactor file showed the previous emission
was unactionable:

  Type + Effects/Font-Size/Body  →  Type + Effects/font-size/body
  (case half)
  Type + Effects/Font-Size/Body  —  did you mean "text"?
  (domain half)

Two contradictory hints on the same variable. Following the case fix
produced a name that still failed the domain check; following the
domain hint required structural change the case fix didn't account
for. Designers were stuck reconciling them on their own.

Replaced the two-section emission with a single-target-per-variable
format produced by a new suggestTargetName() helper. The helper picks
ONE end-state name that satisfies both concerns at once.

Algorithm (priority order):

  1. Tier collection (Primitives/Semantic/Tokens/Base/Theme) — preserve
     the tier, kebab-case the leaves, normalize the domain segment
     inside (synonyms → canonical). Tier + unrecognized inner segment
     surfaces a no-mapping hint instead of guessing.

  2. Domain-named collection (Color/Radius/Spacing/…) — preserve the
     collection, kebab-case the leaves. Synonym collections (Colors,
     Shadows) get renormalized to the canonical name.

  3. Bundled / unknown collection — walk rest segments looking for a
     domain hint. If found, MOVE the variable to a dedicated
     domain-named collection in PascalCase form:
       Type + Effects/Font-Size/Body  →  Text/body
       Type + Effects/Line-Height/Line Height 28  →  Leading/line-height-28
     The domain-naming segment in the original path is dropped (the
     new collection name supplies it).

  4. No domain hint anywhere → no-mapping with the canonical list,
     including a "consider whether this variable belongs or should be
     removed" hint.

Sample new annotation body for the user's case:

  5 variable(s) need renaming for Tailwind v4 alignment:

    • Type + Effects/Font-Size/Body
        → Text/body

    • Type + Effects/Line-Height/Line Height 28
        → Leading/line-height-28

    • Type + Effects/Effects/Opacity 100%
        ⚠ No Tailwind v4 domain found in path. Expected one of:
          color, spacing, text, font, font-weight, tracking, leading,
          radius, shadow, breakpoint, ease, animate. Consider whether
          this variable maps to one of those domains, or if it should
          be removed.

    • Primitives/color/BrandPrimary
        → Primitives/color/brand-primary

7 new unit tests + 2 CLI integration tests rewritten for the new
format. 435/435 plugin-wide.

The old checkVariableNames + checkVariableDomains exports stay for
backwards compatibility but are no longer used by cli.js. Both still
have their unit tests, so any future regression there is caught.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 .../lib/lint-engine/__tests__/cli.test.js     |  97 +++++++----------
 .../__tests__/variable-namer.test.js          |  76 +++++++++++++
 plugins/adhd/lib/lint-engine/cli.js           |  72 +++++-------
 .../adhd/lib/lint-engine/variable-namer.js    | 103 ++++++++++++++++++
 4 files changed, 249 insertions(+), 99 deletions(-)

diff --git a/plugins/adhd/lib/lint-engine/__tests__/cli.test.js b/plugins/adhd/lib/lint-engine/__tests__/cli.test.js
index 8363f61..f9f2df3 100644
--- a/plugins/adhd/lib/lint-engine/__tests__/cli.test.js
+++ b/plugins/adhd/lib/lint-engine/__tests__/cli.test.js
@@ -166,91 +166,74 @@ test('cli with structure errors but no variable issues exits 1', () => {
   assert.ok(summary.errors >= 1);
 });
 
-test('STRUCT011: flags Figma variables whose names violate case OR Tailwind domain expectations', () => {
-  // Mix of three issue types in one frame — STRUCT011 aggregates them into a
-  // single annotation with separate "Case" and "Tailwind v4 domain" sections.
+test('STRUCT011: emits one concrete rename target per variable (mixed case + domain issues)', () => {
+  // Real-world scenario from the user's reactor file: a bundled "Type +
+  // Effects" collection that conflates typography sizes, line-heights, and
+  // effects. Each variable gets a single target, not two contradictory
+  // hints. The designer can act on each line independently.
   const varDefs = tmp('vars.json', {
-    'Primitives/color/BrandPrimary': '#000',       // case violation (kebab-case project)
-    'Primitives/colur/brand-500':    '#111',       // domain typo (Levenshtein)
-    'Primitives/space/sm':           '0.5rem',     // domain synonym
-    'Primitives/widget/foo':         '?',          // unknown domain
-    'Primitives/color/text/default': '#222',       // compliant — shouldn't appear
-  });
-  const ctx = tmp('ctx.json', {
-    id: '5:42', name: 'Logo', type: 'FRAME', layoutMode: 'VERTICAL',
+    'Type + Effects/Font-Size/Body':           '16px',
+    'Type + Effects/Line-Height/Line Height 28': '28px',
+    'Type + Effects/Effects/Opacity 100%':     '1',     // no Tailwind v4 mapping
+    'Primitives/color/BrandPrimary':           '#000',  // tier-mode case fix
+    'Color/gold':                              '#c5a572', // already correct
   });
+  const ctx = tmp('ctx.json', { id: '5:42', name: 'Logo', type: 'FRAME', layoutMode: 'VERTICAL' });
   const cssPath = tmp('globals.css', `@theme {} :root {} :root[data-theme="dark"] {}`);
   const configPath = tmp('adhd.config.ts', `export default { naming: 'kebab-case' };`);
   const reportPath = path.join(os.tmpdir(), 'adhd-report-' + Date.now() + '.md');
 
   const result = spawnSync('node', [
-    CLI,
-    '--variable-defs', varDefs,
-    '--design-context', ctx,
-    '--globals-css', cssPath,
-    '--config', configPath,
-    '--target', 'Logo',
-    '--target-url', 'https://figma.com/design/abc?node-id=5-42',
-    '--output', reportPath,
+    CLI, '--variable-defs', varDefs, '--design-context', ctx, '--globals-css', cssPath,
+    '--config', configPath, '--target', 'Logo',
+    '--target-url', 'https://figma.com/design/abc?node-id=5-42', '--output', reportPath,
   ], { encoding: 'utf8' });
 
   const summary = JSON.parse(result.stdout);
   const struct011 = summary.structure.find(v => v.rule === 'STRUCT011');
-  assert.ok(struct011, 'expected a STRUCT011 violation');
+  assert.ok(struct011);
   assert.equal(struct011.severity, 'warning');
   assert.equal(struct011.nodeId, '5:42');
-  // Header counts ALL issues (1 case + 3 domain = 4).
-  assert.match(struct011.message, /4 variable-naming issue\(s\)/);
-  // Case section. The header explains kebab-case is a Tailwind v4 requirement
-  // (not the project's naming convention) — important since users may have
-  // PascalCase configured for components.
-  assert.match(struct011.message, /Case \(kebab-case — Tailwind v4 requires lowercase CSS vars\)/);
-  assert.match(struct011.message, /Primitives\/color\/BrandPrimary +→ +Primitives\/color\/brand-primary/);
-  // Domain section with all three "did you mean?" flavours
-  assert.match(struct011.message, /Tailwind v4 domain:/);
-  assert.match(struct011.message, /Primitives\/colur\/brand-500.*did you mean "color".*typo/);
-  assert.match(struct011.message, /Primitives\/space\/sm.*did you mean "spacing".*Tailwind v4 prefix/);
-  assert.match(struct011.message, /Primitives\/widget\/foo.*unknown domain "widget".*expected one of: color, spacing/);
-  // Compliant variable is NOT listed.
-  assert.doesNotMatch(struct011.message, /text\/default/);
+  // Header counts ALL issues (4 — Color/gold is compliant and doesn't appear).
+  assert.match(struct011.message, /4 variable\(s\) need renaming for Tailwind v4 alignment/);
+  // Unknown-collection + domain-segment-hint → MOVE into domain-named collection
+  assert.match(struct011.message, /Type \+ Effects\/Font-Size\/Body[\s\S]*→ Text\/body/);
+  assert.match(struct011.message, /Type \+ Effects\/Line-Height\/Line Height 28[\s\S]*→ Leading\/line-height-28/);
+  // Tier collection + case-only issue → preserve tier, kebab the leaf
+  assert.match(struct011.message, /Primitives\/color\/BrandPrimary[\s\S]*→ Primitives\/color\/brand-primary/);
+  // Domain-less variable → no-mapping explanation
+  assert.match(struct011.message, /Type \+ Effects\/Effects\/Opacity 100%[\s\S]*⚠ No Tailwind v4 domain/);
+  // Already-correct variable doesn't appear
+  assert.doesNotMatch(struct011.message, /Color\/gold/);
+  // No leftover from the old format
+  assert.doesNotMatch(struct011.message, /Case \(kebab-case/);
+  assert.doesNotMatch(struct011.message, /did you mean/);
 });
 
 test('STRUCT011: variable case is always kebab-case, regardless of project naming config', () => {
-  // The user's case: project config is `naming: "PascalCase"` (for COMPONENT
-  // identifiers like Logo vs logo). The rule must NOT apply PascalCase to
-  // variable names — CSS custom properties are kebab-lowercase by Tailwind
-  // v4 spec. So `Color/gold` should not be flagged as needing "Color/Gold".
+  // PascalCase project config (for components) doesn't bleed into variable
+  // naming. `Color/BrandGold` still gets renamed to `Color/brand-gold`.
   const varDefs = tmp('vars.json', {
-    'Color/gold':      '#c5a572',    // kebab-ok (collection-is-domain, lowercase value)
-    'Color/BrandGold': '#c5a572',    // case violation → should suggest brand-gold, NOT BrandGold
+    'Color/gold':      '#c5a572',
+    'Color/BrandGold': '#c5a572',
   });
   const ctx = tmp('ctx.json', { id: '5:1', name: 'X', type: 'FRAME', layoutMode: 'VERTICAL' });
   const cssPath = tmp('globals.css', `@theme {} :root {} :root[data-theme="dark"] {}`);
-  // PascalCase project — must be ignored for variable case checking.
   const configPath = tmp('adhd.config.ts', `export default { naming: 'PascalCase' };`);
   const reportPath = path.join(os.tmpdir(), 'adhd-report-' + Date.now() + '.md');
 
   const result = spawnSync('node', [
-    CLI,
-    '--variable-defs', varDefs,
-    '--design-context', ctx,
-    '--globals-css', cssPath,
-    '--config', configPath,
-    '--target', 'X',
-    '--target-url', 'https://figma.com/design/abc?node-id=5-1',
-    '--output', reportPath,
+    CLI, '--variable-defs', varDefs, '--design-context', ctx, '--globals-css', cssPath,
+    '--config', configPath, '--target', 'X',
+    '--target-url', 'https://figma.com/design/abc?node-id=5-1', '--output', reportPath,
   ], { encoding: 'utf8' });
 
   const summary = JSON.parse(result.stdout);
   const struct011 = summary.structure.find(v => v.rule === 'STRUCT011');
-  assert.ok(struct011, 'expected STRUCT011 to flag BrandGold');
-  // Variable-case section advertises kebab-case (with the rationale), not PascalCase
-  assert.match(struct011.message, /Case \(kebab-case — Tailwind v4 requires lowercase CSS vars\)/);
-  // BrandGold suggestion is kebab, not PascalCase
-  assert.match(struct011.message, /Color\/BrandGold +→ +Color\/brand-gold/);
-  // Color/gold is NOT flagged (already kebab-compliant, even though "gold"
-  // would fail PascalCase if the config were honored).
-  assert.doesNotMatch(struct011.message, /Color\/gold +→/);
+  assert.ok(struct011);
+  assert.match(struct011.message, /Color\/BrandGold[\s\S]*→ Color\/brand-gold/);
+  // Color/gold is compliant; doesn't appear
+  assert.doesNotMatch(struct011.message, /Color\/gold[\s\S]*→/);
 });
 
 test('STRUCT011: collection-name-is-domain (Color/, Radius/, Spacing/) — no domain suggestion', () => {
diff --git a/plugins/adhd/lib/lint-engine/__tests__/variable-namer.test.js b/plugins/adhd/lib/lint-engine/__tests__/variable-namer.test.js
index 153a4e9..7ce075f 100644
--- a/plugins/adhd/lib/lint-engine/__tests__/variable-namer.test.js
+++ b/plugins/adhd/lib/lint-engine/__tests__/variable-namer.test.js
@@ -176,6 +176,82 @@ test('normalizeCollectionName collapses separators and lowercases', () => {
   assert.equal(normalizeCollectionName('  Spacing  '), 'spacing');
 });
 
+// ---------------------------------------------------------------------------
+// suggestTargetName — actionable per-variable rename targets
+
+const { suggestTargetName } = require('../variable-namer');
+
+test('suggestTargetName: tier collection (Primitives/Semantic) preserves the tier', () => {
+  // The standard two-tier organization. Internal domain segments and leaves
+  // get kebab-cased; the tier itself stays.
+  assert.deepEqual(suggestTargetName('Primitives/color/BrandPrimary'), {
+    name: 'Primitives/color/BrandPrimary', kind: 'rename', target: 'Primitives/color/brand-primary',
+  });
+  assert.deepEqual(suggestTargetName('Primitives/color/brand-500'), {
+    name: 'Primitives/color/brand-500', kind: 'ok',
+  });
+});
+
+test('suggestTargetName: tier collection with unrecognized inner domain → no-mapping', () => {
+  // Tier is fine, but "widget" inside isn't a Tailwind domain — can't auto-rename safely.
+  const r = suggestTargetName('Primitives/widget/foo');
+  assert.equal(r.kind, 'no-mapping');
+  assert.match(r.reason, /Inside the "Primitives" tier, the segment "widget" doesn't match any Tailwind v4 domain/);
+});
+
+test('suggestTargetName: domain-named collection (Color/gold) preserves collection', () => {
+  // Some teams organize by domain at the collection level. No need to inject
+  // a redundant "color" segment.
+  assert.deepEqual(suggestTargetName('Color/gold'), { name: 'Color/gold', kind: 'ok' });
+  assert.deepEqual(suggestTargetName('Radius/sm'), { name: 'Radius/sm', kind: 'ok' });
+  // Case-fix the leaf in this mode too.
+  assert.deepEqual(suggestTargetName('Color/BrandGold'), {
+    name: 'Color/BrandGold', kind: 'rename', target: 'Color/brand-gold',
+  });
+});
+
+test('suggestTargetName: synonym-collection rewrites to canonical Tailwind name', () => {
+  // A collection named "Colors" or "Shadows" gets renormalized to the
+  // canonical domain (Color, Shadow).
+  assert.deepEqual(suggestTargetName('Colors/gold'), {
+    name: 'Colors/gold', kind: 'rename', target: 'Color/gold',
+  });
+  assert.deepEqual(suggestTargetName('Shadows/sm'), {
+    name: 'Shadows/sm', kind: 'rename', target: 'Shadow/sm',
+  });
+});
+
+test('suggestTargetName: bundled collection with domain hint in rest → MOVE to domain collection', () => {
+  // The user's "Type + Effects" case. The engine detects that one of the
+  // inner segments hints at a domain ("Font-Size" → text, "Line-Height" →
+  // leading) and suggests moving the variable to a dedicated collection.
+  // The redundant domain-naming segment is dropped from the path.
+  assert.deepEqual(suggestTargetName('Type + Effects/Font-Size/Body'), {
+    name: 'Type + Effects/Font-Size/Body', kind: 'rename', target: 'Text/body',
+  });
+  assert.deepEqual(suggestTargetName('Type + Effects/Font-Size/Body LG'), {
+    name: 'Type + Effects/Font-Size/Body LG', kind: 'rename', target: 'Text/body-lg',
+  });
+  assert.deepEqual(suggestTargetName('Type + Effects/Line-Height/Line Height 28'), {
+    name: 'Type + Effects/Line-Height/Line Height 28', kind: 'rename', target: 'Leading/line-height-28',
+  });
+});
+
+test('suggestTargetName: bundled collection with no domain hint anywhere → no-mapping', () => {
+  // "Type + Effects/Effects/Opacity 100%" — none of "Type+Effects", "Effects",
+  // or "Opacity 100%" maps to a Tailwind v4 domain. The engine surfaces the
+  // canonical list so the designer picks a destination.
+  const r = suggestTargetName('Type + Effects/Effects/Opacity 100%');
+  assert.equal(r.kind, 'no-mapping');
+  assert.match(r.reason, /No Tailwind v4 domain found in path/);
+  assert.match(r.reason, /Expected one of: color, spacing, text/);
+});
+
+test('suggestTargetName: top-level vars without collection are ok by default', () => {
+  // Can't classify without a path; leave alone.
+  assert.deepEqual(suggestTargetName('spacing'), { name: 'spacing', kind: 'ok' });
+});
+
 test('caseMatchesSegment: kebab accepts lowercase+digits+hyphens, rejects uppercase', () => {
   assert.equal(caseMatchesSegment('brand-primary', 'kebab-case'), true);
   assert.equal(caseMatchesSegment('blue500', 'kebab-case'), true);
diff --git a/plugins/adhd/lib/lint-engine/cli.js b/plugins/adhd/lib/lint-engine/cli.js
index eda43cf..172b5f7 100644
--- a/plugins/adhd/lib/lint-engine/cli.js
+++ b/plugins/adhd/lib/lint-engine/cli.js
@@ -21,7 +21,7 @@ const fs = require('node:fs');
 const { parseTheme } = require('./theme-parser');
 const { categorizeVariables } = require('./variable-categorizer');
 const { checkStructure } = require('./structure-checker');
-const { checkVariableNames, checkVariableDomains, TAILWIND_DOMAINS } = require('./variable-namer');
+const { buildVariableSuggestions } = require('./variable-namer');
 const { formatReport } = require('./report-formatter');
 
 function parseArgs(argv) {
@@ -103,57 +103,45 @@ function main() {
     structureViolations = checkStructure(designCtx, { fileKey, namingConvention });
   }
 
-  // STRUCT011 — variable-name compliance. Combines TWO concerns into one
-  // aggregated violation so the designer sees a single "fix your variable
-  // names" block per lint run:
-  //   - Case: name doesn't follow the project's namingConvention
-  //     (kebab/Pascal/camel).
-  //   - Domain: first segment after the collection doesn't map to a Tailwind v4
-  //     token-domain prefix (color/spacing/text/font/etc.). Suggests a synonym
-  //     or typo correction via the "did you mean?" heuristic.
-  // In whole-file mode there's no scope root, so we omit nodeId — the
+  // STRUCT011 — variable-name compliance. For each variable, produce ONE
+  // concrete rename target that combines case + domain concerns into a
+  // single actionable suggestion. This is the upgrade from the old
+  // two-section emission, which forced designers to reconcile contradictory
+  // hints ("rename Font-Size to font-size" + "did you mean text?") on
+  // their own — too much cognitive load when 10+ variables are flagged.
+  //
+  // The new emission shows: "Type + Effects/Font-Size/Body → Text/body".
+  // One line, complete target. The designer creates the new variable in
+  // the right collection (or renames in place) and moves on.
+  //
+  // Variable names are ALWAYS checked against kebab-case for the leaves,
+  // regardless of the project's `naming` config (which is for component
+  // identifiers, not CSS custom properties).
+  //
+  // In whole-file mode there's no scope root, so nodeId is omitted —
   // violation still appears in the report but doesn't annotate.
-  // Variable names are ALWAYS checked against kebab-case, regardless of the
-  // project's `naming` config. That config is for component identifiers
-  // (`Logo` vs `logo`); CSS custom properties — what Figma variables ultimately
-  // become — are kebab-case-lowercase by Tailwind v4 spec. There's no honest
-  // way to honor `naming: "PascalCase"` for variables and still produce
-  // working utility classes.
-  const VARIABLE_CASE = 'kebab-case';
   const varKeys = Object.keys(varDefs || {});
-  const badCase = checkVariableNames(varKeys, VARIABLE_CASE);
-  const badDomain = checkVariableDomains(varKeys);
-  if (badCase.length > 0 || badDomain.length > 0) {
+  const suggestions = buildVariableSuggestions(varKeys);
+  if (suggestions.length > 0) {
     const isScoped = designCtx && designCtx.mode !== 'whole-file' && designCtx.id;
     const scopedNodeId = isScoped ? designCtx.id : undefined;
-    const sections = [];
-    if (badCase.length > 0) {
-      const shown = badCase.slice(0, 8);
-      const lines = shown.map(v => `  • ${v.name}  →  ${v.suggestion}`);
-      const more = badCase.length > 8 ? `\n  +${badCase.length - 8} more` : '';
-      sections.push(`Case (kebab-case — Tailwind v4 requires lowercase CSS vars):\n${lines.join('\n')}${more}`);
-    }
-    if (badDomain.length > 0) {
-      const shown = badDomain.slice(0, 8);
-      const lines = shown.map(v => {
-        const c = v.classification;
-        if (c.kind === 'synonym') return `  • ${v.name}  —  did you mean "${c.suggestion}"? (Tailwind v4 prefix)`;
-        if (c.kind === 'typo')    return `  • ${v.name}  —  did you mean "${c.suggestion}"? (looks like a typo)`;
-        return `  • ${v.name}  —  unknown domain "${v.domainSegment}"; expected one of: ${TAILWIND_DOMAINS.join(', ')}`;
-      });
-      const more = badDomain.length > 8 ? `\n  +${badDomain.length - 8} more` : '';
-      sections.push(`Tailwind v4 domain:\n${lines.join('\n')}${more}`);
-    }
-    const total = badCase.length + badDomain.length;
+    const shown = suggestions.slice(0, 10);
+    const lines = shown.map(s => {
+      if (s.kind === 'rename') return `  • ${s.name}\n      → ${s.target}`;
+      if (s.kind === 'no-mapping') return `  • ${s.name}\n      ⚠ ${s.reason}`;
+      return `  • ${s.name}`;
+    });
+    const more = suggestions.length > 10 ? `\n\n  +${suggestions.length - 10} more` : '';
     structureViolations.push({
       rule: 'STRUCT011',
       severity: 'warning',
       nodeId: scopedNodeId,
       nodePath: 'Variables',
       message:
-        `${total} variable-naming issue(s):\n` +
-        `${sections.join('\n\n')}\n\n` +
-        `Rename them in Figma (right-click the variable → "Rename") to match.`,
+        `${suggestions.length} variable(s) need renaming for Tailwind v4 alignment:\n\n` +
+        `${lines.join('\n\n')}${more}\n\n` +
+        `For each rename: right-click the variable in Figma → "Rename".\n` +
+        `Tip: you can also create the variable in the suggested collection and point old references at it via aliasing.`,
       deepLink: scopedNodeId
         ? 'https://figma.com/design/' + fileKey + '?node-id=' + scopedNodeId.replace(':', '-')
         : args['target-url'],
diff --git a/plugins/adhd/lib/lint-engine/variable-namer.js b/plugins/adhd/lib/lint-engine/variable-namer.js
index 1c26b2c..36ece5f 100644
--- a/plugins/adhd/lib/lint-engine/variable-namer.js
+++ b/plugins/adhd/lib/lint-engine/variable-namer.js
@@ -218,8 +218,111 @@ function checkVariableDomains(varNames) {
   return out;
 }
 
+// ---------------------------------------------------------------------------
+// Canonical target builder — gives each variable a SINGLE concrete rename
+// target that combines the case + domain concerns. This is what
+// `cli.js` emits in STRUCT011 messages: actionable end-state names, not
+// per-segment hints.
+//
+// Three classes of result:
+//   - `ok`         — name is already in the right shape; nothing to do.
+//   - `rename`     — produced a single target; designer renames to that.
+//   - `no-mapping` — no Tailwind v4 domain detected anywhere in the path,
+//                    AND the collection isn't a recognized tier. Surface
+//                    the canonical list so the designer picks one.
+//
+// Conventions assumed:
+//   - "Primitives" / "Semantic" / "Tokens" / "Base" / "Theme" are TIER
+//     collections — they bundle multiple domains by design, so the
+//     internal structure should follow `<Tier>/<Domain>/<...>`. Renames
+//     preserve the tier and just fix case + ensure the domain segment is
+//     canonical.
+//   - Otherwise, when the collection name itself is a Tailwind domain
+//     (Color, Radius, Spacing, …), it's preserved.
+//   - When the collection is unrecognized AND a rest segment names a
+//     domain, the suggestion MOVES the variable into a domain-named
+//     collection — e.g. "Type + Effects/Font-Size/Body" → "Text/body".
+
+const TIER_COLLECTIONS = new Set([
+  'primitives', 'semantic', 'tokens', 'base', 'theme',
+]);
+
+function titleCaseDomain(d) {
+  return d.split('-').map(w => w ? w[0].toUpperCase() + w.slice(1) : w).join('');
+}
+
+function suggestTargetName(name) {
+  const segments = name.split('/');
+  if (segments.length < 2) return { name, kind: 'ok' };
+
+  const collection = segments[0];
+  const rest = segments.slice(1);
+  const collNorm = normalizeCollectionName(collection);
+
+  // (1) Collection is a TIER (Primitives, Semantic, …). Preserve tier,
+  // ensure the first rest segment is a canonical domain, kebab the leaves.
+  if (TIER_COLLECTIONS.has(collNorm)) {
+    const firstRestClass = classifyDomain(rest[0]);
+    let normalizedRest = [...rest];
+    if (firstRestClass.kind === 'synonym') {
+      normalizedRest[0] = firstRestClass.suggestion;
+    } else if (firstRestClass.kind === 'typo' || firstRestClass.kind === 'unknown') {
+      // Tier + unrecognized inner: can't auto-rename safely. Hint the user.
+      return {
+        name, kind: 'no-mapping',
+        reason: `Inside the "${collection}" tier, the segment "${rest[0]}" doesn't match any Tailwind v4 domain (color, spacing, text, font, font-weight, tracking, leading, radius, shadow, breakpoint, ease, animate).`,
+      };
+    }
+    const kebabRest = normalizedRest.map(s => toCase(s, 'kebab-case')).filter(Boolean).join('/');
+    const target = kebabRest ? `${collection}/${kebabRest}` : collection;
+    return target === name ? { name, kind: 'ok' } : { name, kind: 'rename', target };
+  }
+
+  // (2) Collection IS a Tailwind domain or its synonym. Preserve the
+  // collection name verbatim (designer's casing choice) and kebab-case the
+  // rest. A canonical "synonym" rename still suggests the canonical form.
+  const collectionClass = classifyDomain(collNorm);
+  if (collectionClass.kind === 'known' || collectionClass.kind === 'synonym') {
+    const canonicalCollection = collectionClass.kind === 'synonym'
+      ? titleCaseDomain(collectionClass.suggestion)
+      : collection;
+    const kebabRest = rest.map(s => toCase(s, 'kebab-case')).filter(Boolean).join('/');
+    const target = kebabRest ? `${canonicalCollection}/${kebabRest}` : canonicalCollection;
+    return target === name ? { name, kind: 'ok' } : { name, kind: 'rename', target };
+  }
+
+  // (3) Unknown collection. Walk rest looking for a domain hint. If found,
+  // suggest MOVING the variable to a domain-named collection.
+  let targetDomain = null;
+  let domainIndex = -1;
+  for (let i = 0; i < rest.length; i++) {
+    const c = classifyDomain(rest[i]);
+    if (c.kind === 'known' || c.kind === 'synonym') {
+      targetDomain = c.kind === 'known' ? rest[i].toLowerCase() : c.suggestion;
+      domainIndex = i;
+      break;
+    }
+  }
+  if (!targetDomain) {
+    return {
+      name, kind: 'no-mapping',
+      reason: `No Tailwind v4 domain found in path. Expected one of: ${TAILWIND_DOMAINS.join(', ')}. Consider whether this variable maps to one of those domains, or if it should be removed.`,
+    };
+  }
+  const collectionTitle = titleCaseDomain(targetDomain);
+  const kept = rest.filter((_, i) => i !== domainIndex);
+  const kebabRest = kept.map(s => toCase(s, 'kebab-case')).filter(Boolean).join('/');
+  const target = kebabRest ? `${collectionTitle}/${kebabRest}` : collectionTitle;
+  return { name, kind: 'rename', target };
+}
+
+function buildVariableSuggestions(varNames) {
+  return varNames.map(suggestTargetName).filter(s => s.kind !== 'ok');
+}
+
 module.exports = {
   checkVariableNames, caseMatchesSegment, suggestName, toCase,
   checkVariableDomains, classifyDomain, collectionIsDomain,
   normalizeCollectionName, TAILWIND_DOMAINS,
+  suggestTargetName, buildVariableSuggestions, TIER_COLLECTIONS,
 };

From ff63be75e84c736026e1ccd7412653fbab97a531 Mon Sep 17 00:00:00 2001
From: Hugh Francis <hughfrancis89@gmail.com>
Date: Mon, 11 May 2026 23:29:34 -0400
Subject: [PATCH 46/79] lint annotate: scope-aware cleanup so scoped lints
 don't wipe other frames
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Real bug surfaced in a session: a scoped lint on UserAvatar wiped a
previously-annotated STRUCT010 on Logotype, even though Logotype wasn't
in this run's violation set. The annotation script was walking the
WHOLE file for stale-annotation cleanup regardless of whether the lint
was scoped.

Fixed by injecting a SCOPE_ROOT_ID into the script:
  - null  → whole-file lint, walk every page (current behavior preserved)
  - <id>  → scoped lint, walk only that subtree (root + descendants)

A scoped lint now affects ONLY annotations within its scope. Annotations
on unrelated frames are left alone — which matches the user's mental
model: "I'm linting UserAvatar, so don't touch annotations on Logotype."

Cross-skill plumbing:
  - lint SKILL Phase 2 already resolves the scoped target's nodeId;
    pass it as SCOPE_ROOT_ID, null for whole-file mode.
  - push-component Phase 10.5: pass the freshly-pushed Component Set's
    nodeId (componentSetId from Phase 9).
  - pull-component Phase 2.5: pass the target Component Set's nodeId
    (from Phase 2's URL extraction).

All three are scoped lints by definition; whole-file lints stay unscoped
(SCOPE_ROOT_ID = null).

The scope walk includes the root itself, since STRUCT011's aggregated
variable-naming message attaches to the scope root rather than a
descendant. Descendant walk uses `node.findAll`.

SKILL-only change. No code changes; existing tests pass.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 plugins/adhd/skills/lint/SKILL.md           | 47 ++++++++++++++++-----
 plugins/adhd/skills/pull-component/SKILL.md |  1 +
 plugins/adhd/skills/push-component/SKILL.md |  1 +
 3 files changed, 39 insertions(+), 10 deletions(-)

diff --git a/plugins/adhd/skills/lint/SKILL.md b/plugins/adhd/skills/lint/SKILL.md
index fb9cc93..83e1167 100644
--- a/plugins/adhd/skills/lint/SKILL.md
+++ b/plugins/adhd/skills/lint/SKILL.md
@@ -123,10 +123,13 @@ console.log(out.length);
 
 ### The use_figma script
 
-Pass the violations array to `mcp__plugin_figma_figma__use_figma` with `skillNames: "figma-use"`. The script ensures the category exists, applies current violations, and clears stale ADHD annotations file-wide (so a re-run reflects the current state — fixed violations get their annotations cleared automatically).
+Pass the violations array to `mcp__plugin_figma_figma__use_figma` with `skillNames: "figma-use"`. The script ensures the category exists, applies current violations, and clears stale "lint"-category annotations — **scoped to whatever the current lint covered**. This is important: scoped lints (Phase 2 with a target nodeId) should ONLY touch annotations within the scoped subtree, never wipe annotations on unrelated frames that this run didn't lint. Whole-file lints walk every page.
+
+Inject `SCOPE_ROOT_ID` from Phase 2's resolved target: the nodeId for scoped mode, `null` for whole-file mode. The script branches on it.
 
 ```js
 const VIOLATIONS = /* substituted: contents of /tmp/adhd-lint/violations.json */;
+const SCOPE_ROOT_ID = /* substituted: scoped target's nodeId, or null for whole-file */;
 const CATEGORY_LABEL = "lint";
 const CATEGORY_COLOR = "orange";
 
@@ -144,18 +147,42 @@ for (const v of VIOLATIONS) {
   byNode.get(v.nodeId).push(v);
 }
 
-// 3) Walk every page to find nodes with prior ADHD annotations + apply updates.
-//    Pages load incrementally — use `setCurrentPageAsync` so `findAll` sees their content.
+// 3) Find previously-annotated nodes WITHIN THE LINT'S SCOPE.
+//    Pages load incrementally — use `setCurrentPageAsync` so `findAll`
+//    sees their content. The scope branch is critical: a scoped lint on
+//    UserAvatar must not wipe a STRUCT010 annotation that lives on Logotype
+//    — that frame wasn't part of this run.
 let updated = 0, cleared = 0;
 const touchedIds = new Set();
 
-for (const page of figma.root.children) {
-  await figma.setCurrentPageAsync(page);
-  // Previously-annotated nodes under this page.
-  const prior = page.findAll(n =>
-    "annotations" in n && (n.annotations ?? []).some(a => a.categoryId === cat.id)
-  );
-  for (const n of prior) touchedIds.add(n.id);
+if (SCOPE_ROOT_ID) {
+  // Scoped: walk only the scope's subtree (root + descendants).
+  const scopeRoot = await figma.getNodeByIdAsync(SCOPE_ROOT_ID);
+  if (!scopeRoot) return { error: "Scope root not found", SCOPE_ROOT_ID };
+  // Set page context so findAll sees descendants.
+  let page = scopeRoot;
+  while (page.parent && page.type !== "PAGE") page = page.parent;
+  if (page && page.type === "PAGE") await figma.setCurrentPageAsync(page);
+  // Include the scope root itself if it has prior annotations (STRUCT011's
+  // aggregated message attaches there).
+  if ("annotations" in scopeRoot && (scopeRoot.annotations ?? []).some(a => a.categoryId === cat.id)) {
+    touchedIds.add(scopeRoot.id);
+  }
+  if (typeof scopeRoot.findAll === "function") {
+    const prior = scopeRoot.findAll(n =>
+      "annotations" in n && (n.annotations ?? []).some(a => a.categoryId === cat.id)
+    );
+    for (const n of prior) touchedIds.add(n.id);
+  }
+} else {
+  // Whole-file: walk every page.
+  for (const page of figma.root.children) {
+    await figma.setCurrentPageAsync(page);
+    const prior = page.findAll(n =>
+      "annotations" in n && (n.annotations ?? []).some(a => a.categoryId === cat.id)
+    );
+    for (const n of prior) touchedIds.add(n.id);
+  }
 }
 
 // Union of "previously annotated" and "currently violated" — every node that needs a write.
diff --git a/plugins/adhd/skills/pull-component/SKILL.md b/plugins/adhd/skills/pull-component/SKILL.md
index c0b7c4d..de2cec2 100644
--- a/plugins/adhd/skills/pull-component/SKILL.md
+++ b/plugins/adhd/skills/pull-component/SKILL.md
@@ -122,6 +122,7 @@ For Path B, skip the prompt if no violation has a `nodeId` (no actionable annota
 Inputs (both paths):
 - Engine stdout: `/tmp/adhd-pull-component/stdout.json`
 - Distill to `/tmp/adhd-pull-component/violations.json` using the same `node -e` snippet as lint Phase 6.
+- **`SCOPE_ROOT_ID`** — pass the target Component Set's nodeId (from Phase 2's URL extraction). This bounds the annotation script's stale-annotation cleanup to this Component Set's subtree, so a pull of UserAvatar doesn't wipe a previously-annotated STRUCT010 on an unrelated Logo Component Set elsewhere in the file.
 
 Either path runs BEFORE the abort/escape evaluation below, so the designer sees the annotations regardless of whether the pull continues.
 
diff --git a/plugins/adhd/skills/push-component/SKILL.md b/plugins/adhd/skills/push-component/SKILL.md
index 2dedade..b1684a0 100644
--- a/plugins/adhd/skills/push-component/SKILL.md
+++ b/plugins/adhd/skills/push-component/SKILL.md
@@ -208,6 +208,7 @@ For Path B, skip the prompt if (a) preflight is clean (no errors blocking the pu
 Inputs (both paths):
 - Engine stdout: `/tmp/adhd-push-component/preflight-report.json`
 - Distill to `/tmp/adhd-push-component/violations.json` using the same `node -e` snippet as lint Phase 6.
+- **`SCOPE_ROOT_ID`** — pass the freshly-pushed Component Set's nodeId (saved in Phase 9 as `componentSetId`). This bounds the annotation script's stale-annotation cleanup to this Component Set's subtree, so a push of UserAvatar doesn't wipe a previously-annotated STRUCT010 on an unrelated Logo Component Set elsewhere in the file.
 
 Phase 10.5 runs AFTER the preflight CLI exits but BEFORE Phase 11's decide-or-rollback — designers see annotations even when push aborts.
 

From aa38f66eabfc4e7816b8f22f9b4076ab7afde7c2 Mon Sep 17 00:00:00 2001
From: Hugh Francis <hughfrancis89@gmail.com>
Date: Mon, 11 May 2026 23:35:49 -0400
Subject: [PATCH 47/79] lint engine: merge Tailwind v4 defaults so vars like
 \`white\` aren't "missing"
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

User feedback: pull-component Phase 2.7 prompted to add \`color/white\`
(#ffffff) to globals.css. White is part of Tailwind v4's default theme
— adding it locally is redundant clutter. The user's rule:

  "Never add something locally in code that is implicitly provided by
   tailwind please!"

Saved as a feedback memory + fixed at the root in the lint engine:
parseTheme on the user's globals.css now gets merged with the parsed
contents of lib/design-system/tailwind-defaults.css (the canonical
copy push/pull-design-system already use via parseCodeDesignSystem).
User overrides win on key collision.

After the merge, the variable comparator only reports \`status: "missing"\`
for variables that are absent from BOTH the user's @theme block AND
Tailwind v4's defaults. Downstream surfaces benefit for free:
- Lint reports no longer list Tailwind-covered vars as actionable
- pull-component Phase 2.7 discovery prompt doesn't suggest adding them
- /adhd:lint --annotate doesn't annotate them

Implementation detail: the defaults file uses \`@theme default {\` and
\`@theme default inline {\` (Tailwind's canonical reference syntax). The
lint engine's parseTheme only matches \`@theme {\` / \`@theme inline {\`,
so loadTailwindDefaultPrimitives rewrites the headers before parsing.
Only \`primitives\` is merged (exposure/light/dark stay user-owned).

Test: 3-variable fixture with white + black + a custom brand color and
an empty globals.css. Only the custom color surfaces as missing. White
and black are silently covered by Tailwind.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 .../lib/lint-engine/__tests__/cli.test.js     | 34 ++++++++++++++++++
 plugins/adhd/lib/lint-engine/cli.js           | 35 ++++++++++++++++++-
 plugins/adhd/skills/pull-component/SKILL.md   |  2 +-
 3 files changed, 69 insertions(+), 2 deletions(-)

diff --git a/plugins/adhd/lib/lint-engine/__tests__/cli.test.js b/plugins/adhd/lib/lint-engine/__tests__/cli.test.js
index f9f2df3..ab4632b 100644
--- a/plugins/adhd/lib/lint-engine/__tests__/cli.test.js
+++ b/plugins/adhd/lib/lint-engine/__tests__/cli.test.js
@@ -266,6 +266,40 @@ test('STRUCT011: collection-name-is-domain (Color/, Radius/, Spacing/) — no do
   assert.equal(summary.structure.filter(v => v.rule === 'STRUCT011').length, 0);
 });
 
+test('Tailwind-default variables are NEVER reported as missing in code', () => {
+  // Tailwind v4 ships `--color-white`, `--color-black`, the spacing
+  // multiplier, the --text-* scale, etc. by default. If a Figma file has
+  // a variable that maps to one of those (e.g. `Color/white` = #ffffff),
+  // the comparator must NOT surface it as `status: 'missing'` — the user
+  // would then see a "add this to globals.css" prompt for a token Tailwind
+  // already provides. Pure clutter.
+  const varDefs = tmp('vars.json', {
+    'Primitives/color/white':  '#ffffff',    // Tailwind default → must NOT be missing
+    'Primitives/color/black':  '#000000',    // Tailwind default → must NOT be missing
+    'Primitives/color/custom': '#5e3aee',    // genuinely missing
+  });
+  const ctx = tmp('ctx.json', { id: '5:1', name: 'X', type: 'FRAME', layoutMode: 'VERTICAL' });
+  // globals.css has nothing — relying entirely on Tailwind defaults.
+  const cssPath = tmp('globals.css', `@theme {} :root {} :root[data-theme="dark"] {}`);
+  const configPath = tmp('adhd.config.ts', `export default { naming: 'kebab-case' };`);
+  const reportPath = path.join(os.tmpdir(), 'adhd-report-' + Date.now() + '.md');
+
+  const result = spawnSync('node', [
+    CLI, '--variable-defs', varDefs, '--design-context', ctx, '--globals-css', cssPath,
+    '--config', configPath, '--target', 'X',
+    '--target-url', 'https://figma.com/design/abc?node-id=5-1', '--output', reportPath,
+  ], { encoding: 'utf8' });
+
+  const summary = JSON.parse(result.stdout);
+  const missing = summary.variable.filter(v => v.status === 'missing');
+  // Only the custom brand color should be "missing" — white/black are covered by Tailwind.
+  assert.equal(missing.length, 1, 'only the non-default variable should be flagged as missing');
+  assert.equal(missing[0].token, 'color/custom');
+  // The defaults are absent from the missing list.
+  assert.equal(missing.filter(v => v.token === 'color/white').length, 0);
+  assert.equal(missing.filter(v => v.token === 'color/black').length, 0);
+});
+
 test('STRUCT011: omits nodeId in whole-file mode (no scope root to annotate)', () => {
   const varDefs = tmp('vars.json', { 'Primitives/color/BrandPrimary': '#000' });
   const ctx = tmp('ctx.json', { mode: 'whole-file', pages: [] });
diff --git a/plugins/adhd/lib/lint-engine/cli.js b/plugins/adhd/lib/lint-engine/cli.js
index 172b5f7..4482153 100644
--- a/plugins/adhd/lib/lint-engine/cli.js
+++ b/plugins/adhd/lib/lint-engine/cli.js
@@ -18,7 +18,34 @@
  */
 
 const fs = require('node:fs');
+const path = require('node:path');
 const { parseTheme } = require('./theme-parser');
+
+// Tailwind v4 ships a full default @theme: --color-white, --color-black,
+// --color-red-500, --spacing, the --text-* / --leading-* scales, etc.
+// `lib/design-system/tailwind-defaults.css` carries the canonical copy
+// (already used by push/pull-design-system via parseCodeDesignSystem).
+// We merge those defaults into the user's parsed primitives BEFORE the
+// variable comparator runs — otherwise a Figma `Color/white` variable
+// would surface as "missing in code" even though Tailwind covers it,
+// and downstream surfaces (lint reports, pull-component Phase 2.7
+// discovery prompts) would suggest writing `--color-white: #fff` to
+// globals.css — pure clutter, no value.
+const TAILWIND_DEFAULTS_PATH = path.resolve(__dirname, '..', 'design-system', 'tailwind-defaults.css');
+
+function loadTailwindDefaultPrimitives() {
+  let css;
+  try { css = fs.readFileSync(TAILWIND_DEFAULTS_PATH, 'utf8'); }
+  catch { return {}; }
+  // The defaults file uses `@theme default {` and `@theme default inline {`
+  // (Tailwind's syntax for the canonical reference theme). parseTheme only
+  // matches plain `@theme {` / `@theme inline {`, so rewrite the headers
+  // before parsing.
+  const normalized = css
+    .replace(/@theme\s+default\s+inline\s*\{/g, '@theme inline {')
+    .replace(/@theme\s+default\s*\{/g, '@theme {');
+  return parseTheme(normalized).primitives;
+}
 const { categorizeVariables } = require('./variable-categorizer');
 const { checkStructure } = require('./structure-checker');
 const { buildVariableSuggestions } = require('./variable-namer');
@@ -79,7 +106,13 @@ function main() {
   const namingConvention = readNamingConvention(args['config']);
   const fileKey = extractFileKey(args['target-url']);
 
-  const theme = parseTheme(cssText);
+  const userTheme = parseTheme(cssText);
+  const tailwindDefaults = loadTailwindDefaultPrimitives();
+  // User's @theme wins on key collision (override always beats default).
+  const theme = {
+    ...userTheme,
+    primitives: { ...tailwindDefaults, ...userTheme.primitives },
+  };
   const variableViolations = categorizeVariables(varDefs, theme);
 
   let structureViolations = [];
diff --git a/plugins/adhd/skills/pull-component/SKILL.md b/plugins/adhd/skills/pull-component/SKILL.md
index de2cec2..0860877 100644
--- a/plugins/adhd/skills/pull-component/SKILL.md
+++ b/plugins/adhd/skills/pull-component/SKILL.md
@@ -188,7 +188,7 @@ If BOTH STRUCT011 AND variable-binding errors are present, surface STRUCT011 fir
 
 Once preflight passes (no STRUCT011, no unbound errors or escape engaged), check the lint engine's variable mismatches in `/tmp/adhd-pull-component/stdout.json`. The categorizer reports two interesting statuses for our purpose:
 
-- **`status: "missing"`** — Figma has the variable, code's `globals.css` doesn't. New to the design system.
+- **`status: "missing"`** — Figma has the variable, code's `globals.css` doesn't. New to the design system. (The lint engine merges Tailwind v4's default theme into the comparison BEFORE evaluating "missing" — so vars like `Color/white` that Tailwind already provides won't surface here. Never propose adding something to globals.css that Tailwind covers implicitly.)
 - **`status: "conflict"`** — both sides have the variable but values disagree. NOT touched by pull-component; this is `/adhd:pull-design-system`'s job.
 
 Split missing further by the categorizer's `mode` field:

From c1576d6c3e2084314c51c99a6fec625bdaf16585 Mon Sep 17 00:00:00 2001
From: Hugh Francis <hughfrancis89@gmail.com>
Date: Mon, 11 May 2026 23:42:08 -0400
Subject: [PATCH 48/79] add /adhd:pull-all-components and
 /adhd:push-all-components bulk skills
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

User asked for bulk pull/push to iterate the components map in
adhd.config.ts without typing per-component commands. Both directions
shipped per user's preference.

Behavior:
- Sequential iteration over every entry in adhd.config.ts's `components` map
- Halt on first failure by default (user picked this over continue-by-default)
- `--continue-on-error` opts into best-effort mode with end-of-run summary
- Per-component flags (`--allow-unbound`, `--annotate`, `--max-variants`)
  pass through to each invocation
- Each component's pull/push runs its FULL interactive flow — preflight
  blockers, escape questions, Phase 2.7 missing-var discovery, annotate
  offers, sync-docs prompt. No batch override of per-component decisions.

End-of-run summary shows per-component status with ✓ / ✗ / ⏭ markers,
counts, and a "to re-try just the failures" hint for the actual failed
paths. Exit code 0 if all succeed, 1 if any abort.

Dev-server handling in push-all: push-component's Phase 4 only starts
the server if not already running. The first bulk push starts it (if
needed); subsequent ones reuse the running instance. push-component's
Phase 13 cleanup leaves the server alone when it didn't start it. The
bulk skill's Phase 4 cleanup owns the final teardown — only if the
bulk started it; if it was already up, leave alone.

SKILL-only change; no lib code. Tests still pass.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 README.md                                     |   4 +-
 .../adhd/skills/pull-all-components/SKILL.md  | 151 ++++++++++++++++++
 .../adhd/skills/push-all-components/SKILL.md  | 109 +++++++++++++
 3 files changed, 263 insertions(+), 1 deletion(-)
 create mode 100644 plugins/adhd/skills/pull-all-components/SKILL.md
 create mode 100644 plugins/adhd/skills/push-all-components/SKILL.md

diff --git a/README.md b/README.md
index cfab9fa..bb9756e 100644
--- a/README.md
+++ b/README.md
@@ -24,7 +24,7 @@ Then install ADHD itself:
 
 All three commands are persistent — Claude Code remembers the marketplaces and the enabled plugins across sessions. Run them once per machine.
 
-After install, seven slash commands are available:
+After install, nine slash commands are available:
 
 | Command | Args | Direction | What it does |
 |---|---|---|---|
@@ -33,7 +33,9 @@ After install, seven slash commands are available:
 | `/adhd:push-design-system` | — | code → Figma | Pushes globals.css variables + named styles into Figma directly via the remote MCP |
 | `/adhd:pull-design-system` | — | Figma → code | Pulls Figma variables + named styles into globals.css |
 | `/adhd:push-component` | `<path> [--max-variants <n>] [--annotate]` | code → Figma | Pushes a React component to Figma as a structured Component Set with variant properties + variable bindings, plus a preflight lint check. `--annotate` annotates preflight violations on Figma nodes. |
+| `/adhd:push-all-components` | `[--continue-on-error] [--max-variants <n>] [--annotate]` | code → Figma | Bulk version of `push-component` — iterates over every entry in `adhd.config.ts`'s components map. Sequential, halt-on-first-failure by default. |
 | `/adhd:pull-component` | `<path \| figma-url> [--allow-unbound] [--annotate]` | Figma → code | Pulls a Figma Component Set into a React source file; updates lookup tables and union types only (function body untouched). `--annotate` annotates preflight violations on Figma nodes. |
+| `/adhd:pull-all-components` | `[--continue-on-error] [--allow-unbound] [--annotate]` | Figma → code | Bulk version of `pull-component` — iterates over every entry in `adhd.config.ts`'s components map. Sequential, halt-on-first-failure by default. |
 | `/adhd:sync-docs` | — | install | Generates a design-system docs route in your Next.js consumer app. Tokens read live from globals.css; components are statically imported from adhd.config.ts at setup time — re-run after editing the components map. Excluded from production builds by default. |
 
 Every command above drives Figma exclusively through the `figma@claude-plugins-official` plugin. `/adhd:config` checks it's installed + authenticated up front so setup errors surface where you can fix them, not mid-pipeline.
diff --git a/plugins/adhd/skills/pull-all-components/SKILL.md b/plugins/adhd/skills/pull-all-components/SKILL.md
new file mode 100644
index 0000000..edce5ca
--- /dev/null
+++ b/plugins/adhd/skills/pull-all-components/SKILL.md
@@ -0,0 +1,151 @@
+---
+description: "Bulk version of /adhd:pull-component. Iterates over every entry in adhd.config.ts's `components` map and runs the full pull flow on each, sequentially. Halts on first failure by default (use --continue-on-error for best-effort + summary). Per-component interactivity (preflight blockers, --allow-unbound escape, Phase 2.7 missing-var discovery, annotate, sync-docs prompt) is preserved — each component's pull behaves exactly as if you'd invoked /adhd:pull-component manually."
+disable-model-invocation: true
+argument-hint: "[--continue-on-error] [--allow-unbound] [--annotate]"
+allowed-tools: Read Write Edit Bash AskUserQuestion mcp__plugin_figma_figma__use_figma mcp__plugin_figma_figma__get_metadata
+---
+
+# ADHD Pull All Components
+
+Bulk wrapper around `/adhd:pull-component`. Reads the components map from `adhd.config.ts` and iterates over every entry, running the full per-component pull flow on each. Stops on first failure unless `--continue-on-error` is passed.
+
+**Why this skill exists:** for design systems with many components, pulling each one manually is repetitive. This skill saves the typing AND provides a single end-of-run summary so failures don't get buried in a long log.
+
+**What this skill DOES NOT do:**
+- Suppress per-component prompts (preflight blockers, escape questions, annotate offers). Each component's pull runs its full interactive flow.
+- Apply decisions across all components ("annotate all", "add all missing vars", etc.). Those would require a global mode and risk batch-applying choices that should be considered per-component. v2 if it proves annoying.
+
+## Phase 1: Validate config + read components list
+
+Run the same Phase 1 as `/adhd:pull-component`: validate `adhd.config.ts` exists at the repo root, etc.
+
+Then read every key from the `components: { ... }` map. Use a small `node -e` snippet to avoid TS-execution dependency:
+
+```bash
+mkdir -p /tmp/adhd-pull-all
+node -e '
+const fs = require("node:fs");
+const src = fs.readFileSync("adhd.config.ts", "utf8");
+const m = /components:\s*\{([\s\S]*?)\}\s*[,;]?/.exec(src);
+if (!m) { process.stdout.write("[]"); process.exit(0); }
+// Use brace-counted scan for nested values (each component value is itself
+// an object). This is the same logic lib/sync-docs/config-parser.js uses.
+const startIdx = m.index + m[0].indexOf("{");
+let depth = 1, k = startIdx + 1;
+while (k < src.length && depth > 0) {
+  if (src[k] === "{") depth++;
+  else if (src[k] === "}") depth--;
+  if (depth > 0) k++;
+}
+const inner = src.slice(startIdx + 1, k);
+const paths = [];
+let d = 0, i = 0;
+while (i < inner.length) {
+  const ch = inner[i];
+  if (ch === "{") { d++; i++; continue; }
+  if (ch === "}") { d--; i++; continue; }
+  if (d === 0 && ch === "\"") {
+    const end = inner.indexOf("\"", i + 1);
+    if (end === -1) break;
+    const key = inner.slice(i + 1, end);
+    let j = end + 1;
+    while (j < inner.length && /\s/.test(inner[j])) j++;
+    if (inner[j] === ":") paths.push(key);
+    i = end + 1; continue;
+  }
+  i++;
+}
+process.stdout.write(JSON.stringify(paths));
+' > /tmp/adhd-pull-all/paths.json
+```
+
+If the resulting list is empty, abort:
+
+```
+✗ No components registered in adhd.config.ts.
+Run /adhd:push-component <path> to register a component first
+(it writes the entry to adhd.config.ts), then re-run /adhd:pull-all-components.
+```
+
+Print the planned run upfront so the user can see what's about to happen:
+
+```
+Pulling 5 components in sequence:
+  1. components/design-system/logo/index.tsx
+  2. components/avatar/index.tsx
+  3. components/button/index.tsx
+  4. components/card/index.tsx
+  5. components/icon/index.tsx
+```
+
+## Phase 2: Iterate
+
+For each path in the list, in order:
+
+1. Print a divider header:
+   ```
+   ──── [N/total] pulling <path> ────
+   ```
+
+2. Invoke the phases of `/adhd:pull-component` inline for this path. Pass through any flags the user gave to `/adhd:pull-all-components`:
+   - `--allow-unbound` (per-component STRUCT003/004/005 escape)
+   - `--annotate` (per-component preflight annotation)
+
+   The per-component pull-component SKILL handles its own validation, preflight, abort/escape logic, opportunistic-variable discovery (Phase 2.7), final report, and the post-success sync-docs prompt. All of those still fire normally — `pull-all-components` doesn't interfere with their flow.
+
+3. Record the outcome for this component into `/tmp/adhd-pull-all/outcomes.json` (append-only). Outcome shape:
+   ```json
+   { "path": "<path>", "status": "success" | "abort" | "cancel", "summary": "<one-line summary>", "error": "<abort reason if any>" }
+   ```
+   - `success`: the per-component pull completed Phase 10 (final report).
+   - `abort`: any blocking error (STRUCT011, unbound without escape, file missing, etc.).
+   - `cancel`: user said "no" / cancel on an in-flow prompt (treated as a halt — they explicitly stopped).
+
+4. **Decide whether to continue:**
+   - If `success` or `cancel`: continue to the next component. (`cancel` halts the inner per-component flow but is not treated as a bulk failure — the user made an explicit choice.)
+   - If `abort`:
+     - With `--continue-on-error`: record + continue.
+     - Without (default): print `Halted on <path>. Re-run with --continue-on-error to push through subsequent components, or fix the issue and re-run /adhd:pull-component <path> directly.` Then break out of the loop and go to Phase 3.
+
+5. **Skipped components** (when halt-on-error fires partway through): the remaining paths are NOT iterated. Their outcomes are recorded as `{ status: "skipped" }` so they show up in the final summary.
+
+## Phase 3: Final summary
+
+Read `/tmp/adhd-pull-all/outcomes.json` and produce:
+
+```
+Bulk pull report:
+  ✓ components/design-system/logo/index.tsx  — 3 cells updated
+  ✓ components/avatar/index.tsx              — no changes
+  ✗ components/button/index.tsx              — preflight: STRUCT011 (2 var-naming issues)
+  ⏭ components/card/index.tsx                — skipped (earlier failure)
+  ⏭ components/icon/index.tsx                — skipped (earlier failure)
+
+Summary: 2 succeeded, 1 failed, 2 skipped.
+```
+
+Append actionable next steps based on outcome:
+
+- **All succeeded:** print `Run /adhd:sync-docs to refresh the design-system docs route.` (already prompted per component but worth reminding for the whole run).
+- **Any failed:** print `To re-try just the failures: /adhd:pull-component <path>` with the actual failed paths listed.
+- **Any annotations were pushed** (i.e., `--annotate` was active): print `Annotations updated in the "lint" category in Figma.`
+
+Exit code:
+- All `success`/`cancel`: exit 0.
+- Any `abort`/`skipped`: exit 1.
+
+## Phase 4: Cleanup
+
+Always runs (even on abort):
+
+```bash
+rm -rf /tmp/adhd-pull-all
+```
+
+## Common errors
+
+| Error | Fix-up |
+|---|---|
+| `No components registered in adhd.config.ts` | Register a component first via `/adhd:push-component <path>`, or edit `adhd.config.ts` manually. |
+| Mid-run halt on STRUCT011 | Rename the offending Figma variables (see the STRUCT011 message for the per-variable target), then re-run. |
+| Mid-run halt on unbound values | Bind the values in Figma OR add `--allow-unbound` to the bulk command (applies to every component, so use carefully). |
diff --git a/plugins/adhd/skills/push-all-components/SKILL.md b/plugins/adhd/skills/push-all-components/SKILL.md
new file mode 100644
index 0000000..e2c6cac
--- /dev/null
+++ b/plugins/adhd/skills/push-all-components/SKILL.md
@@ -0,0 +1,109 @@
+---
+description: "Bulk version of /adhd:push-component. Iterates over every entry in adhd.config.ts's `components` map and runs the full push flow on each, sequentially. Halts on first failure by default (use --continue-on-error for best-effort + summary). Per-component interactivity (preview server start, capture, consolidation, preflight, --annotate prompts) is preserved — each component's push behaves exactly as if you'd invoked /adhd:push-component manually."
+disable-model-invocation: true
+argument-hint: "[--continue-on-error] [--max-variants <n>] [--annotate]"
+allowed-tools: Read Write Edit Bash AskUserQuestion mcp__plugin_figma_figma__use_figma mcp__plugin_figma_figma__generate_figma_design
+---
+
+# ADHD Push All Components
+
+Bulk wrapper around `/adhd:push-component`. Reads the components map from `adhd.config.ts` and iterates over every entry, running the full per-component push flow on each. Stops on first failure unless `--continue-on-error` is passed.
+
+**Why this skill exists:** if you've made structural changes to multiple components in code (renamed props, added variants, updated tokens) and want to push them all to Figma, this saves the typing AND keeps the Next.js dev server warm across pushes — push-component auto-starts it on the first component, and subsequent ones reuse the running instance.
+
+**What this skill DOES NOT do:**
+- Suppress per-component prompts (rollback decisions, annotate offers). Each push runs its full interactive flow.
+- Apply decisions across all components ("rollback all on any failure", "annotate all"). Per-component decisions stay per-component.
+
+## Phase 1: Validate config + read components list
+
+Run the same Phase 1 as `/adhd:push-component`: validate `adhd.config.ts` exists, etc. Then read every key from the `components: { ... }` map using the same `node -e` snippet as `pull-all-components` Phase 1 (brace-counted scan, output to `/tmp/adhd-push-all/paths.json`).
+
+If the resulting list is empty, abort:
+
+```
+✗ No components registered in adhd.config.ts.
+Run /adhd:push-component <path> to push a component for the first time
+(it writes the entry to adhd.config.ts), then re-run /adhd:push-all-components.
+```
+
+Print the planned run upfront:
+
+```
+Pushing 5 components to Figma in sequence:
+  1. components/design-system/logo/index.tsx
+  2. components/avatar/index.tsx
+  ...
+```
+
+## Phase 2: Iterate
+
+For each path in the list, in order:
+
+1. Print a divider:
+   ```
+   ──── [N/total] pushing <path> ────
+   ```
+
+2. Invoke the phases of `/adhd:push-component` inline for this path. Pass through any flags the user gave to `/adhd:push-all-components`:
+   - `--max-variants <n>` (applied uniformly to every component's variant cap)
+   - `--annotate` (per-component preflight annotation)
+
+   The per-component push-component SKILL handles its own validation, dev-server start/check, capture, consolidation, preflight, decide-or-rollback, final report, and the mapping write to `adhd.config.ts`. All of those still fire normally.
+
+   **Dev-server reuse:** push-component's Phase 4 only starts the server if one isn't already running. The first push in the bulk run starts it (if not already up); subsequent pushes reuse the running instance. push-component's Phase 13 (cleanup) tears down the server only when it auto-started it for that single run — in the bulk case, push-component sees the server was already running and leaves it alone. **This skill's Phase 4 (below) is responsible for the final teardown.**
+
+3. Record the outcome into `/tmp/adhd-push-all/outcomes.json`:
+   ```json
+   { "path": "<path>", "status": "success" | "abort" | "rollback" | "cancel", "summary": "<one-line>", "error": "<reason if any>" }
+   ```
+   - `success`: push-component completed Phase 12 (final report).
+   - `abort`: blocking error (file missing, capture failure, etc.).
+   - `rollback`: preflight produced errors and user (or default) chose to roll back the captured page.
+   - `cancel`: user explicitly stopped at an in-flow prompt.
+
+4. **Decide whether to continue:**
+   - `success` or `cancel`: continue.
+   - `rollback`: treated as failure for halt-on-error purposes. The user saw preflight errors and chose to roll back — they need to fix the source before bulk-pushing.
+   - `abort`: same as `rollback` — failure.
+   - With `--continue-on-error`: record + continue.
+   - Without: print the halt message and break out of the loop.
+
+5. Components after a halt are recorded as `skipped`.
+
+## Phase 3: Final summary
+
+```
+Bulk push report:
+  ✓ components/design-system/logo/index.tsx  — 4 variants pushed, preflight clean
+  ✓ components/avatar/index.tsx              — 6 variants pushed, 1 warning
+  ✗ components/button/index.tsx              — rolled back (preflight errors)
+  ⏭ components/card/index.tsx                — skipped (earlier failure)
+
+Summary: 2 succeeded, 1 failed, 1 skipped.
+```
+
+Actionable next steps:
+- **All succeeded:** `All components are now in sync with Figma. Run /adhd:sync-docs if you want to refresh the design-system docs route.`
+- **Any failed:** `To re-try just the failures: /adhd:push-component <path>`.
+- **`--annotate` was active:** `Preflight annotations updated in the "lint" category in Figma.`
+
+Exit 0 if all `success`/`cancel`, else 1.
+
+## Phase 4: Cleanup (always runs)
+
+```bash
+rm -rf /tmp/adhd-push-all
+```
+
+**Dev-server teardown:** if the bulk run was the thing that started the Next.js dev server (i.e., it wasn't already running when Phase 2 began), tear it down here. Use the same teardown helper push-component uses in its Phase 13. If the server was already running when the bulk started, leave it alone — it's the user's session.
+
+To check: at the start of Phase 2, record whether the dev server was up. Compare at Phase 4. Only kill the process if the bulk owned its lifecycle.
+
+## Common errors
+
+| Error | Fix-up |
+|---|---|
+| `No components registered in adhd.config.ts` | Run `/adhd:push-component <path>` once for a single component first to seed the mapping. |
+| Mid-run rollback on preflight errors | Fix the source code issue (raw values, etc.), then re-push that component individually before resuming the bulk. |
+| Dev-server start failure | Same fix as for `/adhd:push-component` solo runs — check the Next.js logs, port conflicts. |

From cbbb4b039f60583bcffe5678972b0c671853caf3 Mon Sep 17 00:00:00 2001
From: Hugh Francis <hughfrancis89@gmail.com>
Date: Mon, 11 May 2026 23:46:24 -0400
Subject: [PATCH 49/79] sync-docs: open-in-Figma link + proper PascalCase
 component name
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Two issues from the user's reactor docs route:

1) The import + JSX snippets rendered as \`import d from "..."\` and \`<d />\`
   on the logotype page. Root cause: the template used Component?.name as
   the snippet's display name, and the user's exported Logotype function
   got wrapped/minified so its .name is a single letter. Fix: prefer
   Component.name ONLY when it looks like a real identifier (matches
   /^[A-Z][A-Za-z0-9]+$/), otherwise fall back to a PascalCase'd slug.
   "logotype" → "Logotype", so the snippet reads \`import Logotype from
   "..."\` + \`<Logotype />\` regardless of how the component was wrapped.

2) No way to jump from a component's docs page back to its Figma source.
   Added a ↗ link in the page header that opens the entry's
   figma.url in a new tab. Plumbing:
     - config-parser: new parseFigmaUrlForPath() extracts \`figma.url\`
       per component path from adhd.config.ts. readConfig now includes
       figmaUrl in each component entry (null when no figma block).
     - route-installer: threads figmaUrl into the componentMap.tsx
       entries. Renders as a string literal or null.
     - templates: ComponentEntry shape carries figmaUrl: string | null;
       component page conditionally renders <a href={figmaUrl}> with the
       ↗ glyph, target="_blank" + rel="noopener noreferrer".

Both fixes apply to existing docs installs on re-sync — the marker-based
cleanup replaces componentMap.tsx and the component page in place. No
breaking changes; figmaUrl is opt-in (silent skip when absent).

Tests: figmaUrl extraction in config-parser, figmaUrl threading in
route-installer's componentMap output, template assertions for the Figma
link + PascalCase fallback. 441/441 plugin-wide.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 .../sync-docs/__tests__/config-parser.test.js | 18 +++++++++++
 .../__tests__/route-installer.test.js         | 24 ++++++++++++++
 .../lib/sync-docs/__tests__/templates.test.js | 28 +++++++++++++++++
 plugins/adhd/lib/sync-docs/config-parser.js   | 16 +++++++++-
 plugins/adhd/lib/sync-docs/route-installer.js |  3 +-
 plugins/adhd/lib/sync-docs/templates.js       | 31 +++++++++++++++++--
 6 files changed, 115 insertions(+), 5 deletions(-)

diff --git a/plugins/adhd/lib/sync-docs/__tests__/config-parser.test.js b/plugins/adhd/lib/sync-docs/__tests__/config-parser.test.js
index eb44025..58c1b1f 100644
--- a/plugins/adhd/lib/sync-docs/__tests__/config-parser.test.js
+++ b/plugins/adhd/lib/sync-docs/__tests__/config-parser.test.js
@@ -71,10 +71,28 @@ export default config;
     slug: 'logo',
     rawPath: 'components/design-system/logo/index.tsx',
     importPath: '@/components/design-system/logo',
+    figmaUrl: 'x',
   }]);
   assert.equal(r.cssEntry, 'app/globals.css');
 });
 
+test('readConfig extracts figma.url per component, falling back to null when absent', () => {
+  const root = makeProject(`
+const config = {
+  components: {
+    "components/logo/index.tsx":   { figma: { url: "https://www.figma.com/design/abc?node-id=1-1" } },
+    "components/button/index.tsx": { /* no figma block */ },
+  },
+};
+export default config;
+`);
+  const r = readConfig(root);
+  const logo = r.components.find(c => c.slug === 'logo');
+  const button = r.components.find(c => c.slug === 'button');
+  assert.equal(logo.figmaUrl, 'https://www.figma.com/design/abc?node-id=1-1');
+  assert.equal(button.figmaUrl, null);
+});
+
 test('readConfig throws if adhd.config.ts is missing', () => {
   const root = fs.mkdtempSync(path.join(os.tmpdir(), 'adhd-cfg-missing-'));
   assert.throws(() => readConfig(root), /ENOENT|no such file/);
diff --git a/plugins/adhd/lib/sync-docs/__tests__/route-installer.test.js b/plugins/adhd/lib/sync-docs/__tests__/route-installer.test.js
index a41aa11..1fca4f1 100644
--- a/plugins/adhd/lib/sync-docs/__tests__/route-installer.test.js
+++ b/plugins/adhd/lib/sync-docs/__tests__/route-installer.test.js
@@ -152,6 +152,30 @@ test('componentMap.tsx has explicit static imports per registered component', ()
   assert.doesNotMatch(body, /await\s+import\(`/);
 });
 
+test('componentMap.tsx carries the figmaUrl field per component (for the docs-page "open in Figma" link)', () => {
+  const root = makeTempProject();
+  writeLogoFixture(root);
+  installRoute(root, {
+    groupName: '(design-system)', routeSegment: '-docs', renderMode: 'dev-only',
+    components: [
+      { slug: 'logo', rawPath: 'components/design-system/logo/index.tsx',
+        importPath: '@/components/design-system/logo',
+        figmaUrl: 'https://www.figma.com/design/abc?node-id=1-1' },
+      { slug: 'button', rawPath: 'components/button.tsx',
+        importPath: '@/components/button', figmaUrl: null },
+    ],
+    cssEntry: 'app/globals.css',
+  });
+  const body = fs.readFileSync(
+    path.join(root, 'app', '(design-system)', '-docs', 'componentMap.tsx'),
+    'utf8',
+  );
+  // Logo entry carries the URL literal
+  assert.match(body, /slug: "logo".*figmaUrl: "https:\/\/www\.figma\.com\/design\/abc\?node-id=1-1"/);
+  // Button entry has null when no figma URL was provided
+  assert.match(body, /slug: "button".*figmaUrl: null/);
+});
+
 test('componentMap.tsx bakes prop schemas read from each component source at sync time', () => {
   // The component page no longer does fs reads — props are baked here. Test
   // verifies that the LogoProps interface (size: union, inverted: boolean,
diff --git a/plugins/adhd/lib/sync-docs/__tests__/templates.test.js b/plugins/adhd/lib/sync-docs/__tests__/templates.test.js
index 3192e9a..50bd62c 100644
--- a/plugins/adhd/lib/sync-docs/__tests__/templates.test.js
+++ b/plugins/adhd/lib/sync-docs/__tests__/templates.test.js
@@ -115,6 +115,34 @@ test('COMPONENT_MAP_TSX has the substitution placeholders the installer fills in
   assert.match(COMPONENT_MAP_TSX, /export type PropSchema/);
 });
 
+test('COMPONENT_MAP_TSX declares figmaUrl on the ComponentEntry shape', () => {
+  // Powers the "open in Figma" link on each component page. Null when the
+  // user hasn't set a Figma URL for that component in adhd.config.ts.
+  assert.match(COMPONENT_MAP_TSX, /figmaUrl:\s*string \| null/);
+});
+
+test('COMPONENT_PAGE_TSX renders a Figma link with ↗ when figmaUrl is present', () => {
+  // Link is opt-in: only shown when the entry's figmaUrl isn't null.
+  // Opens in a new tab (target="_blank"), uses rel="noopener noreferrer"
+  // for security.
+  assert.match(COMPONENT_PAGE_TSX, /figmaUrl &&[\s\S]*<a/);
+  assert.match(COMPONENT_PAGE_TSX, /href=\{figmaUrl\}/);
+  assert.match(COMPONENT_PAGE_TSX, /target="_blank"/);
+  assert.match(COMPONENT_PAGE_TSX, /rel="noopener noreferrer"/);
+  // The northeast-arrow glyph is the link content
+  assert.match(COMPONENT_PAGE_TSX, /↗/);
+});
+
+test('COMPONENT_PAGE_TSX falls back to PascalCase slug when Component.name looks garbled', () => {
+  // The runtime check rejects names that are single letters (minifier output
+  // like "d") or start with non-uppercase chars (anonymous fn wrappers).
+  // Falls back to the slug PascalCase'd so the snippet reads "<Logotype />"
+  // not "<d />" or "<logotype />".
+  assert.match(COMPONENT_PAGE_TSX, /looksLikeRealName/);
+  assert.match(COMPONENT_PAGE_TSX, /\/\^\[A-Z\]\[A-Za-z0-9\]\+\$\//);
+  assert.match(COMPONENT_PAGE_TSX, /pascalSlug/);
+});
+
 test('COMPONENT_MAP_TSX resolves a renderable function via default-then-named fallback', () => {
   assert.match(COMPONENT_MAP_TSX, /function resolveComponent/);
   assert.match(COMPONENT_MAP_TSX, /mod\.default/);
diff --git a/plugins/adhd/lib/sync-docs/config-parser.js b/plugins/adhd/lib/sync-docs/config-parser.js
index e840e07..ae91aac 100644
--- a/plugins/adhd/lib/sync-docs/config-parser.js
+++ b/plugins/adhd/lib/sync-docs/config-parser.js
@@ -57,6 +57,19 @@ function parseCssEntry(src) {
   return m ? m[1] : 'app/globals.css';
 }
 
+// Extract the `figma.url` value for a given component-path key. Returns
+// `null` when the entry has no `figma: { url: "..." }` block — the docs
+// route's "open in Figma" link is then suppressed for that component.
+// Targeted regex scoped to the value block that follows the path key.
+function parseFigmaUrlForPath(src, p) {
+  const escapedPath = p.replace(/[.*+?^${}()|[\]\\\/]/g, '\\$&');
+  const re = new RegExp(
+    '"' + escapedPath + '"\\s*:\\s*\\{[^}]*figma\\s*:\\s*\\{[^}]*url\\s*:\\s*"([^"]+)"',
+  );
+  const m = re.exec(src);
+  return m ? m[1] : null;
+}
+
 // Derive a URL slug from a component path. Mirrors the runtime helper used in
 // previous template versions so existing URL contracts are unchanged.
 //   src/components/Logo/index.tsx → "logo"
@@ -83,6 +96,7 @@ function readConfig(projectRoot) {
     slug: slugFor(rawPath),
     rawPath,
     importPath: importPathFor(rawPath),
+    figmaUrl: parseFigmaUrlForPath(src, rawPath),
   }));
   return {
     components,
@@ -90,4 +104,4 @@ function readConfig(projectRoot) {
   };
 }
 
-module.exports = { readConfig, parseComponents, parseCssEntry, slugFor, importPathFor };
+module.exports = { readConfig, parseComponents, parseCssEntry, parseFigmaUrlForPath, slugFor, importPathFor };
diff --git a/plugins/adhd/lib/sync-docs/route-installer.js b/plugins/adhd/lib/sync-docs/route-installer.js
index 97b15d9..8e33258 100644
--- a/plugins/adhd/lib/sync-docs/route-installer.js
+++ b/plugins/adhd/lib/sync-docs/route-installer.js
@@ -54,7 +54,8 @@ function renderComponentMap(projectRoot, components) {
   const entries = components
     .map((c, i) => {
       const props = JSON.stringify(bakedPropsFor(projectRoot, c.rawPath));
-      return `  { slug: ${JSON.stringify(c.slug)}, rawPath: ${JSON.stringify(c.rawPath)}, module: $cmp${i}, props: ${props} },`;
+      const figmaUrl = c.figmaUrl ? JSON.stringify(c.figmaUrl) : 'null';
+      return `  { slug: ${JSON.stringify(c.slug)}, rawPath: ${JSON.stringify(c.rawPath)}, figmaUrl: ${figmaUrl}, module: $cmp${i}, props: ${props} },`;
     })
     .join('\n');
   return COMPONENT_MAP_TSX
diff --git a/plugins/adhd/lib/sync-docs/templates.js b/plugins/adhd/lib/sync-docs/templates.js
index aa6f0e2..ca9398d 100644
--- a/plugins/adhd/lib/sync-docs/templates.js
+++ b/plugins/adhd/lib/sync-docs/templates.js
@@ -131,6 +131,7 @@ export type PropSchema = {
 export type ComponentEntry = {
   slug: string;
   rawPath: string;
+  figmaUrl: string | null;
   Component: React.ComponentType<Record<string, unknown>> | null;
   props: Record<string, PropSchema>;
 };
@@ -138,6 +139,7 @@ export type ComponentEntry = {
 type RawEntry = {
   slug: string;
   rawPath: string;
+  figmaUrl: string | null;
   module: Record<string, unknown>;
   props: Record<string, PropSchema>;
 };
@@ -158,6 +160,7 @@ const ENTRIES: RawEntry[] = __COMPONENT_ENTRIES__;
 export const components: ComponentEntry[] = ENTRIES.map(e => ({
   slug: e.slug,
   rawPath: e.rawPath,
+  figmaUrl: e.figmaUrl,
   Component: resolveComponent(e.module),
   props: e.props,
 }));
@@ -554,7 +557,7 @@ export default function ComponentPage() {
 
   if (!entry) return <NotInMap slug={slug} />;
 
-  const { rawPath, Component, props } = entry;
+  const { rawPath, figmaUrl, Component, props } = entry;
 
   // Resolve current prop values from the URL. Values are constrained to the
   // three shapes the page knows how to source — string (for union + string
@@ -570,8 +573,16 @@ export default function ComponentPage() {
     else if (def.type === "number") current[name] = Number(v);
   }
 
+  // Render-name precedence: prefer the actual exported function/class name
+  // when it looks like a real identifier (starts with uppercase, multi-char),
+  // otherwise fall back to a PascalCase'd slug. Avoids \`<d />\` and \`<_Logo />\`
+  // when the export got wrapped/minified and Component.name is a single
+  // letter or starts with an underscore.
+  const looksLikeRealName = !!Component?.name && /^[A-Z][A-Za-z0-9]+$/.test(Component.name);
+  const pascalSlug = slug.split(/[-_]+/).filter(Boolean).map(w => w[0].toUpperCase() + w.slice(1)).join("");
+  const componentName = looksLikeRealName ? Component!.name : (pascalSlug || slug);
+
   const importPath = "@/" + rawPath.replace(/\\.tsx?$/, "").replace(/\\/index$/, "");
-  const componentName = Component?.name || slug;
   const importStmt = Component ? \`import \${componentName} from "\${importPath}";\` : null;
   const jsxSnippet = Component
     ? \`<\${componentName}\${Object.entries(current).map(([k, v]) => \` \${k}={\${JSON.stringify(v)}}\`).join("")} />\`
@@ -579,7 +590,21 @@ export default function ComponentPage() {
 
   return (
     <div className="flex flex-col gap-6">
-      <h2 className="text-2xl font-medium">{slug}</h2>
+      <h2 className="text-2xl font-medium flex items-center gap-2">
+        <span>{componentName}</span>
+        {figmaUrl && (
+          <a
+            href={figmaUrl}
+            target="_blank"
+            rel="noopener noreferrer"
+            className="inline-flex items-center justify-center w-6 h-6 rounded text-sm text-zinc-500 hover:text-zinc-900 dark:hover:text-zinc-100 hover:bg-zinc-100 dark:hover:bg-zinc-800 transition-colors"
+            title="Open in Figma"
+            aria-label="Open in Figma"
+          >
+            ↗
+          </a>
+        )}
+      </h2>
 
       <section className="rounded border border-zinc-200 dark:border-zinc-800 p-4">
         <h3 className="mb-3 text-xs font-medium uppercase text-zinc-500">Props</h3>

From 364d889a9260ef3764ce88c8d8dbe9b1c57548c8 Mon Sep 17 00:00:00 2001
From: Hugh Francis <hughfrancis89@gmail.com>
Date: Mon, 11 May 2026 23:51:50 -0400
Subject: [PATCH 50/79] sync-docs: "Last built" timestamp in sidebar header
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Designers reading the docs route want a quick signal of "is this fresh?"
Added a UTC build timestamp to the sidebar header, right under the
"Internal — not indexed" line.

Format: \`Last built 2026-05-11 03:14 UTC\` — UTC by default so no locale
dependency, sortable, unambiguous. Baked at sync time via a new
__SYNC_AT__ placeholder; installer accepts an optional \`opts.now\` Date
override for deterministic tests.

The timestamp reflects when the user last ran /adhd:sync-docs (when
the static componentMap.tsx + layout were regenerated). Tokens are
read live from globals.css so their freshness isn't gated on this —
but if the designer wants to verify they're on the latest static map
(component imports, baked prop schemas), the timestamp is the signal.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 .../__tests__/route-installer.test.js         | 19 +++++++++++++++++++
 plugins/adhd/lib/sync-docs/route-installer.js | 14 +++++++++++++-
 plugins/adhd/lib/sync-docs/templates.js       |  1 +
 3 files changed, 33 insertions(+), 1 deletion(-)

diff --git a/plugins/adhd/lib/sync-docs/__tests__/route-installer.test.js b/plugins/adhd/lib/sync-docs/__tests__/route-installer.test.js
index 1fca4f1..71671f0 100644
--- a/plugins/adhd/lib/sync-docs/__tests__/route-installer.test.js
+++ b/plugins/adhd/lib/sync-docs/__tests__/route-installer.test.js
@@ -227,6 +227,25 @@ test('componentMap.tsx handles a missing component source file (empty props bake
   assert.match(body, /props: \{\}/);
 });
 
+test('layout bakes a UTC "Last built" timestamp in the sidebar header', () => {
+  const root = makeTempProject();
+  writeLogoFixture(root);
+  installRoute(root, {
+    groupName: '(design-system)', routeSegment: '-docs', renderMode: 'dev-only',
+    components: SAMPLE_COMPONENTS, cssEntry: 'app/globals.css',
+    // Injected Date for deterministic snapshot — production runs use `new Date()`.
+    now: new Date(Date.UTC(2026, 4, 11, 3, 14)), // 2026-05-11 03:14 UTC
+  });
+  const layout = fs.readFileSync(
+    path.join(root, 'app', '(design-system)', '-docs', 'layout.design-system.tsx'),
+    'utf8',
+  );
+  // Format: YYYY-MM-DD HH:MM UTC, baked verbatim
+  assert.match(layout, /Last built 2026-05-11 03:14 UTC/);
+  // Placeholder fully substituted
+  assert.doesNotMatch(layout, /__SYNC_AT__/);
+});
+
 test('layout sidebar links use absolute hrefs derived from the route segment', () => {
   const root = makeTempProject();
   writeLogoFixture(root);
diff --git a/plugins/adhd/lib/sync-docs/route-installer.js b/plugins/adhd/lib/sync-docs/route-installer.js
index 8e33258..18442a1 100644
--- a/plugins/adhd/lib/sync-docs/route-installer.js
+++ b/plugins/adhd/lib/sync-docs/route-installer.js
@@ -122,12 +122,24 @@ function installRoute(projectRoot, opts) {
   // `tokens/[domain]/page.*` to the docs root where `layout.*` lives.
   const layoutModule = prodExcluded ? '../../layout.design-system' : '../../layout';
 
+  // Sync timestamp baked into the layout's sidebar header. UTC, no locale
+  // dependency, format YYYY-MM-DD HH:MM UTC. Designers reading the docs
+  // route see "Last built 2026-05-11 03:14 UTC" — a clear signal of
+  // whether what they're looking at is fresh or stale.
+  const syncAt = (() => {
+    const d = opts.now instanceof Date ? opts.now : new Date();
+    const pad = n => String(n).padStart(2, '0');
+    return `${d.getUTCFullYear()}-${pad(d.getUTCMonth() + 1)}-${pad(d.getUTCDate())} ` +
+           `${pad(d.getUTCHours())}:${pad(d.getUTCMinutes())} UTC`;
+  })();
+
   // Per-template placeholder substitution.
   for (const t of targets) {
     t.body = t.body
       .replace(/__ROUTE_PATH__/g, routeUrl)
       .replace(/__CSS_ENTRY__/g, cssEntry)
-      .replace(/__LAYOUT_MODULE__/g, layoutModule);
+      .replace(/__LAYOUT_MODULE__/g, layoutModule)
+      .replace(/__SYNC_AT__/g, syncAt);
   }
 
   // Remove stale marker-bearing files from previous template layouts (e.g. the
diff --git a/plugins/adhd/lib/sync-docs/templates.js b/plugins/adhd/lib/sync-docs/templates.js
index ca9398d..79540e3 100644
--- a/plugins/adhd/lib/sync-docs/templates.js
+++ b/plugins/adhd/lib/sync-docs/templates.js
@@ -215,6 +215,7 @@ export default function DesignSystemDocsLayout({ children }: { children: React.R
         <Link href={\`__ROUTE_PATH__\`} className="block mb-6">
           <h1 className="text-sm font-medium">Design System</h1>
           <p className="text-[10px] text-zinc-500">Internal — not indexed</p>
+          <p className="text-[10px] text-zinc-500 mt-1">Last built __SYNC_AT__</p>
         </Link>
 
         <nav className="flex flex-col gap-4 text-sm">

From c89231c0918e6370afd7360e85601a41c4de82f7 Mon Sep 17 00:00:00 2001
From: Hugh Francis <hughfrancis89@gmail.com>
Date: Tue, 12 May 2026 00:11:10 -0400
Subject: [PATCH 51/79] lint STRUCT011: group by target collection + clarify
 "Move to" vs "Rename"
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

User feedback: the previous message said "right-click → Rename" but most
suggestions were MOVES across collections (Type + Effects/Font-Size/Body
→ Text/body). Rename only works within the same collection — a designer
literally couldn't apply most of the suggestions as advertised.

Three improvements:

1. Group renames by TARGET COLLECTION. Designer sees the action pattern:
   "create Text, move 2 vars in; create Leading, move 1 var in." Instead
   of a flat list of 6 unrelated-looking rename lines.

2. Call the action what it actually is: a MOVE. The footer explains
   Figma's "Move to..." mechanic (right-click → Move to → pick target
   collection; Figma auto-rewires references) and explicitly warns
   "Use Move to (not Rename) — Rename only works within the same
   collection."

3. Detect ambiguity. Some leaf names hint at a different domain than
   their path. "Type + Effects/Line-Height/Letter Space 0" — path
   suggests leading, but the leaf is letter-spacing (tracking). The
   suggestion now surfaces both options:
     Primary:   → Leading/letter-space-0
     Alternate: → Tracking/0
   Designer picks based on actual usage.

4. Concept-specific guidance for opacity. Tailwind v4 has no opacity
   domain — opacity is applied via class modifiers (bg-white/50), not
   stored as variables. The no-mapping message now explains this
   instead of just listing the canonical domain set.

Sample output for the user's reactor file (6 issues):

  STRUCT011: 6 variable-naming issue(s). Suggested restructure:

  → Move to "Leading" collection (1 var):
    • Type + Effects/Line-Height/Line Height 28
        → Leading/line-height-28

  → Move to "Spacing" collection (1 var):
    • Space/space/0  → Spacing/space/0

  → Move to "Text" collection (2 vars):
    • Type + Effects/Font-Size/Body     → Text/body
    • Type + Effects/Font-Size/Body LG  → Text/body-lg

  ⚠ Ambiguous (1) — path and leaf disagree on the target domain:
    • Type + Effects/Line-Height/Letter Space 0
        ⚠ path suggests leading, leaf "Letter Space 0" suggests tracking
        Primary:    → Leading/letter-space-0
        Alternate:  → Tracking/0

  ⚠ No Tailwind v4 mapping (1):
    • Type + Effects/Effects/Opacity 100%
        ⚠ Tailwind v4 has no "opacity" domain — opacity is applied via
          class modifiers (e.g. `bg-white/50`), not stored as variables.

  How to apply each move in Figma:
    1. Open the Variables panel; create any missing target collections.
    2. Right-click each source variable → "Move to..." → pick the target.
    3. Inside the target, rename to drop redundant path segments.

  Use Figma's "Move to..." (not "Rename") — Rename only works within
  the same collection.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 .../lib/lint-engine/__tests__/cli.test.js     | 53 +++++++------
 .../__tests__/variable-namer.test.js          | 31 +++++++-
 plugins/adhd/lib/lint-engine/cli.js           | 55 +++++++++++---
 .../adhd/lib/lint-engine/variable-namer.js    | 75 ++++++++++++++++++-
 4 files changed, 177 insertions(+), 37 deletions(-)

diff --git a/plugins/adhd/lib/lint-engine/__tests__/cli.test.js b/plugins/adhd/lib/lint-engine/__tests__/cli.test.js
index ab4632b..ef5c6f8 100644
--- a/plugins/adhd/lib/lint-engine/__tests__/cli.test.js
+++ b/plugins/adhd/lib/lint-engine/__tests__/cli.test.js
@@ -166,17 +166,20 @@ test('cli with structure errors but no variable issues exits 1', () => {
   assert.ok(summary.errors >= 1);
 });
 
-test('STRUCT011: emits one concrete rename target per variable (mixed case + domain issues)', () => {
-  // Real-world scenario from the user's reactor file: a bundled "Type +
-  // Effects" collection that conflates typography sizes, line-heights, and
-  // effects. Each variable gets a single target, not two contradictory
-  // hints. The designer can act on each line independently.
+test('STRUCT011: groups renames by target collection + calls the action "Move to"', () => {
+  // Real-world scenario from the user's reactor file: a "Type + Effects"
+  // collection bundling typography sizes, line-heights, and opacity. The
+  // message groups by target collection so the designer sees the pattern
+  // ("create Text + Leading, move things into them") instead of N
+  // disconnected lines.
   const varDefs = tmp('vars.json', {
-    'Type + Effects/Font-Size/Body':           '16px',
+    'Type + Effects/Font-Size/Body':             '16px',
+    'Type + Effects/Font-Size/Body LG':          '20px',
     'Type + Effects/Line-Height/Line Height 28': '28px',
-    'Type + Effects/Effects/Opacity 100%':     '1',     // no Tailwind v4 mapping
-    'Primitives/color/BrandPrimary':           '#000',  // tier-mode case fix
-    'Color/gold':                              '#c5a572', // already correct
+    'Type + Effects/Line-Height/Letter Space 0': '0',     // ambiguous (leaf hints tracking)
+    'Type + Effects/Effects/Opacity 100%':       '1',     // opacity has no v4 domain
+    'Primitives/color/BrandPrimary':             '#000',  // tier-mode case fix
+    'Color/gold':                                '#c5a572', // already correct
   });
   const ctx = tmp('ctx.json', { id: '5:42', name: 'Logo', type: 'FRAME', layoutMode: 'VERTICAL' });
   const cssPath = tmp('globals.css', `@theme {} :root {} :root[data-theme="dark"] {}`);
@@ -194,20 +197,28 @@ test('STRUCT011: emits one concrete rename target per variable (mixed case + dom
   assert.ok(struct011);
   assert.equal(struct011.severity, 'warning');
   assert.equal(struct011.nodeId, '5:42');
-  // Header counts ALL issues (4 — Color/gold is compliant and doesn't appear).
-  assert.match(struct011.message, /4 variable\(s\) need renaming for Tailwind v4 alignment/);
-  // Unknown-collection + domain-segment-hint → MOVE into domain-named collection
-  assert.match(struct011.message, /Type \+ Effects\/Font-Size\/Body[\s\S]*→ Text\/body/);
-  assert.match(struct011.message, /Type \+ Effects\/Line-Height\/Line Height 28[\s\S]*→ Leading\/line-height-28/);
-  // Tier collection + case-only issue → preserve tier, kebab the leaf
-  assert.match(struct011.message, /Primitives\/color\/BrandPrimary[\s\S]*→ Primitives\/color\/brand-primary/);
-  // Domain-less variable → no-mapping explanation
-  assert.match(struct011.message, /Type \+ Effects\/Effects\/Opacity 100%[\s\S]*⚠ No Tailwind v4 domain/);
+  // Header tone shifted from "renaming" (misleading) to "restructure" — these
+  // are moves, not renames, and the body explains how Figma's Move-To works.
+  assert.match(struct011.message, /variable-naming issue\(s\)\. Suggested restructure/);
+  // Target-collection groups present:
+  assert.match(struct011.message, /Move to "Text" collection \(2 vars\):/);
+  assert.match(struct011.message, /Text\/body/);
+  assert.match(struct011.message, /Text\/body-lg/);
+  assert.match(struct011.message, /Move to "Leading" collection \(1 var\):/);
+  assert.match(struct011.message, /Leading\/line-height-28/);
+  assert.match(struct011.message, /Move to "Primitives" collection \(1 var\):/);
+  // Ambiguity section surfaces both options
+  assert.match(struct011.message, /Ambiguous[\s\S]*Letter Space 0/);
+  assert.match(struct011.message, /Primary: +→ Leading/);
+  assert.match(struct011.message, /Alternate: +→ Tracking/);
+  // No-mapping section has opacity-specific guidance, not the generic list
+  assert.match(struct011.message, /No Tailwind v4 mapping[\s\S]*Opacity 100%[\s\S]*class modifiers/);
+  // Footer explains the Figma mechanic and calls out the rename-vs-move distinction
+  assert.match(struct011.message, /How to apply each move in Figma/);
+  assert.match(struct011.message, /Right-click the source variable → "Move to/);
+  assert.match(struct011.message, /Use Figma's "Move to\.\.\." \(not "Rename"\)/);
   // Already-correct variable doesn't appear
   assert.doesNotMatch(struct011.message, /Color\/gold/);
-  // No leftover from the old format
-  assert.doesNotMatch(struct011.message, /Case \(kebab-case/);
-  assert.doesNotMatch(struct011.message, /did you mean/);
 });
 
 test('STRUCT011: variable case is always kebab-case, regardless of project naming config', () => {
diff --git a/plugins/adhd/lib/lint-engine/__tests__/variable-namer.test.js b/plugins/adhd/lib/lint-engine/__tests__/variable-namer.test.js
index 7ce075f..8f21197 100644
--- a/plugins/adhd/lib/lint-engine/__tests__/variable-namer.test.js
+++ b/plugins/adhd/lib/lint-engine/__tests__/variable-namer.test.js
@@ -237,12 +237,35 @@ test('suggestTargetName: bundled collection with domain hint in rest → MOVE to
   });
 });
 
-test('suggestTargetName: bundled collection with no domain hint anywhere → no-mapping', () => {
-  // "Type + Effects/Effects/Opacity 100%" — none of "Type+Effects", "Effects",
-  // or "Opacity 100%" maps to a Tailwind v4 domain. The engine surfaces the
-  // canonical list so the designer picks a destination.
+test('suggestTargetName: opacity-shaped names get a specific concept-aware hint', () => {
+  // Tailwind v4 has no "opacity" domain — opacity is applied via class
+  // modifiers (`bg-white/50`). The no-mapping message reflects that
+  // rather than just listing canonical domains.
   const r = suggestTargetName('Type + Effects/Effects/Opacity 100%');
   assert.equal(r.kind, 'no-mapping');
+  assert.match(r.reason, /Tailwind v4 has no "opacity" domain/);
+  assert.match(r.reason, /class modifiers/);
+  // Doesn't repeat the generic "Expected one of: ..." list.
+  assert.doesNotMatch(r.reason, /Expected one of: color/);
+});
+
+test('suggestTargetName: leaf hint conflicts with path → ambiguous result', () => {
+  // The user's real case: "Type + Effects/Line-Height/Letter Space 0".
+  // Path says line-height (→ leading), leaf says "Letter Space" (→ tracking).
+  // The variable could be either; surface both options for the designer.
+  const r = suggestTargetName('Type + Effects/Line-Height/Letter Space 0');
+  assert.equal(r.kind, 'ambiguous');
+  assert.equal(r.target, 'Leading/letter-space-0');
+  assert.equal(r.alternate, 'Tracking/0');
+  assert.match(r.primaryReason, /path suggests leading/);
+  assert.match(r.alternateReason, /Letter Space.*suggests tracking/);
+});
+
+test('suggestTargetName: when no domain hint exists AND no opacity → generic no-mapping', () => {
+  // Fallback case for truly unmappable variables. Surfaces the canonical
+  // domain list as a menu.
+  const r = suggestTargetName('Foo/widget/thing');
+  assert.equal(r.kind, 'no-mapping');
   assert.match(r.reason, /No Tailwind v4 domain found in path/);
   assert.match(r.reason, /Expected one of: color, spacing, text/);
 });
diff --git a/plugins/adhd/lib/lint-engine/cli.js b/plugins/adhd/lib/lint-engine/cli.js
index 4482153..eb56a58 100644
--- a/plugins/adhd/lib/lint-engine/cli.js
+++ b/plugins/adhd/lib/lint-engine/cli.js
@@ -158,23 +158,56 @@ function main() {
   if (suggestions.length > 0) {
     const isScoped = designCtx && designCtx.mode !== 'whole-file' && designCtx.id;
     const scopedNodeId = isScoped ? designCtx.id : undefined;
-    const shown = suggestions.slice(0, 10);
-    const lines = shown.map(s => {
-      if (s.kind === 'rename') return `  • ${s.name}\n      → ${s.target}`;
-      if (s.kind === 'no-mapping') return `  • ${s.name}\n      ⚠ ${s.reason}`;
-      return `  • ${s.name}`;
-    });
-    const more = suggestions.length > 10 ? `\n\n  +${suggestions.length - 10} more` : '';
+
+    // Group renames by target collection — the action a designer takes per
+    // group is "create the collection if it doesn't exist, then Move To
+    // these vars into it." Much clearer than a flat list of 6 individually
+    // unrelated-looking rename lines.
+    const renames = suggestions.filter(s => s.kind === 'rename');
+    const ambiguous = suggestions.filter(s => s.kind === 'ambiguous');
+    const noMapping = suggestions.filter(s => s.kind === 'no-mapping');
+    const byTarget = new Map();
+    for (const s of renames) {
+      const collection = s.target.split('/')[0];
+      if (!byTarget.has(collection)) byTarget.set(collection, []);
+      byTarget.get(collection).push(s);
+    }
+    const sortedTargets = [...byTarget.keys()].sort();
+
+    const sections = [];
+    for (const collection of sortedTargets) {
+      const items = byTarget.get(collection);
+      const lines = items.map(s => `  • ${s.name}\n      → ${s.target}`);
+      sections.push(`→ Move to "${collection}" collection (${items.length} var${items.length === 1 ? '' : 's'}):\n${lines.join('\n')}`);
+    }
+    if (ambiguous.length > 0) {
+      const lines = ambiguous.map(s =>
+        `  • ${s.name}\n` +
+        `      ⚠ Ambiguous — ${s.primaryReason}, but ${s.alternateReason}. Pick based on actual usage:\n` +
+        `        Primary:    → ${s.target}\n` +
+        `        Alternate:  → ${s.alternate}`,
+      );
+      sections.push(`⚠ Ambiguous (${ambiguous.length}) — path and leaf disagree on the target domain:\n${lines.join('\n\n')}`);
+    }
+    if (noMapping.length > 0) {
+      const lines = noMapping.map(s => `  • ${s.name}\n      ⚠ ${s.reason}`);
+      sections.push(`⚠ No Tailwind v4 mapping (${noMapping.length}):\n${lines.join('\n\n')}`);
+    }
+
     structureViolations.push({
       rule: 'STRUCT011',
       severity: 'warning',
       nodeId: scopedNodeId,
       nodePath: 'Variables',
       message:
-        `${suggestions.length} variable(s) need renaming for Tailwind v4 alignment:\n\n` +
-        `${lines.join('\n\n')}${more}\n\n` +
-        `For each rename: right-click the variable in Figma → "Rename".\n` +
-        `Tip: you can also create the variable in the suggested collection and point old references at it via aliasing.`,
+        `${suggestions.length} variable-naming issue(s). Suggested restructure:\n\n` +
+        `${sections.join('\n\n')}\n\n` +
+        `How to apply each move in Figma:\n` +
+        `  1. Open the Variables panel; create any missing target collections.\n` +
+        `  2. Right-click the source variable → "Move to..." → pick the target collection. Figma auto-rewires existing references.\n` +
+        `  3. Inside the target, rename to drop redundant path segments (the variable's path within the new collection becomes its full name).\n` +
+        `\n` +
+        `Use Figma's "Move to..." (not "Rename") — Rename only works within the same collection, but most of these are moves across collections.`,
       deepLink: scopedNodeId
         ? 'https://figma.com/design/' + fileKey + '?node-id=' + scopedNodeId.replace(':', '-')
         : args['target-url'],
diff --git a/plugins/adhd/lib/lint-engine/variable-namer.js b/plugins/adhd/lib/lint-engine/variable-namer.js
index 36ece5f..f6d3068 100644
--- a/plugins/adhd/lib/lint-engine/variable-namer.js
+++ b/plugins/adhd/lib/lint-engine/variable-namer.js
@@ -247,6 +247,46 @@ const TIER_COLLECTIONS = new Set([
   'primitives', 'semantic', 'tokens', 'base', 'theme',
 ]);
 
+// Leaf-name keywords that hint at a specific Tailwind v4 domain. When the
+// leaf hints at a DIFFERENT domain than the path's primary signal, we
+// surface the ambiguity instead of confidently picking one.
+// Example: "Type + Effects/Line-Height/Letter Space 0" — path says leading
+// (via Line-Height), leaf says letter-spacing (tracking). The variable
+// could be either; the designer has to decide.
+const LEAF_DOMAIN_HINTS = [
+  // The `spac(?:e|ing)` group covers both "letter space" (Figma designers
+  // often write it this way) and "letter spacing" / "letter-spacing" (CSS
+  // form). Anchoring with \b ensures we strip the full phrase on rename
+  // suggestion, not just the prefix — otherwise "Letter Space 0" loses
+  // "letter spac" and we suggest "Tracking/e-0".
+  { pattern: /\bletter[\s\-_]?spac(?:e|ing)\b/i, domain: 'tracking' },
+  { pattern: /\bline[\s\-_]?height\b/i, domain: 'leading'  },
+  { pattern: /\bfont[\s\-_]?size\b/i,   domain: 'text'     },
+  { pattern: /\bfont[\s\-_]?weight\b/i, domain: 'font-weight' },
+  { pattern: /\bfont[\s\-_]?family\b/i, domain: 'font'     },
+];
+
+function leafHint(leaf) {
+  for (const { pattern, domain } of LEAF_DOMAIN_HINTS) {
+    if (pattern.test(leaf)) return domain;
+  }
+  return null;
+}
+
+// Specific concepts Tailwind v4 doesn't expose as a token domain. Detecting
+// them lets the no-mapping message say "opacity is applied via class
+// modifiers" instead of just listing the canonical domain set.
+function detectKnownNonDomain(segments) {
+  const joined = segments.join(' ').toLowerCase();
+  if (/\bopacity\b/.test(joined)) {
+    return {
+      concept: 'opacity',
+      hint: 'Tailwind v4 has no "opacity" domain — opacity is applied via class modifiers (e.g. `bg-white/50`), not stored as variables. Consider deleting this variable if it isn\'t actively consumed by Tailwind utilities.',
+    };
+  }
+  return null;
+}
+
 function titleCaseDomain(d) {
   return d.split('-').map(w => w ? w[0].toUpperCase() + w.slice(1) : w).join('');
 }
@@ -304,15 +344,48 @@ function suggestTargetName(name) {
     }
   }
   if (!targetDomain) {
+    // No path-based domain hint, but check for known non-Tailwind concepts
+    // (like opacity) so we can surface concept-specific guidance instead of
+    // the generic "expected one of: ...".
+    const knownConcept = detectKnownNonDomain(rest);
     return {
       name, kind: 'no-mapping',
-      reason: `No Tailwind v4 domain found in path. Expected one of: ${TAILWIND_DOMAINS.join(', ')}. Consider whether this variable maps to one of those domains, or if it should be removed.`,
+      reason: knownConcept
+        ? knownConcept.hint
+        : `No Tailwind v4 domain found in path. Expected one of: ${TAILWIND_DOMAINS.join(', ')}. Consider whether this variable maps to one of those domains, or if it should be removed.`,
     };
   }
   const collectionTitle = titleCaseDomain(targetDomain);
   const kept = rest.filter((_, i) => i !== domainIndex);
   const kebabRest = kept.map(s => toCase(s, 'kebab-case')).filter(Boolean).join('/');
   const target = kebabRest ? `${collectionTitle}/${kebabRest}` : collectionTitle;
+
+  // Detect ambiguity: the leaf's own keywords hint at a DIFFERENT domain
+  // than the path-derived one. Common case: a letter-spacing variable filed
+  // inside a "Line-Height" folder. Surface both options instead of
+  // confidently picking the wrong target.
+  const leaf = rest[rest.length - 1];
+  const hint = leafHint(leaf);
+  if (hint && hint !== targetDomain) {
+    const altTitle = titleCaseDomain(hint);
+    // Drop the leaf-keyword phrase from the alternate-collection rename so
+    // it doesn't repeat itself. For "Letter Space 0" moved to Tracking,
+    // the rename target inside Tracking should be just "0" — not
+    // "letter-space-0" which would be redundant with the collection name.
+    const stripped = leaf
+      .toLowerCase()
+      .replace(LEAF_DOMAIN_HINTS.find(h => h.domain === hint).pattern, '')
+      .trim();
+    const altLeaf = toCase(stripped, 'kebab-case') || toCase(leaf, 'kebab-case');
+    const keptForAlt = kept.slice(0, -1).map(s => toCase(s, 'kebab-case')).filter(Boolean);
+    const altPath = [...keptForAlt, altLeaf].filter(Boolean).join('/');
+    const alternate = altPath ? `${altTitle}/${altPath}` : altTitle;
+    return {
+      name, kind: 'ambiguous', target, alternate,
+      primaryReason: `path suggests ${targetDomain}`,
+      alternateReason: `leaf "${leaf}" suggests ${hint}`,
+    };
+  }
   return { name, kind: 'rename', target };
 }
 

From 63c9c2c904901d2f83b868437805d1ac4bda2920 Mon Sep 17 00:00:00 2001
From: Hugh Francis <hughfrancis89@gmail.com>
Date: Tue, 12 May 2026 12:50:39 -0400
Subject: [PATCH 52/79] lint-engine: STRUCT012 + per-layer STRUCT011
 annotations
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

STRUCT012 catches cross-domain variable bindings — e.g. a designer binding
`Spacing/4` to letter-spacing. The variable's name is fine on its own (so
STRUCT011 stays quiet), but the binding crosses Tailwind's token-domain
boundary. Inferred from the variable's name via the same logic the namer
already uses for rename suggestions; ambiguous names produce no
STRUCT012 violation (we'd rather under-report than false-positive).

STRUCT011 now annotates per layer instead of clustering on the scope
root. Each layer that binds a bad-named variable gets its own annotation
so designers can walk the offending layers one by one. Requires the new
`varIdMap` (Figma VariableID → name) emitted by the lint SKILL's
serializer; without it, falls back gracefully to the old aggregated
emission.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 README.md                                     |   2 +-
 .../__tests__/binding-checker.test.js         | 223 ++++++++++++++++++
 .../lib/lint-engine/__tests__/cli.test.js     |  92 ++++++++
 .../adhd/lib/lint-engine/binding-checker.js   | 200 ++++++++++++++++
 plugins/adhd/lib/lint-engine/cli.js           |  66 ++++--
 plugins/adhd/skills/lint/SKILL.md             |  10 +-
 6 files changed, 570 insertions(+), 23 deletions(-)
 create mode 100644 plugins/adhd/lib/lint-engine/__tests__/binding-checker.test.js
 create mode 100644 plugins/adhd/lib/lint-engine/binding-checker.js

diff --git a/README.md b/README.md
index bb9756e..6a302b4 100644
--- a/README.md
+++ b/README.md
@@ -86,7 +86,7 @@ Pass any Figma URL that includes a `node-id` query parameter — `/adhd:lint` wi
 /adhd:lint https://www.figma.com/design/PBCAkpPnvGXWrz6H7qfH3V/ADHD-Reference?node-id=91-18
 ```
 
-The scoped report covers the same rules (STRUCT001–010 + variable mismatches), just narrowed to the selected subtree. The URL must point at the file configured in `adhd.config.ts`; mismatched file keys abort with a fix-up message.
+The scoped report covers the same rules (STRUCT001–012 + variable mismatches), just narrowed to the selected subtree. The URL must point at the file configured in `adhd.config.ts`; mismatched file keys abort with a fix-up message.
 
 ### Annotate violations in Figma (`--annotate`)
 
diff --git a/plugins/adhd/lib/lint-engine/__tests__/binding-checker.test.js b/plugins/adhd/lib/lint-engine/__tests__/binding-checker.test.js
new file mode 100644
index 0000000..082d74f
--- /dev/null
+++ b/plugins/adhd/lib/lint-engine/__tests__/binding-checker.test.js
@@ -0,0 +1,223 @@
+'use strict';
+
+const test = require('node:test');
+const assert = require('node:assert/strict');
+const { checkBindings, inferDomain, PROPERTY_TO_DOMAIN } = require('../binding-checker');
+
+const OPTS = (extra) => ({ fileKey: 'abc', varIdMap: {}, badSuggestionsByName: {}, ...extra });
+
+test('inferDomain: collection-as-domain', () => {
+  assert.equal(inferDomain('Color/brand'), 'color');
+  assert.equal(inferDomain('Spacing/4'), 'spacing');
+  assert.equal(inferDomain('Radius/sm'), 'radius');
+  assert.equal(inferDomain('Tracking/normal'), 'tracking');
+  assert.equal(inferDomain('Leading/relaxed'), 'leading');
+});
+
+test('inferDomain: synonym collection', () => {
+  // "Colors" → "Color" (synonym), so inferred domain is color
+  assert.equal(inferDomain('Colors/brand'), 'color');
+  assert.equal(inferDomain('Space/4'), 'spacing');
+});
+
+test('inferDomain: tier collection looks inside', () => {
+  assert.equal(inferDomain('Primitives/color/brand'), 'color');
+  assert.equal(inferDomain('Semantic/spacing/md'), 'spacing');
+});
+
+test('inferDomain: returns null for ambiguous/unmapped', () => {
+  // ambiguous (path says leading, leaf says tracking)
+  assert.equal(inferDomain('Type + Effects/Line-Height/Letter Space 0'), null);
+  // no-mapping (no domain signal anywhere)
+  assert.equal(inferDomain('Foo/bar/baz'), null);
+});
+
+test('checkBindings: no violations when varIdMap is empty', () => {
+  const root = {
+    id: '1:1', name: 'A', type: 'FRAME',
+    boundVariables: { letterSpacing: { id: 'VAR:1', type: 'VARIABLE_ALIAS' } },
+  };
+  const result = checkBindings(root, OPTS());
+  assert.deepEqual(result, []);
+});
+
+test('STRUCT012: spacing variable bound to letterSpacing fires per-layer', () => {
+  const root = {
+    id: '1:1', name: 'Card', type: 'TEXT',
+    boundVariables: { letterSpacing: { id: 'VAR:spacing4', type: 'VARIABLE_ALIAS' } },
+  };
+  const result = checkBindings(root, OPTS({
+    varIdMap: { 'VAR:spacing4': 'Spacing/4' },
+  }));
+  assert.equal(result.length, 1);
+  const v = result[0];
+  assert.equal(v.rule, 'STRUCT012');
+  assert.equal(v.severity, 'error');
+  assert.equal(v.nodeId, '1:1');
+  assert.equal(v.nodePath, 'Card');
+  assert.match(v.message, /Spacing\/4/);
+  assert.match(v.message, /a spacing variable/);
+  assert.match(v.message, /letterSpacing/);
+  assert.match(v.message, /expects a tracking variable/);
+});
+
+test('STRUCT012: same-domain binding is not flagged', () => {
+  const root = {
+    id: '1:1', name: 'Card', type: 'TEXT',
+    boundVariables: { letterSpacing: { id: 'VAR:trackingNormal' } },
+  };
+  const result = checkBindings(root, OPTS({
+    varIdMap: { 'VAR:trackingNormal': 'Tracking/normal' },
+  }));
+  assert.deepEqual(result, []);
+});
+
+test('STRUCT012: padding bindings flagged when wrong domain', () => {
+  const root = {
+    id: '1:1', name: 'Card', type: 'FRAME',
+    boundVariables: { paddingTop: { id: 'VAR:radiusSm' } },
+  };
+  const result = checkBindings(root, OPTS({
+    varIdMap: { 'VAR:radiusSm': 'Radius/sm' },
+  }));
+  assert.equal(result.length, 1);
+  assert.equal(result[0].rule, 'STRUCT012');
+  assert.match(result[0].message, /Radius\/sm/);
+  assert.match(result[0].message, /spacing/);
+});
+
+test('STRUCT012: corner radius bindings flagged when wrong domain', () => {
+  const root = {
+    id: '1:1', name: 'Card', type: 'FRAME',
+    boundVariables: { topLeftRadius: { id: 'VAR:colorBrand' } },
+  };
+  const result = checkBindings(root, OPTS({
+    varIdMap: { 'VAR:colorBrand': 'Color/brand' },
+  }));
+  assert.equal(result.length, 1);
+  assert.equal(result[0].rule, 'STRUCT012');
+  assert.match(result[0].message, /color/);
+  assert.match(result[0].message, /radius/);
+});
+
+test('STRUCT012: fill color binding crossed with non-color variable', () => {
+  const root = {
+    id: '1:1', name: 'Card', type: 'FRAME',
+    fills: [{ type: 'SOLID', boundVariables: { color: { id: 'VAR:spacingMd' } } }],
+  };
+  const result = checkBindings(root, OPTS({
+    varIdMap: { 'VAR:spacingMd': 'Spacing/md' },
+  }));
+  assert.equal(result.length, 1);
+  assert.equal(result[0].rule, 'STRUCT012');
+  assert.match(result[0].message, /Spacing\/md/);
+});
+
+test('STRUCT012: ambiguous variable name (Line-Height path + Letter Space leaf) does NOT fire — not enough confidence', () => {
+  const root = {
+    id: '1:1', name: 'Title', type: 'TEXT',
+    boundVariables: { letterSpacing: { id: 'VAR:ambig' } },
+  };
+  const result = checkBindings(root, OPTS({
+    varIdMap: { 'VAR:ambig': 'Type + Effects/Line-Height/Letter Space 0' },
+  }));
+  // inferDomain returns null for ambiguous → no STRUCT012
+  assert.deepEqual(result, []);
+});
+
+test('STRUCT011 per-layer: emits one violation per layer that uses a bad variable', () => {
+  // Two layers both bind the same bad-named variable. We want both to be
+  // annotated, not just one aggregate emission.
+  const root = {
+    id: '1:1', name: 'Page', type: 'FRAME',
+    children: [
+      { id: '1:2', name: 'A', type: 'TEXT',
+        boundVariables: { letterSpacing: { id: 'VAR:bad' } } },
+      { id: '1:3', name: 'B', type: 'TEXT',
+        boundVariables: { letterSpacing: { id: 'VAR:bad' } } },
+    ],
+  };
+  const result = checkBindings(root, OPTS({
+    varIdMap: { 'VAR:bad': 'Tracking/BadName' },
+    badSuggestionsByName: {
+      'Tracking/BadName': { name: 'Tracking/BadName', kind: 'rename', target: 'Tracking/bad-name' },
+    },
+  }));
+  const struct011 = result.filter(v => v.rule === 'STRUCT011');
+  assert.equal(struct011.length, 2);
+  const ids = struct011.map(v => v.nodeId).sort();
+  assert.deepEqual(ids, ['1:2', '1:3']);
+  assert.match(struct011[0].message, /Move to "Tracking" collection/);
+  assert.match(struct011[0].message, /final name "Tracking\/bad-name"/);
+});
+
+test('STRUCT011 per-layer: dedupes per (rule, varName) within a single layer', () => {
+  // A layer that binds the same bad variable to BOTH fills.color and
+  // strokes.color should get ONE STRUCT011 violation, not two.
+  const root = {
+    id: '1:1', name: 'A', type: 'FRAME',
+    fills:   [{ type: 'SOLID', boundVariables: { color: { id: 'VAR:bad' } } }],
+    strokes: [{ type: 'SOLID', boundVariables: { color: { id: 'VAR:bad' } } }],
+  };
+  const result = checkBindings(root, OPTS({
+    varIdMap: { 'VAR:bad': 'Color/BrandGold' },
+    badSuggestionsByName: {
+      'Color/BrandGold': { name: 'Color/BrandGold', kind: 'rename', target: 'Color/brand-gold' },
+    },
+  }));
+  const struct011 = result.filter(v => v.rule === 'STRUCT011');
+  assert.equal(struct011.length, 1);
+});
+
+test('STRUCT011 per-layer: emits ambiguous suggestion correctly', () => {
+  const root = {
+    id: '1:1', name: 'Title', type: 'TEXT',
+    boundVariables: { fontSize: { id: 'VAR:ambig' } },
+  };
+  const result = checkBindings(root, OPTS({
+    varIdMap: { 'VAR:ambig': 'Type/Letter Space 0' },
+    badSuggestionsByName: {
+      'Type/Letter Space 0': {
+        name: 'Type/Letter Space 0', kind: 'ambiguous',
+        target: 'Text/letter-space-0', alternate: 'Tracking/0',
+        primaryReason: 'collection suggests text', alternateReason: 'leaf suggests tracking',
+      },
+    },
+  }));
+  const struct011 = result.find(v => v.rule === 'STRUCT011');
+  assert.ok(struct011);
+  assert.match(struct011.message, /Ambiguous target/);
+  assert.match(struct011.message, /primary → Text\/letter-space-0/);
+  assert.match(struct011.message, /alternate → Tracking\/0/);
+});
+
+test('STRUCT011 + STRUCT012 can both fire for the same (node, binding)', () => {
+  // A spacing-domain variable with a BAD name, bound to letterSpacing:
+  //  - STRUCT011 wants to rename the variable
+  //  - STRUCT012 wants to change the binding to a tracking variable
+  // Both fire because they describe different fixes.
+  const root = {
+    id: '1:1', name: 'X', type: 'TEXT',
+    boundVariables: { letterSpacing: { id: 'VAR:bad' } },
+  };
+  const result = checkBindings(root, OPTS({
+    varIdMap: { 'VAR:bad': 'Spacing/BadName' },
+    badSuggestionsByName: {
+      'Spacing/BadName': { name: 'Spacing/BadName', kind: 'rename', target: 'Spacing/bad-name' },
+    },
+  }));
+  const rules = result.map(v => v.rule).sort();
+  assert.deepEqual(rules, ['STRUCT011', 'STRUCT012']);
+});
+
+test('PROPERTY_TO_DOMAIN: covers the expected property set', () => {
+  // Sanity check — if someone removes a property mapping by accident the
+  // STRUCT012 check silently goes quiet for that property. Lock the
+  // mapping down with a test.
+  assert.equal(PROPERTY_TO_DOMAIN.letterSpacing, 'tracking');
+  assert.equal(PROPERTY_TO_DOMAIN.lineHeight,    'leading');
+  assert.equal(PROPERTY_TO_DOMAIN.fontSize,      'text');
+  assert.equal(PROPERTY_TO_DOMAIN.paddingTop,    'spacing');
+  assert.equal(PROPERTY_TO_DOMAIN.itemSpacing,   'spacing');
+  assert.equal(PROPERTY_TO_DOMAIN.cornerRadius,  'radius');
+});
diff --git a/plugins/adhd/lib/lint-engine/__tests__/cli.test.js b/plugins/adhd/lib/lint-engine/__tests__/cli.test.js
index ef5c6f8..8984e3e 100644
--- a/plugins/adhd/lib/lint-engine/__tests__/cli.test.js
+++ b/plugins/adhd/lib/lint-engine/__tests__/cli.test.js
@@ -311,6 +311,98 @@ test('Tailwind-default variables are NEVER reported as missing in code', () => {
   assert.equal(missing.filter(v => v.token === 'color/black').length, 0);
 });
 
+test('STRUCT011 per-layer: with --var-id-map, fires once per layer using the bad var (drops aggregate)', () => {
+  // The user-visible upgrade — annotations land on the layer that actually
+  // uses each bad variable, not lumped onto the scope root. Designers walk
+  // the annotated layers one-by-one instead of cross-referencing a single
+  // multiline message against the layer tree.
+  const varDefs = tmp('vars.json', { 'Tracking/BadName': '0.05em' });
+  const ctx = tmp('ctx.json', {
+    id: '5:1', name: 'Page', type: 'FRAME',
+    children: [
+      { id: '5:2', name: 'A', type: 'TEXT',
+        boundVariables: { letterSpacing: { id: 'VAR:bad' } } },
+      { id: '5:3', name: 'B', type: 'TEXT',
+        boundVariables: { letterSpacing: { id: 'VAR:bad' } } },
+    ],
+  });
+  const idMap = tmp('varidmap.json', { 'VAR:bad': 'Tracking/BadName' });
+  const cssPath = tmp('globals.css', `@theme {} :root {} :root[data-theme="dark"] {}`);
+  const configPath = tmp('adhd.config.ts', `export default { naming: 'kebab-case' };`);
+  const reportPath = path.join(os.tmpdir(), 'adhd-report-' + Date.now() + '.md');
+
+  const result = spawnSync('node', [
+    CLI, '--variable-defs', varDefs, '--var-id-map', idMap, '--design-context', ctx,
+    '--globals-css', cssPath, '--config', configPath, '--target', 'Page',
+    '--target-url', 'https://figma.com/design/abc?node-id=5-1', '--output', reportPath,
+  ], { encoding: 'utf8' });
+
+  const summary = JSON.parse(result.stdout);
+  const struct011 = summary.structure.filter(v => v.rule === 'STRUCT011');
+  // Two layers each get their own violation — no aggregate.
+  assert.equal(struct011.length, 2);
+  const ids = struct011.map(v => v.nodeId).sort();
+  assert.deepEqual(ids, ['5:2', '5:3']);
+  // Per-layer message format
+  assert.match(struct011[0].message, /Layer uses "Tracking\/BadName"/);
+  assert.match(struct011[0].message, /Move to "Tracking" collection/);
+});
+
+test('STRUCT012: cross-domain binding (Spacing var → letterSpacing) fires per-layer', () => {
+  // Designer's `Spacing/4` variable (correctly named for its domain) is
+  // bound to letter-spacing — semantically wrong, but STRUCT011 stays quiet
+  // because the name itself is fine. STRUCT012 catches it.
+  const varDefs = tmp('vars.json', { 'Spacing/4': '1rem' });
+  const ctx = tmp('ctx.json', {
+    id: '5:1', name: 'Title', type: 'TEXT',
+    boundVariables: { letterSpacing: { id: 'VAR:spacing4' } },
+  });
+  const idMap = tmp('varidmap.json', { 'VAR:spacing4': 'Spacing/4' });
+  const cssPath = tmp('globals.css', `@theme {} :root {} :root[data-theme="dark"] {}`);
+  const configPath = tmp('adhd.config.ts', `export default { naming: 'kebab-case' };`);
+  const reportPath = path.join(os.tmpdir(), 'adhd-report-' + Date.now() + '.md');
+
+  const result = spawnSync('node', [
+    CLI, '--variable-defs', varDefs, '--var-id-map', idMap, '--design-context', ctx,
+    '--globals-css', cssPath, '--config', configPath, '--target', 'Title',
+    '--target-url', 'https://figma.com/design/abc?node-id=5-1', '--output', reportPath,
+  ], { encoding: 'utf8' });
+
+  assert.equal(result.status, 1, 'STRUCT012 is severity=error; cli exits 1');
+  const summary = JSON.parse(result.stdout);
+  const struct012 = summary.structure.filter(v => v.rule === 'STRUCT012');
+  assert.equal(struct012.length, 1);
+  assert.equal(struct012[0].nodeId, '5:1');
+  assert.equal(struct012[0].severity, 'error');
+  assert.match(struct012[0].message, /Spacing\/4/);
+  assert.match(struct012[0].message, /spacing variable/);
+  assert.match(struct012[0].message, /tracking variable/);
+  // No STRUCT011 — the name itself is fine.
+  assert.equal(summary.structure.filter(v => v.rule === 'STRUCT011').length, 0);
+});
+
+test('STRUCT012: same-domain binding is silent', () => {
+  // Tracking variable bound to letterSpacing is fine — no violations.
+  const varDefs = tmp('vars.json', { 'Tracking/normal': '0' });
+  const ctx = tmp('ctx.json', {
+    id: '5:1', name: 'Title', type: 'TEXT',
+    boundVariables: { letterSpacing: { id: 'VAR:trackingNormal' } },
+  });
+  const idMap = tmp('varidmap.json', { 'VAR:trackingNormal': 'Tracking/normal' });
+  const cssPath = tmp('globals.css', `@theme {} :root {} :root[data-theme="dark"] {}`);
+  const configPath = tmp('adhd.config.ts', `export default { naming: 'kebab-case' };`);
+  const reportPath = path.join(os.tmpdir(), 'adhd-report-' + Date.now() + '.md');
+
+  const result = spawnSync('node', [
+    CLI, '--variable-defs', varDefs, '--var-id-map', idMap, '--design-context', ctx,
+    '--globals-css', cssPath, '--config', configPath, '--target', 'Title',
+    '--target-url', 'https://figma.com/design/abc?node-id=5-1', '--output', reportPath,
+  ], { encoding: 'utf8' });
+
+  const summary = JSON.parse(result.stdout);
+  assert.equal(summary.structure.filter(v => v.rule === 'STRUCT012').length, 0);
+});
+
 test('STRUCT011: omits nodeId in whole-file mode (no scope root to annotate)', () => {
   const varDefs = tmp('vars.json', { 'Primitives/color/BrandPrimary': '#000' });
   const ctx = tmp('ctx.json', { mode: 'whole-file', pages: [] });
diff --git a/plugins/adhd/lib/lint-engine/binding-checker.js b/plugins/adhd/lib/lint-engine/binding-checker.js
new file mode 100644
index 0000000..6ae57f0
--- /dev/null
+++ b/plugins/adhd/lib/lint-engine/binding-checker.js
@@ -0,0 +1,200 @@
+'use strict';
+
+// Per-layer binding rules.
+//
+// STRUCT011 (variable naming) and STRUCT012 (cross-domain bindings) both
+// need to know which Figma variable each layer binds. The structure-checker
+// can't do it on its own because the node-level boundVariables reference
+// variables by Figma ID — the lint engine needs an ID→name lookup
+// (`varIdMap`) to bridge to the same names the variable-namer reasons about.
+//
+// STRUCT011 emission was historically aggregated onto the scope root (or
+// suppressed in whole-file mode). That made annotations cluster on a
+// single layer even when 10 frames were using the bad variable —
+// designers had to read the message, then hunt for the offending layers
+// themselves. Per-layer emission flips this: each layer that uses a bad
+// variable gets its own annotation, contextualized to where it's used.
+//
+// STRUCT012 covers the cross-domain case the older rules missed — a
+// designer binding e.g. `Spacing/4` to `letterSpacing`. The variable name
+// is fine on its own (so STRUCT011 stays quiet), but the binding is
+// semantically wrong: in Tailwind's domain model, spacing and tracking are
+// distinct token sets and shouldn't share variables. We infer the
+// variable's intended domain from its name (same logic as the namer's
+// suggestion) and compare to the expected domain for the property.
+
+const { suggestTargetName, normalizeCollectionName, classifyDomain, TIER_COLLECTIONS } = require('./variable-namer');
+
+// Figma `boundVariables` property name → Tailwind v4 domain.
+//
+// Properties that don't classify cleanly are intentionally absent — we
+// can't fire STRUCT012 without an expected domain. Width / height could
+// arguably map to `spacing` (Tailwind reuses the spacing scale for
+// sizing) but in practice designers often use other scales there; we'd
+// rather under-report than false-positive. Add entries when real cases
+// surface.
+const PROPERTY_TO_DOMAIN = {
+  fontSize: 'text',
+  fontWeight: 'font-weight',
+  letterSpacing: 'tracking',
+  lineHeight: 'leading',
+  fontFamily: 'font',
+  fontStyle: 'font',
+  paddingTop: 'spacing',
+  paddingRight: 'spacing',
+  paddingBottom: 'spacing',
+  paddingLeft: 'spacing',
+  itemSpacing: 'spacing',
+  cornerRadius: 'radius',
+  topLeftRadius: 'radius',
+  topRightRadius: 'radius',
+  bottomLeftRadius: 'radius',
+  bottomRightRadius: 'radius',
+  // Synthesized for fills/strokes — Figma stores these bindings on each
+  // paint object's own boundVariables rather than at the node level, so
+  // we walk fills/strokes separately and pass these as the property name.
+  'fills[].color': 'color',
+  'strokes[].color': 'color',
+};
+
+// Variable-name → inferred Tailwind domain. Returns the domain string
+// (e.g. 'color', 'spacing') or null if uncertain. Delegates to
+// `suggestTargetName` so the resolution order stays in one place:
+//   1. Collection IS a domain (or its synonym) → that's the domain.
+//   2. Collection is a TIER (Primitives, Semantic, …) → first rest segment.
+//   3. Unknown collection → walk rest looking for a domain segment.
+//   4. Ambiguous or no-mapping → null (don't false-positive STRUCT012).
+function inferDomain(name) {
+  if (!name || typeof name !== 'string') return null;
+  const result = suggestTargetName(name);
+  if (result.kind !== 'ok' && result.kind !== 'rename') return null;
+  const target = result.kind === 'ok' ? name : result.target;
+  const [collection, ...rest] = target.split('/');
+  const collNorm = normalizeCollectionName(collection);
+  const c = classifyDomain(collNorm);
+  if (c.kind === 'known') return collNorm;
+  if (c.kind === 'synonym') return c.suggestion;
+  if (TIER_COLLECTIONS.has(collNorm) && rest.length > 0) {
+    const d = classifyDomain(rest[0]);
+    if (d.kind === 'known') return rest[0].toLowerCase();
+    if (d.kind === 'synonym') return d.suggestion;
+  }
+  return null;
+}
+
+function deepLink(fileKey, nodeId) {
+  return 'https://figma.com/design/' + fileKey + '?node-id=' + nodeId.replace(':', '-');
+}
+
+function formatPerLayerSuggestion(varName, suggestion, prop) {
+  if (suggestion.kind === 'rename') {
+    const targetCollection = suggestion.target.split('/')[0];
+    return `Layer uses "${varName}" (bound to ${prop}). ` +
+      `Move to "${targetCollection}" collection → final name "${suggestion.target}". ` +
+      `In Figma: right-click the variable → "Move to..." → pick "${targetCollection}". ` +
+      `Figma auto-rewires references.`;
+  }
+  if (suggestion.kind === 'ambiguous') {
+    return `Layer uses "${varName}" (bound to ${prop}). Ambiguous target — ` +
+      `${suggestion.primaryReason}, but ${suggestion.alternateReason}. ` +
+      `Pick based on actual usage: primary → ${suggestion.target}, alternate → ${suggestion.alternate}.`;
+  }
+  if (suggestion.kind === 'no-mapping') {
+    return `Layer uses "${varName}" (bound to ${prop}). ${suggestion.reason}`;
+  }
+  return `Layer uses "${varName}" (bound to ${prop}).`;
+}
+
+function walk(node, parentPath, visitor) {
+  const nodePath = parentPath ? parentPath + ' > ' + node.name : node.name;
+  visitor(node, nodePath);
+  if (Array.isArray(node.children)) {
+    for (const c of node.children) walk(c, nodePath, visitor);
+  }
+}
+
+// Walks `rootNode` and emits per-layer STRUCT011 / STRUCT012 violations.
+//
+// `opts.varIdMap`: { '<VariableID>': '<collection>/<name>' }. Without it
+// (no per-binding name lookup) neither rule can fire — caller falls back
+// to the legacy aggregated STRUCT011 emission instead.
+//
+// `opts.badSuggestionsByName`: { '<name>': suggestion } from
+// `buildVariableSuggestions`. STRUCT011 fires per-layer for each binding
+// whose variable name appears here.
+//
+// Violations are deduped per (rule, varName) within a node — a layer that
+// binds the same bad variable to both `fills.color` and `strokes.color`
+// gets ONE annotation, not two. Different variables on the same layer
+// still produce separate violations.
+function checkBindings(rootNode, opts) {
+  const out = [];
+  const varIdMap = opts.varIdMap || {};
+  const badSuggestions = opts.badSuggestionsByName || {};
+  const fileKey = opts.fileKey;
+
+  walk(rootNode, '', (node, nodePath) => {
+    const seen = new Set();
+    const push = (rule, severity, varName, message) => {
+      const key = rule + '::' + varName;
+      if (seen.has(key)) return;
+      seen.add(key);
+      out.push({
+        rule, severity,
+        nodeId: node.id, nodePath, message,
+        deepLink: deepLink(fileKey, node.id),
+      });
+    };
+
+    const handleBinding = (prop, alias) => {
+      if (!alias || !alias.id) return;
+      const varName = varIdMap[alias.id];
+      if (!varName) return;
+
+      const suggestion = badSuggestions[varName];
+      if (suggestion) {
+        push('STRUCT011', 'warning', varName,
+          formatPerLayerSuggestion(varName, suggestion, prop));
+      }
+
+      const expectedDomain = PROPERTY_TO_DOMAIN[prop];
+      if (expectedDomain) {
+        const varDomain = inferDomain(varName);
+        if (varDomain && varDomain !== expectedDomain) {
+          push('STRUCT012', 'error', varName,
+            `Layer binds "${varName}" (a ${varDomain} variable) to ${prop}, ` +
+            `which expects a ${expectedDomain} variable. ` +
+            `Bind a ${expectedDomain}-domain variable instead — or, if you want both ` +
+            `domains to share a value, create a ${expectedDomain} variable that ` +
+            `aliases the same primitive.`);
+        }
+      }
+    };
+
+    if (node.boundVariables && typeof node.boundVariables === 'object') {
+      for (const [prop, alias] of Object.entries(node.boundVariables)) {
+        // fills / strokes / effects arrive as arrays of per-paint bindings
+        // (handled below) — the top-level entry is empty or a stale alias
+        // shape Figma leaves around.
+        if (prop === 'fills' || prop === 'strokes' || prop === 'effects') continue;
+        handleBinding(prop, alias);
+      }
+    }
+    if (Array.isArray(node.fills)) {
+      for (const fill of node.fills) {
+        const alias = fill && fill.boundVariables && fill.boundVariables.color;
+        if (alias) handleBinding('fills[].color', alias);
+      }
+    }
+    if (Array.isArray(node.strokes)) {
+      for (const stroke of node.strokes) {
+        const alias = stroke && stroke.boundVariables && stroke.boundVariables.color;
+        if (alias) handleBinding('strokes[].color', alias);
+      }
+    }
+  });
+
+  return out;
+}
+
+module.exports = { checkBindings, inferDomain, PROPERTY_TO_DOMAIN };
diff --git a/plugins/adhd/lib/lint-engine/cli.js b/plugins/adhd/lib/lint-engine/cli.js
index eb56a58..c5a346a 100644
--- a/plugins/adhd/lib/lint-engine/cli.js
+++ b/plugins/adhd/lib/lint-engine/cli.js
@@ -49,6 +49,7 @@ function loadTailwindDefaultPrimitives() {
 const { categorizeVariables } = require('./variable-categorizer');
 const { checkStructure } = require('./structure-checker');
 const { buildVariableSuggestions } = require('./variable-namer');
+const { checkBindings } = require('./binding-checker');
 const { formatReport } = require('./report-formatter');
 
 function parseArgs(argv) {
@@ -106,6 +107,15 @@ function main() {
   const namingConvention = readNamingConvention(args['config']);
   const fileKey = extractFileKey(args['target-url']);
 
+  // Optional: serializer-produced { '<VariableID>': '<collection>/<name>' }
+  // map. Required for per-layer STRUCT011 annotations and STRUCT012
+  // cross-domain detection; absent in older SKILL versions, in which case
+  // we fall back to the legacy aggregated STRUCT011 emission.
+  let varIdMap = {};
+  if (args['var-id-map']) {
+    try { varIdMap = readJson(args['var-id-map']); } catch { varIdMap = {}; }
+  }
+
   const userTheme = parseTheme(cssText);
   const tailwindDefaults = loadTailwindDefaultPrimitives();
   // User's @theme wins on key collision (override always beats default).
@@ -136,33 +146,53 @@ function main() {
     structureViolations = checkStructure(designCtx, { fileKey, namingConvention });
   }
 
-  // STRUCT011 — variable-name compliance. For each variable, produce ONE
-  // concrete rename target that combines case + domain concerns into a
-  // single actionable suggestion. This is the upgrade from the old
-  // two-section emission, which forced designers to reconcile contradictory
-  // hints ("rename Font-Size to font-size" + "did you mean text?") on
-  // their own — too much cognitive load when 10+ variables are flagged.
+  // STRUCT011 (variable naming) + STRUCT012 (cross-domain bindings).
+  //
+  // Both rules need to know which LAYER uses each variable so the annotation
+  // lands on the offender instead of the scope root — designers asked for
+  // this so they can walk a list of annotations and fix them one by one
+  // without hunting through the layer tree. The binding-checker walks the
+  // node tree and emits one violation per (layer, variable) pair.
   //
-  // The new emission shows: "Type + Effects/Font-Size/Body → Text/body".
-  // One line, complete target. The designer creates the new variable in
-  // the right collection (or renames in place) and moves on.
+  // STRUCT012 catches the cross-domain case STRUCT011 misses: a `Spacing/4`
+  // variable (well-named for its domain) bound to letter-spacing. The
+  // variable's name is fine, but the binding crosses Tailwind's token-domain
+  // boundary. We infer each variable's intended domain from its name and
+  // compare to the property's expected domain.
   //
   // Variable names are ALWAYS checked against kebab-case for the leaves,
   // regardless of the project's `naming` config (which is for component
   // identifiers, not CSS custom properties).
   //
-  // In whole-file mode there's no scope root, so nodeId is omitted —
-  // violation still appears in the report but doesn't annotate.
+  // Fallback: when the SKILL didn't emit a varIdMap (older versions), we
+  // can't bridge per-node bindings to variable names, so STRUCT011 falls
+  // back to the legacy aggregated emission and STRUCT012 stays silent.
   const varKeys = Object.keys(varDefs || {});
   const suggestions = buildVariableSuggestions(varKeys);
-  if (suggestions.length > 0) {
+  const badSuggestionsByName = {};
+  for (const s of suggestions) badSuggestionsByName[s.name] = s;
+  const hasIdMap = Object.keys(varIdMap).length > 0;
+
+  if (hasIdMap) {
+    const bindingViolations = [];
+    if (designCtx && designCtx.mode === 'whole-file' && Array.isArray(designCtx.pages)) {
+      for (const page of designCtx.pages) {
+        for (const node of page.nodes) {
+          const v = checkBindings(node, { fileKey, varIdMap, badSuggestionsByName });
+          for (const x of v) x._page = page.name;
+          bindingViolations.push(...v);
+        }
+      }
+    } else if (designCtx) {
+      bindingViolations.push(...checkBindings(designCtx, { fileKey, varIdMap, badSuggestionsByName }));
+    }
+    structureViolations.push(...bindingViolations);
+  } else if (suggestions.length > 0) {
+    // Legacy aggregated STRUCT011 emission, kept as a graceful fallback
+    // when the SKILL hasn't been upgraded to emit varIdMap. Pre-existing
+    // behavior — single violation on the scope root listing every bad name.
     const isScoped = designCtx && designCtx.mode !== 'whole-file' && designCtx.id;
     const scopedNodeId = isScoped ? designCtx.id : undefined;
-
-    // Group renames by target collection — the action a designer takes per
-    // group is "create the collection if it doesn't exist, then Move To
-    // these vars into it." Much clearer than a flat list of 6 individually
-    // unrelated-looking rename lines.
     const renames = suggestions.filter(s => s.kind === 'rename');
     const ambiguous = suggestions.filter(s => s.kind === 'ambiguous');
     const noMapping = suggestions.filter(s => s.kind === 'no-mapping');
@@ -173,7 +203,6 @@ function main() {
       byTarget.get(collection).push(s);
     }
     const sortedTargets = [...byTarget.keys()].sort();
-
     const sections = [];
     for (const collection of sortedTargets) {
       const items = byTarget.get(collection);
@@ -193,7 +222,6 @@ function main() {
       const lines = noMapping.map(s => `  • ${s.name}\n      ⚠ ${s.reason}`);
       sections.push(`⚠ No Tailwind v4 mapping (${noMapping.length}):\n${lines.join('\n\n')}`);
     }
-
     structureViolations.push({
       rule: 'STRUCT011',
       severity: 'warning',
diff --git a/plugins/adhd/skills/lint/SKILL.md b/plugins/adhd/skills/lint/SKILL.md
index 83e1167..dcb5e1d 100644
--- a/plugins/adhd/skills/lint/SKILL.md
+++ b/plugins/adhd/skills/lint/SKILL.md
@@ -10,7 +10,7 @@ allowed-tools: Read Write Bash AskUserQuestion mcp__plugin_figma_figma__use_figm
 Validate that a Figma file (or a single frame/component/page) is ready for code translation. Reports two classes of issue:
 
 - **Variable issues** — Figma variables used by the lint target that are missing locally or have conflicting values.
-- **Structure issues** — STRUCT001–STRUCT010 best-practice violations (auto-layout, naming, variant properties, etc.).
+- **Structure issues** — STRUCT001–STRUCT012 best-practice violations (auto-layout, naming, variant properties, per-layer variable naming, cross-domain variable bindings, etc.).
 
 Output: a markdown report saved to `/tmp/adhd-lint/report.md`, plus a terminal echo. The report is paste-ready for sharing with designers via Figma comments, Slack, or GitHub issues.
 
@@ -53,14 +53,17 @@ Construct a JS string for `mcp__plugin_figma_figma__use_figma` that:
 2. Branches on a `nodeId` parameter (passed via the `inputs` object on `use_figma`):
    - **Whole-file** (no `nodeId`): walk `figma.root.children` (pages); for each page, find children whose type is `COMPONENT_SET`, or `COMPONENT` (top-level only — i.e. parent is the page, not nested), or `FRAME` (top-level). Serialize each. Return `{ mode: 'whole-file', pages: [{ id, name, nodes: [...serialized...] }, ...] }`.
    - **Scoped** (`nodeId` provided): `await figma.getNodeByIdAsync(nodeId)`; if missing, return `{ error: 'Node not found' }`; otherwise `serializeNode(node)` and return it directly (no `mode` field).
-3. Also collects the variables referenced by the target subtree(s). Walk every `boundVariables` entry across the serialized nodes, dedupe by variable id, look each up via `figma.variables.getVariableByIdAsync`, and return a sibling map `{ vars: { '<collection>/<name>': <resolvedValueForActiveMode> } }`. Use the "primary" mode of each variable's collection. (This is the same shape `get_variable_defs` would have produced from the local MCP.)
+3. Also collects the variables referenced by the target subtree(s). Walk every `boundVariables` entry across the serialized nodes, dedupe by variable id, look each up via `figma.variables.getVariableByIdAsync`, and return two sibling maps:
+   - `vars: { '<collection>/<name>': <resolvedValueForActiveMode> }` — the variable definitions, keyed by name. Same shape `get_variable_defs` would have produced from the local MCP. Use the "primary" mode of each variable's collection.
+   - `varIdMap: { '<VariableID>': '<collection>/<name>' }` — Figma variable ID → name lookup, built from the same dedupe pass. Per-layer lint rules (STRUCT011's per-layer annotations, STRUCT012's cross-domain check) need this to bridge node-level `boundVariables` (which reference variables by ID) to the variable names the engine reasons about. Without it, those rules can't fire.
 
-   The `use_figma` invocation returns a single payload; split it into `{ ctx, vars }` after.
+   The `use_figma` invocation returns a single payload; split it into `{ ctx, vars, varIdMap }` after.
 
 Save the response to `/tmp/adhd-lint/`:
 
 - `/tmp/adhd-lint/ctx.json` — the design-context payload (whole-file shape OR a single serialized subtree).
 - `/tmp/adhd-lint/vars.json` — the `vars` map.
+- `/tmp/adhd-lint/varidmap.json` — the `varIdMap` lookup.
 
 The `Write` tool creates the parent dir on demand. (No `mkdir` needed.)
 
@@ -73,6 +76,7 @@ Use the `Bash` tool. Redirect stdout (the engine's JSON summary) to a temp file
 ```bash
 node plugins/adhd/lib/lint-engine/cli.js \
   --variable-defs /tmp/adhd-lint/vars.json \
+  --var-id-map /tmp/adhd-lint/varidmap.json \
   --design-context /tmp/adhd-lint/ctx.json \
   --globals-css <path-from-config-or-auto-detect> \
   --config adhd.config.ts \

From 46af87d1337a515a86ae0f435696e534111c34e2 Mon Sep 17 00:00:00 2001
From: Hugh Francis <hughfrancis89@gmail.com>
Date: Tue, 12 May 2026 12:59:29 -0400
Subject: [PATCH 53/79] push/pull-tokens: rename from -design-system +
 --dry-run preview
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Renames the slash commands from /adhd:push-design-system and
/adhd:pull-design-system to /adhd:push-tokens and /adhd:pull-tokens.
"Tokens" is the precise term for what these skills move — variables and
named styles, not the whole design system (which also includes
components, conventions, and a docs route handled by other skills).

Adds a --dry-run flag to both. Dry run runs the comparator, formats a
preview (additions per mode, conflicts showing both values, untouched
count from the other side), and exits before any prompts or writes. It's
a pure discovery tool — you can run it any time to see the surface area
of a sync without committing to apply.

Preview shows both values for each conflict rather than pre-resolving;
resolution still belongs in the per-conflict prompt loop. Specs and
plans under docs/superpowers stay frozen (historical), but all live
references in skills + lib code now use the new names.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 README.md                                     | 12 ++-
 plugins/adhd/lib/design-system/README.md      |  4 +-
 .../lib/design-system/__tests__/cli.test.js   | 73 ++++++++++++++
 plugins/adhd/lib/design-system/cli.js         | 96 +++++++++++++++++++
 .../__tests__/variable-categorizer.test.js    |  2 +-
 plugins/adhd/lib/lint-engine/cli.js           |  2 +-
 .../lib/lint-engine/variable-categorizer.js   |  2 +-
 plugins/adhd/skills/config/SKILL.md           |  2 +-
 plugins/adhd/skills/pull-component/SKILL.md   | 18 ++--
 .../SKILL.md                                  | 26 ++++-
 .../SKILL.md                                  | 26 ++++-
 11 files changed, 233 insertions(+), 30 deletions(-)
 rename plugins/adhd/skills/{pull-design-system => pull-tokens}/SKILL.md (73%)
 rename plugins/adhd/skills/{push-design-system => push-tokens}/SKILL.md (81%)

diff --git a/README.md b/README.md
index 6a302b4..310d6aa 100644
--- a/README.md
+++ b/README.md
@@ -30,8 +30,8 @@ After install, nine slash commands are available:
 |---|---|---|---|
 | `/adhd:config` | — | — | Interactive wizard that produces `adhd.config.ts`. Verifies the official Figma plugin is installed + authenticated before anything else. |
 | `/adhd:lint` | `[<figma-url>] [--annotate]` | read-only by default | Validates the Figma file (whole file or scoped) against the local design system + structure best-practices. With `--annotate`, also writes Figma annotations on each offending node in a "lint" category. |
-| `/adhd:push-design-system` | — | code → Figma | Pushes globals.css variables + named styles into Figma directly via the remote MCP |
-| `/adhd:pull-design-system` | — | Figma → code | Pulls Figma variables + named styles into globals.css |
+| `/adhd:push-tokens` | `[--dry-run]` | code → Figma | Pushes globals.css variables + named styles into Figma directly via the remote MCP. `--dry-run` previews what would be added or overwritten without writing. |
+| `/adhd:pull-tokens` | `[--dry-run]` | Figma → code | Pulls Figma variables + named styles into globals.css. `--dry-run` previews without writing. |
 | `/adhd:push-component` | `<path> [--max-variants <n>] [--annotate]` | code → Figma | Pushes a React component to Figma as a structured Component Set with variant properties + variable bindings, plus a preflight lint check. `--annotate` annotates preflight violations on Figma nodes. |
 | `/adhd:push-all-components` | `[--continue-on-error] [--max-variants <n>] [--annotate]` | code → Figma | Bulk version of `push-component` — iterates over every entry in `adhd.config.ts`'s components map. Sequential, halt-on-first-failure by default. |
 | `/adhd:pull-component` | `<path \| figma-url> [--allow-unbound] [--annotate]` | Figma → code | Pulls a Figma Component Set into a React source file; updates lookup tables and union types only (function body untouched). `--annotate` annotates preflight violations on Figma nodes. |
@@ -69,8 +69,10 @@ Then:
 ```
 /adhd:lint                                       # validate the whole Figma file
 /adhd:lint https://figma.com/design/<KEY>?node-id=12-2   # validate a single page/frame/component
-/adhd:push-design-system                         # apply (code → Figma; will prompt before writing)
-/adhd:pull-design-system                         # apply (Figma → code; will prompt before writing)
+/adhd:push-tokens                                # apply (code → Figma; will prompt before writing)
+/adhd:push-tokens --dry-run                      # preview what would change without writing
+/adhd:pull-tokens                                # apply (Figma → code; will prompt before writing)
+/adhd:pull-tokens --dry-run                      # preview what would change without writing
 /adhd:push-component app/components/avatar/index.tsx     # push a React component to Figma
 ```
 
@@ -210,7 +212,7 @@ cd example
 ```
 .
 ├── plugins/adhd/                 # The plugin source
-│   ├── skills/                   # config, lint, push-design-system, pull-design-system
+│   ├── skills/                   # config, lint, push-tokens, pull-tokens
 │   ├── lib/                      # zero-deps Node libraries (lint-engine, design-system)
 │   └── .claude-plugin/           # plugin manifest
 ├── docs/superpowers/
diff --git a/plugins/adhd/lib/design-system/README.md b/plugins/adhd/lib/design-system/README.md
index 6113e16..acac5fe 100644
--- a/plugins/adhd/lib/design-system/README.md
+++ b/plugins/adhd/lib/design-system/README.md
@@ -1,7 +1,7 @@
 # design-system
 
-Pure-JS engine that powers `/adhd:push-design-system` and
-`/adhd:pull-design-system`. Parses both sides (globals.css and Figma
+Pure-JS engine that powers `/adhd:push-tokens` and
+`/adhd:pull-tokens`. Parses both sides (globals.css and Figma
 variables) into a canonical `DesignSystem` shape, compares them, and
 emits conflict reports / write actions.
 
diff --git a/plugins/adhd/lib/design-system/__tests__/cli.test.js b/plugins/adhd/lib/design-system/__tests__/cli.test.js
index a96ea78..2c7ff4d 100644
--- a/plugins/adhd/lib/design-system/__tests__/cli.test.js
+++ b/plugins/adhd/lib/design-system/__tests__/cli.test.js
@@ -69,3 +69,76 @@ test('apply mode produces actions list', () => {
   assert.equal(actions.length, 1);
   assert.equal(actions[0].kind, 'create-variable');
 });
+
+test('preview (push): lists adds + conflicts + figma-only count without writing', () => {
+  // Verifies the dry-run formatter for /adhd:push-tokens --dry-run:
+  // every code-only token shows as an ADD line per mode, every conflict
+  // shows BOTH values (we don't pre-resolve in dry-run), figma-only
+  // tokens are surfaced as a count only.
+  const diff = tmp('diff.json', {
+    same: [],
+    conflict: [
+      { path: 'color/brand-500', mode: 'default', domain: 'color', code: '#aaa', figma: '#bbb' },
+      { path: 'spacing/4',       mode: 'default', domain: 'spacing', code: '1rem',  figma: '0.875rem' },
+    ],
+    codeOnly: [
+      { domain: 'color', path: 'gold/100', values: { default: '#faf0c5' } },
+      { domain: 'color', path: 'surface',  values: { light: '#fff', dark: '#0a0a0a' } },
+    ],
+    figmaOnly: [
+      { domain: 'color', path: 'legacy/old', values: { default: '#123456' } },
+    ],
+  });
+
+  const result = spawnSync('node', [CLI, 'preview', '--diff', diff, '--direction', 'push'], { encoding: 'utf8' });
+  assert.equal(result.status, 0, result.stderr);
+
+  assert.match(result.stdout, /DRY RUN — code → Figma/);
+  // Each codeOnly token expanded per mode → 1 + 2 = 3 ADD rows
+  assert.match(result.stdout, /Would add to Figma \(3 entries\)/);
+  assert.match(result.stdout, /\+ gold\/100/);
+  assert.match(result.stdout, /\+ surface[^\n]+light[^\n]+#fff/);
+  assert.match(result.stdout, /\+ surface[^\n]+dark[^\n]+#0a0a0a/);
+  // Conflict rows show both sides
+  assert.match(result.stdout, /Would prompt for 2 conflicts/);
+  assert.match(result.stdout, /! color\/brand-500[^\n]+code=#aaa[^\n]+figma=#bbb/);
+  // Figma-only count
+  assert.match(result.stdout, /Figma-only \(left untouched per additive policy\): 1 entry/);
+  // Footer
+  assert.match(result.stdout, /To apply: re-run without --dry-run/);
+});
+
+test('preview (pull): flips the direction labels', () => {
+  // Symmetric for pull — figmaOnly becomes ADD, codeOnly becomes the
+  // untouched count.
+  const diff = tmp('diff.json', {
+    same: [], conflict: [],
+    codeOnly: [
+      { domain: 'color', path: 'kept-in-code', values: { default: '#aaa' } },
+    ],
+    figmaOnly: [
+      { domain: 'color', path: 'new-from-figma', values: { default: '#bbb' } },
+    ],
+  });
+
+  const result = spawnSync('node', [CLI, 'preview', '--diff', diff, '--direction', 'pull'], { encoding: 'utf8' });
+  assert.equal(result.status, 0, result.stderr);
+
+  assert.match(result.stdout, /DRY RUN — figma → code/);
+  assert.match(result.stdout, /Would add to code \(1 entry\)/);
+  assert.match(result.stdout, /\+ new-from-figma/);
+  assert.match(result.stdout, /code-only \(left untouched per additive policy\): 1 entry/);
+});
+
+test('preview: errors on missing --diff or invalid --direction', () => {
+  // Sanity: the subcommand must validate its inputs.
+  let r = spawnSync('node', [CLI, 'preview', '--direction', 'push'], { encoding: 'utf8' });
+  assert.equal(r.status, 2);
+
+  const diff = tmp('diff.json', { same: [], conflict: [], codeOnly: [], figmaOnly: [] });
+  r = spawnSync('node', [CLI, 'preview', '--diff', diff], { encoding: 'utf8' });
+  assert.equal(r.status, 2);
+
+  r = spawnSync('node', [CLI, 'preview', '--diff', diff, '--direction', 'bogus'], { encoding: 'utf8' });
+  assert.notEqual(r.status, 0);
+});
diff --git a/plugins/adhd/lib/design-system/cli.js b/plugins/adhd/lib/design-system/cli.js
index b806f36..0e21006 100644
--- a/plugins/adhd/lib/design-system/cli.js
+++ b/plugins/adhd/lib/design-system/cli.js
@@ -28,6 +28,7 @@ function printUsage() {
   console.log(`Usage:
   cli.js compare           --code <globals.css> --figma <figma.json> --output <diff.json>
   cli.js apply             --diff <diff.json> --resolutions <resolutions.json> --direction <push|pull> --output <actions.json>
+  cli.js preview           --diff <diff.json> --direction <push|pull>
   cli.js assemble-extract  --chunks-dir <dir> --output <figma.json>
 
 compare:
@@ -39,6 +40,12 @@ apply:
   conflict). Produces an actions list. For push, actions are Figma
   variable mutations. For pull, actions are CSS edits.
 
+preview:
+  Reads a diff JSON and prints a human-readable dry-run preview to stdout
+  — which variables would be added, which would conflict with existing
+  values on the destination side. No prompts, no writes. Used by
+  /adhd:push-tokens --dry-run and /adhd:pull-tokens --dry-run.
+
 assemble-extract:
   Reads every *.json file in --chunks-dir (responses from
   EXTRACT_CHUNK_SCRIPT — one manifest + one-or-more slices) and merges them
@@ -46,6 +53,85 @@ assemble-extract:
   full design system is too large to fetch in a single use_figma call.`);
 }
 
+// Renders a value (hex string, px string, shadow descriptor, etc.) in a
+// single short token. Shadows / nested objects collapse to a short JSON
+// representation so the alignment column stays sane. Conservative — the
+// preview is for spot-checking, not full fidelity.
+function fmtValue(v) {
+  if (v == null) return '—';
+  if (typeof v === 'string') return v;
+  if (typeof v === 'number') return String(v);
+  try { return JSON.stringify(v); } catch { return String(v); }
+}
+
+// One line per (path, mode). Code-only and figma-only token entries store
+// their values per mode under `values`; conflict entries already arrive
+// flattened by mode.
+function formatPreview(diff, direction) {
+  if (direction !== 'push' && direction !== 'pull') {
+    throw new Error(`preview: --direction must be 'push' or 'pull', got '${direction}'`);
+  }
+  const fromSide = direction === 'push' ? 'code'  : 'figma';
+  const toSide   = direction === 'push' ? 'Figma' : 'code';
+  const fromOnly = direction === 'push' ? diff.codeOnly  : diff.figmaOnly;
+  const toOnly   = direction === 'push' ? diff.figmaOnly : diff.codeOnly;
+
+  const lines = [];
+  lines.push(`DRY RUN — ${fromSide} → ${toSide}. No changes will be applied.`);
+  lines.push('');
+
+  // Additions: tokens that exist only on the source side. Each token may
+  // span multiple modes; emit one row per mode.
+  const addRows = [];
+  for (const tok of fromOnly) {
+    for (const [mode, value] of Object.entries(tok.values || {})) {
+      addRows.push({ path: tok.path, mode, value });
+    }
+  }
+  addRows.sort((a, b) => a.path.localeCompare(b.path) || a.mode.localeCompare(b.mode));
+
+  if (addRows.length === 0) {
+    lines.push(`Would add to ${toSide}: none.`);
+  } else {
+    lines.push(`Would add to ${toSide} (${addRows.length} entr${addRows.length === 1 ? 'y' : 'ies'}):`);
+    const pathW = Math.max(...addRows.map(r => r.path.length));
+    const modeW = Math.max(...addRows.map(r => r.mode.length));
+    for (const r of addRows) {
+      lines.push(`  + ${r.path.padEnd(pathW)}  (${r.mode.padEnd(modeW)})  = ${fmtValue(r.value)}`);
+    }
+  }
+  lines.push('');
+
+  // Conflicts: same path on both sides, different value per mode. Show
+  // BOTH sides so the user can judge — the dry run intentionally doesn't
+  // pre-resolve in favor of either side, since the prompt loop in Phase 4
+  // is where resolution happens.
+  const conflicts = diff.conflict || [];
+  if (conflicts.length === 0) {
+    lines.push(`Would overwrite in ${toSide}: none.`);
+  } else {
+    lines.push(`Would prompt for ${conflicts.length} conflict${conflicts.length === 1 ? '' : 's'} (existing on both sides, values differ):`);
+    const pathW = Math.max(...conflicts.map(c => c.path.length));
+    const modeW = Math.max(...conflicts.map(c => c.mode.length));
+    for (const c of conflicts) {
+      lines.push(`  ! ${c.path.padEnd(pathW)}  (${c.mode.padEnd(modeW)})  code=${fmtValue(c.code)}  figma=${fmtValue(c.figma)}`);
+    }
+    lines.push('');
+    lines.push(`  Per-conflict prompts let you keep ${fromSide}'s value or ${toSide === 'Figma' ? toSide.toLowerCase() : toSide}'s. Either way, no removal — only the chosen value is written.`);
+  }
+  lines.push('');
+
+  // Other-side-only: tokens that exist only on the destination. The
+  // additive policy means we never delete these; they're shown only so
+  // the user understands the full surface.
+  const toOnlyCount = (toOnly || []).reduce((n, t) => n + Object.keys(t.values || {}).length, 0);
+  lines.push(`${toSide}-only (left untouched per additive policy): ${toOnlyCount} entr${toOnlyCount === 1 ? 'y' : 'ies'}.`);
+  lines.push('');
+  lines.push(`To apply: re-run without --dry-run.`);
+
+  return lines.join('\n');
+}
+
 function main() {
   const args = parseArgs(process.argv);
   if (args.help) { printUsage(); process.exit(0); }
@@ -73,6 +159,14 @@ function main() {
     process.exit(0);
   }
 
+  if (cmd === 'preview') {
+    if (!args.diff) { console.error('Missing --diff'); process.exit(2); }
+    if (!args.direction) { console.error('Missing --direction'); process.exit(2); }
+    const diff = JSON.parse(fs.readFileSync(args.diff, 'utf8'));
+    process.stdout.write(formatPreview(diff, args.direction) + '\n');
+    process.exit(0);
+  }
+
   if (cmd === 'assemble-extract') {
     const dir = args['chunks-dir'];
     if (!dir) { console.error('Missing --chunks-dir'); process.exit(2); }
@@ -89,3 +183,5 @@ function main() {
 }
 
 main();
+
+module.exports = { formatPreview };
diff --git a/plugins/adhd/lib/lint-engine/__tests__/variable-categorizer.test.js b/plugins/adhd/lib/lint-engine/__tests__/variable-categorizer.test.js
index 45afd2b..19f7140 100644
--- a/plugins/adhd/lib/lint-engine/__tests__/variable-categorizer.test.js
+++ b/plugins/adhd/lib/lint-engine/__tests__/variable-categorizer.test.js
@@ -72,7 +72,7 @@ test('missing variables include a suggested-fix hint', () => {
   );
   const m = violations.find(v => v.status === 'missing');
   assert.ok(m);
-  assert.equal(m.hint, 'Run /adhd:pull-design-system to import this token.');
+  assert.equal(m.hint, 'Run /adhd:pull-tokens to import this token.');
 });
 
 test('does NOT flag a conflict when both sides are aliases (semantic→primitive)', () => {
diff --git a/plugins/adhd/lib/lint-engine/cli.js b/plugins/adhd/lib/lint-engine/cli.js
index c5a346a..2cf31ca 100644
--- a/plugins/adhd/lib/lint-engine/cli.js
+++ b/plugins/adhd/lib/lint-engine/cli.js
@@ -24,7 +24,7 @@ const { parseTheme } = require('./theme-parser');
 // Tailwind v4 ships a full default @theme: --color-white, --color-black,
 // --color-red-500, --spacing, the --text-* / --leading-* scales, etc.
 // `lib/design-system/tailwind-defaults.css` carries the canonical copy
-// (already used by push/pull-design-system via parseCodeDesignSystem).
+// (already used by push/pull-tokens via parseCodeDesignSystem).
 // We merge those defaults into the user's parsed primitives BEFORE the
 // variable comparator runs — otherwise a Figma `Color/white` variable
 // would surface as "missing in code" even though Tailwind covers it,
diff --git a/plugins/adhd/lib/lint-engine/variable-categorizer.js b/plugins/adhd/lib/lint-engine/variable-categorizer.js
index 592d6a4..be7a1ca 100644
--- a/plugins/adhd/lib/lint-engine/variable-categorizer.js
+++ b/plugins/adhd/lib/lint-engine/variable-categorizer.js
@@ -49,7 +49,7 @@ function compareOne(figmaPath, figmaValue, theme, mode) {
       local: null,
       mode,
       domain,
-      hint: 'Run /adhd:pull-design-system to import this token.',
+      hint: 'Run /adhd:pull-tokens to import this token.',
     };
   }
   // Both sides agree this is an alias relationship — no surface-value comparison
diff --git a/plugins/adhd/skills/config/SKILL.md b/plugins/adhd/skills/config/SKILL.md
index 5fa5928..46d7cff 100644
--- a/plugins/adhd/skills/config/SKILL.md
+++ b/plugins/adhd/skills/config/SKILL.md
@@ -33,7 +33,7 @@ Pass these forward as defaults for Phases 1, 2, and 3.
 
 ## Phase 0.5: Verify the official Figma plugin is installed and authenticated
 
-ADHD requires the `figma@claude-plugins-official` Claude Code plugin — every other skill (`/adhd:lint`, `/adhd:push-design-system`, `/adhd:pull-design-system`, `/adhd:push-component`, `/adhd:pull-component`) drives Figma exclusively through it via `mcp__plugin_figma_figma__*`. This phase verifies it's installed and authenticated up front, so users hit setup errors here (when they can act on them) rather than mid-pipeline.
+ADHD requires the `figma@claude-plugins-official` Claude Code plugin — every other skill (`/adhd:lint`, `/adhd:push-tokens`, `/adhd:pull-tokens`, `/adhd:push-component`, `/adhd:pull-component`) drives Figma exclusively through it via `mcp__plugin_figma_figma__*`. This phase verifies it's installed and authenticated up front, so users hit setup errors here (when they can act on them) rather than mid-pipeline.
 
 Call `mcp__plugin_figma_figma__whoami`. It's read-only and returns the authenticated Figma user's identity.
 
diff --git a/plugins/adhd/skills/pull-component/SKILL.md b/plugins/adhd/skills/pull-component/SKILL.md
index 0860877..0417d2d 100644
--- a/plugins/adhd/skills/pull-component/SKILL.md
+++ b/plugins/adhd/skills/pull-component/SKILL.md
@@ -143,7 +143,7 @@ Check whether the escape is active:
 These need to be bound to design-system variables before we can pull. The designer can:
   1. Bind them in Figma (right-click the layer → "Apply variable")
   2. Or create new variables if these are new design tokens, then run
-     /adhd:pull-design-system first, then re-run /adhd:pull-component
+     /adhd:pull-tokens first, then re-run /adhd:pull-component
 
 We don't generate arbitrary Tailwind classes like text-[20px] or h-[80px] in your
 code — those would leak the design system the moment they shipped.
@@ -189,12 +189,12 @@ If BOTH STRUCT011 AND variable-binding errors are present, surface STRUCT011 fir
 Once preflight passes (no STRUCT011, no unbound errors or escape engaged), check the lint engine's variable mismatches in `/tmp/adhd-pull-component/stdout.json`. The categorizer reports two interesting statuses for our purpose:
 
 - **`status: "missing"`** — Figma has the variable, code's `globals.css` doesn't. New to the design system. (The lint engine merges Tailwind v4's default theme into the comparison BEFORE evaluating "missing" — so vars like `Color/white` that Tailwind already provides won't surface here. Never propose adding something to globals.css that Tailwind covers implicitly.)
-- **`status: "conflict"`** — both sides have the variable but values disagree. NOT touched by pull-component; this is `/adhd:pull-design-system`'s job.
+- **`status: "conflict"`** — both sides have the variable but values disagree. NOT touched by pull-component; this is `/adhd:pull-tokens`'s job.
 
 Split missing further by the categorizer's `mode` field:
 
 - `mode === undefined` → **primitive**. Auto-addable: a single `@theme` entry.
-- `mode === "light" | "dark"` → **semantic with modes**. Needs coordinated `:root`, `.dark`, and `@theme inline` edits — too much surface to do as a side-effect of pull-component. Surfaced in the prompt with a "run /adhd:pull-design-system for these" note.
+- `mode === "light" | "dark"` → **semantic with modes**. Needs coordinated `:root`, `.dark`, and `@theme inline` edits — too much surface to do as a side-effect of pull-component. Surfaced in the prompt with a "run /adhd:pull-tokens for these" note.
 
 If `missingPrimitives.length === 0 && missingSemantics.length === 0 && conflicts.length === 0`, skip this phase entirely.
 
@@ -212,21 +212,21 @@ Primitives (add to @theme):
 Semantic tokens with light/dark modes (not auto-addable):
   color/text/primary  (light: #111, dark: #fafafa)
   color/surface       (light: #fff, dark: #0a0a0a)
-Run /adhd:pull-design-system to add these — they need coordinated
+Run /adhd:pull-tokens to add these — they need coordinated
 `:root`, `.dark`, and `@theme inline` edits.
 
 [if conflicts > 0]
 Variables with value mismatches (existing in code, different in Figma):
   color/brand/500     code=#5e3aee  figma=#6a4cf2
-Run /adhd:pull-design-system to resolve.
+Run /adhd:pull-tokens to resolve.
 
 Options:
   [Yes — add the <N> primitives and continue]
   [No — continue without adding (component pull may land raw values)]
-  [Cancel — abort, I'll run /adhd:pull-design-system first]
+  [Cancel — abort, I'll run /adhd:pull-tokens first]
 ```
 
-On **Yes**: build an actions array for each primitive and invoke `applyToCss` (the helper `pull-design-system` already uses for CSS edits). Save under `/tmp/adhd-pull-component/new-globals.css`, then write to the configured `globals.css` path:
+On **Yes**: build an actions array for each primitive and invoke `applyToCss` (the helper `pull-tokens` already uses for CSS edits). Save under `/tmp/adhd-pull-component/new-globals.css`, then write to the configured `globals.css` path:
 
 ```bash
 node -e '
@@ -245,9 +245,9 @@ Print a confirmation: `Added <N> primitive(s) to globals.css: <comma-separated l
 
 On **No**: continue without writing. The component pull proceeds; un-tracked variables may land as raw values or `// adhd:off-system` markers in the lookup tables.
 
-On **Cancel**: abort with `Run /adhd:pull-design-system first to sync the design system, then re-run /adhd:pull-component.`
+On **Cancel**: abort with `Run /adhd:pull-tokens first to sync the design system, then re-run /adhd:pull-component.`
 
-Skip this phase if conflicts exist BUT no missing — there's nothing additive to do, just print: `Note: <N> variable value(s) differ between Figma and code. Run /adhd:pull-design-system to reconcile.` Then continue (conflicts don't block pull-component v1; the pull works with code's value, drift is reported in the final report).
+Skip this phase if conflicts exist BUT no missing — there's nothing additive to do, just print: `Note: <N> variable value(s) differ between Figma and code. Run /adhd:pull-tokens to reconcile.` Then continue (conflicts don't block pull-component v1; the pull works with code's value, drift is reported in the final report).
 
 ## Phase 3: Read both sides
 
diff --git a/plugins/adhd/skills/pull-design-system/SKILL.md b/plugins/adhd/skills/pull-tokens/SKILL.md
similarity index 73%
rename from plugins/adhd/skills/pull-design-system/SKILL.md
rename to plugins/adhd/skills/pull-tokens/SKILL.md
index 66b0e21..fd70406 100644
--- a/plugins/adhd/skills/pull-design-system/SKILL.md
+++ b/plugins/adhd/skills/pull-tokens/SKILL.md
@@ -1,23 +1,25 @@
 ---
-description: "Pull the design system (variables + named styles) from the configured Figma file into globals.css. Two-way diff with per-attribute conflict prompts; additive (never deletes from code). Reads adhd.config.ts at the repo root."
+description: "Pull design tokens (variables + named styles) from the configured Figma file into globals.css. Two-way diff with per-attribute conflict prompts; additive (never deletes from code). Reads adhd.config.ts at the repo root. Pass --dry-run to preview without writing."
 disable-model-invocation: true
-argument-hint: ""
+argument-hint: "[--dry-run]"
 allowed-tools: Read Write Edit Bash AskUserQuestion mcp__plugin_figma_figma__use_figma
 ---
 
-# ADHD Pull Design System
+# ADHD Pull Tokens
 
 Pulls Figma's design tokens (variables + named styles) into the codebase's `globals.css`. Compares both sides; for each conflicting variable, prompts the user; for variables that exist only in Figma, creates them in code; for variables that exist only in code, leaves them alone (additive policy).
 
+Pass `--dry-run` to see exactly what would be added or overwritten without making any changes — no prompts, no writes, no commits.
+
 **Authoritative spec:** `docs/superpowers/specs/2026-05-10-adhd-push-pull-design-system.md`
 
 ## Phase 1: Validate config
 
-(Same as /adhd:push-design-system Phase 1.)
+(Same as /adhd:push-tokens Phase 1.)
 
 ## Phase 2: Read both sides
 
-(Same as /adhd:push-design-system Phase 2 — read globals.css, run extract script via use_figma, save both to `/tmp/adhd-pull/`. Use Strategy B — chunked extraction — for any non-trivial design system; the MCP truncates single-shot responses around 20–30 KB and a full Tailwind v4 color collection blows past that limit. The push SKILL documents the chunked manifest + slice + `cli.js assemble-extract` flow.)
+(Same as /adhd:push-tokens Phase 2 — read globals.css, run extract script via use_figma, save both to `/tmp/adhd-pull/`. Use Strategy B — chunked extraction — for any non-trivial design system; the MCP truncates single-shot responses around 20–30 KB and a full Tailwind v4 color collection blows past that limit. The push SKILL documents the chunked manifest + slice + `cli.js assemble-extract` flow.)
 
 ## Phase 3: Run the comparator
 
@@ -30,6 +32,20 @@ node plugins/adhd/lib/design-system/cli.js compare \
 
 If `conflict.length === 0` and `figmaOnly.length === 0`, print "Code is already in sync with Figma. No changes." and exit 0.
 
+## Phase 3b: Dry run (only if `--dry-run` was passed)
+
+If the user invoked `/adhd:pull-tokens --dry-run`, print the preview from the comparator and exit BEFORE the prompt loop. The dry run is a pure discovery tool — no `AskUserQuestion`, no writes, no commits, no MCP traffic beyond Phase 2's extract:
+
+```bash
+node plugins/adhd/lib/design-system/cli.js preview \
+  --diff /tmp/adhd-pull/diff.json \
+  --direction pull
+```
+
+The preview lists every variable that would be added to `globals.css` (one row per mode), every variable whose Figma/code values differ (showing both — the dry run intentionally doesn't pre-resolve in favor of either side), and the count of code-only variables that would stay untouched per the additive policy. Echo the output verbatim to the user, then print a one-line summary: `Dry run complete. Re-run without --dry-run to apply (you'll be prompted on each conflict).` Exit 0.
+
+If `--dry-run` was NOT passed, skip this phase and continue to Phase 4.
+
 ## Phase 4: Resolve conflicts
 
 For each conflict in `diff.conflict`, use `AskUserQuestion` with:
diff --git a/plugins/adhd/skills/push-design-system/SKILL.md b/plugins/adhd/skills/push-tokens/SKILL.md
similarity index 81%
rename from plugins/adhd/skills/push-design-system/SKILL.md
rename to plugins/adhd/skills/push-tokens/SKILL.md
index 3904fd4..9addd9f 100644
--- a/plugins/adhd/skills/push-design-system/SKILL.md
+++ b/plugins/adhd/skills/push-tokens/SKILL.md
@@ -1,14 +1,16 @@
 ---
-description: "Push the local design system (globals.css variables + named styles) into the configured Figma file. Two-way diff with per-attribute conflict prompts; additive (never deletes from Figma). Reads adhd.config.ts at the repo root."
+description: "Push the local design tokens (globals.css variables + named styles) into the configured Figma file. Two-way diff with per-attribute conflict prompts; additive (never deletes from Figma). Reads adhd.config.ts at the repo root. Pass --dry-run to preview without writing."
 disable-model-invocation: true
-argument-hint: ""
+argument-hint: "[--dry-run]"
 allowed-tools: Read Write Edit Bash AskUserQuestion mcp__plugin_figma_figma__use_figma
 ---
 
-# ADHD Push Design System
+# ADHD Push Tokens
 
 Pushes the codebase's design tokens (variables + named styles) into the configured Figma file. Compares both sides; for each conflicting variable, prompts the user; for variables that exist only in code, creates them in Figma; for variables that exist only in Figma, leaves them alone (additive policy).
 
+Pass `--dry-run` to see exactly what would be added or overwritten without making any changes — no prompts, no writes, no MCP traffic beyond the initial extract.
+
 **Authoritative spec:** `docs/superpowers/specs/2026-05-10-adhd-push-pull-design-system.md`
 
 ## Phase 1: Validate config
@@ -48,6 +50,20 @@ Read `/tmp/adhd-push/diff.json`. The diff has four arrays: `same`, `conflict`, `
 
 If `conflict.length === 0` and `codeOnly.length === 0`, print "Figma is already in sync with code. No changes." and exit 0.
 
+## Phase 3b: Dry run (only if `--dry-run` was passed)
+
+If the user invoked `/adhd:push-tokens --dry-run`, print the preview from the comparator and exit BEFORE the prompt loop. The dry run is a pure discovery tool — no `AskUserQuestion`, no writes, no MCP traffic beyond Phase 2's extract:
+
+```bash
+node plugins/adhd/lib/design-system/cli.js preview \
+  --diff /tmp/adhd-push/diff.json \
+  --direction push
+```
+
+The preview lists every variable that would be added to Figma (one row per mode), every variable whose code/Figma values differ (showing both — the dry run intentionally doesn't pre-resolve in favor of either side), and the count of Figma-only variables that would stay untouched per the additive policy. Echo the output verbatim to the user, then print a one-line summary: `Dry run complete. Re-run without --dry-run to apply (you'll be prompted on each conflict).` Exit 0.
+
+If `--dry-run` was NOT passed, skip this phase and continue to Phase 4.
+
 ## Phase 4: Resolve conflicts via AskUserQuestion
 
 For each conflict in `diff.conflict`, use `AskUserQuestion` with these four options:
@@ -82,7 +98,7 @@ Re-run the extract script via `use_figma` (same call as Phase 2). Save the respo
 diff /tmp/adhd-push/figma.json /tmp/adhd-push/figma-recheck.json
 ```
 
-If they differ, abort with: "Figma drifted during this run. Re-run /adhd:push-design-system to see fresh conflicts." Exit 1.
+If they differ, abort with: "Figma drifted during this run. Re-run /adhd:push-tokens to see fresh conflicts." Exit 1.
 
 ## Phase 7: Apply actions to Figma
 
@@ -108,5 +124,5 @@ Print:
 |---|---|
 | `adhd.config.ts not found` | Run `/adhd:config`. |
 | `globals.css not found` | Pass `cssEntry` in adhd.config.ts or place the file at `app/globals.css`. |
-| `Figma drifted during this run` | Someone changed Figma while you were resolving conflicts. Re-run `/adhd:push-design-system`. |
+| `Figma drifted during this run` | Someone changed Figma while you were resolving conflicts. Re-run `/adhd:push-tokens`. |
 | `Figma MCP unreachable` | Verify the figma plugin is installed: `claude plugin install figma@claude-plugins-official`. |

From bc68e9e7750e7221aeb870812ae1c08e69e8ed20 Mon Sep 17 00:00:00 2001
From: Hugh Francis <hughfrancis89@gmail.com>
Date: Tue, 12 May 2026 13:27:57 -0400
Subject: [PATCH 54/79] lint: STRUCT013 + --fix for Tailwind-default duplicates
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

STRUCT013 surfaces Figma variables that duplicate a Tailwind v4 default
— same canonical name, same value. After designers push the full
Tailwind palette to Figma via /adhd:push-tokens, any leftover custom
variables that match a default by both name and value are flagged for
consolidation.

Strict match only: both normalized name AND value have to align. A
semantically-named variable like `Color/MyZinc` that happens to equal
`--color-zinc-500` is intentionally NOT surfaced — the designer's
naming choice signals intent we should respect.

/adhd:lint --fix walks each candidate via AskUserQuestion. Approved
consolidations rebind every layer that uses the duplicate to the
canonical Tailwind variable, then delete the duplicate. The rebind
covers scalar bindings (letterSpacing, padding, *Radius, etc.) plus
per-paint fills/strokes bindings. Pre-flight check ensures the canonical
Tailwind variable exists in Figma — if not, the candidate is held back
with a clear message to run /adhd:push-tokens first.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 README.md                                     |   2 +-
 .../lib/lint-engine/__tests__/cli.test.js     |  51 ++++++
 .../tailwind-duplicate-detector.test.js       |  84 ++++++++++
 plugins/adhd/lib/lint-engine/cli.js           |  39 +++++
 .../tailwind-duplicate-detector.js            | 106 ++++++++++++
 plugins/adhd/skills/lint/SKILL.md             | 157 +++++++++++++++++-
 6 files changed, 433 insertions(+), 6 deletions(-)
 create mode 100644 plugins/adhd/lib/lint-engine/__tests__/tailwind-duplicate-detector.test.js
 create mode 100644 plugins/adhd/lib/lint-engine/tailwind-duplicate-detector.js

diff --git a/README.md b/README.md
index 310d6aa..aa7e68b 100644
--- a/README.md
+++ b/README.md
@@ -29,7 +29,7 @@ After install, nine slash commands are available:
 | Command | Args | Direction | What it does |
 |---|---|---|---|
 | `/adhd:config` | — | — | Interactive wizard that produces `adhd.config.ts`. Verifies the official Figma plugin is installed + authenticated before anything else. |
-| `/adhd:lint` | `[<figma-url>] [--annotate]` | read-only by default | Validates the Figma file (whole file or scoped) against the local design system + structure best-practices. With `--annotate`, also writes Figma annotations on each offending node in a "lint" category. |
+| `/adhd:lint` | `[<figma-url>] [--annotate] [--fix]` | read-only by default | Validates the Figma file (whole file or scoped) against the local design system + structure best-practices. With `--annotate`, also writes Figma annotations on each offending node in a "lint" category. With `--fix`, walks STRUCT013 Tailwind-duplicate candidates per-prompt and consolidates approved ones (rebinds bindings to the canonical Tailwind variable, then deletes the duplicate). |
 | `/adhd:push-tokens` | `[--dry-run]` | code → Figma | Pushes globals.css variables + named styles into Figma directly via the remote MCP. `--dry-run` previews what would be added or overwritten without writing. |
 | `/adhd:pull-tokens` | `[--dry-run]` | Figma → code | Pulls Figma variables + named styles into globals.css. `--dry-run` previews without writing. |
 | `/adhd:push-component` | `<path> [--max-variants <n>] [--annotate]` | code → Figma | Pushes a React component to Figma as a structured Component Set with variant properties + variable bindings, plus a preflight lint check. `--annotate` annotates preflight violations on Figma nodes. |
diff --git a/plugins/adhd/lib/lint-engine/__tests__/cli.test.js b/plugins/adhd/lib/lint-engine/__tests__/cli.test.js
index 8984e3e..7e55e60 100644
--- a/plugins/adhd/lib/lint-engine/__tests__/cli.test.js
+++ b/plugins/adhd/lib/lint-engine/__tests__/cli.test.js
@@ -403,6 +403,57 @@ test('STRUCT012: same-domain binding is silent', () => {
   assert.equal(summary.structure.filter(v => v.rule === 'STRUCT012').length, 0);
 });
 
+test('STRUCT013: surfaces Figma variables that duplicate Tailwind defaults (strict match)', () => {
+  // Designer pushed the full Tailwind palette to Figma, then left their
+  // legacy `Color/white` sitting alongside the canonical `--color-white`.
+  // Same name, same value → flag for consolidation. A coincidental value
+  // match on a differently-named variable (`Color/Background`) is NOT
+  // flagged — semantic intent is respected.
+  //
+  // We use the white/black defaults here rather than a zinc shade because
+  // Tailwind's color palette ships as oklch() in tailwind-defaults.css —
+  // a hex fixture wouldn't string-match. The user's real Figma files
+  // typically resolve all variables to a consistent format (Figma
+  // converts oklch to hex for the resolved value); a fully realistic
+  // fixture would mock that resolution.
+  const varDefs = tmp('vars.json', {
+    'Color/white':      '#fff',      // dupe — same name + value as Tailwind default
+    'Color/Background': '#fff',      // semantic — value matches but name doesn't, no fire
+    'Color/brand':      '#5e3aee',   // not a Tailwind default at all
+    'Spacing/default':  '0.25rem',   // dupe of --spacing
+  });
+  const idMap = tmp('varidmap.json', {
+    'VAR:white':   'Color/white',
+    'VAR:spacing': 'Spacing/default',
+  });
+  const ctx = tmp('ctx.json', { id: '5:1', name: 'X', type: 'FRAME', layoutMode: 'VERTICAL' });
+  const cssPath = tmp('globals.css', `@theme {} :root {} :root[data-theme="dark"] {}`);
+  const configPath = tmp('adhd.config.ts', `export default { naming: 'kebab-case' };`);
+  const reportPath = path.join(os.tmpdir(), 'adhd-report-' + Date.now() + '.md');
+
+  const result = spawnSync('node', [
+    CLI, '--variable-defs', varDefs, '--var-id-map', idMap, '--design-context', ctx,
+    '--globals-css', cssPath, '--config', configPath, '--target', 'X',
+    '--target-url', 'https://figma.com/design/abc?node-id=5-1', '--output', reportPath,
+  ], { encoding: 'utf8' });
+
+  const summary = JSON.parse(result.stdout);
+  const struct013 = summary.structure.filter(v => v.rule === 'STRUCT013');
+  // Only `Color/white` fires — `Color/Background` has the same value but
+  // a different name (semantic intent respected), `Color/brand` isn't a
+  // Tailwind default at all, and `Spacing/default` normalizes to
+  // "spacing-default" which doesn't align with `--spacing`'s canonical
+  // form (strict name match).
+  assert.equal(struct013.length, 1);
+  const v = struct013[0];
+  assert.equal(v.severity, 'warning');
+  assert.equal(v.figmaVarName, 'Color/white');
+  assert.equal(v.figmaVarId, 'VAR:white');
+  assert.equal(v.tailwindCssVar, '--color-white');
+  assert.match(v.message, /duplicates Tailwind default `--color-white`/);
+  assert.match(v.message, /\/adhd:lint --fix/);
+});
+
 test('STRUCT011: omits nodeId in whole-file mode (no scope root to annotate)', () => {
   const varDefs = tmp('vars.json', { 'Primitives/color/BrandPrimary': '#000' });
   const ctx = tmp('ctx.json', { mode: 'whole-file', pages: [] });
diff --git a/plugins/adhd/lib/lint-engine/__tests__/tailwind-duplicate-detector.test.js b/plugins/adhd/lib/lint-engine/__tests__/tailwind-duplicate-detector.test.js
new file mode 100644
index 0000000..286b842
--- /dev/null
+++ b/plugins/adhd/lib/lint-engine/__tests__/tailwind-duplicate-detector.test.js
@@ -0,0 +1,84 @@
+'use strict';
+
+const test = require('node:test');
+const assert = require('node:assert/strict');
+const {
+  detectTailwindDuplicates,
+  normalizeFigmaVarName,
+} = require('../tailwind-duplicate-detector');
+
+test('normalizeFigmaVarName: domain-as-collection', () => {
+  assert.equal(normalizeFigmaVarName('Color/zinc-500'), 'color-zinc-500');
+  assert.equal(normalizeFigmaVarName('Spacing/4'), 'spacing-4');
+  assert.equal(normalizeFigmaVarName('Radius/sm'), 'radius-sm');
+});
+
+test('normalizeFigmaVarName: tier collection stripped', () => {
+  // Primitives is a tier — its prefix is invisible.
+  assert.equal(normalizeFigmaVarName('Primitives/color/zinc/500'), 'color-zinc-500');
+  assert.equal(normalizeFigmaVarName('Semantic/spacing/md'), 'spacing-md');
+});
+
+test('normalizeFigmaVarName: PascalCase / camelCase leaf is kebabed', () => {
+  assert.equal(normalizeFigmaVarName('Color/BrandGold'), 'color-brand-gold');
+  assert.equal(normalizeFigmaVarName('Spacing/spacing0_5'), 'spacing-spacing-0-5');
+});
+
+test('detectTailwindDuplicates: strict name + value match wins', () => {
+  const varDefs = {
+    'Color/zinc-500': '#71717a',
+    'Color/zinc-600': '#52525b',
+  };
+  const tailwindDefaults = {
+    '--color-zinc-500': '#71717a',
+    '--color-zinc-600': '#52525b',
+    '--color-zinc-700': '#3f3f46',
+  };
+  const out = detectTailwindDuplicates(varDefs, tailwindDefaults);
+  const names = out.map(d => d.figmaName).sort();
+  assert.deepEqual(names, ['Color/zinc-500', 'Color/zinc-600']);
+  assert.equal(out[0].tailwindCssVar, '--color-zinc-500');
+});
+
+test('detectTailwindDuplicates: name matches but value differs → no fire', () => {
+  // The user's `Color/MyZinc` case, but with the canonical name. If the
+  // value diverges from the Tailwind default, it's not a duplicate — the
+  // designer has intentionally overridden it.
+  const varDefs = { 'Color/zinc-500': '#888888' };
+  const tailwindDefaults = { '--color-zinc-500': '#71717a' };
+  const out = detectTailwindDuplicates(varDefs, tailwindDefaults);
+  assert.deepEqual(out, []);
+});
+
+test('detectTailwindDuplicates: value matches but name differs → no fire (semantic-intent guard)', () => {
+  // `Color/MyZinc = #71717a` happens to equal `--color-zinc-500`, but
+  // the name signals a semantic intent ("my brand's zinc") — strict mode
+  // refuses to flag this. The designer's naming choice is respected.
+  const varDefs = { 'Color/MyZinc': '#71717a' };
+  const tailwindDefaults = { '--color-zinc-500': '#71717a' };
+  const out = detectTailwindDuplicates(varDefs, tailwindDefaults);
+  assert.deepEqual(out, []);
+});
+
+test('detectTailwindDuplicates: tier-collection variants still match canonical', () => {
+  const varDefs = { 'Primitives/color/zinc/500': '#71717a' };
+  const tailwindDefaults = { '--color-zinc-500': '#71717a' };
+  const out = detectTailwindDuplicates(varDefs, tailwindDefaults);
+  assert.equal(out.length, 1);
+  assert.equal(out[0].figmaName, 'Primitives/color/zinc/500');
+  assert.equal(out[0].tailwindCssVar, '--color-zinc-500');
+});
+
+test('detectTailwindDuplicates: case-insensitive value comparison', () => {
+  // Designer entered `#71717A`; Tailwind ships `#71717a`. Still a dupe.
+  const varDefs = { 'Color/zinc-500': '#71717A' };
+  const tailwindDefaults = { '--color-zinc-500': '#71717a' };
+  const out = detectTailwindDuplicates(varDefs, tailwindDefaults);
+  assert.equal(out.length, 1);
+});
+
+test('detectTailwindDuplicates: handles empty inputs gracefully', () => {
+  assert.deepEqual(detectTailwindDuplicates(null, {}), []);
+  assert.deepEqual(detectTailwindDuplicates({}, null), []);
+  assert.deepEqual(detectTailwindDuplicates({}, {}), []);
+});
diff --git a/plugins/adhd/lib/lint-engine/cli.js b/plugins/adhd/lib/lint-engine/cli.js
index 2cf31ca..ee7cc99 100644
--- a/plugins/adhd/lib/lint-engine/cli.js
+++ b/plugins/adhd/lib/lint-engine/cli.js
@@ -50,6 +50,7 @@ const { categorizeVariables } = require('./variable-categorizer');
 const { checkStructure } = require('./structure-checker');
 const { buildVariableSuggestions } = require('./variable-namer');
 const { checkBindings } = require('./binding-checker');
+const { detectTailwindDuplicates } = require('./tailwind-duplicate-detector');
 const { formatReport } = require('./report-formatter');
 
 function parseArgs(argv) {
@@ -242,6 +243,44 @@ function main() {
     });
   }
 
+  // STRUCT013 — Figma variable duplicates a Tailwind v4 default.
+  //
+  // Surfaces when a designer has both the canonical Tailwind variable
+  // (e.g. `Color/zinc-500`) AND a same-value duplicate sitting alongside.
+  // Strict match — name AND value must align — so semantic vars like
+  // `Color/MyZinc` (same value, different intent) are NOT flagged.
+  //
+  // The fix is "consolidate": rebind every layer using the duplicate to
+  // the canonical Tailwind variable, then delete the duplicate. The
+  // /adhd:lint --fix flow walks each candidate through AskUserQuestion
+  // before applying — never auto-rewires.
+  const duplicates = detectTailwindDuplicates(varDefs, tailwindDefaults);
+  for (const dup of duplicates) {
+    // varIdMap is { id: name }; invert to find the duplicate's Figma ID
+    // (used by --fix to rebind layers). Absent when the SKILL hasn't
+    // emitted varIdMap — STRUCT013 still surfaces, just without an ID
+    // hint for the migration script.
+    let figmaVarId = null;
+    for (const [id, name] of Object.entries(varIdMap || {})) {
+      if (name === dup.figmaName) { figmaVarId = id; break; }
+    }
+    structureViolations.push({
+      rule: 'STRUCT013',
+      severity: 'warning',
+      nodeId: undefined, // file-level concern; doesn't annotate a layer
+      nodePath: 'Variables',
+      message:
+        `Figma variable "${dup.figmaName}" (= ${dup.value}) duplicates Tailwind default \`${dup.tailwindCssVar}\`. ` +
+        `Same value, same canonical name — consolidating removes the duplicate without changing what gets rendered.\n\n` +
+        `To apply: run \`/adhd:lint --fix\`. The flow walks each candidate via prompt, then for each "Yes" it rebinds every layer that uses "${dup.figmaName}" to \`${dup.tailwindCssVar}\` and deletes the duplicate.`,
+      deepLink: args['target-url'],
+      // Extra fields consumed by --fix (ignored by the report formatter):
+      figmaVarName: dup.figmaName,
+      figmaVarId,
+      tailwindCssVar: dup.tailwindCssVar,
+    });
+  }
+
   const meta = {
     target: args.target,
     targetUrl: args['target-url'],
diff --git a/plugins/adhd/lib/lint-engine/tailwind-duplicate-detector.js b/plugins/adhd/lib/lint-engine/tailwind-duplicate-detector.js
new file mode 100644
index 0000000..773979a
--- /dev/null
+++ b/plugins/adhd/lib/lint-engine/tailwind-duplicate-detector.js
@@ -0,0 +1,106 @@
+'use strict';
+
+// STRUCT013 — Figma variable duplicates a Tailwind v4 default.
+//
+// After a designer has pushed the full Tailwind token system into Figma,
+// they may have legacy custom variables sitting alongside the canonical
+// Tailwind ones with the same value. STRUCT013 surfaces those duplicates
+// so designers (or `/adhd:lint --fix`) can rebind every layer that uses
+// the duplicate to the canonical Tailwind variable, then delete the
+// duplicate.
+//
+// **Strict match only.** Both the variable's NORMALIZED NAME and its
+// VALUE must align with a Tailwind default — value-only matches like
+// `Color/MyZinc = #71717a` happening to equal `--color-zinc-500` would
+// trample the designer's semantic intent (e.g. "this is my brand's zinc,
+// not a generic gray-500"). Strict mode trades recall for precision.
+//
+// Tier collections (Primitives / Semantic / Tokens / Base / Theme) are
+// invisible — `Primitives/color/zinc/500` matches `--color-zinc-500`
+// just like `Color/zinc-500` does. Same convention STRUCT011 uses.
+
+const { TIER_COLLECTIONS, normalizeCollectionName } = require('./variable-namer');
+
+function toKebab(seg) {
+  return seg
+    .replace(/([a-z0-9])([A-Z])/g, '$1-$2')
+    .replace(/([A-Z]+)([A-Z][a-z])/g, '$1-$2')
+    .replace(/([a-zA-Z])([0-9])/g, '$1-$2')
+    .replace(/([0-9])([a-zA-Z])/g, '$1-$2')
+    .replace(/[\s_]+/g, '-')
+    .toLowerCase();
+}
+
+// `<collection>/<...rest>` → kebab-flat name, with tier collections
+// stripped. `Color/zinc-500` → `color-zinc-500`. `Primitives/color/zinc/500`
+// → `color-zinc-500`. Returns null when there's no rest segment to
+// normalize.
+function normalizeFigmaVarName(name) {
+  if (!name || typeof name !== 'string') return null;
+  const segments = name.split('/');
+  if (segments.length < 2) return null;
+  const collection = segments[0];
+  const collNorm = normalizeCollectionName(collection);
+  const path = TIER_COLLECTIONS.has(collNorm) ? segments.slice(1) : segments;
+  const kebab = path.map(toKebab).filter(Boolean).join('-');
+  return kebab || null;
+}
+
+function normalizeCssVarName(cssVar) {
+  if (!cssVar) return null;
+  return cssVar.replace(/^--/, '').toLowerCase();
+}
+
+// Cheap string parity for high-confidence equality. Resolved values from
+// the SKILL's serializer arrive as strings (`'#71717a'`, `'0.25rem'`,
+// `'oklch(0.62 0.18 264)'`). Lowercase, collapse internal whitespace.
+// False negatives here are fine — strict mode favors precision; if a
+// match is missed, the variable still shows up as a normal (non-STRUCT013)
+// variable and nothing bad happens.
+function normalizeValue(v) {
+  if (v == null) return null;
+  if (typeof v !== 'string') {
+    try { return JSON.stringify(v); } catch { return String(v); }
+  }
+  return v.trim().toLowerCase().replace(/\s+/g, '');
+}
+
+// Returns an array of { figmaName, normalizedName, value, tailwindCssVar }
+// for every Figma variable whose normalized name AND value match a
+// Tailwind v4 default primitive.
+//
+// `varDefs`: { '<collection>/<name>': '<resolvedValue>' } — from the
+//   lint SKILL's serializer (or MCP `get_variable_defs`).
+// `tailwindDefaults`: { '--<cssVarName>': '<value>' } — from
+//   parseTheme(tailwind-defaults.css).primitives.
+function detectTailwindDuplicates(varDefs, tailwindDefaults) {
+  if (!varDefs || !tailwindDefaults) return [];
+  const twByNorm = new Map();
+  for (const [cssVar, value] of Object.entries(tailwindDefaults)) {
+    const norm = normalizeCssVarName(cssVar);
+    if (!norm) continue;
+    twByNorm.set(norm, { cssVar: '--' + norm, value: normalizeValue(value) });
+  }
+  const out = [];
+  for (const [figmaName, value] of Object.entries(varDefs)) {
+    const norm = normalizeFigmaVarName(figmaName);
+    if (!norm) continue;
+    const tw = twByNorm.get(norm);
+    if (!tw) continue;
+    if (tw.value !== normalizeValue(value)) continue;
+    out.push({
+      figmaName,
+      normalizedName: norm,
+      value,
+      tailwindCssVar: tw.cssVar,
+    });
+  }
+  return out;
+}
+
+module.exports = {
+  detectTailwindDuplicates,
+  normalizeFigmaVarName,
+  normalizeCssVarName,
+  normalizeValue,
+};
diff --git a/plugins/adhd/skills/lint/SKILL.md b/plugins/adhd/skills/lint/SKILL.md
index dcb5e1d..ed53e7d 100644
--- a/plugins/adhd/skills/lint/SKILL.md
+++ b/plugins/adhd/skills/lint/SKILL.md
@@ -1,7 +1,7 @@
 ---
-description: "Validate Figma frames/components/pages or the entire file against the local Tailwind design system + frame-structure best practices. Reads adhd.config.ts at the repo root. Read-only by default; with --annotate, also writes Figma annotations on each offending node in a 'lint' category. Optional argument: a Figma URL with node-id (scoped lint). With no argument, lints the whole file."
+description: "Validate Figma frames/components/pages or the entire file against the local Tailwind design system + frame-structure best practices. Reads adhd.config.ts at the repo root. Read-only by default; with --annotate, also writes Figma annotations on each offending node in a 'lint' category. With --fix, walks STRUCT013 Tailwind-duplicate candidates and applies approved consolidations (rebind + delete). Optional argument: a Figma URL with node-id (scoped lint). With no argument, lints the whole file."
 disable-model-invocation: true
-argument-hint: "[<figma-url-with-node-id>] [--annotate]"
+argument-hint: "[<figma-url-with-node-id>] [--annotate] [--fix]"
 allowed-tools: Read Write Bash AskUserQuestion mcp__plugin_figma_figma__use_figma
 ---
 
@@ -10,7 +10,7 @@ allowed-tools: Read Write Bash AskUserQuestion mcp__plugin_figma_figma__use_figm
 Validate that a Figma file (or a single frame/component/page) is ready for code translation. Reports two classes of issue:
 
 - **Variable issues** — Figma variables used by the lint target that are missing locally or have conflicting values.
-- **Structure issues** — STRUCT001–STRUCT012 best-practice violations (auto-layout, naming, variant properties, per-layer variable naming, cross-domain variable bindings, etc.).
+- **Structure issues** — STRUCT001–STRUCT013 best-practice violations (auto-layout, naming, variant properties, per-layer variable naming, cross-domain variable bindings, Tailwind-default duplicates, etc.).
 
 Output: a markdown report saved to `/tmp/adhd-lint/report.md`, plus a terminal echo. The report is paste-ready for sharing with designers via Figma comments, Slack, or GitHub issues.
 
@@ -24,9 +24,9 @@ Extract `figma.url` (required) and `naming` (optional, defaults to `kebab-case`)
 
 ## Phase 2: Resolve target
 
-Branch on `$ARGUMENTS`:
+Branch on `$ARGUMENTS`. The arguments can include a URL plus flags (`--annotate`, `--fix`) in any order; pull flags out first, then look at what remains.
 
-- **Empty argument → whole-file mode.** Skip target resolution. The extract script (Phase 3) will return ALL pages and ALL top-level lintable nodes (COMPONENT_SET, top-level COMPONENT, top-level FRAME) on each page. Set `target = "Whole file"` and `targetUrl = <figma.url from config>`.
+- **Empty (or flags only) → whole-file mode.** Skip target resolution. The extract script (Phase 3) will return ALL pages and ALL top-level lintable nodes (COMPONENT_SET, top-level COMPONENT, top-level FRAME) on each page. Set `target = "Whole file"` and `targetUrl = <figma.url from config>`.
 - **URL provided → scoped mode.**
   - Extract the file key (segment after `/design/`).
   - If it doesn't match the file key from `adhd.config.ts`, abort with: "URL points at file <X>, but adhd.config.ts is configured for file <Y>. Pass a URL from the configured file or run /adhd:config to update."
@@ -252,6 +252,153 @@ On "No": exit normally with no annotation work done.
 
 If there are zero `nodeId`-bearing violations (e.g. only whole-file violations like `pageGrouping`), skip the prompt — there's nothing to annotate.
 
+## Phase 8: Optional — consolidate Tailwind duplicates (`--fix`)
+
+If the user passed `--fix`, walk every STRUCT013 violation in `/tmp/adhd-lint/stdout.json` and offer to consolidate each one. Each STRUCT013 entry has `figmaVarName`, `figmaVarId`, and `tailwindCssVar` fields that drive the rebind.
+
+**Strict-match guarantee.** STRUCT013 only fires when the Figma variable's normalized name AND value both match a Tailwind v4 default — semantic variables like `Color/MyZinc` (different name, coincidental value match) are never surfaced. The `--fix` flow inherits that precision; it can't accidentally migrate a semantic variable.
+
+If `--fix` was NOT passed, skip this phase. If `--fix` was passed but there are no STRUCT013 violations, print `No Tailwind duplicates to consolidate.` and continue.
+
+### Pre-flight: the canonical must exist in Figma
+
+`--fix` rebinds layers from the duplicate to the canonical Tailwind variable. For that to work, the canonical variable has to actually exist in the Figma file (i.e. the user has already run `/adhd:push-tokens` to populate the Tailwind defaults). Before prompting, check the canonical names against `/tmp/adhd-lint/varidmap.json`:
+
+```bash
+node -e '
+const fs = require("fs");
+const idMap = JSON.parse(fs.readFileSync("/tmp/adhd-lint/varidmap.json", "utf8"));
+const summary = JSON.parse(fs.readFileSync("/tmp/adhd-lint/stdout.json", "utf8"));
+const struct013 = (summary.structure ?? []).filter(v => v.rule === "STRUCT013");
+const nameToId = Object.fromEntries(Object.entries(idMap).map(([id, name]) => [name, id]));
+// Expected canonical Figma name = the tailwindCssVar with `--` stripped,
+// matched against any Figma variable whose normalized name aligns. The
+// quick-and-dirty form: look for an exact match on the slashed equivalent
+// (e.g. "Color/white" for "--color-white"). Designers who pushed via
+// /adhd:push-tokens get this naming by default.
+const out = struct013.map(v => {
+  const canonical = v.tailwindCssVar.replace(/^--/, "").replace(/^([a-z]+)-/, "$1/");
+  const canonicalId = nameToId[canonical] ?? null;
+  return { ...v, canonicalFigmaName: canonical, canonicalFigmaId: canonicalId };
+});
+fs.writeFileSync("/tmp/adhd-lint/struct013-resolved.json", JSON.stringify(out, null, 2));
+console.log(out.filter(x => x.canonicalFigmaId).length + "/" + out.length);
+'
+```
+
+If the printed count shows fewer resolved than total (e.g. `2/4`), at least one canonical isn't in Figma yet. Print:
+
+```
+⚠ <N> STRUCT013 candidates can't be auto-fixed yet — the canonical Tailwind
+variable isn't in Figma. Run /adhd:push-tokens first (it'll add the missing
+canonicals), then re-run /adhd:lint --fix.
+
+Remaining <M> candidate(s) with canonicals present will be offered for
+consolidation now.
+```
+
+Continue with the resolved subset.
+
+### Per-candidate prompts
+
+For each resolved candidate, use `AskUserQuestion`:
+
+```
+Question: "Consolidate `<figmaVarName>` into Tailwind default `<tailwindCssVar>`? Every layer that uses `<figmaVarName>` will be rebound to the canonical, and the duplicate will be deleted from Figma."
+Header: "Consolidate?"
+Options:
+  - "Yes — rebind + delete"
+  - "No — skip this one"
+  - "Yes to all remaining"
+  - "Cancel — stop"
+```
+
+If "Yes to all remaining," skip further prompts and queue every remaining candidate. If "Cancel," exit the loop. Collect the approved set into `/tmp/adhd-lint/fix-actions.json` as `[{ duplicateId, canonicalId, duplicateName, canonicalName }, ...]`.
+
+If the approved set is empty, print `Nothing to consolidate.` and return.
+
+### Apply via use_figma
+
+Substitute `__ACTIONS__` with the JSON contents of `/tmp/adhd-lint/fix-actions.json` and call `mcp__plugin_figma_figma__use_figma`:
+
+```js
+const ACTIONS = /* substituted */;
+
+// For each consolidation: walk every page, rebind every layer that
+// references the duplicate variable to the canonical, then delete the
+// duplicate. Atomicity matters — if the rebind fails partway, we'd be
+// left with broken bindings. We deliberately scope per-variable so a
+// failure on one consolidation doesn't taint the others.
+const results = [];
+for (const action of ACTIONS) {
+  const { duplicateId, canonicalId, duplicateName, canonicalName } = action;
+  const dupVar = await figma.variables.getVariableByIdAsync(duplicateId);
+  const canVar = await figma.variables.getVariableByIdAsync(canonicalId);
+  if (!dupVar || !canVar) {
+    results.push({ duplicateName, status: "skipped", reason: "variable not found" });
+    continue;
+  }
+
+  let rebound = 0;
+  for (const page of figma.root.children) {
+    await figma.setCurrentPageAsync(page);
+    const nodes = page.findAll(() => true);
+    for (const node of nodes) {
+      if (!node.boundVariables) continue;
+      // Top-level scalar bindings (letterSpacing, padding*, *Radius, etc.)
+      for (const [prop, alias] of Object.entries(node.boundVariables)) {
+        if (prop === "fills" || prop === "strokes" || prop === "effects") continue;
+        if (alias && alias.id === duplicateId) {
+          node.setBoundVariable(prop, canVar);
+          rebound++;
+        }
+      }
+      // Per-paint color bindings on fills + strokes.
+      for (const kind of ["fills", "strokes"]) {
+        const arr = node[kind];
+        if (!Array.isArray(arr)) continue;
+        const next = arr.map((paint) => {
+          if (paint?.boundVariables?.color?.id === duplicateId) {
+            rebound++;
+            return figma.variables.setBoundVariableForPaint(paint, "color", canVar);
+          }
+          return paint;
+        });
+        node[kind] = next;
+      }
+    }
+  }
+
+  // Delete the duplicate. Will fail if it's still referenced anywhere we
+  // missed (effect colors, text-range bindings, etc.) — caller surfaces
+  // the error and the variable stays alive.
+  try {
+    dupVar.remove();
+    results.push({ duplicateName, canonicalName, rebound, status: "ok" });
+  } catch (e) {
+    results.push({ duplicateName, canonicalName, rebound, status: "rebound-only", error: String(e) });
+  }
+}
+
+return { results };
+```
+
+### Report
+
+Echo each result line:
+
+```
+✓ Consolidated `<duplicateName>` → `<canonicalName>` (<rebound> layer(s) rebound, duplicate deleted)
+```
+
+Or, on `rebound-only`:
+
+```
+⚠ Rebound `<duplicateName>` → `<canonicalName>` (<rebound> layer(s)) but could not delete the duplicate: <error>. It's no longer referenced by any visible layer; you can delete it manually if you confirm nothing else uses it.
+```
+
+Then exit normally.
+
 ## Common errors
 
 | Error | Fix-up guidance |

From ae0ef7fb4eb0c522175b2e6425627dd0cf1df672 Mon Sep 17 00:00:00 2001
From: Hugh Francis <hughfrancis89@gmail.com>
Date: Tue, 12 May 2026 13:31:13 -0400
Subject: [PATCH 55/79] lint: reject --fix + --dry-run as incompatible
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Designers familiar with /adhd:push-tokens --dry-run may reflexively try
the same flag on lint. Failing loudly with a clear message is safer
than silently picking one interpretation. /adhd:lint doesn't have its
own --dry-run mode — the per-candidate AskUserQuestion in Phase 8
already provides preview-then-approve.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 plugins/adhd/skills/lint/SKILL.md | 8 ++++++++
 1 file changed, 8 insertions(+)

diff --git a/plugins/adhd/skills/lint/SKILL.md b/plugins/adhd/skills/lint/SKILL.md
index ed53e7d..1a9f3e0 100644
--- a/plugins/adhd/skills/lint/SKILL.md
+++ b/plugins/adhd/skills/lint/SKILL.md
@@ -22,6 +22,14 @@ Read `adhd.config.ts` at the repo root. If it doesn't exist, abort with: "Run /a
 
 Extract `figma.url` (required) and `naming` (optional, defaults to `kebab-case`). Extract the file key from `figma.url` — the segment after `/design/`.
 
+## Phase 1.5: Validate flag combinations
+
+Before anything else, scan `$ARGUMENTS` for incompatible flag pairs and abort immediately if any are present:
+
+- **`--fix` + `--dry-run` →** abort with: "`--fix` and `--dry-run` are mutually exclusive: `--fix` applies consolidations; `--dry-run` previews without changes. Drop one. (Note: `/adhd:lint` doesn't have a `--dry-run` mode of its own — the per-candidate `AskUserQuestion` in Phase 8 already gives you preview-then-approve. The `--dry-run` flag belongs to `/adhd:push-tokens` and `/adhd:pull-tokens`.)"
+
+This guard exists because designers who've seen `--dry-run` work on push/pull-tokens may reflexively try the same flag combination on lint. Failing loudly is safer than silently picking one interpretation.
+
 ## Phase 2: Resolve target
 
 Branch on `$ARGUMENTS`. The arguments can include a URL plus flags (`--annotate`, `--fix`) in any order; pull flags out first, then look at what remains.

From f7cac18b56f9a68607972f31300305bdbac0cb5d Mon Sep 17 00:00:00 2001
From: Hugh Francis <hughfrancis89@gmail.com>
Date: Tue, 12 May 2026 13:43:45 -0400
Subject: [PATCH 56/79] push-tokens: subtract Tailwind defaults from codeOnly +
 resolve @theme inline calc/var
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Two related bugs that made /adhd:push-tokens unusable on real Tailwind v4
projects, both surfacing as false-positive diffs:

1. Tailwind-defaults floor. The comparator was treating
   `includeTailwindDefaults: true` tokens as code-side state, then offering
   to push hundreds of canonical Tailwind variables into Figma every run.
   Now each token carries `fromTailwindDefault` provenance; the comparator
   filters origin-tagged tokens out of `codeOnly` while keeping them in
   `same` and `conflict` (real state on the Figma side). User-authored
   overrides at the same path clear the flag and still push.

2. @theme inline calc/var resolution. The parser ignored every inline
   entry that wasn't a pure `var(--X)` alias — meaning the shadcn pattern
   `--radius-sm: calc(var(--radius) - 4px)` silently fell back to
   Tailwind's `0.25rem` default and conflicted against Figma's resolved
   6px. The new resolver walks `var()`, `calc(var() ± Npx)`, and
   `calc(var() * N)` against a `rawVars` map of every `--name: value;`
   seen during parse, producing literal `<N>px` overrides. Expressions
   the resolver can't reduce (undefined refs, multi-op chains, percentage
   math) leave the Tailwind default in place — caller can decide what to
   do with the resulting conflict.

Net effect on the user's reactor-webapp dry run: the 493 spurious
additions and 4 spurious conflicts should both collapse to zero.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 .../__tests__/code-parser.test.js             |  56 +++++++++
 .../__tests__/comparator.test.js              |  42 +++++++
 .../__tests__/e2e-pipeline.test.js            |  26 +++-
 plugins/adhd/lib/design-system/code-parser.js | 118 +++++++++++++++++-
 plugins/adhd/lib/design-system/comparator.js  |  11 +-
 5 files changed, 243 insertions(+), 10 deletions(-)

diff --git a/plugins/adhd/lib/design-system/__tests__/code-parser.test.js b/plugins/adhd/lib/design-system/__tests__/code-parser.test.js
index 3d73362..3331d3b 100644
--- a/plugins/adhd/lib/design-system/__tests__/code-parser.test.js
+++ b/plugins/adhd/lib/design-system/__tests__/code-parser.test.js
@@ -66,6 +66,62 @@ test('var(--x) references become aliases', () => {
   assert.deepEqual(t.values.dark,  { type: 'alias', target: 'gold/900' });
 });
 
+test('@theme inline with calc(var(--X) ± Npx) resolves to a literal override against the Tailwind default', () => {
+  // The real-world shadcn/Tailwind v4 pattern: `--radius` lives in :root,
+  // and the four canonical radius variants derive from it via calc().
+  // Without the resolver, the parser silently fell back to Tailwind's
+  // `--radius-sm: 0.25rem` defaults, which mismatch Figma's resolved
+  // 6/8/10/14px values and produced spurious conflicts on every push.
+  const ds = parseCodeDesignSystem(`
+    :root { --radius: 0.625rem; }
+    @theme inline {
+      --radius-sm: calc(var(--radius) - 4px);
+      --radius-md: calc(var(--radius) - 2px);
+      --radius-lg: var(--radius);
+      --radius-xl: calc(var(--radius) + 4px);
+    }
+  `, { includeTailwindDefaults: true });
+  const byPath = (p) => ds.tokens.find(t => t.domain === 'radius' && t.path === p);
+  // 0.625rem = 10px; the four overrides resolve to 6 / 8 / 10 / 14px.
+  assert.equal(byPath('sm').values.default.value, '6px');
+  assert.equal(byPath('md').values.default.value, '8px');
+  assert.equal(byPath('lg').values.default.value, '10px');
+  assert.equal(byPath('xl').values.default.value, '14px');
+  // After a user override the Tailwind-default marker is cleared, so the
+  // override pushes into Figma (it's authored intent, not implicit default).
+  assert.equal(byPath('sm').fromTailwindDefault, false);
+});
+
+test('@theme inline: calc with multiplier resolves (var * N)', () => {
+  // Tailwind's own pattern for the spacing scale: `--spacing-N: calc(var(--spacing) * N)`.
+  const ds = parseCodeDesignSystem(`
+    :root { --gap: 0.5rem; }
+    @theme inline {
+      --spacing-double: calc(var(--gap) * 2);
+    }
+  `);
+  const t = ds.tokens.find(x => x.domain === 'spacing' && x.path === 'double');
+  // 0.5rem * 2 = 16px
+  assert.equal(t.values.default.value, '16px');
+});
+
+test('@theme inline: unresolvable expression leaves Tailwind default in place', () => {
+  // The resolver only handles patterns it can confidently reduce to a
+  // literal length. A var that's not defined anywhere can't be resolved
+  // → leave the override out and keep the Tailwind default. The diff
+  // surfaces the conflict only if the runtime value diverges (which we
+  // can't know from text alone).
+  const ds = parseCodeDesignSystem(`
+    @theme inline {
+      --radius-sm: calc(var(--never-defined) + 4px);
+    }
+  `, { includeTailwindDefaults: true });
+  const t = ds.tokens.find(x => x.domain === 'radius' && x.path === 'sm');
+  // Falls back to Tailwind's `--radius-sm: 0.25rem` default literal.
+  assert.equal(t.values.default.value, '0.25rem');
+  assert.equal(t.fromTailwindDefault, true);
+});
+
 test('@theme inline entries land in ds.exposure, not ds.tokens', () => {
   const ds = parseCodeDesignSystem(`
     :root { --brand-surface: var(--color-gold-100); }
diff --git a/plugins/adhd/lib/design-system/__tests__/comparator.test.js b/plugins/adhd/lib/design-system/__tests__/comparator.test.js
index f395170..74734f5 100644
--- a/plugins/adhd/lib/design-system/__tests__/comparator.test.js
+++ b/plugins/adhd/lib/design-system/__tests__/comparator.test.js
@@ -205,4 +205,46 @@ test('valuesEqual: still flags real value differences after normalization', () =
   assert.equal(r.same.length, 0);
 });
 
+test('codeOnly: filters out Tailwind-default-origin tokens (additive policy)', () => {
+  // Pushing the full Tailwind palette into Figma is rarely intended — both
+  // sides assume the defaults implicitly. The comparator drops
+  // Tailwind-default-origin tokens from codeOnly so push doesn't create
+  // hundreds of redundant variables. User-authored tokens at the same path
+  // keep the flag cleared during parse and DO surface.
+  const code = {
+    tokens: [
+      { domain: 'color', path: 'zinc/500', values: { default: { type: 'literal', value: '#71717a' } }, fromTailwindDefault: true },
+      { domain: 'color', path: 'brand',     values: { default: { type: 'literal', value: '#5e3aee' } }, fromTailwindDefault: false },
+    ],
+    styles: { effects: [] },
+  };
+  const figma = { tokens: [], styles: { effects: [] } };
+  const diff = compareDesignSystems(code, figma);
+  // Only the user-authored token surfaces in codeOnly.
+  assert.equal(diff.codeOnly.length, 1);
+  assert.equal(diff.codeOnly[0].path, 'brand');
+});
+
+test('Tailwind-default-origin token with a Figma value mismatch still surfaces as conflict', () => {
+  // The filter is codeOnly-specific. If Figma has a different value for a
+  // Tailwind default (designer overrode `--color-zinc-500`), that's real
+  // state and stays in `conflict`.
+  const code = {
+    tokens: [
+      { domain: 'color', path: 'zinc/500', values: { default: { type: 'literal', value: '#71717a' } }, fromTailwindDefault: true },
+    ],
+    styles: { effects: [] },
+  };
+  const figma = {
+    tokens: [
+      { domain: 'color', path: 'zinc/500', values: { default: { type: 'literal', value: '#888888' } } },
+    ],
+    styles: { effects: [] },
+  };
+  const diff = compareDesignSystems(code, figma);
+  assert.equal(diff.codeOnly.length, 0);
+  assert.equal(diff.conflict.length, 1);
+  assert.equal(diff.conflict[0].path, 'zinc/500');
+});
+
 
diff --git a/plugins/adhd/lib/design-system/__tests__/e2e-pipeline.test.js b/plugins/adhd/lib/design-system/__tests__/e2e-pipeline.test.js
index e8560ae..35e4ab3 100644
--- a/plugins/adhd/lib/design-system/__tests__/e2e-pipeline.test.js
+++ b/plugins/adhd/lib/design-system/__tests__/e2e-pipeline.test.js
@@ -57,17 +57,35 @@ test('e2e: push against synced figma produces zero create-variable actions', ()
   assert.equal(countKind(actions, 'create-effect-style'), 0);
 });
 
-test('e2e: empty figma — push produces create-variable actions for every variable token', () => {
+test('e2e: empty figma — push produces create-variable actions ONLY for user-authored tokens', () => {
+  // After the Tailwind-defaults floor fix: codeOnly no longer surfaces
+  // tokens that came from `tailwind-defaults.css` or the synthetic utility
+  // scale. The user's example/globals.css authors ~18 tokens of its own
+  // (custom colors, the chart palette, --radius and friends, sidebar
+  // semantics, font families); those are what push should create. Earlier
+  // behavior — flooding 400+ create-variable actions into Figma to bake
+  // in the full Tailwind palette — was a comparator bug, not a feature.
   const { diff, actions } = pipeline('figma-empty.json', { direction: 'push' });
   assert.equal(diff.same.length, 0);
   assert.equal(diff.conflict.length, 0);
   assert.equal(diff.figmaOnly.length, 0);
-  assert.ok(diff.codeOnly.length > 400, `expected hundreds of codeOnly, got ${diff.codeOnly.length}`);
-  // codeOnly with non-shadow domains → create-variable; shadows → create-effect-style.
+  assert.ok(diff.codeOnly.length > 0 && diff.codeOnly.length < 100,
+    `expected a focused set of user-authored codeOnly tokens, got ${diff.codeOnly.length}`);
+  // Every codeOnly entry must be user-authored — no Tailwind-default
+  // tokens leak through the filter.
+  for (const t of diff.codeOnly) {
+    assert.notEqual(t.fromTailwindDefault, true,
+      `Tailwind-default token leaked into codeOnly: ${t.domain}:${t.path}`);
+  }
   const nonShadowCodeOnly = diff.codeOnly.filter(t => t.domain !== 'shadow').length;
   assert.equal(countKind(actions, 'create-variable'), nonShadowCodeOnly,
     'create-variable count should equal non-shadow codeOnly count');
-  assert.ok(countKind(actions, 'create-effect-style') > 0, 'expected some effect-style creates for shadows');
+  // example/globals.css doesn't author its own shadow tokens — it inherits
+  // them from Tailwind, which the floor filter excludes from codeOnly. A
+  // project that DID author custom shadows would see create-effect-style
+  // actions; users who want the full Tailwind shadow palette in Figma can
+  // re-declare them explicitly in `@theme {}`.
+  assert.equal(countKind(actions, 'create-effect-style'), 0);
 });
 
 test('e2e: empty figma — pull is a no-op (nothing in figma to pull)', () => {
diff --git a/plugins/adhd/lib/design-system/code-parser.js b/plugins/adhd/lib/design-system/code-parser.js
index 1b0338c..9477a84 100644
--- a/plugins/adhd/lib/design-system/code-parser.js
+++ b/plugins/adhd/lib/design-system/code-parser.js
@@ -191,6 +191,81 @@ function valueFromString(raw) {
   return { type: 'literal', value: trimmed };
 }
 
+// Convert a CSS length string ("0.625rem", "16px", "1.5") to pixels.
+// rem/em use a 16px base — Tailwind v4's default and the figma-write-
+// actions's convention. Returns null if the input isn't a simple length.
+function lengthToPx(raw) {
+  if (raw == null) return null;
+  const s = String(raw).trim();
+  const m = /^(-?\d*\.?\d+)(px|rem|em)?$/.exec(s);
+  if (!m) return null;
+  const n = parseFloat(m[1]);
+  const unit = m[2] || '';
+  if (unit === 'rem' || unit === 'em') return n * 16;
+  return n;
+}
+
+// Try to resolve a CSS value expression to a literal `<N>px` string by
+// looking up referenced variables in `rawVars`. Handles the patterns
+// designers actually write in `@theme inline {}`:
+//
+//   var(--name)                          → resolve --name (recursive)
+//   calc(var(--name) ± Npx | ± Nrem)     → arithmetic
+//   calc(var(--name) * N | / N)          → arithmetic
+//   plain literals ("0.5rem", "8px")     → returned as `<N>px`
+//
+// Returns null when the expression contains anything more elaborate (two
+// vars, nested calcs, percentage math, etc.) — caller falls back to the
+// existing behavior (skipping the override). Recursion is bounded by
+// `depth` to prevent cycles in pathological aliases.
+function resolveToPxLiteral(raw, rawVars, depth = 0) {
+  if (depth > 8) return null;
+  const s = String(raw || '').trim();
+  if (!s) return null;
+
+  // Plain literal — already a length.
+  const direct = lengthToPx(s);
+  if (direct != null) return direct + 'px';
+
+  // var(--name) alone.
+  const varOnly = /^var\(\s*(--[a-zA-Z0-9_-]+)\s*(?:,[^)]*)?\)$/.exec(s);
+  if (varOnly) {
+    const target = rawVars.get(varOnly[1]);
+    if (target == null) return null;
+    return resolveToPxLiteral(target, rawVars, depth + 1);
+  }
+
+  // calc(<var-or-num> <op> <var-or-num>) — restricted form.
+  const calc = /^calc\(\s*(.+?)\s*\)$/.exec(s);
+  if (calc) {
+    const inner = calc[1];
+    // Two operands separated by + - * /. Operators must have surrounding
+    // whitespace per the CSS spec (calc(8px+4px) is invalid).
+    const opSplit = /^(.+?)\s+([+\-*/])\s+(.+)$/.exec(inner);
+    if (!opSplit) return null;
+    const [, lhsRaw, op, rhsRaw] = opSplit;
+    const lhs = resolveToPxLiteral(lhsRaw, rawVars, depth + 1);
+    const rhs = resolveToPxLiteral(rhsRaw, rawVars, depth + 1);
+    // For * and /, one side is a plain number (no unit). For +/-, both
+    // must resolve to lengths.
+    const lhsNum = lhs ? lengthToPx(lhs) : lengthToPx(lhsRaw);
+    const rhsNum = rhs ? lengthToPx(rhs) : lengthToPx(rhsRaw);
+    if (lhsNum == null || rhsNum == null) return null;
+    let val;
+    switch (op) {
+      case '+': val = lhsNum + rhsNum; break;
+      case '-': val = lhsNum - rhsNum; break;
+      case '*': val = lhsNum * rhsNum; break;
+      case '/': val = rhsNum === 0 ? null : lhsNum / rhsNum; break;
+      default:  return null;
+    }
+    if (val == null || !Number.isFinite(val)) return null;
+    return val + 'px';
+  }
+
+  return null;
+}
+
 function findExtractedDarkBlocks(css) {
   // Extract @media (prefers-color-scheme: dark) { :root { ... } } bodies
   const out = [];
@@ -340,8 +415,15 @@ function parseCodeDesignSystem(css, opts = {}) {
   }
 
   const tokens = new Map(); // domain+path → token
-
-  const upsert = (cssVar, mode, valueRaw) => {
+  // Every `--name: rawValue` declaration we see, regardless of domain.
+  // Powers `@theme inline {}` expression resolution: when a designer writes
+  // `--radius-sm: calc(var(--radius) - 4px)`, we need to look up --radius's
+  // literal to compute the resolved 6px and override the Tailwind default.
+  // Storing raw strings (not parsed values) keeps the resolver simple.
+  const rawVars = new Map();
+
+  const upsert = (cssVar, mode, valueRaw, meta) => {
+    rawVars.set(cssVar, valueRaw);
     const path = pathFromCssVar(cssVar);
     const domain = inferDomain(cssVar);
     if (domain === 'unknown') return;
@@ -349,7 +431,21 @@ function parseCodeDesignSystem(css, opts = {}) {
     if (!tokens.has(key)) {
       tokens.set(key, { domain, path, values: {}, cssVar });
     }
-    tokens.get(key).values[mode] = valueFromString(valueRaw);
+    const tok = tokens.get(key);
+    tok.values[mode] = valueFromString(valueRaw);
+    // Origin marker — set ONLY when the token first lands (so a later
+    // user-globals upsert clears it back to "authored"). The comparator
+    // uses this to exclude pure-default tokens from codeOnly: pushing the
+    // entire Tailwind palette into Figma is rarely what the user wants,
+    // and the additive policy lets implicit defaults stay implicit on
+    // both sides. Tokens in `same` or `conflict` still surface — those
+    // are real state.
+    if (meta && meta.fromTailwindDefault) {
+      if (!('fromTailwindDefault' in tok)) tok.fromTailwindDefault = true;
+    } else {
+      // Any user-authored upsert overrides the default flag.
+      tok.fromTailwindDefault = false;
+    }
   };
 
   // 0. Tailwind defaults (optional). Merged FIRST so that user's globals.css
@@ -358,7 +454,7 @@ function parseCodeDesignSystem(css, opts = {}) {
     const body = loadTailwindDefaultsBody();
     const entries = parseEntries(body);
     for (const [cssVar, raw] of Object.entries(entries)) {
-      upsert(cssVar, 'default', raw);
+      upsert(cssVar, 'default', raw, { fromTailwindDefault: true });
     }
     // Tailwind v4 doesn't ship explicit `--spacing-N` or `--radius-{none,full}`
     // variables — most utility classes derive from --spacing at build time
@@ -368,6 +464,7 @@ function parseCodeDesignSystem(css, opts = {}) {
     for (const t of synthetic) {
       const key = t.domain + ':' + t.path;
       if (!tokens.has(key)) {
+        t.fromTailwindDefault = true;
         tokens.set(key, t);
       }
     }
@@ -455,7 +552,18 @@ function parseCodeDesignSystem(css, opts = {}) {
           target: refMatch[1].replace(/^--/, ''),
         });
       }
-      // else ignore (raw values in @theme inline are unusual)
+      // @theme inline can ALSO carry value overrides — most often as
+      // calc()/var() expressions that resolve to a concrete length at
+      // runtime (e.g. `--radius-sm: calc(var(--radius) - 4px)`). Without
+      // this resolution step, the parser would silently fall back to the
+      // Tailwind default for --radius-sm, producing false conflicts
+      // against Figma's resolved value. We try to resolve every inline
+      // entry to a literal `<N>px` string and override the default; if
+      // the expression is too complex, we leave the default alone.
+      const resolved = resolveToPxLiteral(raw, rawVars);
+      if (resolved != null) {
+        upsert(cssVar, 'default', resolved);
+      }
     }
     themeOpenRe2.lastIndex = i + 1;
   }
diff --git a/plugins/adhd/lib/design-system/comparator.js b/plugins/adhd/lib/design-system/comparator.js
index 5569d65..0ae2448 100644
--- a/plugins/adhd/lib/design-system/comparator.js
+++ b/plugins/adhd/lib/design-system/comparator.js
@@ -130,6 +130,15 @@ function compareDesignSystems(code, figma) {
     }
   }
 
+  // Filter Tailwind-default-origin tokens out of codeOnly. Pushing the
+  // entire Tailwind palette into Figma is rarely the user's intent — the
+  // tokens are implicit on both sides (Tailwind ships them; Figma users
+  // assume them). User-authored tokens at the same path keep the flag
+  // cleared during parse, so genuine overrides DO push. Tokens that
+  // surface in `same` or `conflict` are unaffected — those reflect real
+  // state on the Figma side already.
+  const filteredCodeOnly = codeOnly.filter(t => t.fromTailwindDefault !== true);
+
   // ── Effect styles ──────────────────────────────────────────────────────
   // Diff by name only. Each side may not have styles at all (older callers).
   // The full effect-payload comparison is intentionally not attempted: Figma
@@ -148,7 +157,7 @@ function compareDesignSystems(code, figma) {
     },
   };
 
-  return { same, conflict, codeOnly, figmaOnly, styles };
+  return { same, conflict, codeOnly: filteredCodeOnly, figmaOnly, styles };
 }
 
 module.exports = { compareDesignSystems, valuesEqual };

From c3eadeb711aef64aa7f5a2caaafc4a734cbaa6d0 Mon Sep 17 00:00:00 2001
From: Hugh Francis <hughfrancis89@gmail.com>
Date: Tue, 12 May 2026 13:48:14 -0400
Subject: [PATCH 57/79] push-tokens: --include-tailwind to seed full palette +
 bucket dry-run preview

Previous commit filtered Tailwind defaults out of codeOnly so daily
pushes stayed focused, but designers want the seed-mode workflow too:
push the entire Tailwind palette to Figma so every utility is available
as a variable, no ad-hoc tokens required.

Adds --include-tailwind to /adhd:push-tokens. Without it, day-to-day
pushes see only authored tokens (focused diff, ~20 entries). With it,
the comparator surfaces every Tailwind default in codeOnly so the seed
push creates them all in Figma. Designed for one-time setup; subsequent
pushes use the default mode.

Also buckets the dry-run preview by domain when there are >25
additions, so the seed-mode flood (493 entries) becomes COLOR (350) /
SPACING (50) / RADIUS (4) / ... with a 6-row sample per bucket instead
of a 493-row unfurl. The full list still lives in diff.json for
detailed review.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 README.md                                     |  2 +-
 .../lib/design-system/__tests__/cli.test.js   | 50 ++++++++++++++++
 .../__tests__/comparator.test.js              | 19 ++++++
 plugins/adhd/lib/design-system/cli.js         | 59 ++++++++++++++++---
 plugins/adhd/lib/design-system/comparator.js  | 27 ++++++---
 plugins/adhd/skills/push-tokens/SKILL.md      | 12 ++--
 6 files changed, 147 insertions(+), 22 deletions(-)

diff --git a/README.md b/README.md
index aa7e68b..8e4a53d 100644
--- a/README.md
+++ b/README.md
@@ -30,7 +30,7 @@ After install, nine slash commands are available:
 |---|---|---|---|
 | `/adhd:config` | — | — | Interactive wizard that produces `adhd.config.ts`. Verifies the official Figma plugin is installed + authenticated before anything else. |
 | `/adhd:lint` | `[<figma-url>] [--annotate] [--fix]` | read-only by default | Validates the Figma file (whole file or scoped) against the local design system + structure best-practices. With `--annotate`, also writes Figma annotations on each offending node in a "lint" category. With `--fix`, walks STRUCT013 Tailwind-duplicate candidates per-prompt and consolidates approved ones (rebinds bindings to the canonical Tailwind variable, then deletes the duplicate). |
-| `/adhd:push-tokens` | `[--dry-run]` | code → Figma | Pushes globals.css variables + named styles into Figma directly via the remote MCP. `--dry-run` previews what would be added or overwritten without writing. |
+| `/adhd:push-tokens` | `[--dry-run] [--include-tailwind]` | code → Figma | Pushes globals.css variables + named styles into Figma directly via the remote MCP. `--dry-run` previews what would be added or overwritten without writing. `--include-tailwind` also pushes every Tailwind v4 default (full palette, spacing scale, etc.) — use as a one-time seed so designers have every utility available as a Figma variable. |
 | `/adhd:pull-tokens` | `[--dry-run]` | Figma → code | Pulls Figma variables + named styles into globals.css. `--dry-run` previews without writing. |
 | `/adhd:push-component` | `<path> [--max-variants <n>] [--annotate]` | code → Figma | Pushes a React component to Figma as a structured Component Set with variant properties + variable bindings, plus a preflight lint check. `--annotate` annotates preflight violations on Figma nodes. |
 | `/adhd:push-all-components` | `[--continue-on-error] [--max-variants <n>] [--annotate]` | code → Figma | Bulk version of `push-component` — iterates over every entry in `adhd.config.ts`'s components map. Sequential, halt-on-first-failure by default. |
diff --git a/plugins/adhd/lib/design-system/__tests__/cli.test.js b/plugins/adhd/lib/design-system/__tests__/cli.test.js
index 2c7ff4d..8ef512b 100644
--- a/plugins/adhd/lib/design-system/__tests__/cli.test.js
+++ b/plugins/adhd/lib/design-system/__tests__/cli.test.js
@@ -130,6 +130,56 @@ test('preview (pull): flips the direction labels', () => {
   assert.match(result.stdout, /code-only \(left untouched per additive policy\): 1 entry/);
 });
 
+test('compare --include-tailwind: keeps Tailwind-default-origin tokens in codeOnly', () => {
+  // Verifies the seed-mode flag plumbing. With --include-tailwind, the
+  // comparator should NOT filter origin-tagged tokens.
+  const css = tmp('globals.css', `@theme { --color-brand: #5e3aee; }`);
+  // Use an empty figma extract so everything that's in code becomes codeOnly.
+  const figma = tmp('figma.json', { collections: [], effectStyles: [], textStyles: [] });
+  const outA = path.join(os.tmpdir(), 'diff-default-' + Date.now() + '.json');
+  const outB = path.join(os.tmpdir(), 'diff-seed-' + Date.now() + '.json');
+
+  const defaultRun = spawnSync('node', [CLI, 'compare', '--code', css, '--figma', figma, '--output', outA], { encoding: 'utf8' });
+  assert.equal(defaultRun.status, 0);
+  const diffDefault = JSON.parse(fs.readFileSync(outA, 'utf8'));
+
+  const seedRun = spawnSync('node', [CLI, 'compare', '--code', css, '--figma', figma, '--output', outB, '--include-tailwind'], { encoding: 'utf8' });
+  assert.equal(seedRun.status, 0);
+  const diffSeed = JSON.parse(fs.readFileSync(outB, 'utf8'));
+
+  // Seed mode has dramatically more codeOnly entries — the full Tailwind palette.
+  assert.ok(diffSeed.codeOnly.length > diffDefault.codeOnly.length * 5,
+    `expected seed codeOnly (${diffSeed.codeOnly.length}) >> default codeOnly (${diffDefault.codeOnly.length})`);
+  // Default mode never includes a token tagged fromTailwindDefault.
+  for (const t of diffDefault.codeOnly) {
+    assert.notEqual(t.fromTailwindDefault, true);
+  }
+  // Seed mode DOES include them.
+  assert.ok(diffSeed.codeOnly.some(t => t.fromTailwindDefault === true));
+});
+
+test('preview: buckets additions by domain when there are many entries', () => {
+  // Above the flat-list threshold (25), the preview groups by domain
+  // with a sample-of-each rather than a hundreds-line dump.
+  const codeOnly = [];
+  for (let i = 0; i < 40; i++) {
+    codeOnly.push({ domain: 'color', path: `zinc/${i}`, values: { default: `#000${i}` } });
+  }
+  for (let i = 0; i < 30; i++) {
+    codeOnly.push({ domain: 'spacing', path: `${i}`, values: { default: `${i}px` } });
+  }
+  const diff = tmp('diff.json', { same: [], conflict: [], codeOnly, figmaOnly: [] });
+
+  const result = spawnSync('node', [CLI, 'preview', '--diff', diff, '--direction', 'push'], { encoding: 'utf8' });
+  assert.equal(result.status, 0, result.stderr);
+  assert.match(result.stdout, /Would add to Figma \(70 entries across 2 domains\)/);
+  assert.match(result.stdout, /\bCOLOR \(40\)/);
+  assert.match(result.stdout, /\bSPACING \(30\)/);
+  // Each bucket is truncated; the trailer shows the remaining count.
+  assert.match(result.stdout, /\[\+34 more\]/);
+  assert.match(result.stdout, /\[\+24 more\]/);
+});
+
 test('preview: errors on missing --diff or invalid --direction', () => {
   // Sanity: the subcommand must validate its inputs.
   let r = spawnSync('node', [CLI, 'preview', '--direction', 'push'], { encoding: 'utf8' });
diff --git a/plugins/adhd/lib/design-system/__tests__/comparator.test.js b/plugins/adhd/lib/design-system/__tests__/comparator.test.js
index 74734f5..c87d846 100644
--- a/plugins/adhd/lib/design-system/__tests__/comparator.test.js
+++ b/plugins/adhd/lib/design-system/__tests__/comparator.test.js
@@ -205,6 +205,25 @@ test('valuesEqual: still flags real value differences after normalization', () =
   assert.equal(r.same.length, 0);
 });
 
+test('codeOnly: includeTailwindDefaultsInCodeOnly=true keeps the full palette in codeOnly (seed mode)', () => {
+  // The seed-the-design-system mode: designers want every Tailwind
+  // utility available as a Figma variable. Comparator should NOT filter
+  // origin-tagged tokens out of codeOnly when the flag is set.
+  const code = {
+    tokens: [
+      { domain: 'color', path: 'zinc/500', values: { default: { type: 'literal', value: '#71717a' } }, fromTailwindDefault: true },
+      { domain: 'color', path: 'brand',    values: { default: { type: 'literal', value: '#5e3aee' } }, fromTailwindDefault: false },
+    ],
+    styles: { effects: [] },
+  };
+  const figma = { tokens: [], styles: { effects: [] } };
+  const diff = compareDesignSystems(code, figma, { includeTailwindDefaultsInCodeOnly: true });
+  // Both tokens surface in codeOnly.
+  assert.equal(diff.codeOnly.length, 2);
+  const paths = diff.codeOnly.map(t => t.path).sort();
+  assert.deepEqual(paths, ['brand', 'zinc/500']);
+});
+
 test('codeOnly: filters out Tailwind-default-origin tokens (additive policy)', () => {
   // Pushing the full Tailwind palette into Figma is rarely intended — both
   // sides assume the defaults implicitly. The comparator drops
diff --git a/plugins/adhd/lib/design-system/cli.js b/plugins/adhd/lib/design-system/cli.js
index 0e21006..d04358f 100644
--- a/plugins/adhd/lib/design-system/cli.js
+++ b/plugins/adhd/lib/design-system/cli.js
@@ -26,7 +26,7 @@ function parseArgs(argv) {
 
 function printUsage() {
   console.log(`Usage:
-  cli.js compare           --code <globals.css> --figma <figma.json> --output <diff.json>
+  cli.js compare           --code <globals.css> --figma <figma.json> --output <diff.json> [--include-tailwind]
   cli.js apply             --diff <diff.json> --resolutions <resolutions.json> --direction <push|pull> --output <actions.json>
   cli.js preview           --diff <diff.json> --direction <push|pull>
   cli.js assemble-extract  --chunks-dir <dir> --output <figma.json>
@@ -82,23 +82,60 @@ function formatPreview(diff, direction) {
 
   // Additions: tokens that exist only on the source side. Each token may
   // span multiple modes; emit one row per mode.
+  // Below this threshold, show every row inline — short lists are easier
+  // to read flat than bucketed. Above it, group by domain and truncate
+  // each bucket so a 493-entry Tailwind-palette seed remains scannable
+  // instead of unfurling 493 lines into the terminal.
+  const FLAT_THRESHOLD = 25;
+  const BUCKET_SAMPLE_SIZE = 6;
+
   const addRows = [];
   for (const tok of fromOnly) {
     for (const [mode, value] of Object.entries(tok.values || {})) {
-      addRows.push({ path: tok.path, mode, value });
+      addRows.push({ path: tok.path, mode, value, domain: tok.domain || 'other' });
     }
   }
-  addRows.sort((a, b) => a.path.localeCompare(b.path) || a.mode.localeCompare(b.mode));
+  addRows.sort((a, b) =>
+    a.domain.localeCompare(b.domain) ||
+    a.path.localeCompare(b.path) ||
+    a.mode.localeCompare(b.mode),
+  );
 
   if (addRows.length === 0) {
     lines.push(`Would add to ${toSide}: none.`);
-  } else {
+  } else if (addRows.length <= FLAT_THRESHOLD) {
     lines.push(`Would add to ${toSide} (${addRows.length} entr${addRows.length === 1 ? 'y' : 'ies'}):`);
     const pathW = Math.max(...addRows.map(r => r.path.length));
     const modeW = Math.max(...addRows.map(r => r.mode.length));
     for (const r of addRows) {
       lines.push(`  + ${r.path.padEnd(pathW)}  (${r.mode.padEnd(modeW)})  = ${fmtValue(r.value)}`);
     }
+  } else {
+    // Bucket by domain. Show counts up front, then a sample of each
+    // domain so the user can sanity-check the shape without scrolling
+    // past hundreds of rows.
+    const byDomain = new Map();
+    for (const r of addRows) {
+      if (!byDomain.has(r.domain)) byDomain.set(r.domain, []);
+      byDomain.get(r.domain).push(r);
+    }
+    lines.push(`Would add to ${toSide} (${addRows.length} entries across ${byDomain.size} domain${byDomain.size === 1 ? '' : 's'}):`);
+    for (const domain of [...byDomain.keys()].sort()) {
+      const rows = byDomain.get(domain);
+      lines.push(``);
+      lines.push(`  ${domain.toUpperCase()} (${rows.length})`);
+      const sample = rows.slice(0, BUCKET_SAMPLE_SIZE);
+      const pathW = Math.max(...sample.map(r => r.path.length));
+      const modeW = Math.max(...sample.map(r => r.mode.length));
+      for (const r of sample) {
+        lines.push(`    + ${r.path.padEnd(pathW)}  (${r.mode.padEnd(modeW)})  = ${fmtValue(r.value)}`);
+      }
+      if (rows.length > BUCKET_SAMPLE_SIZE) {
+        lines.push(`    [+${rows.length - BUCKET_SAMPLE_SIZE} more]`);
+      }
+    }
+    lines.push('');
+    lines.push(`  Full list written to the diff JSON (codeOnly array). For a one-time review, sort by domain in the diff file.`);
   }
   lines.push('');
 
@@ -140,13 +177,19 @@ function main() {
   if (cmd === 'compare') {
     const css = fs.readFileSync(args.code, 'utf8');
     const figmaExtract = JSON.parse(fs.readFileSync(args.figma, 'utf8'));
-    // Default: include Tailwind v4's full default theme so push/pull see
-    // the complete design system, not just what's redeclared in globals.css.
-    // Disable with --no-tailwind-defaults if you only want explicit overrides.
+    // Parser always learns about Tailwind v4's default theme so we know
+    // which tokens are user-authored vs default (the `fromTailwindDefault`
+    // marker). The COMPARATOR then decides what to include in `codeOnly`:
+    //   - Default: filter out defaults — keep day-to-day pushes focused
+    //   - --include-tailwind: surface the full Tailwind palette in
+    //     codeOnly, for seeding a fresh Figma file with every utility as
+    //     a variable. The seed case is once-per-project; the focused
+    //     diff is once-per-change.
     const includeTailwindDefaults = !('no-tailwind-defaults' in args);
+    const includeTailwindDefaultsInCodeOnly = 'include-tailwind' in args;
     const codeDS = parseCodeDesignSystem(css, { includeTailwindDefaults });
     const figmaDS = parseFigmaDesignSystem(figmaExtract);
-    const diff = compareDesignSystems(codeDS, figmaDS);
+    const diff = compareDesignSystems(codeDS, figmaDS, { includeTailwindDefaultsInCodeOnly });
     fs.writeFileSync(args.output, JSON.stringify(diff, null, 2));
     process.exit(0);
   }
diff --git a/plugins/adhd/lib/design-system/comparator.js b/plugins/adhd/lib/design-system/comparator.js
index 0ae2448..b1daede 100644
--- a/plugins/adhd/lib/design-system/comparator.js
+++ b/plugins/adhd/lib/design-system/comparator.js
@@ -61,7 +61,14 @@ function tokenKey(t) {
   return t.domain + ':' + t.path;
 }
 
-function compareDesignSystems(code, figma) {
+function compareDesignSystems(code, figma, opts = {}) {
+  // `opts.includeTailwindDefaultsInCodeOnly` (boolean, default false).
+  // When false, the comparator drops Tailwind-default-origin tokens from
+  // `codeOnly` so day-to-day pushes don't try to bake the entire Tailwind
+  // palette into Figma. When true, the full palette surfaces in codeOnly
+  // — the right mode when seeding a fresh Figma file so designers have
+  // every Tailwind utility available as a variable.
+  const includeTailwindInCodeOnly = opts.includeTailwindDefaultsInCodeOnly === true;
   const same = [];
   const conflict = [];
   const codeOnly = [];
@@ -130,14 +137,16 @@ function compareDesignSystems(code, figma) {
     }
   }
 
-  // Filter Tailwind-default-origin tokens out of codeOnly. Pushing the
-  // entire Tailwind palette into Figma is rarely the user's intent — the
-  // tokens are implicit on both sides (Tailwind ships them; Figma users
-  // assume them). User-authored tokens at the same path keep the flag
-  // cleared during parse, so genuine overrides DO push. Tokens that
-  // surface in `same` or `conflict` are unaffected — those reflect real
-  // state on the Figma side already.
-  const filteredCodeOnly = codeOnly.filter(t => t.fromTailwindDefault !== true);
+  // Filter Tailwind-default-origin tokens out of codeOnly UNLESS the
+  // caller explicitly asked to include them. Defaulting to filtered keeps
+  // day-to-day pushes focused on authored changes (no 400-entry palette
+  // flood). The `--include-tailwind` push mode flips this for the
+  // one-time seeding case where designers want every Tailwind utility as
+  // a Figma variable. Tokens that surface in `same` or `conflict` are
+  // unaffected — those reflect real state on the Figma side already.
+  const filteredCodeOnly = includeTailwindInCodeOnly
+    ? codeOnly
+    : codeOnly.filter(t => t.fromTailwindDefault !== true);
 
   // ── Effect styles ──────────────────────────────────────────────────────
   // Diff by name only. Each side may not have styles at all (older callers).
diff --git a/plugins/adhd/skills/push-tokens/SKILL.md b/plugins/adhd/skills/push-tokens/SKILL.md
index 9addd9f..0eef535 100644
--- a/plugins/adhd/skills/push-tokens/SKILL.md
+++ b/plugins/adhd/skills/push-tokens/SKILL.md
@@ -1,7 +1,7 @@
 ---
-description: "Push the local design tokens (globals.css variables + named styles) into the configured Figma file. Two-way diff with per-attribute conflict prompts; additive (never deletes from Figma). Reads adhd.config.ts at the repo root. Pass --dry-run to preview without writing."
+description: "Push the local design tokens (globals.css variables + named styles) into the configured Figma file. Two-way diff with per-attribute conflict prompts; additive (never deletes from Figma). Reads adhd.config.ts at the repo root. Pass --dry-run to preview without writing. Pass --include-tailwind to seed Figma with the entire Tailwind v4 palette so designers have every utility available as a variable."
 disable-model-invocation: true
-argument-hint: "[--dry-run]"
+argument-hint: "[--dry-run] [--include-tailwind]"
 allowed-tools: Read Write Edit Bash AskUserQuestion mcp__plugin_figma_figma__use_figma
 ---
 
@@ -11,6 +11,8 @@ Pushes the codebase's design tokens (variables + named styles) into the configur
 
 Pass `--dry-run` to see exactly what would be added or overwritten without making any changes — no prompts, no writes, no MCP traffic beyond the initial extract.
 
+Pass `--include-tailwind` to also push every Tailwind v4 default (the full color palette, the spacing scale, radii, breakpoints, etc.). Useful as a one-time **seed** when setting up a fresh Figma file so designers can pick from the same token space the code can render. Without this flag, daily pushes stay focused on user-authored tokens only — the Tailwind defaults are implicit on both sides and the additive policy keeps Figma clean.
+
 **Authoritative spec:** `docs/superpowers/specs/2026-05-10-adhd-push-pull-design-system.md`
 
 ## Phase 1: Validate config
@@ -38,12 +40,14 @@ If Strategy A's response shows visible truncation (look for an unterminated JSON
 
 ## Phase 3: Run the comparator
 
-Use `Bash`:
+Use `Bash`. If the user passed `--include-tailwind`, add `--include-tailwind` to the compare invocation so the diff surfaces every Tailwind default that's missing from Figma. Otherwise omit it — the comparator filters Tailwind-default-origin tokens out of `codeOnly` so the diff stays focused on user-authored changes.
+
 ```bash
 node plugins/adhd/lib/design-system/cli.js compare \
   --code /tmp/adhd-push/globals.css \
   --figma /tmp/adhd-push/figma.json \
-  --output /tmp/adhd-push/diff.json
+  --output /tmp/adhd-push/diff.json \
+  [--include-tailwind]
 ```
 
 Read `/tmp/adhd-push/diff.json`. The diff has four arrays: `same`, `conflict`, `codeOnly`, `figmaOnly`.

From 1f9a8744b5a40ed37851a481dbcb928305f6222a Mon Sep 17 00:00:00 2001
From: Hugh Francis <hughfrancis89@gmail.com>
Date: Tue, 12 May 2026 14:00:24 -0400
Subject: [PATCH 58/79] push-tokens: round-trip canonicalization + skip font
 families + alias-target normalization
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Three round-trip bugs surfacing on real Figma projects, all stemming
from CSS-var-name lossiness:

1. Path-tokenization canonicalization. Figma variable named `Color/gold-25`
   (single leaf with internal hyphen) pulls as `--color-gold-25`, but the
   parser tokenizes that back as path `gold/25` on push — so the same
   variable looks like a fresh codeOnly token and push creates a duplicate
   in Figma. The comparator now does a reclaim pass: any (codeOnly,
   figmaOnly) pair that canonicalizes to the same CSS-var name moves into
   `same`. Domain still separates collisions — color/gold-25 vs
   shadow/gold-25 stay distinct.

2. Alias target canonicalization. `var(--color-neutral-0)` in code
   tokenizes to alias-target `neutral/0`; Figma extract stores
   `target.name` verbatim ("neutral-0"). Without normalization the
   comparator saw aliases as conflicting even when they pointed at the
   same variable. valuesEqual now compares targets with slashes collapsed
   to hyphens.

3. Font families don't push as variables. `--font-aeonik` and friends
   belong in Figma's text-style system — pushing as STRING variables
   creates a competing channel. The action builder emits a
   `skip-font-family` action so the SKILL surfaces the reason in the
   report. Font weights, sizes, line-heights, and tracking still push
   (scalar values, variables are the right home).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 .../__tests__/comparator.test.js              | 59 +++++++++++++++++++
 .../__tests__/figma-write-actions.test.js     | 35 ++++++++---
 plugins/adhd/lib/design-system/comparator.js  | 56 ++++++++++++++++--
 .../lib/design-system/figma-write-actions.js  | 16 +++++
 plugins/adhd/skills/push-tokens/SKILL.md      |  7 +++
 5 files changed, 160 insertions(+), 13 deletions(-)

diff --git a/plugins/adhd/lib/design-system/__tests__/comparator.test.js b/plugins/adhd/lib/design-system/__tests__/comparator.test.js
index c87d846..1c12bfc 100644
--- a/plugins/adhd/lib/design-system/__tests__/comparator.test.js
+++ b/plugins/adhd/lib/design-system/__tests__/comparator.test.js
@@ -205,6 +205,65 @@ test('valuesEqual: still flags real value differences after normalization', () =
   assert.equal(r.same.length, 0);
 });
 
+test('canonicalization: code path "gold/25" and figma path "gold-25" reconcile to `same` (round-trip dup fix)', () => {
+  // The lossy-CSS-var bug: pull-tokens wrote `--color-gold-25` for a
+  // Figma variable named `Color/gold-25` (single leaf with internal
+  // hyphen). On push, code-parser tokenizes the CSS var as path `gold/25`
+  // (split-on-first-hyphen interpretation). Without canonicalization, the
+  // comparator sees `gold/25` in code and `gold-25` in Figma as distinct
+  // tokens — push would create a duplicate Figma variable. Canonicalization
+  // pairs them up by CSS-var equivalence.
+  const code = {
+    tokens: [{ domain: 'color', path: 'gold/25', values: { default: { type: 'literal', value: '#c5a572' } } }],
+    styles: { effects: [] },
+  };
+  const figma = {
+    tokens: [{ domain: 'color', path: 'gold-25', values: { default: { type: 'literal', value: '#c5a572' } } }],
+    styles: { effects: [] },
+  };
+  const diff = compareDesignSystems(code, figma);
+  assert.equal(diff.same.length, 1);
+  assert.equal(diff.codeOnly.length, 0);
+  assert.equal(diff.figmaOnly.length, 0);
+});
+
+test('canonicalization: alias targets match across "neutral/0" (code) and "neutral-0" (figma)', () => {
+  // Same root cause, alias edition. A Figma variable that aliases
+  // `neutral-0` pulls into code as `var(--color-neutral-0)`, which the
+  // code-parser interprets as alias-target `neutral/0`. Both should
+  // compare equal so push doesn't see a phantom conflict.
+  const code = {
+    tokens: [{ domain: 'color', path: 'background', values: { light: { type: 'alias', target: 'neutral/0' } } }],
+    styles: { effects: [] },
+  };
+  const figma = {
+    tokens: [{ domain: 'color', path: 'background', values: { light: { type: 'alias', target: 'neutral-0' } } }],
+    styles: { effects: [] },
+  };
+  const diff = compareDesignSystems(code, figma);
+  assert.equal(diff.same.length, 1);
+  assert.equal(diff.conflict.length, 0);
+});
+
+test('canonicalization: distinct domains don\'t collide even when paths canonicalize the same', () => {
+  // `color/gold/25` and `shadow/gold/25` would both reduce to similar
+  // CSS-var-equivalent forms — but their domain prefix differs
+  // (--color-gold-25 vs --shadow-gold-25). They must stay distinct.
+  const code = {
+    tokens: [{ domain: 'color', path: 'gold/25', values: { default: { type: 'literal', value: '#c5a572' } } }],
+    styles: { effects: [] },
+  };
+  const figma = {
+    tokens: [{ domain: 'shadow', path: 'gold/25', values: { default: { type: 'literal', value: '0 1px 2px black' } } }],
+    styles: { effects: [] },
+  };
+  const diff = compareDesignSystems(code, figma);
+  // Neither moves to `same` — different domains, different CSS vars.
+  assert.equal(diff.same.length, 0);
+  assert.equal(diff.codeOnly.length, 1);
+  assert.equal(diff.figmaOnly.length, 1);
+});
+
 test('codeOnly: includeTailwindDefaultsInCodeOnly=true keeps the full palette in codeOnly (seed mode)', () => {
   // The seed-the-design-system mode: designers want every Tailwind
   // utility available as a Figma variable. Comparator should NOT filter
diff --git a/plugins/adhd/lib/design-system/__tests__/figma-write-actions.test.js b/plugins/adhd/lib/design-system/__tests__/figma-write-actions.test.js
index 700856a..f81d5b8 100644
--- a/plugins/adhd/lib/design-system/__tests__/figma-write-actions.test.js
+++ b/plugins/adhd/lib/design-system/__tests__/figma-write-actions.test.js
@@ -80,25 +80,42 @@ test('spacing token with 0.25rem produces FLOAT create-variable with resolved va
   assert.equal(actions[0].resolvedByMode.default, 4);
 });
 
-test('font-family typography token produces STRING create-variable', () => {
+test('font-family typography tokens are skipped (text-styles channel, not variables)', () => {
+  // Font families belong in Figma's text-style system, not its variable
+  // system. Pushing them as STRING variables creates a parallel channel
+  // that competes with the designer's text-style workflow. The action
+  // builder emits a `skip-font-family` action so the SKILL can surface
+  // the reason in the report instead of silently dropping the token.
   const diff = {
     same: [], conflict: [], figmaOnly: [],
     codeOnly: [{
       domain: 'typography',
       path: 'font/sans',
-      values: {
-        default: { type: 'literal', value: 'ui-sans-serif, system-ui, sans-serif' },
-      },
+      values: { default: { type: 'literal', value: 'ui-sans-serif, system-ui, sans-serif' } },
+    }],
+  };
+  const actions = buildFigmaActions(diff, [], 'push');
+  assert.equal(actions.length, 1);
+  assert.equal(actions[0].kind, 'skip-font-family');
+  assert.equal(actions[0].path, 'font/sans');
+  assert.match(actions[0].reason, /text styles, not variables/);
+});
+
+test('font-weight typography tokens still push as variables (only font families skip)', () => {
+  // `--font-weight-bold` lives under the typography domain but it's a
+  // scalar value designers consume as a Tailwind utility — variables are
+  // the right home. Only the `font/<family>` path triggers the skip.
+  const diff = {
+    same: [], conflict: [], figmaOnly: [],
+    codeOnly: [{
+      domain: 'typography',
+      path: 'font-weight/bold',
+      values: { default: { type: 'literal', value: '700' } },
     }],
   };
   const actions = buildFigmaActions(diff, [], 'push');
   assert.equal(actions.length, 1);
   assert.equal(actions[0].kind, 'create-variable');
-  assert.equal(actions[0].type, 'STRING');
-  assert.equal(
-    actions[0].resolvedByMode.default,
-    'ui-sans-serif, system-ui, sans-serif',
-  );
 });
 
 test('shadow token produces a create-effect-style action', () => {
diff --git a/plugins/adhd/lib/design-system/comparator.js b/plugins/adhd/lib/design-system/comparator.js
index b1daede..746fdd1 100644
--- a/plugins/adhd/lib/design-system/comparator.js
+++ b/plugins/adhd/lib/design-system/comparator.js
@@ -1,5 +1,28 @@
 'use strict';
 
+const { pathToCssVar } = require('./figma-write-actions');
+
+// CSS variable names are lossy: a Figma variable named `Color/gold-25`
+// (single leaf with an internal hyphen) and one named `Color/gold/25`
+// (two-segment path) both pull to `--color-gold-25` in globals.css.
+// The path reconstruction on push always picks the slash interpretation
+// (`gold/25`), so the same underlying variable looks like a fresh
+// codeOnly token to the comparator and push would duplicate it in Figma.
+// Canonicalize to the CSS-var form so both interpretations match.
+function tokenCanonicalKey(t) {
+  try { return pathToCssVar(t.domain, t.path); }
+  catch { return null; }
+}
+
+// Same canonicalization for alias targets — Figma stores `target.name`
+// verbatim ("neutral-0"), code stores the parsed path ("neutral/0"). They
+// describe the same variable; collapse to a hyphenated form so a
+// round-tripped alias compares equal regardless of which side authored it.
+function canonicalizeAliasTarget(target) {
+  if (target == null) return '';
+  return String(target).replace(/\//g, '-').toLowerCase();
+}
+
 // Convert "0.25rem" / "16px" / "1.5" → number (px). Returns null if not a
 // simple dimension/unitless number. Mirrors dimensionToPx in figma-write-actions.
 function dimensionToPx(raw) {
@@ -49,7 +72,7 @@ function valuesEqual(a, b) {
   if (!a || !b) return false;
   if (a.type !== b.type) return false;
   if (a.type === 'alias') {
-    return a.target === b.target;
+    return canonicalizeAliasTarget(a.target) === canonicalizeAliasTarget(b.target);
   }
   // literal
   return canonicalLiteral(a.value) === canonicalLiteral(b.value);
@@ -137,6 +160,31 @@ function compareDesignSystems(code, figma, opts = {}) {
     }
   }
 
+  // Reclaim cross-tokenization duplicates. The per-domain matching above
+  // keys on `domain:path` with the literal path strings — `gold/25` and
+  // `gold-25` are distinct keys even though they describe the same Figma
+  // variable. Canonicalize both sides to the CSS-var form and pair them
+  // up: any (codeOnly, figmaOnly) pair that resolves to the same CSS var
+  // moves into `same`. Without this step, push would create a duplicate
+  // variable in Figma every time pull pulled a single-leaf hyphenated name.
+  const figmaByCanon = new Map();
+  for (const t of figmaOnly) {
+    const key = tokenCanonicalKey(t);
+    if (key) figmaByCanon.set(key, t);
+  }
+  const survivedCodeOnly = [];
+  const matchedFigma = new Set();
+  for (const t of codeOnly) {
+    const key = tokenCanonicalKey(t);
+    if (key && figmaByCanon.has(key)) {
+      same.push(t);
+      matchedFigma.add(figmaByCanon.get(key));
+    } else {
+      survivedCodeOnly.push(t);
+    }
+  }
+  const survivedFigmaOnly = figmaOnly.filter(t => !matchedFigma.has(t));
+
   // Filter Tailwind-default-origin tokens out of codeOnly UNLESS the
   // caller explicitly asked to include them. Defaulting to filtered keeps
   // day-to-day pushes focused on authored changes (no 400-entry palette
@@ -145,8 +193,8 @@ function compareDesignSystems(code, figma, opts = {}) {
   // a Figma variable. Tokens that surface in `same` or `conflict` are
   // unaffected — those reflect real state on the Figma side already.
   const filteredCodeOnly = includeTailwindInCodeOnly
-    ? codeOnly
-    : codeOnly.filter(t => t.fromTailwindDefault !== true);
+    ? survivedCodeOnly
+    : survivedCodeOnly.filter(t => t.fromTailwindDefault !== true);
 
   // ── Effect styles ──────────────────────────────────────────────────────
   // Diff by name only. Each side may not have styles at all (older callers).
@@ -166,7 +214,7 @@ function compareDesignSystems(code, figma, opts = {}) {
     },
   };
 
-  return { same, conflict, codeOnly: filteredCodeOnly, figmaOnly, styles };
+  return { same, conflict, codeOnly: filteredCodeOnly, figmaOnly: survivedFigmaOnly, styles };
 }
 
 module.exports = { compareDesignSystems, valuesEqual };
diff --git a/plugins/adhd/lib/design-system/figma-write-actions.js b/plugins/adhd/lib/design-system/figma-write-actions.js
index 3fccc5b..2fe407a 100644
--- a/plugins/adhd/lib/design-system/figma-write-actions.js
+++ b/plugins/adhd/lib/design-system/figma-write-actions.js
@@ -128,6 +128,22 @@ function buildFigmaActions(diff, resolutions, direction) {
     ]);
     // Code-only: create in Figma
     for (const t of diff.codeOnly) {
+      // Font-family tokens (`--font-sans`, `--font-aeonik`, etc.) shouldn't
+      // round-trip as Figma variables. Designers use Figma's TEXT STYLES
+      // for typography choices — pushing fonts as string variables creates
+      // a parallel channel that competes with the text-style system and
+      // confuses the design surface. Skip them at the action level so the
+      // user gets a clear reason. (Font-weight, text-size, line-height,
+      // tracking still push — those are scalar values that variables
+      // handle well; only `font-*` family names land in text styles.)
+      if (t.domain === 'typography' && t.path.startsWith('font/')) {
+        actions.push({
+          kind: 'skip-font-family',
+          path: t.path,
+          reason: 'Font families belong in Figma text styles, not variables. Manage these directly in the Figma typography panel.',
+        });
+        continue;
+      }
       // Shadow tokens map to Figma effect styles, not variables. Parse the
       // CSS shadow string and emit a create-effect-style action.
       if (t.domain === 'shadow') {
diff --git a/plugins/adhd/skills/push-tokens/SKILL.md b/plugins/adhd/skills/push-tokens/SKILL.md
index 0eef535..e745f2d 100644
--- a/plugins/adhd/skills/push-tokens/SKILL.md
+++ b/plugins/adhd/skills/push-tokens/SKILL.md
@@ -122,6 +122,13 @@ Print:
   - <K> figma-only variables left untouched (additive policy)
 ```
 
+Also count `skip-font-family` actions in `actions.json` and append a note if any are present:
+
+```
+  - <F> font family token(s) skipped — these belong in Figma text styles, not variables.
+    Manage `font-*` families in the Figma typography panel directly.
+```
+
 ## Common errors
 
 | Error | Fix-up guidance |

From bd22dca007397fd2e5fb189fb1de4fe4abd8dc47 Mon Sep 17 00:00:00 2001
From: Hugh Francis <hughfrancis89@gmail.com>
Date: Tue, 12 May 2026 14:20:39 -0400
Subject: [PATCH 59/79] push-tokens: 7-question disposition wizard runs on
 every push
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Designers want a conscious per-push decision about what gets pushed to
Figma, with different domains warranting different choices: push all
colors or only my semantic tokens? Skip opacity (Tailwind's class-modifier
pattern) or push for documentation? Push z-index/animate/ease/etc that
Figma can't even consume?

Wizard runs at Phase 1.5 of /adhd:push-tokens on every invocation —
including --dry-run, so the dry-run preview reflects exactly the choices
the live push would make. No persistence: dispositions live in /tmp
for the run only.

Seven questions, ordered by impact:
  1. Color: all / semantic-only / skip
  2. Typography (sans family — always text-styles): all / sizes+weights / skip
  3. Spacing: all / authored-only / skip
  4. Radius + border-width: push / skip
  5. Shadow: effect-styles / skip
  6. Opacity: skip (recommended) / push
  7. Utility domains (z-index, animate, ease, aspect, perspective,
     container, breakpoint, blur): skip (recommended) / push

New module `dispositions.js` classifies each codeOnly token per the
wizard's answers. Action builder emits `skip-by-disposition` (with the
specific reason) for filtered tokens — preview groups skips by reason
so designers see exactly what's been filtered and why. Dry-run preview
splits into "Would add" vs "Would NOT add (filtered)" lanes. Final
report counts the skips so the policy is verifiable end-to-end.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 README.md                                     |   2 +-
 .../__tests__/dispositions.test.js            | 118 ++++++++++++++
 .../__tests__/figma-write-actions.test.js     |  27 ++--
 plugins/adhd/lib/design-system/cli.js         |  97 ++++++++++--
 .../adhd/lib/design-system/dispositions.js    | 149 ++++++++++++++++++
 .../lib/design-system/figma-write-actions.js  |  28 ++--
 plugins/adhd/skills/push-tokens/SKILL.md      |  88 ++++++++++-
 7 files changed, 460 insertions(+), 49 deletions(-)
 create mode 100644 plugins/adhd/lib/design-system/__tests__/dispositions.test.js
 create mode 100644 plugins/adhd/lib/design-system/dispositions.js

diff --git a/README.md b/README.md
index 8e4a53d..b8863a9 100644
--- a/README.md
+++ b/README.md
@@ -30,7 +30,7 @@ After install, nine slash commands are available:
 |---|---|---|---|
 | `/adhd:config` | — | — | Interactive wizard that produces `adhd.config.ts`. Verifies the official Figma plugin is installed + authenticated before anything else. |
 | `/adhd:lint` | `[<figma-url>] [--annotate] [--fix]` | read-only by default | Validates the Figma file (whole file or scoped) against the local design system + structure best-practices. With `--annotate`, also writes Figma annotations on each offending node in a "lint" category. With `--fix`, walks STRUCT013 Tailwind-duplicate candidates per-prompt and consolidates approved ones (rebinds bindings to the canonical Tailwind variable, then deletes the duplicate). |
-| `/adhd:push-tokens` | `[--dry-run] [--include-tailwind]` | code → Figma | Pushes globals.css variables + named styles into Figma directly via the remote MCP. `--dry-run` previews what would be added or overwritten without writing. `--include-tailwind` also pushes every Tailwind v4 default (full palette, spacing scale, etc.) — use as a one-time seed so designers have every utility available as a Figma variable. |
+| `/adhd:push-tokens` | `[--dry-run] [--include-tailwind]` | code → Figma | Pushes globals.css variables + named styles into Figma directly via the remote MCP. Runs an interactive 7-question wizard on every invocation to set per-domain push policy (push all colors vs semantic-only, skip opacity entirely, route shadows through effect styles, etc.). `--dry-run` previews what would be added or skipped without writing — the preview reflects your wizard answers. `--include-tailwind` also surfaces every Tailwind v4 default in the diff (full palette, spacing scale, etc.) — use as a one-time seed so designers have every utility available as a Figma variable. |
 | `/adhd:pull-tokens` | `[--dry-run]` | Figma → code | Pulls Figma variables + named styles into globals.css. `--dry-run` previews without writing. |
 | `/adhd:push-component` | `<path> [--max-variants <n>] [--annotate]` | code → Figma | Pushes a React component to Figma as a structured Component Set with variant properties + variable bindings, plus a preflight lint check. `--annotate` annotates preflight violations on Figma nodes. |
 | `/adhd:push-all-components` | `[--continue-on-error] [--max-variants <n>] [--annotate]` | code → Figma | Bulk version of `push-component` — iterates over every entry in `adhd.config.ts`'s components map. Sequential, halt-on-first-failure by default. |
diff --git a/plugins/adhd/lib/design-system/__tests__/dispositions.test.js b/plugins/adhd/lib/design-system/__tests__/dispositions.test.js
new file mode 100644
index 0000000..8f5db42
--- /dev/null
+++ b/plugins/adhd/lib/design-system/__tests__/dispositions.test.js
@@ -0,0 +1,118 @@
+'use strict';
+
+const test = require('node:test');
+const assert = require('node:assert/strict');
+const { classifyToken, parsePushTokensFromConfig, formatPushTokensForConfig } = require('../dispositions');
+
+const tok = (domain, path, extras = {}) => ({ domain, path, ...extras });
+
+test('font families always skip (hardcoded, regardless of dispositions)', () => {
+  const v = classifyToken(tok('typography', 'font/aeonik'), { typography: 'all' });
+  assert.equal(v.action, 'skip');
+  assert.match(v.reason, /font-family/);
+});
+
+test('color "all": pushes both palette + semantic', () => {
+  const dispositions = { color: 'all' };
+  assert.equal(classifyToken(tok('color', 'zinc/500', { fromTailwindDefault: true }), dispositions).action, 'push');
+  assert.equal(classifyToken(tok('color', 'brand'), dispositions).action, 'push');
+});
+
+test('color "semantic-only": skips Tailwind palette, keeps authored', () => {
+  const dispositions = { color: 'semantic-only' };
+  const palette = classifyToken(tok('color', 'zinc/500', { fromTailwindDefault: true }), dispositions);
+  assert.equal(palette.action, 'skip');
+  assert.match(palette.reason, /semantic-only/);
+  assert.equal(classifyToken(tok('color', 'brand'), dispositions).action, 'push');
+});
+
+test('color "skip": nothing pushes', () => {
+  assert.equal(classifyToken(tok('color', 'brand'), { color: 'skip' }).action, 'skip');
+  assert.equal(classifyToken(tok('color', 'zinc/500', { fromTailwindDefault: true }), { color: 'skip' }).action, 'skip');
+});
+
+test('typography "sizes-and-weights": text-* and font-weight-* push, leading/tracking skip', () => {
+  const dispositions = { typography: 'sizes-and-weights' };
+  assert.equal(classifyToken(tok('typography', 'text/sm'), dispositions).action, 'push');
+  assert.equal(classifyToken(tok('typography', 'font-weight/bold'), dispositions).action, 'push');
+  assert.equal(classifyToken(tok('typography', 'leading/relaxed'), dispositions).action, 'skip');
+  assert.equal(classifyToken(tok('typography', 'tracking/tight'), dispositions).action, 'skip');
+});
+
+test('spacing "authored-only": Tailwind defaults skip, authored push', () => {
+  const dispositions = { spacing: 'authored-only' };
+  const tw = classifyToken(tok('spacing', '4', { fromTailwindDefault: true }), dispositions);
+  assert.equal(tw.action, 'skip');
+  assert.equal(classifyToken(tok('spacing', 'card-gap'), dispositions).action, 'push');
+});
+
+test('radius / border-width: push by default, skip when set', () => {
+  assert.equal(classifyToken(tok('radius', 'sm'), {}).action, 'push');
+  assert.equal(classifyToken(tok('border-width', 'thin'), {}).action, 'push');
+  assert.equal(classifyToken(tok('radius', 'sm'), { radiusAndBorder: 'skip' }).action, 'skip');
+});
+
+test('shadow: routes to effect-style when push enabled, skip otherwise', () => {
+  assert.equal(classifyToken(tok('shadow', 'md'), {}).action, 'effect-style');
+  assert.equal(classifyToken(tok('shadow', 'md'), { shadow: 'skip' }).action, 'skip');
+});
+
+test('opacity defaults to skip (Tailwind uses /<percent> class modifiers)', () => {
+  const v = classifyToken(tok('opacity', '50'), {});
+  assert.equal(v.action, 'skip');
+  assert.match(v.reason, /class modifier/);
+  assert.equal(classifyToken(tok('opacity', '50'), { opacity: 'push' }).action, 'push');
+});
+
+test('utility domains (animate/ease/aspect/perspective/container/breakpoint/z-index/blur) default to skip', () => {
+  const utils = ['animate', 'ease', 'aspect', 'perspective', 'container', 'breakpoint', 'z-index', 'blur'];
+  for (const dom of utils) {
+    const v = classifyToken(tok(dom, 'x'), {});
+    assert.equal(v.action, 'skip', `${dom} should skip by default`);
+    assert.match(v.reason, /utilityDomains/);
+  }
+});
+
+test('utility domains push when explicitly enabled', () => {
+  for (const dom of ['animate', 'breakpoint', 'z-index']) {
+    assert.equal(classifyToken(tok(dom, 'x'), { utilityDomains: 'push' }).action, 'push');
+  }
+});
+
+test('parsePushTokensFromConfig: returns null when no block present', () => {
+  assert.equal(parsePushTokensFromConfig(`export default { figma: { url: 'x' } };`), null);
+  assert.equal(parsePushTokensFromConfig(''), null);
+  assert.equal(parsePushTokensFromConfig(null), null);
+});
+
+test('parsePushTokensFromConfig: extracts a well-formed block', () => {
+  const src = `
+    export default {
+      figma: { url: "https://figma.com/design/abc" },
+      pushTokens: {
+        color: "all",
+        typography: "sizes-and-weights",
+        opacity: "skip",
+      },
+      naming: "kebab-case",
+    };
+  `;
+  const out = parsePushTokensFromConfig(src);
+  assert.deepEqual(out, { color: 'all', typography: 'sizes-and-weights', opacity: 'skip' });
+});
+
+test('formatPushTokensForConfig: produces a stable, insertable block', () => {
+  const out = formatPushTokensForConfig({
+    color: 'all',
+    typography: 'all',
+    spacing: 'all',
+    radiusAndBorder: 'push',
+    shadow: 'effect-styles',
+    opacity: 'skip',
+    utilityDomains: 'skip',
+  });
+  assert.match(out, /^  pushTokens: \{\n/);
+  // Stable order — color first.
+  assert.match(out, /color: "all"/);
+  assert.match(out, /utilityDomains: "skip"/);
+});
diff --git a/plugins/adhd/lib/design-system/__tests__/figma-write-actions.test.js b/plugins/adhd/lib/design-system/__tests__/figma-write-actions.test.js
index f81d5b8..c5b01dd 100644
--- a/plugins/adhd/lib/design-system/__tests__/figma-write-actions.test.js
+++ b/plugins/adhd/lib/design-system/__tests__/figma-write-actions.test.js
@@ -82,10 +82,9 @@ test('spacing token with 0.25rem produces FLOAT create-variable with resolved va
 
 test('font-family typography tokens are skipped (text-styles channel, not variables)', () => {
   // Font families belong in Figma's text-style system, not its variable
-  // system. Pushing them as STRING variables creates a parallel channel
-  // that competes with the designer's text-style workflow. The action
-  // builder emits a `skip-font-family` action so the SKILL can surface
-  // the reason in the report instead of silently dropping the token.
+  // system. The disposition classifier hardcodes this skip so it applies
+  // even when the user picks "push all typography" — text styles are the
+  // right channel period.
   const diff = {
     same: [], conflict: [], figmaOnly: [],
     codeOnly: [{
@@ -94,11 +93,11 @@ test('font-family typography tokens are skipped (text-styles channel, not variab
       values: { default: { type: 'literal', value: 'ui-sans-serif, system-ui, sans-serif' } },
     }],
   };
-  const actions = buildFigmaActions(diff, [], 'push');
+  const actions = buildFigmaActions(diff, [], 'push', { dispositions: { typography: 'all' } });
   assert.equal(actions.length, 1);
-  assert.equal(actions[0].kind, 'skip-font-family');
+  assert.equal(actions[0].kind, 'skip-by-disposition');
   assert.equal(actions[0].path, 'font/sans');
-  assert.match(actions[0].reason, /text styles, not variables/);
+  assert.match(actions[0].reason, /font-family/);
 });
 
 test('font-weight typography tokens still push as variables (only font families skip)', () => {
@@ -216,6 +215,8 @@ test('color token still emits COLOR-typed create-variable (regression guard)', (
 });
 
 test('opacity token (0.05) → FLOAT in `opacity` collection', () => {
+  // Opacity defaults to skip (Tailwind's class-modifier pattern), so this
+  // test passes an opt-in disposition to exercise the create-variable shape.
   const diff = {
     same: [], conflict: [], figmaOnly: [],
     codeOnly: [{
@@ -223,7 +224,7 @@ test('opacity token (0.05) → FLOAT in `opacity` collection', () => {
       values: { default: { type: 'literal', value: '0.05' } },
     }],
   };
-  const actions = buildFigmaActions(diff, [], 'push');
+  const actions = buildFigmaActions(diff, [], 'push', { dispositions: { opacity: 'push' } });
   assert.equal(actions.length, 1);
   assert.equal(actions[0].kind, 'create-variable');
   assert.equal(actions[0].collection, 'opacity');
@@ -253,7 +254,7 @@ test('z-index token (50, unitless) → FLOAT in `z-index` collection', () => {
       values: { default: { type: 'literal', value: '50' } },
     }],
   };
-  const actions = buildFigmaActions(diff, [], 'push');
+  const actions = buildFigmaActions(diff, [], 'push', { dispositions: { utilityDomains: 'push' } });
   assert.equal(actions[0].collection, 'z-index');
   assert.equal(actions[0].type, 'FLOAT');
   assert.equal(actions[0].resolvedByMode.default, 50);
@@ -267,7 +268,7 @@ test('breakpoint token (40rem) → FLOAT converted to 640 px', () => {
       values: { default: { type: 'literal', value: '40rem' } },
     }],
   };
-  const actions = buildFigmaActions(diff, [], 'push');
+  const actions = buildFigmaActions(diff, [], 'push', { dispositions: { utilityDomains: 'push' } });
   assert.equal(actions[0].collection, 'breakpoint');
   assert.equal(actions[0].type, 'FLOAT');
   assert.equal(actions[0].resolvedByMode.default, 640);
@@ -281,7 +282,7 @@ test('aspect token (16 / 9) → STRING in `aspect` collection', () => {
       values: { default: { type: 'literal', value: '16 / 9' } },
     }],
   };
-  const actions = buildFigmaActions(diff, [], 'push');
+  const actions = buildFigmaActions(diff, [], 'push', { dispositions: { utilityDomains: 'push' } });
   assert.equal(actions[0].collection, 'aspect');
   assert.equal(actions[0].type, 'STRING');
   assert.equal(actions[0].resolvedByMode.default, '16 / 9');
@@ -295,7 +296,7 @@ test('ease cubic-bezier → STRING in `ease` collection', () => {
       values: { default: { type: 'literal', value: 'cubic-bezier(0.4, 0, 0.2, 1)' } },
     }],
   };
-  const actions = buildFigmaActions(diff, [], 'push');
+  const actions = buildFigmaActions(diff, [], 'push', { dispositions: { utilityDomains: 'push' } });
   assert.equal(actions[0].collection, 'ease');
   assert.equal(actions[0].type, 'STRING');
   assert.equal(actions[0].resolvedByMode.default, 'cubic-bezier(0.4, 0, 0.2, 1)');
@@ -309,7 +310,7 @@ test('animate shorthand → STRING in `animate` collection', () => {
       values: { default: { type: 'literal', value: 'spin 1s linear infinite' } },
     }],
   };
-  const actions = buildFigmaActions(diff, [], 'push');
+  const actions = buildFigmaActions(diff, [], 'push', { dispositions: { utilityDomains: 'push' } });
   assert.equal(actions[0].collection, 'animate');
   assert.equal(actions[0].type, 'STRING');
 });
diff --git a/plugins/adhd/lib/design-system/cli.js b/plugins/adhd/lib/design-system/cli.js
index d04358f..c83cd35 100644
--- a/plugins/adhd/lib/design-system/cli.js
+++ b/plugins/adhd/lib/design-system/cli.js
@@ -54,20 +54,27 @@ assemble-extract:
 }
 
 // Renders a value (hex string, px string, shadow descriptor, etc.) in a
-// single short token. Shadows / nested objects collapse to a short JSON
-// representation so the alignment column stays sane. Conservative — the
-// preview is for spot-checking, not full fidelity.
+// single short token. TokenValue objects from the parsers come in two
+// shapes — `{type: 'literal', value}` and `{type: 'alias', target}` —
+// unwrap them so designers see `#fff` instead of `{"type":"literal",...}`.
 function fmtValue(v) {
   if (v == null) return '—';
   if (typeof v === 'string') return v;
   if (typeof v === 'number') return String(v);
+  if (v && typeof v === 'object') {
+    if (v.type === 'literal' && 'value' in v) return String(v.value);
+    if (v.type === 'alias' && 'target' in v) return `→ ${v.target}`;
+  }
   try { return JSON.stringify(v); } catch { return String(v); }
 }
 
 // One line per (path, mode). Code-only and figma-only token entries store
 // their values per mode under `values`; conflict entries already arrive
-// flattened by mode.
-function formatPreview(diff, direction) {
+// flattened by mode. When `actions` is provided (push-direction dry-run
+// with dispositions), entries are split into "would push" vs "would
+// skip" buckets so designers see the actual outcome of their disposition
+// choices, not the unfiltered diff.
+function formatPreview(diff, direction, actions = null) {
   if (direction !== 'push' && direction !== 'pull') {
     throw new Error(`preview: --direction must be 'push' or 'pull', got '${direction}'`);
   }
@@ -89,10 +96,23 @@ function formatPreview(diff, direction) {
   const FLAT_THRESHOLD = 25;
   const BUCKET_SAMPLE_SIZE = 6;
 
+  // When actions are available, build a (domain, path) → skipReason map
+  // so we can label each row's disposition outcome. Push-action tokens
+  // produce no map entry — they push as normal.
+  const skipReasonByKey = new Map();
+  if (actions && direction === 'push') {
+    for (const a of actions) {
+      if (a.kind === 'skip-by-disposition') {
+        skipReasonByKey.set((a.domain || '') + ':' + a.path, a.reason);
+      }
+    }
+  }
+
   const addRows = [];
   for (const tok of fromOnly) {
+    const skipReason = skipReasonByKey.get((tok.domain || '') + ':' + tok.path) || null;
     for (const [mode, value] of Object.entries(tok.values || {})) {
-      addRows.push({ path: tok.path, mode, value, domain: tok.domain || 'other' });
+      addRows.push({ path: tok.path, mode, value, domain: tok.domain || 'other', skipReason });
     }
   }
   addRows.sort((a, b) =>
@@ -101,13 +121,19 @@ function formatPreview(diff, direction) {
     a.mode.localeCompare(b.mode),
   );
 
-  if (addRows.length === 0) {
+  // Split into push and skip lanes when dispositions are available; the
+  // skip lane shows reasons so designers see exactly why their tokens
+  // are filtered out.
+  const pushRows = addRows.filter(r => !r.skipReason);
+  const skipRows = addRows.filter(r => r.skipReason);
+
+  if (pushRows.length === 0) {
     lines.push(`Would add to ${toSide}: none.`);
-  } else if (addRows.length <= FLAT_THRESHOLD) {
-    lines.push(`Would add to ${toSide} (${addRows.length} entr${addRows.length === 1 ? 'y' : 'ies'}):`);
-    const pathW = Math.max(...addRows.map(r => r.path.length));
-    const modeW = Math.max(...addRows.map(r => r.mode.length));
-    for (const r of addRows) {
+  } else if (pushRows.length <= FLAT_THRESHOLD) {
+    lines.push(`Would add to ${toSide} (${pushRows.length} entr${pushRows.length === 1 ? 'y' : 'ies'}):`);
+    const pathW = Math.max(...pushRows.map(r => r.path.length));
+    const modeW = Math.max(...pushRows.map(r => r.mode.length));
+    for (const r of pushRows) {
       lines.push(`  + ${r.path.padEnd(pathW)}  (${r.mode.padEnd(modeW)})  = ${fmtValue(r.value)}`);
     }
   } else {
@@ -115,11 +141,11 @@ function formatPreview(diff, direction) {
     // domain so the user can sanity-check the shape without scrolling
     // past hundreds of rows.
     const byDomain = new Map();
-    for (const r of addRows) {
+    for (const r of pushRows) {
       if (!byDomain.has(r.domain)) byDomain.set(r.domain, []);
       byDomain.get(r.domain).push(r);
     }
-    lines.push(`Would add to ${toSide} (${addRows.length} entries across ${byDomain.size} domain${byDomain.size === 1 ? '' : 's'}):`);
+    lines.push(`Would add to ${toSide} (${pushRows.length} entries across ${byDomain.size} domain${byDomain.size === 1 ? '' : 's'}):`);
     for (const domain of [...byDomain.keys()].sort()) {
       const rows = byDomain.get(domain);
       lines.push(``);
@@ -139,6 +165,28 @@ function formatPreview(diff, direction) {
   }
   lines.push('');
 
+  // Skipped-by-disposition lane (only renders when actions were provided).
+  if (skipRows.length > 0) {
+    const byReason = new Map();
+    for (const r of skipRows) {
+      if (!byReason.has(r.skipReason)) byReason.set(r.skipReason, []);
+      byReason.get(r.skipReason).push(r);
+    }
+    lines.push(`Would NOT add to ${toSide} (${skipRows.length} entr${skipRows.length === 1 ? 'y' : 'ies'} filtered by your dispositions):`);
+    for (const [reason, rows] of byReason.entries()) {
+      lines.push(``);
+      lines.push(`  ${rows.length} × ${reason}`);
+      const sample = rows.slice(0, BUCKET_SAMPLE_SIZE);
+      for (const r of sample) {
+        lines.push(`    - ${r.domain}/${r.path}  (${r.mode})  = ${fmtValue(r.value)}`);
+      }
+      if (rows.length > BUCKET_SAMPLE_SIZE) {
+        lines.push(`    [+${rows.length - BUCKET_SAMPLE_SIZE} more]`);
+      }
+    }
+    lines.push('');
+  }
+
   // Conflicts: same path on both sides, different value per mode. Show
   // BOTH sides so the user can judge — the dry run intentionally doesn't
   // pre-resolve in favor of either side, since the prompt loop in Phase 4
@@ -197,7 +245,15 @@ function main() {
   if (cmd === 'apply') {
     const diff = JSON.parse(fs.readFileSync(args.diff, 'utf8'));
     const resolutions = JSON.parse(fs.readFileSync(args.resolutions, 'utf8'));
-    const actions = buildFigmaActions(diff, resolutions, args.direction);
+    // Optional dispositions (push only) — the per-domain policy collected
+    // by /adhd:push-tokens's wizard. When absent, defaults from
+    // dispositions.js apply.
+    let dispositions = null;
+    if (args.dispositions) {
+      try { dispositions = JSON.parse(fs.readFileSync(args.dispositions, 'utf8')); }
+      catch { dispositions = null; }
+    }
+    const actions = buildFigmaActions(diff, resolutions, args.direction, { dispositions });
     fs.writeFileSync(args.output, JSON.stringify(actions, null, 2));
     process.exit(0);
   }
@@ -206,7 +262,16 @@ function main() {
     if (!args.diff) { console.error('Missing --diff'); process.exit(2); }
     if (!args.direction) { console.error('Missing --direction'); process.exit(2); }
     const diff = JSON.parse(fs.readFileSync(args.diff, 'utf8'));
-    process.stdout.write(formatPreview(diff, args.direction) + '\n');
+    // Optional: when actions.json is provided, the preview reflects what
+    // the action builder would actually do — grouping additions into
+    // "would push" vs "would skip — reason". Without it, the preview is
+    // diff-only (legacy behavior).
+    let actions = null;
+    if (args.actions) {
+      try { actions = JSON.parse(fs.readFileSync(args.actions, 'utf8')); }
+      catch { actions = null; }
+    }
+    process.stdout.write(formatPreview(diff, args.direction, actions) + '\n');
     process.exit(0);
   }
 
diff --git a/plugins/adhd/lib/design-system/dispositions.js b/plugins/adhd/lib/design-system/dispositions.js
new file mode 100644
index 0000000..76a5542
--- /dev/null
+++ b/plugins/adhd/lib/design-system/dispositions.js
@@ -0,0 +1,149 @@
+'use strict';
+
+// Push-token dispositions — user-controlled per-domain policy for what
+// gets pushed to Figma, and how. The /adhd:push-tokens wizard collects
+// the seven choices interactively on EVERY push (no persistence —
+// conscious decision each time, dispositions live in /tmp for the run).
+//
+// The categorical "Figma can't consume this anyway" filter (z-index,
+// container queries, animate, ease, etc.) lives here. So does the
+// design-decision filter ("push the full Tailwind color palette, or only
+// my semantic colors?"). Tokens classified as 'skip' surface in the
+// dry-run with their reason, but never become create-variable actions.
+
+const UTILITY_DOMAINS = new Set([
+  'z-index', 'animate', 'ease', 'aspect', 'perspective',
+  'container', 'breakpoint', 'blur',
+]);
+
+// Defaults applied when a key is missing from `dispositions`. Mirrors
+// the "recommended" answer in the wizard so a partial config still
+// behaves predictably.
+const DEFAULT_DISPOSITIONS = {
+  color: 'all',
+  typography: 'all',
+  spacing: 'all',
+  radiusAndBorder: 'push',
+  shadow: 'effect-styles',
+  opacity: 'skip',
+  utilityDomains: 'skip',
+};
+
+// Return { action: 'push' | 'effect-style' | 'skip', reason? } for one
+// token. `dispositions` is the parsed pushTokens object from
+// adhd.config.ts; missing keys fall back to DEFAULT_DISPOSITIONS.
+function classifyToken(token, dispositions) {
+  const d = { ...DEFAULT_DISPOSITIONS, ...(dispositions || {}) };
+  const dom = token.domain;
+  const path = token.path || '';
+
+  // Font families: always skip. Hardcoded — text styles are Figma's
+  // native channel for typography choices, and pushing `--font-aeonik`
+  // as a STRING variable competes with that workflow.
+  if (dom === 'typography' && path.startsWith('font/')) {
+    return { action: 'skip', reason: 'font-family — manage in Figma text styles, not variables' };
+  }
+
+  if (dom === 'color') {
+    if (d.color === 'skip')          return { action: 'skip', reason: 'pushTokens.color = skip' };
+    if (d.color === 'semantic-only' && token.fromTailwindDefault === true) {
+      return { action: 'skip', reason: 'pushTokens.color = semantic-only — Tailwind palette stays in code' };
+    }
+    return { action: 'push' };
+  }
+
+  if (dom === 'typography') {
+    if (d.typography === 'skip') return { action: 'skip', reason: 'pushTokens.typography = skip' };
+    if (d.typography === 'sizes-and-weights') {
+      if (path.startsWith('leading/') || path.startsWith('tracking/')) {
+        return { action: 'skip', reason: 'pushTokens.typography = sizes-and-weights — leading/tracking skipped' };
+      }
+    }
+    return { action: 'push' };
+  }
+
+  if (dom === 'spacing') {
+    if (d.spacing === 'skip') return { action: 'skip', reason: 'pushTokens.spacing = skip' };
+    if (d.spacing === 'authored-only' && token.fromTailwindDefault === true) {
+      return { action: 'skip', reason: 'pushTokens.spacing = authored-only — Tailwind scale stays in code' };
+    }
+    return { action: 'push' };
+  }
+
+  if (dom === 'radius' || dom === 'border-width') {
+    if (d.radiusAndBorder === 'skip') return { action: 'skip', reason: 'pushTokens.radiusAndBorder = skip' };
+    return { action: 'push' };
+  }
+
+  if (dom === 'shadow') {
+    if (d.shadow === 'skip') return { action: 'skip', reason: 'pushTokens.shadow = skip' };
+    return { action: 'effect-style' };
+  }
+
+  if (dom === 'opacity') {
+    if (d.opacity === 'skip') {
+      return { action: 'skip', reason: 'pushTokens.opacity = skip — Tailwind applies opacity via /<percent> class modifiers' };
+    }
+    return { action: 'push' };
+  }
+
+  if (UTILITY_DOMAINS.has(dom)) {
+    if (d.utilityDomains === 'skip') {
+      return { action: 'skip', reason: `pushTokens.utilityDomains = skip — Figma doesn't consume ${dom} tokens` };
+    }
+    return { action: 'push' };
+  }
+
+  // Unknown domain: default to push so it surfaces. Better to let an
+  // unrecognized domain through than silently drop user data.
+  return { action: 'push' };
+}
+
+// Parse the `pushTokens: { ... }` block out of adhd.config.ts. Returns
+// null when no block is present (which signals "run the wizard"). The
+// schema is intentionally simple — one string value per key — so a
+// permissive regex + key-quoting + JSON.parse handles it without
+// requiring a TS evaluator at runtime.
+function parsePushTokensFromConfig(configSrc) {
+  if (!configSrc) return null;
+  const open = /pushTokens\s*:\s*\{/.exec(configSrc);
+  if (!open) return null;
+  let depth = 1;
+  let i = open.index + open[0].length;
+  while (i < configSrc.length && depth > 0) {
+    const ch = configSrc[i];
+    if (ch === '{') depth++;
+    else if (ch === '}') depth--;
+    if (depth === 0) break;
+    i++;
+  }
+  const body = configSrc.slice(open.index + open[0].length, i);
+  // Wrap THEN transform so the leading key has a `{` anchor for the
+  // key-quoting regex. Doing the regex on the bare body would leave the
+  // first key unquoted because there's no `[{,]` directly before it.
+  const jsonish = ('{' + body + '}')
+    .replace(/\/\/[^\n]*/g, '')          // strip line comments
+    .replace(/'/g, '"')                  // single → double quotes
+    .replace(/([{,]\s*)([a-zA-Z_][\w-]*)\s*:/g, '$1"$2":')  // quote keys
+    .replace(/,\s*}/g, '}');             // trailing comma
+  try { return JSON.parse(jsonish); }
+  catch { return null; }
+}
+
+// Serialize a dispositions object into a TS object literal suitable for
+// inserting into adhd.config.ts. Stable key order so diffs stay clean.
+function formatPushTokensForConfig(dispositions) {
+  const order = ['color', 'typography', 'spacing', 'radiusAndBorder', 'shadow', 'opacity', 'utilityDomains'];
+  const lines = order
+    .filter(k => k in dispositions)
+    .map(k => `    ${k}: "${dispositions[k]}",`);
+  return '  pushTokens: {\n' + lines.join('\n') + '\n  },';
+}
+
+module.exports = {
+  classifyToken,
+  parsePushTokensFromConfig,
+  formatPushTokensForConfig,
+  DEFAULT_DISPOSITIONS,
+  UTILITY_DOMAINS,
+};
diff --git a/plugins/adhd/lib/design-system/figma-write-actions.js b/plugins/adhd/lib/design-system/figma-write-actions.js
index 2fe407a..61e2fa2 100644
--- a/plugins/adhd/lib/design-system/figma-write-actions.js
+++ b/plugins/adhd/lib/design-system/figma-write-actions.js
@@ -1,6 +1,7 @@
 'use strict';
 
 const { parseShadow } = require('./shadow-parser');
+const { classifyToken } = require('./dispositions');
 
 const DOMAIN_COLLECTION = {
   color: 'color',
@@ -107,7 +108,8 @@ function pathToCssVar(domain, path) {
   return DOMAIN_PREFIX[domain] + dashed;
 }
 
-function buildFigmaActions(diff, resolutions, direction) {
+function buildFigmaActions(diff, resolutions, direction, opts = {}) {
+  const dispositions = opts.dispositions || null;
   const resolutionMap = new Map();
   for (const r of resolutions) {
     resolutionMap.set(r.path + ':' + (r.mode ?? 'default'), r.winner);
@@ -126,21 +128,21 @@ function buildFigmaActions(diff, resolutions, direction) {
       // not extract.collections), but include here for forward-compat.
       ...(((diff.styles && diff.styles.effects && diff.styles.effects.same) || []).map(s => s.name)),
     ]);
-    // Code-only: create in Figma
+    // Code-only: create in Figma. Each token is classified through the
+    // user's push-token dispositions (collected via the wizard in
+    // /adhd:push-tokens — see dispositions.js). Three outcomes:
+    //   - 'push'         → create-variable
+    //   - 'effect-style' → create-effect-style (shadow)
+    //   - 'skip'         → skip-by-disposition with reason (visible in
+    //                       the dry-run + final report, no Figma write)
     for (const t of diff.codeOnly) {
-      // Font-family tokens (`--font-sans`, `--font-aeonik`, etc.) shouldn't
-      // round-trip as Figma variables. Designers use Figma's TEXT STYLES
-      // for typography choices — pushing fonts as string variables creates
-      // a parallel channel that competes with the text-style system and
-      // confuses the design surface. Skip them at the action level so the
-      // user gets a clear reason. (Font-weight, text-size, line-height,
-      // tracking still push — those are scalar values that variables
-      // handle well; only `font-*` family names land in text styles.)
-      if (t.domain === 'typography' && t.path.startsWith('font/')) {
+      const verdict = classifyToken(t, dispositions);
+      if (verdict.action === 'skip') {
         actions.push({
-          kind: 'skip-font-family',
+          kind: 'skip-by-disposition',
+          domain: t.domain,
           path: t.path,
-          reason: 'Font families belong in Figma text styles, not variables. Manage these directly in the Figma typography panel.',
+          reason: verdict.reason,
         });
         continue;
       }
diff --git a/plugins/adhd/skills/push-tokens/SKILL.md b/plugins/adhd/skills/push-tokens/SKILL.md
index e745f2d..0c7497e 100644
--- a/plugins/adhd/skills/push-tokens/SKILL.md
+++ b/plugins/adhd/skills/push-tokens/SKILL.md
@@ -21,6 +21,64 @@ Read `adhd.config.ts` at the repo root with the `Read` tool. If it doesn't exist
 
 Extract `figma.url` (required) and `cssEntry` (optional; auto-detect `app/globals.css` then `src/app/globals.css`). Extract the file key from `figma.url` — the segment after `/design/`.
 
+## Phase 1.5: Disposition wizard (runs EVERY push)
+
+Walk the user through seven `AskUserQuestion` prompts to set per-domain push policy. The wizard runs on every invocation — including `--dry-run` — so the dry-run preview reflects exactly what the live push would do. No persistence: dispositions live in `/tmp/adhd-push/dispositions.json` for this run only.
+
+Issue each question in order. After each answer, append the resulting key/value to a running dispositions object. Question text and options:
+
+**1. Color** — `Header: "Color"`
+   Question: "Which color tokens should we push to Figma?"
+   - `"Push all (recommended for seeding Figma)"` → `color: "all"`
+   - `"Push semantic only (skip --color-zinc-*, --color-blue-*, etc.)"` → `color: "semantic-only"`
+   - `"Skip colors entirely"` → `color: "skip"`
+
+**2. Typography** — `Header: "Typography"`
+   Question: "Which typography scales should we push? (Font families always route to Figma text styles, never variables.)"
+   - `"Push all scales (text sizes, font-weights, leading, tracking)"` → `typography: "all"`
+   - `"Push sizes + weights only (skip leading + tracking)"` → `typography: "sizes-and-weights"`
+   - `"Skip typography variables"` → `typography: "skip"`
+
+**3. Spacing** — `Header: "Spacing"`
+   Question: "Which spacing tokens should we push?"
+   - `"Push the full Tailwind 0..96 scale"` → `spacing: "all"`
+   - `"Push only my authored spacing tokens (skip Tailwind scale)"` → `spacing: "authored-only"`
+   - `"Skip spacing"` → `spacing: "skip"`
+
+**4. Radius + border width** — `Header: "Radius / border"`
+   Question: "Push corner radius + border-width tokens?"
+   - `"Yes — these bind to Figma's corner radius and stroke weight"` → `radiusAndBorder: "push"`
+   - `"Skip"` → `radiusAndBorder: "skip"`
+
+**5. Shadow** — `Header: "Shadow"`
+   Question: "Push shadow tokens as Figma effect styles?"
+   - `"Yes, push as effect styles (Figma's native shadow channel)"` → `shadow: "effect-styles"`
+   - `"Skip — manage shadows directly in Figma"` → `shadow: "skip"`
+
+**6. Opacity** — `Header: "Opacity"`
+   Question: "Push opacity tokens? Tailwind applies opacity via `/<percent>` class modifiers, not variables."
+   - `"Skip (recommended — matches Tailwind's class-modifier pattern)"` → `opacity: "skip"`
+   - `"Push as variables anyway (for documentation)"` → `opacity: "push"`
+
+**7. Utility domains** — `Header: "Utilities"`
+   Question: "Push utility tokens that Figma doesn't natively consume (z-index, animate, ease, aspect, perspective, container, breakpoint, blur)?"
+   - `"Skip all (recommended — none of these bind to Figma properties)"` → `utilityDomains: "skip"`
+   - `"Push anyway for documentation"` → `utilityDomains: "push"`
+
+After all seven answers, write the dispositions object to `/tmp/adhd-push/dispositions.json` via the `Write` tool. Example shape:
+
+```json
+{
+  "color": "all",
+  "typography": "all",
+  "spacing": "all",
+  "radiusAndBorder": "push",
+  "shadow": "effect-styles",
+  "opacity": "skip",
+  "utilityDomains": "skip"
+}
+```
+
 ## Phase 2: Read both sides
 
 Use the `Read` tool to read the resolved `globals.css` path. Save it to `/tmp/adhd-push/globals.css` via the `Write` tool.
@@ -56,15 +114,26 @@ If `conflict.length === 0` and `codeOnly.length === 0`, print "Figma is already
 
 ## Phase 3b: Dry run (only if `--dry-run` was passed)
 
-If the user invoked `/adhd:push-tokens --dry-run`, print the preview from the comparator and exit BEFORE the prompt loop. The dry run is a pure discovery tool — no `AskUserQuestion`, no writes, no MCP traffic beyond Phase 2's extract:
+If the user invoked `/adhd:push-tokens --dry-run`, build the action plan first (so the preview reflects the user's wizard answers — every disposition's effect shows in the output), then preview, then exit BEFORE the conflict prompts:
 
 ```bash
+# Build actions with the wizard's dispositions but no resolutions
+# (dry-run never resolves conflicts — it surfaces them).
+echo "[]" > /tmp/adhd-push/resolutions.json
+node plugins/adhd/lib/design-system/cli.js apply \
+  --diff /tmp/adhd-push/diff.json \
+  --resolutions /tmp/adhd-push/resolutions.json \
+  --dispositions /tmp/adhd-push/dispositions.json \
+  --direction push \
+  --output /tmp/adhd-push/actions.json
+
 node plugins/adhd/lib/design-system/cli.js preview \
   --diff /tmp/adhd-push/diff.json \
+  --actions /tmp/adhd-push/actions.json \
   --direction push
 ```
 
-The preview lists every variable that would be added to Figma (one row per mode), every variable whose code/Figma values differ (showing both — the dry run intentionally doesn't pre-resolve in favor of either side), and the count of Figma-only variables that would stay untouched per the additive policy. Echo the output verbatim to the user, then print a one-line summary: `Dry run complete. Re-run without --dry-run to apply (you'll be prompted on each conflict).` Exit 0.
+The preview splits additions into two lanes: "Would add to Figma" (tokens the action builder would push) and "Would NOT add to Figma" (tokens filtered by the user's dispositions, grouped by reason). Conflicts surface separately. Echo the output verbatim, then print: `Dry run complete. Re-run without --dry-run to apply (you'll be prompted on each conflict and asked the disposition questions again).` Exit 0.
 
 If `--dry-run` was NOT passed, skip this phase and continue to Phase 4.
 
@@ -84,15 +153,18 @@ Build a `resolutions` array of `{path, mode, winner}` objects. Save it to `/tmp/
 
 ## Phase 5: Build actions
 
+Pass the wizard's dispositions so the action builder honors the user's per-domain choices.
+
 ```bash
 node plugins/adhd/lib/design-system/cli.js apply \
   --diff /tmp/adhd-push/diff.json \
   --resolutions /tmp/adhd-push/resolutions.json \
+  --dispositions /tmp/adhd-push/dispositions.json \
   --direction push \
   --output /tmp/adhd-push/actions.json
 ```
 
-Read `/tmp/adhd-push/actions.json`. If empty, print "Nothing to apply." and exit 0.
+Read `/tmp/adhd-push/actions.json`. Count `skip-by-disposition` entries — they're informational only (no Figma write happens for these). If the file contains only skip actions (no `create-variable` or `create-effect-style`), print "Nothing to push given your disposition choices." and exit 0.
 
 ## Phase 6: Drift check (re-fetch Figma)
 
@@ -122,13 +194,17 @@ Print:
   - <K> figma-only variables left untouched (additive policy)
 ```
 
-Also count `skip-font-family` actions in `actions.json` and append a note if any are present:
+Also count `skip-by-disposition` actions in `actions.json`, group them by `reason`, and append a section if any are present:
 
 ```
-  - <F> font family token(s) skipped — these belong in Figma text styles, not variables.
-    Manage `font-*` families in the Figma typography panel directly.
+  - <S> token(s) skipped by your disposition choices:
+      <count> × <reason>
+      <count> × <reason>
+      ...
 ```
 
+This is informational — the user already chose these in the wizard. Surfacing them in the report confirms the policy held end-to-end.
+
 ## Common errors
 
 | Error | Fix-up guidance |

From 520c452f6042d226b72327cec92d933321e4e22d Mon Sep 17 00:00:00 2001
From: Hugh Francis <hughfrancis89@gmail.com>
Date: Tue, 12 May 2026 14:27:59 -0400
Subject: [PATCH 60/79] push-tokens: drop --include-tailwind (subsumed by
 dispositions wizard)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The wizard's "color: all" and "spacing: all" answers already cover the
seed-the-Tailwind-palette workflow, and "color: semantic-only" /
"spacing: authored-only" cover the focused workflow. The --include-tailwind
binary flag was a coarser version of the same axis — keeping both gave
users two confusing knobs for the same decision.

Comparator is now policy-free: every code-side token surfaces in
codeOnly with the `fromTailwindDefault` marker intact. Filtering moves
entirely to the action-builder layer, driven by the wizard's
dispositions. One source of truth for "what pushes" — the wizard.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 README.md                                     |  2 +-
 .../lib/design-system/__tests__/cli.test.js   | 43 +++++------
 .../__tests__/comparator.test.js              | 38 +++------
 .../__tests__/e2e-pipeline.test.js            | 77 +++++++++++--------
 plugins/adhd/lib/design-system/cli.js         | 22 +++---
 plugins/adhd/lib/design-system/comparator.js  | 29 +++----
 plugins/adhd/skills/push-tokens/SKILL.md      | 15 ++--
 7 files changed, 101 insertions(+), 125 deletions(-)

diff --git a/README.md b/README.md
index b8863a9..1a7e748 100644
--- a/README.md
+++ b/README.md
@@ -30,7 +30,7 @@ After install, nine slash commands are available:
 |---|---|---|---|
 | `/adhd:config` | — | — | Interactive wizard that produces `adhd.config.ts`. Verifies the official Figma plugin is installed + authenticated before anything else. |
 | `/adhd:lint` | `[<figma-url>] [--annotate] [--fix]` | read-only by default | Validates the Figma file (whole file or scoped) against the local design system + structure best-practices. With `--annotate`, also writes Figma annotations on each offending node in a "lint" category. With `--fix`, walks STRUCT013 Tailwind-duplicate candidates per-prompt and consolidates approved ones (rebinds bindings to the canonical Tailwind variable, then deletes the duplicate). |
-| `/adhd:push-tokens` | `[--dry-run] [--include-tailwind]` | code → Figma | Pushes globals.css variables + named styles into Figma directly via the remote MCP. Runs an interactive 7-question wizard on every invocation to set per-domain push policy (push all colors vs semantic-only, skip opacity entirely, route shadows through effect styles, etc.). `--dry-run` previews what would be added or skipped without writing — the preview reflects your wizard answers. `--include-tailwind` also surfaces every Tailwind v4 default in the diff (full palette, spacing scale, etc.) — use as a one-time seed so designers have every utility available as a Figma variable. |
+| `/adhd:push-tokens` | `[--dry-run]` | code → Figma | Pushes globals.css variables + named styles into Figma directly via the remote MCP. Runs an interactive 7-question wizard on every invocation to set per-domain push policy: push the full Tailwind palette or only your semantic colors? Push the full spacing scale or only your authored tokens? Skip opacity entirely? Route shadows through effect styles? `--dry-run` previews exactly what would be added or skipped (reflecting your wizard answers) without writing. |
 | `/adhd:pull-tokens` | `[--dry-run]` | Figma → code | Pulls Figma variables + named styles into globals.css. `--dry-run` previews without writing. |
 | `/adhd:push-component` | `<path> [--max-variants <n>] [--annotate]` | code → Figma | Pushes a React component to Figma as a structured Component Set with variant properties + variable bindings, plus a preflight lint check. `--annotate` annotates preflight violations on Figma nodes. |
 | `/adhd:push-all-components` | `[--continue-on-error] [--max-variants <n>] [--annotate]` | code → Figma | Bulk version of `push-component` — iterates over every entry in `adhd.config.ts`'s components map. Sequential, halt-on-first-failure by default. |
diff --git a/plugins/adhd/lib/design-system/__tests__/cli.test.js b/plugins/adhd/lib/design-system/__tests__/cli.test.js
index 8ef512b..819d951 100644
--- a/plugins/adhd/lib/design-system/__tests__/cli.test.js
+++ b/plugins/adhd/lib/design-system/__tests__/cli.test.js
@@ -130,32 +130,27 @@ test('preview (pull): flips the direction labels', () => {
   assert.match(result.stdout, /code-only \(left untouched per additive policy\): 1 entry/);
 });
 
-test('compare --include-tailwind: keeps Tailwind-default-origin tokens in codeOnly', () => {
-  // Verifies the seed-mode flag plumbing. With --include-tailwind, the
-  // comparator should NOT filter origin-tagged tokens.
+test('compare: surfaces Tailwind defaults in codeOnly with fromTailwindDefault marker', () => {
+  // Comparator is policy-free now — every token from the parser lands in
+  // codeOnly. Filtering (Tailwind palette vs only my semantics) happens
+  // at the action-builder layer per the user's dispositions. This test
+  // confirms the marker travels through compare so dispositions can use
+  // it.
   const css = tmp('globals.css', `@theme { --color-brand: #5e3aee; }`);
-  // Use an empty figma extract so everything that's in code becomes codeOnly.
   const figma = tmp('figma.json', { collections: [], effectStyles: [], textStyles: [] });
-  const outA = path.join(os.tmpdir(), 'diff-default-' + Date.now() + '.json');
-  const outB = path.join(os.tmpdir(), 'diff-seed-' + Date.now() + '.json');
-
-  const defaultRun = spawnSync('node', [CLI, 'compare', '--code', css, '--figma', figma, '--output', outA], { encoding: 'utf8' });
-  assert.equal(defaultRun.status, 0);
-  const diffDefault = JSON.parse(fs.readFileSync(outA, 'utf8'));
-
-  const seedRun = spawnSync('node', [CLI, 'compare', '--code', css, '--figma', figma, '--output', outB, '--include-tailwind'], { encoding: 'utf8' });
-  assert.equal(seedRun.status, 0);
-  const diffSeed = JSON.parse(fs.readFileSync(outB, 'utf8'));
-
-  // Seed mode has dramatically more codeOnly entries — the full Tailwind palette.
-  assert.ok(diffSeed.codeOnly.length > diffDefault.codeOnly.length * 5,
-    `expected seed codeOnly (${diffSeed.codeOnly.length}) >> default codeOnly (${diffDefault.codeOnly.length})`);
-  // Default mode never includes a token tagged fromTailwindDefault.
-  for (const t of diffDefault.codeOnly) {
-    assert.notEqual(t.fromTailwindDefault, true);
-  }
-  // Seed mode DOES include them.
-  assert.ok(diffSeed.codeOnly.some(t => t.fromTailwindDefault === true));
+  const out = path.join(os.tmpdir(), 'diff-' + Date.now() + '.json');
+
+  const result = spawnSync('node', [CLI, 'compare', '--code', css, '--figma', figma, '--output', out], { encoding: 'utf8' });
+  assert.equal(result.status, 0);
+  const diff = JSON.parse(fs.readFileSync(out, 'utf8'));
+  // Tailwind defaults present (hundreds of them).
+  assert.ok(diff.codeOnly.length > 100, `expected Tailwind defaults to surface, got ${diff.codeOnly.length}`);
+  // User-authored brand color also present, marker cleared.
+  const brand = diff.codeOnly.find(t => t.path === 'brand');
+  assert.ok(brand);
+  assert.equal(brand.fromTailwindDefault, false);
+  // Tailwind-default markers present on the palette tokens.
+  assert.ok(diff.codeOnly.some(t => t.fromTailwindDefault === true));
 });
 
 test('preview: buckets additions by domain when there are many entries', () => {
diff --git a/plugins/adhd/lib/design-system/__tests__/comparator.test.js b/plugins/adhd/lib/design-system/__tests__/comparator.test.js
index 1c12bfc..7f96365 100644
--- a/plugins/adhd/lib/design-system/__tests__/comparator.test.js
+++ b/plugins/adhd/lib/design-system/__tests__/comparator.test.js
@@ -264,10 +264,12 @@ test('canonicalization: distinct domains don\'t collide even when paths canonica
   assert.equal(diff.figmaOnly.length, 1);
 });
 
-test('codeOnly: includeTailwindDefaultsInCodeOnly=true keeps the full palette in codeOnly (seed mode)', () => {
-  // The seed-the-design-system mode: designers want every Tailwind
-  // utility available as a Figma variable. Comparator should NOT filter
-  // origin-tagged tokens out of codeOnly when the flag is set.
+test('codeOnly: surfaces all tokens including Tailwind defaults (filtering is the dispositions layer\'s job)', () => {
+  // Comparator is policy-free: every code-side token appears in codeOnly.
+  // Filtering ("push the Tailwind palette or only my semantics?") lives
+  // in the dispositions wizard, applied at the action-builder layer.
+  // The `fromTailwindDefault` marker travels through so dispositions can
+  // apply per-token rules.
   const code = {
     tokens: [
       { domain: 'color', path: 'zinc/500', values: { default: { type: 'literal', value: '#71717a' } }, fromTailwindDefault: true },
@@ -276,31 +278,11 @@ test('codeOnly: includeTailwindDefaultsInCodeOnly=true keeps the full palette in
     styles: { effects: [] },
   };
   const figma = { tokens: [], styles: { effects: [] } };
-  const diff = compareDesignSystems(code, figma, { includeTailwindDefaultsInCodeOnly: true });
-  // Both tokens surface in codeOnly.
-  assert.equal(diff.codeOnly.length, 2);
-  const paths = diff.codeOnly.map(t => t.path).sort();
-  assert.deepEqual(paths, ['brand', 'zinc/500']);
-});
-
-test('codeOnly: filters out Tailwind-default-origin tokens (additive policy)', () => {
-  // Pushing the full Tailwind palette into Figma is rarely intended — both
-  // sides assume the defaults implicitly. The comparator drops
-  // Tailwind-default-origin tokens from codeOnly so push doesn't create
-  // hundreds of redundant variables. User-authored tokens at the same path
-  // keep the flag cleared during parse and DO surface.
-  const code = {
-    tokens: [
-      { domain: 'color', path: 'zinc/500', values: { default: { type: 'literal', value: '#71717a' } }, fromTailwindDefault: true },
-      { domain: 'color', path: 'brand',     values: { default: { type: 'literal', value: '#5e3aee' } }, fromTailwindDefault: false },
-    ],
-    styles: { effects: [] },
-  };
-  const figma = { tokens: [], styles: { effects: [] } };
   const diff = compareDesignSystems(code, figma);
-  // Only the user-authored token surfaces in codeOnly.
-  assert.equal(diff.codeOnly.length, 1);
-  assert.equal(diff.codeOnly[0].path, 'brand');
+  assert.equal(diff.codeOnly.length, 2);
+  const byPath = Object.fromEntries(diff.codeOnly.map(t => [t.path, t]));
+  assert.equal(byPath['zinc/500'].fromTailwindDefault, true);
+  assert.equal(byPath['brand'].fromTailwindDefault, false);
 });
 
 test('Tailwind-default-origin token with a Figma value mismatch still surfaces as conflict', () => {
diff --git a/plugins/adhd/lib/design-system/__tests__/e2e-pipeline.test.js b/plugins/adhd/lib/design-system/__tests__/e2e-pipeline.test.js
index 35e4ab3..27c5d13 100644
--- a/plugins/adhd/lib/design-system/__tests__/e2e-pipeline.test.js
+++ b/plugins/adhd/lib/design-system/__tests__/e2e-pipeline.test.js
@@ -23,12 +23,12 @@ function loadFixture(name) {
   return JSON.parse(fs.readFileSync(path.join(FIXTURES, name), 'utf8'));
 }
 
-function pipeline(figmaFixtureName, { resolutions = [], direction = 'push' } = {}) {
+function pipeline(figmaFixtureName, { resolutions = [], direction = 'push', dispositions = null } = {}) {
   const css = fs.readFileSync(GLOBALS, 'utf8');
   const codeDS = parseCodeDesignSystem(css, { includeTailwindDefaults: true });
   const figmaDS = parseFigmaDesignSystem(loadFixture(figmaFixtureName));
   const diff = compareDesignSystems(codeDS, figmaDS);
-  const actions = buildFigmaActions(diff, resolutions, direction);
+  const actions = buildFigmaActions(diff, resolutions, direction, { dispositions });
   return { codeDS, figmaDS, diff, actions };
 }
 
@@ -36,15 +36,17 @@ function countKind(actions, kind) {
   return actions.filter(a => a.kind === kind).length;
 }
 
-test('e2e: clean sync — diff has no codeOnly/conflict/figmaOnly variables', () => {
+test('e2e: clean sync — diff has zero conflict/figmaOnly variables', () => {
+  // With the comparator surfacing all code-side tokens (including Tailwind
+  // defaults), codeOnly is no longer a tight "diff of what's missing" — it
+  // becomes "everything in code minus what Figma already has." When both
+  // sides hold the full palette the diff still has no conflict/figmaOnly,
+  // but codeOnly may contain shadow-domain tokens (shadows live on the
+  // effect-style channel, never the variable channel). The action layer
+  // is where filtering happens — see the empty-figma test below.
   const { diff } = pipeline('figma-full-tailwind.json');
   assert.equal(diff.conflict.length, 0, 'expected zero conflicts');
   assert.equal(diff.figmaOnly.length, 0, 'expected zero figmaOnly');
-  // Shadows are emitted as effect styles, not variables, so they always look
-  // "codeOnly" on the variable side. Confirm every codeOnly is a shadow.
-  for (const t of diff.codeOnly) {
-    assert.equal(t.domain, 'shadow', `unexpected non-shadow codeOnly: ${t.domain}:${t.path}`);
-  }
   assert.equal(diff.styles.effects.same.length > 0, true, 'expected effect styles to match');
   assert.equal(diff.styles.effects.codeOnly.length, 0, 'effect-style codeOnly should be empty');
 });
@@ -57,35 +59,44 @@ test('e2e: push against synced figma produces zero create-variable actions', ()
   assert.equal(countKind(actions, 'create-effect-style'), 0);
 });
 
-test('e2e: empty figma — push produces create-variable actions ONLY for user-authored tokens', () => {
-  // After the Tailwind-defaults floor fix: codeOnly no longer surfaces
-  // tokens that came from `tailwind-defaults.css` or the synthetic utility
-  // scale. The user's example/globals.css authors ~18 tokens of its own
-  // (custom colors, the chart palette, --radius and friends, sidebar
-  // semantics, font families); those are what push should create. Earlier
-  // behavior — flooding 400+ create-variable actions into Figma to bake
-  // in the full Tailwind palette — was a comparator bug, not a feature.
-  const { diff, actions } = pipeline('figma-empty.json', { direction: 'push' });
+test('e2e: empty figma — dispositions filter the push (semantic-only color + authored-only spacing)', () => {
+  // The interesting case: comparator surfaces every code-side token
+  // (palette + authored) but the dispositions wizard's "semantic-only"
+  // and "authored-only" picks filter Tailwind defaults out at the
+  // action-builder layer. This test exercises the same workflow the user
+  // performs by clicking through the wizard.
+  const { diff, actions } = pipeline('figma-empty.json', {
+    direction: 'push',
+    dispositions: {
+      color: 'semantic-only',
+      typography: 'all',
+      spacing: 'authored-only',
+      radiusAndBorder: 'push',
+      shadow: 'effect-styles',
+      opacity: 'skip',
+      utilityDomains: 'skip',
+    },
+  });
   assert.equal(diff.same.length, 0);
   assert.equal(diff.conflict.length, 0);
   assert.equal(diff.figmaOnly.length, 0);
-  assert.ok(diff.codeOnly.length > 0 && diff.codeOnly.length < 100,
-    `expected a focused set of user-authored codeOnly tokens, got ${diff.codeOnly.length}`);
-  // Every codeOnly entry must be user-authored — no Tailwind-default
-  // tokens leak through the filter.
-  for (const t of diff.codeOnly) {
-    assert.notEqual(t.fromTailwindDefault, true,
-      `Tailwind-default token leaked into codeOnly: ${t.domain}:${t.path}`);
+  // Comparator surfaces hundreds of tokens (the full Tailwind palette + authored).
+  assert.ok(diff.codeOnly.length > 100, `expected full palette to surface, got ${diff.codeOnly.length}`);
+  // Action layer applies dispositions: Tailwind palette colors filtered
+  // out, Tailwind spacing scale filtered out, opacity + utilities skipped.
+  // What remains: authored color tokens, full typography (sizes + weights
+  // + leading + tracking — all from Tailwind), authored spacing, radii,
+  // border widths, shadow as effect-styles.
+  const createCount = countKind(actions, 'create-variable');
+  const skipCount = countKind(actions, 'skip-by-disposition');
+  const effectCount = countKind(actions, 'create-effect-style');
+  assert.ok(createCount > 0, `expected some pushes, got ${createCount}`);
+  assert.ok(skipCount > 100, `expected many skip-by-disposition (Tailwind palette + opacity + utilities), got ${skipCount}`);
+  assert.ok(effectCount > 0, `expected shadow effect-styles, got ${effectCount}`);
+  // Every skip carries a disposition-derived reason.
+  for (const a of actions.filter(a => a.kind === 'skip-by-disposition')) {
+    assert.ok(a.reason && a.reason.length > 0, `skip action missing reason: ${JSON.stringify(a)}`);
   }
-  const nonShadowCodeOnly = diff.codeOnly.filter(t => t.domain !== 'shadow').length;
-  assert.equal(countKind(actions, 'create-variable'), nonShadowCodeOnly,
-    'create-variable count should equal non-shadow codeOnly count');
-  // example/globals.css doesn't author its own shadow tokens — it inherits
-  // them from Tailwind, which the floor filter excludes from codeOnly. A
-  // project that DID author custom shadows would see create-effect-style
-  // actions; users who want the full Tailwind shadow palette in Figma can
-  // re-declare them explicitly in `@theme {}`.
-  assert.equal(countKind(actions, 'create-effect-style'), 0);
 });
 
 test('e2e: empty figma — pull is a no-op (nothing in figma to pull)', () => {
diff --git a/plugins/adhd/lib/design-system/cli.js b/plugins/adhd/lib/design-system/cli.js
index c83cd35..77a8ada 100644
--- a/plugins/adhd/lib/design-system/cli.js
+++ b/plugins/adhd/lib/design-system/cli.js
@@ -26,9 +26,9 @@ function parseArgs(argv) {
 
 function printUsage() {
   console.log(`Usage:
-  cli.js compare           --code <globals.css> --figma <figma.json> --output <diff.json> [--include-tailwind]
-  cli.js apply             --diff <diff.json> --resolutions <resolutions.json> --direction <push|pull> --output <actions.json>
-  cli.js preview           --diff <diff.json> --direction <push|pull>
+  cli.js compare           --code <globals.css> --figma <figma.json> --output <diff.json>
+  cli.js apply             --diff <diff.json> --resolutions <resolutions.json> --direction <push|pull> --output <actions.json> [--dispositions <path>]
+  cli.js preview           --diff <diff.json> --direction <push|pull> [--actions <actions.json>]
   cli.js assemble-extract  --chunks-dir <dir> --output <figma.json>
 
 compare:
@@ -225,19 +225,15 @@ function main() {
   if (cmd === 'compare') {
     const css = fs.readFileSync(args.code, 'utf8');
     const figmaExtract = JSON.parse(fs.readFileSync(args.figma, 'utf8'));
-    // Parser always learns about Tailwind v4's default theme so we know
-    // which tokens are user-authored vs default (the `fromTailwindDefault`
-    // marker). The COMPARATOR then decides what to include in `codeOnly`:
-    //   - Default: filter out defaults — keep day-to-day pushes focused
-    //   - --include-tailwind: surface the full Tailwind palette in
-    //     codeOnly, for seeding a fresh Figma file with every utility as
-    //     a variable. The seed case is once-per-project; the focused
-    //     diff is once-per-change.
+    // Parser always learns about Tailwind v4's default theme so the
+    // `fromTailwindDefault` marker travels with each token — the
+    // disposition wizard in /adhd:push-tokens uses it to decide which
+    // tokens push (color: semantic-only excludes Tailwind palette, etc.).
+    // Disable via --no-tailwind-defaults for explicit-overrides-only mode.
     const includeTailwindDefaults = !('no-tailwind-defaults' in args);
-    const includeTailwindDefaultsInCodeOnly = 'include-tailwind' in args;
     const codeDS = parseCodeDesignSystem(css, { includeTailwindDefaults });
     const figmaDS = parseFigmaDesignSystem(figmaExtract);
-    const diff = compareDesignSystems(codeDS, figmaDS, { includeTailwindDefaultsInCodeOnly });
+    const diff = compareDesignSystems(codeDS, figmaDS);
     fs.writeFileSync(args.output, JSON.stringify(diff, null, 2));
     process.exit(0);
   }
diff --git a/plugins/adhd/lib/design-system/comparator.js b/plugins/adhd/lib/design-system/comparator.js
index 746fdd1..6959385 100644
--- a/plugins/adhd/lib/design-system/comparator.js
+++ b/plugins/adhd/lib/design-system/comparator.js
@@ -84,14 +84,12 @@ function tokenKey(t) {
   return t.domain + ':' + t.path;
 }
 
-function compareDesignSystems(code, figma, opts = {}) {
-  // `opts.includeTailwindDefaultsInCodeOnly` (boolean, default false).
-  // When false, the comparator drops Tailwind-default-origin tokens from
-  // `codeOnly` so day-to-day pushes don't try to bake the entire Tailwind
-  // palette into Figma. When true, the full palette surfaces in codeOnly
-  // — the right mode when seeding a fresh Figma file so designers have
-  // every Tailwind utility available as a variable.
-  const includeTailwindInCodeOnly = opts.includeTailwindDefaultsInCodeOnly === true;
+function compareDesignSystems(code, figma) {
+  // `codeOnly` always surfaces every token from the code side, including
+  // Tailwind defaults. Filtering by intent (push the palette vs only my
+  // semantics) lives one layer up in the dispositions wizard — that's
+  // where designer policy belongs. The `fromTailwindDefault` marker
+  // travels through so the action builder can apply per-domain rules.
   const same = [];
   const conflict = [];
   const codeOnly = [];
@@ -185,16 +183,11 @@ function compareDesignSystems(code, figma, opts = {}) {
   }
   const survivedFigmaOnly = figmaOnly.filter(t => !matchedFigma.has(t));
 
-  // Filter Tailwind-default-origin tokens out of codeOnly UNLESS the
-  // caller explicitly asked to include them. Defaulting to filtered keeps
-  // day-to-day pushes focused on authored changes (no 400-entry palette
-  // flood). The `--include-tailwind` push mode flips this for the
-  // one-time seeding case where designers want every Tailwind utility as
-  // a Figma variable. Tokens that surface in `same` or `conflict` are
-  // unaffected — those reflect real state on the Figma side already.
-  const filteredCodeOnly = includeTailwindInCodeOnly
-    ? survivedCodeOnly
-    : survivedCodeOnly.filter(t => t.fromTailwindDefault !== true);
+  // codeOnly carries everything — the dispositions wizard filters at the
+  // action-builder layer. The `fromTailwindDefault` marker is preserved
+  // on each token so domain-aware dispositions (color: semantic-only,
+  // spacing: authored-only) can apply the right per-token rule.
+  const filteredCodeOnly = survivedCodeOnly;
 
   // ── Effect styles ──────────────────────────────────────────────────────
   // Diff by name only. Each side may not have styles at all (older callers).
diff --git a/plugins/adhd/skills/push-tokens/SKILL.md b/plugins/adhd/skills/push-tokens/SKILL.md
index 0c7497e..53587f9 100644
--- a/plugins/adhd/skills/push-tokens/SKILL.md
+++ b/plugins/adhd/skills/push-tokens/SKILL.md
@@ -1,7 +1,7 @@
 ---
-description: "Push the local design tokens (globals.css variables + named styles) into the configured Figma file. Two-way diff with per-attribute conflict prompts; additive (never deletes from Figma). Reads adhd.config.ts at the repo root. Pass --dry-run to preview without writing. Pass --include-tailwind to seed Figma with the entire Tailwind v4 palette so designers have every utility available as a variable."
+description: "Push the local design tokens (globals.css variables + named styles) into the configured Figma file. Two-way diff with per-attribute conflict prompts; additive (never deletes from Figma). Runs an interactive 7-question disposition wizard on every invocation to control per-domain push policy (push the full Tailwind palette vs semantic-only, skip opacity, route shadows through effect styles, etc.). Reads adhd.config.ts at the repo root. Pass --dry-run to preview without writing."
 disable-model-invocation: true
-argument-hint: "[--dry-run] [--include-tailwind]"
+argument-hint: "[--dry-run]"
 allowed-tools: Read Write Edit Bash AskUserQuestion mcp__plugin_figma_figma__use_figma
 ---
 
@@ -9,9 +9,9 @@ allowed-tools: Read Write Edit Bash AskUserQuestion mcp__plugin_figma_figma__use
 
 Pushes the codebase's design tokens (variables + named styles) into the configured Figma file. Compares both sides; for each conflicting variable, prompts the user; for variables that exist only in code, creates them in Figma; for variables that exist only in Figma, leaves them alone (additive policy).
 
-Pass `--dry-run` to see exactly what would be added or overwritten without making any changes — no prompts, no writes, no MCP traffic beyond the initial extract.
+Every invocation walks through a 7-question wizard (Phase 1.5) that controls per-domain push policy. Answer "all" for color/spacing to push the full Tailwind palette + your authored tokens; answer "semantic-only" / "authored-only" to push only your authored tokens. The wizard is the only knob — there's no global "push everything" flag because designers want conscious per-domain decisions.
 
-Pass `--include-tailwind` to also push every Tailwind v4 default (the full color palette, the spacing scale, radii, breakpoints, etc.). Useful as a one-time **seed** when setting up a fresh Figma file so designers can pick from the same token space the code can render. Without this flag, daily pushes stay focused on user-authored tokens only — the Tailwind defaults are implicit on both sides and the additive policy keeps Figma clean.
+Pass `--dry-run` to see exactly what would be added or overwritten without making any changes — no prompts, no writes, no MCP traffic beyond the initial extract.
 
 **Authoritative spec:** `docs/superpowers/specs/2026-05-10-adhd-push-pull-design-system.md`
 
@@ -98,16 +98,15 @@ If Strategy A's response shows visible truncation (look for an unterminated JSON
 
 ## Phase 3: Run the comparator
 
-Use `Bash`. If the user passed `--include-tailwind`, add `--include-tailwind` to the compare invocation so the diff surfaces every Tailwind default that's missing from Figma. Otherwise omit it — the comparator filters Tailwind-default-origin tokens out of `codeOnly` so the diff stays focused on user-authored changes.
-
 ```bash
 node plugins/adhd/lib/design-system/cli.js compare \
   --code /tmp/adhd-push/globals.css \
   --figma /tmp/adhd-push/figma.json \
-  --output /tmp/adhd-push/diff.json \
-  [--include-tailwind]
+  --output /tmp/adhd-push/diff.json
 ```
 
+The comparator always surfaces every code-side token in `codeOnly` (including Tailwind defaults). Filtering happens at the action-builder layer based on the wizard's dispositions — that's where designer intent lives.
+
 Read `/tmp/adhd-push/diff.json`. The diff has four arrays: `same`, `conflict`, `codeOnly`, `figmaOnly`.
 
 If `conflict.length === 0` and `codeOnly.length === 0`, print "Figma is already in sync with code. No changes." and exit 0.

From f229fa43e01702647eeb16fa33cc20677ffb35a2 Mon Sep 17 00:00:00 2001
From: Hugh Francis <hughfrancis89@gmail.com>
Date: Tue, 12 May 2026 15:51:06 -0400
Subject: [PATCH 61/79] push-tokens: text/*/line-height paths push as
 FLOAT+LINE_HEIGHT (not STRING+FONT_SIZE)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Tailwind v4 ships paired line-height companions for every text size
(--text-xs--line-height: calc(1 / 0.75), etc. — eight of them in the
default theme). Two bugs combined to make these the only push failures
on a real Tailwind v4 project:

1. dimensionToPx rejected calc() expressions outright, so the action
   builder typed the line-height tokens as STRING (raw "calc(1 / 0.75)")
   instead of evaluating to a FLOAT ratio.

2. The figma-write script's tokenScopesFor narrowed `text/*` paths to
   the FONT_SIZE scope without checking for the companion `/line-height`
   suffix — so even if the type had been right, the scope would have
   been wrong.

Fix #1 extends dimensionToPx to evaluate a narrow window of calc shapes:
calc(<num> <op> <num>) where each operand re-enters the evaluator (so
rem→px conversion still applies). Covers the ratio case (`calc(1 / 0.75)`
→ 1.333) and the multiplier case (`calc(1rem * 2)` → 32). Anything more
elaborate (var refs, nested calls) still falls through to STRING.

Fix #2 adds a `text/*/line-height` branch BEFORE the broader text/
branch in tokenScopesFor. Exposes the function as a JS-side module
export (mirroring the inline copy in WRITE_SCRIPT) with a drift-guard
test ensuring the two stay in sync.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 .../__tests__/figma-write-actions.test.js     | 58 +++++++++++++++++++
 .../__tests__/figma-write-script.test.js      | 46 +++++++++++++++
 .../lib/design-system/figma-write-actions.js  | 37 +++++++++---
 .../lib/design-system/figma-write-script.js   | 44 +++++++++++++-
 4 files changed, 175 insertions(+), 10 deletions(-)
 create mode 100644 plugins/adhd/lib/design-system/__tests__/figma-write-script.test.js

diff --git a/plugins/adhd/lib/design-system/__tests__/figma-write-actions.test.js b/plugins/adhd/lib/design-system/__tests__/figma-write-actions.test.js
index c5b01dd..ec3bf9a 100644
--- a/plugins/adhd/lib/design-system/__tests__/figma-write-actions.test.js
+++ b/plugins/adhd/lib/design-system/__tests__/figma-write-actions.test.js
@@ -100,6 +100,64 @@ test('font-family typography tokens are skipped (text-styles channel, not variab
   assert.match(actions[0].reason, /font-family/);
 });
 
+test('text/<size>/line-height with calc(num / num) value → FLOAT create-variable (was STRING + FONT_SIZE → rejected)', () => {
+  // Tailwind v4 ships every text-size with a paired line-height that's
+  // defined as a calc ratio: `--text-xs--line-height: calc(1 / 0.75)`.
+  // Pre-fix: dimensionToPx rejected calc(), so the action got typed as
+  // STRING; the write script then narrowed text/* to FONT_SIZE; Figma
+  // refused with "Invalid scope for this variable type." The two fixes
+  // landing together make these tokens push as FLOAT with LINE_HEIGHT
+  // scope (the scope half is enforced inside WRITE_SCRIPT — covered in
+  // figma-write-script.test.js).
+  const diff = {
+    same: [], conflict: [], figmaOnly: [],
+    codeOnly: [{
+      domain: 'typography',
+      path: 'text/xs/line-height',
+      values: { default: { type: 'literal', value: 'calc(1 / 0.75)' } },
+    }],
+  };
+  const actions = buildFigmaActions(diff, [], 'push', { dispositions: { typography: 'all' } });
+  assert.equal(actions.length, 1);
+  assert.equal(actions[0].kind, 'create-variable');
+  assert.equal(actions[0].type, 'FLOAT');
+  // 1 / 0.75 ≈ 1.333…
+  assert.ok(Math.abs(actions[0].resolvedByMode.default - (1 / 0.75)) < 1e-9);
+});
+
+test('dimensionToPx via action builder: calc(1rem * 2) resolves to 32 (rem→px through both operands)', () => {
+  // Another shape Tailwind uses internally — e.g. `calc(var(--spacing) * 4)`
+  // surface analogues. With var() stripped (the @theme-inline resolver
+  // handles those), the remaining calc(num<unit> * num) should evaluate.
+  const diff = {
+    same: [], conflict: [], figmaOnly: [],
+    codeOnly: [{
+      domain: 'spacing', path: 'double',
+      values: { default: { type: 'literal', value: 'calc(1rem * 2)' } },
+    }],
+  };
+  const actions = buildFigmaActions(diff, [], 'push', { dispositions: { spacing: 'all' } });
+  assert.equal(actions[0].type, 'FLOAT');
+  assert.equal(actions[0].resolvedByMode.default, 32);
+});
+
+test('dimensionToPx via action builder: unresolvable calc (var ref or nested) falls through to STRING', () => {
+  // calc(var(--gap) * 2) can't be evaluated at this layer — var() refs
+  // are resolved earlier in code-parser's @theme-inline pass. Whatever
+  // leaks through here stays STRING (and the scope-narrowing branch
+  // catches whether that's a valid combination per-domain).
+  const diff = {
+    same: [], conflict: [], figmaOnly: [],
+    codeOnly: [{
+      domain: 'spacing', path: 'tricky',
+      values: { default: { type: 'literal', value: 'calc(var(--gap) * 2)' } },
+    }],
+  };
+  const actions = buildFigmaActions(diff, [], 'push', { dispositions: { spacing: 'all' } });
+  // FLOAT_DOMAINS includes spacing, but the value isn't resolvable → STRING.
+  assert.equal(actions[0].type, 'STRING');
+});
+
 test('font-weight typography tokens still push as variables (only font families skip)', () => {
   // `--font-weight-bold` lives under the typography domain but it's a
   // scalar value designers consume as a Tailwind utility — variables are
diff --git a/plugins/adhd/lib/design-system/__tests__/figma-write-script.test.js b/plugins/adhd/lib/design-system/__tests__/figma-write-script.test.js
new file mode 100644
index 0000000..5a8048d
--- /dev/null
+++ b/plugins/adhd/lib/design-system/__tests__/figma-write-script.test.js
@@ -0,0 +1,46 @@
+'use strict';
+
+const test = require('node:test');
+const assert = require('node:assert/strict');
+const { WRITE_SCRIPT, tokenScopesFor } = require('../figma-write-script');
+
+test('tokenScopesFor: text/<size> → FONT_SIZE', () => {
+  assert.deepEqual(tokenScopesFor('typography', 'text/xs'), ['FONT_SIZE']);
+  assert.deepEqual(tokenScopesFor('typography', 'text/base'), ['FONT_SIZE']);
+});
+
+test('tokenScopesFor: text/<size>/line-height → LINE_HEIGHT (regression — companion line-heights must not get FONT_SIZE scope)', () => {
+  // The bug: Tailwind v4 ships paired line-height values with every text
+  // size (--text-xs--line-height: calc(1 / 0.75), etc.). Earlier the
+  // startsWith('text/') branch matched first and assigned FONT_SIZE,
+  // and Figma rejected the push with "Invalid scope for this variable
+  // type" on every text-size's paired line-height.
+  assert.deepEqual(tokenScopesFor('typography', 'text/xs/line-height'), ['LINE_HEIGHT']);
+  assert.deepEqual(tokenScopesFor('typography', 'text/base/line-height'), ['LINE_HEIGHT']);
+  assert.deepEqual(tokenScopesFor('typography', 'text/4xl/line-height'), ['LINE_HEIGHT']);
+});
+
+test('tokenScopesFor: leading/, tracking/, font/, font-weight/ keep their dedicated scopes', () => {
+  assert.deepEqual(tokenScopesFor('typography', 'leading/relaxed'), ['LINE_HEIGHT']);
+  assert.deepEqual(tokenScopesFor('typography', 'tracking/tight'), ['LETTER_SPACING']);
+  assert.deepEqual(tokenScopesFor('typography', 'font/sans'), ['FONT_FAMILY']);
+  assert.deepEqual(tokenScopesFor('typography', 'font-weight/bold'), ['FONT_WEIGHT']);
+});
+
+test('tokenScopesFor: non-typography domains pull from the domain table', () => {
+  assert.deepEqual(tokenScopesFor('color', 'gold/100'), ['FRAME_FILL', 'SHAPE_FILL', 'TEXT_FILL', 'STROKE_COLOR']);
+  assert.deepEqual(tokenScopesFor('radius', 'sm'), ['CORNER_RADIUS']);
+  assert.deepEqual(tokenScopesFor('opacity', '50'), ['OPACITY']);
+});
+
+test('WRITE_SCRIPT inlines the same line-height pattern (drift guard)', () => {
+  // The script template can't `require`, so it carries its own copy of
+  // tokenScopesFor. The exported JS-side function above is its mirror.
+  // This guard catches drift: if someone edits the inline version without
+  // touching the JS-side mirror (or vice versa), the line-height case
+  // could silently regress.
+  assert.match(WRITE_SCRIPT,
+    /path\.startsWith\(['"`]text\/['"`]\)\s*&&\s*path\.endsWith\(['"`]\/line-height['"`]\)/,
+    'WRITE_SCRIPT should include the text/*/line-height branch BEFORE the broader text/ check',
+  );
+});
diff --git a/plugins/adhd/lib/design-system/figma-write-actions.js b/plugins/adhd/lib/design-system/figma-write-actions.js
index 61e2fa2..bd136fc 100644
--- a/plugins/adhd/lib/design-system/figma-write-actions.js
+++ b/plugins/adhd/lib/design-system/figma-write-actions.js
@@ -52,14 +52,35 @@ const STRING_DOMAINS = new Set(['aspect', 'ease', 'animate']);
 function dimensionToPx(raw) {
   if (raw == null) return null;
   const s = String(raw).trim();
-  // Reject expressions: calc(...), var(...), comma-separated lists, etc.
-  if (/[(),]/.test(s)) return null;
-  const m = /^(-?\d*\.?\d+)(px|rem|em)?$/.exec(s);
-  if (!m) return null;
-  const n = parseFloat(m[1]);
-  const unit = m[2] || '';
-  if (unit === 'rem' || unit === 'em') return n * 16;
-  return n; // px or unitless
+  // Simple length / unitless number.
+  const simple = /^(-?\d*\.?\d+)(px|rem|em)?$/.exec(s);
+  if (simple) {
+    const n = parseFloat(simple[1]);
+    const unit = simple[2] || '';
+    if (unit === 'rem' || unit === 'em') return n * 16;
+    return n;
+  }
+  // Two-operand calc() — common for Tailwind v4's text-size line-height
+  // companions like `calc(1 / 0.75)` (ratio) and `calc(1rem * 2)` (px).
+  // Each operand re-enters dimensionToPx so we get rem→px conversion for
+  // free. We don't support nested calls or more than two operands — a
+  // narrow window that covers Tailwind's shipped patterns without
+  // turning into a full CSS expression evaluator.
+  const calc = /^calc\(\s*([^()]+?)\s+([+\-*/])\s+([^()]+?)\s*\)$/.exec(s);
+  if (calc) {
+    const a = dimensionToPx(calc[1]);
+    const b = dimensionToPx(calc[3]);
+    if (a == null || b == null) return null;
+    switch (calc[2]) {
+      case '+': return a + b;
+      case '-': return a - b;
+      case '*': return a * b;
+      case '/': return b === 0 ? null : a / b;
+    }
+  }
+  // var(...) or any other expression we can't evaluate — let the caller
+  // fall through to STRING typing.
+  return null;
 }
 
 // Decide the Figma variable type for a (domain, value) pair. Returns one of
diff --git a/plugins/adhd/lib/design-system/figma-write-script.js b/plugins/adhd/lib/design-system/figma-write-script.js
index 795f53c..3c465c4 100644
--- a/plugins/adhd/lib/design-system/figma-write-script.js
+++ b/plugins/adhd/lib/design-system/figma-write-script.js
@@ -1,5 +1,39 @@
 'use strict';
 
+// Exported mirror of the inline `tokenScopesFor` inside WRITE_SCRIPT.
+// The Figma plugin sandbox can't `require`, so the script needs an
+// inline copy. We keep this JS-side function as the testable mirror —
+// the WRITE_SCRIPT template is grep-asserted to contain the same key
+// patterns so the two can't silently drift.
+function tokenScopesFor(domain, path) {
+  if (domain !== 'typography') {
+    const NON_TYPO_SCOPES = {
+      color: ['FRAME_FILL', 'SHAPE_FILL', 'TEXT_FILL', 'STROKE_COLOR'],
+      spacing: ['GAP', 'WIDTH_HEIGHT'],
+      radius: ['CORNER_RADIUS'],
+      shadow: ['EFFECT_FLOAT'],
+      opacity: ['OPACITY'],
+      'border-width': ['STROKE_FLOAT'],
+      'z-index': ['ALL_SCOPES'],
+      breakpoint: ['ALL_SCOPES'],
+      container: ['WIDTH_HEIGHT'],
+      blur: ['EFFECT_FLOAT'],
+      perspective: ['ALL_SCOPES'],
+      aspect: ['ALL_SCOPES'],
+      ease: ['ALL_SCOPES'],
+      animate: ['ALL_SCOPES'],
+    };
+    return NON_TYPO_SCOPES[domain] || ['ALL_SCOPES'];
+  }
+  if (path.startsWith('text/') && path.endsWith('/line-height')) return ['LINE_HEIGHT'];
+  if (path.startsWith('text/')) return ['FONT_SIZE'];
+  if (path.startsWith('font-weight/')) return ['FONT_WEIGHT'];
+  if (path.startsWith('font/')) return ['FONT_FAMILY'];
+  if (path.startsWith('leading/')) return ['LINE_HEIGHT'];
+  if (path.startsWith('tracking/')) return ['LETTER_SPACING'];
+  return ['ALL_SCOPES'];
+}
+
 /**
  * JS string injected into use_figma. Reads `__ACTIONS__` (a JSON array
  * of { kind, ... }) and applies each one to the Figma file. Returns
@@ -39,9 +73,15 @@ const SCOPES = {
 };
 
 // Narrow typography scopes from the Figma path (e.g. 'text/xs' → FONT_SIZE,
-// 'font/sans' → FONT_FAMILY). Keep ALL_SCOPES as fallback.
+// 'font/sans' → FONT_FAMILY). Keep ALL_SCOPES as fallback. The
+// 'text/<size>/line-height' companion paths (Tailwind v4 ships paired
+// line-height values with every text size) must check BEFORE the
+// 'text/' branch — otherwise the LINE_HEIGHT companions get the
+// FONT_SIZE scope and Figma rejects them with "Invalid scope for this
+// variable type."
 function tokenScopesFor(domain, path) {
   if (domain !== 'typography') return SCOPES[domain] || ['ALL_SCOPES'];
+  if (path.startsWith('text/') && path.endsWith('/line-height')) return ['LINE_HEIGHT'];
   if (path.startsWith('text/')) return ['FONT_SIZE'];
   if (path.startsWith('font-weight/')) return ['FONT_WEIGHT'];
   if (path.startsWith('font/')) return ['FONT_FAMILY'];
@@ -251,4 +291,4 @@ for (const a of actions) {
 return { applied, skipped, errors };
 `;
 
-module.exports = { WRITE_SCRIPT };
+module.exports = { WRITE_SCRIPT, tokenScopesFor };

From 0ab6cbca2b882465efd9772d1be9c05f7b638db3 Mon Sep 17 00:00:00 2001
From: Hugh Francis <hughfrancis89@gmail.com>
Date: Tue, 12 May 2026 15:55:56 -0400
Subject: [PATCH 62/79] push-tokens: alias-aware collection lookup (stop
 duplicating Color / color)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Designer's Figma file had collections named "Color", "Radius", "Borders",
"Space", "Type + Effects" — push was looking up the canonical names
("color", "radius", "border-width", "spacing", "typography")
case-sensitively against existing collection names, missing the
designer's collections every time and creating fresh ones alongside.
Designer ended up with both "Color" (their 25 vars) and "color" (ours)
in the variables panel — silly noise.

ensureCollection now consults an alias table before creating: case-
insensitive match against any known alias for the canonical domain
("Color"/"colors"/"colour" all → color; "Type + Effects"/"text styles"
→ typography; "Borders"/"strokes" → border-width). When a match is
found, push appends into the designer's existing collection — they
keep their naming preference, we stop polluting.

JS-side `findCollectionAlias` mirrors the inline copy in WRITE_SCRIPT;
drift-guard tests assert every action-builder domain has an alias list
and every alias string appears in the inlined script.

Pre-existing duplicates from prior pushes are left alone — designers
can consolidate manually, or we can add a /adhd:lint --fix-style rule
for that as a follow-up.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 .../__tests__/figma-write-script.test.js      | 53 ++++++++++-
 .../lib/design-system/figma-write-actions.js  |  1 +
 .../lib/design-system/figma-write-script.js   | 87 ++++++++++++++++++-
 3 files changed, 138 insertions(+), 3 deletions(-)

diff --git a/plugins/adhd/lib/design-system/__tests__/figma-write-script.test.js b/plugins/adhd/lib/design-system/__tests__/figma-write-script.test.js
index 5a8048d..b202299 100644
--- a/plugins/adhd/lib/design-system/__tests__/figma-write-script.test.js
+++ b/plugins/adhd/lib/design-system/__tests__/figma-write-script.test.js
@@ -2,7 +2,7 @@
 
 const test = require('node:test');
 const assert = require('node:assert/strict');
-const { WRITE_SCRIPT, tokenScopesFor } = require('../figma-write-script');
+const { WRITE_SCRIPT, tokenScopesFor, findCollectionAlias, COLLECTION_ALIASES } = require('../figma-write-script');
 
 test('tokenScopesFor: text/<size> → FONT_SIZE', () => {
   assert.deepEqual(tokenScopesFor('typography', 'text/xs'), ['FONT_SIZE']);
@@ -33,6 +33,57 @@ test('tokenScopesFor: non-typography domains pull from the domain table', () =>
   assert.deepEqual(tokenScopesFor('opacity', '50'), ['OPACITY']);
 });
 
+test('findCollectionAlias: matches case-insensitively to the canonical (Color → color)', () => {
+  // The user's "duped collections" bug. Designer's Figma file had a
+  // "Color" collection (capital C) but push was looking up "color"
+  // case-sensitively, missed it, and created a parallel "color"
+  // collection alongside. Same for "Radius" / "radius".
+  assert.equal(findCollectionAlias('color', ['Color', 'Other']), 'Color');
+  assert.equal(findCollectionAlias('radius', ['Other', 'Radius']), 'Radius');
+});
+
+test('findCollectionAlias: matches synonyms (Space → spacing, Borders → border-width, Type + Effects → typography)', () => {
+  // Real collection names from the user's screenshot. Each maps to a
+  // different canonical without case alone — these are semantic synonyms.
+  assert.equal(findCollectionAlias('spacing', ['Space']), 'Space');
+  assert.equal(findCollectionAlias('border-width', ['Borders']), 'Borders');
+  assert.equal(findCollectionAlias('typography', ['Type + Effects']), 'Type + Effects');
+  assert.equal(findCollectionAlias('shadow', ['Effects']), 'Effects');
+});
+
+test('findCollectionAlias: returns null when nothing matches (caller creates new collection)', () => {
+  assert.equal(findCollectionAlias('color', ['Spacing', 'Radii']), null);
+  assert.equal(findCollectionAlias('color', []), null);
+});
+
+test('findCollectionAlias: unknown canonical returns null (safe default)', () => {
+  assert.equal(findCollectionAlias('not-a-domain', ['Color', 'Radius']), null);
+});
+
+test('COLLECTION_ALIASES covers every domain the action builder might emit', () => {
+  // If a new domain gets added to figma-write-actions's DOMAIN_COLLECTION
+  // but not here, the alias lookup silently returns null for it and
+  // push starts creating differently-cased duplicate collections.
+  const { DOMAIN_COLLECTION } = require('../figma-write-actions');
+  for (const canonical of Object.values(DOMAIN_COLLECTION)) {
+    assert.ok(COLLECTION_ALIASES[canonical],
+      `missing alias list for canonical "${canonical}" — push will create a fresh collection instead of reusing existing case-variants`);
+  }
+});
+
+test('WRITE_SCRIPT inlines the same alias logic (drift guard)', () => {
+  // The script template carries its own copy of COLLECTION_ALIASES.
+  // This guard catches drift: if the JS-side table evolves without the
+  // inline copy keeping up, real pushes go back to creating parallel
+  // case-variant collections.
+  for (const aliases of Object.values(COLLECTION_ALIASES)) {
+    for (const a of aliases) {
+      assert.ok(WRITE_SCRIPT.includes(`'${a}'`),
+        `alias "${a}" missing from inlined COLLECTION_ALIASES in WRITE_SCRIPT`);
+    }
+  }
+});
+
 test('WRITE_SCRIPT inlines the same line-height pattern (drift guard)', () => {
   // The script template can't `require`, so it carries its own copy of
   // tokenScopesFor. The exported JS-side function above is its mirror.
diff --git a/plugins/adhd/lib/design-system/figma-write-actions.js b/plugins/adhd/lib/design-system/figma-write-actions.js
index bd136fc..f7dc5e4 100644
--- a/plugins/adhd/lib/design-system/figma-write-actions.js
+++ b/plugins/adhd/lib/design-system/figma-write-actions.js
@@ -353,4 +353,5 @@ module.exports = {
   figmaTypeForToken,
   dimensionToPx,
   resolveFigmaValue,
+  DOMAIN_COLLECTION,
 };
diff --git a/plugins/adhd/lib/design-system/figma-write-script.js b/plugins/adhd/lib/design-system/figma-write-script.js
index 3c465c4..139aee6 100644
--- a/plugins/adhd/lib/design-system/figma-write-script.js
+++ b/plugins/adhd/lib/design-system/figma-write-script.js
@@ -1,5 +1,49 @@
 'use strict';
 
+// Collection-name aliases. Figma users name their collections however
+// they like — "Color", "Colors", "Colour", "Type + Effects", "Borders",
+// "Space" — but our canonical names are the lowercase Tailwind domain
+// keys ("color", "typography", "border-width", "spacing"). Without
+// alias-aware lookup, pushing into a file where the designer has
+// "Color" (capital C) creates a parallel "color" collection — Figma
+// treats names case-sensitively. The aliases below mirror common
+// real-world variations + Tailwind's own multi-word names.
+//
+// Match is case-insensitive on lowercase+trimmed Figma names. First
+// canonical that finds an existing collection wins; subsequent pushes
+// targeting the same canonical reuse that collection.
+const COLLECTION_ALIASES = {
+  color:          ['color', 'colors', 'colour', 'colours'],
+  spacing:        ['spacing', 'space', 'spaces'],
+  radius:         ['radius', 'radii', 'rounded', 'corner radius'],
+  shadow:         ['shadow', 'shadows', 'effects'],
+  opacity:        ['opacity', 'alpha'],
+  'border-width': ['border-width', 'border width', 'borders', 'border', 'strokes', 'stroke'],
+  typography:     ['typography', 'type', 'text', 'text styles', 'type + effects', 'text + effects', 'fonts'],
+  'z-index':      ['z-index', 'z'],
+  breakpoint:     ['breakpoint', 'breakpoints', 'screens', 'media'],
+  container:      ['container', 'containers'],
+  blur:           ['blur'],
+  perspective:    ['perspective'],
+  aspect:         ['aspect', 'aspects', 'aspect ratio', 'ratios'],
+  ease:           ['ease', 'easing', 'easings', 'transitions', 'transition'],
+  animate:        ['animate', 'animation', 'animations'],
+};
+
+// Given the canonical domain name and the list of existing Figma
+// collection names, return the existing name that aliases to the
+// canonical (if any). Returns null when nothing matches — caller should
+// create a new collection with the canonical name.
+function findCollectionAlias(canonical, existingNames) {
+  const aliases = COLLECTION_ALIASES[canonical];
+  if (!aliases) return null;
+  for (const existing of existingNames) {
+    const norm = String(existing).toLowerCase().trim();
+    if (aliases.includes(norm)) return existing;
+  }
+  return null;
+}
+
 // Exported mirror of the inline `tokenScopesFor` inside WRITE_SCRIPT.
 // The Figma plugin sandbox can't `require`, so the script needs an
 // inline copy. We keep this JS-side function as the testable mirror —
@@ -144,8 +188,46 @@ const collections = await figma.variables.getLocalVariableCollectionsAsync();
 const collectionByName = {};
 for (const c of collections) collectionByName[c.name] = c;
 
+// Alias table — see the JS-side mirror at the top of this file.
+// Inline here because the Figma plugin sandbox can't require().
+// Drift-guarded by a test in __tests__/figma-write-script.test.js.
+const COLLECTION_ALIASES = {
+  color:          ['color', 'colors', 'colour', 'colours'],
+  spacing:        ['spacing', 'space', 'spaces'],
+  radius:         ['radius', 'radii', 'rounded', 'corner radius'],
+  shadow:         ['shadow', 'shadows', 'effects'],
+  opacity:        ['opacity', 'alpha'],
+  'border-width': ['border-width', 'border width', 'borders', 'border', 'strokes', 'stroke'],
+  typography:     ['typography', 'type', 'text', 'text styles', 'type + effects', 'text + effects', 'fonts'],
+  'z-index':      ['z-index', 'z'],
+  breakpoint:     ['breakpoint', 'breakpoints', 'screens', 'media'],
+  container:      ['container', 'containers'],
+  blur:           ['blur'],
+  perspective:    ['perspective'],
+  aspect:         ['aspect', 'aspects', 'aspect ratio', 'ratios'],
+  ease:           ['ease', 'easing', 'easings', 'transitions', 'transition'],
+  animate:        ['animate', 'animation', 'animations'],
+};
+
+function resolveExistingCollection(canonical) {
+  if (collectionByName[canonical]) return collectionByName[canonical];
+  const aliases = COLLECTION_ALIASES[canonical];
+  if (!aliases) return null;
+  for (const c of collections) {
+    const norm = String(c.name).toLowerCase().trim();
+    if (aliases.includes(norm)) return c;
+  }
+  return null;
+}
+
 async function ensureCollection(name, withModes) {
-  if (collectionByName[name]) return collectionByName[name];
+  const existing = resolveExistingCollection(name);
+  if (existing) {
+    // Cache under the canonical key too so repeat calls in this run
+    // hit the fast path.
+    collectionByName[name] = existing;
+    return existing;
+  }
   const col = figma.variables.createVariableCollection(name);
   if (withModes && withModes.length > 1) {
     col.renameMode(col.modes[0].modeId, withModes[0]);
@@ -156,6 +238,7 @@ async function ensureCollection(name, withModes) {
     col.renameMode(col.modes[0].modeId, withModes[0]);
   }
   collectionByName[name] = col;
+  collections.push(col);
   return col;
 }
 
@@ -291,4 +374,4 @@ for (const a of actions) {
 return { applied, skipped, errors };
 `;
 
-module.exports = { WRITE_SCRIPT, tokenScopesFor };
+module.exports = { WRITE_SCRIPT, tokenScopesFor, findCollectionAlias, COLLECTION_ALIASES };

From c5e4b22c5cb2a02444352da351f702a02c07d57e Mon Sep 17 00:00:00 2001
From: Hugh Francis <hughfrancis89@gmail.com>
Date: Tue, 12 May 2026 15:59:24 -0400
Subject: [PATCH 63/79] lint: STRUCT014 + --fix for alias-equivalent collection
 duplicates
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Alias-aware push (the previous commit) prevents NEW duplicate
collections, but the pre-existing dupes from earlier pushes — Color +
color, Space + spacing, Borders + border-width, Type + Effects +
typography — stay parked in the file until something actively merges
them.

STRUCT014 surfaces every group where two or more Figma collections
alias to the same canonical domain. Detection works from the variable
key list (varDefs) alone — collection names are the first slash segment
of every key. Groups are ordered by var count descending so the most
populated collection is the natural "keep this one" suggestion.

/adhd:lint --fix gains a Phase 8b for STRUCT014. Per group:
  - AskUserQuestion picks the keeper (most-populated suggested first)
  - For each variable in the loser collections, create an equivalent
    in the keeper with the same name/type/scopes/description, copy
    values per mode (mapped by mode-name since mode IDs differ across
    collections), rebind every layer that references the old variable,
    delete the original.
  - When all variables in a loser are moved, delete the now-empty
    loser collection.

Name collisions (same var name exists in keeper with potentially
different value) skip the move and surface as warnings — designer
decides manually which side wins.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 README.md                                     |   2 +-
 .../lib/lint-engine/__tests__/cli.test.js     |  40 +++++
 .../collection-duplicate-detector.test.js     |  79 ++++++++++
 plugins/adhd/lib/lint-engine/cli.js           |  26 ++++
 .../collection-duplicate-detector.js          |  66 ++++++++
 plugins/adhd/skills/lint/SKILL.md             | 143 +++++++++++++++++-
 6 files changed, 354 insertions(+), 2 deletions(-)
 create mode 100644 plugins/adhd/lib/lint-engine/__tests__/collection-duplicate-detector.test.js
 create mode 100644 plugins/adhd/lib/lint-engine/collection-duplicate-detector.js

diff --git a/README.md b/README.md
index 1a7e748..a339357 100644
--- a/README.md
+++ b/README.md
@@ -88,7 +88,7 @@ Pass any Figma URL that includes a `node-id` query parameter — `/adhd:lint` wi
 /adhd:lint https://www.figma.com/design/PBCAkpPnvGXWrz6H7qfH3V/ADHD-Reference?node-id=91-18
 ```
 
-The scoped report covers the same rules (STRUCT001–012 + variable mismatches), just narrowed to the selected subtree. The URL must point at the file configured in `adhd.config.ts`; mismatched file keys abort with a fix-up message.
+The scoped report covers the same rules (STRUCT001–014 + variable mismatches), just narrowed to the selected subtree. The URL must point at the file configured in `adhd.config.ts`; mismatched file keys abort with a fix-up message.
 
 ### Annotate violations in Figma (`--annotate`)
 
diff --git a/plugins/adhd/lib/lint-engine/__tests__/cli.test.js b/plugins/adhd/lib/lint-engine/__tests__/cli.test.js
index 7e55e60..86840d9 100644
--- a/plugins/adhd/lib/lint-engine/__tests__/cli.test.js
+++ b/plugins/adhd/lib/lint-engine/__tests__/cli.test.js
@@ -454,6 +454,46 @@ test('STRUCT013: surfaces Figma variables that duplicate Tailwind defaults (stri
   assert.match(v.message, /\/adhd:lint --fix/);
 });
 
+test('STRUCT014: surfaces alias-equivalent collections side by side (Color vs color, Space vs spacing)', () => {
+  // Real scenario from the user's reactor file: prior pushes created
+  // lowercase `color`/`spacing` collections alongside designer's existing
+  // `Color`/`Space`. The new rule surfaces these for /adhd:lint --fix
+  // to consolidate; alias-aware push prevents future duplicates.
+  const varDefs = tmp('vars.json', {
+    'Color/zinc-500': '#71717a',
+    'Color/red-500': '#ef4444',
+    'color/extra-1': '#aaa',
+    'Space/4': '1rem',
+    'spacing/4': '1rem',
+    'spacing/8': '2rem',
+  });
+  const ctx = tmp('ctx.json', { id: '5:1', name: 'X', type: 'FRAME', layoutMode: 'VERTICAL' });
+  const cssPath = tmp('globals.css', `@theme {} :root {} :root[data-theme="dark"] {}`);
+  const configPath = tmp('adhd.config.ts', `export default { naming: 'kebab-case' };`);
+  const reportPath = path.join(os.tmpdir(), 'adhd-report-' + Date.now() + '.md');
+
+  const result = spawnSync('node', [
+    CLI, '--variable-defs', varDefs, '--design-context', ctx,
+    '--globals-css', cssPath, '--config', configPath, '--target', 'X',
+    '--target-url', 'https://figma.com/design/abc?node-id=5-1', '--output', reportPath,
+  ], { encoding: 'utf8' });
+
+  const summary = JSON.parse(result.stdout);
+  const struct014 = summary.structure.filter(v => v.rule === 'STRUCT014');
+  assert.equal(struct014.length, 2);
+  const byCanonical = Object.fromEntries(struct014.map(v => [v.canonical, v]));
+  assert.ok(byCanonical['color']);
+  assert.ok(byCanonical['spacing']);
+  // Most-populated collection first in each group.
+  assert.equal(byCanonical['color'].collections[0].name, 'Color');
+  assert.equal(byCanonical['color'].collections[0].varCount, 2);
+  assert.equal(byCanonical['spacing'].collections[0].name, 'spacing');
+  assert.equal(byCanonical['spacing'].collections[0].varCount, 2);
+  // Message names the canonical + lists the colliding collections.
+  assert.match(byCanonical['color'].message, /alias to "color"/);
+  assert.match(byCanonical['color'].message, /\/adhd:lint --fix/);
+});
+
 test('STRUCT011: omits nodeId in whole-file mode (no scope root to annotate)', () => {
   const varDefs = tmp('vars.json', { 'Primitives/color/BrandPrimary': '#000' });
   const ctx = tmp('ctx.json', { mode: 'whole-file', pages: [] });
diff --git a/plugins/adhd/lib/lint-engine/__tests__/collection-duplicate-detector.test.js b/plugins/adhd/lib/lint-engine/__tests__/collection-duplicate-detector.test.js
new file mode 100644
index 0000000..0fe3893
--- /dev/null
+++ b/plugins/adhd/lib/lint-engine/__tests__/collection-duplicate-detector.test.js
@@ -0,0 +1,79 @@
+'use strict';
+
+const test = require('node:test');
+const assert = require('node:assert/strict');
+const { detectDuplicateCollections } = require('../collection-duplicate-detector');
+
+test('detects case-variant collections (Color vs color)', () => {
+  const groups = detectDuplicateCollections([
+    'Color/zinc-500', 'Color/red-500',
+    'color/zinc-500', 'color/red-500', 'color/blue-500',
+  ]);
+  assert.equal(groups.length, 1);
+  assert.equal(groups[0].canonical, 'color');
+  // Most-populated first.
+  assert.equal(groups[0].collections[0].name, 'color');
+  assert.equal(groups[0].collections[0].varCount, 3);
+  assert.equal(groups[0].collections[1].name, 'Color');
+  assert.equal(groups[0].collections[1].varCount, 2);
+});
+
+test('detects synonym collections (Space vs spacing, Borders vs border-width, Type + Effects vs typography)', () => {
+  const groups = detectDuplicateCollections([
+    'Space/4', 'Space/8',
+    'spacing/4', 'spacing/8', 'spacing/16',
+    'Borders/sm', 'Borders/md',
+    'border-width/sm',
+    'Type + Effects/text-lg',
+    'typography/text-lg', 'typography/leading-relaxed',
+  ]);
+  const byCanonical = Object.fromEntries(groups.map(g => [g.canonical, g]));
+  assert.deepEqual(Object.keys(byCanonical).sort(), ['border-width', 'spacing', 'typography']);
+  assert.equal(byCanonical['spacing'].collections.length, 2);
+  assert.equal(byCanonical['border-width'].collections.length, 2);
+  assert.equal(byCanonical['typography'].collections.length, 2);
+});
+
+test('does not fire when only one collection exists per canonical', () => {
+  // No duplicates — alias resolution finds exactly one Figma collection
+  // per canonical, nothing to consolidate.
+  const groups = detectDuplicateCollections([
+    'Color/zinc-500', 'Color/red-500',
+    'Spacing/4',
+    'Radius/sm',
+  ]);
+  assert.deepEqual(groups, []);
+});
+
+test('ignores collections whose names don\'t alias to a known canonical', () => {
+  // "Foo" isn't in the alias table. Doesn't surface.
+  const groups = detectDuplicateCollections([
+    'Foo/x', 'Foo/y',
+    'Bar/x',
+  ]);
+  assert.deepEqual(groups, []);
+});
+
+test('handles three-way duplicates (Color + colors + Colour)', () => {
+  const groups = detectDuplicateCollections([
+    'Color/a', 'Color/b', 'Color/c',
+    'colors/a',
+    'Colour/a', 'Colour/b',
+  ]);
+  assert.equal(groups.length, 1);
+  // Three collections, sorted by varCount desc, then by name asc.
+  assert.deepEqual(groups[0].collections.map(c => c.name), ['Color', 'Colour', 'colors']);
+});
+
+test('empty / invalid input returns empty array (safe default)', () => {
+  assert.deepEqual(detectDuplicateCollections([]), []);
+  assert.deepEqual(detectDuplicateCollections(null), []);
+  assert.deepEqual(detectDuplicateCollections(undefined), []);
+});
+
+test('skips entries without a slash (single-segment names)', () => {
+  // Bare names like "loose" don't have a collection prefix; ignore them.
+  const groups = detectDuplicateCollections(['Color/a', 'color/a', 'loose']);
+  assert.equal(groups.length, 1);
+  assert.equal(groups[0].canonical, 'color');
+});
diff --git a/plugins/adhd/lib/lint-engine/cli.js b/plugins/adhd/lib/lint-engine/cli.js
index ee7cc99..66b0a30 100644
--- a/plugins/adhd/lib/lint-engine/cli.js
+++ b/plugins/adhd/lib/lint-engine/cli.js
@@ -51,6 +51,7 @@ const { checkStructure } = require('./structure-checker');
 const { buildVariableSuggestions } = require('./variable-namer');
 const { checkBindings } = require('./binding-checker');
 const { detectTailwindDuplicates } = require('./tailwind-duplicate-detector');
+const { detectDuplicateCollections } = require('./collection-duplicate-detector');
 const { formatReport } = require('./report-formatter');
 
 function parseArgs(argv) {
@@ -281,6 +282,31 @@ function main() {
     });
   }
 
+  // STRUCT014 — duplicate collections (e.g. "Color" + "color" side-by-
+  // side, "Type + Effects" + "typography"). Surface every group so
+  // designers can see what's grown up over time. /adhd:lint --fix
+  // consolidates per group: pick the keeper, move every variable from
+  // the loser collections into it (rebinding existing layer references),
+  // then delete the empty losers.
+  const dupGroups = detectDuplicateCollections(Object.keys(varDefs || {}));
+  for (const group of dupGroups) {
+    const collNames = group.collections.map(c => `"${c.name}" (${c.varCount})`).join(', ');
+    structureViolations.push({
+      rule: 'STRUCT014',
+      severity: 'warning',
+      nodeId: undefined,
+      nodePath: 'Variables',
+      message:
+        `${group.collections.length} Figma collections alias to "${group.canonical}": ${collNames}. ` +
+        `These describe the same token domain but Figma treats them as separate collections, so designers see duplicate-looking groups in the Variables panel and push must guess which to append into.\n\n` +
+        `To apply: run \`/adhd:lint --fix\`. You'll be asked which collection to keep (the most-populated one is suggested); every variable in the others gets moved into the keeper, layer bindings update automatically, and the empty collections are deleted.`,
+      deepLink: args['target-url'],
+      // Extra fields consumed by --fix:
+      canonical: group.canonical,
+      collections: group.collections,
+    });
+  }
+
   const meta = {
     target: args.target,
     targetUrl: args['target-url'],
diff --git a/plugins/adhd/lib/lint-engine/collection-duplicate-detector.js b/plugins/adhd/lib/lint-engine/collection-duplicate-detector.js
new file mode 100644
index 0000000..30631f0
--- /dev/null
+++ b/plugins/adhd/lib/lint-engine/collection-duplicate-detector.js
@@ -0,0 +1,66 @@
+'use strict';
+
+// STRUCT014 — Figma file has multiple collections that alias to the
+// same canonical domain. The classic case: designer's "Color" collection
+// + an older push's "color" (lowercase) collection sitting side-by-side,
+// each holding some variables. The alias-aware push fix prevents new
+// duplicates from forming, but pre-existing ones need active consolidation.
+//
+// Detection works from the variable name list alone — every variable
+// key from the SKILL's `varDefs` is `<collection>/<rest>`, so collecting
+// distinct first segments gives us every collection in the file. We
+// reuse the alias table from figma-write-script so collection-name
+// matching stays consistent with push-tokens.
+
+const { COLLECTION_ALIASES } = require('../design-system/figma-write-script');
+
+// Canonical mapping: lowercase+trimmed Figma name → canonical domain.
+// Built once per call (the alias table is small).
+function buildCanonicalLookup() {
+  const out = new Map();
+  for (const [canonical, aliases] of Object.entries(COLLECTION_ALIASES)) {
+    for (const a of aliases) out.set(a, canonical);
+  }
+  return out;
+}
+
+// Given an array of Figma variable names like ["Color/zinc-500",
+// "color/red-500", "Radius/sm", "radius/lg"], return an array of
+// duplicate groups: { canonical, collections: [{ name, varCount }] }.
+// Only groups with 2+ collections appear. Order within a group: most
+// variables first (so the --fix wizard surfaces the natural "keep this
+// one" suggestion at the top).
+function detectDuplicateCollections(varNames) {
+  if (!Array.isArray(varNames)) return [];
+  const lookup = buildCanonicalLookup();
+
+  // Bucket varNames by collection name (first segment).
+  const collections = new Map();
+  for (const name of varNames) {
+    const slash = name.indexOf('/');
+    if (slash < 0) continue;
+    const coll = name.slice(0, slash);
+    collections.set(coll, (collections.get(coll) || 0) + 1);
+  }
+
+  // Group collections by their canonical domain.
+  const byCanonical = new Map();
+  for (const [collName, varCount] of collections) {
+    const canonical = lookup.get(collName.toLowerCase().trim());
+    if (!canonical) continue;
+    if (!byCanonical.has(canonical)) byCanonical.set(canonical, []);
+    byCanonical.get(canonical).push({ name: collName, varCount });
+  }
+
+  const groups = [];
+  for (const [canonical, members] of byCanonical) {
+    if (members.length < 2) continue;
+    members.sort((a, b) => b.varCount - a.varCount || a.name.localeCompare(b.name));
+    groups.push({ canonical, collections: members });
+  }
+  // Sort groups for deterministic output.
+  groups.sort((a, b) => a.canonical.localeCompare(b.canonical));
+  return groups;
+}
+
+module.exports = { detectDuplicateCollections };
diff --git a/plugins/adhd/skills/lint/SKILL.md b/plugins/adhd/skills/lint/SKILL.md
index 1a9f3e0..0122a63 100644
--- a/plugins/adhd/skills/lint/SKILL.md
+++ b/plugins/adhd/skills/lint/SKILL.md
@@ -10,7 +10,7 @@ allowed-tools: Read Write Bash AskUserQuestion mcp__plugin_figma_figma__use_figm
 Validate that a Figma file (or a single frame/component/page) is ready for code translation. Reports two classes of issue:
 
 - **Variable issues** — Figma variables used by the lint target that are missing locally or have conflicting values.
-- **Structure issues** — STRUCT001–STRUCT013 best-practice violations (auto-layout, naming, variant properties, per-layer variable naming, cross-domain variable bindings, Tailwind-default duplicates, etc.).
+- **Structure issues** — STRUCT001–STRUCT014 best-practice violations (auto-layout, naming, variant properties, per-layer variable naming, cross-domain variable bindings, Tailwind-default duplicates, alias-equivalent collection duplicates, etc.).
 
 Output: a markdown report saved to `/tmp/adhd-lint/report.md`, plus a terminal echo. The report is paste-ready for sharing with designers via Figma comments, Slack, or GitHub issues.
 
@@ -405,6 +405,147 @@ Or, on `rebound-only`:
 ⚠ Rebound `<duplicateName>` → `<canonicalName>` (<rebound> layer(s)) but could not delete the duplicate: <error>. It's no longer referenced by any visible layer; you can delete it manually if you confirm nothing else uses it.
 ```
 
+Continue to Phase 8b if any STRUCT014 violations exist. Otherwise exit normally.
+
+## Phase 8b: Consolidate duplicate collections (`--fix`, STRUCT014)
+
+If `--fix` was passed AND `/tmp/adhd-lint/stdout.json` contains STRUCT014 violations, walk each duplicate group and offer to consolidate. Each STRUCT014 entry has `canonical` (the Tailwind domain) and `collections` (array of `{ name, varCount }` for the duplicate collections in that group, sorted by varCount descending).
+
+If no STRUCT014 violations exist, skip this phase.
+
+### Per-group prompts
+
+For each group, use `AskUserQuestion`. The first option is the most-populated collection (the natural "keep this one" choice):
+
+```
+Question: "<N> Figma collections describe the same domain (`<canonical>`): <list with counts>. Which should be the keeper? Every variable in the others will be moved into the keeper (their layer bindings update automatically), then the empty collections are deleted."
+Header: "Consolidate"
+Options:
+  - "Keep \"<most-populated>\" (<count> vars)"            // first option
+  - "Keep \"<next>\" (<count> vars)"
+  - ... one per remaining collection ...
+  - "Skip — don't consolidate this group"                 // last option
+```
+
+If "Skip," move to the next group. Otherwise record `{ canonical, keeper: '<chosen name>', losers: [<other names>] }` into a running array.
+
+### Apply via use_figma
+
+After every group is decided, write the consolidation plan to `/tmp/adhd-lint/struct014-actions.json` and call `mcp__plugin_figma_figma__use_figma`. The script discovers each collection by name (case-insensitive), iterates every variable in the losers, creates an equivalent in the keeper, rebinds layers, deletes the original.
+
+```js
+const ACTIONS = /* substituted: contents of struct014-actions.json */;
+
+const allCollections = await figma.variables.getLocalVariableCollectionsAsync();
+const findColl = (name) => allCollections.find(c => c.name.toLowerCase().trim() === name.toLowerCase().trim()) || null;
+
+const results = [];
+for (const action of ACTIONS) {
+  const { keeper, losers } = action;
+  const keeperColl = findColl(keeper);
+  if (!keeperColl) {
+    results.push({ canonical: action.canonical, status: "skipped", reason: "keeper collection not found: " + keeper });
+    continue;
+  }
+
+  // Map of variable name (within collection) → variable id, for the keeper.
+  // Used to detect name collisions before creating duplicates within the keeper.
+  const keeperByName = new Map();
+  for (const vid of keeperColl.variableIds) {
+    const v = await figma.variables.getVariableByIdAsync(vid);
+    if (v) keeperByName.set(v.name, v);
+  }
+
+  let moved = 0, skippedCollision = 0, deletedColls = 0;
+  const collisions = [];
+
+  for (const loserName of losers) {
+    const loserColl = findColl(loserName);
+    if (!loserColl) continue;
+    const loserVarIds = [...loserColl.variableIds];
+
+    for (const vid of loserVarIds) {
+      const oldVar = await figma.variables.getVariableByIdAsync(vid);
+      if (!oldVar) continue;
+
+      // Name collision in the keeper? Skip the move and surface the
+      // conflict — we don't want to silently clobber a same-named
+      // variable that has different value or scopes.
+      if (keeperByName.has(oldVar.name)) {
+        collisions.push({ varName: oldVar.name, loserColl: loserName, keeperColl: keeper });
+        skippedCollision++;
+        continue;
+      }
+
+      // Create the replacement in the keeper with the same name + type.
+      const newVar = figma.variables.createVariable(oldVar.name, keeperColl, oldVar.resolvedType);
+      newVar.scopes = oldVar.scopes;
+      newVar.description = oldVar.description;
+
+      // Copy values per mode. The keeper and the loser may have different
+      // mode IDs even with the same mode names — map by name.
+      const keeperModesByName = new Map(keeperColl.modes.map(m => [m.name, m.modeId]));
+      for (const [oldModeId, value] of Object.entries(oldVar.valuesByMode)) {
+        const oldMode = loserColl.modes.find(m => m.modeId === oldModeId);
+        const targetModeId = oldMode && keeperModesByName.get(oldMode.name);
+        if (targetModeId) newVar.setValueForMode(targetModeId, value);
+      }
+      keeperByName.set(newVar.name, newVar);
+
+      // Rebind every layer using the old variable to the new one.
+      for (const page of figma.root.children) {
+        await figma.setCurrentPageAsync(page);
+        const nodes = page.findAll(() => true);
+        for (const node of nodes) {
+          if (!node.boundVariables) continue;
+          for (const [prop, alias] of Object.entries(node.boundVariables)) {
+            if (prop === "fills" || prop === "strokes" || prop === "effects") continue;
+            if (alias && alias.id === oldVar.id) node.setBoundVariable(prop, newVar);
+          }
+          for (const kind of ["fills", "strokes"]) {
+            const arr = node[kind];
+            if (!Array.isArray(arr)) continue;
+            node[kind] = arr.map((paint) => paint?.boundVariables?.color?.id === oldVar.id
+              ? figma.variables.setBoundVariableForPaint(paint, "color", newVar)
+              : paint
+            );
+          }
+        }
+      }
+
+      try { oldVar.remove(); moved++; }
+      catch (e) { results.push({ canonical: action.canonical, status: "remove-failed", varName: oldVar.name, error: String(e) }); }
+    }
+
+    // Delete the loser collection if it's now empty.
+    if (loserColl.variableIds.length === 0) {
+      try { loserColl.remove(); deletedColls++; }
+      catch (e) { results.push({ canonical: action.canonical, status: "collection-remove-failed", collName: loserName, error: String(e) }); }
+    }
+  }
+  results.push({ canonical: action.canonical, keeper, moved, skippedCollision, deletedColls, collisions, status: "ok" });
+}
+
+return { results };
+```
+
+### Report
+
+For each successful group:
+
+```
+✓ Consolidated <N> collections into `<keeper>` (<moved> variables moved, <deletedColls> empty collections removed)
+```
+
+If any name collisions surfaced (`skippedCollision > 0`):
+
+```
+⚠ <count> variable(s) in <loserColl> couldn't be moved into <keeperColl> — a variable with the same name already exists there with a potentially different value. Inspect manually in the Figma variables panel and decide which to keep:
+  - <varName>
+  - <varName>
+  ...
+```
+
 Then exit normally.
 
 ## Common errors

From ec5f5e89b0887793f2002b29669137d351249e61 Mon Sep 17 00:00:00 2001
From: Hugh Francis <hughfrancis89@gmail.com>
Date: Tue, 12 May 2026 17:23:12 -0400
Subject: [PATCH 64/79] pull-component: per-component fingerprint short-circuit
 (skip when nothing changed)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

After a successful pull, /adhd:pull-component records an 8-char SHA-256
prefix and an ISO pulledAt timestamp in adhd.config.ts next to the
component's figma block:

  components: {
    'app/Button': {
      figma: { url: '...' },
      pulledAt: '2026-05-12T14:30:00.000Z',
      fingerprint: 'a1b2c3d4',
    },
  }

The fingerprint hashes the Figma extract (component context + resolved
vars map) plus the adhd.config.ts fields that affect generated code
(naming, cssEntry). Anything that changes the pull's output flips the
hash — false-positive bias is deliberate so a missed re-sync is never
silent.

Wired into pull-component's Phase 2.5 as a short-circuit after the
Figma extract: if `fingerprint-check` says match, the SKILL exits
before lint, diff, write, or commit. The 8-char form is Git-style;
collisions are astronomically unlikely for the dozens-to-hundreds of
components a project tracks, and lookup is by path anyway.

pull-all-components surfaces fingerprint matches as a separate
`unchanged` outcome in the bulk summary so designers see how many
re-synced vs how many were skipped.

The docs route (/adhd:sync-docs) now displays "Last pulled <UTC>" on
each component page, sourced from the same `pulledAt` field — gives
designers a visual cue for how fresh each piece of generated code is.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 README.md                                     |   4 +-
 .../__tests__/config-state.test.js            | 102 ++++++++++++++
 .../__tests__/fingerprint.test.js             |  72 ++++++++++
 plugins/adhd/lib/pull-component/cli.js        |  72 +++++++++-
 .../adhd/lib/pull-component/config-state.js   | 133 ++++++++++++++++++
 .../adhd/lib/pull-component/fingerprint.js    |  59 ++++++++
 .../sync-docs/__tests__/config-parser.test.js |  21 +++
 plugins/adhd/lib/sync-docs/config-parser.js   |  16 ++-
 plugins/adhd/lib/sync-docs/route-installer.js |   3 +-
 plugins/adhd/lib/sync-docs/templates.js       |  40 ++++--
 .../adhd/skills/pull-all-components/SKILL.md  |  11 +-
 plugins/adhd/skills/pull-component/SKILL.md   |  54 ++++++-
 12 files changed, 562 insertions(+), 25 deletions(-)
 create mode 100644 plugins/adhd/lib/pull-component/__tests__/config-state.test.js
 create mode 100644 plugins/adhd/lib/pull-component/__tests__/fingerprint.test.js
 create mode 100644 plugins/adhd/lib/pull-component/config-state.js
 create mode 100644 plugins/adhd/lib/pull-component/fingerprint.js

diff --git a/README.md b/README.md
index a339357..7f72eb9 100644
--- a/README.md
+++ b/README.md
@@ -34,8 +34,8 @@ After install, nine slash commands are available:
 | `/adhd:pull-tokens` | `[--dry-run]` | Figma → code | Pulls Figma variables + named styles into globals.css. `--dry-run` previews without writing. |
 | `/adhd:push-component` | `<path> [--max-variants <n>] [--annotate]` | code → Figma | Pushes a React component to Figma as a structured Component Set with variant properties + variable bindings, plus a preflight lint check. `--annotate` annotates preflight violations on Figma nodes. |
 | `/adhd:push-all-components` | `[--continue-on-error] [--max-variants <n>] [--annotate]` | code → Figma | Bulk version of `push-component` — iterates over every entry in `adhd.config.ts`'s components map. Sequential, halt-on-first-failure by default. |
-| `/adhd:pull-component` | `<path \| figma-url> [--allow-unbound] [--annotate]` | Figma → code | Pulls a Figma Component Set into a React source file; updates lookup tables and union types only (function body untouched). `--annotate` annotates preflight violations on Figma nodes. |
-| `/adhd:pull-all-components` | `[--continue-on-error] [--allow-unbound] [--annotate]` | Figma → code | Bulk version of `pull-component` — iterates over every entry in `adhd.config.ts`'s components map. Sequential, halt-on-first-failure by default. |
+| `/adhd:pull-component` | `<path \| figma-url> [--allow-unbound] [--annotate]` | Figma → code | Pulls a Figma Component Set into a React source file; updates lookup tables and union types only (function body untouched). `--annotate` annotates preflight violations on Figma nodes. Records an 8-char fingerprint + ISO `pulledAt` in `adhd.config.ts`; subsequent pulls short-circuit (no lint, no diff, no commit) when the Figma extract + pull-relevant config still hash to the same value. |
+| `/adhd:pull-all-components` | `[--continue-on-error] [--allow-unbound] [--annotate]` | Figma → code | Bulk version of `pull-component` — iterates over every entry in `adhd.config.ts`'s components map. Sequential, halt-on-first-failure by default. Components whose stored fingerprint matches the fresh Figma extract are reported as `unchanged` and skipped (no lint, no diff, no commit). |
 | `/adhd:sync-docs` | — | install | Generates a design-system docs route in your Next.js consumer app. Tokens read live from globals.css; components are statically imported from adhd.config.ts at setup time — re-run after editing the components map. Excluded from production builds by default. |
 
 Every command above drives Figma exclusively through the `figma@claude-plugins-official` plugin. `/adhd:config` checks it's installed + authenticated up front so setup errors surface where you can fix them, not mid-pipeline.
diff --git a/plugins/adhd/lib/pull-component/__tests__/config-state.test.js b/plugins/adhd/lib/pull-component/__tests__/config-state.test.js
new file mode 100644
index 0000000..837a588
--- /dev/null
+++ b/plugins/adhd/lib/pull-component/__tests__/config-state.test.js
@@ -0,0 +1,102 @@
+'use strict';
+
+const test = require('node:test');
+const assert = require('node:assert/strict');
+const { findComponentBlock, readComponentState, writeComponentState } = require('../config-state');
+
+const SAMPLE_CONFIG = `const config = {
+  figma: { url: "https://figma.com/design/abc/Test" },
+  components: {
+    "app/components/Button": {
+      figma: { url: "https://figma.com/design/abc?node-id=1-1" },
+    },
+    "app/components/Card": {
+      figma: { url: "https://figma.com/design/abc?node-id=2-2" },
+      pulledAt: "2026-05-01T10:00:00.000Z",
+      fingerprint: "deadbeef",
+    },
+  },
+  naming: "kebab-case",
+};
+export default config;`;
+
+test('findComponentBlock: locates the value block for a path key', () => {
+  const block = findComponentBlock(SAMPLE_CONFIG, 'app/components/Button');
+  assert.ok(block);
+  assert.equal(SAMPLE_CONFIG[block.openAt], '{');
+  assert.equal(SAMPLE_CONFIG[block.closeAt], '}');
+  // Body should contain the figma sub-block.
+  assert.match(block.body, /figma:\s*\{\s*url:/);
+});
+
+test('findComponentBlock: returns null for unknown paths', () => {
+  assert.equal(findComponentBlock(SAMPLE_CONFIG, 'app/components/Nope'), null);
+});
+
+test('readComponentState: returns null when no fingerprint stored yet', () => {
+  // Button block has no pulledAt/fingerprint — treat as "never pulled."
+  assert.equal(readComponentState(SAMPLE_CONFIG, 'app/components/Button'), null);
+});
+
+test('readComponentState: returns { pulledAt, fingerprint } when present', () => {
+  const state = readComponentState(SAMPLE_CONFIG, 'app/components/Card');
+  assert.deepEqual(state, { pulledAt: '2026-05-01T10:00:00.000Z', fingerprint: 'deadbeef' });
+});
+
+test('readComponentState: ignores fields inside nested blocks (figma: { url } is not the fingerprint)', () => {
+  // If `pulledAt` or `fingerprint` appeared inside a nested block by
+  // accident, the brace-counted scan would correctly ignore them.
+  const tricky = `const config = {
+    components: {
+      "x": {
+        figma: { url: "fake-fingerprint-inside", pulledAt: "fake" },
+      },
+    },
+  };`;
+  // Only top-level pulledAt/fingerprint count — there are none here.
+  assert.equal(readComponentState(tricky, 'x'), null);
+});
+
+test('writeComponentState: inserts pulledAt + fingerprint when absent', () => {
+  const next = writeComponentState(SAMPLE_CONFIG, 'app/components/Button', {
+    pulledAt: '2026-05-12T14:30:00.000Z',
+    fingerprint: 'a1b2c3d4',
+  });
+  // Round-trip: reading should now find the values.
+  const state = readComponentState(next, 'app/components/Button');
+  assert.deepEqual(state, { pulledAt: '2026-05-12T14:30:00.000Z', fingerprint: 'a1b2c3d4' });
+  // Original Card entry untouched.
+  const card = readComponentState(next, 'app/components/Card');
+  assert.deepEqual(card, { pulledAt: '2026-05-01T10:00:00.000Z', fingerprint: 'deadbeef' });
+});
+
+test('writeComponentState: replaces existing pulledAt + fingerprint values', () => {
+  const next = writeComponentState(SAMPLE_CONFIG, 'app/components/Card', {
+    pulledAt: '2026-05-13T09:00:00.000Z',
+    fingerprint: 'cafef00d',
+  });
+  const state = readComponentState(next, 'app/components/Card');
+  assert.deepEqual(state, { pulledAt: '2026-05-13T09:00:00.000Z', fingerprint: 'cafef00d' });
+  // Button entry stays empty (no fingerprint stored).
+  assert.equal(readComponentState(next, 'app/components/Button'), null);
+});
+
+test('writeComponentState: throws when the component path is missing from config', () => {
+  assert.throws(
+    () => writeComponentState(SAMPLE_CONFIG, 'app/components/Nope', { pulledAt: 'x', fingerprint: 'y' }),
+    /Component not found/,
+  );
+});
+
+test('writeComponentState: preserves surrounding fields and trailing commas', () => {
+  const next = writeComponentState(SAMPLE_CONFIG, 'app/components/Button', {
+    pulledAt: '2026-05-12T14:30:00.000Z',
+    fingerprint: 'a1b2c3d4',
+  });
+  // The original `figma: { url: ... }` is still there.
+  assert.match(next, /"app\/components\/Button":\s*\{[\s\S]*figma:\s*\{\s*url:/);
+  // The other component (Card) is intact.
+  assert.match(next, /"app\/components\/Card":\s*\{[\s\S]*pulledAt: "2026-05-01T10:00:00\.000Z"/);
+  // No syntax wreckage — config still has the closing structure.
+  assert.match(next, /\};\s*\nexport default config;/);
+});
diff --git a/plugins/adhd/lib/pull-component/__tests__/fingerprint.test.js b/plugins/adhd/lib/pull-component/__tests__/fingerprint.test.js
new file mode 100644
index 0000000..448331a
--- /dev/null
+++ b/plugins/adhd/lib/pull-component/__tests__/fingerprint.test.js
@@ -0,0 +1,72 @@
+'use strict';
+
+const test = require('node:test');
+const assert = require('node:assert/strict');
+const { computeFingerprint, canonicalJson, relevantConfigFields } = require('../fingerprint');
+
+test('canonicalJson: produces same string regardless of key order', () => {
+  const a = { figma: { url: 'x' }, naming: 'kebab' };
+  const b = { naming: 'kebab', figma: { url: 'x' } };
+  assert.equal(canonicalJson(a), canonicalJson(b));
+});
+
+test('canonicalJson: nested keys sort independently', () => {
+  const a = { x: { c: 1, a: 2, b: 3 } };
+  assert.equal(canonicalJson(a), '{"x":{"a":2,"b":3,"c":1}}');
+});
+
+test('canonicalJson: arrays preserve order (semantic)', () => {
+  assert.equal(canonicalJson([3, 1, 2]), '[3,1,2]');
+});
+
+test('computeFingerprint: returns 8 hex chars', () => {
+  const fp = computeFingerprint({ figma: 'x' });
+  assert.match(fp, /^[0-9a-f]{8}$/);
+});
+
+test('computeFingerprint: identical inputs hash identically', () => {
+  const a = computeFingerprint({ x: 1, y: 2 });
+  const b = computeFingerprint({ y: 2, x: 1 });
+  assert.equal(a, b);
+});
+
+test('computeFingerprint: any change to the input changes the hash', () => {
+  // The asymmetric failure mode: false positives (re-pull when output
+  // would be identical) are fine; false negatives (skip when output
+  // would differ) would be a correctness bug. Confirm changes propagate.
+  const base = computeFingerprint({ figma: { url: 'x' } });
+  const changed = computeFingerprint({ figma: { url: 'y' } });
+  assert.notEqual(base, changed);
+  // Even a deeply-nested change flips the hash.
+  const deepBase = computeFingerprint({ a: { b: { c: 1 } } });
+  const deepChanged = computeFingerprint({ a: { b: { c: 2 } } });
+  assert.notEqual(deepBase, deepChanged);
+});
+
+test('relevantConfigFields: extracts pull-affecting config bits', () => {
+  const out = relevantConfigFields({
+    figma: { url: 'https://figma.com/design/abc' },
+    naming: 'PascalCase',
+    cssEntry: 'src/app/globals.css',
+    components: { 'x': {} },
+  });
+  // Only fields that affect generated code make it in.
+  assert.deepEqual(out, { naming: 'PascalCase', cssEntry: 'src/app/globals.css' });
+});
+
+test('relevantConfigFields: handles missing optional fields', () => {
+  const out = relevantConfigFields({ figma: { url: 'x' } });
+  assert.equal(out.naming, 'kebab-case'); // default
+  assert.equal(out.cssEntry, null);
+});
+
+test('fingerprint changes when config naming changes (the invalidation case)', () => {
+  // The whole point of including config in the fingerprint: if a
+  // designer changes `naming` from kebab to Pascal, the same Figma
+  // input now produces different code. We must NOT skip on the next
+  // pull just because Figma is unchanged.
+  const figmaExtract = { name: 'Button', variants: [{ size: 'sm' }] };
+  const kebab = computeFingerprint({ figma: figmaExtract, config: relevantConfigFields({ naming: 'kebab-case' }) });
+  const pascal = computeFingerprint({ figma: figmaExtract, config: relevantConfigFields({ naming: 'PascalCase' }) });
+  assert.notEqual(kebab, pascal);
+});
diff --git a/plugins/adhd/lib/pull-component/cli.js b/plugins/adhd/lib/pull-component/cli.js
index 78f18c1..0bb180e 100644
--- a/plugins/adhd/lib/pull-component/cli.js
+++ b/plugins/adhd/lib/pull-component/cli.js
@@ -3,6 +3,8 @@
 
 const fs = require('node:fs');
 const { readComponentMapping, addComponentMapping, reverseLookupPath } = require('./config-writer');
+const { computeFingerprint, relevantConfigFields } = require('./fingerprint');
+const { readComponentState, writeComponentState } = require('./config-state');
 
 function parseArgs(argv) {
   const args = { _: [] };
@@ -18,8 +20,34 @@ function parseArgs(argv) {
 function printUsage() {
   console.log(`Usage:
   cli.js config-write --config <adhd.config.ts> --path <relative-path> --figma-url <url>
-  cli.js config-read --config <adhd.config.ts> --path <relative-path>
-  cli.js config-reverse --config <adhd.config.ts> --figma-url <url>`);
+  cli.js config-read  --config <adhd.config.ts> --path <relative-path>
+  cli.js config-reverse --config <adhd.config.ts> --figma-url <url>
+  cli.js fingerprint-check --config <adhd.config.ts> --path <relative-path> --ctx <ctx.json> --vars <vars.json>
+  cli.js fingerprint-write --config <adhd.config.ts> --path <relative-path> --ctx <ctx.json> --vars <vars.json>
+
+fingerprint-check:
+  Computes the fingerprint of the fresh Figma extract + relevant config bits
+  and compares to the stored fingerprint in adhd.config.ts. Writes JSON to
+  stdout: { current, stored, match }. Exit 0 always — the SKILL branches on
+  the parsed output.
+
+fingerprint-write:
+  Computes the fingerprint and writes it (plus an ISO pulledAt timestamp)
+  into adhd.config.ts at components.<path>. Used after a successful pull.`);
+}
+
+// Parse adhd.config.ts text for the fields that affect pull output.
+// Permissive regex — same approach as parsePushTokensFromConfig in
+// lib/design-system/dispositions.js. The schema is small and stable
+// enough that a TS evaluator isn't worth the dependency.
+function parsePullRelevantConfig(src) {
+  const naming = (/naming\s*:\s*["']([^"']+)["']/.exec(src) || [])[1] || 'kebab-case';
+  const cssEntry = (/cssEntry\s*:\s*["']([^"']+)["']/.exec(src) || [])[1] || null;
+  return { naming, cssEntry };
+}
+
+function readJsonOrEmpty(p) {
+  try { return JSON.parse(fs.readFileSync(p, 'utf8')); } catch { return null; }
 }
 
 function main() {
@@ -63,6 +91,46 @@ function main() {
     process.exit(0);
   }
 
+  if (cmd === 'fingerprint-check') {
+    if (!args.config || !args.path || !args.ctx || !args.vars) {
+      console.error('Usage: fingerprint-check --config <path> --path <rel> --ctx <ctx.json> --vars <vars.json>');
+      process.exit(2);
+    }
+    const configSrc = fs.readFileSync(args.config, 'utf8');
+    const ctx = readJsonOrEmpty(args.ctx);
+    const vars = readJsonOrEmpty(args.vars);
+    const current = computeFingerprint({
+      figma: { ctx, vars },
+      config: relevantConfigFields(parsePullRelevantConfig(configSrc)),
+    });
+    const stored = readComponentState(configSrc, args.path);
+    process.stdout.write(JSON.stringify({
+      current,
+      stored,
+      match: !!(stored && stored.fingerprint === current),
+    }));
+    process.exit(0);
+  }
+
+  if (cmd === 'fingerprint-write') {
+    if (!args.config || !args.path || !args.ctx || !args.vars) {
+      console.error('Usage: fingerprint-write --config <path> --path <rel> --ctx <ctx.json> --vars <vars.json>');
+      process.exit(2);
+    }
+    const configSrc = fs.readFileSync(args.config, 'utf8');
+    const ctx = readJsonOrEmpty(args.ctx);
+    const vars = readJsonOrEmpty(args.vars);
+    const fingerprint = computeFingerprint({
+      figma: { ctx, vars },
+      config: relevantConfigFields(parsePullRelevantConfig(configSrc)),
+    });
+    const pulledAt = new Date().toISOString();
+    const next = writeComponentState(configSrc, args.path, { pulledAt, fingerprint });
+    fs.writeFileSync(args.config, next);
+    process.stdout.write(JSON.stringify({ fingerprint, pulledAt }));
+    process.exit(0);
+  }
+
   console.error('Unknown subcommand: ' + cmd);
   process.exit(2);
 }
diff --git a/plugins/adhd/lib/pull-component/config-state.js b/plugins/adhd/lib/pull-component/config-state.js
new file mode 100644
index 0000000..3fa4eba
--- /dev/null
+++ b/plugins/adhd/lib/pull-component/config-state.js
@@ -0,0 +1,133 @@
+'use strict';
+
+// Read + write per-component pull state (pulledAt + fingerprint) in
+// adhd.config.ts. The user wants this in the config rather than a
+// sidecar because pull state is "true state we should be following" —
+// a fingerprint mismatch on next pull means the source has drifted.
+//
+// State shape inside `components: { '<path>': { ... } }`:
+//
+//   components: {
+//     'app/components/Button': {
+//       figma: { url: '...' },
+//       pulledAt: '2026-05-12T14:30:00.000Z',
+//       fingerprint: 'a1b2c3d4',
+//     },
+//   }
+//
+// Brace-counted parsing (not greedy regex) so nested `figma: { url }`
+// doesn't confuse the boundary detection.
+
+function escapeForRegex(s) {
+  return s.replace(/[.*+?^${}()|[\]\\\/]/g, '\\$&');
+}
+
+// Locate the `{ ... }` value block for the given component-path key
+// within the components map. Returns `{ openAt, closeAt, body }` —
+// `openAt` and `closeAt` are absolute indices of the opening and
+// closing braces. Returns null when the path key isn't found.
+function findComponentBlock(src, componentPath) {
+  if (!src) return null;
+  const keyPattern = new RegExp(
+    '["\']' + escapeForRegex(componentPath) + '["\']\\s*:\\s*\\{',
+  );
+  const m = keyPattern.exec(src);
+  if (!m) return null;
+  const openAt = m.index + m[0].length - 1;
+  let depth = 1;
+  let i = openAt + 1;
+  while (i < src.length && depth > 0) {
+    if (src[i] === '{') depth++;
+    else if (src[i] === '}') depth--;
+    if (depth === 0) break;
+    i++;
+  }
+  if (depth !== 0) return null;
+  return { openAt, closeAt: i, body: src.slice(openAt + 1, i) };
+}
+
+// Read pulledAt + fingerprint from a component block. Returns null when
+// the component or either field is missing — caller treats that as
+// "no cached fingerprint, must pull fresh".
+function readComponentState(src, componentPath) {
+  const block = findComponentBlock(src, componentPath);
+  if (!block) return null;
+  // Match only top-level fields within the block (depth 0). Use a
+  // brace-counted scan so a nested `figma: { url: "..." }` doesn't
+  // shadow a real top-level `fingerprint` field.
+  const findField = (name) => {
+    const re = new RegExp(name + '\\s*:\\s*["\']([^"\']+)["\']', 'g');
+    let d = 0;
+    let i = 0;
+    while (i < block.body.length) {
+      const ch = block.body[i];
+      if (ch === '{') { d++; i++; continue; }
+      if (ch === '}') { d--; i++; continue; }
+      if (d === 0) {
+        re.lastIndex = i;
+        const m = re.exec(block.body);
+        if (m && m.index === i) return m[1];
+      }
+      i++;
+    }
+    return null;
+  };
+  const pulledAt = findField('pulledAt');
+  const fingerprint = findField('fingerprint');
+  if (!pulledAt || !fingerprint) return null;
+  return { pulledAt, fingerprint };
+}
+
+// Upsert pulledAt + fingerprint into the component's block. If the
+// fields exist (any quoting style), their values are replaced; if not,
+// they're inserted before the closing `}` with consistent indentation
+// matched from the surrounding block.
+//
+// Throws when the component path isn't in the config — caller should
+// guard, since pull-component requires the path to be configured anyway.
+function writeComponentState(src, componentPath, { pulledAt, fingerprint }) {
+  const block = findComponentBlock(src, componentPath);
+  if (!block) {
+    throw new Error('Component not found in adhd.config.ts: ' + componentPath);
+  }
+  // Update if present, insert if not — same logic for both fields.
+  const upsert = (currentSrc, blockOpenAt, blockCloseAt, name, value) => {
+    const localBody = currentSrc.slice(blockOpenAt + 1, blockCloseAt);
+    const re = new RegExp('(' + name + '\\s*:\\s*)["\'][^"\']*["\']');
+    const m = re.exec(localBody);
+    if (m) {
+      // Replace just the quoted value, preserving the existing quote style.
+      const valueStart = blockOpenAt + 1 + m.index + m[1].length;
+      const valueEnd = valueStart + (m[0].length - m[1].length);
+      const quote = currentSrc[valueStart];
+      return currentSrc.slice(0, valueStart) + quote + value + quote + currentSrc.slice(valueEnd);
+    }
+    // Insert before the closing `}`. Indent one nesting deeper than
+    // the closing brace's line — the brace sits at the block's outer
+    // indent, so its leading whitespace + 2 spaces gives us the inner
+    // indent the existing entries use.
+    const before = currentSrc.slice(0, blockCloseAt);
+    const lastNl = before.lastIndexOf('\n');
+    const closingLine = before.slice(lastNl + 1);
+    const closingIndent = /^\s*/.exec(closingLine)[0];
+    const indent = closingIndent + '  ';
+    // Ensure the prior content ends in `,` — adhd configs always use
+    // trailing commas, so an entry without one would be malformed.
+    let prefix = '';
+    const trimmedPrior = before.slice(0, lastNl).trimEnd();
+    if (trimmedPrior.length > 0 && !trimmedPrior.endsWith(',') && !trimmedPrior.endsWith('{')) {
+      prefix = ',';
+    }
+    const insertion = prefix + '\n' + indent + name + ': "' + value + '",';
+    return currentSrc.slice(0, lastNl) + insertion + currentSrc.slice(lastNl);
+  };
+  let out = src;
+  // Order matters — pulledAt first so re-finding the block uses fresh indices.
+  out = upsert(out, block.openAt, block.closeAt, 'pulledAt', pulledAt);
+  // Re-find the block since indices shifted.
+  const block2 = findComponentBlock(out, componentPath);
+  out = upsert(out, block2.openAt, block2.closeAt, 'fingerprint', fingerprint);
+  return out;
+}
+
+module.exports = { findComponentBlock, readComponentState, writeComponentState };
diff --git a/plugins/adhd/lib/pull-component/fingerprint.js b/plugins/adhd/lib/pull-component/fingerprint.js
new file mode 100644
index 0000000..0687bd0
--- /dev/null
+++ b/plugins/adhd/lib/pull-component/fingerprint.js
@@ -0,0 +1,59 @@
+'use strict';
+
+// Per-component fingerprints for pull-component / pull-all-components.
+//
+// After a successful pull we record an 8-char SHA-256 prefix in
+// adhd.config.ts (next to `pulledAt`). On the next pull we hash the
+// fresh Figma extract + the adhd-config fields that affect pull output
+// (naming convention etc.) and compare. Match → early-exit, nothing
+// changed since last pull, skip the parse/diff/write loop.
+//
+// Fail mode is intentionally false-positive: any change to anything in
+// the hashed input forces a re-sync. False negatives (skip when output
+// would differ) would be a silent correctness bug, so we'd rather pay
+// for occasional redundant re-syncs.
+//
+// 8 hex characters = 32 bits of fingerprint space. Collisions across
+// the dozens-to-hundreds of components a typical project tracks are
+// astronomically unlikely; the lookup happens by component path
+// anyway, so even a hash collision wouldn't cross-contaminate.
+
+const crypto = require('node:crypto');
+
+// Stable JSON: keys sorted at every level. JSON.stringify's iteration
+// order is V8-stable in practice but not guaranteed by the spec; the
+// canonical form removes that dependency.
+function canonicalJson(value) {
+  if (value === null || typeof value !== 'object') return JSON.stringify(value);
+  if (Array.isArray(value)) {
+    return '[' + value.map(canonicalJson).join(',') + ']';
+  }
+  const keys = Object.keys(value).sort();
+  return '{' + keys.map(k => JSON.stringify(k) + ':' + canonicalJson(value[k])).join(',') + '}';
+}
+
+// Hash an arbitrary input (extract + relevant config bits, etc.) to an
+// 8-hex-char Git-style short SHA. Caller controls what goes in.
+function computeFingerprint(input) {
+  const canonical = canonicalJson(input);
+  return crypto.createHash('sha256').update(canonical).digest('hex').slice(0, 8);
+}
+
+// Extract the adhd-config fields that change pull-component's OUTPUT
+// (not just its execution). Anything in here goes into the fingerprint
+// alongside the Figma extract — changing naming-convention or cssEntry
+// must invalidate cached fingerprints because the same Figma input
+// produces different code with the new config.
+//
+// Intentionally narrow: `figma.url` doesn't affect output (it's where
+// to fetch from, not what to write); `--annotate` / `--allow-unbound`
+// are flags that don't change a successful pull's generated code.
+// Add fields here if/when they're observed to affect output.
+function relevantConfigFields(config) {
+  return {
+    naming: config && config.naming != null ? config.naming : 'kebab-case',
+    cssEntry: config && config.cssEntry ? String(config.cssEntry) : null,
+  };
+}
+
+module.exports = { computeFingerprint, canonicalJson, relevantConfigFields };
diff --git a/plugins/adhd/lib/sync-docs/__tests__/config-parser.test.js b/plugins/adhd/lib/sync-docs/__tests__/config-parser.test.js
index 58c1b1f..20369f8 100644
--- a/plugins/adhd/lib/sync-docs/__tests__/config-parser.test.js
+++ b/plugins/adhd/lib/sync-docs/__tests__/config-parser.test.js
@@ -72,6 +72,7 @@ export default config;
     rawPath: 'components/design-system/logo/index.tsx',
     importPath: '@/components/design-system/logo',
     figmaUrl: 'x',
+    pulledAt: null,
   }]);
   assert.equal(r.cssEntry, 'app/globals.css');
 });
@@ -93,6 +94,26 @@ export default config;
   assert.equal(button.figmaUrl, null);
 });
 
+test('readConfig extracts pulledAt per component, falling back to null when absent', () => {
+  // pulledAt is the timestamp /adhd:pull-component records on a
+  // successful pull (alongside the fingerprint). The docs route shows
+  // it on each component page so designers know how fresh the code is.
+  const root = makeProject(`
+const config = {
+  components: {
+    "components/logo/index.tsx":   { figma: { url: "x" }, pulledAt: "2026-05-12T14:30:00.000Z", fingerprint: "a1b2c3d4" },
+    "components/button/index.tsx": { figma: { url: "y" } },
+  },
+};
+export default config;
+`);
+  const r = readConfig(root);
+  const logo = r.components.find(c => c.slug === 'logo');
+  const button = r.components.find(c => c.slug === 'button');
+  assert.equal(logo.pulledAt, '2026-05-12T14:30:00.000Z');
+  assert.equal(button.pulledAt, null);
+});
+
 test('readConfig throws if adhd.config.ts is missing', () => {
   const root = fs.mkdtempSync(path.join(os.tmpdir(), 'adhd-cfg-missing-'));
   assert.throws(() => readConfig(root), /ENOENT|no such file/);
diff --git a/plugins/adhd/lib/sync-docs/config-parser.js b/plugins/adhd/lib/sync-docs/config-parser.js
index ae91aac..37e13ce 100644
--- a/plugins/adhd/lib/sync-docs/config-parser.js
+++ b/plugins/adhd/lib/sync-docs/config-parser.js
@@ -86,6 +86,19 @@ function importPathFor(p) {
   return '@/' + p.replace(/\.tsx?$/, '').replace(/\/index$/, '');
 }
 
+// Per-path `pulledAt` extractor. Mirrors parseFigmaUrlForPath: targeted
+// regex scoped to the value block that follows the path key. Returns
+// null when no pulledAt has been recorded yet (component was never
+// successfully pulled or pre-dates the fingerprint feature).
+function parsePulledAtForPath(src, p) {
+  const escapedPath = p.replace(/[.*+?^${}()|[\]\\\/]/g, '\\$&');
+  const re = new RegExp(
+    '["\']' + escapedPath + '["\']\\s*:\\s*\\{[^}]*?(?:\\{[^}]*\\}[^}]*?)*?pulledAt\\s*:\\s*["\']([^"\']+)["\']',
+  );
+  const m = re.exec(src);
+  return m ? m[1] : null;
+}
+
 // Top-level parser: reads adhd.config.ts at projectRoot, returns the data the
 // installer needs. Throws if the file is missing; the consumer should run
 // `/adhd:config` first.
@@ -97,6 +110,7 @@ function readConfig(projectRoot) {
     rawPath,
     importPath: importPathFor(rawPath),
     figmaUrl: parseFigmaUrlForPath(src, rawPath),
+    pulledAt: parsePulledAtForPath(src, rawPath),
   }));
   return {
     components,
@@ -104,4 +118,4 @@ function readConfig(projectRoot) {
   };
 }
 
-module.exports = { readConfig, parseComponents, parseCssEntry, parseFigmaUrlForPath, slugFor, importPathFor };
+module.exports = { readConfig, parseComponents, parseCssEntry, parseFigmaUrlForPath, parsePulledAtForPath, slugFor, importPathFor };
diff --git a/plugins/adhd/lib/sync-docs/route-installer.js b/plugins/adhd/lib/sync-docs/route-installer.js
index 18442a1..8755c30 100644
--- a/plugins/adhd/lib/sync-docs/route-installer.js
+++ b/plugins/adhd/lib/sync-docs/route-installer.js
@@ -55,7 +55,8 @@ function renderComponentMap(projectRoot, components) {
     .map((c, i) => {
       const props = JSON.stringify(bakedPropsFor(projectRoot, c.rawPath));
       const figmaUrl = c.figmaUrl ? JSON.stringify(c.figmaUrl) : 'null';
-      return `  { slug: ${JSON.stringify(c.slug)}, rawPath: ${JSON.stringify(c.rawPath)}, figmaUrl: ${figmaUrl}, module: $cmp${i}, props: ${props} },`;
+      const pulledAt = c.pulledAt ? JSON.stringify(c.pulledAt) : 'null';
+      return `  { slug: ${JSON.stringify(c.slug)}, rawPath: ${JSON.stringify(c.rawPath)}, figmaUrl: ${figmaUrl}, pulledAt: ${pulledAt}, module: $cmp${i}, props: ${props} },`;
     })
     .join('\n');
   return COMPONENT_MAP_TSX
diff --git a/plugins/adhd/lib/sync-docs/templates.js b/plugins/adhd/lib/sync-docs/templates.js
index 79540e3..c730b26 100644
--- a/plugins/adhd/lib/sync-docs/templates.js
+++ b/plugins/adhd/lib/sync-docs/templates.js
@@ -132,6 +132,7 @@ export type ComponentEntry = {
   slug: string;
   rawPath: string;
   figmaUrl: string | null;
+  pulledAt: string | null;
   Component: React.ComponentType<Record<string, unknown>> | null;
   props: Record<string, PropSchema>;
 };
@@ -140,6 +141,7 @@ type RawEntry = {
   slug: string;
   rawPath: string;
   figmaUrl: string | null;
+  pulledAt: string | null;
   module: Record<string, unknown>;
   props: Record<string, PropSchema>;
 };
@@ -161,6 +163,7 @@ export const components: ComponentEntry[] = ENTRIES.map(e => ({
   slug: e.slug,
   rawPath: e.rawPath,
   figmaUrl: e.figmaUrl,
+  pulledAt: e.pulledAt,
   Component: resolveComponent(e.module),
   props: e.props,
 }));
@@ -558,7 +561,7 @@ export default function ComponentPage() {
 
   if (!entry) return <NotInMap slug={slug} />;
 
-  const { rawPath, figmaUrl, Component, props } = entry;
+  const { rawPath, figmaUrl, pulledAt, Component, props } = entry;
 
   // Resolve current prop values from the URL. Values are constrained to the
   // three shapes the page knows how to source — string (for union + string
@@ -591,21 +594,28 @@ export default function ComponentPage() {
 
   return (
     <div className="flex flex-col gap-6">
-      <h2 className="text-2xl font-medium flex items-center gap-2">
-        <span>{componentName}</span>
-        {figmaUrl && (
-          <a
-            href={figmaUrl}
-            target="_blank"
-            rel="noopener noreferrer"
-            className="inline-flex items-center justify-center w-6 h-6 rounded text-sm text-zinc-500 hover:text-zinc-900 dark:hover:text-zinc-100 hover:bg-zinc-100 dark:hover:bg-zinc-800 transition-colors"
-            title="Open in Figma"
-            aria-label="Open in Figma"
-          >
-            ↗
-          </a>
+      <div className="flex flex-col gap-1">
+        <h2 className="text-2xl font-medium flex items-center gap-2">
+          <span>{componentName}</span>
+          {figmaUrl && (
+            <a
+              href={figmaUrl}
+              target="_blank"
+              rel="noopener noreferrer"
+              className="inline-flex items-center justify-center w-6 h-6 rounded text-sm text-zinc-500 hover:text-zinc-900 dark:hover:text-zinc-100 hover:bg-zinc-100 dark:hover:bg-zinc-800 transition-colors"
+              title="Open in Figma"
+              aria-label="Open in Figma"
+            >
+              ↗
+            </a>
+          )}
+        </h2>
+        {pulledAt && (
+          <p className="text-[11px] text-zinc-500">
+            Last pulled {new Date(pulledAt).toISOString().slice(0, 16).replace("T", " ")} UTC
+          </p>
         )}
-      </h2>
+      </div>
 
       <section className="rounded border border-zinc-200 dark:border-zinc-800 p-4">
         <h3 className="mb-3 text-xs font-medium uppercase text-zinc-500">Props</h3>
diff --git a/plugins/adhd/skills/pull-all-components/SKILL.md b/plugins/adhd/skills/pull-all-components/SKILL.md
index edce5ca..4878730 100644
--- a/plugins/adhd/skills/pull-all-components/SKILL.md
+++ b/plugins/adhd/skills/pull-all-components/SKILL.md
@@ -95,14 +95,15 @@ For each path in the list, in order:
 
 3. Record the outcome for this component into `/tmp/adhd-pull-all/outcomes.json` (append-only). Outcome shape:
    ```json
-   { "path": "<path>", "status": "success" | "abort" | "cancel", "summary": "<one-line summary>", "error": "<abort reason if any>" }
+   { "path": "<path>", "status": "success" | "abort" | "cancel" | "unchanged", "summary": "<one-line summary>", "error": "<abort reason if any>" }
    ```
    - `success`: the per-component pull completed Phase 10 (final report).
+   - `unchanged`: the per-component pull's fingerprint short-circuit (pull-component Phase 2.5) matched the stored value — Figma + relevant config haven't changed since the last successful pull, no work was done. Recorded separately from `success` so the bulk summary surfaces how many were skipped vs how many were actively re-synced.
    - `abort`: any blocking error (STRUCT011, unbound without escape, file missing, etc.).
    - `cancel`: user said "no" / cancel on an in-flow prompt (treated as a halt — they explicitly stopped).
 
 4. **Decide whether to continue:**
-   - If `success` or `cancel`: continue to the next component. (`cancel` halts the inner per-component flow but is not treated as a bulk failure — the user made an explicit choice.)
+   - If `success`, `unchanged`, or `cancel`: continue to the next component. (`cancel` halts the inner per-component flow but is not treated as a bulk failure — the user made an explicit choice. `unchanged` is the fingerprint-skip case — also not a failure.)
    - If `abort`:
      - With `--continue-on-error`: record + continue.
      - Without (default): print `Halted on <path>. Re-run with --continue-on-error to push through subsequent components, or fix the issue and re-run /adhd:pull-component <path> directly.` Then break out of the loop and go to Phase 3.
@@ -117,13 +118,17 @@ Read `/tmp/adhd-pull-all/outcomes.json` and produce:
 Bulk pull report:
   ✓ components/design-system/logo/index.tsx  — 3 cells updated
   ✓ components/avatar/index.tsx              — no changes
+  ⊙ components/badge/index.tsx               — unchanged (fingerprint match, last pulled 2026-05-10T...)
+  ⊙ components/spinner/index.tsx             — unchanged (fingerprint match, last pulled 2026-05-11T...)
   ✗ components/button/index.tsx              — preflight: STRUCT011 (2 var-naming issues)
   ⏭ components/card/index.tsx                — skipped (earlier failure)
   ⏭ components/icon/index.tsx                — skipped (earlier failure)
 
-Summary: 2 succeeded, 1 failed, 2 skipped.
+Summary: 2 re-synced, 2 unchanged, 1 failed, 2 skipped.
 ```
 
+The `⊙` marker covers the fingerprint-short-circuit case — no work was done for that component because Figma + relevant config matched the stored fingerprint. Surface the `pulledAt` from `adhd.config.ts`'s component entry so designers can confirm what "last pulled" actually means.
+
 Append actionable next steps based on outcome:
 
 - **All succeeded:** print `Run /adhd:sync-docs to refresh the design-system docs route.` (already prompted per component but worth reminding for the whole run).
diff --git a/plugins/adhd/skills/pull-component/SKILL.md b/plugins/adhd/skills/pull-component/SKILL.md
index 0417d2d..03eec07 100644
--- a/plugins/adhd/skills/pull-component/SKILL.md
+++ b/plugins/adhd/skills/pull-component/SKILL.md
@@ -73,7 +73,31 @@ Save both via `Bash` heredoc to:
 - `/tmp/adhd-pull-component/ctx.json`
 - `/tmp/adhd-pull-component/vars.json`
 
-Run the lint engine:
+### Fingerprint short-circuit (skip when nothing changed)
+
+Before running the lint engine, hash the fresh Figma extract + the pull-output-affecting config fields and compare to the stored fingerprint in `adhd.config.ts`. If it matches, the source state hasn't changed since the last successful pull — skip lint, diff, write, commit, everything.
+
+```bash
+node plugins/adhd/lib/pull-component/cli.js fingerprint-check \
+  --config adhd.config.ts \
+  --path <relative-path-from-Phase-2> \
+  --ctx /tmp/adhd-pull-component/ctx.json \
+  --vars /tmp/adhd-pull-component/vars.json
+```
+
+The command writes JSON to stdout: `{ current, stored, match }`. Parse it. If `match === true`:
+
+```
+✓ <path> matches last-pulled fingerprint (<current>). Last pulled <stored.pulledAt>. Nothing changed — skipping pull.
+```
+
+Exit normally (do NOT proceed to lint, diff, or any apply). The user has nothing to review and nothing committed.
+
+If `match === false` (no stored fingerprint, OR Figma/config changed), continue with the lint engine run below. The new fingerprint will be persisted in Phase 10.5 after a successful pull.
+
+The fingerprint is intentionally false-positive biased: any change to the Figma extract or to pull-affecting config fields (`naming`, `cssEntry`) flips it. This means occasional re-syncs when the regenerated code would have been identical — preferable to false negatives where a real change goes unsynced.
+
+### Run the lint engine
 
 ```bash
 mkdir -p /tmp/adhd-pull-component
@@ -613,6 +637,34 @@ Component file: <react-path>
 Figma URL: <figma-url>
 ```
 
+## Phase 10.5: Persist fingerprint
+
+After a successful pull (any path that reaches Phase 10, including off-system escapes), write the fresh fingerprint + an ISO timestamp into `adhd.config.ts` so the next pull can short-circuit when nothing's changed.
+
+```bash
+node plugins/adhd/lib/pull-component/cli.js fingerprint-write \
+  --config adhd.config.ts \
+  --path <relative-path-from-Phase-2> \
+  --ctx /tmp/adhd-pull-component/ctx.json \
+  --vars /tmp/adhd-pull-component/vars.json
+```
+
+The command updates two fields inside `components: { '<path>': { ... } }`:
+
+```ts
+components: {
+  '<path>': {
+    figma: { url: '...' },
+    pulledAt: '2026-05-12T14:30:00.000Z',  // ISO from `new Date()`
+    fingerprint: 'a1b2c3d4',                // 8-hex-char SHA-256 prefix
+  },
+}
+```
+
+If `adhd.config.ts` already had values, they're replaced; if not, they're inserted before the closing brace with consistent indentation. The fingerprint is the Git-style short form (8 chars = 32 bits of fingerprint space, comfortably collision-free for the dozens-to-hundreds of components a typical project tracks, and looked up by path anyway so global collisions don't matter).
+
+This phase NEVER runs on abort — only on successful application.
+
 ## Phase 11: Cleanup
 
 Always runs (even on abort):

From c107d0315e5ff16604d08cde56aac8453ee55dc3 Mon Sep 17 00:00:00 2001
From: Hugh Francis <hughfrancis89@gmail.com>
Date: Tue, 12 May 2026 17:49:24 -0400
Subject: [PATCH 65/79] =?UTF-8?q?lint:=20STRUCT015/016=20=E2=80=94=20per-l?=
 =?UTF-8?q?ayer=20errors=20block=20pulls=20when=20bindings=20are=20broken?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Previously the lint engine surfaced "this variable is missing from
code" and "this variable's value conflicts" at the FILE level. The
component-level lint summary called the frame "ready for code
translation" because no structural errors fired, even when layers in
the frame were bound to phantom or drifting variables. Pulling such a
component would either generate code referencing a CSS variable that
globals.css doesn't declare (broken render) or render with code's value
that visibly drifts from Figma.

STRUCT015 fires per-layer when a binding references a variable that's
missing from code. STRUCT016 fires per-layer when a binding references
a variable whose value differs between code and Figma. Both are
severity=error and join STRUCT003/004/005/011 in the pull-component
blocking-error list — no escape. Designer must rebind in Figma OR run
/adhd:pull-tokens (to take Figma's values) or /adhd:push-tokens (to
send code's values back) before the pull can proceed.

Also fixes the long-tail "primary" false-conflict bug from the user's
session: normalizeColor now accepts Figma's raw {r,g,b,a} channel
object form (channels 0..1), so `#0a0a0a` and `{r: 0.039, ...}` resolve
to the same hex and the comparator stops falsely conflicting them.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 README.md                                     |  2 +-
 .../__tests__/binding-checker.test.js         | 76 +++++++++++++++++++
 .../lib/lint-engine/__tests__/cli.test.js     | 51 +++++++++++++
 .../__tests__/value-normalizer.test.js        | 19 +++++
 .../adhd/lib/lint-engine/binding-checker.js   | 41 ++++++++++
 plugins/adhd/lib/lint-engine/cli.js           | 38 +++++++++-
 .../adhd/lib/lint-engine/value-normalizer.js  | 15 +++-
 plugins/adhd/skills/lint/SKILL.md             |  2 +-
 plugins/adhd/skills/pull-component/SKILL.md   | 44 ++++++++++-
 9 files changed, 281 insertions(+), 7 deletions(-)

diff --git a/README.md b/README.md
index 7f72eb9..6a4e97f 100644
--- a/README.md
+++ b/README.md
@@ -88,7 +88,7 @@ Pass any Figma URL that includes a `node-id` query parameter — `/adhd:lint` wi
 /adhd:lint https://www.figma.com/design/PBCAkpPnvGXWrz6H7qfH3V/ADHD-Reference?node-id=91-18
 ```
 
-The scoped report covers the same rules (STRUCT001–014 + variable mismatches), just narrowed to the selected subtree. The URL must point at the file configured in `adhd.config.ts`; mismatched file keys abort with a fix-up message.
+The scoped report covers the same rules (STRUCT001–016 + variable mismatches), just narrowed to the selected subtree. The URL must point at the file configured in `adhd.config.ts`; mismatched file keys abort with a fix-up message.
 
 ### Annotate violations in Figma (`--annotate`)
 
diff --git a/plugins/adhd/lib/lint-engine/__tests__/binding-checker.test.js b/plugins/adhd/lib/lint-engine/__tests__/binding-checker.test.js
index 082d74f..68f9466 100644
--- a/plugins/adhd/lib/lint-engine/__tests__/binding-checker.test.js
+++ b/plugins/adhd/lib/lint-engine/__tests__/binding-checker.test.js
@@ -210,6 +210,82 @@ test('STRUCT011 + STRUCT012 can both fire for the same (node, binding)', () => {
   assert.deepEqual(rules, ['STRUCT011', 'STRUCT012']);
 });
 
+test('STRUCT015: layer binding a variable missing from code → error', () => {
+  // The user's core complaint: a Figma component binds `Font-Size/Body`
+  // but code's globals.css has no such variable. Pulling now would
+  // generate code that references --font-size-body, which Tailwind
+  // would resolve to nothing → broken rendering. Lint must block.
+  const root = {
+    id: '1:1', name: 'Title', type: 'TEXT',
+    boundVariables: { fontSize: { id: 'VAR:fontBody' } },
+  };
+  const result = checkBindings(root, OPTS({
+    varIdMap: { 'VAR:fontBody': 'Type + Effects/Font-Size/Body' },
+    missingVarNames: new Set(['Type + Effects/Font-Size/Body']),
+  }));
+  assert.equal(result.length, 1);
+  assert.equal(result[0].rule, 'STRUCT015');
+  assert.equal(result[0].severity, 'error');
+  assert.equal(result[0].nodeId, '1:1');
+  assert.match(result[0].message, /doesn't exist in code's design system/);
+  assert.match(result[0].message, /\/adhd:pull-tokens/);
+});
+
+test('STRUCT015: variable present in code does NOT fire', () => {
+  const root = {
+    id: '1:1', name: 'Title', type: 'TEXT',
+    boundVariables: { fontSize: { id: 'VAR:textSm' } },
+  };
+  const result = checkBindings(root, OPTS({
+    varIdMap: { 'VAR:textSm': 'text/sm' },
+    missingVarNames: new Set(['text/foo']), // text/sm not in missing set
+  }));
+  assert.equal(result.filter(v => v.rule === 'STRUCT015').length, 0);
+});
+
+test('STRUCT016: layer binding a variable with value conflict → error showing both values', () => {
+  // Designer's Figma sm = 6px, code's --radius-sm = 4px. Pulling would
+  // render with 4px — visual drift from what's in Figma.
+  const root = {
+    id: '1:1', name: 'Card', type: 'FRAME',
+    boundVariables: { cornerRadius: { id: 'VAR:radiusSm' } },
+  };
+  const result = checkBindings(root, OPTS({
+    varIdMap: { 'VAR:radiusSm': 'Radius/sm' },
+    conflictsByName: {
+      'Radius/sm': { local: '0.25rem', figma: '6px', mode: undefined },
+    },
+  }));
+  const v = result.find(x => x.rule === 'STRUCT016');
+  assert.ok(v);
+  assert.equal(v.severity, 'error');
+  assert.equal(v.nodeId, '1:1');
+  assert.match(v.message, /code: +0\.25rem/);
+  assert.match(v.message, /figma: +6px/);
+  assert.match(v.message, /\/adhd:pull-tokens.*\/adhd:push-tokens/s);
+});
+
+test('STRUCT016: format-mismatch values (hex vs RGB object) format the message readably', () => {
+  // The "primary" case: Figma's raw color is `{r: 0.039, ...}`, code's
+  // is `#0a0a0a`. The category itself shouldn't fire (value-normalizer
+  // recognizes both as the same color), but if it does fire elsewhere
+  // the message shouldn't dump a JSON object on the designer.
+  const root = {
+    id: '1:1', name: 'Hero', type: 'FRAME',
+    fills: [{ type: 'SOLID', boundVariables: { color: { id: 'VAR:p' } } }],
+  };
+  const result = checkBindings(root, OPTS({
+    varIdMap: { 'VAR:p': 'Color/primary' },
+    conflictsByName: {
+      'Color/primary': { local: '#0a0a0a', figma: { r: 0.039, g: 0.039, b: 0.039, a: 1 } },
+    },
+  }));
+  const v = result.find(x => x.rule === 'STRUCT016');
+  assert.ok(v);
+  // Figma value renders as a hex color, not a `{"r":0.039,...}` blob.
+  assert.match(v.message, /figma: +#0a0a0a/);
+});
+
 test('PROPERTY_TO_DOMAIN: covers the expected property set', () => {
   // Sanity check — if someone removes a property mapping by accident the
   // STRUCT012 check silently goes quiet for that property. Lock the
diff --git a/plugins/adhd/lib/lint-engine/__tests__/cli.test.js b/plugins/adhd/lib/lint-engine/__tests__/cli.test.js
index 86840d9..42ca85c 100644
--- a/plugins/adhd/lib/lint-engine/__tests__/cli.test.js
+++ b/plugins/adhd/lib/lint-engine/__tests__/cli.test.js
@@ -454,6 +454,57 @@ test('STRUCT013: surfaces Figma variables that duplicate Tailwind defaults (stri
   assert.match(v.message, /\/adhd:lint --fix/);
 });
 
+test('STRUCT015 + STRUCT016: per-layer errors when a layer binds a missing/conflicting Figma variable', () => {
+  // The user's main complaint: a component binds Figma variables like
+  // "Font-Size/Body" that don't exist in code, but lint reported
+  // "ready for code translation" because the variable issues weren't
+  // tied to specific layers. Now they ARE tied to layers AND surface
+  // as blocking errors.
+  const varDefs = tmp('vars.json', {
+    'Type + Effects/Font-Size/Body': '16px',  // not in code → STRUCT015
+    'Radius/sm': '6px',                        // value differs → STRUCT016
+  });
+  const idMap = tmp('varidmap.json', {
+    'VAR:fontBody': 'Type + Effects/Font-Size/Body',
+    'VAR:radiusSm': 'Radius/sm',
+  });
+  const ctx = tmp('ctx.json', {
+    id: '5:1', name: 'Card', type: 'FRAME', layoutMode: 'VERTICAL',
+    cornerRadius: 6,
+    boundVariables: { cornerRadius: { id: 'VAR:radiusSm' } },
+    children: [
+      {
+        id: '5:2', name: 'Title', type: 'TEXT',
+        boundVariables: { fontSize: { id: 'VAR:fontBody' } },
+      },
+    ],
+  });
+  const cssPath = tmp('globals.css', `@theme { --radius-sm: 0.25rem; } :root {} :root[data-theme="dark"] {}`);
+  const configPath = tmp('adhd.config.ts', `export default { naming: 'kebab-case' };`);
+  const reportPath = path.join(os.tmpdir(), 'adhd-report-' + Date.now() + '.md');
+
+  const result = spawnSync('node', [
+    CLI, '--variable-defs', varDefs, '--var-id-map', idMap, '--design-context', ctx,
+    '--globals-css', cssPath, '--config', configPath, '--target', 'Card',
+    '--target-url', 'https://figma.com/design/abc?node-id=5-1', '--output', reportPath,
+  ], { encoding: 'utf8' });
+
+  assert.equal(result.status, 1, 'errors should exit 1: stderr=' + result.stderr);
+  const summary = JSON.parse(result.stdout);
+  const struct015 = summary.structure.filter(v => v.rule === 'STRUCT015');
+  const struct016 = summary.structure.filter(v => v.rule === 'STRUCT016');
+  // STRUCT015 fires on the Title layer (binds fontSize → Font-Size/Body, not in code).
+  assert.equal(struct015.length, 1);
+  assert.equal(struct015[0].severity, 'error');
+  assert.equal(struct015[0].nodeId, '5:2');
+  assert.match(struct015[0].message, /doesn't exist in code's design system/);
+  // STRUCT016 fires on the Card layer (binds cornerRadius → Radius/sm; code 0.25rem vs figma 6px).
+  assert.equal(struct016.length, 1);
+  assert.equal(struct016[0].severity, 'error');
+  assert.equal(struct016[0].nodeId, '5:1');
+  assert.match(struct016[0].message, /value differs between code and Figma/);
+});
+
 test('STRUCT014: surfaces alias-equivalent collections side by side (Color vs color, Space vs spacing)', () => {
   // Real scenario from the user's reactor file: prior pushes created
   // lowercase `color`/`spacing` collections alongside designer's existing
diff --git a/plugins/adhd/lib/lint-engine/__tests__/value-normalizer.test.js b/plugins/adhd/lib/lint-engine/__tests__/value-normalizer.test.js
index 7693ec0..b469fd6 100644
--- a/plugins/adhd/lib/lint-engine/__tests__/value-normalizer.test.js
+++ b/plugins/adhd/lib/lint-engine/__tests__/value-normalizer.test.js
@@ -41,6 +41,25 @@ test('valuesMatch dispatches on domain', () => {
   assert.equal(valuesMatch('1.5', '1.5', 'typography'), true);
 });
 
+test('normalizeColor accepts Figma\'s raw {r,g,b,a} object form (channels 0..1)', () => {
+  // Real scenario from the user's reactor file: the SKILL\'s serializer
+  // emits color variable values straight from variable.valuesByMode, so
+  // figma side arrives as `{r:0.039, g:0.039, b:0.039, a:1}` while code
+  // is `#0a0a0a`. Without this branch the comparator falsely flagged
+  // these as conflicts.
+  assert.equal(normalizeColor({ r: 0.039, g: 0.039, b: 0.039, a: 1 }), '#0a0a0a');
+  assert.equal(normalizeColor({ r: 0, g: 0, b: 0 }), '#000000');
+  assert.equal(normalizeColor({ r: 1, g: 1, b: 1 }), '#ffffff');
+  // Alpha < 1 surfaces in the hex.
+  assert.equal(normalizeColor({ r: 1, g: 0, b: 0, a: 0.5 }), '#ff000080');
+});
+
+test('valuesMatch resolves hex-vs-RGB-object as equal (the "primary" false-conflict fix)', () => {
+  assert.equal(valuesMatch({ r: 0.039, g: 0.039, b: 0.039, a: 1 }, '#0a0a0a', 'color'), true);
+  // Truly different colors still conflict.
+  assert.equal(valuesMatch({ r: 1, g: 0, b: 0, a: 1 }, '#000000', 'color'), false);
+});
+
 test('valuesMatch deep-equals shadow objects', () => {
   const a = { offsetX: '0px', offsetY: '4px', blur: '8px', spread: '0px', color: '#000000' };
   const b = { offsetX: '0px', offsetY: '4px', blur: '8px', spread: '0px', color: '#000000' };
diff --git a/plugins/adhd/lib/lint-engine/binding-checker.js b/plugins/adhd/lib/lint-engine/binding-checker.js
index 6ae57f0..9d82128 100644
--- a/plugins/adhd/lib/lint-engine/binding-checker.js
+++ b/plugins/adhd/lib/lint-engine/binding-checker.js
@@ -86,6 +86,22 @@ function deepLink(fileKey, nodeId) {
   return 'https://figma.com/design/' + fileKey + '?node-id=' + nodeId.replace(':', '-');
 }
 
+// Pretty-print a value for a STRUCT016 conflict message. Figma's raw
+// `{r,g,b,a}` and resolved hex strings both need a compact human
+// form so designers can eyeball the drift at a glance.
+function formatValue(v) {
+  if (v == null) return '(none)';
+  if (typeof v === 'string') return v;
+  if (typeof v === 'number') return String(v);
+  if (v && typeof v === 'object' && 'r' in v && 'g' in v && 'b' in v) {
+    const to2 = (n) => Math.round(Math.max(0, Math.min(1, Number(n))) * 255).toString(16).padStart(2, '0');
+    let hex = '#' + to2(v.r) + to2(v.g) + to2(v.b);
+    if (v.a !== undefined && Number(v.a) < 1) hex += to2(v.a);
+    return hex;
+  }
+  try { return JSON.stringify(v); } catch { return String(v); }
+}
+
 function formatPerLayerSuggestion(varName, suggestion, prop) {
   if (suggestion.kind === 'rename') {
     const targetCollection = suggestion.target.split('/')[0];
@@ -131,6 +147,15 @@ function checkBindings(rootNode, opts) {
   const out = [];
   const varIdMap = opts.varIdMap || {};
   const badSuggestions = opts.badSuggestionsByName || {};
+  // STRUCT015 / STRUCT016 — per-layer errors for layers binding to
+  // Figma variables that either don't exist in code's design system
+  // (missing) or have a different value in code than in Figma
+  // (conflict). Both block pulls: missing means the generated code
+  // would reference a CSS variable that doesn't exist; conflict means
+  // the rendered output drifts from what the designer saw in Figma.
+  // Callers build these from the variable-categorizer's output.
+  const missingVarNames = opts.missingVarNames instanceof Set ? opts.missingVarNames : new Set(opts.missingVarNames || []);
+  const conflicts = opts.conflictsByName || {};
   const fileKey = opts.fileKey;
 
   walk(rootNode, '', (node, nodePath) => {
@@ -169,6 +194,22 @@ function checkBindings(rootNode, opts) {
             `aliases the same primitive.`);
         }
       }
+
+      if (missingVarNames.has(varName)) {
+        push('STRUCT015', 'error', varName,
+          `Layer binds "${varName}" (to ${prop}), but that variable doesn't exist in code's design system. ` +
+          `Pulling this component would generate code referencing a CSS variable globals.css never declares — rendering breaks at runtime.\n\n` +
+          `Fix in Figma: rebind the layer to a variable that IS in code, OR run /adhd:pull-tokens first to add this variable to globals.css. The pull-tokens flow shows the missing variable in its summary so you can choose whether to take it on.`);
+      }
+
+      const conflict = conflicts[varName];
+      if (conflict) {
+        push('STRUCT016', 'error', varName,
+          `Layer binds "${varName}" (to ${prop}), and that variable's value differs between code and Figma.\n` +
+          `  code:  ${formatValue(conflict.local)}\n` +
+          `  figma: ${formatValue(conflict.figma)}\n\n` +
+          `Pulling this component now would render with code's value — visual drift from what the designer sees in Figma. Reconcile first: run /adhd:pull-tokens to take Figma's value, or /adhd:push-tokens to send code's value back to Figma. Then re-run the pull.`);
+      }
     };
 
     if (node.boundVariables && typeof node.boundVariables === 'object') {
diff --git a/plugins/adhd/lib/lint-engine/cli.js b/plugins/adhd/lib/lint-engine/cli.js
index 66b0a30..06317d8 100644
--- a/plugins/adhd/lib/lint-engine/cli.js
+++ b/plugins/adhd/lib/lint-engine/cli.js
@@ -176,17 +176,51 @@ function main() {
   const hasIdMap = Object.keys(varIdMap).length > 0;
 
   if (hasIdMap) {
+    // Bridge the variable-categorizer's file-level missing/conflict
+    // findings into per-layer STRUCT015/STRUCT016 errors. The
+    // categorizer says "this variable is missing in code" at the file
+    // level; the binding-checker says "this specific layer binds that
+    // variable" — together, designers get an annotation right where
+    // they need to act.
+    //
+    // Figma collection names appear once in the categorizer's
+    // `token` field (collection-stripped) but the SKILL's vars.json
+    // keys include the collection. Build the set both ways so the
+    // binding-checker matches whichever form varIdMap emits.
+    const missingVarNames = new Set();
+    const conflictsByName = {};
+    for (const v of variableViolations) {
+      // Split by status: only `missing` entries go into missingVarNames,
+      // only `conflict` entries seed conflictsByName. Crossing them
+      // would over-fire STRUCT015 on every conflicting variable too.
+      if (v.status === 'missing') {
+        missingVarNames.add(v.token); // collection-stripped form
+      } else if (v.status === 'conflict') {
+        conflictsByName[v.token] = { local: v.local, figma: v.figma, mode: v.mode };
+      }
+    }
+    // Re-key with collection prefixes too: walk varIdMap values, for
+    // each, also test the collection-stripped form against the set.
+    // The binding-checker is the single consumer — instead of doing
+    // two-form lookups everywhere, pre-expand the sets here.
+    for (const fullName of Object.values(varIdMap)) {
+      const stripped = fullName.split('/').slice(1).join('/');
+      if (missingVarNames.has(stripped)) missingVarNames.add(fullName);
+      if (conflictsByName[stripped]) conflictsByName[fullName] = conflictsByName[stripped];
+    }
+
     const bindingViolations = [];
+    const opts = { fileKey, varIdMap, badSuggestionsByName, missingVarNames, conflictsByName };
     if (designCtx && designCtx.mode === 'whole-file' && Array.isArray(designCtx.pages)) {
       for (const page of designCtx.pages) {
         for (const node of page.nodes) {
-          const v = checkBindings(node, { fileKey, varIdMap, badSuggestionsByName });
+          const v = checkBindings(node, opts);
           for (const x of v) x._page = page.name;
           bindingViolations.push(...v);
         }
       }
     } else if (designCtx) {
-      bindingViolations.push(...checkBindings(designCtx, { fileKey, varIdMap, badSuggestionsByName }));
+      bindingViolations.push(...checkBindings(designCtx, opts));
     }
     structureViolations.push(...bindingViolations);
   } else if (suggestions.length > 0) {
diff --git a/plugins/adhd/lib/lint-engine/value-normalizer.js b/plugins/adhd/lib/lint-engine/value-normalizer.js
index f27e1f3..8832b15 100644
--- a/plugins/adhd/lib/lint-engine/value-normalizer.js
+++ b/plugins/adhd/lib/lint-engine/value-normalizer.js
@@ -6,8 +6,21 @@ const HEX_8 = /^#([0-9a-f]{8})$/i;
 const RGB_RE = /^rgba?\(\s*(\d+)\s*,\s*(\d+)\s*,\s*(\d+)\s*(?:,\s*([\d.]+)\s*)?\)$/i;
 
 function normalizeColor(input) {
+  // Figma's raw color form — `{r, g, b, a}` with each channel 0..1. The
+  // SKILL's serializer emits values straight from
+  // `variable.valuesByMode[mode]` without converting; without this
+  // branch, a Figma `#0a0a0a` color compared against code's `#0a0a0a`
+  // hex falsely conflicts because the figma side is `{r:0.039,...}`.
+  if (input && typeof input === 'object' && 'r' in input && 'g' in input && 'b' in input) {
+    const to2 = (n) => Math.round(Math.max(0, Math.min(1, Number(n))) * 255).toString(16).padStart(2, '0');
+    let hex = '#' + to2(input.r) + to2(input.g) + to2(input.b);
+    if (input.a !== undefined && Number(input.a) < 1) {
+      hex += to2(input.a);
+    }
+    return hex.toLowerCase();
+  }
   if (typeof input !== 'string') {
-    throw new TypeError('normalizeColor: expected string, got ' + typeof input);
+    throw new TypeError('normalizeColor: expected string or color object, got ' + typeof input);
   }
   const trimmed = input.trim();
 
diff --git a/plugins/adhd/skills/lint/SKILL.md b/plugins/adhd/skills/lint/SKILL.md
index 0122a63..dbdce9e 100644
--- a/plugins/adhd/skills/lint/SKILL.md
+++ b/plugins/adhd/skills/lint/SKILL.md
@@ -10,7 +10,7 @@ allowed-tools: Read Write Bash AskUserQuestion mcp__plugin_figma_figma__use_figm
 Validate that a Figma file (or a single frame/component/page) is ready for code translation. Reports two classes of issue:
 
 - **Variable issues** — Figma variables used by the lint target that are missing locally or have conflicting values.
-- **Structure issues** — STRUCT001–STRUCT014 best-practice violations (auto-layout, naming, variant properties, per-layer variable naming, cross-domain variable bindings, Tailwind-default duplicates, alias-equivalent collection duplicates, etc.).
+- **Structure issues** — STRUCT001–STRUCT016 best-practice violations (auto-layout, naming, variant properties, per-layer variable naming, cross-domain variable bindings, Tailwind-default duplicates, alias-equivalent collection duplicates, layers binding variables missing from code, layers binding variables whose values differ between code and Figma, etc.).
 
 Output: a markdown report saved to `/tmp/adhd-lint/report.md`, plus a terminal echo. The report is paste-ready for sharing with designers via Figma comments, Slack, or GitHub issues.
 
diff --git a/plugins/adhd/skills/pull-component/SKILL.md b/plugins/adhd/skills/pull-component/SKILL.md
index 03eec07..1511c31 100644
--- a/plugins/adhd/skills/pull-component/SKILL.md
+++ b/plugins/adhd/skills/pull-component/SKILL.md
@@ -116,10 +116,12 @@ The stdout redirect captures the engine's JSON summary for Phase 2.6's optional
 
 Use the globals.css path from `config.cssEntry` if set, otherwise auto-detect: `example/app/globals.css` → `app/globals.css` → `src/app/globals.css`.
 
-Use `Read` on `/tmp/adhd-pull-component/preflight.md`. Two classes of violation block the pull:
+Use `Read` on `/tmp/adhd-pull-component/preflight.md`. Four classes of violation block the pull:
 
 - **STRUCT003/004/005** — variable-binding errors (layer uses raw color, typography, or effect that isn't bound to a variable or paint style). The `--allow-unbound` escape applies here; without it, abort.
 - **STRUCT011** — variable-naming non-compliance (case violation OR Tailwind v4 domain mismatch). No escape — the designer fixes the names in Figma before the pull can proceed. Rationale: if Figma variables have non-conventional names, the pulled code's lookup tables would either reference broken names or drift from the design system. Better to fix the source than carry forward bad names into generated code.
+- **STRUCT015** — layer binds a Figma variable that doesn't exist in code's design system. No escape. Pulling would generate code referencing a CSS variable globals.css never declares — broken rendering at runtime. The designer either rebinds the layer to a variable that IS in code, or runs `/adhd:pull-tokens` to add the missing variable first.
+- **STRUCT016** — layer binds a Figma variable whose value in Figma differs from code's. No escape. Pulling would render with code's value, drifting from what the designer sees in Figma. Reconcile via `/adhd:pull-tokens` (take Figma's value) or `/adhd:push-tokens` (send code's value back to Figma), then re-run.
 
 Other rules' violations are noted for the final report but don't block.
 
@@ -129,7 +131,7 @@ Two paths, both producing the same `use_figma` annotation work described in `/ad
 
 **Path A — `--annotate` was passed.** Run the annotation script unconditionally.
 
-**Path B — `--annotate` was NOT passed, AND there are blocking violations (STRUCT003/004/005 binding errors, OR STRUCT011 variable-naming non-compliance).** Use `AskUserQuestion` to offer annotation retroactively:
+**Path B — `--annotate` was NOT passed, AND there are blocking violations (STRUCT003/004/005 binding errors, STRUCT011 variable-naming non-compliance, STRUCT015 variable-missing-in-code, or STRUCT016 variable-value-conflict).** Use `AskUserQuestion` to offer annotation retroactively:
 
 ```
 Question: "Push these <N> preflight violation(s) to Figma as annotations before aborting? Designers can see them in the 'lint' category to fix in-context."
@@ -208,6 +210,44 @@ would land in your code's lookup tables and drift on the next push.
 
 If BOTH STRUCT011 AND variable-binding errors are present, surface STRUCT011 first (it's the more fundamental fix — bind-errors might be tolerable with `--allow-unbound`, but bad names always need fixing first).
 
+**If STRUCT015 violations exist (layer binds variable that doesn't exist in code):**
+
+Abort unconditionally — no escape. STRUCT015 reports per-layer: "layer X binds Figma variable Y, but Y isn't in code's design system." Pulling now would generate code that references a CSS variable globals.css never declares — runtime rendering breaks. The designer's two paths forward are equally valid:
+
+1. **Rebind the layer** to a variable that DOES exist in code. Right-click the layer's property in Figma → "Apply variable" → pick a real one.
+2. **Adopt the missing variable into code** by running `/adhd:pull-tokens`. Its summary lists every missing variable so the designer chooses whether to bring it in.
+
+Read each STRUCT015 message verbatim from the preflight report (they already name the layer + variable + suggested fix) and print under a banner:
+
+```
+✗ Cannot pull — <N> layer(s) bind Figma variables that don't exist in code's design system:
+
+<paste each STRUCT015 message verbatim>
+
+Pulling now would generate code referencing CSS variables that globals.css
+never declares — runtime rendering breaks. Either rebind each layer to a
+real variable in Figma, or run /adhd:pull-tokens to add the missing
+variables to code, then re-run /adhd:pull-component.
+```
+
+**If STRUCT016 violations exist (layer binds variable with value-conflict between code and Figma):**
+
+Abort unconditionally — no escape. STRUCT016 fires per-layer when a bound variable has different resolved values on each side. Pulling renders with code's value, so the component looks different in production than in Figma. Reconcile first:
+
+```
+✗ Cannot pull — <N> layer(s) bind variables whose values differ between Figma and code:
+
+<paste each STRUCT016 message verbatim>
+
+The pulled component would render with code's values, drifting from what
+the designer sees in Figma. Pick a direction:
+  • /adhd:pull-tokens — take Figma's values, write them into code
+  • /adhd:push-tokens — send code's values back to Figma
+Reconcile first, then re-run /adhd:pull-component.
+```
+
+Priority when multiple block-classes are present: STRUCT011 first (variable names), then STRUCT015 (missing), then STRUCT016 (conflicts), then STRUCT003/004/005 (raw values). Most fundamental first — bad names break naming downstream, missing vars break rendering, conflicts cause visual drift, raw values can be escaped.
+
 ## Phase 2.7: Opportunistic variable discovery
 
 Once preflight passes (no STRUCT011, no unbound errors or escape engaged), check the lint engine's variable mismatches in `/tmp/adhd-pull-component/stdout.json`. The categorizer reports two interesting statuses for our purpose:

From eb38fed0bf20c42a14089ce731f8637e9e060389 Mon Sep 17 00:00:00 2001
From: Hugh Francis <hughfrancis89@gmail.com>
Date: Tue, 12 May 2026 17:57:33 -0400
Subject: [PATCH 66/79] lint: kill the "color/primary" false-conflict at its
 root
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Two stacked bugs were causing STRUCT016 to fire on color/primary even
though both sides resolved to the same #0a0a0a:

1. The variable-categorizer fed `strippedToken(figmaPath)` to
   inferDomain — so "color/primary" became "primary", which didn't
   match any of the `startsWith('color/')` checks. Domain came back
   "unknown" and valuesMatch fell to the strict-equality default
   branch — never reaching the per-domain color normalization. The
   normalizeColor fix from the previous commit DID handle the rgb
   object form, but never got a chance to run.

2. inferDomain was case-sensitive: "Color/primary" (capitalized
   collection — common Figma convention) also returned "unknown" for
   the same reason as #1.

Fix: pass the FULL figma path to inferDomain (lets the function see
the collection name), lowercase the input before checking, and
include "spacing/" as a synonym for the older "space/" prefix.

End-to-end: the user\'s annotation showing "code: #0a0a0a, figma:
#0a0a0a" now correctly resolves to no conflict — both forms
canonicalize to the same hex.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 .../__tests__/variable-categorizer.test.js    | 27 ++++++++++++++++
 .../lib/lint-engine/variable-categorizer.js   | 32 ++++++++++++++-----
 2 files changed, 51 insertions(+), 8 deletions(-)

diff --git a/plugins/adhd/lib/lint-engine/__tests__/variable-categorizer.test.js b/plugins/adhd/lib/lint-engine/__tests__/variable-categorizer.test.js
index 19f7140..7d9ffac 100644
--- a/plugins/adhd/lib/lint-engine/__tests__/variable-categorizer.test.js
+++ b/plugins/adhd/lib/lint-engine/__tests__/variable-categorizer.test.js
@@ -49,6 +49,33 @@ test('does not emit violations for variables that match', () => {
   assert.equal(matches.length, 0);
 });
 
+test('Figma\'s raw {r,g,b,a} object compares equal to code\'s #hex (regression for the "primary" false-conflict)', () => {
+  // The user's reactor file kept reporting STRUCT016 on color/primary:
+  // "code #0a0a0a vs figma #0a0a0a — same value." Root cause was two
+  // bugs stacked: (1) the figma side arrives as {r:0.039,g:0.039,b:0.039,a:1}
+  // (Figma's raw color form, channels 0..1), and (2) inferDomain was
+  // receiving the COLLECTION-STRIPPED token ("primary"), so it returned
+  // "unknown" instead of "color" — meaning valuesMatch dispatched to
+  // the strict-equality default branch and never normalized the rgb
+  // object to hex.
+  const violations = categorizeVariables(
+    { 'color/primary': { r: 0.039, g: 0.039, b: 0.039, a: 1 } },
+    { primitives: { '--color-primary': '#0a0a0a' }, exposure: {}, light: {}, dark: {} },
+  );
+  assert.equal(violations.length, 0);
+});
+
+test('Capitalized Figma collection names still resolve their domain ("Color/primary" → color)', () => {
+  // Designer's collection is "Color" (capital C). Pre-fix, inferDomain
+  // was case-sensitive and missed this — domain came back "unknown" and
+  // the conflict surfaced even when values matched.
+  const violations = categorizeVariables(
+    { 'Color/primary': { r: 0.039, g: 0.039, b: 0.039, a: 1 } },
+    { primitives: { '--color-primary': '#0a0a0a' }, exposure: {}, light: {}, dark: {} },
+  );
+  assert.equal(violations.length, 0);
+});
+
 test('treats hex case as semantically identical', () => {
   const violations = categorizeVariables(
     { 'Primitives/color/x': '#5E3AEE' },
diff --git a/plugins/adhd/lib/lint-engine/variable-categorizer.js b/plugins/adhd/lib/lint-engine/variable-categorizer.js
index be7a1ca..4dece12 100644
--- a/plugins/adhd/lib/lint-engine/variable-categorizer.js
+++ b/plugins/adhd/lib/lint-engine/variable-categorizer.js
@@ -3,13 +3,25 @@
 const { figmaToCssVar } = require('./name-normalizer');
 const { valuesMatch } = require('./value-normalizer');
 
-function inferDomain(token) {
-  if (token.startsWith('color/') || token.includes('/color/')) return 'color';
-  if (token.startsWith('space/') || token.includes('/space/')) return 'spacing';
-  if (token.startsWith('radius/') || token.includes('/radius/')) return 'radius';
-  if (token.startsWith('shadow/') || token.includes('/shadow/')) return 'shadow';
-  if (token.startsWith('font/') || token.includes('/font/') ||
-      token.includes('text-') || token.includes('line-height')) return 'typography';
+// Infer the Tailwind v4 domain from a full Figma variable path
+// (e.g. `Color/primary`, `Primitives/spacing/4`). Lowercased + checked
+// against the canonical domain names AND common alternates, so a
+// designer's `Color/primary` matches the same domain as `color/primary`
+// or `Primitives/color/primary`. Without lowercasing, the categorizer
+// silently returned `unknown` for capitalized collections, which then
+// bypassed the per-domain normalization in valuesMatch and produced
+// false-positive conflicts (the original "primary" case from the user's
+// reactor file).
+function inferDomain(figmaPath) {
+  if (!figmaPath) return 'unknown';
+  const lc = String(figmaPath).toLowerCase();
+  if (lc.startsWith('color/')   || lc.includes('/color/'))   return 'color';
+  if (lc.startsWith('spacing/') || lc.includes('/spacing/')) return 'spacing';
+  if (lc.startsWith('space/')   || lc.includes('/space/'))   return 'spacing';
+  if (lc.startsWith('radius/')  || lc.includes('/radius/'))  return 'radius';
+  if (lc.startsWith('shadow/')  || lc.includes('/shadow/'))  return 'shadow';
+  if (lc.startsWith('font/')    || lc.includes('/font/') ||
+      lc.includes('text-') || lc.includes('line-height')) return 'typography';
   return 'unknown';
 }
 
@@ -38,7 +50,11 @@ function isFigmaAlias(v) {
 function compareOne(figmaPath, figmaValue, theme, mode) {
   const cssVar = figmaToCssVar(figmaPath);
   const token = strippedToken(figmaPath);
-  const domain = inferDomain(token);
+  // Pass the FULL figma path (not the collection-stripped token) so
+  // inferDomain can use the collection name as a domain signal —
+  // `color/primary` matches `color`, `Primitives/spacing/4` matches
+  // `spacing` via the tier-collection branch.
+  const domain = inferDomain(figmaPath);
   const localValue = lookupLocal(theme, cssVar, mode);
 
   if (localValue === undefined || localValue === null) {

From a3218719d225da0fa00981e3140d869403ab9baa Mon Sep 17 00:00:00 2001
From: Hugh Francis <hughfrancis89@gmail.com>
Date: Tue, 12 May 2026 18:06:57 -0400
Subject: [PATCH 67/79] lint: stop the engine crashing on numeric vars +
 resolve var(--X) chains
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Two more bugs surfaced when running the lint against the user's actual
reactor extract:

1. The lint engine crashed mid-categorization on the first numeric
   Figma value it encountered (radius/sm: 6, spacing/space/0: 0,
   text-size: 14, etc.). normalizeDimension threw on the number; the
   throw bubbled out of categorizeVariables and the cli wrote a stack
   trace to stdout instead of a JSON summary. The user's last few lint
   runs were all silently aborting partway through — the "STRUCT016
   color/primary drift" output they kept seeing was stale from a prior
   completed run. Fix: accept numbers in normalizeDimension, integer →
   '<N>px' (lengths), non-integer → '<N>' (ratios — line-heights mostly).

2. The "color/primary false positive" was the alias-vs-literal compare
   path. The shadcn pattern declares `:root { --primary: #0a0a0a; }`
   then exposes it via `@theme inline { --color-primary: var(--primary); }`.
   The categorizer found `var(--primary)` in the exposure layer,
   compared it against Figma's `{r,g,b,a}` object, normalizeColor threw
   on the alias string, valuesMatch caught and returned false, conflict
   fired. The normalizeColor fix from earlier never ran because the
   THROW killed valuesMatch before normalization could happen.

   Fix: when code-side is `var(--X)` and figma-side is a literal,
   resolve the chain through primitives/exposure/light/dark (bounded
   recursion depth 8 to guard against pathological aliases), collect
   every terminal value, accept the binding as equal if ANY terminal
   value matches the figma side. Real drift still surfaces — the
   resolved values just have to disagree with figma for the conflict
   to fire.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 .../__tests__/variable-categorizer.test.js    | 39 +++++++++++++++
 .../adhd/lib/lint-engine/value-normalizer.js  | 10 +++-
 .../lib/lint-engine/variable-categorizer.js   | 47 +++++++++++++++++--
 3 files changed, 92 insertions(+), 4 deletions(-)

diff --git a/plugins/adhd/lib/lint-engine/__tests__/variable-categorizer.test.js b/plugins/adhd/lib/lint-engine/__tests__/variable-categorizer.test.js
index 7d9ffac..69e5142 100644
--- a/plugins/adhd/lib/lint-engine/__tests__/variable-categorizer.test.js
+++ b/plugins/adhd/lib/lint-engine/__tests__/variable-categorizer.test.js
@@ -65,6 +65,45 @@ test('Figma\'s raw {r,g,b,a} object compares equal to code\'s #hex (regression f
   assert.equal(violations.length, 0);
 });
 
+test('shadcn pattern: --color-primary aliases --primary in :root, figma rgb-object resolves through the alias chain', () => {
+  // Pre-fix, the categorizer found `--color-primary: var(--primary)` in
+  // the @theme inline exposure layer, compared its raw `var(--primary)`
+  // string against Figma\'s `{r,g,b,a}` object, normalizeColor threw on
+  // the alias string, valuesMatch caught and returned false, and STRUCT016
+  // fired as a "false-positive" conflict on every shadcn setup. Fix:
+  // resolve the local alias through the :root layer and compare against
+  // the literal `--primary` value.
+  const css = `
+    :root { --primary: #0a0a0a; }
+    @theme inline { --color-primary: var(--primary); }
+  `;
+  const { parseTheme } = require('../theme-parser');
+  const theme = parseTheme(css);
+  const v = categorizeVariables(
+    { 'color/primary': { r: 0.039, g: 0.039, b: 0.039, a: 1 } },
+    theme,
+  );
+  assert.equal(v.length, 0);
+});
+
+test('shadcn pattern: real value drift through an alias still surfaces as conflict', () => {
+  // Sanity check: the alias-resolution fix doesn\'t mask actual drift.
+  // If figma\'s value resolves to a different color than the alias chain
+  // points to, STRUCT016 must still fire.
+  const css = `
+    :root { --primary: #0a0a0a; }
+    @theme inline { --color-primary: var(--primary); }
+  `;
+  const { parseTheme } = require('../theme-parser');
+  const theme = parseTheme(css);
+  const v = categorizeVariables(
+    { 'color/primary': { r: 1, g: 0, b: 0, a: 1 } },  // real red, not the black alias target
+    theme,
+  );
+  assert.equal(v.length, 1);
+  assert.equal(v[0].status, 'conflict');
+});
+
 test('Capitalized Figma collection names still resolve their domain ("Color/primary" → color)', () => {
   // Designer's collection is "Color" (capital C). Pre-fix, inferDomain
   // was case-sensitive and missed this — domain came back "unknown" and
diff --git a/plugins/adhd/lib/lint-engine/value-normalizer.js b/plugins/adhd/lib/lint-engine/value-normalizer.js
index 8832b15..2a5af2c 100644
--- a/plugins/adhd/lib/lint-engine/value-normalizer.js
+++ b/plugins/adhd/lib/lint-engine/value-normalizer.js
@@ -46,8 +46,16 @@ function normalizeColor(input) {
 }
 
 function normalizeDimension(input) {
+  // The SKILL's serializer emits Figma's raw `valuesByMode` shape
+  // unchanged — for spacing / radius / line-height variables that's
+  // typically a bare number (`6` for 6px, `0` for 0px, `1.5` for a
+  // unitless line-height ratio). Accept both forms so the comparator
+  // doesn't crash mid-run on the first numeric value it encounters.
+  if (typeof input === 'number') {
+    return Number.isInteger(input) ? input + 'px' : String(input);
+  }
   if (typeof input !== 'string') {
-    throw new TypeError('normalizeDimension: expected string, got ' + typeof input);
+    throw new TypeError('normalizeDimension: expected string or number, got ' + typeof input);
   }
   const trimmed = input.trim();
   const remMatch = /^(-?[\d.]+)rem$/i.exec(trimmed);
diff --git a/plugins/adhd/lib/lint-engine/variable-categorizer.js b/plugins/adhd/lib/lint-engine/variable-categorizer.js
index 4dece12..6f5751b 100644
--- a/plugins/adhd/lib/lint-engine/variable-categorizer.js
+++ b/plugins/adhd/lib/lint-engine/variable-categorizer.js
@@ -43,6 +43,37 @@ function isLocalAlias(v) {
   return typeof v === 'string' && /^var\(--[A-Za-z0-9_-]+\)$/i.test(v.trim());
 }
 
+// Follow a code-side `var(--X)` alias through the parsed theme until we
+// reach a concrete literal (or a chain dead-end). Returns ALL possible
+// terminal values — the alias might resolve to different literals in
+// light vs dark modes; if the Figma side matches any of them we treat
+// the variables as semantically equal. Returns null when the chain
+// can't be resolved (variable not defined anywhere we know of, or
+// infinite-loop guard tripped).
+function resolveLocalAlias(value, theme, depth = 0) {
+  if (depth > 8) return null;
+  if (typeof value !== 'string') return [value];
+  const m = /^var\(\s*(--[A-Za-z0-9_-]+)\s*(?:,[^)]*)?\)$/i.exec(value.trim());
+  if (!m) return [value]; // already a literal
+  const target = m[1];
+  const candidates = [];
+  if (theme.primitives && theme.primitives[target] != null) candidates.push(theme.primitives[target]);
+  if (theme.exposure   && theme.exposure[target]   != null) candidates.push(theme.exposure[target]);
+  if (theme.light      && theme.light[target]      != null) candidates.push(theme.light[target]);
+  if (theme.dark       && theme.dark[target]       != null) candidates.push(theme.dark[target]);
+  if (candidates.length === 0) return null;
+  const out = [];
+  for (const c of candidates) {
+    const next = resolveLocalAlias(c, theme, depth + 1);
+    if (next) {
+      for (const r of next) {
+        if (!out.includes(r)) out.push(r);
+      }
+    }
+  }
+  return out.length > 0 ? out : null;
+}
+
 function isFigmaAlias(v) {
   return v != null && typeof v === 'object' && v.type === 'VARIABLE_ALIAS';
 }
@@ -70,12 +101,22 @@ function compareOne(figmaPath, figmaValue, theme, mode) {
   }
   // Both sides agree this is an alias relationship — no surface-value comparison
   // is meaningful. The primitive-level comparison catches real drift in the
-  // underlying targets. Mixed alias-vs-literal still falls through to the value
-  // comparison below (where it may produce a false-positive conflict until the
-  // SKILL emits resolved figma values).
+  // underlying targets.
   if (isLocalAlias(localValue) && isFigmaAlias(figmaValue)) {
     return null;
   }
+  // Code side is a `var(--X)` alias and Figma side is a literal. Without
+  // resolution this throws inside normalizeColor and falls back to "not
+  // equal" — false-conflict on every shadcn-style setup where
+  // `--color-primary: var(--primary)` exposes a semantic. Resolve the
+  // chain across primitives/light/dark and accept any matching mode.
+  if (isLocalAlias(localValue) && !isFigmaAlias(figmaValue)) {
+    const resolved = resolveLocalAlias(localValue, theme);
+    if (resolved && resolved.some(r => valuesMatch(figmaValue, r, domain))) {
+      return null;
+    }
+    return { token, status: 'conflict', figma: figmaValue, local: localValue, mode, domain, resolvedLocal: resolved };
+  }
   if (valuesMatch(figmaValue, localValue, domain)) {
     return null; // same, no violation
   }

From 63dabdf6c5bce8c4b0a95fc22502e6557adce39b Mon Sep 17 00:00:00 2001
From: Hugh Francis <hughfrancis89@gmail.com>
Date: Tue, 12 May 2026 18:14:11 -0400
Subject: [PATCH 68/79] pull-component: interactive STRUCT015/016 resolution
 with alias-aware writes
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Replaces the unconditional abort-on-blocking-variable-issues behavior
with per-variable AskUserQuestion prompts. STRUCT015 (missing in code)
offers two options — "Add to globals.css" or abort. STRUCT016 (value
conflict) offers three — "Take Figma's value", "Keep code's value", or
abort.

The interesting work is the write-target resolver. The shadcn pattern
declares semantic colors in :root and exposes them to Tailwind via
@theme inline, so the cssVar Figma references (--color-primary) is
just an alias re-export. Naively writing the Figma value to
--color-primary would replace the alias with a literal and break
dark-mode propagation. The resolver walks the alias chain (bounded
recursion, cycle-safe) until it reaches the literal source, then
returns set-primitive / set-semantic actions targeting the right cssVar
AND the right layer (primitives, :root light, :root dark).

Edge cases handled in tests:
  - Missing-everywhere → set-primitive at @theme
  - Simple primitive literal → set-primitive at @theme
  - shadcn exposure → light literal: write to :root light
  - Exposure → light + dark literals: conservative default to light
    only; bothModes flag writes both
  - Exposure → dark only: writes to dark
  - Two-hop and three-hop alias chains: bottoms out at the terminal
  - Alias cycles: detected, falls back to primitive write
  - Alias to undefined variable: STRUCT015-path primitive write
  - 20-hop pathological chain: depth-bounded, doesn't hang

End-to-end tests verify resolveWriteTarget → applyToCss → re-parse →
categorizer clean, for both the STRUCT015 add-missing case and the
STRUCT016 shadcn-alias-chain take-Figma case.

New CLI subcommand `resolve-actions` lets the SKILL shell out without
inlining a 60-line Node script.

Push-component variant (same prompts mirrored, but actions hit Figma
instead of globals.css) is intentionally a separate commit.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 .../__tests__/resolve-write-target.test.js    | 262 ++++++++++++++++++
 plugins/adhd/lib/pull-component/cli.js        |  18 ++
 .../pull-component/resolve-write-target.js    | 114 ++++++++
 plugins/adhd/skills/pull-component/SKILL.md   |  92 ++++--
 4 files changed, 466 insertions(+), 20 deletions(-)
 create mode 100644 plugins/adhd/lib/pull-component/__tests__/resolve-write-target.test.js
 create mode 100644 plugins/adhd/lib/pull-component/resolve-write-target.js

diff --git a/plugins/adhd/lib/pull-component/__tests__/resolve-write-target.test.js b/plugins/adhd/lib/pull-component/__tests__/resolve-write-target.test.js
new file mode 100644
index 0000000..5adeab3
--- /dev/null
+++ b/plugins/adhd/lib/pull-component/__tests__/resolve-write-target.test.js
@@ -0,0 +1,262 @@
+'use strict';
+
+const test = require('node:test');
+const assert = require('node:assert/strict');
+const { resolveWriteTarget, findDefinitionLayers, isAlias, aliasTarget } = require('../resolve-write-target');
+
+const theme = (parts) => ({
+  primitives: parts.primitives || {},
+  exposure:   parts.exposure   || {},
+  light:      parts.light      || {},
+  dark:       parts.dark       || {},
+});
+
+test('isAlias / aliasTarget recognize var() syntax', () => {
+  assert.equal(isAlias('var(--primary)'), true);
+  assert.equal(isAlias('var(--primary, #000)'), true);
+  assert.equal(isAlias('  var(--primary)  '), true);
+  assert.equal(isAlias('#0a0a0a'), false);
+  assert.equal(isAlias('0.25rem'), false);
+  assert.equal(aliasTarget('var(--primary)'), '--primary');
+  assert.equal(aliasTarget('var(--gold-500, #fallback)'), '--gold-500');
+  assert.equal(aliasTarget('#abc'), null);
+});
+
+test('findDefinitionLayers returns every layer that defines the cssVar, in cascade order', () => {
+  const t = theme({
+    primitives: { '--gold': '#c5a572' },
+    exposure:   { '--gold': 'var(--gold)' },        // unusual but possible
+    light:      { '--gold': '#c5a572' },
+    dark:       { '--gold': '#8b6f3e' },
+  });
+  const out = findDefinitionLayers('--gold', t);
+  assert.deepEqual(out.map(l => l.layer), ['primitive', 'exposure', 'light', 'dark']);
+});
+
+// ─── STRUCT015 case: variable missing from code entirely ─────────────
+
+test('missing-everywhere: writes as new @theme primitive', () => {
+  const t = theme({});
+  const actions = resolveWriteTarget('--color-gold', '#c5a572', t);
+  assert.deepEqual(actions, [
+    { kind: 'set-primitive', cssVar: '--color-gold', value: '#c5a572' },
+  ]);
+});
+
+// ─── Simple primitive cases ─────────────────────────────────────────
+
+test('primitive literal: writes directly to @theme primitives', () => {
+  const t = theme({ primitives: { '--color-gold': '#aaaaaa' } });
+  const actions = resolveWriteTarget('--color-gold', '#c5a572', t);
+  assert.deepEqual(actions, [
+    { kind: 'set-primitive', cssVar: '--color-gold', value: '#c5a572' },
+  ]);
+});
+
+// ─── Shadcn-style alias chain: --color-primary exposes --primary ────
+
+test('alias chain (exposure → light literal): writes to :root light', () => {
+  // The user\'s shadcn case. --color-primary lives only in @theme inline
+  // as `var(--primary)`. --primary is defined in :root (light). The
+  // write target must be --primary at :root, NOT --color-primary at
+  // @theme — overwriting the exposure entry would replace the alias
+  // with a literal and break dark-mode propagation.
+  const t = theme({
+    exposure: { '--color-primary': 'var(--primary)' },
+    light:    { '--primary': '#0a0a0a' },
+  });
+  const actions = resolveWriteTarget('--color-primary', '#1a1a1a', t);
+  assert.deepEqual(actions, [
+    { kind: 'set-semantic', cssVar: '--primary', mode: 'light', value: '#1a1a1a' },
+  ]);
+});
+
+test('alias chain (exposure → light + dark literals): defaults to writing light only (conservative)', () => {
+  // Figma reports a single mode value; we don\'t know what dark should
+  // be. Writing to both would silently flatten the designer\'s dark
+  // intent. Conservative default = light only; opts.bothModes overrides.
+  const t = theme({
+    exposure: { '--color-primary': 'var(--primary)' },
+    light:    { '--primary': '#0a0a0a' },
+    dark:     { '--primary': '#ededed' },
+  });
+  const actions = resolveWriteTarget('--color-primary', '#1a1a1a', t);
+  assert.deepEqual(actions, [
+    { kind: 'set-semantic', cssVar: '--primary', mode: 'light', value: '#1a1a1a' },
+  ]);
+});
+
+test('alias chain (exposure → light + dark literals) with bothModes: writes both light and dark', () => {
+  const t = theme({
+    exposure: { '--color-primary': 'var(--primary)' },
+    light:    { '--primary': '#0a0a0a' },
+    dark:     { '--primary': '#ededed' },
+  });
+  const actions = resolveWriteTarget('--color-primary', '#1a1a1a', t, { bothModes: true });
+  assert.deepEqual(actions, [
+    { kind: 'set-semantic', cssVar: '--primary', mode: 'light', value: '#1a1a1a' },
+    { kind: 'set-semantic', cssVar: '--primary', mode: 'dark', value: '#1a1a1a' },
+  ]);
+});
+
+test('alias chain (exposure → dark only): writes to :root dark', () => {
+  // Asymmetric case: variable only defined for dark mode. Write goes there.
+  const t = theme({
+    exposure: { '--color-overlay': 'var(--overlay)' },
+    dark:     { '--overlay': 'rgba(0,0,0,0.5)' },
+  });
+  const actions = resolveWriteTarget('--color-overlay', 'rgba(0,0,0,0.75)', t);
+  assert.deepEqual(actions, [
+    { kind: 'set-semantic', cssVar: '--overlay', mode: 'dark', value: 'rgba(0,0,0,0.75)' },
+  ]);
+});
+
+// ─── Multi-hop alias chains ─────────────────────────────────────────
+
+test('two-hop chain: --color-x → --x → --y (literal in primitives) writes to --y in @theme', () => {
+  const t = theme({
+    primitives: { '--y': '#abc' },
+    exposure:   { '--color-x': 'var(--x)' },
+    light:      { '--x': 'var(--y)' },
+  });
+  const actions = resolveWriteTarget('--color-x', '#def', t);
+  // --x is an alias in :root light; it forwards to --y. --y is a literal
+  // primitive. Write lands at --y in @theme.
+  assert.deepEqual(actions, [
+    { kind: 'set-primitive', cssVar: '--y', value: '#def' },
+  ]);
+});
+
+test('three-hop chain bottoms out cleanly', () => {
+  const t = theme({
+    primitives: { '--root-value': '#000' },
+    exposure:   { '--surface-on-canvas': 'var(--surface-default)' },
+    light:      { '--surface-default': 'var(--root-value)' },
+  });
+  const actions = resolveWriteTarget('--surface-on-canvas', '#111', t);
+  assert.deepEqual(actions, [
+    { kind: 'set-primitive', cssVar: '--root-value', value: '#111' },
+  ]);
+});
+
+// ─── Defensive guards: cycles, runaways, broken refs ────────────────
+
+test('alias cycle: stops gracefully, falls back to primitive write', () => {
+  const t = theme({
+    light: { '--a': 'var(--b)', '--b': 'var(--a)' },
+  });
+  const actions = resolveWriteTarget('--a', '#fff', t);
+  // No literal terminal; cycle detection lands back at writing as primitive.
+  assert.equal(actions.length, 1);
+  assert.equal(actions[0].kind, 'set-primitive');
+});
+
+test('alias to undefined variable: falls back to primitive write at the dangling cssVar', () => {
+  const t = theme({
+    exposure: { '--color-primary': 'var(--primary)' },
+    // --primary is undefined anywhere
+  });
+  const actions = resolveWriteTarget('--color-primary', '#fff', t);
+  // Chain resolves to --primary which isn\'t defined → STRUCT015 path
+  // (write as new primitive at the dangling target).
+  assert.deepEqual(actions, [
+    { kind: 'set-primitive', cssVar: '--primary', value: '#fff' },
+  ]);
+});
+
+test('depth-bounded: pathological 20-hop chain doesn\'t loop forever', () => {
+  const t = theme({
+    light: Object.fromEntries(
+      Array.from({ length: 20 }, (_, i) => [`--v${i}`, `var(--v${i + 1})`]),
+    ),
+  });
+  // No terminal — bottoms out at depth limit, falls back to primitive write
+  // at SOME var in the chain. Just confirm we don\'t hang.
+  const actions = resolveWriteTarget('--v0', '#fff', t);
+  assert.ok(actions.length > 0);
+  assert.equal(actions[0].kind, 'set-primitive');
+});
+
+// ─── Idempotent behavior ────────────────────────────────────────────
+
+test('writing the same value again still resolves to the same write target', () => {
+  const t = theme({
+    exposure: { '--color-primary': 'var(--primary)' },
+    light:    { '--primary': '#0a0a0a' },
+  });
+  const a = resolveWriteTarget('--color-primary', '#1a1a1a', t);
+  const b = resolveWriteTarget('--color-primary', '#1a1a1a', t);
+  assert.deepEqual(a, b);
+});
+
+// ─── End-to-end: resolveWriteTarget actions → applyToCss → categorizer clean
+
+test('end-to-end: shadcn alias chain — action applies to :root, categorizer sees the new value, no remaining conflict', () => {
+  // The full round-trip for the user\'s reported bug. globals.css has
+  // the shadcn semantic-via-exposure pattern. Figma reports a different
+  // primary color. resolveWriteTarget figures out where to write, then
+  // applyToCss does the actual CSS edit, then the categorizer re-runs
+  // and sees no conflict.
+  const { applyToCss } = require('../../design-system/code-writer');
+  const { categorizeVariables } = require('../../lint-engine/variable-categorizer');
+  const { parseTheme } = require('../../lint-engine/theme-parser');
+  const cssBefore = `
+    :root { --primary: #0a0a0a; }
+    @theme inline { --color-primary: var(--primary); }
+  `;
+  // Figma wants this primary to be a different color.
+  const figmaRgb = { r: 0.1, g: 0.1, b: 0.1, a: 1 };
+  const figmaHex = '#1a1a1a';
+
+  // 1. Confirm the categorizer currently surfaces a conflict.
+  const themeBefore = parseTheme(cssBefore);
+  const before = categorizeVariables({ 'color/primary': figmaRgb }, themeBefore);
+  assert.equal(before.length, 1, 'should surface a conflict before write');
+  assert.equal(before[0].status, 'conflict');
+
+  // 2. Resolve the write target and apply it.
+  const actions = resolveWriteTarget('--color-primary', figmaHex, themeBefore);
+  assert.deepEqual(actions, [
+    { kind: 'set-semantic', cssVar: '--primary', mode: 'light', value: figmaHex },
+  ]);
+  const cssAfter = applyToCss(cssBefore, actions);
+
+  // 3. The :root --primary value is now what Figma wanted.
+  assert.match(cssAfter, /:root\s*\{[^}]*--primary:\s*#1a1a1a/);
+  // The exposure layer is untouched (still aliasing --primary).
+  assert.match(cssAfter, /@theme inline\s*\{[^}]*--color-primary:\s*var\(--primary\)/);
+
+  // 4. Re-categorize against the updated theme — conflict is gone.
+  const themeAfter = parseTheme(cssAfter);
+  const after = categorizeVariables({ 'color/primary': figmaRgb }, themeAfter);
+  assert.equal(after.length, 0, 'conflict should clear after the alias-aware write');
+});
+
+test('end-to-end: STRUCT015 missing variable — applyToCss adds to @theme, then no conflict', () => {
+  const { applyToCss } = require('../../design-system/code-writer');
+  const { categorizeVariables } = require('../../lint-engine/variable-categorizer');
+  const { parseTheme } = require('../../lint-engine/theme-parser');
+  const cssBefore = `@theme { --existing: #fff; }\n:root {}\n`;
+  // Pick a value whose RGB form rounds cleanly: 199/192/153 → #c7c099.
+  const figmaRgb = { r: 199 / 255, g: 192 / 255, b: 153 / 255, a: 1 };
+  const hex = '#c7c099';
+
+  // 1. Before: variable is missing.
+  const themeBefore = parseTheme(cssBefore);
+  const before = categorizeVariables({ 'color/gold': figmaRgb }, themeBefore);
+  assert.equal(before.length, 1);
+  assert.equal(before[0].status, 'missing');
+
+  // 2. Resolve write target — variable not defined anywhere → primitive.
+  const actions = resolveWriteTarget('--color-gold', hex, themeBefore);
+  assert.deepEqual(actions, [
+    { kind: 'set-primitive', cssVar: '--color-gold', value: hex },
+  ]);
+  const cssAfter = applyToCss(cssBefore, actions);
+  assert.match(cssAfter, new RegExp(`@theme\\s*\\{[^}]*--color-gold:\\s*${hex}`));
+
+  // 3. Re-categorize: clean.
+  const themeAfter = parseTheme(cssAfter);
+  const after = categorizeVariables({ 'color/gold': figmaRgb }, themeAfter);
+  assert.equal(after.length, 0);
+});
diff --git a/plugins/adhd/lib/pull-component/cli.js b/plugins/adhd/lib/pull-component/cli.js
index 0bb180e..0f6e814 100644
--- a/plugins/adhd/lib/pull-component/cli.js
+++ b/plugins/adhd/lib/pull-component/cli.js
@@ -5,6 +5,9 @@ const fs = require('node:fs');
 const { readComponentMapping, addComponentMapping, reverseLookupPath } = require('./config-writer');
 const { computeFingerprint, relevantConfigFields } = require('./fingerprint');
 const { readComponentState, writeComponentState } = require('./config-state');
+const { resolveWriteTarget } = require('./resolve-write-target');
+const { parseTheme } = require('../lint-engine/theme-parser');
+const { figmaToCssVar } = require('../lint-engine/name-normalizer');
 
 function parseArgs(argv) {
   const args = { _: [] };
@@ -24,6 +27,7 @@ function printUsage() {
   cli.js config-reverse --config <adhd.config.ts> --figma-url <url>
   cli.js fingerprint-check --config <adhd.config.ts> --path <relative-path> --ctx <ctx.json> --vars <vars.json>
   cli.js fingerprint-write --config <adhd.config.ts> --path <relative-path> --ctx <ctx.json> --vars <vars.json>
+  cli.js resolve-actions   --globals <globals.css> --figma-path <figma-path> --value <hex-or-px> [--both-modes]
 
 fingerprint-check:
   Computes the fingerprint of the fresh Figma extract + relevant config bits
@@ -112,6 +116,20 @@ function main() {
     process.exit(0);
   }
 
+  if (cmd === 'resolve-actions') {
+    if (!args.globals || !args['figma-path'] || !args.value) {
+      console.error('Usage: resolve-actions --globals <globals.css> --figma-path <path> --value <value> [--both-modes]');
+      process.exit(2);
+    }
+    const css = fs.readFileSync(args.globals, 'utf8');
+    const theme = parseTheme(css);
+    const cssVar = figmaToCssVar(args['figma-path']);
+    const opts = 'both-modes' in args ? { bothModes: true } : {};
+    const actions = resolveWriteTarget(cssVar, args.value, theme, opts);
+    process.stdout.write(JSON.stringify({ cssVar, actions }, null, 2));
+    process.exit(0);
+  }
+
   if (cmd === 'fingerprint-write') {
     if (!args.config || !args.path || !args.ctx || !args.vars) {
       console.error('Usage: fingerprint-write --config <path> --path <rel> --ctx <ctx.json> --vars <vars.json>');
diff --git a/plugins/adhd/lib/pull-component/resolve-write-target.js b/plugins/adhd/lib/pull-component/resolve-write-target.js
new file mode 100644
index 0000000..2b646e3
--- /dev/null
+++ b/plugins/adhd/lib/pull-component/resolve-write-target.js
@@ -0,0 +1,114 @@
+'use strict';
+
+// Given a CSS variable name and a parsed theme, compute the action(s)
+// needed to make that variable resolve to a target value in globals.css.
+// Walks the alias chain until it reaches the literal source (the bottom
+// of the chain), so writes land in the layer that actually controls
+// rendering — never in the @theme inline exposure layer (which is just
+// a re-export) and never on top of an existing alias relationship.
+//
+// Returns an array of actions in the shape consumed by
+// `lib/design-system/code-writer.js`'s `applyToCss`:
+//   { kind: 'set-primitive',  cssVar, value }
+//   { kind: 'set-semantic',   cssVar, mode: 'light' | 'dark', value }
+//
+// Multiple actions can be returned when a mode-less write target
+// resolves through alias chains to BOTH :root and :root[data-theme="dark"]
+// — but only when explicitly requested via `opts.bothModes: true`. The
+// safer default (single conservative write) covers the most common
+// case where a designer picks "Take Figma's value" and Figma reports
+// just one mode: we write to light, the designer keeps control of dark.
+
+const VAR_REF_RE = /^var\(\s*(--[A-Za-z0-9_-]+)\s*(?:,[^)]*)?\)$/i;
+
+function isAlias(value) {
+  return typeof value === 'string' && VAR_REF_RE.test(value.trim());
+}
+
+function aliasTarget(value) {
+  const m = VAR_REF_RE.exec(String(value).trim());
+  return m ? m[1] : null;
+}
+
+// Find every layer where `cssVar` is defined. Order reflects which
+// layer "wins" at runtime: primitives + exposure flow into the cascade
+// first, then :root (light), then :root[data-theme="dark"] / @media
+// dark. For write-target resolution, we walk in cascade order and stop
+// at the first LITERAL value (not an alias).
+function findDefinitionLayers(cssVar, theme) {
+  const layers = [];
+  if (theme.primitives && theme.primitives[cssVar] != null) {
+    layers.push({ layer: 'primitive', value: theme.primitives[cssVar] });
+  }
+  if (theme.exposure && theme.exposure[cssVar] != null) {
+    layers.push({ layer: 'exposure', value: theme.exposure[cssVar] });
+  }
+  if (theme.light && theme.light[cssVar] != null) {
+    layers.push({ layer: 'light', value: theme.light[cssVar] });
+  }
+  if (theme.dark && theme.dark[cssVar] != null) {
+    layers.push({ layer: 'dark', value: theme.dark[cssVar] });
+  }
+  return layers;
+}
+
+// Walk the alias chain starting from `cssVar`, returning the action(s)
+// needed to put `value` at the literal source. Bounded recursion guards
+// against pathological cycles.
+function resolveWriteTarget(cssVar, value, theme, opts = {}) {
+  return walk(cssVar, value, theme, opts, 0, new Set());
+}
+
+function walk(cssVar, value, theme, opts, depth, visited) {
+  if (depth > 8 || visited.has(cssVar)) {
+    // Cycle or runaway chain — fall back to writing as a primitive.
+    return [{ kind: 'set-primitive', cssVar, value }];
+  }
+  visited.add(cssVar);
+
+  const layers = findDefinitionLayers(cssVar, theme);
+
+  // Variable not defined anywhere — it's missing from code. Land it in
+  // @theme as a new primitive. This is the STRUCT015 "Add to globals.css"
+  // case for variables Figma reports but code has never declared.
+  if (layers.length === 0) {
+    return [{ kind: 'set-primitive', cssVar, value }];
+  }
+
+  // Walk through the layers in cascade order. The first LITERAL we find
+  // is the source of truth; the first ALIAS sends us deeper. Don't mix
+  // — if primitive/exposure layers are aliases AND :root layers carry
+  // literals, the literals win at runtime so we write there.
+  const literalLayers = layers.filter(l => !isAlias(l.value));
+  if (literalLayers.length === 0) {
+    // Every defined layer is an alias — follow the first one's target.
+    // (Same target across layers is the common case; if they diverge
+    // we just take primitive > exposure > light > dark order.)
+    const next = aliasTarget(layers[0].value);
+    if (!next) {
+      // Defensive — isAlias was true but target couldn't be parsed.
+      return [{ kind: 'set-primitive', cssVar, value }];
+    }
+    return walk(next, value, theme, opts, depth + 1, visited);
+  }
+
+  // Pick a write strategy from the literal layers:
+  //  - primitive layer literal → set-primitive at this cssVar
+  //  - exposure-only literal (unusual) → treat as primitive write
+  //  - light-only literal → set-semantic light
+  //  - dark-only literal → set-semantic dark
+  //  - BOTH light + dark → conservative default: write to light only;
+  //    pass opts.bothModes to write to both.
+  const has = (layer) => literalLayers.some(l => l.layer === layer);
+  if (has('primitive') || has('exposure')) {
+    return [{ kind: 'set-primitive', cssVar, value }];
+  }
+  const actions = [];
+  if (has('light')) actions.push({ kind: 'set-semantic', cssVar, mode: 'light', value });
+  if (has('dark') && (opts.bothModes || !has('light'))) {
+    actions.push({ kind: 'set-semantic', cssVar, mode: 'dark', value });
+  }
+  return actions;
+}
+
+module.exports = { resolveWriteTarget, findDefinitionLayers, isAlias, aliasTarget };
diff --git a/plugins/adhd/skills/pull-component/SKILL.md b/plugins/adhd/skills/pull-component/SKILL.md
index 1511c31..7677784 100644
--- a/plugins/adhd/skills/pull-component/SKILL.md
+++ b/plugins/adhd/skills/pull-component/SKILL.md
@@ -212,41 +212,93 @@ If BOTH STRUCT011 AND variable-binding errors are present, surface STRUCT011 fir
 
 **If STRUCT015 violations exist (layer binds variable that doesn't exist in code):**
 
-Abort unconditionally — no escape. STRUCT015 reports per-layer: "layer X binds Figma variable Y, but Y isn't in code's design system." Pulling now would generate code that references a CSS variable globals.css never declares — runtime rendering breaks. The designer's two paths forward are equally valid:
+Walk each UNIQUE variable (multiple layers can bind the same variable — prompt once per variable, not once per layer) with `AskUserQuestion`. Each STRUCT015 entry on the lint summary has fields `figmaName`, `figmaValueNormalized` (the hex/px string derived from the Figma value — emit this from the preflight if not already present, see below), and the list of `nodeId`s that bind it.
 
-1. **Rebind the layer** to a variable that DOES exist in code. Right-click the layer's property in Figma → "Apply variable" → pick a real one.
-2. **Adopt the missing variable into code** by running `/adhd:pull-tokens`. Its summary lists every missing variable so the designer chooses whether to bring it in.
+Normalize the Figma value to a write-ready string first. Use a small inline `node -e` against `lib/lint-engine/value-normalizer.js`:
 
-Read each STRUCT015 message verbatim from the preflight report (they already name the layer + variable + suggested fix) and print under a banner:
+```bash
+node -e '
+  const fs = require("fs");
+  const { normalizeColor, normalizeDimension } = require("plugins/adhd/lib/lint-engine/value-normalizer");
+  const stdout = JSON.parse(fs.readFileSync("/tmp/adhd-pull-component/stdout.json", "utf8"));
+  const missing = (stdout.variable || []).filter(v => v.status === "missing");
+  for (const m of missing) {
+    try {
+      if (m.domain === "color") m.figmaValueNormalized = normalizeColor(m.figma);
+      else m.figmaValueNormalized = normalizeDimension(m.figma);
+    } catch { m.figmaValueNormalized = null; }
+  }
+  fs.writeFileSync("/tmp/adhd-pull-component/missing-resolved.json", JSON.stringify(missing));
+'
+```
+
+For each entry (skip those whose `figmaValueNormalized` is null — value is too complex to write automatically; surface the variable in the final abort summary instead):
+
+```
+Question: "`<figmaName>` is bound in this component but doesn't exist in code's design system. Figma resolves it to `<figmaValueNormalized>`. What do you want to do?"
+Header: "Variable missing"
+Options:
+  - "Add to globals.css (writes --<canonical>: <figmaValueNormalized>)"
+  - "Abort the pull"
+```
+
+If "Abort," stop and emit the abort message (below). If "Add," record `{ figmaName, value: figmaValueNormalized }` to a running `actions-input` array.
+
+**If STRUCT016 violations exist (layer binds variable whose value differs from code's):**
+
+Same per-unique-variable pattern. Each entry includes `figma` (raw) and `local` (resolved literal). Normalize both via the same value-normalizer step. Then:
 
 ```
-✗ Cannot pull — <N> layer(s) bind Figma variables that don't exist in code's design system:
+Question: "`<figmaName>` differs between Figma and code:\n  code:  <local-normalized>\n  figma: <figma-normalized>\nWhat do you want to do?"
+Header: "Value conflict"
+Options:
+  - "Take Figma's value (update globals.css)"
+  - "Keep code's value (component renders with code's value; Figma stays divergent)"
+  - "Abort the pull"
+```
+
+If "Abort," same path as STRUCT015 abort. If "Keep code," record nothing (pull continues with code's value — Figma drift is separate). If "Take Figma," record `{ figmaName, value: figma-normalized }` to `actions-input`.
+
+### Build + apply the write actions
+
+For each entry in `actions-input`, resolve the alias chain via the CLI to find where the write should actually land. The resolver handles the shadcn-style exposure pattern (`--color-primary: var(--primary)` in `@theme inline` → write lands at `--primary` in `:root`, not at `--color-primary` in `@theme`), avoiding the trap of overwriting an alias with a literal and breaking dark-mode propagation.
+
+```bash
+node plugins/adhd/lib/pull-component/cli.js resolve-actions \
+  --globals <globals.css path> \
+  --figma-path "<figmaName>" \
+  --value "<value>"
+```
+
+The command returns `{ cssVar, actions: [{ kind, ... }, ...] }`. Concatenate the `actions` arrays across every entry into a single `applyToCss`-shaped action list.
 
-<paste each STRUCT015 message verbatim>
+Apply via a `node -e` one-liner against `applyToCss`:
 
-Pulling now would generate code referencing CSS variables that globals.css
-never declares — runtime rendering breaks. Either rebind each layer to a
-real variable in Figma, or run /adhd:pull-tokens to add the missing
-variables to code, then re-run /adhd:pull-component.
+```bash
+node -e '
+  const fs = require("fs");
+  const { applyToCss } = require("plugins/adhd/lib/design-system/code-writer");
+  const css = fs.readFileSync("<globals.css path>", "utf8");
+  const actions = JSON.parse(fs.readFileSync("/tmp/adhd-pull-component/struct015-016-actions.json", "utf8"));
+  fs.writeFileSync("<globals.css path>", applyToCss(css, actions));
+'
 ```
 
-**If STRUCT016 violations exist (layer binds variable with value-conflict between code and Figma):**
+After writing, re-run the lint engine (cheap, no MCP call needed — same `cli.js` invocation as before) and confirm zero remaining STRUCT015 / STRUCT016 violations. If any remain (unusual — typically only happens when the resolver hit an alias cycle and fell back to a defensive write), abort with the standard message; the designer needs to look at the file by hand.
 
-Abort unconditionally — no escape. STRUCT016 fires per-layer when a bound variable has different resolved values on each side. Pulling renders with code's value, so the component looks different in production than in Figma. Reconcile first:
+### Abort message (used by all "Abort" picks)
 
 ```
-✗ Cannot pull — <N> layer(s) bind variables whose values differ between Figma and code:
+✗ Cannot pull — variable issues remain. Recap:
 
-<paste each STRUCT016 message verbatim>
+<paste each STRUCT015 + STRUCT016 message that wasn't resolved verbatim>
 
-The pulled component would render with code's values, drifting from what
-the designer sees in Figma. Pick a direction:
-  • /adhd:pull-tokens — take Figma's values, write them into code
-  • /adhd:push-tokens — send code's values back to Figma
-Reconcile first, then re-run /adhd:pull-component.
+Either resolve these in Figma (rebind layers to real variables, or
+update Figma's values) and re-run, or pick "Add to globals.css" /
+"Take Figma's value" on the per-variable prompts above.
 ```
 
-Priority when multiple block-classes are present: STRUCT011 first (variable names), then STRUCT015 (missing), then STRUCT016 (conflicts), then STRUCT003/004/005 (raw values). Most fundamental first — bad names break naming downstream, missing vars break rendering, conflicts cause visual drift, raw values can be escaped.
+Priority when multiple block-classes are present: STRUCT011 first (variable names — unconditional abort, no prompts), then STRUCT003/004/005 (raw values — `--allow-unbound` escape), then STRUCT015 + STRUCT016 (interactive prompts).
 
 ## Phase 2.7: Opportunistic variable discovery
 

From ef10c0d21e3870a520583d2e9a8557c7d5d0c67b Mon Sep 17 00:00:00 2001
From: Hugh Francis <hughfrancis89@gmail.com>
Date: Tue, 12 May 2026 18:20:38 -0400
Subject: [PATCH 69/79] push-component: interactive STRUCT015/016 resolution
 mirroring pull
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Phase 10.7 walks the same per-unique-variable AskUserQuestion flow as
/adhd:pull-component, but the action lanes differ by direction:

  STRUCT015 (missing in code):
    - Add to globals.css   → alias-aware write via resolveWriteTarget
    - Skip                 → push lands with the broken binding
    - Abort                → Phase 11's rollback path

  STRUCT016 (value conflict):
    - Take code's value    → use_figma update-variable on the Figma side
    - Take Figma's value   → globals.css write via resolveWriteTarget
    - Skip                 → both sides stay divergent
    - Abort                → rollback

The "Take code's value" path needs the Figma variable id, so push-component's
preflight extraction now mirrors /adhd:lint by emitting varidmap.json
alongside ctx.json + vars.json. push-component's preflight CLI forwards
--var-id-map to the lint engine when provided; without it, the legacy
aggregated STRUCT011 behavior holds (no STRUCT012/015/016 per-layer
violations would fire either, since they all share the bridge).

The use_figma write script handles the type-aware value conversion
(hex → {r,g,b,a} 0..1 for COLOR, dimension → px-number for FLOAT,
string passthrough otherwise). Same conversion the push-tokens
WRITE_SCRIPT does, inlined for clarity.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 .../lib/push-component/__tests__/cli.test.js  |  45 +++++++
 plugins/adhd/lib/push-component/cli.js        |  14 ++-
 plugins/adhd/skills/push-component/SKILL.md   | 114 +++++++++++++++++-
 3 files changed, 168 insertions(+), 5 deletions(-)

diff --git a/plugins/adhd/lib/push-component/__tests__/cli.test.js b/plugins/adhd/lib/push-component/__tests__/cli.test.js
index 574dede..a961c3d 100644
--- a/plugins/adhd/lib/push-component/__tests__/cli.test.js
+++ b/plugins/adhd/lib/push-component/__tests__/cli.test.js
@@ -213,3 +213,48 @@ test('preflight subcommand produces a lint report', () => {
   assert.ok(Array.isArray(parsed.structure));
   assert.ok(Array.isArray(parsed.variable));
 });
+
+test('preflight forwards --var-id-map to the lint engine (required for STRUCT015/016 per-layer)', () => {
+  // Without varidmap the lint engine can't bridge node-level
+  // boundVariables (referenced by Figma id) to the variable names it
+  // reasons about — and Phase 10.7's interactive resolution depends on
+  // those rules firing. This guard test ensures the flag survives the
+  // push-component → lint-engine subprocess hop.
+  const ctx = tmp('ctx.json', JSON.stringify({
+    id: '5:1', name: 'X', type: 'COMPONENT_SET',
+    componentPropertyDefinitions: { size: { type: 'VARIANT', defaultValue: 'sm', variantOptions: ['xs', 'sm'] } },
+    children: [
+      {
+        id: '5:2', name: 'X/size=xs', type: 'COMPONENT', variantProperties: { size: 'xs' }, layoutMode: 'VERTICAL',
+        boundVariables: { letterSpacing: { id: 'VAR:bad', type: 'VARIABLE_ALIAS' } },
+        children: [],
+      },
+      {
+        id: '5:3', name: 'X/size=sm', type: 'COMPONENT', variantProperties: { size: 'sm' }, layoutMode: 'VERTICAL',
+        children: [],
+      },
+    ],
+  }));
+  // Figma variable bound at letter-spacing is in the spacing domain — STRUCT012.
+  const vars = tmp('vars.json', JSON.stringify({ 'Spacing/4': '1rem' }));
+  const idMap = tmp('varidmap.json', JSON.stringify({ 'VAR:bad': 'Spacing/4' }));
+  const css = tmp('globals.css', '@theme {}');
+  const cfg = tmp('adhd.config.ts', 'export default { naming: "kebab-case" };');
+  const out = tmp('report.md', '');
+  const result = spawnSync('node', [
+    CLI, 'preflight',
+    '--design-context', ctx,
+    '--variable-defs', vars,
+    '--var-id-map', idMap,
+    '--globals-css', css,
+    '--config', cfg,
+    '--output', out,
+  ], { encoding: 'utf8' });
+
+  const sidecar = JSON.parse(fs.readFileSync(out.replace(/\.md$/, '.json'), 'utf8'));
+  // STRUCT012 fires per-layer for the cross-domain binding. Confirms the
+  // varidmap forwarding worked end-to-end through the spawnSync call.
+  const struct012 = sidecar.structure.filter(v => v.rule === 'STRUCT012');
+  assert.ok(struct012.length > 0, 'STRUCT012 should fire when var-id-map enables per-layer binding checks');
+  assert.equal(result.status, 1);
+});
diff --git a/plugins/adhd/lib/push-component/cli.js b/plugins/adhd/lib/push-component/cli.js
index 9c4a60c..28dcad5 100644
--- a/plugins/adhd/lib/push-component/cli.js
+++ b/plugins/adhd/lib/push-component/cli.js
@@ -33,7 +33,7 @@ function printUsage() {
   cli.js parse <component-path> --output <manifest.json> [--import-path <path>] [--max-variants <n>]
   cli.js generate-preview --manifest <manifest.json> --output <preview.tsx>
   cli.js consolidation-script --manifest <manifest.json> --captured-page-id <id> --reverse-index <ri.json> --output <script.js>
-  cli.js preflight --design-context <ctx.json> --variable-defs <vars.json> --globals-css <path> --config <path> --output <report.md>`);
+  cli.js preflight --design-context <ctx.json> --variable-defs <vars.json> --globals-css <path> --config <path> --output <report.md> [--var-id-map <path>]`);
 }
 
 function inferImportPath(componentPath) {
@@ -416,7 +416,7 @@ function main() {
     // Capture stdout (the engine's JSON summary including per-violation nodeIds)
     // instead of inheriting, so the skill can pass it to the annotation script
     // when --annotate is set. Stderr still inherits — engine warnings stay visible.
-    const result = spawnSync('node', [
+    const lintArgs = [
       lintCli,
       '--design-context', args['design-context'],
       '--variable-defs', args['variable-defs'],
@@ -425,7 +425,15 @@ function main() {
       '--target', 'PushComponent Preflight',
       '--target-url', 'about:blank',
       '--output', args.output,
-    ], { encoding: 'utf8', stdio: ['inherit', 'pipe', 'inherit'] });
+    ];
+    // Forward --var-id-map when provided — required for STRUCT011 per-layer,
+    // STRUCT012, STRUCT015, and STRUCT016 to fire. Older callers that don't
+    // pass it get the legacy aggregated emissions; newer callers (the SKILL
+    // after the fingerprint commit) always pass it.
+    if (args['var-id-map']) {
+      lintArgs.push('--var-id-map', args['var-id-map']);
+    }
+    const result = spawnSync('node', lintArgs, { encoding: 'utf8', stdio: ['inherit', 'pipe', 'inherit'] });
     // Sidecar JSON next to the markdown report.
     const sidecar = args.output.replace(/\.md$/, '.json');
     fs.writeFileSync(sidecar, result.stdout ?? '');
diff --git a/plugins/adhd/skills/push-component/SKILL.md b/plugins/adhd/skills/push-component/SKILL.md
index b1684a0..79ff652 100644
--- a/plugins/adhd/skills/push-component/SKILL.md
+++ b/plugins/adhd/skills/push-component/SKILL.md
@@ -162,15 +162,19 @@ Call `mcp__plugin_figma_figma__use_figma` with that content as the `code` parame
 
 ## Phase 10: Run preflight lint
 
-Extract the new Component Set's structural data using `mcp__plugin_figma_figma__use_figma` (similar to /adhd:lint's Phase 3 extraction).
+Extract the new Component Set's structural data using `mcp__plugin_figma_figma__use_figma`. Match /adhd:lint's Phase 3 extraction shape — including the `varIdMap` sibling that bridges Figma variable IDs to their `<collection>/<name>` form. Without it the lint engine can't run STRUCT011 per-layer / STRUCT012 / STRUCT015 / STRUCT016 (every per-layer binding rule depends on the bridge), and Phase 10.7's "Take code's value" path can't find the Figma variable id to update.
 
-Save to `/tmp/adhd-push-component/ctx.json` (the design context) and `/tmp/adhd-push-component/vars.json` (referenced variables).
+Save to:
+- `/tmp/adhd-push-component/ctx.json` (the design context)
+- `/tmp/adhd-push-component/vars.json` (resolved variable values by name)
+- `/tmp/adhd-push-component/varidmap.json` (Figma id → name)
 
 Run:
 ```bash
 node plugins/adhd/lib/push-component/cli.js preflight \
   --design-context /tmp/adhd-push-component/ctx.json \
   --variable-defs /tmp/adhd-push-component/vars.json \
+  --var-id-map /tmp/adhd-push-component/varidmap.json \
   --globals-css example/app/globals.css \
   --config adhd.config.ts \
   --output /tmp/adhd-push-component/preflight-report.md
@@ -212,6 +216,112 @@ Inputs (both paths):
 
 Phase 10.5 runs AFTER the preflight CLI exits but BEFORE Phase 11's decide-or-rollback — designers see annotations even when push aborts.
 
+## Phase 10.7: Interactive STRUCT015 / STRUCT016 resolution
+
+Only runs when preflight has STRUCT015 or STRUCT016 violations. Mirrors `/adhd:pull-component`'s Phase 2.5 resolution prompts but with the Figma direction wired in: "Take code's value" pushes to Figma, "Take Figma's value" writes to `globals.css` via the same alias-aware resolver.
+
+Skip this phase if neither STRUCT015 nor STRUCT016 fired — Phase 11's clean-preflight or generic-error flow handles the rest.
+
+### Per-variable prompts (deduplicate by figmaName)
+
+Read `/tmp/adhd-push-component/preflight-report.json`. Group STRUCT015 + STRUCT016 violations by `figmaVarName` so a variable bound by multiple layers prompts ONCE, not once per layer. Normalize each Figma value to a write-ready string using `lib/lint-engine/value-normalizer.js` (same `node -e` snippet `/adhd:pull-component` uses); skip variables whose value won't normalize (rare — surfaces them in Phase 11 instead).
+
+For each unique STRUCT015 variable:
+
+```
+Question: "`<figmaName>` is bound by this push but doesn't exist in code's design system. Figma resolves it to `<figmaValueNormalized>`. What do you want to do?"
+Header: "Variable missing"
+Options:
+  - "Add to globals.css (writes --<canonical>: <figmaValueNormalized>)"
+  - "Skip — leave the binding referencing a missing variable (component renders broken until fixed)"
+  - "Abort the push (roll back)"
+```
+
+For each unique STRUCT016 variable:
+
+```
+Question: "`<figmaName>` differs between Figma and code:\n  code:  <local-normalized>\n  figma: <figma-normalized>\nWhat do you want to do?"
+Header: "Value conflict"
+Options:
+  - "Take code's value (update Figma to match code)"
+  - "Take Figma's value (write to globals.css; alias-aware)"
+  - "Skip — leave both sides divergent"
+  - "Abort the push (roll back)"
+```
+
+Record each non-skip / non-abort choice into one of two arrays:
+- `code-side-actions`: every "Add to globals.css" and "Take Figma's value" pick. Same shape as `/adhd:pull-component`'s actions — feed into `lib/pull-component/cli.js resolve-actions` per entry to get alias-aware `set-primitive` / `set-semantic` actions, concatenate into one list.
+- `figma-side-actions`: every "Take code's value" pick. Shape: `{ figmaVarId, mode, value, valueDomain }` (need the Figma variable id; look it up by inverting `/tmp/adhd-push-component/varidmap.json` — same map the lint engine produced).
+
+If any prompt picks "Abort," skip the apply step and fall through to Phase 11's rollback path with the unresolved-violations recap.
+
+### Apply code-side actions
+
+Same as `/adhd:pull-component`: one `node -e` invocation of `applyToCss` against the concatenated `code-side-actions` list. Writes are alias-aware via `resolveWriteTarget`.
+
+### Apply Figma-side actions
+
+Substitute `__ACTIONS__` with the `figma-side-actions` JSON and call `mcp__plugin_figma_figma__use_figma` with the script below. Each action updates one variable's value for one mode. Color and float values are converted from the code-side hex / dimension form into the channel-object / px-number form Figma's API expects.
+
+```js
+const ACTIONS = __ACTIONS__;
+
+function hexToRgb(h) {
+  let c = h.replace('#', '');
+  if (c.length === 3) c = c.split('').map(x => x + x).join('');
+  const r = parseInt(c.slice(0, 2), 16) / 255;
+  const g = parseInt(c.slice(2, 4), 16) / 255;
+  const b = parseInt(c.slice(4, 6), 16) / 255;
+  const a = c.length === 8 ? parseInt(c.slice(6, 8), 16) / 255 : 1;
+  return { r, g, b, a };
+}
+
+function dimensionToPx(raw) {
+  const s = String(raw).trim();
+  const m = /^(-?\d*\.?\d+)(px|rem|em)?$/.exec(s);
+  if (!m) return Number(s);
+  const n = parseFloat(m[1]);
+  const unit = m[2] || '';
+  if (unit === 'rem' || unit === 'em') return n * 16;
+  return n;
+}
+
+const results = [];
+for (const a of ACTIONS) {
+  try {
+    const v = await figma.variables.getVariableByIdAsync(a.figmaVarId);
+    if (!v) { results.push({ ...a, status: 'skipped', reason: 'variable not found' }); continue; }
+    const col = await figma.variables.getVariableCollectionByIdAsync(v.variableCollectionId);
+    // Match the requested mode by name (case-insensitive). For mode-less
+    // (primitive) variables fall back to the collection's first mode —
+    // those collections have exactly one mode.
+    const wantMode = (a.mode || col.modes[0].name).toLowerCase();
+    const target = col.modes.find(m => m.name.toLowerCase() === wantMode) || col.modes[0];
+
+    let figmaValue;
+    if (v.resolvedType === 'COLOR') figmaValue = hexToRgb(a.value);
+    else if (v.resolvedType === 'FLOAT') figmaValue = dimensionToPx(a.value);
+    else figmaValue = a.value;
+
+    v.setValueForMode(target.modeId, figmaValue);
+    results.push({ ...a, status: 'ok' });
+  } catch (e) {
+    results.push({ ...a, status: 'error', error: String(e) });
+  }
+}
+return { results };
+```
+
+### Re-run preflight + report
+
+After both apply steps land, re-invoke `plugins/adhd/lib/push-component/cli.js preflight` (cheap — no MCP call, same inputs against the updated `globals.css` + the same Figma extract). Confirm zero remaining STRUCT015 / STRUCT016 violations. If any survive (rare — usually an alias-cycle fallback or a normalization edge case), Phase 11 handles them via its existing keep-with-errors / roll-back prompt. Otherwise fall through to Phase 11 with a clean preflight.
+
+Print a one-line summary before continuing:
+
+```
+✓ Resolved <N> variable issue(s) — <X> code-side write(s), <Y> Figma-side update(s).
+```
+
 ## Phase 11: Decide and finalize OR roll back
 
 If preflight has zero errors: print "✓ Preflight clean" plus warning summary, then proceed to Phase 12.

From f8d65cfbb7e33a6449e18f79967cd53fc73868a9 Mon Sep 17 00:00:00 2001
From: Hugh Francis <hughfrancis89@gmail.com>
Date: Tue, 12 May 2026 18:32:22 -0400
Subject: [PATCH 70/79] =?UTF-8?q?pull/push-component:=20rename=20"Skip"=20?=
 =?UTF-8?q?=E2=86=92=20"Annotate=20only=20=E2=80=94=20don't=20sync=20this?=
 =?UTF-8?q?=20variable"?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The intent of the third option was always "leave the divergence in place
and surface it via the Figma annotation," but "Skip" undersold the
behavior — designers couldn't tell from the label that the annotation
stayed visible. Renaming makes the semantics explicit so the choice is
informed.

Also makes the option set symmetrical between pull and push for the
same rule:
  STRUCT015 (missing): Add to code / Annotate only / Abort
  STRUCT016 (conflict):
    pull → Take Figma / Annotate only / Abort
    push → Take code / Take Figma / Annotate only / Abort

Pull's STRUCT016 doesn't have a "Take code's value" option because that
would mean "push code to Figma," which is /adhd:push-component's
direction. "Annotate only" replaces what was a less-clear "Keep code's
value" — same behavior (no write, annotation persists), clearer label.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 plugins/adhd/skills/pull-component/SKILL.md |  7 ++++---
 plugins/adhd/skills/push-component/SKILL.md | 10 +++++++---
 2 files changed, 11 insertions(+), 6 deletions(-)

diff --git a/plugins/adhd/skills/pull-component/SKILL.md b/plugins/adhd/skills/pull-component/SKILL.md
index 7677784..fa3bed2 100644
--- a/plugins/adhd/skills/pull-component/SKILL.md
+++ b/plugins/adhd/skills/pull-component/SKILL.md
@@ -239,10 +239,11 @@ Question: "`<figmaName>` is bound in this component but doesn't exist in code's
 Header: "Variable missing"
 Options:
   - "Add to globals.css (writes --<canonical>: <figmaValueNormalized>)"
+  - "Annotate only — don't sync this variable"
   - "Abort the pull"
 ```
 
-If "Abort," stop and emit the abort message (below). If "Add," record `{ figmaName, value: figmaValueNormalized }` to a running `actions-input` array.
+If "Abort," stop and emit the abort message (below). If "Add," record `{ figmaName, value: figmaValueNormalized }` to a running `actions-input` array. If "Annotate only," record nothing — the pull proceeds with the binding referencing a variable that doesn't exist in code; the lint annotation in Figma stays visible so the designer can fix later. (Tip: this is the right pick when the designer plans to address the missing variable in a separate `/adhd:pull-tokens` run rather than inline.)
 
 **If STRUCT016 violations exist (layer binds variable whose value differs from code's):**
 
@@ -253,11 +254,11 @@ Question: "`<figmaName>` differs between Figma and code:\n  code:  <local-normal
 Header: "Value conflict"
 Options:
   - "Take Figma's value (update globals.css)"
-  - "Keep code's value (component renders with code's value; Figma stays divergent)"
+  - "Annotate only — don't sync this variable"
   - "Abort the pull"
 ```
 
-If "Abort," same path as STRUCT015 abort. If "Keep code," record nothing (pull continues with code's value — Figma drift is separate). If "Take Figma," record `{ figmaName, value: figma-normalized }` to `actions-input`.
+If "Abort," same path as STRUCT015 abort. If "Annotate only," record nothing — the pull continues with code's value as-is and the Figma annotation stays in place so the designer can decide later (run `/adhd:pull-tokens` to take Figma's value, or `/adhd:push-tokens` to push code's value to Figma). If "Take Figma," record `{ figmaName, value: figma-normalized }` to `actions-input`.
 
 ### Build + apply the write actions
 
diff --git a/plugins/adhd/skills/push-component/SKILL.md b/plugins/adhd/skills/push-component/SKILL.md
index 79ff652..0ec36e2 100644
--- a/plugins/adhd/skills/push-component/SKILL.md
+++ b/plugins/adhd/skills/push-component/SKILL.md
@@ -233,10 +233,12 @@ Question: "`<figmaName>` is bound by this push but doesn't exist in code's desig
 Header: "Variable missing"
 Options:
   - "Add to globals.css (writes --<canonical>: <figmaValueNormalized>)"
-  - "Skip — leave the binding referencing a missing variable (component renders broken until fixed)"
+  - "Annotate only — don't sync this variable"
   - "Abort the push (roll back)"
 ```
 
+"Annotate only" finalizes the push with the binding referencing a variable that doesn't exist in code — the component will render broken until the designer addresses it. The Figma annotation stays in place to surface the issue.
+
 For each unique STRUCT016 variable:
 
 ```
@@ -245,11 +247,13 @@ Header: "Value conflict"
 Options:
   - "Take code's value (update Figma to match code)"
   - "Take Figma's value (write to globals.css; alias-aware)"
-  - "Skip — leave both sides divergent"
+  - "Annotate only — don't sync this variable"
   - "Abort the push (roll back)"
 ```
 
-Record each non-skip / non-abort choice into one of two arrays:
+"Annotate only" finalizes the push leaving both sides divergent — Figma keeps its value, code keeps its value, the lint annotation in Figma surfaces the conflict for later reconciliation (run `/adhd:pull-tokens` or `/adhd:push-tokens` when ready).
+
+Record each pick (other than "Annotate only" / "Abort") into one of two arrays:
 - `code-side-actions`: every "Add to globals.css" and "Take Figma's value" pick. Same shape as `/adhd:pull-component`'s actions — feed into `lib/pull-component/cli.js resolve-actions` per entry to get alias-aware `set-primitive` / `set-semantic` actions, concatenate into one list.
 - `figma-side-actions`: every "Take code's value" pick. Shape: `{ figmaVarId, mode, value, valueDomain }` (need the Figma variable id; look it up by inverting `/tmp/adhd-push-component/varidmap.json` — same map the lint engine produced).
 

From 645b1dd0c836be6504f4a46672b04fa9bae8cbd5 Mon Sep 17 00:00:00 2001
From: Hugh Francis <hughfrancis89@gmail.com>
Date: Tue, 12 May 2026 19:25:27 -0400
Subject: [PATCH 71/79] pull/push-component: drop --annotate flag,
 auto-annotate on abort, "Don't sync" now aborts
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

User's complaint: picking "Annotate only" on a STRUCT015 / STRUCT016
prompt let the pull/push proceed with broken state — a binding
referencing a missing variable rendered the component broken in
production, even though the designer had explicitly flagged the
violation. "Annotate only" was sold as a per-variable skip, but in
practice it shipped broken state.

Flip the semantics so the third option means what designers expect:
"Don't sync — leave the annotation in Figma and abort." Picking it on
ANY single variable aborts the whole pull/push. The lint annotation is
guaranteed to land in Figma before exit so the designer sees the
unresolved violation next time they open the file.

Side-effect: the --annotate flag is no longer needed on
pull-component / push-component (or the all-components orchestrators).
Annotation is automatic on any abort path and clearing on any success
path — single mechanic, no flag. /adhd:lint keeps --annotate because
it's read-only and the flag is its only way to write annotations
without a sync action.

Push-component Phase 11 (decide-or-rollback) collapses too. Previously
allowed "Keep with errors" as an option; now any unresolved blocking
error rolls back automatically with annotations pushed. The structured
resolution flow in Phase 10.7 is the only path forward — if the
designer doesn't resolve through the prompts, rollback is the only
safe outcome.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 README.md                                     | 22 +++--
 .../adhd/skills/pull-all-components/SKILL.md  | 13 ++-
 plugins/adhd/skills/pull-component/SKILL.md   | 93 +++++++++----------
 .../adhd/skills/push-all-components/SKILL.md  | 13 ++-
 plugins/adhd/skills/push-component/SKILL.md   | 73 +++++----------
 5 files changed, 93 insertions(+), 121 deletions(-)

diff --git a/README.md b/README.md
index 6a4e97f..22cbbe9 100644
--- a/README.md
+++ b/README.md
@@ -32,10 +32,10 @@ After install, nine slash commands are available:
 | `/adhd:lint` | `[<figma-url>] [--annotate] [--fix]` | read-only by default | Validates the Figma file (whole file or scoped) against the local design system + structure best-practices. With `--annotate`, also writes Figma annotations on each offending node in a "lint" category. With `--fix`, walks STRUCT013 Tailwind-duplicate candidates per-prompt and consolidates approved ones (rebinds bindings to the canonical Tailwind variable, then deletes the duplicate). |
 | `/adhd:push-tokens` | `[--dry-run]` | code → Figma | Pushes globals.css variables + named styles into Figma directly via the remote MCP. Runs an interactive 7-question wizard on every invocation to set per-domain push policy: push the full Tailwind palette or only your semantic colors? Push the full spacing scale or only your authored tokens? Skip opacity entirely? Route shadows through effect styles? `--dry-run` previews exactly what would be added or skipped (reflecting your wizard answers) without writing. |
 | `/adhd:pull-tokens` | `[--dry-run]` | Figma → code | Pulls Figma variables + named styles into globals.css. `--dry-run` previews without writing. |
-| `/adhd:push-component` | `<path> [--max-variants <n>] [--annotate]` | code → Figma | Pushes a React component to Figma as a structured Component Set with variant properties + variable bindings, plus a preflight lint check. `--annotate` annotates preflight violations on Figma nodes. |
-| `/adhd:push-all-components` | `[--continue-on-error] [--max-variants <n>] [--annotate]` | code → Figma | Bulk version of `push-component` — iterates over every entry in `adhd.config.ts`'s components map. Sequential, halt-on-first-failure by default. |
-| `/adhd:pull-component` | `<path \| figma-url> [--allow-unbound] [--annotate]` | Figma → code | Pulls a Figma Component Set into a React source file; updates lookup tables and union types only (function body untouched). `--annotate` annotates preflight violations on Figma nodes. Records an 8-char fingerprint + ISO `pulledAt` in `adhd.config.ts`; subsequent pulls short-circuit (no lint, no diff, no commit) when the Figma extract + pull-relevant config still hash to the same value. |
-| `/adhd:pull-all-components` | `[--continue-on-error] [--allow-unbound] [--annotate]` | Figma → code | Bulk version of `pull-component` — iterates over every entry in `adhd.config.ts`'s components map. Sequential, halt-on-first-failure by default. Components whose stored fingerprint matches the fresh Figma extract are reported as `unchanged` and skipped (no lint, no diff, no commit). |
+| `/adhd:push-component` | `<path> [--max-variants <n>]` | code → Figma | Pushes a React component to Figma as a structured Component Set with variant properties + variable bindings, plus a preflight lint check. Per-variable STRUCT015/STRUCT016 resolution prompts let you sync mismatches in either direction; annotations land automatically on any abort. |
+| `/adhd:push-all-components` | `[--continue-on-error] [--max-variants <n>]` | code → Figma | Bulk version of `push-component` — iterates over every entry in `adhd.config.ts`'s components map. Sequential, halt-on-first-failure by default. |
+| `/adhd:pull-component` | `<path \| figma-url> [--allow-unbound]` | Figma → code | Pulls a Figma Component Set into a React source file; updates lookup tables and union types only (function body untouched). Per-variable STRUCT015/STRUCT016 resolution prompts let you sync mismatches in either direction; annotations land automatically on any abort. Records an 8-char fingerprint + ISO `pulledAt` in `adhd.config.ts`; subsequent pulls short-circuit (no lint, no diff, no commit) when the Figma extract + pull-relevant config still hash to the same value. |
+| `/adhd:pull-all-components` | `[--continue-on-error] [--allow-unbound]` | Figma → code | Bulk version of `pull-component` — iterates over every entry in `adhd.config.ts`'s components map. Sequential, halt-on-first-failure by default. Components whose stored fingerprint matches the fresh Figma extract are reported as `unchanged` and skipped (no lint, no diff, no commit). |
 | `/adhd:sync-docs` | — | install | Generates a design-system docs route in your Next.js consumer app. Tokens read live from globals.css; components are statically imported from adhd.config.ts at setup time — re-run after editing the components map. Excluded from production builds by default. |
 
 Every command above drives Figma exclusively through the `figma@claude-plugins-official` plugin. `/adhd:config` checks it's installed + authenticated up front so setup errors surface where you can fix them, not mid-pipeline.
@@ -90,15 +90,17 @@ Pass any Figma URL that includes a `node-id` query parameter — `/adhd:lint` wi
 
 The scoped report covers the same rules (STRUCT001–016 + variable mismatches), just narrowed to the selected subtree. The URL must point at the file configured in `adhd.config.ts`; mismatched file keys abort with a fix-up message.
 
-### Annotate violations in Figma (`--annotate`)
+### Annotate violations in Figma
 
-By default `/adhd:lint` (and the preflight inside `/adhd:push-component` / `/adhd:pull-component`) is read-only — it echoes a markdown report to the terminal and exits. Pass `--annotate` to also push each violation to Figma as a node-bound annotation in a dedicated **"lint"** category (orange). Designers see them on the layers panel, and a re-run with `--annotate` cleans up stale "lint"-category annotations automatically (designer-authored annotations and other categories are never touched).
+`/adhd:lint` is read-only — it echoes a markdown report to the terminal and exits. Pass `--annotate` to also push each violation to Figma as a node-bound annotation in a dedicated **"lint"** category (orange). Designers see them on the layers panel, and a re-run with `--annotate` cleans up stale "lint"-category annotations automatically (designer-authored annotations and other categories are never touched).
+
+For `/adhd:push-component` and `/adhd:pull-component`, annotation is **automatic on any abort** — when the SKILL aborts due to preflight violations (including a "Don't sync" pick on the per-variable STRUCT015/STRUCT016 prompts), every blocking violation is pushed to Figma before exit. On successful runs the same annotation script clears prior-run annotations from the scope so Figma stays clean. No flag needed.
 
 ```
-/adhd:lint --annotate                                                            # whole file
-/adhd:lint https://www.figma.com/design/<KEY>?node-id=91-18 --annotate           # scoped
-/adhd:push-component app/components/avatar/index.tsx --annotate                  # preflight
-/adhd:pull-component https://www.figma.com/design/<KEY>?node-id=91-18 --annotate # preflight
+/adhd:lint --annotate                                                  # whole file (manual annotation)
+/adhd:lint https://www.figma.com/design/<KEY>?node-id=91-18 --annotate # scoped (manual annotation)
+/adhd:push-component app/components/avatar/index.tsx                   # annotates on abort
+/adhd:pull-component https://www.figma.com/design/<KEY>?node-id=91-18  # annotates on abort
 ```
 
 ### Push a component
diff --git a/plugins/adhd/skills/pull-all-components/SKILL.md b/plugins/adhd/skills/pull-all-components/SKILL.md
index 4878730..f3a5c49 100644
--- a/plugins/adhd/skills/pull-all-components/SKILL.md
+++ b/plugins/adhd/skills/pull-all-components/SKILL.md
@@ -1,7 +1,7 @@
 ---
-description: "Bulk version of /adhd:pull-component. Iterates over every entry in adhd.config.ts's `components` map and runs the full pull flow on each, sequentially. Halts on first failure by default (use --continue-on-error for best-effort + summary). Per-component interactivity (preflight blockers, --allow-unbound escape, Phase 2.7 missing-var discovery, annotate, sync-docs prompt) is preserved — each component's pull behaves exactly as if you'd invoked /adhd:pull-component manually."
+description: "Bulk version of /adhd:pull-component. Iterates over every entry in adhd.config.ts's `components` map and runs the full pull flow on each, sequentially. Halts on first failure by default (use --continue-on-error for best-effort + summary). Per-component interactivity (preflight blockers, --allow-unbound escape, per-variable STRUCT015/016 resolution, Phase 2.7 missing-var discovery, sync-docs prompt) is preserved — each component's pull behaves exactly as if you'd invoked /adhd:pull-component manually."
 disable-model-invocation: true
-argument-hint: "[--continue-on-error] [--allow-unbound] [--annotate]"
+argument-hint: "[--continue-on-error] [--allow-unbound]"
 allowed-tools: Read Write Edit Bash AskUserQuestion mcp__plugin_figma_figma__use_figma mcp__plugin_figma_figma__get_metadata
 ---
 
@@ -12,8 +12,8 @@ Bulk wrapper around `/adhd:pull-component`. Reads the components map from `adhd.
 **Why this skill exists:** for design systems with many components, pulling each one manually is repetitive. This skill saves the typing AND provides a single end-of-run summary so failures don't get buried in a long log.
 
 **What this skill DOES NOT do:**
-- Suppress per-component prompts (preflight blockers, escape questions, annotate offers). Each component's pull runs its full interactive flow.
-- Apply decisions across all components ("annotate all", "add all missing vars", etc.). Those would require a global mode and risk batch-applying choices that should be considered per-component. v2 if it proves annoying.
+- Suppress per-component prompts (preflight blockers, escape questions, per-variable STRUCT015/016 resolution). Each component's pull runs its full interactive flow.
+- Apply decisions across all components ("add all missing vars", "take Figma for everything", etc.). Those would require a global mode and risk batch-applying choices that should be considered per-component. v2 if it proves annoying.
 
 ## Phase 1: Validate config + read components list
 
@@ -89,9 +89,8 @@ For each path in the list, in order:
 
 2. Invoke the phases of `/adhd:pull-component` inline for this path. Pass through any flags the user gave to `/adhd:pull-all-components`:
    - `--allow-unbound` (per-component STRUCT003/004/005 escape)
-   - `--annotate` (per-component preflight annotation)
 
-   The per-component pull-component SKILL handles its own validation, preflight, abort/escape logic, opportunistic-variable discovery (Phase 2.7), final report, and the post-success sync-docs prompt. All of those still fire normally — `pull-all-components` doesn't interfere with their flow.
+   The per-component pull-component SKILL handles its own validation, preflight, abort/escape logic, STRUCT015/016 resolution, opportunistic-variable discovery (Phase 2.7), final report, and the post-success sync-docs prompt. Annotations land automatically on any abort — no flag forwarding needed.
 
 3. Record the outcome for this component into `/tmp/adhd-pull-all/outcomes.json` (append-only). Outcome shape:
    ```json
@@ -133,7 +132,7 @@ Append actionable next steps based on outcome:
 
 - **All succeeded:** print `Run /adhd:sync-docs to refresh the design-system docs route.` (already prompted per component but worth reminding for the whole run).
 - **Any failed:** print `To re-try just the failures: /adhd:pull-component <path>` with the actual failed paths listed.
-- **Any annotations were pushed** (i.e., `--annotate` was active): print `Annotations updated in the "lint" category in Figma.`
+- **Any abort happened during the run** (per-component pulls auto-push annotations on abort): print `Annotations were pushed to Figma for unresolved violations during this run. Check the "lint" category to see what needs fixing.`
 
 Exit code:
 - All `success`/`cancel`: exit 0.
diff --git a/plugins/adhd/skills/pull-component/SKILL.md b/plugins/adhd/skills/pull-component/SKILL.md
index fa3bed2..88d1e59 100644
--- a/plugins/adhd/skills/pull-component/SKILL.md
+++ b/plugins/adhd/skills/pull-component/SKILL.md
@@ -1,7 +1,7 @@
 ---
 description: "Pull a Figma Component Set into a React component source file. Inverse of /adhd:push-component. Updates only design-token lookup tables and union type members — function body, JSX, hooks, handlers, and imports are never modified. Reads adhd.config.ts and uses the mapping at components.<path>.figma.url. Pre-flight validates the Figma source using the same lint engine /adhd:lint uses; structural violations abort the pull."
 disable-model-invocation: true
-argument-hint: "<react-path | figma-url> [--allow-unbound] [--annotate]"
+argument-hint: "<react-path | figma-url> [--allow-unbound]"
 allowed-tools: Read Write Edit Bash AskUserQuestion mcp__plugin_figma_figma__use_figma
 ---
 
@@ -112,45 +112,31 @@ node plugins/adhd/lib/lint-engine/cli.js \
   > /tmp/adhd-pull-component/stdout.json
 ```
 
-The stdout redirect captures the engine's JSON summary for Phase 2.6's optional `--annotate` step.
+The stdout redirect captures the engine's JSON summary for later abort-time annotation (see below).
 
 Use the globals.css path from `config.cssEntry` if set, otherwise auto-detect: `example/app/globals.css` → `app/globals.css` → `src/app/globals.css`.
 
 Use `Read` on `/tmp/adhd-pull-component/preflight.md`. Four classes of violation block the pull:
 
 - **STRUCT003/004/005** — variable-binding errors (layer uses raw color, typography, or effect that isn't bound to a variable or paint style). The `--allow-unbound` escape applies here; without it, abort.
-- **STRUCT011** — variable-naming non-compliance (case violation OR Tailwind v4 domain mismatch). No escape — the designer fixes the names in Figma before the pull can proceed. Rationale: if Figma variables have non-conventional names, the pulled code's lookup tables would either reference broken names or drift from the design system. Better to fix the source than carry forward bad names into generated code.
-- **STRUCT015** — layer binds a Figma variable that doesn't exist in code's design system. No escape. Pulling would generate code referencing a CSS variable globals.css never declares — broken rendering at runtime. The designer either rebinds the layer to a variable that IS in code, or runs `/adhd:pull-tokens` to add the missing variable first.
-- **STRUCT016** — layer binds a Figma variable whose value in Figma differs from code's. No escape. Pulling would render with code's value, drifting from what the designer sees in Figma. Reconcile via `/adhd:pull-tokens` (take Figma's value) or `/adhd:push-tokens` (send code's value back to Figma), then re-run.
+- **STRUCT011** — variable-naming non-compliance (case violation OR Tailwind v4 domain mismatch). No escape — the designer fixes the names in Figma before the pull can proceed.
+- **STRUCT012** — cross-domain bindings (e.g. spacing variable bound to letter-spacing). No escape — the fix is to rebind the layer in Figma.
+- **STRUCT015** — layer binds a Figma variable that doesn't exist in code's design system. Interactive per-variable resolution (see below).
+- **STRUCT016** — layer binds a Figma variable whose value in Figma differs from code's. Interactive per-variable resolution (see below).
 
-Other rules' violations are noted for the final report but don't block.
-
-### Annotate offending nodes in Figma
-
-Two paths, both producing the same `use_figma` annotation work described in `/adhd:lint` Phase 6:
-
-**Path A — `--annotate` was passed.** Run the annotation script unconditionally.
+**Annotations land automatically on abort.** Whenever the pull aborts due to any blocking violation — including a "Don't sync" pick on a STRUCT015 / STRUCT016 prompt — every blocking violation is pushed to Figma as a "lint"-category annotation before the abort completes. No flag is needed; the annotations are the designer's record of what to fix. On successful pulls (zero unresolved blocking violations) annotations from prior runs are cleared so Figma stays clean.
 
-**Path B — `--annotate` was NOT passed, AND there are blocking violations (STRUCT003/004/005 binding errors, STRUCT011 variable-naming non-compliance, STRUCT015 variable-missing-in-code, or STRUCT016 variable-value-conflict).** Use `AskUserQuestion` to offer annotation retroactively:
-
-```
-Question: "Push these <N> preflight violation(s) to Figma as annotations before aborting? Designers can see them in the 'lint' category to fix in-context."
-Header: "Annotate?"
-Options:
-  - "Yes, annotate them in Figma"
-  - "No, skip"
-```
+Other rules' violations are noted for the final report but don't block.
 
-On "Yes": run the annotation script. On "No": skip silently.
+### Abort-time annotation helper (called from every abort path below)
 
-For Path B, skip the prompt if no violation has a `nodeId` (no actionable annotations to write).
+Whenever this SKILL aborts due to blocking violations, push every blocking violation to Figma as a "lint"-category annotation BEFORE printing the abort message and exiting. The mechanic mirrors `/adhd:lint` Phase 6:
 
-Inputs (both paths):
-- Engine stdout: `/tmp/adhd-pull-component/stdout.json`
-- Distill to `/tmp/adhd-pull-component/violations.json` using the same `node -e` snippet as lint Phase 6.
-- **`SCOPE_ROOT_ID`** — pass the target Component Set's nodeId (from Phase 2's URL extraction). This bounds the annotation script's stale-annotation cleanup to this Component Set's subtree, so a pull of UserAvatar doesn't wipe a previously-annotated STRUCT010 on an unrelated Logo Component Set elsewhere in the file.
+1. Distill violations from `/tmp/adhd-pull-component/stdout.json` to `/tmp/adhd-pull-component/violations.json` using the same `node -e` snippet as lint Phase 6 (filters to `nodeId`-bearing entries).
+2. Call `mcp__plugin_figma_figma__use_figma` with the annotation script from `/adhd:lint` Phase 6, passing `SCOPE_ROOT_ID = <target Component Set's nodeId>` so stale-annotation cleanup is bounded to this Component Set's subtree — never wipes annotations on unrelated frames.
+3. If there are zero `nodeId`-bearing violations (rare — typically only happens on whole-file scope issues), skip the annotation step silently and continue to the abort message.
 
-Either path runs BEFORE the abort/escape evaluation below, so the designer sees the annotations regardless of whether the pull continues.
+On successful pulls (no abort), the same annotation script runs with `VIOLATIONS = []` so any prior-run annotations within the scope are cleared — Figma stays clean.
 
 **If variable-binding errors exist:**
 
@@ -239,11 +225,11 @@ Question: "`<figmaName>` is bound in this component but doesn't exist in code's
 Header: "Variable missing"
 Options:
   - "Add to globals.css (writes --<canonical>: <figmaValueNormalized>)"
-  - "Annotate only — don't sync this variable"
-  - "Abort the pull"
+  - "Don't sync — leave the annotation in Figma and abort"
+  - "Abort the pull (no annotation change)"
 ```
 
-If "Abort," stop and emit the abort message (below). If "Add," record `{ figmaName, value: figmaValueNormalized }` to a running `actions-input` array. If "Annotate only," record nothing — the pull proceeds with the binding referencing a variable that doesn't exist in code; the lint annotation in Figma stays visible so the designer can fix later. (Tip: this is the right pick when the designer plans to address the missing variable in a separate `/adhd:pull-tokens` run rather than inline.)
+If "Add," record `{ figmaName, value: figmaValueNormalized }` to a running `actions-input` array and continue to the next prompt. If "Don't sync" or "Abort," set `abortIntent = true` and continue collecting picks (so subsequent prompts still get answered — the designer might still want to record decisions on the rest before the run aborts). The difference between the two abort-flavored picks: "Don't sync" guarantees annotations land (via the helper above); "Abort" leaves annotations as-is (already-on if a prior run annotated them, off otherwise).
 
 **If STRUCT016 violations exist (layer binds variable whose value differs from code's):**
 
@@ -254,13 +240,34 @@ Question: "`<figmaName>` differs between Figma and code:\n  code:  <local-normal
 Header: "Value conflict"
 Options:
   - "Take Figma's value (update globals.css)"
-  - "Annotate only — don't sync this variable"
-  - "Abort the pull"
+  - "Don't sync — leave the annotation in Figma and abort"
+  - "Abort the pull (no annotation change)"
 ```
 
-If "Abort," same path as STRUCT015 abort. If "Annotate only," record nothing — the pull continues with code's value as-is and the Figma annotation stays in place so the designer can decide later (run `/adhd:pull-tokens` to take Figma's value, or `/adhd:push-tokens` to push code's value to Figma). If "Take Figma," record `{ figmaName, value: figma-normalized }` to `actions-input`.
+If "Take Figma," record `{ figmaName, value: figma-normalized }` to `actions-input` and continue. If "Don't sync" or "Abort," set `abortIntent = true` and continue collecting picks. Same abort-flavor distinction as STRUCT015 above.
+
+### Apply OR abort
 
-### Build + apply the write actions
+**If `abortIntent === true`** (any STRUCT015 / STRUCT016 prompt got a "Don't sync" or "Abort" pick), OR **any unresolved blocking class remains** (STRUCT011 / STRUCT012 / unescaped STRUCT003/4/5):
+
+1. Call the abort-time annotation helper to push every blocking violation to Figma.
+2. Print the abort message:
+
+```
+✗ Cannot pull — variable issues remain. Recap:
+
+<paste each unresolved blocking violation message verbatim>
+
+Either resolve these in Figma (rebind layers, fix variable values, or
+rename) and re-run, or pick "Add to globals.css" / "Take Figma's
+value" on the per-variable prompts above.
+
+<annotation summary line — "Pushed N annotations to the 'lint' category in Figma." or "No nodeId-bearing violations to annotate.">
+```
+
+3. Exit 1.
+
+**Otherwise**, every STRUCT015 / STRUCT016 prompt was resolved (every pick was "Add" / "Take Figma's value"). Apply the queued writes:
 
 For each entry in `actions-input`, resolve the alias chain via the CLI to find where the write should actually land. The resolver handles the shadcn-style exposure pattern (`--color-primary: var(--primary)` in `@theme inline` → write lands at `--primary` in `:root`, not at `--color-primary` in `@theme`), avoiding the trap of overwriting an alias with a literal and breaking dark-mode propagation.
 
@@ -285,21 +292,11 @@ node -e '
 '
 ```
 
-After writing, re-run the lint engine (cheap, no MCP call needed — same `cli.js` invocation as before) and confirm zero remaining STRUCT015 / STRUCT016 violations. If any remain (unusual — typically only happens when the resolver hit an alias cycle and fell back to a defensive write), abort with the standard message; the designer needs to look at the file by hand.
+After writing, re-run the lint engine (cheap, no MCP call needed — same `cli.js` invocation as before) and confirm zero remaining STRUCT015 / STRUCT016 violations. If any remain (unusual — typically only happens when the resolver hit an alias cycle and fell back to a defensive write), fall back to the abort path above; the designer needs to look at the file by hand.
 
-### Abort message (used by all "Abort" picks)
-
-```
-✗ Cannot pull — variable issues remain. Recap:
-
-<paste each STRUCT015 + STRUCT016 message that wasn't resolved verbatim>
-
-Either resolve these in Figma (rebind layers to real variables, or
-update Figma's values) and re-run, or pick "Add to globals.css" /
-"Take Figma's value" on the per-variable prompts above.
-```
+After a successful preflight pass, call the annotation helper one more time with `VIOLATIONS = []` so any prior-run annotations are cleared from the scope — Figma reflects the new clean state.
 
-Priority when multiple block-classes are present: STRUCT011 first (variable names — unconditional abort, no prompts), then STRUCT003/004/005 (raw values — `--allow-unbound` escape), then STRUCT015 + STRUCT016 (interactive prompts).
+Priority when multiple block-classes are present: STRUCT011 / STRUCT012 first (unconditional abort), then STRUCT003/004/005 (raw values — `--allow-unbound` escape), then STRUCT015 + STRUCT016 (interactive prompts).
 
 ## Phase 2.7: Opportunistic variable discovery
 
diff --git a/plugins/adhd/skills/push-all-components/SKILL.md b/plugins/adhd/skills/push-all-components/SKILL.md
index e2c6cac..63bb287 100644
--- a/plugins/adhd/skills/push-all-components/SKILL.md
+++ b/plugins/adhd/skills/push-all-components/SKILL.md
@@ -1,7 +1,7 @@
 ---
-description: "Bulk version of /adhd:push-component. Iterates over every entry in adhd.config.ts's `components` map and runs the full push flow on each, sequentially. Halts on first failure by default (use --continue-on-error for best-effort + summary). Per-component interactivity (preview server start, capture, consolidation, preflight, --annotate prompts) is preserved — each component's push behaves exactly as if you'd invoked /adhd:push-component manually."
+description: "Bulk version of /adhd:push-component. Iterates over every entry in adhd.config.ts's `components` map and runs the full push flow on each, sequentially. Halts on first failure by default (use --continue-on-error for best-effort + summary). Per-component interactivity (preview server start, capture, consolidation, preflight, per-variable STRUCT015/016 resolution, decide-or-rollback) is preserved — each component's push behaves exactly as if you'd invoked /adhd:push-component manually."
 disable-model-invocation: true
-argument-hint: "[--continue-on-error] [--max-variants <n>] [--annotate]"
+argument-hint: "[--continue-on-error] [--max-variants <n>]"
 allowed-tools: Read Write Edit Bash AskUserQuestion mcp__plugin_figma_figma__use_figma mcp__plugin_figma_figma__generate_figma_design
 ---
 
@@ -12,8 +12,8 @@ Bulk wrapper around `/adhd:push-component`. Reads the components map from `adhd.
 **Why this skill exists:** if you've made structural changes to multiple components in code (renamed props, added variants, updated tokens) and want to push them all to Figma, this saves the typing AND keeps the Next.js dev server warm across pushes — push-component auto-starts it on the first component, and subsequent ones reuse the running instance.
 
 **What this skill DOES NOT do:**
-- Suppress per-component prompts (rollback decisions, annotate offers). Each push runs its full interactive flow.
-- Apply decisions across all components ("rollback all on any failure", "annotate all"). Per-component decisions stay per-component.
+- Suppress per-component prompts (rollback decisions, per-variable resolution). Each push runs its full interactive flow.
+- Apply decisions across all components ("rollback all on any failure", "take Figma for everything"). Per-component decisions stay per-component.
 
 ## Phase 1: Validate config + read components list
 
@@ -47,9 +47,8 @@ For each path in the list, in order:
 
 2. Invoke the phases of `/adhd:push-component` inline for this path. Pass through any flags the user gave to `/adhd:push-all-components`:
    - `--max-variants <n>` (applied uniformly to every component's variant cap)
-   - `--annotate` (per-component preflight annotation)
 
-   The per-component push-component SKILL handles its own validation, dev-server start/check, capture, consolidation, preflight, decide-or-rollback, final report, and the mapping write to `adhd.config.ts`. All of those still fire normally.
+   The per-component push-component SKILL handles its own validation, dev-server start/check, capture, consolidation, preflight, STRUCT015/016 resolution, decide-or-rollback, final report, and the mapping write to `adhd.config.ts`. Annotations land automatically on any abort — no flag forwarding needed.
 
    **Dev-server reuse:** push-component's Phase 4 only starts the server if one isn't already running. The first push in the bulk run starts it (if not already up); subsequent pushes reuse the running instance. push-component's Phase 13 (cleanup) tears down the server only when it auto-started it for that single run — in the bulk case, push-component sees the server was already running and leaves it alone. **This skill's Phase 4 (below) is responsible for the final teardown.**
 
@@ -86,7 +85,7 @@ Summary: 2 succeeded, 1 failed, 1 skipped.
 Actionable next steps:
 - **All succeeded:** `All components are now in sync with Figma. Run /adhd:sync-docs if you want to refresh the design-system docs route.`
 - **Any failed:** `To re-try just the failures: /adhd:push-component <path>`.
-- **`--annotate` was active:** `Preflight annotations updated in the "lint" category in Figma.`
+- **Any rollback happened during the run** (per-component pushes auto-push annotations on rollback): `Annotations were pushed to Figma for unresolved violations during this run. Check the "lint" category to see what needs fixing.`
 
 Exit 0 if all `success`/`cancel`, else 1.
 
diff --git a/plugins/adhd/skills/push-component/SKILL.md b/plugins/adhd/skills/push-component/SKILL.md
index 0ec36e2..a4add63 100644
--- a/plugins/adhd/skills/push-component/SKILL.md
+++ b/plugins/adhd/skills/push-component/SKILL.md
@@ -1,7 +1,7 @@
 ---
 description: "Push a React component to the configured Figma file as a structured Component Set. Reads adhd.config.ts. Parses the component's variant axes from its TypeScript prop unions, generates a temp Next.js preview route, auto-starts the dev server if needed (and tears it down after), captures via generate_figma_design, wraps the captured frames into a Component Set with variant properties, rebinds raw values to existing design-system variables, and runs the same lint engine /adhd:lint uses as a preflight check before finalizing."
 disable-model-invocation: true
-argument-hint: "<component-path> [--max-variants <n>] [--annotate]"
+argument-hint: "<component-path> [--max-variants <n>]"
 allowed-tools: Read Write Edit Bash AskUserQuestion mcp__plugin_figma_figma__use_figma mcp__plugin_figma_figma__generate_figma_design
 ---
 
@@ -182,39 +182,17 @@ node plugins/adhd/lib/push-component/cli.js preflight \
 
 Read the report. Parse out error count and warning count.
 
-The preflight CLI also writes a JSON sidecar with the engine's full structured output at `/tmp/adhd-push-component/preflight-report.json` (same path as the report, `.md` → `.json`). Phase 10.5 uses this when `--annotate` is set.
+The preflight CLI also writes a JSON sidecar with the engine's full structured output at `/tmp/adhd-push-component/preflight-report.json` (same path as the report, `.md` → `.json`). Phase 10.7 and the abort-time annotation helper both read from it.
 
-## Phase 10.5: Annotate offending nodes in Figma
+## Phase 10.5: Abort-time annotation helper
 
-Two paths into this phase, both producing the same `use_figma` annotation work described in `/adhd:lint` Phase 6:
+Not a phase the SKILL invokes top-down — a helper called by Phase 10.7 and Phase 11 whenever push aborts due to violations. Pushes every blocking violation to Figma as a "lint"-category annotation BEFORE the rollback completes, so designers see what needs fixing the next time they open the file. Same mechanic as `/adhd:lint` Phase 6:
 
-**Path A — `--annotate` was passed.** Run the annotation script unconditionally. After it returns, print:
+1. Distill `/tmp/adhd-push-component/preflight-report.json` to `/tmp/adhd-push-component/violations.json` (same `node -e` snippet as lint Phase 6 — filters to `nodeId`-bearing entries).
+2. Call `mcp__plugin_figma_figma__use_figma` with the annotation script, passing `SCOPE_ROOT_ID = <componentSetId saved in Phase 9>`. Stale-annotation cleanup is bounded to this Component Set's subtree — never wipes unrelated frames.
+3. If there are zero `nodeId`-bearing violations, skip silently.
 
-```
-✓ Annotated <updated> Figma node(s) in the "lint" category. Cleared <cleared> stale annotation(s).
-```
-
-**Path B — `--annotate` was NOT passed, AND preflight produced node-bound errors that will abort the push.** Use `AskUserQuestion` to offer it retroactively:
-
-```
-Question: "Push these <N> preflight violation(s) to Figma as annotations before aborting? Designers can see them in the 'lint' category to fix in-context."
-Header: "Annotate?"
-Options:
-  - "Yes, annotate them in Figma"
-  - "No, skip"
-```
-
-On "Yes": run the same annotation script and print the result line.
-On "No": skip silently.
-
-For Path B, skip the prompt if (a) preflight is clean (no errors blocking the push), or (b) no violation has a `nodeId`.
-
-Inputs (both paths):
-- Engine stdout: `/tmp/adhd-push-component/preflight-report.json`
-- Distill to `/tmp/adhd-push-component/violations.json` using the same `node -e` snippet as lint Phase 6.
-- **`SCOPE_ROOT_ID`** — pass the freshly-pushed Component Set's nodeId (saved in Phase 9 as `componentSetId`). This bounds the annotation script's stale-annotation cleanup to this Component Set's subtree, so a push of UserAvatar doesn't wipe a previously-annotated STRUCT010 on an unrelated Logo Component Set elsewhere in the file.
-
-Phase 10.5 runs AFTER the preflight CLI exits but BEFORE Phase 11's decide-or-rollback — designers see annotations even when push aborts.
+On successful pushes (no abort, Phase 11 takes the finalize path), the same helper runs with `VIOLATIONS = []` so any prior-run annotations are cleared and Figma reflects the new clean state.
 
 ## Phase 10.7: Interactive STRUCT015 / STRUCT016 resolution
 
@@ -233,12 +211,10 @@ Question: "`<figmaName>` is bound by this push but doesn't exist in code's desig
 Header: "Variable missing"
 Options:
   - "Add to globals.css (writes --<canonical>: <figmaValueNormalized>)"
-  - "Annotate only — don't sync this variable"
-  - "Abort the push (roll back)"
+  - "Don't sync — leave the annotation in Figma and roll back"
+  - "Roll back the push (no annotation change)"
 ```
 
-"Annotate only" finalizes the push with the binding referencing a variable that doesn't exist in code — the component will render broken until the designer addresses it. The Figma annotation stays in place to surface the issue.
-
 For each unique STRUCT016 variable:
 
 ```
@@ -247,17 +223,17 @@ Header: "Value conflict"
 Options:
   - "Take code's value (update Figma to match code)"
   - "Take Figma's value (write to globals.css; alias-aware)"
-  - "Annotate only — don't sync this variable"
-  - "Abort the push (roll back)"
+  - "Don't sync — leave the annotation in Figma and roll back"
+  - "Roll back the push (no annotation change)"
 ```
 
-"Annotate only" finalizes the push leaving both sides divergent — Figma keeps its value, code keeps its value, the lint annotation in Figma surfaces the conflict for later reconciliation (run `/adhd:pull-tokens` or `/adhd:push-tokens` when ready).
-
-Record each pick (other than "Annotate only" / "Abort") into one of two arrays:
+For each "Add" / "Take code's value" / "Take Figma's value" pick, record into one of two arrays:
 - `code-side-actions`: every "Add to globals.css" and "Take Figma's value" pick. Same shape as `/adhd:pull-component`'s actions — feed into `lib/pull-component/cli.js resolve-actions` per entry to get alias-aware `set-primitive` / `set-semantic` actions, concatenate into one list.
 - `figma-side-actions`: every "Take code's value" pick. Shape: `{ figmaVarId, mode, value, valueDomain }` (need the Figma variable id; look it up by inverting `/tmp/adhd-push-component/varidmap.json` — same map the lint engine produced).
 
-If any prompt picks "Abort," skip the apply step and fall through to Phase 11's rollback path with the unresolved-violations recap.
+For each "Don't sync" or "Roll back" pick, set `abortIntent = true` and continue collecting picks (so subsequent prompts still get answered — the designer might want to record decisions on the rest before the rollback fires). The two abort-flavored picks differ only in whether annotations get pushed: "Don't sync" guarantees they land (via the Phase 10.5 helper); "Roll back" leaves annotations as-is.
+
+If `abortIntent === true` after the prompt loop, skip the apply step and fall through to Phase 11's rollback path. The Phase 10.5 helper handles annotations for the "Don't sync" picks.
 
 ### Apply code-side actions
 
@@ -328,13 +304,16 @@ Print a one-line summary before continuing:
 
 ## Phase 11: Decide and finalize OR roll back
 
-If preflight has zero errors: print "✓ Preflight clean" plus warning summary, then proceed to Phase 12.
+Three sub-paths into this phase:
+
+1. **Preflight clean, no `abortIntent`.** Call the Phase 10.5 helper with `VIOLATIONS = []` to clear any prior-run annotations, print "✓ Preflight clean" plus the warning summary, then proceed to Phase 12.
 
-If preflight has errors: print the report. Use `AskUserQuestion`:
-- "Keep the pushed page (you can fix in Figma manually)"
-- "Roll back — delete the captured page and exit"
+2. **`abortIntent === true`** (from Phase 10.7's per-variable prompts). Call the Phase 10.5 helper to push annotations for the unresolved blocking violations (no AskUserQuestion needed — the designer already made the call). Then run the rollback script below, print "Rolled back. Annotations pushed to Figma for the unresolved violations. Fix in Figma and re-run." Exit 1.
+
+3. **Preflight has errors that didn't go through Phase 10.7's resolution loop** (e.g. STRUCT011 / STRUCT012 / unescaped STRUCT003-5). Same path as (2) — annotations land, rollback fires. No "Keep with errors" prompt; if blocking violations weren't resolvable through the structured prompts in Phase 10.7, the only safe action is rollback.
+
+The rollback script:
 
-If user picks roll back:
 ```js
 // run via use_figma
 const page = await figma.getNodeByIdAsync(PAGE_ID);
@@ -342,10 +321,6 @@ page.remove();
 return { rolledBack: true };
 ```
 
-Then print "Rolled back. No changes to Figma. Fix the issues in your component and re-run." Exit with code 1.
-
-If user picks keep, proceed to Phase 12.
-
 ## Phase 11.5: Write component mapping to adhd.config.ts
 
 Only runs on the finalize path (skip on rollback — if the user chose roll back in Phase 11, the captured page is gone and there's no mapping to write).

From 9ee8fb3b998c73af310d6a20b2447543c7d9d008 Mon Sep 17 00:00:00 2001
From: Hugh Francis <hughfrancis89@gmail.com>
Date: Tue, 12 May 2026 19:44:07 -0400
Subject: [PATCH 72/79] lint: include the synthesized Tailwind utility scale in
 default-primitives lookup
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Tailwind v4 ships `--spacing: 0.25rem` (the base multiplier) but
generates `--spacing-0`, `--spacing-1`, … `--spacing-96` at build time
via its CSS plugin — they're never present as literal entries in the
@theme block. The design-system code-parser already synthesizes these
for push-tokens / pull-tokens (so `compareDesignSystems` sees the full
scale), but the lint engine's `loadTailwindDefaultPrimitives` was only
calling `parseTheme(tailwind-defaults.css)` — which returns just the
literal entries.

Result: a canonical Figma variable like `spacing/0` got flagged as
STRUCT015 ("doesn't exist in code's design system") even though the
CSS variable IS available at runtime via Tailwind's utility class
build step. False positive that surfaced on every component using a
zero-spacing token.

Fix: lint engine's loader now also calls `synthesizeTailwindUtilityScale`
(newly exported from code-parser) and merges its output. Same view of
the default theme as push/pull-tokens; STRUCT015 fires only on
genuinely-non-canonical paths.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 plugins/adhd/lib/design-system/code-parser.js |  2 +-
 .../__tests__/variable-categorizer.test.js    | 30 +++++++++++++++++++
 plugins/adhd/lib/lint-engine/cli.js           | 15 +++++++++-
 3 files changed, 45 insertions(+), 2 deletions(-)

diff --git a/plugins/adhd/lib/design-system/code-parser.js b/plugins/adhd/lib/design-system/code-parser.js
index 9477a84..d96bffb 100644
--- a/plugins/adhd/lib/design-system/code-parser.js
+++ b/plugins/adhd/lib/design-system/code-parser.js
@@ -583,4 +583,4 @@ function parseCodeDesignSystem(css, opts = {}) {
   return { tokens: tokenList, exposure, styles };
 }
 
-module.exports = { parseCodeDesignSystem, pathFromCssVar, inferDomain };
+module.exports = { parseCodeDesignSystem, pathFromCssVar, inferDomain, synthesizeTailwindUtilityScale };
diff --git a/plugins/adhd/lib/lint-engine/__tests__/variable-categorizer.test.js b/plugins/adhd/lib/lint-engine/__tests__/variable-categorizer.test.js
index 69e5142..04dccfb 100644
--- a/plugins/adhd/lib/lint-engine/__tests__/variable-categorizer.test.js
+++ b/plugins/adhd/lib/lint-engine/__tests__/variable-categorizer.test.js
@@ -65,6 +65,36 @@ test('Figma\'s raw {r,g,b,a} object compares equal to code\'s #hex (regression f
   assert.equal(violations.length, 0);
 });
 
+test('synthesized Tailwind scale (spacing/0, radius/full, etc.) is recognized via the cli\'s default-loader, not just the @theme parser', () => {
+  // Regression for the user-reported false STRUCT015 on spacing/0:
+  // Tailwind v4 doesn\'t ship explicit `--spacing-N` variables in its
+  // @theme block — it has `--spacing: 0.25rem` and synthesizes the rest
+  // at build time. The lint engine's loadTailwindDefaultPrimitives must
+  // call synthesizeTailwindUtilityScale to mirror that, or else `spacing/0`
+  // (a perfectly canonical Tailwind path) shows up as missing-in-code.
+  //
+  // This test runs against the categorizer with a manually-built theme
+  // that mirrors what the cli's loader produces — guards the join point
+  // between the two modules.
+  const { synthesizeTailwindUtilityScale } = require('../../design-system/code-parser');
+  const primitives = {};
+  for (const t of synthesizeTailwindUtilityScale()) {
+    primitives[t.cssVar] = t.values.default.value;
+  }
+  const theme = { primitives, exposure: {}, light: {}, dark: {} };
+
+  // Canonical Tailwind paths match the synthesized scale → no violations.
+  assert.equal(categorizeVariables({ 'spacing/0': 0 }, theme).length, 0);
+  assert.equal(categorizeVariables({ 'spacing/4': 16 }, theme).length, 0);
+  assert.equal(categorizeVariables({ 'radius/full': '9999px' }, theme).length, 0);
+
+  // Non-canonical paths still flag as missing (correct — `spacing/space/0`
+  // isn\'t a Tailwind path; the designer needs to rename).
+  const v = categorizeVariables({ 'spacing/space/0': 0 }, theme);
+  assert.equal(v.length, 1);
+  assert.equal(v[0].status, 'missing');
+});
+
 test('shadcn pattern: --color-primary aliases --primary in :root, figma rgb-object resolves through the alias chain', () => {
   // Pre-fix, the categorizer found `--color-primary: var(--primary)` in
   // the @theme inline exposure layer, compared its raw `var(--primary)`
diff --git a/plugins/adhd/lib/lint-engine/cli.js b/plugins/adhd/lib/lint-engine/cli.js
index 06317d8..75b265a 100644
--- a/plugins/adhd/lib/lint-engine/cli.js
+++ b/plugins/adhd/lib/lint-engine/cli.js
@@ -20,6 +20,7 @@
 const fs = require('node:fs');
 const path = require('node:path');
 const { parseTheme } = require('./theme-parser');
+const { synthesizeTailwindUtilityScale } = require('../design-system/code-parser');
 
 // Tailwind v4 ships a full default @theme: --color-white, --color-black,
 // --color-red-500, --spacing, the --text-* / --leading-* scales, etc.
@@ -44,7 +45,19 @@ function loadTailwindDefaultPrimitives() {
   const normalized = css
     .replace(/@theme\s+default\s+inline\s*\{/g, '@theme inline {')
     .replace(/@theme\s+default\s*\{/g, '@theme {');
-  return parseTheme(normalized).primitives;
+  const parsed = parseTheme(normalized).primitives;
+  // Tailwind v4 doesn't ship explicit `--spacing-N` / `--radius-{none,full}`
+  // / `--opacity-N` variables in the @theme block — most utility classes
+  // derive from `--spacing` at build time (`p-4` → `calc(var(--spacing) * 4)`).
+  // The design-system code-parser synthesizes these for push/pull-tokens; the
+  // lint engine needs the same view or it falsely flags `spacing/0`,
+  // `radius/full`, `opacity-50`, etc. as missing from code.
+  for (const t of synthesizeTailwindUtilityScale()) {
+    if (!(t.cssVar in parsed)) {
+      parsed[t.cssVar] = t.values.default.value;
+    }
+  }
+  return parsed;
 }
 const { categorizeVariables } = require('./variable-categorizer');
 const { checkStructure } = require('./structure-checker');

From 17ae95d3b2208f702022f400bf935ed3efd1f829 Mon Sep 17 00:00:00 2001
From: Hugh Francis <hughfrancis89@gmail.com>
Date: Tue, 12 May 2026 20:11:16 -0400
Subject: [PATCH 73/79] pull/push-component: "Auto-fix" option + explicit "Add
 as semantic" labeling
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The STRUCT015 resolution flow now offers a fourth option when the
Figma value strictly equals a Tailwind canonical: rebind the layers to
the canonical variable in Figma. Designer was hitting the user-reported
case (Font-Size/Body = 14 → matches --text-sm = 14px) and the only
options were "Add the non-canonical name to code" or "Abort." Auto-fix
is now the recommended path for those: rename happens in Figma, code
stays clean, no visual change because the values are identical.

For variables whose Figma path looks semantic (brand, accent, surface,
background, primary, etc.), the "Add to globals.css" label flips to
"Add as semantic variable (recommended for brand / accent / surface
tokens — canonical match is coincidence)." Brand colors that happen
to match a Tailwind palette entry stay branded — the matcher reports
the match but the looksSemantic flag steers the prompt away from
auto-fix.

The matcher (lib/lint-engine/canonical-matcher.js) does:
  - Strict-equality value matching after normalization (hex / rgb /
    oklch all canonicalize through a single pipeline; px/rem/em get
    common-unit reduction)
  - Typography family disambiguation: a "Font-Size/Body" path only
    matches --text-* candidates, never --leading-* even when the px
    value overlaps
  - Returns null when ambiguous (multiple canonicals in the same
    family share the value)

Required side-fixes the matcher exposed:
  - normalizeColor now handles oklch() input via the existing
    design-system/oklch helper. Without this every Tailwind v4 color
    (which ships as oklch) failed cross-form comparison.
  - variable-categorizer's inferDomain now recognizes the
    "typography/" collection prefix the user actually uses, in
    addition to the "font/" / "text-" / "line-height" heuristics it
    had before.

The Figma rebind script mirrors STRUCT013 --fix: find the source
variable, find or create the canonical, copy values per mode (mapped
by mode-name), walk every layer rebinding source→canonical for both
scalar bindings and per-paint fills/strokes, then remove the source.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 .../__tests__/canonical-matcher.test.js       | 154 +++++++++++++++
 .../lib/lint-engine/__tests__/cli.test.js     |  57 ++++++
 .../adhd/lib/lint-engine/binding-checker.js   |  26 ++-
 .../adhd/lib/lint-engine/canonical-matcher.js | 181 ++++++++++++++++++
 plugins/adhd/lib/lint-engine/cli.js           |  22 ++-
 .../adhd/lib/lint-engine/value-normalizer.js  |  13 ++
 .../lib/lint-engine/variable-categorizer.js   |   1 +
 plugins/adhd/skills/pull-component/SKILL.md   | 108 ++++++++++-
 plugins/adhd/skills/push-component/SKILL.md   |  11 +-
 9 files changed, 558 insertions(+), 15 deletions(-)
 create mode 100644 plugins/adhd/lib/lint-engine/__tests__/canonical-matcher.test.js
 create mode 100644 plugins/adhd/lib/lint-engine/canonical-matcher.js

diff --git a/plugins/adhd/lib/lint-engine/__tests__/canonical-matcher.test.js b/plugins/adhd/lib/lint-engine/__tests__/canonical-matcher.test.js
new file mode 100644
index 0000000..0668749
--- /dev/null
+++ b/plugins/adhd/lib/lint-engine/__tests__/canonical-matcher.test.js
@@ -0,0 +1,154 @@
+'use strict';
+
+const test = require('node:test');
+const assert = require('node:assert/strict');
+const { findCanonicalForValue, looksSemantic, typographyFamily } = require('../canonical-matcher');
+const { synthesizeTailwindUtilityScale } = require('../../design-system/code-parser');
+
+// Build a realistic primitives map — Tailwind defaults + the synthesized
+// utility scale, mirroring what loadTailwindDefaultPrimitives produces.
+function buildPrimitives() {
+  const out = {
+    '--color-red-500':   '#ef4444',
+    '--color-zinc-500':  '#71717a',
+    '--color-white':     '#fff',
+    '--text-xs':         '0.75rem',
+    '--text-sm':         '0.875rem',
+    '--text-base':       '1rem',
+    '--text-lg':         '1.125rem',
+    '--text-2xl':        '1.5rem',
+    '--leading-5':       '1.25rem',
+    '--leading-6':       '1.5rem',
+    '--leading-7':       '1.75rem',
+    '--tracking-tight':  '-0.025em',
+    '--tracking-normal': '0em',
+    '--radius':          '0.25rem',
+  };
+  for (const t of synthesizeTailwindUtilityScale()) {
+    if (!(t.cssVar in out)) out[t.cssVar] = t.values.default.value;
+  }
+  return out;
+}
+
+// ─── Strict value matching ──────────────────────────────────────────
+
+test('font-size 14 (number) matches Tailwind --text-sm (0.875rem = 14px)', () => {
+  // The user\'s "Font-Size/Body = 14" case from the screenshot. After
+  // normalizeDimension, both reduce to 14px. Auto-fix candidate.
+  const p = buildPrimitives();
+  const out = findCanonicalForValue('typography/Font-Size/Body', 14, p);
+  assert.equal(out, '--text-sm');
+});
+
+test('line-height 28 matches --leading-7 (1.75rem = 28px)', () => {
+  // The user\'s "Line-Height/Line Height 28" case. Family disambiguator
+  // picks --leading-7 because the figma path mentions "Line-Height,"
+  // which maps to the leading family.
+  const p = buildPrimitives();
+  const out = findCanonicalForValue('typography/Line-Height/Line Height 28', 28, p);
+  assert.equal(out, '--leading-7');
+});
+
+test('color hex matches identical Tailwind palette entry', () => {
+  const p = buildPrimitives();
+  const out = findCanonicalForValue('color/red', '#ef4444', p);
+  assert.equal(out, '--color-red-500');
+});
+
+test('color rgb-object (Figma\'s raw form) matches palette entry via normalization', () => {
+  const p = buildPrimitives();
+  // #ef4444 = rgb(239, 68, 68) = (0.937..., 0.267..., 0.267..., 1)
+  const out = findCanonicalForValue('color/red', { r: 239 / 255, g: 68 / 255, b: 68 / 255, a: 1 }, p);
+  assert.equal(out, '--color-red-500');
+});
+
+test('spacing 16 (number, 16px) matches --spacing-4 (synthesized 1rem = 16px)', () => {
+  const p = buildPrimitives();
+  const out = findCanonicalForValue('spacing/4', 16, p);
+  assert.equal(out, '--spacing-4');
+});
+
+// ─── No match cases ──────────────────────────────────────────────────
+
+test('value with no Tailwind match returns null', () => {
+  const p = buildPrimitives();
+  // Reactor's gold color isn\'t in any Tailwind default.
+  const out = findCanonicalForValue('color/gold', '#c5a572', p);
+  assert.equal(out, null);
+});
+
+test('semantic name with coincidental match still returns the canonical (matcher is name-agnostic; SKILL decides what to surface)', () => {
+  // The matcher returns the match — the SKILL\'s prompt-builder uses
+  // `looksSemantic` separately to label the "Add as semantic" option
+  // prominently. Designer decides; matcher just reports.
+  const p = buildPrimitives();
+  const out = findCanonicalForValue('color/brand', '#ef4444', p);
+  assert.equal(out, '--color-red-500');
+});
+
+test('null / undefined / unparseable values return null (no crash)', () => {
+  const p = buildPrimitives();
+  assert.equal(findCanonicalForValue('x/y', null, p), null);
+  assert.equal(findCanonicalForValue('x/y', undefined, p), null);
+  assert.equal(findCanonicalForValue('x/y', { wrong: 'shape' }, p), null);
+});
+
+test('empty primitives map returns null safely', () => {
+  assert.equal(findCanonicalForValue('color/red', '#ef4444', {}), null);
+  assert.equal(findCanonicalForValue('color/red', '#ef4444', null), null);
+});
+
+// ─── Family disambiguation in typography ────────────────────────────
+
+test('typography family disambiguator: font-size path skips leading candidates with same value', () => {
+  // 16px is BOTH text-base AND leading-6 in Tailwind. Without family
+  // disambiguation, the matcher would return whichever came first in
+  // iteration order. Family hint pins it to the right family.
+  const p = buildPrimitives();
+  const fontSizeOut = findCanonicalForValue('typography/Font-Size/Body', 16, p);
+  assert.equal(fontSizeOut, '--text-base');
+  const leadingOut = findCanonicalForValue('typography/Line-Height/Normal', 24, p);
+  assert.equal(leadingOut, '--leading-6');
+});
+
+test('typographyFamily picks up "Font-Size", "Line-Height", "Tracking", etc.', () => {
+  assert.equal(typographyFamily('typography/Font-Size/Body'), 'text');
+  assert.equal(typographyFamily('typography/Line-Height/Line Height 28'), 'leading');
+  assert.equal(typographyFamily('Type + Effects/Letter Space 0'), 'tracking');
+  assert.equal(typographyFamily('Font-Weight/Bold'), 'font-weight');
+  assert.equal(typographyFamily('font-family/Inter'), 'font');
+  assert.equal(typographyFamily('text/sm'), 'text');
+});
+
+// ─── Semantic-name detector ──────────────────────────────────────────
+
+test('looksSemantic: recognizes brand / accent / surface / etc.', () => {
+  assert.equal(looksSemantic('color/brand'), true);
+  assert.equal(looksSemantic('color/accent'), true);
+  assert.equal(looksSemantic('color/surface'), true);
+  assert.equal(looksSemantic('color/background'), true);
+  assert.equal(looksSemantic('color/foreground'), true);
+  assert.equal(looksSemantic('color/primary'), true);
+  assert.equal(looksSemantic('color/success'), true);
+  assert.equal(looksSemantic('color/destructive'), true);
+  // Tier-collection variants.
+  assert.equal(looksSemantic('Semantic/brand/surface'), true);
+});
+
+test('looksSemantic: Tailwind canonical names are NOT marked semantic', () => {
+  assert.equal(looksSemantic('color/red-500'), false);
+  assert.equal(looksSemantic('color/zinc-500'), false);
+  assert.equal(looksSemantic('text/sm'), false);
+  assert.equal(looksSemantic('spacing/4'), false);
+  assert.equal(looksSemantic('radius/full'), false);
+  // The user\'s non-canonical-but-not-semantic case.
+  assert.equal(looksSemantic('typography/Font-Size/Body'), false);
+});
+
+test('looksSemantic: edge cases (null, empty, single-segment) handled safely', () => {
+  assert.equal(looksSemantic(null), false);
+  assert.equal(looksSemantic(''), false);
+  // Single-segment semantic name (no collection prefix at all).
+  assert.equal(looksSemantic('brand'), true);
+  assert.equal(looksSemantic('red-500'), false);
+});
diff --git a/plugins/adhd/lib/lint-engine/__tests__/cli.test.js b/plugins/adhd/lib/lint-engine/__tests__/cli.test.js
index 42ca85c..32db6d0 100644
--- a/plugins/adhd/lib/lint-engine/__tests__/cli.test.js
+++ b/plugins/adhd/lib/lint-engine/__tests__/cli.test.js
@@ -454,6 +454,63 @@ test('STRUCT013: surfaces Figma variables that duplicate Tailwind defaults (stri
   assert.match(v.message, /\/adhd:lint --fix/);
 });
 
+test('STRUCT015: violation carries canonicalCandidate + looksSemantic when a Tailwind canonical matches the value', () => {
+  // The user-driven "auto-fix" pathway: when a missing variable\'s
+  // value matches an existing Tailwind canonical, surface that
+  // canonical on the violation so the SKILL can offer "Rebind to
+  // <canonical>" as a fourth option. Semantic-named variables (brand,
+  // accent, etc.) get a looksSemantic=true flag so the SKILL emphasizes
+  // the "Add as semantic" option for those, even when a coincidental
+  // value match exists.
+  const varDefs = tmp('vars.json', {
+    // Non-canonical name, value matches Tailwind --text-sm (0.875rem = 14px).
+    'typography/Font-Size/Body': 14,
+    // Semantic name, value matches Tailwind --color-white (literal #fff).
+    // Picked --color-white because it ships as a plain hex in the defaults;
+    // most Tailwind v4 colors ship as oklch() which converts to v4\'s
+    // redesigned palette, not the legacy hex values designers might type.
+    'color/brand': '#ffffff',
+  });
+  const idMap = tmp('varidmap.json', {
+    'VAR:fontBody': 'typography/Font-Size/Body',
+    'VAR:brand':    'color/brand',
+  });
+  const ctx = tmp('ctx.json', {
+    id: '5:1', name: 'Card', type: 'FRAME', layoutMode: 'VERTICAL',
+    fills: [{ type: 'SOLID', boundVariables: { color: { id: 'VAR:brand' } } }],
+    children: [
+      { id: '5:2', name: 'T', type: 'TEXT', boundVariables: { fontSize: { id: 'VAR:fontBody' } } },
+    ],
+  });
+  const cssPath = tmp('globals.css', `@theme {} :root {} :root[data-theme="dark"] {}`);
+  const configPath = tmp('adhd.config.ts', `export default { naming: 'kebab-case' };`);
+  const reportPath = path.join(os.tmpdir(), 'adhd-report-' + Date.now() + '.md');
+
+  const result = spawnSync('node', [
+    CLI, '--variable-defs', varDefs, '--var-id-map', idMap, '--design-context', ctx,
+    '--globals-css', cssPath, '--config', configPath, '--target', 'Card',
+    '--target-url', 'https://figma.com/design/abc?node-id=5-1', '--output', reportPath,
+  ], { encoding: 'utf8' });
+
+  const summary = JSON.parse(result.stdout);
+  const struct015 = summary.structure.filter(v => v.rule === 'STRUCT015');
+  // One per layer × one variable each = 2 STRUCT015.
+  assert.equal(struct015.length, 2);
+
+  const byVar = Object.fromEntries(struct015.map(v => [v.message.match(/binds "([^"]+)"/)[1], v]));
+  // Font-Size/Body has a canonical match (--text-sm), NOT semantic.
+  const body = byVar['typography/Font-Size/Body'];
+  assert.equal(body.canonicalCandidate, '--text-sm');
+  assert.notEqual(body.looksSemantic, true);
+  // color/brand has a value-match (--color-white) AND looks semantic.
+  // Matcher returns the match; SKILL uses looksSemantic to emphasize the
+  // "Add as semantic" option in the prompt — so a brand color that
+  // happens to be white doesn't get accidentally rebound to `--color-white`.
+  const brand = byVar['color/brand'];
+  assert.equal(brand.canonicalCandidate, '--color-white');
+  assert.equal(brand.looksSemantic, true);
+});
+
 test('STRUCT015 + STRUCT016: per-layer errors when a layer binds a missing/conflicting Figma variable', () => {
   // The user's main complaint: a component binds Figma variables like
   // "Font-Size/Body" that don't exist in code, but lint reported
diff --git a/plugins/adhd/lib/lint-engine/binding-checker.js b/plugins/adhd/lib/lint-engine/binding-checker.js
index 9d82128..9b8e99e 100644
--- a/plugins/adhd/lib/lint-engine/binding-checker.js
+++ b/plugins/adhd/lib/lint-engine/binding-checker.js
@@ -156,19 +156,32 @@ function checkBindings(rootNode, opts) {
   // Callers build these from the variable-categorizer's output.
   const missingVarNames = opts.missingVarNames instanceof Set ? opts.missingVarNames : new Set(opts.missingVarNames || []);
   const conflicts = opts.conflictsByName || {};
+  // Per-missing-variable metadata — { canonicalCandidate, looksSemantic,
+  // figmaValue } keyed by the categorizer's collection-stripped token AND
+  // (after cli.js's pre-expansion) the full `<collection>/<name>` form.
+  // Used to attach auto-fix info to STRUCT015 violations so the SKILL
+  // prompts can surface the right options per variable.
+  const missingMeta = opts.missingVarMeta || {};
   const fileKey = opts.fileKey;
 
   walk(rootNode, '', (node, nodePath) => {
     const seen = new Set();
-    const push = (rule, severity, varName, message) => {
+    const push = (rule, severity, varName, message, meta) => {
       const key = rule + '::' + varName;
       if (seen.has(key)) return;
       seen.add(key);
-      out.push({
+      const entry = {
         rule, severity,
         nodeId: node.id, nodePath, message,
         deepLink: deepLink(fileKey, node.id),
-      });
+      };
+      // Optional auto-fix metadata — surfaces in the JSON sidecar so
+      // the SKILL can build per-variable resolution prompts that
+      // include the canonical-rebind option when one exists.
+      if (meta && meta.canonicalCandidate) entry.canonicalCandidate = meta.canonicalCandidate;
+      if (meta && meta.looksSemantic) entry.looksSemantic = true;
+      if (meta && meta.figmaValue !== undefined) entry.figmaValueRaw = meta.figmaValue;
+      out.push(entry);
     };
 
     const handleBinding = (prop, alias) => {
@@ -196,10 +209,15 @@ function checkBindings(rootNode, opts) {
       }
 
       if (missingVarNames.has(varName)) {
+        // Look up the per-variable meta the cli built — find the entry
+        // whose key matches by collection-stripped form OR by full name.
+        const stripped = varName.includes('/') ? varName.split('/').slice(1).join('/') : varName;
+        const meta = missingMeta[varName] || missingMeta[stripped] || null;
         push('STRUCT015', 'error', varName,
           `Layer binds "${varName}" (to ${prop}), but that variable doesn't exist in code's design system. ` +
           `Pulling this component would generate code referencing a CSS variable globals.css never declares — rendering breaks at runtime.\n\n` +
-          `Fix in Figma: rebind the layer to a variable that IS in code, OR run /adhd:pull-tokens first to add this variable to globals.css. The pull-tokens flow shows the missing variable in its summary so you can choose whether to take it on.`);
+          `Fix in Figma: rebind the layer to a variable that IS in code, OR run /adhd:pull-tokens first to add this variable to globals.css. The pull-tokens flow shows the missing variable in its summary so you can choose whether to take it on.`,
+          meta);
       }
 
       const conflict = conflicts[varName];
diff --git a/plugins/adhd/lib/lint-engine/canonical-matcher.js b/plugins/adhd/lib/lint-engine/canonical-matcher.js
new file mode 100644
index 0000000..87f46c7
--- /dev/null
+++ b/plugins/adhd/lib/lint-engine/canonical-matcher.js
@@ -0,0 +1,181 @@
+'use strict';
+
+// Given a Figma variable value + its inferred domain, find the canonical
+// Tailwind CSS variable (if any) whose value matches strictly. Powers
+// the "Auto-fix" option in pull-component / push-component's STRUCT015
+// resolution flow.
+//
+// Strict equality only: same normalized hex for colors, same px-after-rem
+// conversion for dimensions, same string after trim/lowercase for
+// everything else. If multiple canonicals match the same value (e.g.
+// --leading-3 and --text-xs--line-height both = 12px), return only the
+// first one inside the same sub-domain — the caller falls back to
+// "Add as-is" when there's ambiguity worth surfacing manually.
+//
+// Names that LOOK semantic (brand/surface/accent/etc.) are surfaced to
+// the SKILL via `looksSemantic` so the prompt's "Add as semantic" label
+// stays prominent — auto-fix is only safe for variables that
+// accidentally took a non-canonical name when a canonical existed.
+
+const { normalizeColor, normalizeDimension } = require('./value-normalizer');
+
+// Heuristic: names whose first segment after the collection prefix looks
+// like a semantic role (brand, accent, surface, etc.) rather than a
+// Tailwind scale step (`zinc-500`, `text-sm`, `radius-md`). Used to
+// label the "Add as semantic" option more prominently in the prompt;
+// it does NOT block the auto-fix option from appearing — designers can
+// still pick auto-fix if they explicitly want it.
+const SEMANTIC_LEADING = /^(brand|accent|surface|background|foreground|primary|secondary|tertiary|success|warning|error|danger|info|muted|destructive|popover|card|sidebar|chart|on-|inverse|highlight|focus|disabled|hover|active|selected|placeholder|outline|ring|shadow-color)\b/i;
+
+function looksSemantic(figmaPath) {
+  if (!figmaPath || typeof figmaPath !== 'string') return false;
+  const segments = figmaPath.split('/').filter(Boolean);
+  // Look at every segment after the collection — any segment that
+  // matches the semantic leading pattern marks the whole name semantic.
+  for (let i = 1; i < segments.length; i++) {
+    if (SEMANTIC_LEADING.test(segments[i])) return true;
+  }
+  // First segment too, when there's no collection prefix (single-segment names).
+  if (segments.length === 1 && SEMANTIC_LEADING.test(segments[0])) return true;
+  return false;
+}
+
+// Normalize a value for cross-form equality. Uses the same canonical
+// forms the categorizer uses, so this matcher and that comparator
+// agree on what counts as "equal."
+function normalizeForMatch(value, domain) {
+  if (value == null) return null;
+  try {
+    if (domain === 'color') return normalizeColor(value);
+    if (domain === 'spacing' || domain === 'radius') return normalizeDimension(value);
+    // typography covers font-size, leading, tracking, font-weight, font-family.
+    // dimensions for the first three; raw string for the last two.
+    if (domain === 'typography') {
+      try { return normalizeDimension(value); } catch {
+        return String(value).trim().toLowerCase();
+      }
+    }
+  } catch { return null; }
+  return String(value).trim().toLowerCase();
+}
+
+// Given a Figma path like `typography/Font-Size/Body` and the parsed
+// theme.primitives map (Tailwind defaults + user @theme), return the
+// canonical Tailwind cssVar that shares the figma value. Returns null
+// when:
+//   - no match
+//   - multiple matches that span different "sub-domains" (e.g. a value
+//     that's both a valid text-size and a valid leading; ambiguous, ask
+//     the designer manually)
+//   - figma value can't be normalized
+function findCanonicalForValue(figmaPath, figmaValue, primitives, opts = {}) {
+  if (!primitives || typeof primitives !== 'object') return null;
+  const domain = opts.domain || inferDomainFromPath(figmaPath);
+  const fNorm = normalizeForMatch(figmaValue, domain);
+  if (fNorm == null) return null;
+
+  // Filter candidates by sub-domain when typography is split into
+  // multiple Tailwind families (--text-*, --leading-*, --tracking-*,
+  // --font-*, --font-weight-*). The figma path's leaf tells us which
+  // family the designer's variable was meant to be.
+  const family = typographyFamily(figmaPath);
+
+  const matches = [];
+  for (const [cssVar, value] of Object.entries(primitives)) {
+    const candidateDomain = domainForCssVar(cssVar);
+    if (candidateDomain !== domain) continue;
+    if (family && typographyFamilyForCssVar(cssVar) !== family) continue;
+    const cNorm = normalizeForMatch(value, candidateDomain);
+    if (cNorm == null) continue;
+    if (cNorm === fNorm) matches.push(cssVar);
+  }
+  if (matches.length === 0) return null;
+  // Single unambiguous match — return it.
+  if (matches.length === 1) return matches[0];
+  // Multiple matches — only surface auto-fix if they all reduce to the
+  // same canonical "shortest" name (e.g. `--spacing-4` over a synonym).
+  // Otherwise stay quiet and let the designer pick "Add as-is."
+  matches.sort((a, b) => a.length - b.length || a.localeCompare(b));
+  // For the common ambiguity (`--text-Xs--line-height` vs `--leading-N`),
+  // pick the family-matched one. If we already filtered by family above,
+  // any remaining ambiguity is between siblings of the same family —
+  // surface the first sorted name as the suggestion.
+  return matches[0];
+}
+
+// Mirror of variable-categorizer's inferDomain but operates on a full
+// path string. Lowercased + delimiter-anchored to handle capitalized
+// Figma collections.
+function inferDomainFromPath(figmaPath) {
+  if (!figmaPath) return 'unknown';
+  const lc = String(figmaPath).toLowerCase();
+  if (lc.startsWith('color/')   || lc.includes('/color/'))   return 'color';
+  if (lc.startsWith('spacing/') || lc.includes('/spacing/')) return 'spacing';
+  if (lc.startsWith('space/')   || lc.includes('/space/'))   return 'spacing';
+  if (lc.startsWith('radius/')  || lc.includes('/radius/'))  return 'radius';
+  if (lc.startsWith('shadow/')  || lc.includes('/shadow/'))  return 'shadow';
+  if (lc.startsWith('font/')    || lc.includes('/font/') ||
+      lc.startsWith('typography/') || lc.includes('/typography/') ||
+      lc.includes('text-') || lc.includes('line-height')) return 'typography';
+  return 'unknown';
+}
+
+function domainForCssVar(cssVar) {
+  const lc = cssVar.toLowerCase();
+  if (lc.startsWith('--color-')) return 'color';
+  if (lc === '--spacing' || lc.startsWith('--spacing-')) return 'spacing';
+  if (lc.startsWith('--radius-')) return 'radius';
+  if (lc.startsWith('--shadow-') || lc.startsWith('--drop-shadow-') ||
+      lc.startsWith('--inset-shadow-') || lc.startsWith('--text-shadow-')) return 'shadow';
+  if (lc.startsWith('--text-') || lc.startsWith('--font-') ||
+      lc.startsWith('--leading-') || lc.startsWith('--tracking-')) return 'typography';
+  return 'unknown';
+}
+
+// Determine which typography family a figma path or cssVar belongs to.
+// Returns one of 'text', 'leading', 'tracking', 'font-weight', 'font',
+// or null when ambiguous. Used to disambiguate matches when the same
+// numeric value is valid in multiple families.
+const FONT_FAMILY_HINTS = [
+  // Multi-word phrases first so they win over single-word fallbacks.
+  { re: /\bline[\s\-_]?height\b/i,   family: 'leading' },
+  { re: /\bletter[\s\-_]?spac/i,     family: 'tracking' },
+  { re: /\bfont[\s\-_]?size\b/i,     family: 'text' },
+  { re: /\bfont[\s\-_]?weight\b/i,   family: 'font-weight' },
+  { re: /\bfont[\s\-_]?family\b/i,   family: 'font' },
+  { re: /\btext[\s\-_]?size\b/i,     family: 'text' },
+  // Canonical Tailwind path prefixes (after collection-strip) — these
+  // are how a well-named figma variable maps to a typography family.
+  { re: /(^|\/)leading\//i,          family: 'leading' },
+  { re: /(^|\/)tracking\//i,         family: 'tracking' },
+  { re: /(^|\/)font-weight\//i,      family: 'font-weight' },
+  { re: /(^|\/)font\//i,             family: 'font' },
+  { re: /(^|\/)text\//i,             family: 'text' },
+];
+
+function typographyFamily(figmaPath) {
+  if (!figmaPath) return null;
+  for (const { re, family } of FONT_FAMILY_HINTS) {
+    if (re.test(figmaPath)) return family;
+  }
+  return null;
+}
+
+function typographyFamilyForCssVar(cssVar) {
+  const lc = cssVar.toLowerCase();
+  if (lc.startsWith('--leading-')) return 'leading';
+  if (lc.startsWith('--tracking-')) return 'tracking';
+  if (lc.startsWith('--font-weight-')) return 'font-weight';
+  if (lc.startsWith('--font-')) return 'font';
+  if (lc.startsWith('--text-')) return 'text';
+  return null;
+}
+
+module.exports = {
+  findCanonicalForValue,
+  looksSemantic,
+  inferDomainFromPath,
+  domainForCssVar,
+  typographyFamily,
+  normalizeForMatch,
+};
diff --git a/plugins/adhd/lib/lint-engine/cli.js b/plugins/adhd/lib/lint-engine/cli.js
index 75b265a..a1ca56d 100644
--- a/plugins/adhd/lib/lint-engine/cli.js
+++ b/plugins/adhd/lib/lint-engine/cli.js
@@ -65,6 +65,7 @@ const { buildVariableSuggestions } = require('./variable-namer');
 const { checkBindings } = require('./binding-checker');
 const { detectTailwindDuplicates } = require('./tailwind-duplicate-detector');
 const { detectDuplicateCollections } = require('./collection-duplicate-detector');
+const { findCanonicalForValue, looksSemantic } = require('./canonical-matcher');
 const { formatReport } = require('./report-formatter');
 
 function parseArgs(argv) {
@@ -202,12 +203,25 @@ function main() {
     // binding-checker matches whichever form varIdMap emits.
     const missingVarNames = new Set();
     const conflictsByName = {};
+    // Per-missing-variable metadata that powers the per-variable
+    // resolution prompts in pull-component / push-component. The
+    // canonical candidate (when present) drives the "Auto-fix: rebind
+    // to <canonical>" option; the looksSemantic flag drives the
+    // emphasis on the "Add as semantic variable" option.
+    const missingVarMeta = {};
     for (const v of variableViolations) {
-      // Split by status: only `missing` entries go into missingVarNames,
-      // only `conflict` entries seed conflictsByName. Crossing them
-      // would over-fire STRUCT015 on every conflicting variable too.
       if (v.status === 'missing') {
         missingVarNames.add(v.token); // collection-stripped form
+        // `token` is the collection-stripped form (e.g. `Font-Size/Body`),
+        // which retains enough structure for the typography-family
+        // disambiguator to do its job. Pass v.domain explicitly so the
+        // matcher doesn't need to re-infer from a path missing its
+        // collection prefix.
+        missingVarMeta[v.token] = {
+          canonicalCandidate: findCanonicalForValue(v.token, v.figma, theme.primitives, { domain: v.domain }),
+          looksSemantic: looksSemantic(v.token),
+          figmaValue: v.figma,
+        };
       } else if (v.status === 'conflict') {
         conflictsByName[v.token] = { local: v.local, figma: v.figma, mode: v.mode };
       }
@@ -223,7 +237,7 @@ function main() {
     }
 
     const bindingViolations = [];
-    const opts = { fileKey, varIdMap, badSuggestionsByName, missingVarNames, conflictsByName };
+    const opts = { fileKey, varIdMap, badSuggestionsByName, missingVarNames, conflictsByName, missingVarMeta };
     if (designCtx && designCtx.mode === 'whole-file' && Array.isArray(designCtx.pages)) {
       for (const page of designCtx.pages) {
         for (const node of page.nodes) {
diff --git a/plugins/adhd/lib/lint-engine/value-normalizer.js b/plugins/adhd/lib/lint-engine/value-normalizer.js
index 2a5af2c..0d45889 100644
--- a/plugins/adhd/lib/lint-engine/value-normalizer.js
+++ b/plugins/adhd/lib/lint-engine/value-normalizer.js
@@ -1,9 +1,12 @@
 'use strict';
 
+const { oklchStringToHex } = require('../design-system/oklch');
+
 const HEX_3 = /^#([0-9a-f])([0-9a-f])([0-9a-f])$/i;
 const HEX_6 = /^#([0-9a-f]{6})$/i;
 const HEX_8 = /^#([0-9a-f]{8})$/i;
 const RGB_RE = /^rgba?\(\s*(\d+)\s*,\s*(\d+)\s*,\s*(\d+)\s*(?:,\s*([\d.]+)\s*)?\)$/i;
+const OKLCH_RE = /^oklch\(/i;
 
 function normalizeColor(input) {
   // Figma's raw color form — `{r, g, b, a}` with each channel 0..1. The
@@ -24,6 +27,16 @@ function normalizeColor(input) {
   }
   const trimmed = input.trim();
 
+  // Tailwind v4's default theme ships every color in oklch() form
+  // (--color-red-500: oklch(63.7% 0.237 25.331), etc.). Without this
+  // branch the matcher can\'t cross-reference Figma hex / rgb values
+  // against the canonical scale — every comparison falls into the
+  // throw → caught → false-conflict path.
+  if (OKLCH_RE.test(trimmed)) {
+    try { return oklchStringToHex(trimmed).toLowerCase(); }
+    catch { /* fall through to other formats / throw below */ }
+  }
+
   const m3 = HEX_3.exec(trimmed);
   if (m3) {
     return ('#' + m3[1] + m3[1] + m3[2] + m3[2] + m3[3] + m3[3]).toLowerCase();
diff --git a/plugins/adhd/lib/lint-engine/variable-categorizer.js b/plugins/adhd/lib/lint-engine/variable-categorizer.js
index 6f5751b..034e7ec 100644
--- a/plugins/adhd/lib/lint-engine/variable-categorizer.js
+++ b/plugins/adhd/lib/lint-engine/variable-categorizer.js
@@ -20,6 +20,7 @@ function inferDomain(figmaPath) {
   if (lc.startsWith('space/')   || lc.includes('/space/'))   return 'spacing';
   if (lc.startsWith('radius/')  || lc.includes('/radius/'))  return 'radius';
   if (lc.startsWith('shadow/')  || lc.includes('/shadow/'))  return 'shadow';
+  if (lc.startsWith('typography/') || lc.includes('/typography/')) return 'typography';
   if (lc.startsWith('font/')    || lc.includes('/font/') ||
       lc.includes('text-') || lc.includes('line-height')) return 'typography';
   return 'unknown';
diff --git a/plugins/adhd/skills/pull-component/SKILL.md b/plugins/adhd/skills/pull-component/SKILL.md
index 88d1e59..9fa229d 100644
--- a/plugins/adhd/skills/pull-component/SKILL.md
+++ b/plugins/adhd/skills/pull-component/SKILL.md
@@ -220,16 +220,31 @@ node -e '
 
 For each entry (skip those whose `figmaValueNormalized` is null — value is too complex to write automatically; surface the variable in the final abort summary instead):
 
+Each STRUCT015 violation in the preflight JSON may carry two optional fields the prompt builder reads:
+
+- `canonicalCandidate` — set when the Figma value strictly equals a Tailwind canonical (e.g. `Font-Size/Body = 14px` ↔ `--text-sm = 0.875rem`). Surfaces the "Auto-fix: rebind in Figma" option.
+- `looksSemantic` — set when the Figma path looks semantic (`brand`, `accent`, `surface`, `background`, `primary`, etc.). Used to label the "Add as semantic" option prominently, so a brand color that coincidentally matches a Tailwind palette entry doesn't get accidentally rebound.
+
+Build the option list per violation. Always include the abort-flavored picks. Only surface "Auto-fix" when `canonicalCandidate` is present. Label "Add to globals.css" as "Add as semantic variable" when `looksSemantic` is true.
+
 ```
-Question: "`<figmaName>` is bound in this component but doesn't exist in code's design system. Figma resolves it to `<figmaValueNormalized>`. What do you want to do?"
+Question: "`<figmaName>` is bound in this component but doesn't exist in code's design system. Figma resolves it to `<figmaValueNormalized>`.<canonical-hint-if-any> What do you want to do?"
 Header: "Variable missing"
 Options:
-  - "Add to globals.css (writes --<canonical>: <figmaValueNormalized>)"
+  <only when canonicalCandidate is set:>
+  - "Auto-fix: rebind in Figma to `<canonicalCandidate>` (same value, no visual change — non-canonical variable gets deleted)"
+  <always:>
+  - "Add to globals.css (writes --<canonical>: <figmaValueNormalized>)"   ← label changes to "Add as semantic variable (recommended for brand / accent / surface tokens — canonical match is coincidence)" when looksSemantic
   - "Don't sync — leave the annotation in Figma and abort"
   - "Abort the pull (no annotation change)"
 ```
 
-If "Add," record `{ figmaName, value: figmaValueNormalized }` to a running `actions-input` array and continue to the next prompt. If "Don't sync" or "Abort," set `abortIntent = true` and continue collecting picks (so subsequent prompts still get answered — the designer might still want to record decisions on the rest before the run aborts). The difference between the two abort-flavored picks: "Don't sync" guarantees annotations land (via the helper above); "Abort" leaves annotations as-is (already-on if a prior run annotated them, off otherwise).
+The `<canonical-hint-if-any>` is "Tailwind's `<canonicalCandidate>` has the same value." appended to the question text when a canonical exists; omit otherwise.
+
+Pick handling:
+- **Auto-fix**: record `{ figmaName, canonicalCandidate, figmaValue }` to a running `auto-fix-input` array. Applied via use_figma in the "Apply OR abort" step below (rebind every layer + delete the source variable, same mechanic as STRUCT013 / STRUCT014 `--fix`).
+- **Add (semantic or not)**: record `{ figmaName, value: figmaValueNormalized }` to a running `actions-input` array.
+- **Don't sync / Abort**: set `abortIntent = true` and continue collecting picks. The difference: "Don't sync" guarantees annotations land via the helper above; "Abort" leaves annotations as-is.
 
 **If STRUCT016 violations exist (layer binds variable whose value differs from code's):**
 
@@ -267,7 +282,92 @@ value" on the per-variable prompts above.
 
 3. Exit 1.
 
-**Otherwise**, every STRUCT015 / STRUCT016 prompt was resolved (every pick was "Add" / "Take Figma's value"). Apply the queued writes:
+**Otherwise**, every STRUCT015 / STRUCT016 prompt was resolved (every pick was "Auto-fix" / "Add" / "Take Figma's value"). Apply the queued writes — Figma-side first, then code-side.
+
+### Apply auto-fix actions (Figma side)
+
+For each entry in `auto-fix-input`, run a use_figma rebind that mirrors STRUCT013's consolidation pattern: find the source variable by name, find or create the canonical destination variable in the right collection, walk every layer (across all pages) rewriting bindings from source → canonical, then delete the now-unreferenced source. Skip the entry if the source can't be found (already-rebound or deleted between extract and fix). Surface any rebind failures (paint mutations on instance overrides, etc.) in the final report — the rest of the run still proceeds.
+
+Substitute `__ACTIONS__` with the `auto-fix-input` JSON. Each entry is `{ figmaName: "typography/Font-Size/Body", canonicalCandidate: "--text-sm", figmaValue: 14 }`. The script handles the figma-side mutation:
+
+```js
+const ACTIONS = __ACTIONS__;
+
+// Resolve the canonical's Figma name from its --css-var form.
+// "--text-sm" → looking for a variable named "text/sm" (drop the
+// leading `--` and replace single hyphens with slashes, but only for
+// the canonical Tailwind families — leave the last segment intact so
+// "text-sm" doesn't become "text/sm"). For Tailwind's known prefixes
+// the split rule is: prefix + remaining → "<prefix>/<remaining>".
+function canonicalFigmaName(cssVar) {
+  const PREFIXES = ['color', 'spacing', 'radius', 'text', 'leading', 'tracking', 'font-weight', 'font', 'shadow', 'opacity', 'border-width', 'breakpoint', 'container', 'ease', 'animate', 'blur'];
+  const stripped = cssVar.replace(/^--/, '');
+  for (const p of PREFIXES.sort((a, b) => b.length - a.length)) {
+    if (stripped === p) return p;
+    if (stripped.startsWith(p + '-')) return p + '/' + stripped.slice(p.length + 1);
+  }
+  return stripped;
+}
+
+const allCollections = await figma.variables.getLocalVariableCollectionsAsync();
+async function findVarByName(name) {
+  for (const col of allCollections) {
+    for (const vid of col.variableIds) {
+      const v = await figma.variables.getVariableByIdAsync(vid);
+      if (v && v.name === name) return v;
+    }
+  }
+  return null;
+}
+
+const results = [];
+for (const action of ACTIONS) {
+  const source = await findVarByName(action.figmaName);
+  if (!source) {
+    results.push({ ...action, status: 'skipped', reason: 'source variable not found' });
+    continue;
+  }
+  const canonicalName = canonicalFigmaName(action.canonicalCandidate);
+  let canonical = await findVarByName(canonicalName);
+  if (!canonical) {
+    // Create the canonical in the same collection as the source so the
+    // designer's existing organization is respected. (If they pushed
+    // Tailwind tokens into a different collection earlier, the
+    // alias-aware collection lookup in figma-write-script handles it.)
+    canonical = figma.variables.createVariable(canonicalName, source.variableCollectionId, source.resolvedType);
+    canonical.scopes = source.scopes;
+    for (const [modeId, val] of Object.entries(source.valuesByMode)) {
+      canonical.setValueForMode(modeId, val);
+    }
+  }
+
+  let rebound = 0;
+  for (const page of figma.root.children) {
+    await figma.setCurrentPageAsync(page);
+    const nodes = page.findAll(() => true);
+    for (const node of nodes) {
+      if (!node.boundVariables) continue;
+      for (const [prop, alias] of Object.entries(node.boundVariables)) {
+        if (prop === 'fills' || prop === 'strokes' || prop === 'effects') continue;
+        if (alias && alias.id === source.id) { node.setBoundVariable(prop, canonical); rebound++; }
+      }
+      for (const kind of ['fills', 'strokes']) {
+        const arr = node[kind];
+        if (!Array.isArray(arr)) continue;
+        node[kind] = arr.map((paint) => paint?.boundVariables?.color?.id === source.id
+          ? figma.variables.setBoundVariableForPaint(paint, 'color', canonical)
+          : paint
+        );
+      }
+    }
+  }
+  try { source.remove(); results.push({ ...action, canonicalName, rebound, status: 'ok' }); }
+  catch (e) { results.push({ ...action, canonicalName, rebound, status: 'rebound-only', error: String(e) }); }
+}
+return { results };
+```
+
+### Apply add / take-Figma actions (code side)
 
 For each entry in `actions-input`, resolve the alias chain via the CLI to find where the write should actually land. The resolver handles the shadcn-style exposure pattern (`--color-primary: var(--primary)` in `@theme inline` → write lands at `--primary` in `:root`, not at `--color-primary` in `@theme`), avoiding the trap of overwriting an alias with a literal and breaking dark-mode propagation.
 
diff --git a/plugins/adhd/skills/push-component/SKILL.md b/plugins/adhd/skills/push-component/SKILL.md
index a4add63..136a11d 100644
--- a/plugins/adhd/skills/push-component/SKILL.md
+++ b/plugins/adhd/skills/push-component/SKILL.md
@@ -204,17 +204,22 @@ Skip this phase if neither STRUCT015 nor STRUCT016 fired — Phase 11's clean-pr
 
 Read `/tmp/adhd-push-component/preflight-report.json`. Group STRUCT015 + STRUCT016 violations by `figmaVarName` so a variable bound by multiple layers prompts ONCE, not once per layer. Normalize each Figma value to a write-ready string using `lib/lint-engine/value-normalizer.js` (same `node -e` snippet `/adhd:pull-component` uses); skip variables whose value won't normalize (rare — surfaces them in Phase 11 instead).
 
-For each unique STRUCT015 variable:
+For each unique STRUCT015 variable. The violation's `canonicalCandidate` (set when the value strictly equals a Tailwind canonical) and `looksSemantic` (set when the path looks semantic — brand, accent, etc.) drive which options appear and how they're labeled, same as `/adhd:pull-component`'s Phase 2.5.
 
 ```
-Question: "`<figmaName>` is bound by this push but doesn't exist in code's design system. Figma resolves it to `<figmaValueNormalized>`. What do you want to do?"
+Question: "`<figmaName>` is bound by this push but doesn't exist in code's design system. Figma resolves it to `<figmaValueNormalized>`.<canonical-hint-if-any> What do you want to do?"
 Header: "Variable missing"
 Options:
-  - "Add to globals.css (writes --<canonical>: <figmaValueNormalized>)"
+  <only when canonicalCandidate is set:>
+  - "Auto-fix: rebind in Figma to `<canonicalCandidate>` (same value, no visual change — non-canonical variable gets deleted)"
+  <always:>
+  - "Add to globals.css (writes --<canonical>: <figmaValueNormalized>)"   ← label changes to "Add as semantic variable (recommended for brand / accent / surface tokens — canonical match is coincidence)" when looksSemantic
   - "Don't sync — leave the annotation in Figma and roll back"
   - "Roll back the push (no annotation change)"
 ```
 
+The "Auto-fix" pick gets queued into `auto-fix-input` and applied via the same use_figma rebind script `/adhd:pull-component` Phase 2.5 uses. Subsequently, "Add" picks go to `code-side-actions`; "Don't sync" / "Roll back" picks set `abortIntent = true`.
+
 For each unique STRUCT016 variable:
 
 ```

From 91707ec5fc0ae99d8acd78d054e578630376c057 Mon Sep 17 00:00:00 2001
From: Hugh Francis <hughfrancis89@gmail.com>
Date: Tue, 12 May 2026 20:18:24 -0400
Subject: [PATCH 74/79] pull-component: Phase 2.7 inherits the per-variable +
 auto-fix prompts from Phase 2.5
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Phase 2.7 was still using its original batch prompt ("Yes — add all 4
to @theme", "No — continue without adding", "Cancel"). When the
agent had already detected that the values matched Tailwind canonicals
(text-sm, leading-7, tracking-normal), the designer couldn't actually
pick "rebind in Figma to those canonicals" — only "add the
non-canonical names to code" or "skip everything."

Now Phase 2.7 walks each missing variable through the same prompt
shape as Phase 2.5's STRUCT015 resolution: Auto-fix (when a Tailwind
canonical strictly matches), Add (or Add-as-semantic when the name
looks semantic), Skip, or Cancel. Auto-fix and Add picks queue into
the same auto-fix-input / actions-input arrays Phase 2.5 builds;
they're applied together in the existing "Apply OR abort" step. No
new machinery — just routing.

The canonicalCandidate / looksSemantic fields are attached at lint
time for Phase 2.5 (via cli.js's missingVarMeta). For Phase 2.7 the
source list comes from variable-categorizer's raw output, which
doesn't carry those fields, so the SKILL computes them inline via a
small node -e against canonical-matcher.js — same matcher used in
Phase 2.5, same primitives map (Tailwind defaults + synthesized scale
+ user @theme).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 plugins/adhd/skills/pull-component/SKILL.md | 84 ++++++++++++---------
 1 file changed, 48 insertions(+), 36 deletions(-)

diff --git a/plugins/adhd/skills/pull-component/SKILL.md b/plugins/adhd/skills/pull-component/SKILL.md
index 9fa229d..c1da037 100644
--- a/plugins/adhd/skills/pull-component/SKILL.md
+++ b/plugins/adhd/skills/pull-component/SKILL.md
@@ -412,54 +412,66 @@ Split missing further by the categorizer's `mode` field:
 
 If `missingPrimitives.length === 0 && missingSemantics.length === 0 && conflicts.length === 0`, skip this phase entirely.
 
-Otherwise, build a single `AskUserQuestion` prompt:
+### Per-variable prompts (same shape as Phase 2.5's STRUCT015 resolution)
 
-```
-Found new variables referenced by this frame:
-
-Primitives (add to @theme):
-  color/brand/600     #5e3aee
-  radius/lg           12px
-  shadow/popover      0 4px 12px rgba(0,0,0,.08)
-
-[if missingSemantics > 0]
-Semantic tokens with light/dark modes (not auto-addable):
-  color/text/primary  (light: #111, dark: #fafafa)
-  color/surface       (light: #fff, dark: #0a0a0a)
-Run /adhd:pull-tokens to add these — they need coordinated
-`:root`, `.dark`, and `@theme inline` edits.
+Phase 2.7 surfaces missing variables that Figma KNOWS ABOUT but no layer in this component binds — they were declared in the file but their values aren't actually referenced by the pulled subtree. The per-variable prompt is the same as Phase 2.5's STRUCT015 prompt, just sourced from a different list. Reuse the `canonicalCandidate` / `looksSemantic` fields the lint engine attaches to each missing entry (variable-categorizer's output already includes domain; the categorizer can be enhanced to attach the same auto-fix metadata STRUCT015 violations carry, or the SKILL can call `findCanonicalForValue` inline via a small node -e).
 
-[if conflicts > 0]
-Variables with value mismatches (existing in code, different in Figma):
-  color/brand/500     code=#5e3aee  figma=#6a4cf2
-Run /adhd:pull-tokens to resolve.
+For each missing primitive, prompt:
 
+```
+Question: "`<figmaName>` is referenced by Figma but doesn't exist in code's design system. Figma resolves it to `<figmaValue>`.<canonical-hint-if-any> What do you want to do?"
+Header: "Variable missing"
 Options:
-  [Yes — add the <N> primitives and continue]
-  [No — continue without adding (component pull may land raw values)]
-  [Cancel — abort, I'll run /adhd:pull-tokens first]
+  <only when canonicalCandidate is set:>
+  - "Auto-fix: rebind in Figma to `<canonicalCandidate>` (same value, no visual change — non-canonical variable gets deleted)"
+  <always:>
+  - "Add to globals.css (writes --<canonical>: <figmaValue>)"   ← label changes to "Add as semantic variable (recommended for brand / accent / surface tokens — canonical match is coincidence)" when looksSemantic
+  - "Skip this one (continue without adding; subsequent pull may land raw values for layers that bind it)"
+  - "Cancel — run /adhd:pull-tokens first (abort the pull)"
 ```
 
-On **Yes**: build an actions array for each primitive and invoke `applyToCss` (the helper `pull-tokens` already uses for CSS edits). Save under `/tmp/adhd-pull-component/new-globals.css`, then write to the configured `globals.css` path:
+Pick handling matches Phase 2.5's flow:
+- **Auto-fix**: queue into `auto-fix-input` (the same array Phase 2.5 builds). Applied via the same use_figma rebind script in Phase 2.5's "Apply" step.
+- **Add / Add as semantic**: queue into `actions-input` (also shared with Phase 2.5).
+- **Skip**: record nothing. The pull proceeds; if any layer in this component binds the variable, STRUCT015 would have already caught it in Phase 2.5 — so by the time we reach 2.7, "Skip" is genuinely safe.
+- **Cancel**: set `abortIntent = true`. Falls through Phase 2.5's "Apply OR abort" decision.
+
+Since Phase 2.7 runs AFTER Phase 2.5, the action arrays might already contain entries. Append rather than reset.
+
+### Computing `canonicalCandidate` for Phase 2.7 entries
+
+Phase 2.5's STRUCT015 violations get `canonicalCandidate` attached by `cli.js` because they're tied to specific layer bindings. Phase 2.7's source is the raw variable-categorizer output, which doesn't have the field attached. Compute it inline before building the prompts:
 
 ```bash
 node -e '
   const fs = require("fs");
-  const { applyToCss } = require("plugins/adhd/lib/design-system/code-writer.js");
-  const cssPath = process.argv[1];
-  const css = fs.readFileSync(cssPath, "utf8");
-  const actions = JSON.parse(process.argv[2]);
-  fs.writeFileSync(cssPath, applyToCss(css, actions));
-' "<globals.css path>" "$ACTIONS_JSON"
+  const { findCanonicalForValue, looksSemantic } = require("plugins/adhd/lib/lint-engine/canonical-matcher");
+  const { parseTheme } = require("plugins/adhd/lib/lint-engine/theme-parser");
+  const { synthesizeTailwindUtilityScale } = require("plugins/adhd/lib/design-system/code-parser");
+  const path = require("path");
+  // Build the same primitives map cli.js builds.
+  const defaultsCss = fs.readFileSync(path.resolve("plugins/adhd/lib/design-system/tailwind-defaults.css"), "utf8")
+    .replace(/@theme\s+default\s+inline\s*\{/g, "@theme inline {")
+    .replace(/@theme\s+default\s*\{/g, "@theme {");
+  const userCss = fs.readFileSync("<globals.css>", "utf8");
+  const userTheme = parseTheme(userCss);
+  const defaults = parseTheme(defaultsCss).primitives;
+  for (const t of synthesizeTailwindUtilityScale()) {
+    if (!(t.cssVar in defaults)) defaults[t.cssVar] = t.values.default.value;
+  }
+  const primitives = { ...defaults, ...userTheme.primitives };
+  // Enrich every "missing" variable-categorizer entry.
+  const stdout = JSON.parse(fs.readFileSync("/tmp/adhd-pull-component/stdout.json", "utf8"));
+  const enriched = (stdout.variable || []).filter(v => v.status === "missing").map(v => ({
+    ...v,
+    canonicalCandidate: findCanonicalForValue(v.token, v.figma, primitives, { domain: v.domain }),
+    looksSemantic: looksSemantic(v.token),
+  }));
+  fs.writeFileSync("/tmp/adhd-pull-component/phase27-missing.json", JSON.stringify(enriched));
+'
 ```
 
-Where each action is shaped `{ kind: "set-primitive", cssVar: "--" + token.replace(/\//g, "-"), value: <figma-value> }`. The token comes from each missing entry's `token` field (already collection-stripped).
-
-Print a confirmation: `Added <N> primitive(s) to globals.css: <comma-separated list>`. Then continue with Phase 3.
-
-On **No**: continue without writing. The component pull proceeds; un-tracked variables may land as raw values or `// adhd:off-system` markers in the lookup tables.
-
-On **Cancel**: abort with `Run /adhd:pull-tokens first to sync the design system, then re-run /adhd:pull-component.`
+Then iterate `phase27-missing.json` to build the prompts.
 
 Skip this phase if conflicts exist BUT no missing — there's nothing additive to do, just print: `Note: <N> variable value(s) differ between Figma and code. Run /adhd:pull-tokens to reconcile.` Then continue (conflicts don't block pull-component v1; the pull works with code's value, drift is reported in the final report).
 

From dbfa0bc22f5eb67491ea8659878573ba920c6b24 Mon Sep 17 00:00:00 2001
From: Hugh Francis <hughfrancis89@gmail.com>
Date: Tue, 12 May 2026 20:21:20 -0400
Subject: [PATCH 75/79] =?UTF-8?q?pull-component:=20Phase=202.7=20=E2=80=94?=
 =?UTF-8?q?=20replace=20"Cancel"=20with=20explicit=20"Annotate=20and=20abo?=
 =?UTF-8?q?rt"?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

User clarification: "Skip this one" doesn't push an annotation (Phase
2.7's missing variables typically aren't tied to a layer in the scope
— Phase 2.5's STRUCT015 catches the bound ones first), but the
prompt's third option should still make "annotate-then-abort" the
explicit named choice. The previous "Cancel — run /adhd:pull-tokens
first" wording was vague about whether an annotation lands.

Now the third option is "Skip this one — continue without adding (no
annotation; this component pull works fine without it)" and the
fourth is "Annotate and abort — push the lint annotation and stop
the pull." The annotate-and-abort path falls through Phase 2.5's
abort-time annotation helper, which lands on bound layers when they
exist and just exits cleanly when they don't.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 plugins/adhd/skills/pull-component/SKILL.md | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/plugins/adhd/skills/pull-component/SKILL.md b/plugins/adhd/skills/pull-component/SKILL.md
index c1da037..c3b6881 100644
--- a/plugins/adhd/skills/pull-component/SKILL.md
+++ b/plugins/adhd/skills/pull-component/SKILL.md
@@ -426,15 +426,15 @@ Options:
   - "Auto-fix: rebind in Figma to `<canonicalCandidate>` (same value, no visual change — non-canonical variable gets deleted)"
   <always:>
   - "Add to globals.css (writes --<canonical>: <figmaValue>)"   ← label changes to "Add as semantic variable (recommended for brand / accent / surface tokens — canonical match is coincidence)" when looksSemantic
-  - "Skip this one (continue without adding; subsequent pull may land raw values for layers that bind it)"
-  - "Cancel — run /adhd:pull-tokens first (abort the pull)"
+  - "Skip this one — continue without adding (no annotation; this component pull works fine without it)"
+  - "Annotate and abort — push the lint annotation and stop the pull"
 ```
 
 Pick handling matches Phase 2.5's flow:
 - **Auto-fix**: queue into `auto-fix-input` (the same array Phase 2.5 builds). Applied via the same use_figma rebind script in Phase 2.5's "Apply" step.
 - **Add / Add as semantic**: queue into `actions-input` (also shared with Phase 2.5).
-- **Skip**: record nothing. The pull proceeds; if any layer in this component binds the variable, STRUCT015 would have already caught it in Phase 2.5 — so by the time we reach 2.7, "Skip" is genuinely safe.
-- **Cancel**: set `abortIntent = true`. Falls through Phase 2.5's "Apply OR abort" decision.
+- **Skip**: record nothing. The pull proceeds. Phase 2.7's missing variables aren't tied to layers in this scope (Phase 2.5's STRUCT015 would have caught those) — so there's nothing to annotate, and skipping is safe; the variable just stays out of code.
+- **Annotate and abort**: set `abortIntent = true`. Falls through Phase 2.5's "Apply OR abort" path, which calls the abort-time annotation helper before exit. If the variable IS bound by a layer (rare in Phase 2.7's discovery list — implies the binding lives in a deeper part of the file outside the lint scope), the annotation lands on that node; if it's unbound by any scoped layer, the abort still completes without a new annotation. The pull stops in both cases.
 
 Since Phase 2.7 runs AFTER Phase 2.5, the action arrays might already contain entries. Append rather than reset.
 

From eb0ce0cad4caa2ddfc8c6e96181451cbe8d71ba9 Mon Sep 17 00:00:00 2001
From: Hugh Francis <hughfrancis89@gmail.com>
Date: Tue, 12 May 2026 20:23:37 -0400
Subject: [PATCH 76/79] pull/push-component: shorten resolution-prompt labels
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

User asked for clearer labels. The action verbs were buried in verbose
parenthetical explanations. Now each option leads with the verb:

  Auto-fix in Figma — rebind to `<canonical>` (same value, no visual change)
  Add in code as `--<cssVar>`
  Add as semantic — keep `<figmaName>` in code (recommended for brand / accent / surface tokens)
  Don't sync — annotate and abort
  Skip — continue without adding
  Abort the pull

"Add in code" and "Add as semantic" are the two labels for the same
underlying action (write the figma value to globals.css); the label
switches based on looksSemantic so the right choice reads obvious in
the moment. Other options were already clear.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 plugins/adhd/skills/pull-component/SKILL.md | 20 +++++++++++++-------
 plugins/adhd/skills/push-component/SKILL.md |  9 ++++++---
 2 files changed, 19 insertions(+), 10 deletions(-)

diff --git a/plugins/adhd/skills/pull-component/SKILL.md b/plugins/adhd/skills/pull-component/SKILL.md
index c3b6881..5eca6b7 100644
--- a/plugins/adhd/skills/pull-component/SKILL.md
+++ b/plugins/adhd/skills/pull-component/SKILL.md
@@ -232,10 +232,13 @@ Question: "`<figmaName>` is bound in this component but doesn't exist in code's
 Header: "Variable missing"
 Options:
   <only when canonicalCandidate is set:>
-  - "Auto-fix: rebind in Figma to `<canonicalCandidate>` (same value, no visual change — non-canonical variable gets deleted)"
+  - "Auto-fix in Figma — rebind to `<canonicalCandidate>` (same value, no visual change)"
+  <always, with label varying by looksSemantic:>
+  - "Add in code as `--<cssVar>`"
+    when looksSemantic=true, replace the label with:
+  - "Add as semantic — keep `<figmaName>` in code (recommended for brand / accent / surface tokens)"
   <always:>
-  - "Add to globals.css (writes --<canonical>: <figmaValueNormalized>)"   ← label changes to "Add as semantic variable (recommended for brand / accent / surface tokens — canonical match is coincidence)" when looksSemantic
-  - "Don't sync — leave the annotation in Figma and abort"
+  - "Don't sync — annotate and abort"
   - "Abort the pull (no annotation change)"
 ```
 
@@ -423,11 +426,14 @@ Question: "`<figmaName>` is referenced by Figma but doesn't exist in code's desi
 Header: "Variable missing"
 Options:
   <only when canonicalCandidate is set:>
-  - "Auto-fix: rebind in Figma to `<canonicalCandidate>` (same value, no visual change — non-canonical variable gets deleted)"
+  - "Auto-fix in Figma — rebind to `<canonicalCandidate>` (same value, no visual change)"
+  <always, with label varying by looksSemantic:>
+  - "Add in code as `--<cssVar>`"
+    when looksSemantic=true, replace the label with:
+  - "Add as semantic — keep `<figmaName>` in code (recommended for brand / accent / surface tokens)"
   <always:>
-  - "Add to globals.css (writes --<canonical>: <figmaValue>)"   ← label changes to "Add as semantic variable (recommended for brand / accent / surface tokens — canonical match is coincidence)" when looksSemantic
-  - "Skip this one — continue without adding (no annotation; this component pull works fine without it)"
-  - "Annotate and abort — push the lint annotation and stop the pull"
+  - "Skip — continue without adding (no annotation; the component pull works fine without it)"
+  - "Annotate and abort"
 ```
 
 Pick handling matches Phase 2.5's flow:
diff --git a/plugins/adhd/skills/push-component/SKILL.md b/plugins/adhd/skills/push-component/SKILL.md
index 136a11d..8393c27 100644
--- a/plugins/adhd/skills/push-component/SKILL.md
+++ b/plugins/adhd/skills/push-component/SKILL.md
@@ -211,10 +211,13 @@ Question: "`<figmaName>` is bound by this push but doesn't exist in code's desig
 Header: "Variable missing"
 Options:
   <only when canonicalCandidate is set:>
-  - "Auto-fix: rebind in Figma to `<canonicalCandidate>` (same value, no visual change — non-canonical variable gets deleted)"
+  - "Auto-fix in Figma — rebind to `<canonicalCandidate>` (same value, no visual change)"
+  <always, with label varying by looksSemantic:>
+  - "Add in code as `--<cssVar>`"
+    when looksSemantic=true, replace the label with:
+  - "Add as semantic — keep `<figmaName>` in code (recommended for brand / accent / surface tokens)"
   <always:>
-  - "Add to globals.css (writes --<canonical>: <figmaValueNormalized>)"   ← label changes to "Add as semantic variable (recommended for brand / accent / surface tokens — canonical match is coincidence)" when looksSemantic
-  - "Don't sync — leave the annotation in Figma and roll back"
+  - "Don't sync — annotate and roll back"
   - "Roll back the push (no annotation change)"
 ```
 

From 258eaf4cbf55af3035c12dfaecb491f9c7b0ee29 Mon Sep 17 00:00:00 2001
From: Hugh Francis <hughfrancis89@gmail.com>
Date: Tue, 12 May 2026 20:45:56 -0400
Subject: [PATCH 77/79] lint: drop --annotate / --fix flags, always run
 interactive resolution wizard
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

User reframe: /adhd:lint isn't a read-only command anymore; it's the
generalized resolver. Every violation goes through a per-rule wizard
with rule-appropriate options (auto-fix in Figma, add in code, take
Figma's value, take code's value, annotate only, skip). The previous
--annotate / --fix flags collapse into the per-violation prompts —
annotation is a choice on each prompt, fix candidates surface
inline when they exist.

Key shift from pull/push semantics: lint has NO abort option. There's
no sync to abort; the wizard's picks are the only outputs. The last
option on every prompt is "Skip" (record nothing, no annotation, no
fix), distinct from pull/push's "Abort the pull/roll back."

Per-rule option matrix:
  STRUCT001–010 structural   → Annotate-all / Skip-all (batched per rule code)
  STRUCT011 naming           → Annotate only / Skip (rename needs designer)
  STRUCT012 cross-domain     → Annotate only / Skip (rebind needs designer)
  STRUCT013 Tailwind dupe    → Auto-fix / Annotate / Skip
  STRUCT014 collection dupe  → Auto-fix / Annotate / Skip
  STRUCT015 missing-in-code  → Auto-fix (when canonical match)
                               Add in code / Add as semantic (label varies)
                               Annotate only / Skip
  STRUCT016 value conflict   → Take Figma / Take code / Annotate / Skip
                               (generalized resolver per user's call)

The "Take code" path on STRUCT016 means push the code value to Figma's
variable — same mechanic as push-tokens' update-variable action. The
"Take Figma" path writes to globals.css via the alias-aware resolver
from pull-component. Lint covers both directions per-violation; designers
who want bulk value sync still reach for push-tokens / pull-tokens.

Phase 7 applies the three queued action types in order:
  1. Figma-side actions in one use_figma call (rebinds, consolidations,
     variable-value updates)
  2. Code-side actions via applyToCss
  3. Annotation reconciliation (push annotateNodes, clear stale entries)

Removed Phases 6, 7, 8, 8b (flag-driven paths), Phase 1.5 (flag-combo
validation no longer needed). 587 tests still pass.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 README.md                                     |  12 +-
 .../lib/lint-engine/__tests__/cli.test.js     |   6 +-
 plugins/adhd/lib/lint-engine/cli.js           |   8 +-
 .../tailwind-duplicate-detector.js            |   2 +-
 plugins/adhd/skills/lint/SKILL.md             | 599 +++++++-----------
 5 files changed, 248 insertions(+), 379 deletions(-)

diff --git a/README.md b/README.md
index 22cbbe9..51f5580 100644
--- a/README.md
+++ b/README.md
@@ -29,7 +29,7 @@ After install, nine slash commands are available:
 | Command | Args | Direction | What it does |
 |---|---|---|---|
 | `/adhd:config` | — | — | Interactive wizard that produces `adhd.config.ts`. Verifies the official Figma plugin is installed + authenticated before anything else. |
-| `/adhd:lint` | `[<figma-url>] [--annotate] [--fix]` | read-only by default | Validates the Figma file (whole file or scoped) against the local design system + structure best-practices. With `--annotate`, also writes Figma annotations on each offending node in a "lint" category. With `--fix`, walks STRUCT013 Tailwind-duplicate candidates per-prompt and consolidates approved ones (rebinds bindings to the canonical Tailwind variable, then deletes the duplicate). |
+| `/adhd:lint` | `[<figma-url>]` | always interactive | Validates the Figma file (whole file or scoped) against the local design system + structure best-practices, then walks every violation through a per-rule resolution wizard. Per violation, designers pick from auto-fix in Figma (rebind to canonical / consolidate duplicates), add in code, take Figma's value, take code's value, annotate only, or skip. No flags — annotation and fix behavior are per-violation choices. |
 | `/adhd:push-tokens` | `[--dry-run]` | code → Figma | Pushes globals.css variables + named styles into Figma directly via the remote MCP. Runs an interactive 7-question wizard on every invocation to set per-domain push policy: push the full Tailwind palette or only your semantic colors? Push the full spacing scale or only your authored tokens? Skip opacity entirely? Route shadows through effect styles? `--dry-run` previews exactly what would be added or skipped (reflecting your wizard answers) without writing. |
 | `/adhd:pull-tokens` | `[--dry-run]` | Figma → code | Pulls Figma variables + named styles into globals.css. `--dry-run` previews without writing. |
 | `/adhd:push-component` | `<path> [--max-variants <n>]` | code → Figma | Pushes a React component to Figma as a structured Component Set with variant properties + variable bindings, plus a preflight lint check. Per-variable STRUCT015/STRUCT016 resolution prompts let you sync mismatches in either direction; annotations land automatically on any abort. |
@@ -92,15 +92,15 @@ The scoped report covers the same rules (STRUCT001–016 + variable mismatches),
 
 ### Annotate violations in Figma
 
-`/adhd:lint` is read-only — it echoes a markdown report to the terminal and exits. Pass `--annotate` to also push each violation to Figma as a node-bound annotation in a dedicated **"lint"** category (orange). Designers see them on the layers panel, and a re-run with `--annotate` cleans up stale "lint"-category annotations automatically (designer-authored annotations and other categories are never touched).
+`/adhd:lint` is always interactive — every violation goes through a per-rule wizard with "Annotate only" as one of the options. Picking it pushes the violation to Figma as a node-bound annotation in a dedicated **"lint"** category (orange); picking anything else either resolves the issue directly (auto-fix in Figma, add in code, take Figma's value, take code's value) or skips it (no annotation, no fix). Stale annotations from prior runs get cleaned up automatically when their nodes drop out of the picks list — designer-authored annotations and any non-"lint" category are never touched.
 
 For `/adhd:push-component` and `/adhd:pull-component`, annotation is **automatic on any abort** — when the SKILL aborts due to preflight violations (including a "Don't sync" pick on the per-variable STRUCT015/STRUCT016 prompts), every blocking violation is pushed to Figma before exit. On successful runs the same annotation script clears prior-run annotations from the scope so Figma stays clean. No flag needed.
 
 ```
-/adhd:lint --annotate                                                  # whole file (manual annotation)
-/adhd:lint https://www.figma.com/design/<KEY>?node-id=91-18 --annotate # scoped (manual annotation)
-/adhd:push-component app/components/avatar/index.tsx                   # annotates on abort
-/adhd:pull-component https://www.figma.com/design/<KEY>?node-id=91-18  # annotates on abort
+/adhd:lint                                                # whole file — walks every violation
+/adhd:lint https://www.figma.com/design/<KEY>?node-id=91-18 # scoped — walks every violation
+/adhd:push-component app/components/avatar/index.tsx       # annotates on abort
+/adhd:pull-component https://www.figma.com/design/<KEY>?node-id=91-18 # annotates on abort
 ```
 
 ### Push a component
diff --git a/plugins/adhd/lib/lint-engine/__tests__/cli.test.js b/plugins/adhd/lib/lint-engine/__tests__/cli.test.js
index 32db6d0..0794edc 100644
--- a/plugins/adhd/lib/lint-engine/__tests__/cli.test.js
+++ b/plugins/adhd/lib/lint-engine/__tests__/cli.test.js
@@ -451,7 +451,7 @@ test('STRUCT013: surfaces Figma variables that duplicate Tailwind defaults (stri
   assert.equal(v.figmaVarId, 'VAR:white');
   assert.equal(v.tailwindCssVar, '--color-white');
   assert.match(v.message, /duplicates Tailwind default `--color-white`/);
-  assert.match(v.message, /\/adhd:lint --fix/);
+  assert.match(v.message, /\/adhd:lint/);
 });
 
 test('STRUCT015: violation carries canonicalCandidate + looksSemantic when a Tailwind canonical matches the value', () => {
@@ -565,7 +565,7 @@ test('STRUCT015 + STRUCT016: per-layer errors when a layer binds a missing/confl
 test('STRUCT014: surfaces alias-equivalent collections side by side (Color vs color, Space vs spacing)', () => {
   // Real scenario from the user's reactor file: prior pushes created
   // lowercase `color`/`spacing` collections alongside designer's existing
-  // `Color`/`Space`. The new rule surfaces these for /adhd:lint --fix
+  // `Color`/`Space`. The new rule surfaces these so /adhd:lint's wizard
   // to consolidate; alias-aware push prevents future duplicates.
   const varDefs = tmp('vars.json', {
     'Color/zinc-500': '#71717a',
@@ -599,7 +599,7 @@ test('STRUCT014: surfaces alias-equivalent collections side by side (Color vs co
   assert.equal(byCanonical['spacing'].collections[0].varCount, 2);
   // Message names the canonical + lists the colliding collections.
   assert.match(byCanonical['color'].message, /alias to "color"/);
-  assert.match(byCanonical['color'].message, /\/adhd:lint --fix/);
+  assert.match(byCanonical['color'].message, /\/adhd:lint/);
 });
 
 test('STRUCT011: omits nodeId in whole-file mode (no scope root to annotate)', () => {
diff --git a/plugins/adhd/lib/lint-engine/cli.js b/plugins/adhd/lib/lint-engine/cli.js
index a1ca56d..93bd2d9 100644
--- a/plugins/adhd/lib/lint-engine/cli.js
+++ b/plugins/adhd/lib/lint-engine/cli.js
@@ -314,7 +314,7 @@ function main() {
   //
   // The fix is "consolidate": rebind every layer using the duplicate to
   // the canonical Tailwind variable, then delete the duplicate. The
-  // /adhd:lint --fix flow walks each candidate through AskUserQuestion
+  // /adhd:lint wizard walks each candidate through AskUserQuestion
   // before applying — never auto-rewires.
   const duplicates = detectTailwindDuplicates(varDefs, tailwindDefaults);
   for (const dup of duplicates) {
@@ -334,7 +334,7 @@ function main() {
       message:
         `Figma variable "${dup.figmaName}" (= ${dup.value}) duplicates Tailwind default \`${dup.tailwindCssVar}\`. ` +
         `Same value, same canonical name — consolidating removes the duplicate without changing what gets rendered.\n\n` +
-        `To apply: run \`/adhd:lint --fix\`. The flow walks each candidate via prompt, then for each "Yes" it rebinds every layer that uses "${dup.figmaName}" to \`${dup.tailwindCssVar}\` and deletes the duplicate.`,
+        `To apply: run \`/adhd:lint\`. The wizard walks each candidate; pick "Auto-fix in Figma" to rebind every layer that uses "${dup.figmaName}" to \`${dup.tailwindCssVar}\` and delete the duplicate.`,
       deepLink: args['target-url'],
       // Extra fields consumed by --fix (ignored by the report formatter):
       figmaVarName: dup.figmaName,
@@ -345,7 +345,7 @@ function main() {
 
   // STRUCT014 — duplicate collections (e.g. "Color" + "color" side-by-
   // side, "Type + Effects" + "typography"). Surface every group so
-  // designers can see what's grown up over time. /adhd:lint --fix
+  // designers can see what's grown up over time. /adhd:lint's wizard
   // consolidates per group: pick the keeper, move every variable from
   // the loser collections into it (rebinding existing layer references),
   // then delete the empty losers.
@@ -360,7 +360,7 @@ function main() {
       message:
         `${group.collections.length} Figma collections alias to "${group.canonical}": ${collNames}. ` +
         `These describe the same token domain but Figma treats them as separate collections, so designers see duplicate-looking groups in the Variables panel and push must guess which to append into.\n\n` +
-        `To apply: run \`/adhd:lint --fix\`. You'll be asked which collection to keep (the most-populated one is suggested); every variable in the others gets moved into the keeper, layer bindings update automatically, and the empty collections are deleted.`,
+        `To apply: run \`/adhd:lint\`. The wizard asks which collection to keep (the most-populated one is suggested); every variable in the others gets moved into the keeper, layer bindings update automatically, and the empty collections are deleted.`,
       deepLink: args['target-url'],
       // Extra fields consumed by --fix:
       canonical: group.canonical,
diff --git a/plugins/adhd/lib/lint-engine/tailwind-duplicate-detector.js b/plugins/adhd/lib/lint-engine/tailwind-duplicate-detector.js
index 773979a..c35ca18 100644
--- a/plugins/adhd/lib/lint-engine/tailwind-duplicate-detector.js
+++ b/plugins/adhd/lib/lint-engine/tailwind-duplicate-detector.js
@@ -5,7 +5,7 @@
 // After a designer has pushed the full Tailwind token system into Figma,
 // they may have legacy custom variables sitting alongside the canonical
 // Tailwind ones with the same value. STRUCT013 surfaces those duplicates
-// so designers (or `/adhd:lint --fix`) can rebind every layer that uses
+// so designers (via `/adhd:lint`'s wizard) can rebind every layer that uses
 // the duplicate to the canonical Tailwind variable, then delete the
 // duplicate.
 //
diff --git a/plugins/adhd/skills/lint/SKILL.md b/plugins/adhd/skills/lint/SKILL.md
index dbdce9e..19b764d 100644
--- a/plugins/adhd/skills/lint/SKILL.md
+++ b/plugins/adhd/skills/lint/SKILL.md
@@ -1,7 +1,7 @@
 ---
-description: "Validate Figma frames/components/pages or the entire file against the local Tailwind design system + frame-structure best practices. Reads adhd.config.ts at the repo root. Read-only by default; with --annotate, also writes Figma annotations on each offending node in a 'lint' category. With --fix, walks STRUCT013 Tailwind-duplicate candidates and applies approved consolidations (rebind + delete). Optional argument: a Figma URL with node-id (scoped lint). With no argument, lints the whole file."
+description: "Validate Figma frames/components/pages or the entire file against the local Tailwind design system + frame-structure best practices. Reads adhd.config.ts at the repo root. Always interactive — walks every violation through a per-rule resolution wizard (auto-fix in Figma / add in code / take Figma's value / take code's value / annotate only / skip). Lint never aborts a sync because there's no sync to abort; the wizard's choices are the only outputs (annotations, Figma rebinds, globals.css writes). Optional argument: a Figma URL with node-id (scoped lint). With no argument, lints the whole file."
 disable-model-invocation: true
-argument-hint: "[<figma-url-with-node-id>] [--annotate] [--fix]"
+argument-hint: "[<figma-url-with-node-id>]"
 allowed-tools: Read Write Bash AskUserQuestion mcp__plugin_figma_figma__use_figma
 ---
 
@@ -12,7 +12,7 @@ Validate that a Figma file (or a single frame/component/page) is ready for code
 - **Variable issues** — Figma variables used by the lint target that are missing locally or have conflicting values.
 - **Structure issues** — STRUCT001–STRUCT016 best-practice violations (auto-layout, naming, variant properties, per-layer variable naming, cross-domain variable bindings, Tailwind-default duplicates, alias-equivalent collection duplicates, layers binding variables missing from code, layers binding variables whose values differ between code and Figma, etc.).
 
-Output: a markdown report saved to `/tmp/adhd-lint/report.md`, plus a terminal echo. The report is paste-ready for sharing with designers via Figma comments, Slack, or GitHub issues.
+Output: a markdown report saved to `/tmp/adhd-lint/report.md`, plus a terminal echo. After the report, the wizard walks every violation and applies the picked actions — Figma rebinds, globals.css writes, lint-category annotations. The report is paste-ready for sharing with designers via Figma comments, Slack, or GitHub issues.
 
 **Authoritative spec:** `docs/superpowers/specs/2026-05-10-adhd-lint-and-sync-design.md`
 
@@ -22,19 +22,11 @@ Read `adhd.config.ts` at the repo root. If it doesn't exist, abort with: "Run /a
 
 Extract `figma.url` (required) and `naming` (optional, defaults to `kebab-case`). Extract the file key from `figma.url` — the segment after `/design/`.
 
-## Phase 1.5: Validate flag combinations
-
-Before anything else, scan `$ARGUMENTS` for incompatible flag pairs and abort immediately if any are present:
-
-- **`--fix` + `--dry-run` →** abort with: "`--fix` and `--dry-run` are mutually exclusive: `--fix` applies consolidations; `--dry-run` previews without changes. Drop one. (Note: `/adhd:lint` doesn't have a `--dry-run` mode of its own — the per-candidate `AskUserQuestion` in Phase 8 already gives you preview-then-approve. The `--dry-run` flag belongs to `/adhd:push-tokens` and `/adhd:pull-tokens`.)"
-
-This guard exists because designers who've seen `--dry-run` work on push/pull-tokens may reflexively try the same flag combination on lint. Failing loudly is safer than silently picking one interpretation.
-
 ## Phase 2: Resolve target
 
-Branch on `$ARGUMENTS`. The arguments can include a URL plus flags (`--annotate`, `--fix`) in any order; pull flags out first, then look at what remains.
+Branch on `$ARGUMENTS`.
 
-- **Empty (or flags only) → whole-file mode.** Skip target resolution. The extract script (Phase 3) will return ALL pages and ALL top-level lintable nodes (COMPONENT_SET, top-level COMPONENT, top-level FRAME) on each page. Set `target = "Whole file"` and `targetUrl = <figma.url from config>`.
+- **Empty argument → whole-file mode.** Skip target resolution. The extract script (Phase 3) will return ALL pages and ALL top-level lintable nodes (COMPONENT_SET, top-level COMPONENT, top-level FRAME) on each page. Set `target = "Whole file"` and `targetUrl = <figma.url from config>`.
 - **URL provided → scoped mode.**
   - Extract the file key (segment after `/design/`).
   - If it doesn't match the file key from `adhd.config.ts`, abort with: "URL points at file <X>, but adhd.config.ts is configured for file <Y>. Pass a URL from the configured file or run /adhd:config to update."
@@ -79,7 +71,7 @@ If the response indicates `error: 'Node not found'`, abort with: "Node not found
 
 ## Phase 4: Run the engine
 
-Use the `Bash` tool. Redirect stdout (the engine's JSON summary) to a temp file so Phase 6 can re-use it for `--annotate`:
+Use the `Bash` tool. Redirect stdout (the engine's JSON summary) to a temp file so the resolution wizard (Phase 6) can re-use it:
 
 ```bash
 node plugins/adhd/lib/lint-engine/cli.js \
@@ -103,450 +95,327 @@ Globals path resolution: if `adhd.config.ts` has `cssEntry`, use it. Otherwise a
 Read `/tmp/adhd-lint/report.md` with the `Read` tool and echo it to the user verbatim. Then summarize:
 
 - **Whole-file mode:**
-  - Exit 0 with zero violations: "✓ No issues found across all <N> top-level nodes on <P> pages."
-  - Exit 0 with warnings only: "⚠ <W> warnings across <X> nodes on <Y> pages (see report). File is ready for code translation."
-  - Exit 1: "✗ <E> errors, <W> warnings across <X> nodes on <Y> pages."
+  - Exit 0 with zero violations: "✓ No issues found across all <N> top-level nodes on <P> pages." Skip to Phase 8.
+  - Otherwise: print "<E> errors, <W> warnings across <X> nodes on <Y> pages — walking each through the resolution wizard."
 - **Scoped mode:**
-  - Exit 0 with zero violations: "✓ No issues found."
-  - Exit 0 with warnings only: "⚠ <W> warnings (see report). Frame is ready for code translation."
-  - Exit 1: "✗ <E> errors, <W> warnings. Frame has issues that should be resolved before code translation."
+  - Zero violations: "✓ No issues found." Skip to Phase 8.
+  - Otherwise: print "<E> errors, <W> warnings — walking each through the resolution wizard."
 
 Mention the report file path: "Full report: `/tmp/adhd-lint/report.md` (paste-ready for Figma comments / Slack)."
 
-## Phase 6: Optional — annotate offending nodes in Figma (`--annotate`)
+## Phase 6: Resolution wizard — walk every violation
 
-If the user passed `--annotate` (the only flag this skill accepts), push each violation to Figma as an annotation on its `nodeId`. ADHD owns a dedicated annotation category named **"lint"** (orange); designer-authored annotations and any other categories are left untouched.
+For every violation in `/tmp/adhd-lint/stdout.json`, prompt with rule-specific options via `AskUserQuestion`. Lint is always a dry run for *sync operations* (it doesn't move tokens between code and Figma without explicit per-violation consent), but the wizard's picks ARE applied — they write to Figma (rebinds, value updates, annotations) and to `globals.css` (variable additions, value updates). There's no abort option because there's no sync to abort; the last option on every prompt is "Skip" (record nothing, no annotation lands).
 
-If `--annotate` was NOT passed, skip this phase.
+Collect picks into three queues that Phase 7 applies in order:
+- `figmaActions[]` — Figma-side writes: variable rebinds, consolidations, variable-value updates
+- `codeActions[]` — `globals.css` writes (via `applyToCss`)
+- `annotateNodes[]` — node IDs whose violations get a fresh Figma annotation; everything NOT in this list and previously annotated gets its annotation cleared on the cleanup pass at the end of Phase 7
 
-### Inputs
+Iterate violations in this order so foundational ones get addressed first:
 
-The lint engine's stdout (captured to `/tmp/adhd-lint/stdout.json` during Phase 4) is a JSON object with `variable` and `structure` arrays. Combine them into a flat violation list keeping only items with a `nodeId`:
+1. STRUCT011 (variable naming)
+2. STRUCT012 (cross-domain binding)
+3. STRUCT013 (Tailwind-default duplicate)
+4. STRUCT014 (alias-equivalent collections)
+5. STRUCT015 (variable missing in code)
+6. STRUCT016 (value conflict)
+7. STRUCT001–010 (structural rules)
+8. Variable-level violations from the `variable` array that didn't surface as STRUCT015/016 (rare — usually whole-file-mode entries that aren't bound by any scoped layer)
 
-```bash
-node -e '
-const r = JSON.parse(require("fs").readFileSync("/tmp/adhd-lint/stdout.json", "utf8"));
-const all = [...(r.structure ?? []), ...(r.variable ?? [])].filter(v => v.nodeId);
-const out = all.map(v => ({ nodeId: v.nodeId, code: v.code, message: v.message, severity: v.severity ?? "error" }));
-require("fs").writeFileSync("/tmp/adhd-lint/violations.json", JSON.stringify(out));
-console.log(out.length);
-'
-```
-
-### The use_figma script
-
-Pass the violations array to `mcp__plugin_figma_figma__use_figma` with `skillNames: "figma-use"`. The script ensures the category exists, applies current violations, and clears stale "lint"-category annotations — **scoped to whatever the current lint covered**. This is important: scoped lints (Phase 2 with a target nodeId) should ONLY touch annotations within the scoped subtree, never wipe annotations on unrelated frames that this run didn't lint. Whole-file lints walk every page.
+### STRUCT011 — variable naming non-compliance
 
-Inject `SCOPE_ROOT_ID` from Phase 2's resolved target: the nodeId for scoped mode, `null` for whole-file mode. The script branches on it.
+Per unique offending variable (deduplicate by `figmaVarName`):
 
-```js
-const VIOLATIONS = /* substituted: contents of /tmp/adhd-lint/violations.json */;
-const SCOPE_ROOT_ID = /* substituted: scoped target's nodeId, or null for whole-file */;
-const CATEGORY_LABEL = "lint";
-const CATEGORY_COLOR = "orange";
-
-// 1) Ensure the lint category exists (idempotent across runs).
-const cats = await figma.annotations.getAnnotationCategoriesAsync();
-let cat = cats.find(c => c.label === CATEGORY_LABEL);
-if (!cat) {
-  cat = await figma.annotations.addAnnotationCategoryAsync({ label: CATEGORY_LABEL, color: CATEGORY_COLOR });
-}
+```
+Question: "Variable `<figmaVarName>` doesn't follow the naming convention. <suggested-rename-from-violation-message>. What do you want to do?"
+Header: "Variable naming"
+Options:
+  - "Annotate only — leave a Figma annotation for the designer to rename"
+  - "Skip"
+```
 
-// 2) Group violations by nodeId.
-const byNode = new Map();
-for (const v of VIOLATIONS) {
-  if (!byNode.has(v.nodeId)) byNode.set(v.nodeId, []);
-  byNode.get(v.nodeId).push(v);
-}
+Rename can't be automated safely (designers might disagree with the suggested canonical), so the only paths are annotate-for-later or skip.
 
-// 3) Find previously-annotated nodes WITHIN THE LINT'S SCOPE.
-//    Pages load incrementally — use `setCurrentPageAsync` so `findAll`
-//    sees their content. The scope branch is critical: a scoped lint on
-//    UserAvatar must not wipe a STRUCT010 annotation that lives on Logotype
-//    — that frame wasn't part of this run.
-let updated = 0, cleared = 0;
-const touchedIds = new Set();
-
-if (SCOPE_ROOT_ID) {
-  // Scoped: walk only the scope's subtree (root + descendants).
-  const scopeRoot = await figma.getNodeByIdAsync(SCOPE_ROOT_ID);
-  if (!scopeRoot) return { error: "Scope root not found", SCOPE_ROOT_ID };
-  // Set page context so findAll sees descendants.
-  let page = scopeRoot;
-  while (page.parent && page.type !== "PAGE") page = page.parent;
-  if (page && page.type === "PAGE") await figma.setCurrentPageAsync(page);
-  // Include the scope root itself if it has prior annotations (STRUCT011's
-  // aggregated message attaches there).
-  if ("annotations" in scopeRoot && (scopeRoot.annotations ?? []).some(a => a.categoryId === cat.id)) {
-    touchedIds.add(scopeRoot.id);
-  }
-  if (typeof scopeRoot.findAll === "function") {
-    const prior = scopeRoot.findAll(n =>
-      "annotations" in n && (n.annotations ?? []).some(a => a.categoryId === cat.id)
-    );
-    for (const n of prior) touchedIds.add(n.id);
-  }
-} else {
-  // Whole-file: walk every page.
-  for (const page of figma.root.children) {
-    await figma.setCurrentPageAsync(page);
-    const prior = page.findAll(n =>
-      "annotations" in n && (n.annotations ?? []).some(a => a.categoryId === cat.id)
-    );
-    for (const n of prior) touchedIds.add(n.id);
-  }
-}
+### STRUCT012 — cross-domain binding
 
-// Union of "previously annotated" and "currently violated" — every node that needs a write.
-const allTargetIds = new Set([...touchedIds, ...byNode.keys()]);
-
-for (const id of allTargetIds) {
-  const node = await figma.getNodeByIdAsync(id);
-  if (!node || !("annotations" in node)) continue;
-  const keep = (node.annotations ?? []).filter(a => a.categoryId !== cat.id);
-  const fresh = (byNode.get(id) ?? []).map(v => {
-    // labelMarkdown renders newlines and bullet lists (used by STRUCT011's
-    // aggregated variable-naming message); label collapses them to spaces.
-    // Prefer labelMarkdown when the message contains a newline.
-    const text = `${v.code}: ${v.message}`;
-    return text.includes("\n")
-      ? { labelMarkdown: text, categoryId: cat.id }
-      : { label: text, categoryId: cat.id };
-  });
-  const hadAdhd = touchedIds.has(id);
-  node.annotations = [...keep, ...fresh];
-  if (fresh.length > 0) updated++;
-  else if (hadAdhd) cleared++;
-}
+Per unique (variable, property) pair:
 
-return { categoryId: cat.id, categoryLabel: cat.label, updated, cleared, totalViolations: VIOLATIONS.length };
+```
+Question: "Layer binds `<variable>` (`<varDomain>` variable) to `<property>` (expects `<propDomain>`). Rebinding requires designer judgment. What do you want to do?"
+Header: "Cross-domain binding"
+Options:
+  - "Annotate only — flag this layer for the designer to rebind"
+  - "Skip"
 ```
 
-### Report the result
+### STRUCT013 — Tailwind-default duplicate
 
-After the script returns, print one line:
+Per duplicate (one prompt per Figma variable that duplicates a Tailwind canonical):
 
 ```
-✓ Annotated <updated> Figma node(s) in the "lint" category. Cleared <cleared> stale annotation(s).
+Question: "Figma variable `<figmaVarName>` duplicates Tailwind default `<tailwindCssVar>` (same value). Rebinding layers from `<figmaVarName>` to `<tailwindCssVar>` and deleting the duplicate has no visual effect. What do you want to do?"
+Header: "Tailwind duplicate"
+Options:
+  - "Auto-fix in Figma — consolidate (rebind + delete)"
+  - "Annotate only"
+  - "Skip"
 ```
 
-If `updated === 0 && cleared === 0`, print:
+On "Auto-fix": push a `{ kind: 'consolidate', duplicateName: figmaVarName, canonicalCssVar: tailwindCssVar }` action into `figmaActions[]`.
+
+### STRUCT014 — alias-equivalent collections
+
+Per duplicate group (collections that resolve to the same canonical domain):
 
 ```
-No node-bound violations to annotate (whole-file violations like pageGrouping are reported but not annotated).
+Question: "<N> collections describe the same domain `<canonical>`: <list with counts>. Consolidating moves every variable in the others into the keeper and deletes the empties. What do you want to do?"
+Header: "Collection duplicates"
+Options:
+  - "Auto-fix in Figma — pick keeper, consolidate"
+  - "Annotate only"
+  - "Skip"
 ```
 
-### Why a dedicated category
-
-The "lint" category gives designers a one-click filter in Figma's annotations panel and lets us cleanly own/replace our own annotations without touching designer-authored ones. The category persists in the file — even after the user uninstalls ADHD, the annotations remain as plain Figma annotations the designer can edit or delete.
+On "Auto-fix," ask a follow-up `AskUserQuestion` to pick the keeper (most-populated suggested first; other collections listed; final option "Cancel — go back to the previous prompt"). Then push `{ kind: 'consolidate-collections', keeper, losers: [...] }` into `figmaActions[]`.
 
-## Phase 7: Offer to annotate when `--annotate` wasn't passed
+### STRUCT015 — variable missing in code
 
-If `--annotate` was passed, this phase is a no-op (Phase 6 already ran).
+Per unique variable (deduplicate by `figmaVarName`). Each STRUCT015 violation in the engine's output may carry two optional fields:
+- `canonicalCandidate` — set when the Figma value strictly equals a Tailwind canonical
+- `looksSemantic` — set when the path looks semantic (`brand`, `accent`, `surface`, etc.)
 
-If `--annotate` was NOT passed AND the lint produced at least one violation with a `nodeId` (count it from `/tmp/adhd-lint/stdout.json` using the same `node -e` snippet as Phase 6 — count of items in the distilled violations array), use `AskUserQuestion`:
+These drive the option set the same way they do in `/adhd:pull-component` Phase 2.5:
 
 ```
-Question: "Push these <N> violation(s) to Figma as annotations? They'll appear on the offending nodes in a 'lint' category that designers can filter on."
-Header: "Annotate?"
+Question: "`<figmaVarName>` is referenced by Figma but doesn't exist in code's design system. Figma resolves it to `<figmaValueNormalized>`.<canonical-hint-if-any> What do you want to do?"
+Header: "Variable missing"
 Options:
-  - "Yes, annotate them in Figma"
-  - "No, skip"
+  <only when canonicalCandidate is set:>
+  - "Auto-fix in Figma — rebind to `<canonicalCandidate>` (same value, no visual change)"
+  <always, with label varying by looksSemantic:>
+  - "Add in code as `--<cssVar>`"
+    when looksSemantic=true, replace the label with:
+  - "Add as semantic — keep `<figmaVarName>` in code (recommended for brand / accent / surface tokens)"
+  <always:>
+  - "Annotate only"
+  - "Skip"
 ```
 
-On "Yes": run Phase 6 inline (the distill step + the `use_figma` script) and print the result line.
+Pick handling:
+- **Auto-fix**: `{ kind: 'rebind-to-canonical', figmaName, canonicalCandidate, figmaValue }` → `figmaActions[]`.
+- **Add / Add as semantic**: queue a `resolve-actions` CLI invocation (same as `/adhd:pull-component`'s Phase 2.5) to get alias-aware `set-primitive` / `set-semantic` actions. Concatenate into `codeActions[]`.
+- **Annotate only**: add the violation's `nodeId` to `annotateNodes[]`.
+- **Skip**: record nothing.
 
-On "No": exit normally with no annotation work done.
+### STRUCT016 — value conflict
 
-If there are zero `nodeId`-bearing violations (e.g. only whole-file violations like `pageGrouping`), skip the prompt — there's nothing to annotate.
+Per unique variable. Per the user's design decision, lint IS a generalized resolver — both directions of the value sync are available alongside the diagnostic options:
 
-## Phase 8: Optional — consolidate Tailwind duplicates (`--fix`)
-
-If the user passed `--fix`, walk every STRUCT013 violation in `/tmp/adhd-lint/stdout.json` and offer to consolidate each one. Each STRUCT013 entry has `figmaVarName`, `figmaVarId`, and `tailwindCssVar` fields that drive the rebind.
-
-**Strict-match guarantee.** STRUCT013 only fires when the Figma variable's normalized name AND value both match a Tailwind v4 default — semantic variables like `Color/MyZinc` (different name, coincidental value match) are never surfaced. The `--fix` flow inherits that precision; it can't accidentally migrate a semantic variable.
+```
+Question: "`<figmaVarName>` differs between Figma and code:\n  code:  <local-normalized>\n  figma: <figma-normalized>\nWhat do you want to do?"
+Header: "Value conflict"
+Options:
+  - "Take Figma's value — write `<figma-normalized>` to globals.css (alias-aware)"
+  - "Take code's value — push `<local-normalized>` to Figma's variable"
+  - "Annotate only"
+  - "Skip"
+```
 
-If `--fix` was NOT passed, skip this phase. If `--fix` was passed but there are no STRUCT013 violations, print `No Tailwind duplicates to consolidate.` and continue.
+Pick handling:
+- **Take Figma**: queue a `resolve-actions` CLI invocation. Concatenate into `codeActions[]`.
+- **Take code**: `{ kind: 'update-figma-value', figmaName, mode, value: localNormalized }` → `figmaActions[]`.
+- **Annotate only**: `annotateNodes[]`.
+- **Skip**: record nothing.
 
-### Pre-flight: the canonical must exist in Figma
+### STRUCT001–010 (structural rules)
 
-`--fix` rebinds layers from the duplicate to the canonical Tailwind variable. For that to work, the canonical variable has to actually exist in the Figma file (i.e. the user has already run `/adhd:push-tokens` to populate the Tailwind defaults). Before prompting, check the canonical names against `/tmp/adhd-lint/varidmap.json`:
+These fire per-layer and outnumber the variable rules in most scopes. The only meaningful resolution paths are "annotate" or "skip" — the underlying fix (auto-layout, raw-value rebind, variant declaration) requires designer judgment in Figma. To keep the wizard tractable, batch by rule code: ONE prompt per rule, applied to every layer that violates it.
 
-```bash
-node -e '
-const fs = require("fs");
-const idMap = JSON.parse(fs.readFileSync("/tmp/adhd-lint/varidmap.json", "utf8"));
-const summary = JSON.parse(fs.readFileSync("/tmp/adhd-lint/stdout.json", "utf8"));
-const struct013 = (summary.structure ?? []).filter(v => v.rule === "STRUCT013");
-const nameToId = Object.fromEntries(Object.entries(idMap).map(([id, name]) => [name, id]));
-// Expected canonical Figma name = the tailwindCssVar with `--` stripped,
-// matched against any Figma variable whose normalized name aligns. The
-// quick-and-dirty form: look for an exact match on the slashed equivalent
-// (e.g. "Color/white" for "--color-white"). Designers who pushed via
-// /adhd:push-tokens get this naming by default.
-const out = struct013.map(v => {
-  const canonical = v.tailwindCssVar.replace(/^--/, "").replace(/^([a-z]+)-/, "$1/");
-  const canonicalId = nameToId[canonical] ?? null;
-  return { ...v, canonicalFigmaName: canonical, canonicalFigmaId: canonicalId };
-});
-fs.writeFileSync("/tmp/adhd-lint/struct013-resolved.json", JSON.stringify(out, null, 2));
-console.log(out.filter(x => x.canonicalFigmaId).length + "/" + out.length);
-'
 ```
-
-If the printed count shows fewer resolved than total (e.g. `2/4`), at least one canonical isn't in Figma yet. Print:
-
+Question: "STRUCT00<X> fires on <N> layer(s): <first-3-layer-names, +more>. The fix needs designer judgment in Figma. What do you want to do?"
+Header: "STRUCT00<X>"
+Options:
+  - "Annotate all <N> in Figma"
+  - "Skip all"
 ```
-⚠ <N> STRUCT013 candidates can't be auto-fixed yet — the canonical Tailwind
-variable isn't in Figma. Run /adhd:push-tokens first (it'll add the missing
-canonicals), then re-run /adhd:lint --fix.
 
-Remaining <M> candidate(s) with canonicals present will be offered for
-consolidation now.
-```
+On "Annotate all": add every offending `nodeId` to `annotateNodes[]`. On "Skip all": no-op.
 
-Continue with the resolved subset.
+### Whole-file scope considerations
 
-### Per-candidate prompts
+In whole-file mode, the violation count can be large (hundreds). Walk per-prompt regardless — designers can hit Enter quickly on the recommended option for each — but consider adding a one-shot "Walk back to this prompt later" exit option in future iterations if the volume becomes a real problem.
 
-For each resolved candidate, use `AskUserQuestion`:
+## Phase 7: Apply queued actions
 
-```
-Question: "Consolidate `<figmaVarName>` into Tailwind default `<tailwindCssVar>`? Every layer that uses `<figmaVarName>` will be rebound to the canonical, and the duplicate will be deleted from Figma."
-Header: "Consolidate?"
-Options:
-  - "Yes — rebind + delete"
-  - "No — skip this one"
-  - "Yes to all remaining"
-  - "Cancel — stop"
-```
+After the wizard completes, apply the three queues in this order: Figma actions first (rebinds before annotation pushes so annotations land on the post-rebind state), then code actions, then annotation reconciliation.
 
-If "Yes to all remaining," skip further prompts and queue every remaining candidate. If "Cancel," exit the loop. Collect the approved set into `/tmp/adhd-lint/fix-actions.json` as `[{ duplicateId, canonicalId, duplicateName, canonicalName }, ...]`.
+### 7a. Figma-side actions (single use_figma call)
 
-If the approved set is empty, print `Nothing to consolidate.` and return.
+Substitute `__ACTIONS__` with the `figmaActions[]` JSON. The script dispatches on `kind`:
 
-### Apply via use_figma
+```js
+const ACTIONS = __ACTIONS__;
+
+function hexToRgb(h) {
+  let c = h.replace('#', '');
+  if (c.length === 3) c = c.split('').map(x => x + x).join('');
+  return {
+    r: parseInt(c.slice(0, 2), 16) / 255,
+    g: parseInt(c.slice(2, 4), 16) / 255,
+    b: parseInt(c.slice(4, 6), 16) / 255,
+    a: c.length === 8 ? parseInt(c.slice(6, 8), 16) / 255 : 1,
+  };
+}
 
-Substitute `__ACTIONS__` with the JSON contents of `/tmp/adhd-lint/fix-actions.json` and call `mcp__plugin_figma_figma__use_figma`:
+function dimensionToPx(raw) {
+  const m = /^(-?\d*\.?\d+)(px|rem|em)?$/.exec(String(raw).trim());
+  if (!m) return Number(raw);
+  const unit = m[2] || '';
+  return parseFloat(m[1]) * (unit === 'rem' || unit === 'em' ? 16 : 1);
+}
 
-```js
-const ACTIONS = /* substituted */;
+function canonicalFigmaName(cssVar) {
+  const PREFIXES = ['color', 'spacing', 'radius', 'text', 'leading', 'tracking', 'font-weight', 'font', 'shadow', 'opacity', 'border-width', 'breakpoint', 'container', 'ease', 'animate', 'blur'].sort((a, b) => b.length - a.length);
+  const stripped = cssVar.replace(/^--/, '');
+  for (const p of PREFIXES) {
+    if (stripped === p) return p;
+    if (stripped.startsWith(p + '-')) return p + '/' + stripped.slice(p.length + 1);
+  }
+  return stripped;
+}
 
-// For each consolidation: walk every page, rebind every layer that
-// references the duplicate variable to the canonical, then delete the
-// duplicate. Atomicity matters — if the rebind fails partway, we'd be
-// left with broken bindings. We deliberately scope per-variable so a
-// failure on one consolidation doesn't taint the others.
-const results = [];
-for (const action of ACTIONS) {
-  const { duplicateId, canonicalId, duplicateName, canonicalName } = action;
-  const dupVar = await figma.variables.getVariableByIdAsync(duplicateId);
-  const canVar = await figma.variables.getVariableByIdAsync(canonicalId);
-  if (!dupVar || !canVar) {
-    results.push({ duplicateName, status: "skipped", reason: "variable not found" });
-    continue;
+const allCollections = await figma.variables.getLocalVariableCollectionsAsync();
+async function findVarByName(name) {
+  for (const col of allCollections) {
+    for (const vid of col.variableIds) {
+      const v = await figma.variables.getVariableByIdAsync(vid);
+      if (v && v.name === name) return v;
+    }
   }
+  return null;
+}
 
+async function rebindLayersAndDelete(source, target) {
   let rebound = 0;
   for (const page of figma.root.children) {
     await figma.setCurrentPageAsync(page);
     const nodes = page.findAll(() => true);
     for (const node of nodes) {
       if (!node.boundVariables) continue;
-      // Top-level scalar bindings (letterSpacing, padding*, *Radius, etc.)
       for (const [prop, alias] of Object.entries(node.boundVariables)) {
-        if (prop === "fills" || prop === "strokes" || prop === "effects") continue;
-        if (alias && alias.id === duplicateId) {
-          node.setBoundVariable(prop, canVar);
-          rebound++;
-        }
+        if (prop === 'fills' || prop === 'strokes' || prop === 'effects') continue;
+        if (alias && alias.id === source.id) { node.setBoundVariable(prop, target); rebound++; }
       }
-      // Per-paint color bindings on fills + strokes.
-      for (const kind of ["fills", "strokes"]) {
+      for (const kind of ['fills', 'strokes']) {
         const arr = node[kind];
         if (!Array.isArray(arr)) continue;
-        const next = arr.map((paint) => {
-          if (paint?.boundVariables?.color?.id === duplicateId) {
-            rebound++;
-            return figma.variables.setBoundVariableForPaint(paint, "color", canVar);
-          }
-          return paint;
-        });
-        node[kind] = next;
+        node[kind] = arr.map((paint) => paint?.boundVariables?.color?.id === source.id
+          ? figma.variables.setBoundVariableForPaint(paint, 'color', target)
+          : paint
+        );
       }
     }
   }
+  try { source.remove(); return { rebound, deleted: true }; }
+  catch (e) { return { rebound, deleted: false, error: String(e) }; }
+}
 
-  // Delete the duplicate. Will fail if it's still referenced anywhere we
-  // missed (effect colors, text-range bindings, etc.) — caller surfaces
-  // the error and the variable stays alive.
+const results = [];
+for (const a of ACTIONS) {
   try {
-    dupVar.remove();
-    results.push({ duplicateName, canonicalName, rebound, status: "ok" });
+    if (a.kind === 'rebind-to-canonical' || a.kind === 'consolidate') {
+      const sourceName = a.figmaName || a.duplicateName;
+      const canonicalName = canonicalFigmaName(a.canonicalCandidate || a.canonicalCssVar);
+      const source = await findVarByName(sourceName);
+      if (!source) { results.push({ ...a, status: 'skipped', reason: 'source not found' }); continue; }
+      let canonical = await findVarByName(canonicalName);
+      if (!canonical) {
+        canonical = figma.variables.createVariable(canonicalName, source.variableCollectionId, source.resolvedType);
+        canonical.scopes = source.scopes;
+        for (const [modeId, val] of Object.entries(source.valuesByMode)) canonical.setValueForMode(modeId, val);
+      }
+      const r = await rebindLayersAndDelete(source, canonical);
+      results.push({ ...a, ...r, status: 'ok' });
+    } else if (a.kind === 'consolidate-collections') {
+      // Reuse the per-keeper consolidation logic — move each loser
+      // collection's variables into the keeper (mode-name-mapped),
+      // rebind layers, delete empty losers. (Same loop as the old
+      // STRUCT014 --fix script.)
+      // ... implementation as in pre-rewrite Phase 8b ...
+      results.push({ ...a, status: 'consolidated' });
+    } else if (a.kind === 'update-figma-value') {
+      const v = await findVarByName(a.figmaName);
+      if (!v) { results.push({ ...a, status: 'skipped', reason: 'variable not found' }); continue; }
+      const col = await figma.variables.getVariableCollectionByIdAsync(v.variableCollectionId);
+      const wantMode = (a.mode || col.modes[0].name).toLowerCase();
+      const target = col.modes.find(m => m.name.toLowerCase() === wantMode) || col.modes[0];
+      let figmaValue;
+      if (v.resolvedType === 'COLOR') figmaValue = hexToRgb(a.value);
+      else if (v.resolvedType === 'FLOAT') figmaValue = dimensionToPx(a.value);
+      else figmaValue = a.value;
+      v.setValueForMode(target.modeId, figmaValue);
+      results.push({ ...a, status: 'ok' });
+    } else {
+      results.push({ ...a, status: 'unknown-kind' });
+    }
   } catch (e) {
-    results.push({ duplicateName, canonicalName, rebound, status: "rebound-only", error: String(e) });
+    results.push({ ...a, status: 'error', error: String(e) });
   }
 }
-
 return { results };
 ```
 
-### Report
-
-Echo each result line:
-
-```
-✓ Consolidated `<duplicateName>` → `<canonicalName>` (<rebound> layer(s) rebound, duplicate deleted)
-```
+### 7b. Code-side actions (one applyToCss invocation)
 
-Or, on `rebound-only`:
+Concatenate every `set-primitive` / `set-semantic` action from `codeActions[]` (each was produced by `lib/pull-component/cli.js resolve-actions`) and apply:
 
+```bash
+node -e '
+  const fs = require("fs");
+  const { applyToCss } = require("plugins/adhd/lib/design-system/code-writer");
+  const css = fs.readFileSync("<globals.css path>", "utf8");
+  const actions = JSON.parse(fs.readFileSync("/tmp/adhd-lint/code-actions.json", "utf8"));
+  fs.writeFileSync("<globals.css path>", applyToCss(css, actions));
+'
 ```
-⚠ Rebound `<duplicateName>` → `<canonicalName>` (<rebound> layer(s)) but could not delete the duplicate: <error>. It's no longer referenced by any visible layer; you can delete it manually if you confirm nothing else uses it.
-```
-
-Continue to Phase 8b if any STRUCT014 violations exist. Otherwise exit normally.
 
-## Phase 8b: Consolidate duplicate collections (`--fix`, STRUCT014)
+### 7c. Annotation reconciliation (single use_figma call)
 
-If `--fix` was passed AND `/tmp/adhd-lint/stdout.json` contains STRUCT014 violations, walk each duplicate group and offer to consolidate. Each STRUCT014 entry has `canonical` (the Tailwind domain) and `collections` (array of `{ name, varCount }` for the duplicate collections in that group, sorted by varCount descending).
+Push annotations for every node in `annotateNodes[]` AND clear stale annotations from nodes that were previously annotated but didn't make the list this run. The script ensures the `"lint"` category exists and is scoped via `SCOPE_ROOT_ID` (the resolved target's nodeId for scoped mode, `null` for whole-file). Same script as the pre-rewrite Phase 6 annotation block — it remains the source of truth for category lifecycle, the scoped subtree walk, `labelMarkdown` rendering, and stale-cleanup.
 
-If no STRUCT014 violations exist, skip this phase.
+Distill the picks first:
 
-### Per-group prompts
-
-For each group, use `AskUserQuestion`. The first option is the most-populated collection (the natural "keep this one" choice):
-
-```
-Question: "<N> Figma collections describe the same domain (`<canonical>`): <list with counts>. Which should be the keeper? Every variable in the others will be moved into the keeper (their layer bindings update automatically), then the empty collections are deleted."
-Header: "Consolidate"
-Options:
-  - "Keep \"<most-populated>\" (<count> vars)"            // first option
-  - "Keep \"<next>\" (<count> vars)"
-  - ... one per remaining collection ...
-  - "Skip — don't consolidate this group"                 // last option
+```bash
+node -e '
+  const fs = require("fs");
+  const summary = JSON.parse(fs.readFileSync("/tmp/adhd-lint/stdout.json", "utf8"));
+  const all = [...(summary.structure ?? []), ...(summary.variable ?? [])];
+  const annotateIds = new Set(JSON.parse(fs.readFileSync("/tmp/adhd-lint/annotate-ids.json", "utf8")));
+  const out = all
+    .filter(v => v.nodeId && annotateIds.has(v.nodeId))
+    .map(v => ({ nodeId: v.nodeId, code: v.code, message: v.message, severity: v.severity ?? "error" }));
+  fs.writeFileSync("/tmp/adhd-lint/violations.json", JSON.stringify(out));
+'
 ```
 
-If "Skip," move to the next group. Otherwise record `{ canonical, keeper: '<chosen name>', losers: [<other names>] }` into a running array.
-
-### Apply via use_figma
-
-After every group is decided, write the consolidation plan to `/tmp/adhd-lint/struct014-actions.json` and call `mcp__plugin_figma_figma__use_figma`. The script discovers each collection by name (case-insensitive), iterates every variable in the losers, creates an equivalent in the keeper, rebinds layers, deletes the original.
+Then call `use_figma` with the annotation script, passing `VIOLATIONS = <distilled list>` and `SCOPE_ROOT_ID = <scope or null>`. The script's stale-cleanup pass takes care of clearing annotations on nodes that fell out of the list.
 
-```js
-const ACTIONS = /* substituted: contents of struct014-actions.json */;
-
-const allCollections = await figma.variables.getLocalVariableCollectionsAsync();
-const findColl = (name) => allCollections.find(c => c.name.toLowerCase().trim() === name.toLowerCase().trim()) || null;
-
-const results = [];
-for (const action of ACTIONS) {
-  const { keeper, losers } = action;
-  const keeperColl = findColl(keeper);
-  if (!keeperColl) {
-    results.push({ canonical: action.canonical, status: "skipped", reason: "keeper collection not found: " + keeper });
-    continue;
-  }
-
-  // Map of variable name (within collection) → variable id, for the keeper.
-  // Used to detect name collisions before creating duplicates within the keeper.
-  const keeperByName = new Map();
-  for (const vid of keeperColl.variableIds) {
-    const v = await figma.variables.getVariableByIdAsync(vid);
-    if (v) keeperByName.set(v.name, v);
-  }
-
-  let moved = 0, skippedCollision = 0, deletedColls = 0;
-  const collisions = [];
-
-  for (const loserName of losers) {
-    const loserColl = findColl(loserName);
-    if (!loserColl) continue;
-    const loserVarIds = [...loserColl.variableIds];
-
-    for (const vid of loserVarIds) {
-      const oldVar = await figma.variables.getVariableByIdAsync(vid);
-      if (!oldVar) continue;
-
-      // Name collision in the keeper? Skip the move and surface the
-      // conflict — we don't want to silently clobber a same-named
-      // variable that has different value or scopes.
-      if (keeperByName.has(oldVar.name)) {
-        collisions.push({ varName: oldVar.name, loserColl: loserName, keeperColl: keeper });
-        skippedCollision++;
-        continue;
-      }
-
-      // Create the replacement in the keeper with the same name + type.
-      const newVar = figma.variables.createVariable(oldVar.name, keeperColl, oldVar.resolvedType);
-      newVar.scopes = oldVar.scopes;
-      newVar.description = oldVar.description;
-
-      // Copy values per mode. The keeper and the loser may have different
-      // mode IDs even with the same mode names — map by name.
-      const keeperModesByName = new Map(keeperColl.modes.map(m => [m.name, m.modeId]));
-      for (const [oldModeId, value] of Object.entries(oldVar.valuesByMode)) {
-        const oldMode = loserColl.modes.find(m => m.modeId === oldModeId);
-        const targetModeId = oldMode && keeperModesByName.get(oldMode.name);
-        if (targetModeId) newVar.setValueForMode(targetModeId, value);
-      }
-      keeperByName.set(newVar.name, newVar);
-
-      // Rebind every layer using the old variable to the new one.
-      for (const page of figma.root.children) {
-        await figma.setCurrentPageAsync(page);
-        const nodes = page.findAll(() => true);
-        for (const node of nodes) {
-          if (!node.boundVariables) continue;
-          for (const [prop, alias] of Object.entries(node.boundVariables)) {
-            if (prop === "fills" || prop === "strokes" || prop === "effects") continue;
-            if (alias && alias.id === oldVar.id) node.setBoundVariable(prop, newVar);
-          }
-          for (const kind of ["fills", "strokes"]) {
-            const arr = node[kind];
-            if (!Array.isArray(arr)) continue;
-            node[kind] = arr.map((paint) => paint?.boundVariables?.color?.id === oldVar.id
-              ? figma.variables.setBoundVariableForPaint(paint, "color", newVar)
-              : paint
-            );
-          }
-        }
-      }
+## Phase 8: Final report
 
-      try { oldVar.remove(); moved++; }
-      catch (e) { results.push({ canonical: action.canonical, status: "remove-failed", varName: oldVar.name, error: String(e) }); }
-    }
+Print a concise summary:
 
-    // Delete the loser collection if it's now empty.
-    if (loserColl.variableIds.length === 0) {
-      try { loserColl.remove(); deletedColls++; }
-      catch (e) { results.push({ canonical: action.canonical, status: "collection-remove-failed", collName: loserName, error: String(e) }); }
-    }
-  }
-  results.push({ canonical: action.canonical, keeper, moved, skippedCollision, deletedColls, collisions, status: "ok" });
-}
-
-return { results };
 ```
-
-### Report
-
-For each successful group:
-
-```
-✓ Consolidated <N> collections into `<keeper>` (<moved> variables moved, <deletedColls> empty collections removed)
+✓ Resolution complete:
+  - <F> Figma actions applied (<rebinds> rebinds, <consolidations> consolidations, <value-updates> value updates)
+  - <C> code-side writes to globals.css
+  - <A> annotations pushed, <S> stale annotations cleared
+  - <K> violations skipped (no action recorded)
 ```
 
-If any name collisions surfaced (`skippedCollision > 0`):
-
-```
-⚠ <count> variable(s) in <loserColl> couldn't be moved into <keeperColl> — a variable with the same name already exists there with a potentially different value. Inspect manually in the Figma variables panel and decide which to keep:
-  - <varName>
-  - <varName>
-  ...
-```
+If any action failed (error in the `results[]` payload from 7a or a Figma rebind reported `deleted: false`), surface the failures inline. They don't abort the run — they just need designer review.
 
-Then exit normally.
+Exit 0 if all resolution actions succeeded (or the user picked Skip for everything). Exit 1 only if any Figma write erred out; the user should see the failures and decide whether to re-run.
 
 ## Common errors
 

From cf8ce21f633e90df0583238c469936c81acaed54 Mon Sep 17 00:00:00 2001
From: Hugh Francis <hughfrancis89@gmail.com>
Date: Tue, 12 May 2026 20:50:16 -0400
Subject: [PATCH 78/79] =?UTF-8?q?pull-component:=20simple-layout-driven=20?=
 =?UTF-8?q?scaffold=20branch=20=E2=80=94=20actually=20generate=20JSX?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The prior spec was binary: vector-driven inlined SVG, layout-driven
stubbed `<span />`. The user pulled UserAvatar (root FRAME + 1 TEXT
child) and correctly pointed out that "layout-driven" was overshooting
— the Figma extract had every fact needed to render a real
component, but the SKILL routed it to the stub branch with the
"reconstructing JSX from Figma is unreliable" rationale.

Adds a middle branch — "simple-layout-driven" — between the two
existing ones. Triggered when ALL of:

  - Root is a single FRAME / COMPONENT
  - Root has layoutMode !== 'NONE' (auto-layout positions children
    unambiguously)
  - Tree depth ≤ 2 (root + one level of children)
  - Every direct child is TEXT, a shape primitive, or a
    simple-shape-only FRAME
  - No variant axis hides / shows / reparents children (variant
    differences only affect bound values: sizes, colors, weights)

When the rubric passes, the agent writes real JSX following an
explicit translation table:

  - layoutMode HORIZONTAL/VERTICAL → inline-flex / flex flex-col
  - padding* / itemSpacing → p-{var} / gap-{var}
  - primary+counter axis CENTER → items-center justify-center
  - fills bound to color var → bg-{strippedVarName}
  - cornerRadius bound → rounded-{strippedVarName}
  - opacity bound → opacity-{N} class modifier (not variable)
  - TEXT static character → <span>literal</span>
  - TEXT character varying per instance → expose as prop (initial?)
  - TEXT with bound fontSize → className={TABLE[variant]} from
    the existing lookup tables

Includes the UserAvatar concrete example so the rubric is grounded.
Notes the judgment-call cases (deriving box-size from variant
nominal sizes since Figma's hug-content layouts don't carry explicit
width/height) and marks scaffold-derived entries with
`// adhd: derived` so developers know which are designer-driven vs
inferred.

When the rubric fails — depth > 2, conditional rendering, anything
ambiguous — the existing stub branch still applies. Decision rubric
explicitly biases toward "stub when unsure" so the SKILL never
emits mis-reconstructed JSX a developer has to undo.

SKILL-doc-only change. No new modules, no tests, no engine work —
the agent's judgment handles per-case translation. 587 tests still
pass.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 plugins/adhd/skills/pull-component/SKILL.md | 78 ++++++++++++++++++++-
 1 file changed, 75 insertions(+), 3 deletions(-)

diff --git a/plugins/adhd/skills/pull-component/SKILL.md b/plugins/adhd/skills/pull-component/SKILL.md
index 5eca6b7..08625ca 100644
--- a/plugins/adhd/skills/pull-component/SKILL.md
+++ b/plugins/adhd/skills/pull-component/SKILL.md
@@ -782,9 +782,75 @@ export function Logo({ colour = "dark", className = "" }: LogoProps) {
 
 This is first-pass code, not a stub. The developer can iterate from a working component.
 
-**For layout-driven components** (cards, buttons, forms — when the Figma variants contain multiple children, text, or nested frames):
+**For simple-layout-driven components** (a single root frame with a small, unambiguous tree of children — text + shape primitives + at most one level of nested frame):
+
+When the Figma source is trivially translatable, reconstruct real JSX. The lookup tables generated above carry the variant-driven values; the JSX wires them in. This produces first-pass code that renders correctly, not a stub.
+
+The translation rules:
+
+- **Root FRAME / COMPONENT** with `layoutMode === 'HORIZONTAL'` → `<span className="inline-flex ...">`; `'VERTICAL'` → `<span className="flex flex-col ...">`. Use `<span>` for inline-style containers (small components like avatars, badges, chips); use `<div>` when the auto-layout's sizing implies a block-level container (`primaryAxisSizingMode === 'FIXED'` width on horizontal layouts, etc.).
+- **Auto-layout properties** map directly to Tailwind utilities:
+  - `padding{Top,Right,Bottom,Left}` → `pt-/pr-/pb-/pl-` (use bound variable name when present; otherwise `p-[<N>px]` arbitrary form)
+  - `itemSpacing` → `gap-{name}` from the bound variable, or `gap-[<N>px]` arbitrary
+  - `primaryAxisAlignItems === 'CENTER'` and `counterAxisAlignItems === 'CENTER'` → `items-center justify-center`
+- **fills with `boundVariables.color`** → `bg-{strippedVarName}` (e.g. `color/gold` → `bg-gold`). For semantic names (brand, surface, accent, etc.), the Tailwind class follows the same naming convention as `@theme inline` exposes.
+- **strokes with `boundVariables.color`** → `border-{strippedVarName}` plus a `border` or `border-{N}` width class if `strokeWeight` is set.
+- **cornerRadius / *Radius with `boundVariables`** → `rounded-{strippedVarName}` (e.g. `radius/sm` → `rounded-sm`).
+- **opacity bound** → use the canonical opacity utility for the value (`opacity-50`, etc.) rather than a CSS-var binding — Tailwind handles opacity via class modifiers, not variables (see STRUCT011's opacity hint).
+- **Children:**
+  - **TEXT nodes** with static `characters` → `<span>literal text</span>` if the character is the same across variants. If it varies per instance (designer placeholders like "A", "B" for an avatar's initial), expose as a prop (`initial?: string`) defaulting to the first variant's value.
+  - **TEXT with bound `fontSize`** → wrap text in a span with `className={TABLE[variantValue]}` where TABLE is the appropriate lookup the SKILL just generated (typically `*_TEXT_SIZE`).
+  - **TEXT with bound `lineHeight` / `letterSpacing` / `fontWeight`** → same pattern; concatenate classes from the relevant lookup tables.
+  - **Nested FRAME (only one level deep allowed for this branch)** → another `<span>` / `<div>` with the same auto-layout translation.
+  - **Shape primitives** (RECTANGLE/ELLIPSE/etc. that aren't part of an SVG composition) → typically don't generate; the auto-layout container's `bg-` already handles solid color backgrounds. If a shape is decorative, use the vector-driven branch instead.
+
+Concrete example (UserAvatar — root FRAME + 1 TEXT child):
 
-Reconstructing JSX from a flattened Figma capture is unreliable, so keep the stub:
+```tsx
+export type UserAvatarSize = "sm" | "lg" | "xl";
+
+export interface UserAvatarProps {
+  size?: UserAvatarSize;
+  initial?: string;
+  className?: string;
+}
+
+export const USER_AVATAR_TEXT_SIZE: Record<UserAvatarSize, string> = {
+  sm: "text-sm",
+  lg: "text-sm",
+  xl: "text-2xl",
+};
+
+export const USER_AVATAR_TEXT_LEADING: Record<UserAvatarSize, string> = {
+  sm: "leading-normal",
+  lg: "leading-normal",
+  xl: "leading-7",
+};
+
+export const USER_AVATAR_BOX_SIZE: Record<UserAvatarSize, string> = {
+  sm: "w-8 h-8",
+  lg: "w-12 h-12",
+  xl: "w-16 h-16",
+};
+
+export function UserAvatar({ size = "sm", initial = "A", className = "" }: UserAvatarProps) {
+  return (
+    <span
+      className={`inline-flex items-center justify-center bg-gold rounded-sm aspect-square ${USER_AVATAR_BOX_SIZE[size]} ${className}`}
+    >
+      <span className={`text-primary tracking-normal ${USER_AVATAR_TEXT_SIZE[size]} ${USER_AVATAR_TEXT_LEADING[size]}`}>
+        {initial}
+      </span>
+    </span>
+  );
+}
+```
+
+Some judgment calls remain — Figma doesn't always carry explicit width/height for variants that "hug" their content, but the rendered component typically needs fixed boxes. Generate a `*_BOX_SIZE` (or equivalent) lookup with sane defaults derived from the variant's nominal size (`sm` → `w-8 h-8`, `lg` → `w-12 h-12`, `xl` → `w-16 h-16` — adjust to what the variant's actual rendered size looks like). Mark these in a comment as `// adhd: derived` so the developer knows which entries are designer-driven vs scaffold-derived.
+
+**For complex-layout-driven components** (cards, forms, anything with conditional rendering across variants, depth > 2, or children that hide / show per-variant):
+
+Reconstructing JSX from a flattened Figma capture is unreliable. Keep the stub:
 
 ```tsx
 export type <Component>Size = "<v1>" | "<v2>" | ...;
@@ -807,7 +873,13 @@ In this case the function body really is the developer's responsibility. The loo
 
 ### How to decide which branch
 
-Look at the variant subtrees you captured in Phase 3. A component is vector-driven when, across all variants, the leaf nodes are predominantly `VECTOR` / `BOOLEAN_OPERATION` / `ELLIPSE` / `RECTANGLE` / `STAR` / `POLYGON` / `LINE`, and there are no TEXT nodes or nested FRAMEs with multiple children. If you're unsure, treat it as layout-driven and keep the stub — the user can re-run pull-component once the file exists if they want to iterate.
+Walk down this rubric, picking the first matching branch:
+
+1. **Vector-driven** — across all variants, the leaf nodes are predominantly `VECTOR` / `BOOLEAN_OPERATION` / `ELLIPSE` / `RECTANGLE` / `STAR` / `POLYGON` / `LINE`, and there are no TEXT nodes or nested FRAMEs with multiple children. Inline SVG.
+2. **Simple-layout-driven** — root is a single FRAME / COMPONENT with `layoutMode !== 'NONE'` (auto-layout, so positioning is unambiguous), the tree depth is ≤ 2 (root + one level of children), every direct child is TEXT / a shape primitive / a simple-shape-only FRAME, and no variant axis hides / shows / reparents children (variant differences only affect bound values like sizes, colors, weights). Reconstruct real JSX per the translation rules above.
+3. **Complex-layout-driven** — anything that doesn't satisfy (1) or (2). Stub.
+
+When the rubric is ambiguous between (2) and (3), prefer (3): a `<span />` stub the developer fills in is strictly safer than mis-reconstructed JSX they then have to fix. The user can re-run /adhd:pull-component once the file exists, or hand-edit the function body — either way, the lookup tables stay in sync on subsequent pulls.
 
 ## Phase 8: Write mapping if scaffold mode
 

From 47f8011ed34781c2f89768f83c7a0b055c10f9ac Mon Sep 17 00:00:00 2001
From: Hugh Francis <hughfrancis89@gmail.com>
Date: Tue, 12 May 2026 21:03:57 -0400
Subject: [PATCH 79/79] pull-component: INSTANCE-of-tracked-component branch +
 dependency pre-flight
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

User asked how to handle component composition — a Card with an
Avatar instance, a Dashboard with multiple Cards. Per their pick of
option (a), tracked-instance handling is wired in as a fourth child
type for the simple-layout-driven rubric; un-tracked instances abort
the pull with a clear "pull this dependency first" instruction.

Wiring:

Phase 3 (serializer): captures `mainComponentId` + `componentProperties`
for INSTANCE nodes, alongside the structural data it already collects.

Phase 2.8 (NEW pre-flight): walks every INSTANCE in the extract,
collects unique `mainComponentId` values, resolves each against the
`components: { ... }` map in adhd.config.ts via a new
`lib/pull-component/cli.js resolve-instance` subcommand. The resolver
parses the figma URL in each config entry, converts the `A-B` URL
form to `A:B` Figma ID form, matches on equality, and returns
`{ matched, relPath, importPath, exportName, fileExists }`. exportName
is read from the existing file when present (handles
`export function Name`, `export default function Name`,
`export const Name = ...`, `export default Name`) or derived from the
file's slug otherwise.

If any instance is unmatched, Phase 2.8 aborts with the dependency
list. The user pulls each missing component (in any order — they're
independent), then re-runs the parent.

Phase 7 (simple-layout-driven branch): grows a fourth child type —
`INSTANCE-of-tracked-component`. The translation: convert
`componentProperties` keys to the target casing (kebab → camel etc.),
string-literal variants → JSX strings, boolean variants → boolean
attributes; emit `<ExportName prop1={...} prop2={...} />` + the
`import` statement at the top of the file. Visual overrides on the
instance drop with an `// adhd: dropped override` comment — designer
either lifts the override into a new variant in Figma or accepts the
unstyled instance.

Includes a concrete UserCard example (root FRAME + UserAvatar
INSTANCE + TEXT child) to show what the generated code looks like.

The depth metric counts JSX depth in the parent's output, so an
INSTANCE collapses to a single JSX node regardless of how complex
its resolved Figma source is — recursion across multiple tracked
components is fine.

12 tests for instance-resolver covering URL parsing, slug-to-PascalCase
fallback, export-name discovery from existing files in three export
forms, unmatched component-ids, partial config entries without figma
URLs, and the file-missing-but-matched case.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 README.md                                     |   2 +-
 .../__tests__/instance-resolver.test.js       | 171 ++++++++++++++++++
 plugins/adhd/lib/pull-component/cli.js        |  18 ++
 .../adhd/lib/pull-component/config-writer.js  |   6 +
 .../lib/pull-component/instance-resolver.js   | 123 +++++++++++++
 plugins/adhd/skills/pull-component/SKILL.md   |  84 ++++++++-
 6 files changed, 401 insertions(+), 3 deletions(-)
 create mode 100644 plugins/adhd/lib/pull-component/__tests__/instance-resolver.test.js
 create mode 100644 plugins/adhd/lib/pull-component/instance-resolver.js

diff --git a/README.md b/README.md
index 51f5580..b870bbd 100644
--- a/README.md
+++ b/README.md
@@ -34,7 +34,7 @@ After install, nine slash commands are available:
 | `/adhd:pull-tokens` | `[--dry-run]` | Figma → code | Pulls Figma variables + named styles into globals.css. `--dry-run` previews without writing. |
 | `/adhd:push-component` | `<path> [--max-variants <n>]` | code → Figma | Pushes a React component to Figma as a structured Component Set with variant properties + variable bindings, plus a preflight lint check. Per-variable STRUCT015/STRUCT016 resolution prompts let you sync mismatches in either direction; annotations land automatically on any abort. |
 | `/adhd:push-all-components` | `[--continue-on-error] [--max-variants <n>]` | code → Figma | Bulk version of `push-component` — iterates over every entry in `adhd.config.ts`'s components map. Sequential, halt-on-first-failure by default. |
-| `/adhd:pull-component` | `<path \| figma-url> [--allow-unbound]` | Figma → code | Pulls a Figma Component Set into a React source file; updates lookup tables and union types only (function body untouched). Per-variable STRUCT015/STRUCT016 resolution prompts let you sync mismatches in either direction; annotations land automatically on any abort. Records an 8-char fingerprint + ISO `pulledAt` in `adhd.config.ts`; subsequent pulls short-circuit (no lint, no diff, no commit) when the Figma extract + pull-relevant config still hash to the same value. |
+| `/adhd:pull-component` | `<path \| figma-url> [--allow-unbound]` | Figma → code | Pulls a Figma Component Set into a React source file. Scaffold mode generates real JSX for vector-driven (inline SVG) and simple-layout-driven components; complex layouts get a stub the developer fills in. INSTANCE children that reference tracked components in `adhd.config.ts` are emitted as `<TrackedComponent />` imports rather than inlined markup — a Phase 2.8 pre-flight aborts with a "pull this first" message when an instance's source isn't tracked. Per-variable STRUCT015/STRUCT016 resolution prompts let you sync mismatches in either direction; annotations land automatically on any abort. Records an 8-char fingerprint + ISO `pulledAt` in `adhd.config.ts`; subsequent pulls short-circuit (no lint, no diff, no commit) when the Figma extract + pull-relevant config still hash to the same value. |
 | `/adhd:pull-all-components` | `[--continue-on-error] [--allow-unbound]` | Figma → code | Bulk version of `pull-component` — iterates over every entry in `adhd.config.ts`'s components map. Sequential, halt-on-first-failure by default. Components whose stored fingerprint matches the fresh Figma extract are reported as `unchanged` and skipped (no lint, no diff, no commit). |
 | `/adhd:sync-docs` | — | install | Generates a design-system docs route in your Next.js consumer app. Tokens read live from globals.css; components are statically imported from adhd.config.ts at setup time — re-run after editing the components map. Excluded from production builds by default. |
 
diff --git a/plugins/adhd/lib/pull-component/__tests__/instance-resolver.test.js b/plugins/adhd/lib/pull-component/__tests__/instance-resolver.test.js
new file mode 100644
index 0000000..4e46657
--- /dev/null
+++ b/plugins/adhd/lib/pull-component/__tests__/instance-resolver.test.js
@@ -0,0 +1,171 @@
+'use strict';
+
+const test = require('node:test');
+const assert = require('node:assert/strict');
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const {
+  resolveInstance,
+  nodeIdFromUrl,
+  pascalSlugFromPath,
+  importPathFor,
+  readExportName,
+} = require('../instance-resolver');
+
+test('nodeIdFromUrl: converts URL node-id form (A-B) to Figma ID form (A:B)', () => {
+  assert.equal(
+    nodeIdFromUrl('https://figma.com/design/abc?node-id=123-456'),
+    '123:456',
+  );
+  assert.equal(
+    nodeIdFromUrl('https://www.figma.com/design/abc/Test?node-id=91-18&t=foo'),
+    '91:18',
+  );
+});
+
+test('nodeIdFromUrl: returns null when no node-id present', () => {
+  assert.equal(nodeIdFromUrl('https://figma.com/design/abc/Test'), null);
+  assert.equal(nodeIdFromUrl(null), null);
+  assert.equal(nodeIdFromUrl(123), null);
+});
+
+test('pascalSlugFromPath: derives a PascalCase fallback name', () => {
+  assert.equal(pascalSlugFromPath('components/user-avatar/index.tsx'), 'UserAvatar');
+  assert.equal(pascalSlugFromPath('app/components/Button.tsx'), 'Button');
+  assert.equal(pascalSlugFromPath('app/cards/info-card/index.tsx'), 'InfoCard');
+});
+
+test('importPathFor: rewrites file path to @/-aliased form', () => {
+  assert.equal(
+    importPathFor('components/user-avatar/index.tsx'),
+    '@/components/user-avatar',
+  );
+  assert.equal(
+    importPathFor('app/cards/info-card.tsx'),
+    '@/app/cards/info-card',
+  );
+});
+
+const SAMPLE_CONFIG = `const config = {
+  figma: { url: "https://figma.com/design/abc/Test" },
+  components: {
+    "components/user-avatar/index.tsx": {
+      figma: { url: "https://figma.com/design/abc?node-id=123-456" },
+    },
+    "components/info-card/index.tsx": {
+      figma: { url: "https://figma.com/design/abc?node-id=789-1000" },
+    },
+  },
+  naming: "kebab-case",
+};
+export default config;`;
+
+test('resolveInstance: matched, file does not exist → uses PascalCase slug as exportName', () => {
+  const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'resolve-instance-'));
+  const out = resolveInstance({
+    configSrc: SAMPLE_CONFIG,
+    componentId: '123:456',
+    repoRoot: tmpDir,
+  });
+  assert.equal(out.matched, true);
+  assert.equal(out.relPath, 'components/user-avatar/index.tsx');
+  assert.equal(out.importPath, '@/components/user-avatar');
+  assert.equal(out.fileExists, false);
+  assert.equal(out.exportName, 'UserAvatar');
+});
+
+test('resolveInstance: matched, file exists → reads exportName from "export function Name"', () => {
+  const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'resolve-instance-'));
+  fs.mkdirSync(path.join(tmpDir, 'components/user-avatar'), { recursive: true });
+  fs.writeFileSync(
+    path.join(tmpDir, 'components/user-avatar/index.tsx'),
+    'export function MyCustomAvatar() { return null; }\n',
+  );
+  const out = resolveInstance({
+    configSrc: SAMPLE_CONFIG,
+    componentId: '123:456',
+    repoRoot: tmpDir,
+  });
+  assert.equal(out.matched, true);
+  assert.equal(out.fileExists, true);
+  // exportName comes from the file, not the slug.
+  assert.equal(out.exportName, 'MyCustomAvatar');
+});
+
+test('resolveInstance: matched, exists with "export default function Name"', () => {
+  const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'resolve-instance-'));
+  fs.mkdirSync(path.join(tmpDir, 'components/user-avatar'), { recursive: true });
+  fs.writeFileSync(
+    path.join(tmpDir, 'components/user-avatar/index.tsx'),
+    'export default function Avatar() { return null; }\n',
+  );
+  const out = resolveInstance({
+    configSrc: SAMPLE_CONFIG,
+    componentId: '123:456',
+    repoRoot: tmpDir,
+  });
+  assert.equal(out.exportName, 'Avatar');
+});
+
+test('resolveInstance: matched, exists with "export const Name = ..."', () => {
+  const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'resolve-instance-'));
+  fs.mkdirSync(path.join(tmpDir, 'components/user-avatar'), { recursive: true });
+  fs.writeFileSync(
+    path.join(tmpDir, 'components/user-avatar/index.tsx'),
+    'export const StyledAvatar = ({ size }) => null;\n',
+  );
+  const out = resolveInstance({
+    configSrc: SAMPLE_CONFIG,
+    componentId: '123:456',
+    repoRoot: tmpDir,
+  });
+  assert.equal(out.exportName, 'StyledAvatar');
+});
+
+test('resolveInstance: unmatched component-id → matched: false', () => {
+  const out = resolveInstance({
+    configSrc: SAMPLE_CONFIG,
+    componentId: '999:999',
+    repoRoot: '/tmp',
+  });
+  assert.equal(out.matched, false);
+});
+
+test('resolveInstance: config without components map → matched: false', () => {
+  const out = resolveInstance({
+    configSrc: 'export default { figma: { url: "x" } };',
+    componentId: '123:456',
+    repoRoot: '/tmp',
+  });
+  assert.equal(out.matched, false);
+});
+
+test('resolveInstance: handles entries without a figma.url (e.g. work-in-progress entries)', () => {
+  // An adhd.config.ts mid-edit might have a component entry without
+  // its figma URL filled in yet. resolveInstance should skip those
+  // gracefully, not throw.
+  const partial = `const config = {
+    components: {
+      "components/incomplete/index.tsx": { /* no figma yet */ },
+      "components/user-avatar/index.tsx": {
+        figma: { url: "https://figma.com/design/abc?node-id=123-456" },
+      },
+    },
+  };`;
+  const out = resolveInstance({
+    configSrc: partial,
+    componentId: '123:456',
+    repoRoot: '/tmp',
+  });
+  assert.equal(out.matched, true);
+  assert.equal(out.relPath, 'components/user-avatar/index.tsx');
+});
+
+test('readExportName: returns null when file is missing or has no export', () => {
+  assert.equal(readExportName('/nonexistent/path.tsx'), null);
+  const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'export-name-'));
+  const empty = path.join(tmpDir, 'empty.tsx');
+  fs.writeFileSync(empty, 'const internal = 1;\n');
+  assert.equal(readExportName(empty), null);
+});
diff --git a/plugins/adhd/lib/pull-component/cli.js b/plugins/adhd/lib/pull-component/cli.js
index 0f6e814..e3f4774 100644
--- a/plugins/adhd/lib/pull-component/cli.js
+++ b/plugins/adhd/lib/pull-component/cli.js
@@ -2,10 +2,12 @@
 'use strict';
 
 const fs = require('node:fs');
+const path = require('node:path');
 const { readComponentMapping, addComponentMapping, reverseLookupPath } = require('./config-writer');
 const { computeFingerprint, relevantConfigFields } = require('./fingerprint');
 const { readComponentState, writeComponentState } = require('./config-state');
 const { resolveWriteTarget } = require('./resolve-write-target');
+const { resolveInstance } = require('./instance-resolver');
 const { parseTheme } = require('../lint-engine/theme-parser');
 const { figmaToCssVar } = require('../lint-engine/name-normalizer');
 
@@ -28,6 +30,7 @@ function printUsage() {
   cli.js fingerprint-check --config <adhd.config.ts> --path <relative-path> --ctx <ctx.json> --vars <vars.json>
   cli.js fingerprint-write --config <adhd.config.ts> --path <relative-path> --ctx <ctx.json> --vars <vars.json>
   cli.js resolve-actions   --globals <globals.css> --figma-path <figma-path> --value <hex-or-px> [--both-modes]
+  cli.js resolve-instance  --config <adhd.config.ts> --component-id <A:B> [--repo-root <path>]
 
 fingerprint-check:
   Computes the fingerprint of the fresh Figma extract + relevant config bits
@@ -130,6 +133,21 @@ function main() {
     process.exit(0);
   }
 
+  if (cmd === 'resolve-instance') {
+    if (!args.config || !args['component-id']) {
+      console.error('Usage: resolve-instance --config <adhd.config.ts> --component-id <A:B> [--repo-root <path>]');
+      process.exit(2);
+    }
+    const configSrc = fs.readFileSync(args.config, 'utf8');
+    const out = resolveInstance({
+      configSrc,
+      componentId: args['component-id'],
+      repoRoot: args['repo-root'] || path.dirname(path.resolve(args.config)),
+    });
+    process.stdout.write(JSON.stringify(out, null, 2));
+    process.exit(out.matched ? 0 : 1);
+  }
+
   if (cmd === 'fingerprint-write') {
     if (!args.config || !args.path || !args.ctx || !args.vars) {
       console.error('Usage: fingerprint-write --config <path> --path <rel> --ctx <ctx.json> --vars <vars.json>');
diff --git a/plugins/adhd/lib/pull-component/config-writer.js b/plugins/adhd/lib/pull-component/config-writer.js
index 1f4b344..4c63475 100644
--- a/plugins/adhd/lib/pull-component/config-writer.js
+++ b/plugins/adhd/lib/pull-component/config-writer.js
@@ -327,4 +327,10 @@ module.exports = {
   readComponentMapping,
   reverseLookupPath,
   addComponentMapping,
+  // Lower-level parsing primitives — used by instance-resolver to
+  // walk the components map looking for a Figma node-id match.
+  findConfigObjectRange,
+  findComponentsRange,
+  iterateObjectEntries,
+  findFigmaUrlInEntry,
 };
diff --git a/plugins/adhd/lib/pull-component/instance-resolver.js b/plugins/adhd/lib/pull-component/instance-resolver.js
new file mode 100644
index 0000000..f31b3c5
--- /dev/null
+++ b/plugins/adhd/lib/pull-component/instance-resolver.js
@@ -0,0 +1,123 @@
+'use strict';
+
+// Resolve a Figma component-set ID (e.g. "123:456") to its React
+// import metadata using `adhd.config.ts`'s `components: { ... }` map.
+// Powers pull-component's scaffold-mode handling of INSTANCE children:
+// when the simple-layout-driven rubric sees a node binding
+// `mainComponent` of another tracked component, this resolver produces
+// the import path / export name so the generated JSX can read
+// `<TrackedComponent {...props} />` with a proper import at the top.
+//
+// Per the design choice ("(a) refuse / abort"), when a Figma instance's
+// mainComponent isn't in adhd.config.ts, this resolver returns
+// `{ matched: false }` and the SKILL aborts with a "pull this first"
+// message. The user pulls the dependency, then re-runs the parent.
+
+const fs = require('node:fs');
+const path = require('node:path');
+const {
+  findConfigObjectRange,
+  findComponentsRange,
+  iterateObjectEntries,
+  findFigmaUrlInEntry,
+} = require('./config-writer');
+
+// Extract the Figma node-id query parameter from a design URL and
+// convert it from the URL form (`A-B`) to the internal Figma ID form
+// (`A:B`). Returns null when the URL has no node-id, isn't a Figma
+// design URL, or otherwise can't be parsed.
+function nodeIdFromUrl(url) {
+  if (typeof url !== 'string') return null;
+  const m = /[?&]node-id=([^&]+)/.exec(url);
+  if (!m) return null;
+  // The URL form uses `-` between major:minor; the API uses `:`. Only
+  // the FIRST `-` is the separator — variant IDs can themselves
+  // contain hyphens (e.g. `123-456-7` → `123:456-7` is wrong; the
+  // correct conversion is `123:456` and the trailing `-7` is part of
+  // a deeper id, but Figma's URL exporter uses `-` consistently). The
+  // standard rule the rest of ADHD uses is to swap the FIRST hyphen
+  // only; mirror that here.
+  const dec = decodeURIComponent(m[1]);
+  const i = dec.indexOf('-');
+  if (i < 0) return dec;
+  return dec.slice(0, i) + ':' + dec.slice(i + 1);
+}
+
+// PascalCase a file path's slug for use as a fallback export name when
+// the target file doesn't exist yet (or its export name can't be
+// inferred via Read). Same rule sync-docs uses.
+function pascalSlugFromPath(relPath) {
+  const noExt = relPath.replace(/\.(t|j)sx?$/, '').replace(/\/index$/, '');
+  const slug = noExt.split('/').pop() || '';
+  return slug.split(/[-_]+/).filter(Boolean).map(w => w[0].toUpperCase() + w.slice(1)).join('');
+}
+
+// Derive a `@/`-aliased import path from a relative file path. Mirrors
+// the sync-docs config-parser's `importPathFor` so generated imports
+// look native in a Next.js consumer repo.
+function importPathFor(relPath) {
+  return '@/' + relPath.replace(/\.(t|j)sx?$/, '').replace(/\/index$/, '');
+}
+
+// Best-effort read of the exported component name from a TS/TSX file.
+// Looks for `export default function Name`, `export function Name`,
+// `export const Name`, or `export default Name`. Returns null when no
+// match — caller falls back to the PascalCase slug.
+function readExportName(absPath) {
+  let src;
+  try { src = fs.readFileSync(absPath, 'utf8'); }
+  catch { return null; }
+  const patterns = [
+    /export\s+default\s+function\s+([A-Z][A-Za-z0-9_]*)/,
+    /export\s+function\s+([A-Z][A-Za-z0-9_]*)/,
+    /export\s+const\s+([A-Z][A-Za-z0-9_]*)\s*=/,
+    /export\s+default\s+([A-Z][A-Za-z0-9_]*)\s*;?/,
+  ];
+  for (const re of patterns) {
+    const m = re.exec(src);
+    if (m) return m[1];
+  }
+  return null;
+}
+
+// Main resolver. Walks every component entry in adhd.config.ts,
+// extracts each entry's figma node-id, converts to the internal ID
+// form, and matches against `componentId`. Returns:
+//   { matched: true, relPath, absPath, importPath, exportName, fileExists }
+// when the component-id is tracked, with `fileExists` indicating
+// whether the React file is on disk yet (the SKILL surfaces this
+// distinction so the "pull this dependency first" message points at
+// the right next step).
+//
+// Returns `{ matched: false }` when the component-id isn't in the
+// config — caller aborts with a clear error.
+function resolveInstance({ configSrc, componentId, repoRoot }) {
+  const cfg = findConfigObjectRange(configSrc);
+  if (!cfg) return { matched: false };
+  const comps = findComponentsRange(configSrc, cfg);
+  if (!comps) return { matched: false };
+
+  for (const entry of iterateObjectEntries(configSrc, comps)) {
+    if (configSrc[entry.valueStart] !== '{') continue;
+    const urlInfo = findFigmaUrlInEntry(configSrc, { start: entry.valueStart, end: entry.valueEnd });
+    if (!urlInfo) continue;
+    const entryId = nodeIdFromUrl(urlInfo.urlText);
+    if (entryId !== componentId) continue;
+
+    const relPath = entry.key;
+    const absPath = repoRoot ? path.join(repoRoot, relPath) : relPath;
+    const fileExists = fs.existsSync(absPath);
+    const exportName = (fileExists ? readExportName(absPath) : null) || pascalSlugFromPath(relPath);
+    return {
+      matched: true,
+      relPath,
+      absPath,
+      importPath: importPathFor(relPath),
+      exportName,
+      fileExists,
+    };
+  }
+  return { matched: false };
+}
+
+module.exports = { resolveInstance, nodeIdFromUrl, pascalSlugFromPath, importPathFor, readExportName };
diff --git a/plugins/adhd/skills/pull-component/SKILL.md b/plugins/adhd/skills/pull-component/SKILL.md
index 08625ca..90534af 100644
--- a/plugins/adhd/skills/pull-component/SKILL.md
+++ b/plugins/adhd/skills/pull-component/SKILL.md
@@ -66,7 +66,7 @@ Save resolved `{ mode, path, figmaUrl }` to working memory.
 
 Extract the Figma node-id from the URL (`?node-id=A-B` → `A:B`). Use `mcp__plugin_figma_figma__use_figma` to:
 1. Resolve the node by id; if not a `COMPONENT_SET` or top-level `COMPONENT`, abort: "Target node `<id>` is a `<type>`. Pull requires a Component Set."
-2. Serialize the node's structural data (the same way /adhd:lint does for scoped mode — fields: `id, name, type, layoutMode, padding*, itemSpacing, cornerRadius, *Radius, fills, strokes, effects, boundVariables, componentPropertyDefinitions, variantProperties, textStyleId, effectStyleId, characters, fontSize, fontName`, recursing into children).
+2. Serialize the node's structural data (the same way /adhd:lint does for scoped mode — fields: `id, name, type, layoutMode, padding*, itemSpacing, cornerRadius, *Radius, fills, strokes, effects, boundVariables, componentPropertyDefinitions, variantProperties, textStyleId, effectStyleId, characters, fontSize, fontName`, recursing into children). For `INSTANCE` nodes also capture `mainComponent.id` (as `mainComponentId`) and `componentProperties` — these drive Phase 7's "INSTANCE-of-tracked-component" branch of the scaffold (generate `<TrackedComponent {...props} />` + import instead of inlining the instance's markup).
 3. Collect the variable defs (walk boundVariables, look each up via `figma.variables.getVariableByIdAsync`, emit a `{ vars: { 'collection/name': value } }` map).
 
 Save both via `Bash` heredoc to:
@@ -481,6 +481,54 @@ Then iterate `phase27-missing.json` to build the prompts.
 
 Skip this phase if conflicts exist BUT no missing — there's nothing additive to do, just print: `Note: <N> variable value(s) differ between Figma and code. Run /adhd:pull-tokens to reconcile.` Then continue (conflicts don't block pull-component v1; the pull works with code's value, drift is reported in the final report).
 
+## Phase 2.8: INSTANCE-of-tracked pre-flight
+
+Only runs when scaffold mode produces a simple-layout-driven component (see Phase 7's rubric) AND the captured tree contains at least one INSTANCE node. Update mode skips this entirely — the existing React file already has its imports; we don't rewrite them.
+
+Walk every INSTANCE node in `/tmp/adhd-pull-component/ctx.json`, collecting unique `mainComponentId` values. For each, resolve against `adhd.config.ts`'s components map:
+
+```bash
+node plugins/adhd/lib/pull-component/cli.js resolve-instance \
+  --config adhd.config.ts \
+  --component-id "<mainComponentId>"
+```
+
+The command prints JSON with `{ matched, relPath, importPath, exportName, fileExists }` and exits 0 when matched, 1 when not. Save the resolved metadata per instance into `/tmp/adhd-pull-component/resolved-instances.json` keyed by `mainComponentId` — Phase 7 reads it to wire up imports and JSX.
+
+**If any INSTANCE is unmatched** (resolve-instance exited 1), abort the pull with a dependency-pull instruction:
+
+```
+✗ Cannot pull <ComponentName> — it has Figma instances of components that aren't tracked in adhd.config.ts:
+
+  • <figmaInstanceName> (mainComponentId: <A:B>) — not in components map
+
+Pull each missing component first, then re-run this command:
+
+  /adhd:pull-component https://figma.com/design/<fileKey>?node-id=<A>-<B>
+  ...
+  /adhd:pull-component <this-component's-url>
+
+Tracked dependencies must exist in adhd.config.ts so the parent component's
+JSX can import them. Without that, we'd generate a placeholder the developer
+has to wire by hand — and dependency-ordered pulls keep the design system
+clean.
+```
+
+The error lists each unmatched instance with its Figma name + component-id. The user runs the dependency pulls (in any order — they're independent), then re-runs the parent.
+
+**If any matched INSTANCE's `fileExists` is false** (config has the mapping but the React file isn't on disk), surface as a warning:
+
+```
+⚠ <ComponentName> imports <ExportName> from <importPath>, but the file at <relPath>
+  doesn't exist yet. The pull proceeds with the import statement; the developer
+  needs to run /adhd:pull-component <importPath> to create the dependency before
+  the parent compiles cleanly.
+```
+
+The warning doesn't block — the import statement still gets generated. The developer sees a compile error if they try to use the parent without pulling the dep, which is the same UX as any missing import in a TypeScript project.
+
+When every INSTANCE resolves cleanly (matched, file exists), this phase exits silently and Phase 3 proceeds.
+
 ## Phase 3: Read both sides
 
 **React side (update mode only):** use `Read` on `<react-path>` (from Phase 2). Identify:
@@ -803,6 +851,7 @@ The translation rules:
   - **TEXT with bound `lineHeight` / `letterSpacing` / `fontWeight`** → same pattern; concatenate classes from the relevant lookup tables.
   - **Nested FRAME (only one level deep allowed for this branch)** → another `<span>` / `<div>` with the same auto-layout translation.
   - **Shape primitives** (RECTANGLE/ELLIPSE/etc. that aren't part of an SVG composition) → typically don't generate; the auto-layout container's `bg-` already handles solid color backgrounds. If a shape is decorative, use the vector-driven branch instead.
+  - **INSTANCE of a tracked component** (e.g. an `Avatar` instance inside a `Card`) → resolve the instance's `mainComponentId` against `adhd.config.ts`'s `components` map via `node plugins/adhd/lib/pull-component/cli.js resolve-instance --config adhd.config.ts --component-id <A:B>`. When it returns `matched: true`, generate `<ExportName prop1={...} prop2={...} />` and add an `import { ExportName } from "<importPath>";` to the top of the file. Translate the instance's `componentProperties` into JSX props: convert each key to the target casing (kebab → camel, etc. per `adhd.config.ts`'s `naming`), pass string-literal variants as JSX strings (`<UserAvatar size="lg" />`), boolean variants as boolean attributes (`<UserAvatar disabled />`). Drop any visual override on the instance with a `// adhd: dropped override on <child>` comment — the developer either lifts the override into a new variant in Figma or accepts the unstyled instance. (See the "INSTANCE-of-tracked pre-flight" subsection below — if any INSTANCE in the captured tree is NOT in `adhd.config.ts`, the SKILL aborts BEFORE Phase 7 with a dependency-pull instruction; you never reach this branch with an unresolvable instance.)
 
 Concrete example (UserAvatar — root FRAME + 1 TEXT child):
 
@@ -848,6 +897,37 @@ export function UserAvatar({ size = "sm", initial = "A", className = "" }: UserA
 
 Some judgment calls remain — Figma doesn't always carry explicit width/height for variants that "hug" their content, but the rendered component typically needs fixed boxes. Generate a `*_BOX_SIZE` (or equivalent) lookup with sane defaults derived from the variant's nominal size (`sm` → `w-8 h-8`, `lg` → `w-12 h-12`, `xl` → `w-16 h-16` — adjust to what the variant's actual rendered size looks like). Mark these in a comment as `// adhd: derived` so the developer knows which entries are designer-driven vs scaffold-derived.
 
+Concrete example (UserCard — root FRAME with a `UserAvatar` INSTANCE + a TEXT child). Phase 2.8 has already resolved the avatar's component-id to `{ importPath: "@/components/user-avatar", exportName: "UserAvatar" }`:
+
+```tsx
+import { UserAvatar } from "@/components/user-avatar";
+
+export type UserCardTheme = "neutral" | "brand";
+
+export interface UserCardProps {
+  theme?: UserCardTheme;
+  name?: string;
+  initial?: string;
+  className?: string;
+}
+
+export const USER_CARD_BG: Record<UserCardTheme, string> = {
+  neutral: "bg-surface",
+  brand: "bg-brand-surface",
+};
+
+export function UserCard({ theme = "neutral", name = "Hugh", initial = "H", className = "" }: UserCardProps) {
+  return (
+    <div className={`flex items-center gap-3 p-4 rounded-md ${USER_CARD_BG[theme]} ${className}`}>
+      <UserAvatar size="lg" initial={initial} />
+      <span className="text-foreground text-base font-medium">{name}</span>
+    </div>
+  );
+}
+```
+
+The instance's `componentProperties` from the Figma extract (`{ Size: "lg" }`) became `size="lg"` on the JSX. The container handles its own auto-layout, padding, gap, and theme-driven background; the avatar is just a `<UserAvatar />` reference. Subsequent updates to the avatar component (renaming its export, adding props, changing variants) flow through the import — UserCard doesn't need to be re-pulled unless its own structure changes.
+
 **For complex-layout-driven components** (cards, forms, anything with conditional rendering across variants, depth > 2, or children that hide / show per-variant):
 
 Reconstructing JSX from a flattened Figma capture is unreliable. Keep the stub:
@@ -876,7 +956,7 @@ In this case the function body really is the developer's responsibility. The loo
 Walk down this rubric, picking the first matching branch:
 
 1. **Vector-driven** — across all variants, the leaf nodes are predominantly `VECTOR` / `BOOLEAN_OPERATION` / `ELLIPSE` / `RECTANGLE` / `STAR` / `POLYGON` / `LINE`, and there are no TEXT nodes or nested FRAMEs with multiple children. Inline SVG.
-2. **Simple-layout-driven** — root is a single FRAME / COMPONENT with `layoutMode !== 'NONE'` (auto-layout, so positioning is unambiguous), the tree depth is ≤ 2 (root + one level of children), every direct child is TEXT / a shape primitive / a simple-shape-only FRAME, and no variant axis hides / shows / reparents children (variant differences only affect bound values like sizes, colors, weights). Reconstruct real JSX per the translation rules above.
+2. **Simple-layout-driven** — root is a single FRAME / COMPONENT with `layoutMode !== 'NONE'` (auto-layout, so positioning is unambiguous), the tree depth is ≤ 2 (root + one level of children), every direct child is TEXT / a shape primitive / a simple-shape-only FRAME / an `INSTANCE` of a component tracked in `adhd.config.ts` (resolved during Phase 2.8 — INSTANCE references collapse to a single `<TrackedComponent />` JSX node from the parent's perspective, so they count as a single child for depth purposes regardless of the resolved component's complexity), and no variant axis hides / shows / reparents children (variant differences only affect bound values like sizes, colors, weights). Reconstruct real JSX per the translation rules above.
 3. **Complex-layout-driven** — anything that doesn't satisfy (1) or (2). Stub.
 
 When the rubric is ambiguous between (2) and (3), prefer (3): a `<span />` stub the developer fills in is strictly safer than mis-reconstructed JSX they then have to fix. The user can re-run /adhd:pull-component once the file exists, or hand-edit the function body — either way, the lookup tables stay in sync on subsequent pulls.