@hegemonart/get-design-done 1.53.0 → 1.54.0

package/.claude-plugin/marketplace.json

@@ -5,14 +5,14 @@
   },
   "metadata": {
     "description": "Get Design Done — 5-stage agent-orchestrated design pipeline with 9 connections, handoff-first workflow, bidirectional Figma write-back, 22+ specialized agents, queryable knowledge layer (intel store, dependency analysis, learnings extraction), and a self-improvement loop (reflector, frontmatter + budget feedback, global-skills layer). v1.20.0 ships the SDK foundation: gdd-state MCP server (11 typed tools), lockfile-safe STATE.md mutations, event stream, and resilience primitives (jittered-backoff, rate-guard, error-classifier, iteration-budget) for rate-limit + 429 + context-overflow recovery. Full CI/CD pipeline (Node 22/24 × Linux/macOS/Windows) and release automation (auto-tag + GitHub Release + release-time smoke test).",
-    "version": "1.53.0"
+    "version": "1.54.0"
   },
   "plugins": [
     {
       "name": "get-design-done",
       "source": "./",
       "description": "Agent-orchestrated 5-stage design pipeline: Brief → Explore → Plan → Design → Verify. 22+ specialized agents, 9 connections (Figma, Refero, Preview, Storybook, Chromatic, Figma Writer, Graphify, Pinterest, Claude Design), Claude Design handoff, bidirectional Figma write-back, and a queryable intel store (.design/intel/) for dependency and learnings queries. Standalone commands: style, darkmode, compare, figma-write, graphify, handoff, analyze-dependencies, skill-manifest, extract-learnings. Embeds NNG heuristics, WCAG thresholds, typographic systems, motion framework, and anti-pattern catalog. Ships with a full CI/CD pipeline (Node 22/24 × Linux/macOS/Windows) and release automation. Optimization layer (v1.0.4.1, retroactive): gdd-router + gdd-cache-manager skills, PreToolUse budget-enforcer hook, tier-aware agent frontmatter, lazy checker gates, streaming synthesizer, /gdd:warm-cache + /gdd:optimize commands, and cost telemetry at .design/telemetry/costs.jsonl — targeting 50-70% per-task token-cost reduction with no quality-floor regression. v1.20.0 SDK foundation: gdd-state MCP server (11 typed tools), lockfile-safe STATE.md mutations, event stream at .design/telemetry/events.jsonl, resilience primitives (jittered-backoff, rate-guard, error-classifier, iteration-budget) with rate-limit + 429 + context-overflow recovery, and TypeScript toolchain.",
-      "version": "1.53.0",
+      "version": "1.54.0",
       "author": {
         "name": "hegemonart"
       },

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "get-design-done",
   "short_name": "gdd",
-  "version": "1.53.0",
+  "version": "1.54.0",
   "description": "Agent-orchestrated 5-stage design pipeline: Brief → Explore → Plan → Design → Verify. 59 specialized agents, 88 skills, 41 connection integrations (Figma, Refero, Preview, Storybook, Chromatic, Graphify, Slack, Linear, Jira, Notion, and more), handoff-first workflow via Claude Design bundles, bidirectional Figma write-back (annotations, Code Connect), queryable intel store (`.design/intel/`) for O(1) design surface lookups, and self-improvement loop (reflector agent, frontmatter + budget feedback, global-skills layer at `~/.claude/gdd/global-skills/`). Standalone commands: style, darkmode, compare, figma-write, graphify, handoff, analyze-dependencies, skill-manifest, extract-learnings, reflect, apply-reflections. Embeds NNG heuristics, WCAG thresholds, typographic systems, motion framework, and anti-pattern catalog. Ships with a full CI/CD pipeline (Node 22/24 × Linux/macOS/Windows, lint + schema + frontmatter + stale-ref + shellcheck + gitleaks + injection-scan + blocking size-budget) and release automation (auto-tag + GitHub Release + release-time smoke test). Optimization layer (v1.0.4.1, retroactive): gdd-router + gdd-cache-manager skills, PreToolUse budget-enforcer hook, tier-aware agent frontmatter, lazy checker gates, streaming synthesizer, /gdd:warm-cache + /gdd:optimize commands, and cost telemetry at .design/telemetry/costs.jsonl — targeting 50-70% per-task token-cost reduction with no quality-floor regression. v1.20.0 SDK foundation: gdd-state MCP server (11 typed tools), lockfile-safe STATE.md mutations, event stream at .design/telemetry/events.jsonl, resilience primitives (jittered-backoff, rate-guard, error-classifier, iteration-budget) with rate-limit + 429 + context-overflow recovery, and TypeScript toolchain. v1.27.7 ships gdd-mcp (Phase 27.7): 12 read-only MCP tools for sub-3s priming. v1.28.0 (Phase 28): Foundational References Tier 2 — 5 new reference files (color-theory, composition, proportion-systems, i18n, contrast-advanced), 2 verifier i18n probes + 1 explore i18n-readiness probe, 12 additive cross-link insertions across 10 existing references, 2 orthogonal audit-scoring lens-tags (composition_alignment + i18n_readiness).",
   "author": {
     "name": "hegemonart",

package/CHANGELOG.md

@@ -4,6 +4,47 @@ All notable changes to get-design-done are documented here. Versions follow [sem
 
 ---
 
+## [1.54.0] - 2026-06-03
+
+### Phase 54 - Composable Reference Addendums (Per-DS + Per-Framework + Per-Motion-Lib)
+
+One general mapper prompt could not be stack-aware: it missed Tailwind's `@theme` tokens, shadcn's `cn()` convention,
+vanilla-extract's `style({})` shape. Phase 54 adds 18 composable prompt addendums (one per design system, framework, and
+motion library) that the explore mappers compose into their prompt at spawn time based on the detected stack. Adapted
+from Understand-Anything's per-language/per-framework addendum pattern. Maintainer-authored and vendor-cross-checked;
+no LLM-generated content. Planned and executed via the GSD pipeline (5 parallel executors + 1 integration executor).
+
+### Breaking changes
+
+- **Mappers are now stack-aware.** `scripts/lib/detect/stack.cjs` detects `{ds, framework, motion_libs[]}` from
+  package.json deps + config files + import signatures; `scripts/lib/mapper-spawn.cjs` composes the matching addendums
+  (capped at 3: one DS, one framework, one motion) into each mapper's prompt before dispatch (additive and
+  backward-compatible: no detected stack or no addendum leaves the base prompt unchanged).
+- **Registry gains a `stack-addendum` type.** `reference/registry.schema.json` adds `"stack-addendum"` to the entry
+  type enum and an optional `composes_into` field; the 18 addendums register against it with their target mappers.
+
+### Added
+
+- **Design-system addendums** (`reference/systems/`): tailwind, shadcn, radix-themes, mui, chakra, vanilla-extract,
+  styled-components, css-modules. **Framework addendums** (`reference/frameworks/`): nextjs, remix, vite-react, astro,
+  sveltekit, storybook. **Motion-lib addendums** (`reference/motion/`): framer-motion, gsap, motion-one, react-spring.
+  Each is at most 50 lines with four sections (Conventions, File patterns, Gotchas, and an Example output fragment in
+  the Phase 52 DesignContext schema).
+- **`/gdd:new-addendum <kind> <name>`** skill + `scripts/lib/new-addendum.cjs` scaffolder (mirrors `/gdd:new-skill`;
+  validates the kind and slug, defaults `composes_into` by kind, writes the 4-section skeleton).
+- **Fallback + coverage**: an unmatched stack falls back to the base prompt and flags the gap; `gsd-health` reports a
+  "N/M detected stacks have addendums" coverage row.
+
+### Notes
+
+- 6-manifest lockstep at **v1.54.0** + `OFF_CADENCE_VERSIONS.add('1.54.0')` + 37 `manifests-version.txt` baselines.
+  Re-locked: skill-list (91 -> 92, +new-addendum) + the phase-28.5 distribution (new-addendum at 81 lines, clean; warn
+  count unchanged at 10) + skill-graph + the registry-diff baseline (+18 stack-addendum entries) + resilience-primitives
+  (+mapper-spawn.cjs +new-addendum.cjs) + the phase-42 compile count (115 -> 116) + the gsd-health check count (8 -> 9).
+  Tarball golden 944 -> 969 (+25). **No new runtime dependency.**
+
+---
+
 ## [1.53.0] - 2026-06-03
 
 ### Phase 53 - Semantic Mapper Engine (Louvain Batching + neighborMap + Fingerprint Incremental)

package/README.md

@@ -267,6 +267,8 @@ All 14 runtimes receive their native artifact layout (`skills/`, `command/`, `ag
 
 **Semantic mapper engine (v1.53.0).** Mappers get smart about scale and re-runs on top of the Phase 52 graph. Louvain community batching (`scripts/lib/mappers/compute-batches.mjs`, dep-free, deterministic) groups files that import each other so each parallel mapper sees a coherent slice; a neighborMap sidecar (`neighbor-map.mjs`) hands each batch its 1-hop external symbols so cross-batch edges emit without rereading other batches. SHA-256 fingerprinting (`sdk/fingerprint/`) classifies each re-run as SKIP / PARTIAL / ARCHITECTURE / FULL, so `/gdd:discover` (now incremental by default, `--full` to override) only re-discovers what actually changed. A graph-context-reviewer agent runs nine checks on the assembled graph (hard-reject on schema or referential breakage, soft-warn otherwise). Node builtins only, no `graphology`, no embeddings. **No new runtime dependency.**
 
+**Composable reference addendums (v1.54.0).** One general mapper prompt cannot know Tailwind's `@theme` tokens from shadcn's `cn()` from vanilla-extract's `style({})`. Phase 54 adds 18 stack-specific addendums (8 design systems, 6 frameworks, 4 motion libraries) under `reference/{systems,frameworks,motion}/`, each at most 50 lines with Conventions / File patterns / Gotchas / Example-output sections. `scripts/lib/detect/stack.cjs` detects the project stack from dependencies plus config files and import signatures; `scripts/lib/mapper-spawn.cjs` composes the matching addendums (capped at one DS + one framework + one motion) into each explore mapper's prompt at spawn time, additively, so a project on an unknown stack just keeps the base prompt and `gsd-health` reports the coverage gap. A `/gdd:new-addendum` scaffolder adds more. Maintainer-authored, vendor-cross-checked, no LLM-generated content. **No new runtime dependency.**
+
 Verify with:
 
 ```

package/SKILL.md

@@ -2,7 +2,7 @@
 name: get-design-done
 short_name: gdd
 description: "Master design pipeline for Claude Code. 5-stage workflow: Brief → Explore → Plan → Design → Verify. Run 'brief' first in any new project to capture the design problem, then 'explore' to inventory the codebase and interview for context. Invoke without arguments for status and auto-routing."
-argument-hint: "[brief|explore|plan|design|verify|handoff|map|next|help|status|style|darkmode|live|compare|figma-write|graphify|discuss|list-assumptions|progress|health|todo|stats|note|plant-seed|add-backlog|review-backlog|scan|discover|settings|update|reapply-patches|audit|pause|resume|new-cycle|debug|quick|new-project|complete-cycle|fast|do|ship|undo|pr-branch|sketch|sketch-wrap-up|spike|spike-wrap-up|reflect|apply-reflections|analyze-dependencies|extract-learnings|skill-manifest|pin|unpin|list-pins|new-skill|instinct|warm-cache|optimize|cache-manager|watch-authorities|check-update|benchmark|recall|timeline|continue|zoom-out]"
+argument-hint: "[brief|explore|plan|design|verify|handoff|map|next|help|status|style|darkmode|live|compare|figma-write|graphify|discuss|list-assumptions|progress|health|todo|stats|note|plant-seed|add-backlog|review-backlog|scan|discover|settings|update|reapply-patches|audit|pause|resume|new-cycle|debug|quick|new-project|complete-cycle|fast|do|ship|undo|pr-branch|sketch|sketch-wrap-up|spike|spike-wrap-up|reflect|apply-reflections|analyze-dependencies|extract-learnings|skill-manifest|pin|unpin|list-pins|new-skill|new-addendum|instinct|warm-cache|optimize|cache-manager|watch-authorities|check-update|benchmark|recall|timeline|continue|zoom-out]"
 user-invocable: true
 ---
 
@@ -94,6 +94,7 @@ Each stage produces artifacts in `.design/` inside the current project.
 | `unpin <skill>` | `get-design-done:gdd-unpin` | Phase 46 - remove pinned aliases for a skill (only files carrying the gdd-pinned-skill marker) |
 | `list-pins` | `get-design-done:gdd-list-pins` | Phase 46 - show pinned aliases per harness with their source skill and last-pinned timestamp |
 | `new-skill <name>` | `get-design-done:gdd-new-skill` | Phase 50 - interactive scaffolder for a new Phase 28.5 + v3-compliant skill (multi-paragraph description, lifecycle stage, optional composes_with); writes source/skills/<name>/SKILL.md |
+| `new-addendum <kind> <name>` | `get-design-done:gdd-new-addendum` | Phase 54 - scaffold a composable reference addendum (kind = system\|framework\|motion); validates the slug, defaults composes_into by kind, writes a 4-section skeleton at reference/{systems\|frameworks\|motion}/<name>.md that an explore mapper composes at spawn time |
 | `instinct [list\|query <kw>\|promote <id>]` | `get-design-done:gdd-instinct` | Phase 51 - inspect and manage atomic instinct learning units (project + global stores); list, search by keyword, or promote a vetted project instinct to global once it clears the cross-project gate |
 | `quality-gate` | `get-design-done:quality-gate` | Phase 25 - parallel lint/type/test/visual command runner; classifies failures via quality-gate-runner agent |
 | `turn-closeout` | `get-design-done:turn-closeout` | Phase 25 - Stop-hook mirror skill; finalizes per-turn STATE blocks and emits closeout events |

package/agents/component-taxonomy-mapper.md

@@ -18,6 +18,9 @@ writes:
 
 # component-taxonomy-mapper
 
+<!-- {{addendum_block}} -->
+Stack-specific guidance (a `## Stack-specific guidance` block for the detected DS / framework / motion library) is appended here at spawn time by `scripts/lib/mapper-spawn.cjs`. When present, follow it as an extension of the rules below.
+
 ## Role
 
 You inventory the component taxonomy of the codebase. Zero session memory. You do not modify source code or spawn other agents.

package/agents/motion-mapper.md

@@ -18,6 +18,7 @@ writes:
 
 # motion-mapper
 
+<!-- {{addendum_block}}: a `## Stack-specific guidance` block for the detected DS / framework / motion library is appended here at spawn time by scripts/lib/mapper-spawn.cjs. When present, follow it as an extension of the rules below. -->
 ## Role
 
 You inventory motion and animation patterns. Zero session memory. You do not modify source code and do not spawn other agents.

package/agents/token-mapper.md

@@ -18,6 +18,9 @@ writes:
 
 # token-mapper
 
+<!-- {{addendum_block}} -->
+Stack-specific guidance (a `## Stack-specific guidance` block for the detected DS / framework / motion library) is appended here at spawn time by `scripts/lib/mapper-spawn.cjs`. When present, follow it as an extension of the rules below.
+
 ## Role
 
 You map design tokens from the codebase. Zero session memory - everything you need is in the prompt and `<required_reading>`. You do not modify source code or spawn other agents.

package/dist/claude-code/.claude/skills/new-addendum/SKILL.md

@@ -0,0 +1,81 @@
+---
+name: gdd-new-addendum
+description: "Scaffolds a new Phase-54 composable reference addendum for a design-system, framework, or motion library: validates the kind and the slug, defaults composes_into by kind, and writes a 4-section skeleton at reference/{systems|frameworks|motion}/<name>.md from the pure generator. Use when adding stack-specific guidance that an explore mapper should compose at spawn time and you want the frontmatter, the composes_into wiring, and the mandatory sections correct from the first commit. Activates for requests involving authoring a reference addendum, adding stack-specific mapper guidance, scaffolding a systems or frameworks or motion doc, or registering a new design-system."
+argument-hint: "<kind> <name>"
+tools: Read, Write, Bash, AskUserQuestion
+user-invocable: true
+---
+
+# /gdd:new-addendum
+
+**Role:** Scaffold a contract-compliant stack addendum. Validate the kind and the name, then write `reference/{systems|frameworks|motion}/<name>.md` from the pure generator at `scripts/lib/new-addendum.cjs`. This skill writes ONE reference file. It does NOT touch `reference/registry.json` and does NOT run any build; it prints the exact follow-up steps instead.
+
+An addendum is a registry entry, not a skill. Read `reference/registry.json` for the `type:"stack-addendum"` entry shape and `scripts/lib/mapper-spawn.cjs` for how `composes_into` selects an addendum at spawn time. Read one shipped example first, for instance `reference/systems/tailwind.md`, to match the house style.
+
+## Step 1 - Gather the fields
+
+1. **kind**: the first token of `$ARGUMENTS` if present, else ask. Must be one of `system`, `framework`, or `motion`. This picks the target subdir and the default `composes_into`.
+2. **name**: the second token of `$ARGUMENTS` if present, else ask. Must match `^[a-z0-9][a-z0-9-._]*$`. The basename is also the matcher key in `mapper-spawn.cjs`, so it must equal the value `detectStack` reports for this stack (for example `tailwind`, `nextjs`, `framer-motion`). Reject a `reference/{dir}/<name>.md` collision.
+3. **composes_into** (optional): accept the kind default, or override with a comma list of mapper names. Defaults: `system` to `token-mapper, component-taxonomy-mapper`; `framework` to `component-taxonomy-mapper, visual-hierarchy-mapper`; `motion` to `motion-mapper`.
+
+Resolve the target path and check for a collision:
+
+```bash
+node -e "
+const a = require('./scripts/lib/new-addendum.cjs');
+console.log(a.targetPathFor(process.argv[1], process.argv[2]));
+" "<kind>" "<name>"
+```
+
+If that path already exists, stop and tell the user to edit the existing file instead.
+
+## Step 2 - Write the file
+
+Build the record and render the skeleton with the pure generator, then write it with the Write tool (not shell redirection):
+
+```bash
+node -e "
+const a = require('./scripts/lib/new-addendum.cjs');
+const rec = a.buildAddendumRecord({
+  kind: process.env.AD_KIND,
+  name: process.env.AD_NAME,
+  composesInto: process.env.AD_COMPOSES || undefined,
+});
+process.stdout.write(a.renderAddendumMd(rec));
+"
+```
+
+`buildAddendumRecord` throws on an invalid kind, an invalid name, or a malformed composes_into list. Surface the thrown message to the user and re-prompt the offending field. Capture stdout and write it verbatim to the path from Step 1 via the Write tool.
+
+## Step 3 - Fill the four sections
+
+The skeleton ships four mandatory sections with TODO placeholders: Conventions, File patterns, Gotchas, Example output. Replace every TODO with terse vendor-checked bullets (keep the file at or under about 50 lines). Rules:
+
+- Lead with the real vendor docs URL in the attribution comment.
+- The Example output block uses ONLY the Phase 52 DesignContext schema (node types token / component / variant / state / motion-fragment / screen / layer; edge types uses-token / composes / extends / transitions-to / mirrors).
+- Tags must come from `reference/design-context-tag-vocab.md`; drop any tag not in that vocabulary.
+- For a motion addendum, reuse the `reference/motion-transition-taxonomy.md` duration classes (instant / quick / standard / slow / narrative) and call out the seconds-vs-ms-vs-no-duration unit trap.
+- No em dashes anywhere (the `lint:prose` gate scans `reference/`).
+
+## Step 4 - Tell the user the follow-up
+
+The skill stops here by contract. Print the next steps for the maintainer to run:
+
+```
+1. Add a registry entry for "<name>" to reference/registry.json
+   (name addendum-<kind>-<name>, path, type "stack-addendum", phase 54, kind, composes_into, description).
+2. node -e "require('./scripts/lib/reference-registry.cjs').validateRegistry({cwd:process.cwd()})"
+   must report ok:true (the round-trip scan picks up the new subdir file).
+3. npm test (the reference-registry + phase-54 suites must stay green).
+```
+
+The registry round-trip test stays red until the registry entry exists; that is expected and is the maintainer's step.
+
+## Do Not
+
+- Do not edit `reference/registry.json`, `package.json`, or `scripts/lib/manifest/skills.json`.
+- Do not run a build or the registry generator for the user; print the steps.
+- Do not write the file with shell redirection; use the Write tool so the content is exact.
+- Do not invent vendor facts; the addendum content must be vendor-checked.
+
+## NEW-ADDENDUM COMPLETE

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hegemonart/get-design-done",
-  "version": "1.53.0",
+  "version": "1.54.0",
   "description": "A design-quality pipeline for AI coding agents: brief, plan, implement, and verify UI work against your design system.",
   "author": "Hegemon",
   "homepage": "https://github.com/hegemonart/get-design-done",

package/reference/frameworks/astro.md

@@ -0,0 +1,43 @@
+---
+name: astro
+kind: framework
+composes_into: [component-taxonomy-mapper, visual-hierarchy-mapper]
+phase: 54
+---
+<!-- Vendor docs: https://docs.astro.build. -->
+
+# Astro
+
+## Conventions
+
+- An `.astro` file is a script fence (the `---` code fence runs at build or on the server) plus an HTML template; props arrive via `Astro.props`.
+- File routing lives in `src/pages/` (`.astro` and `.md`). Framework components are static by default; `client:load`, `client:idle`, `client:visible`, and `client:only` directives mark hydration, which is the interactivity signal.
+- `<style>` is scoped by default; `is:global` or `:global()` escapes the scope. Content collections are typed Markdown or MDX in `src/content/`, configured by `content.config.ts` with Zod.
+
+## File patterns
+
+- `src/pages/**/*.astro`, `src/layouts/*.astro`, `src/components/*.astro`, `content.config.ts`, `astro.config.mjs`.
+- Identify via: astro in deps plus a `src/pages/` directory.
+
+## Gotchas
+
+- Most `.astro` files ship zero js; only `client:*`-directed islands are interactive, so motion attaches only to hydrated islands.
+- Scoped `<style>` rewrites class names locally; treat those names as component-local, not global tokens.
+- `src/pages/*.astro` files are screens; layouts wrap them via a `<slot/>` (emit a composes edge).
+- Global tokens enter via an `is:global` block or a stylesheet imported in a layout.
+
+## Example output
+
+```json
+{
+  "schema_version": "52.0",
+  "nodes": [
+    { "id": "scr.index", "type": "screen", "name": "/", "summary": "Home page from src/pages/index.astro.", "complexity": "simple", "tags": ["navigation"] },
+    { "id": "lay.base", "type": "layer", "subtype": "Template", "name": "BaseLayout", "summary": "Layout wrapping pages via slot, holds global styles.", "complexity": "moderate", "tags": ["template", "layout"] },
+    { "id": "cmp.counter", "type": "component", "name": "Counter", "summary": "Hydrated island marked client:visible, interactive.", "complexity": "moderate", "tags": ["interactive"] }
+  ],
+  "edges": [
+    { "source": "lay.base", "target": "scr.index", "type": "composes", "direction": "forward", "weight": 0.9 }
+  ]
+}
+```

package/reference/frameworks/nextjs.md

@@ -0,0 +1,44 @@
+---
+name: nextjs
+kind: framework
+composes_into: [component-taxonomy-mapper, visual-hierarchy-mapper]
+phase: 54
+---
+<!-- Vendor docs: https://nextjs.org/docs/app. -->
+
+# Next.js
+
+## Conventions
+
+- Two routers. App Router (`app/`): folder names are URL segments; `page.tsx` is the routable surface (a screen node). `layout.tsx` wraps and nests its segment; the root layout owns `<html>`/`<body>` and imports `globals.css`.
+- Special files: `loading`, `error`, `template`, `route`. Server Components are the default; `'use client'` marks the client boundary, and only client components are interactive.
+- Pages Router (legacy `pages/`): one file is one route; `_app`/`_document` are shells; data via `getServerSideProps`/`getStaticProps`.
+
+## File patterns
+
+- App Router: `app/**/page.tsx`, `app/**/layout.tsx`, `app/globals.css`.
+- Pages Router: `pages/**`, `pages/_app.tsx`, `pages/_document.tsx`.
+- Identify via: next in deps plus an `app/` or `pages/` directory.
+
+## Gotchas
+
+- Screen nodes are `page.tsx` files; set the node path to the route, not the file path.
+- A `layout.tsx` plus `page.tsx` in one folder is one screen and its layout; emit a composes edge layout to page.
+- Without `'use client'`, a component is not a motion or hover candidate; the boundary gates interactivity.
+- Global tokens enter at the root-layout `globals.css`.
+
+## Example output
+
+```json
+{
+  "schema_version": "52.0",
+  "nodes": [
+    { "id": "scr.dashboard", "type": "screen", "name": "/dashboard", "summary": "Routable dashboard page from app/dashboard/page.tsx.", "complexity": "moderate", "tags": ["navigation", "layout"] },
+    { "id": "lay.root", "type": "layer", "subtype": "Template", "name": "RootLayout", "summary": "Root layout owning html and body, imports global tokens.", "complexity": "moderate", "tags": ["template", "layout"] },
+    { "id": "cmp.chart", "type": "component", "name": "Chart", "summary": "Client component marked use client, interactive.", "complexity": "complex", "tags": ["interactive", "data-display"] }
+  ],
+  "edges": [
+    { "source": "lay.root", "target": "scr.dashboard", "type": "composes", "direction": "forward", "weight": 0.9 }
+  ]
+}
+```

package/reference/frameworks/remix.md

@@ -0,0 +1,44 @@
+---
+name: remix
+kind: framework
+composes_into: [component-taxonomy-mapper, visual-hierarchy-mapper]
+phase: 54
+---
+<!-- Vendor docs: https://remix.run/docs/en/main/file-conventions/routes (Remix v2 / React Router v7 framework mode). -->
+
+# Remix
+
+## Conventions
+
+- `app/routes/` uses file conventions; `app/root.tsx` is the root layout and renders an `Outlet`.
+- Flat-routes v2: dot-delimited filenames nest, so `concerts.$city.tsx` is a child of `concerts.tsx` and renders inside its `Outlet`. A trailing `_` opts a segment out of layout nesting; a leading `_` marks a pathless layout.
+- Each route module co-locates a `loader` (server read), an `action` (server mutation), and a default-export component (the screen).
+- Global styles ship via an exported `links` array or a CSS import in `root.tsx`.
+
+## File patterns
+
+- `app/root.tsx`, `app/routes/*.tsx` (dot-segment names).
+- Identify via: @remix-run/* or react-router in deps plus an `app/routes/` directory.
+
+## Gotchas
+
+- A route file is a screen; parse the dot-naming to recover the layout tree and emit composes edges parent to child.
+- `loader` and `action` are server data functions, not components; do not map them as nodes.
+- A trailing `_` breaks visual nesting even when the dot path looks nested; respect it when building edges.
+- Tokens enter via the `root.tsx` global stylesheet.
+
+## Example output
+
+```json
+{
+  "schema_version": "52.0",
+  "nodes": [
+    { "id": "lay.root", "type": "layer", "subtype": "Template", "name": "Root", "summary": "Root layout with Outlet and global links.", "complexity": "moderate", "tags": ["template", "layout"] },
+    { "id": "scr.concerts", "type": "screen", "name": "concerts", "summary": "Parent route screen rendering nested city Outlet.", "complexity": "moderate", "tags": ["navigation"] },
+    { "id": "scr.concerts.city", "type": "screen", "name": "concerts.$city", "summary": "Child route screen nested in concerts via dot naming.", "complexity": "simple", "tags": ["navigation"] }
+  ],
+  "edges": [
+    { "source": "scr.concerts", "target": "scr.concerts.city", "type": "composes", "direction": "forward", "weight": 0.8 }
+  ]
+}
+```

package/reference/frameworks/storybook.md

@@ -0,0 +1,44 @@
+---
+name: storybook
+kind: framework
+composes_into: [component-taxonomy-mapper, visual-hierarchy-mapper]
+phase: 54
+---
+<!-- Vendor docs: https://storybook.js.org/docs/writing-stories. -->
+
+# Storybook
+
+## Conventions
+
+- The richest source of variant and state nodes. A `*.stories.tsx` file in CSF3 has a default export (the meta, typed `Meta<typeof X>`, with `component`, `title`, `args`, `argTypes`) and named exports (the stories, typed `StoryObj`, mostly `args`).
+- Each named story is a concrete variant or state of one component (Primary, Disabled, Loading, Small).
+- `argTypes` declares the controllable prop space; its enumerated `options` describe the full variant axis. `decorators` wrap a story; `play` scripts an interaction.
+
+## File patterns
+
+- `*.stories.@(tsx|jsx|ts|mdx)`, `.storybook/main.ts`, `.storybook/preview.ts` or `preview.tsx`.
+- Identify via: @storybook/* in deps plus any `*.stories.*` file.
+
+## Gotchas
+
+- Map each named story to a variant node, or a state node when the name or args set hover, focus, disabled, active, or loading; link it back to `meta.component` via composes or extends.
+- `argTypes.options` enumerates the full variant space and is richer than a source scan; prefer it.
+- The meta default export is metadata, not a component; decorators are wrappers, not nodes.
+- Handle CSF2 (a `template.bind({})` story) the same as CSF3.
+
+## Example output
+
+```json
+{
+  "schema_version": "52.0",
+  "nodes": [
+    { "id": "cmp.button", "type": "component", "name": "Button", "summary": "Component referenced by the stories meta.", "complexity": "moderate", "tags": ["interactive", "atom"] },
+    { "id": "var.button.primary", "type": "variant", "name": "Primary", "summary": "Primary variant story of Button.", "complexity": "simple", "tags": ["interactive"] },
+    { "id": "st.button.disabled", "type": "state", "name": "Disabled", "summary": "Disabled state story of Button.", "complexity": "simple", "tags": ["disabled", "state"] }
+  ],
+  "edges": [
+    { "source": "var.button.primary", "target": "cmp.button", "type": "extends", "direction": "forward", "weight": 0.9 },
+    { "source": "st.button.disabled", "target": "cmp.button", "type": "extends", "direction": "forward", "weight": 0.9 }
+  ]
+}
+```

package/reference/frameworks/sveltekit.md

@@ -0,0 +1,43 @@
+---
+name: sveltekit
+kind: framework
+composes_into: [component-taxonomy-mapper, visual-hierarchy-mapper]
+phase: 54
+---
+<!-- Vendor docs: https://svelte.dev/docs/kit/routing. -->
+
+# SvelteKit
+
+## Conventions
+
+- `src/routes/` uses file routing: `+page.svelte` is a screen, `+layout.svelte` is a wrapper (hierarchical, via `<slot/>` or `{@render children()}`), `+page.ts`/`+page.server.ts` hold `load`, and `+server.ts` is an endpoint.
+- `<style>` in a `.svelte` file is auto-scoped; `:global()` escapes the scope.
+- Shared code lives in `src/lib/` behind the `$lib` alias. Global CSS (`app.css`) is imported once in the root `+layout.svelte`. `src/app.html` is the document shell.
+
+## File patterns
+
+- `src/routes/**/+page.svelte`, `+layout.svelte`, `src/lib/`, `src/app.css`, `svelte.config.js`.
+- Identify via: @sveltejs/kit in deps plus a `src/routes/` directory.
+
+## Gotchas
+
+- Only `+page`-prefixed and `+layout`-prefixed files are routes; a sibling `+page.server.ts` is data, not a screen.
+- Layout nesting follows directory depth; emit one composes edge per level from layout to page.
+- Scoped styles are component-local; do not promote those class names to global tokens.
+- Tokens live in `app.css` under `:root` or a `$lib` theme module; a `$lib` import is a depends-on edge.
+
+## Example output
+
+```json
+{
+  "schema_version": "52.0",
+  "nodes": [
+    { "id": "scr.home", "type": "screen", "name": "/", "summary": "Home screen from src/routes/+page.svelte.", "complexity": "simple", "tags": ["navigation"] },
+    { "id": "lay.root", "type": "layer", "subtype": "Template", "name": "RootLayout", "summary": "Root +layout.svelte wrapping pages, imports app.css.", "complexity": "moderate", "tags": ["template", "layout"] },
+    { "id": "tok.color.bg", "type": "token", "subtype": "color", "name": "--bg", "summary": "Surface color token declared in app.css :root.", "complexity": "simple", "tags": ["color", "surface"] }
+  ],
+  "edges": [
+    { "source": "lay.root", "target": "scr.home", "type": "composes", "direction": "forward", "weight": 0.9 }
+  ]
+}
+```

package/reference/frameworks/vite-react.md

@@ -0,0 +1,43 @@
+---
+name: vite-react
+kind: framework
+composes_into: [component-taxonomy-mapper, visual-hierarchy-mapper]
+phase: 54
+---
+<!-- Vendor docs: https://vite.dev/guide and https://reactrouter.com. -->
+
+# Vite + React
+
+## Conventions
+
+- No built-in routing. `index.html` is the entry and loads `src/main.tsx`, which mounts `<App/>` into the `#root` element.
+- Routing is opt-in via react-router-dom: either `createBrowserRouter([{ path, element }])` with `<RouterProvider>`, or JSX `<Routes>`/`<Route>`. Screens are config objects, not files.
+- Layout is convention only (`src/components`, `src/pages`). Global CSS imports live in `main.tsx` or `App.tsx`. Path aliases come from `vite.config` `resolve.alias` (such as `@/`).
+
+## File patterns
+
+- `index.html`, `src/main.tsx` (`createRoot().render`), `vite.config.ts`.
+- Identify via: vite plus react in deps and a `src/main.tsx` entry.
+
+## Gotchas
+
+- Screens come from the router config, not the filesystem; parse `createBrowserRouter` or `<Route path>` to recover them.
+- `src/pages/*` is a convention, not a route source; do not infer screens from that folder alone.
+- The entry is `main.tsx`; treat its mounted `<App/>` as the tree root.
+- There is no server or client split; everything is client, so any component can be a motion or hover candidate.
+
+## Example output
+
+```json
+{
+  "schema_version": "52.0",
+  "nodes": [
+    { "id": "scr.home", "type": "screen", "name": "/", "summary": "Home screen from a createBrowserRouter route element.", "complexity": "simple", "tags": ["navigation"] },
+    { "id": "lay.app", "type": "layer", "subtype": "Template", "name": "App", "summary": "Root App mounted into #root by main.tsx.", "complexity": "moderate", "tags": ["template", "layout"] },
+    { "id": "scr.settings", "type": "screen", "name": "/settings", "summary": "Settings screen declared in the router config.", "complexity": "moderate", "tags": ["navigation", "form"] }
+  ],
+  "edges": [
+    { "source": "lay.app", "target": "scr.home", "type": "composes", "direction": "forward", "weight": 0.8 }
+  ]
+}
+```

package/reference/interaction.md

@@ -46,3 +46,4 @@ Interaction is the broadest design domain. It governs every point where a user a
 - Civic one-thing-per-page forms: `reference/domains/civic-patterns.md`
 - Typography: `reference/typography.md`
 - Color: `reference/color.md`
+- Stack-specific component and token conventions (Phase 54 composable addendums): `reference/systems/` (design systems) and `reference/frameworks/` (frameworks). These are composed into the explore mappers at spawn time by `scripts/lib/mapper-spawn.cjs` when `detectStack` matches the project, and are registered as `type:"stack-addendum"` entries in `reference/registry.json`.

package/reference/motion/framer-motion.md

@@ -0,0 +1,45 @@
+---
+name: framer-motion
+kind: motion
+composes_into: [motion-mapper]
+phase: 54
+---
+<!-- Vendor docs: https://motion.dev/docs/react-animation. -->
+
+# Framer Motion
+
+## Conventions
+
+- Declarative: `motion.*` elements take `initial` / `animate` / `exit` plus gesture props `whileHover` / `whileTap` / `whileDrag` / `whileInView` / `drag`.
+- Named `variants` propagate parent to child; `staggerChildren` sequences them.
+- `transition.type` is the model: `spring` (stiffness/damping/mass, or duration+bounce, default bounce ~0.25, keep <0.1 for UI) vs `tween` (duration plus named ease).
+- `AnimatePresence` (stable `key`) enables `exit`; `layout` / `layoutId` drive FLIP and shared-element morphs.
+
+## File patterns
+
+- `import { motion, AnimatePresence } from "motion/react"` (or legacy `"framer-motion"`).
+- Markers: `motion.div`, `whileHover`, `variants`, `layoutId`, `useScroll`.
+- Identify via: the `motion/react` import plus `motion.*` JSX.
+
+## Gotchas
+
+- Unit trap: tween `duration` is SECONDS, so multiply by 1000 BEFORE bucketing; the `spring()` value-fn duration is milliseconds.
+- Extract a duration bucket via the taxonomy: instant <100ms, quick 100-200, standard 200-300, slow 300-500, narrative 500+.
+- Easing class: read `transition.type` (spring is physics; tween is named or cubic-bezier).
+- Gesture vs tween: `whileHover` / `whileTap` / `whileDrag` / `whileInView` are gesture fragments; `initial`->`animate`/`exit` are transitions.
+- A matched `layoutId` pair is a shared-element link, emitted as `transitions-to`.
+
+## Example output
+
+```json
+{
+  "schema_version": "52.0",
+  "nodes": [
+    { "id": "mf.button.hover", "type": "motion-fragment", "name": "Button whileHover", "summary": "Pointer-reactive spring lift on hover.", "complexity": "simple", "tags": ["motion", "gesture", "hover"] },
+    { "id": "mf.card.enter", "type": "motion-fragment", "name": "Card entrance", "summary": "Quick tween fade-and-rise on mount.", "complexity": "simple", "tags": ["motion", "transition", "enter", "duration"] }
+  ],
+  "edges": [
+    { "source": "mf.card.enter", "target": "mf.button.hover", "type": "composes", "direction": "forward", "weight": 0.5 }
+  ]
+}
+```

package/reference/motion/gsap.md

@@ -0,0 +1,45 @@
+---
+name: gsap
+kind: motion
+composes_into: [motion-mapper]
+phase: 54
+---
+<!-- Vendor docs: https://gsap.com/docs/v3/GSAP/Tween. -->
+
+# GSAP
+
+## Conventions
+
+- Imperative, no component model: `gsap.to(target, { duration, ease, ... })` plus `.from` / `.fromTo` / `.set`.
+- `gsap.timeline({ defaults })` sequences tweens; children inherit the timeline defaults.
+- Eases are strings `"<name>.<inOut>"`: power0 through power4, none (linear), sine / expo / circ / back / elastic / bounce / steps(); default is `power1.out`.
+- `ScrollTrigger` (registered via `gsap.registerPlugin`) binds a tween to scroll. The core has no spring.
+
+## File patterns
+
+- `import gsap from "gsap"`; `import { ScrollTrigger } from "gsap/ScrollTrigger"`.
+- Markers: `gsap.to(`, `gsap.timeline(`, `registerPlugin`, often inside `useGSAP` or `useEffect`.
+- Identify via: the `gsap` import plus a `gsap.to` / `gsap.timeline` call.
+
+## Gotchas
+
+- Unit trap: `duration` is SECONDS, so multiply by 1000 BEFORE bucketing.
+- Extract a duration bucket via the taxonomy: instant <100ms, quick 100-200, standard 200-300, slow 300-500, narrative 500+.
+- Easing class: every ease string is a tween (named or eased); GSAP core has no native spring.
+- Gesture vs tween: a `ScrollTrigger`-bound tween is a scroll-linked fragment; a bare `timeline` is an orchestrated transition.
+- Targets are selectors or refs, so link each fragment to the component that owns the ref.
+
+## Example output
+
+```json
+{
+  "schema_version": "52.0",
+  "nodes": [
+    { "id": "mf.hero.reveal", "type": "motion-fragment", "name": "Hero scroll reveal", "summary": "Slow eased tween bound to ScrollTrigger.", "complexity": "moderate", "tags": ["motion", "transition", "duration", "easing"] },
+    { "id": "mf.list.stagger", "type": "motion-fragment", "name": "List stagger", "summary": "Timeline staggering item entrances.", "complexity": "moderate", "tags": ["motion", "transition", "enter"] }
+  ],
+  "edges": [
+    { "source": "mf.list.stagger", "target": "mf.hero.reveal", "type": "transitions-to", "direction": "forward", "weight": 0.4 }
+  ]
+}
+```