Add /adhd:install-design-system-docs-route skill

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

.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 sync-docs tests
+        run: node --test plugins/adhd/lib/sync-docs/__tests__/
 
   hygiene:
     name: project hygiene

README.md

@@ -24,16 +24,19 @@ 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, 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>]` | read-only | Validates the Figma file (whole file or scoped) against the local design system + structure best-practices |
-| `/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: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. |
+| `/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. 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. |
 
 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.
 
@@ -66,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
 ```
 
@@ -83,7 +88,20 @@ 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–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
+
+`/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                                                # 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
 
@@ -110,6 +128,65 @@ 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:sync-docs
+```
+
+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,
+  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.
+
+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
+
+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: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
+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.
+
 ### 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.
@@ -137,7 +214,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/