@hegemonart/get-design-done 1.51.0 → 1.52.0

package/agents/visual-hierarchy-mapper.md

@@ -11,6 +11,7 @@ typical-duration-seconds: 45
 reads-only: false
 writes:
   - ".design/map/visual-hierarchy.md"
+  - ".design/fragments/visual-hierarchy-mapper.json"
 ---
 
 @reference/shared-preamble.md
@@ -117,9 +118,37 @@ Total: N findings.
 ```
 ```
 
+## Graph fragment emission
+
+Dual-emit: keep writing `.design/map/visual-hierarchy.md` above, and ALSO emit a typed graph fragment for the synthesizer to merge into `.design/context-graph.json`. Fragment shape and field rules come from `reference/design-context-schema.md`; allowed `tags[]` come from `reference/design-context-tag-vocab.md`. Do not invent fields or tags outside those two references.
+
+### 1. Deterministic phase (structural nodes/edges)
+
+Run the matching extractor over the same source roots you scanned above:
+
+```bash
+node scripts/lib/design-context/extract-visual-hierarchy.mjs <source_root> [<source_root>...] > .design/fragments/visual-hierarchy-mapper.json
+```
+
+`extract-visual-hierarchy.mjs` walks the source roots with regex (zero-dep) and returns a Fragment whose `nodes[]` have `id`, `type` (`screen` for pages or routes, `pattern` for layout patterns, `anti-pattern` for hierarchy violations you flagged), and `name` filled, with stub `summary` you must replace.
+
+### 2. LLM phase (fill summary, tags, complexity)
+
+For every node the extractor produced, set:
+
+- `summary`: one sentence describing the screen or pattern and its hierarchy signal, distinct from `name`. Example for an F-pattern node: "Left-aligned scan path with stacked content blocks".
+- `tags[]`: pick from `reference/design-context-tag-vocab.md` only (hierarchy terms such as `f-pattern`, `z-pattern`, `centered`, `type-scale`, `focal-weight`). Drop any tag not in the vocab.
+- `complexity`: `simple` for a single layout pattern, `moderate` for a screen combining two patterns, `complex` for a screen with nested or competing focal regions.
+
+Add edges the extractor cannot infer: two screens sharing a layout pattern are `mirrors`; a flagged anti-pattern that contradicts a sibling screen's pattern is `conflicts-with`. Set `direction` and `weight` per the schema.
+
+### 3. Write the fragment
+
+Write the completed Fragment to `.design/fragments/visual-hierarchy-mapper.json` with `schema_version`, `mapper: "visual-hierarchy-mapper"`, `generated_at` (ISO 8601), the enriched `nodes[]`, and `edges[]`. Resolve the main repo root the same way the rest of the pipeline does so a worktree run does not leak the file.
+
 ## Constraints
 
-No modifications outside `.design/map/`. No git. No agent spawning.
+No modifications outside `.design/map/` and `.design/fragments/`. No git. No agent spawning.
 
 ## Record
 

package/dist/claude-code/.claude/skills/context/SKILL.md

@@ -0,0 +1,137 @@
+---
+name: gdd-context
+description: "Queries the typed DesignContext graph at .design/context-graph.json - the design-semantic map of tokens, components, variants, states, motion, a11y patterns, screens, layers, and design patterns plus the edges between them. Lists and filters nodes and edges, traces a path between two nodes, finds the consumers of a node, and reports unreachable nodes, dependency cycles, and coverage. Use when the user wants to inspect the design graph, find what depends on a token or component, trace how one node reaches another, or check graph health. Activates for requests involving the design context graph, design dependencies, token consumers, component composition, unreachable design nodes, design cycles, or design coverage."
+argument-hint: "[nodes --type X | edges --type Z | path <a> <b> | consumers-of <id> | unreachable | cycles | coverage]"
+tools: Read, Bash
+user-invocable: true
+---
+
+# /gdd:context
+
+**Role:** Read-only front end for the typed DesignContext graph. The graph is a design-semantic map: nodes are tokens, components, variants, states, motion fragments, a11y patterns, screens, layers, and design patterns; edges connect them (uses-token, composes, extends, transitions-to, depends-on, mirrors, conflicts-with, referenced-by, tested-by, documented-by, consumes-context, provides-context). This skill queries that graph. It never writes to it. The graph is authored by the mapper agents plus the design-research-synthesizer; this skill only reads.
+
+The query engine ships at `scripts/lib/design-context-query.cjs` (authored elsewhere; this skill only calls it). It is pure and dep-free, exposing `load`, `nodes`, `edges`, `path`, `consumersOf`, `unreachable`, `cycles`, and `coverage`. The merged graph lives at `.design/context-graph.json` with the shape `{ schema_version, generated_at, nodes[], edges[] }`.
+
+If `.design/context-graph.json` is absent, print: `No DesignContext graph yet. Run the design research pipeline (mappers plus /gdd:synthesize) to generate .design/context-graph.json.` Then STOP. Do not invent a graph.
+
+The engine exposes a module API rather than a CLI, so drive it from a short `node -e` script, the same way other skills call a `scripts/lib` helper:
+
+```bash
+node -e "const q=require('${CLAUDE_PLUGIN_ROOT}/scripts/lib/design-context-query.cjs'); \
+  const g=q.load('.design/context-graph.json'); \
+  console.log(JSON.stringify(q.nodes(g, { type: process.env.NODE_TYPE || undefined, tag: process.env.TAG || undefined })));"
+```
+
+## Invocation Modes
+
+| Command | Behavior |
+|---|---|
+| `/gdd:context nodes` | List graph nodes, optionally filtered by `--type` and `--tag` (default mode). |
+| `/gdd:context edges` | List graph edges, optionally filtered by `--type`. |
+| `/gdd:context path <a> <b>` | Trace a path from node `<a>` to node `<b>`. |
+| `/gdd:context consumers-of <id>` | List the nodes that consume node `<id>`. |
+| `/gdd:context unreachable` | List nodes no edge reaches. |
+| `/gdd:context cycles` | List dependency cycles in the graph. |
+| `/gdd:context coverage` | Report graph coverage (typed and tagged ratios). |
+
+Output discipline: emit JSON when a tool or another skill is the caller; render a compact table when a person is at the terminal.
+
+## nodes
+
+List nodes. `--type <t>` filters by node type (token, component, variant, state, motion-fragment, a11y-pattern, screen, layer, pattern, anti-pattern). `--tag <tag>` filters by a controlled tag. Call `nodes(graph, { type, tag })`:
+
+```bash
+node -e "const q=require('${CLAUDE_PLUGIN_ROOT}/scripts/lib/design-context-query.cjs'); \
+  const g=q.load('.design/context-graph.json'); \
+  console.log(JSON.stringify(q.nodes(g, { type: process.env.NODE_TYPE || undefined, tag: process.env.TAG || undefined })));"
+```
+
+Render one row per node. Keep it scannable:
+
+```
+ID                  TYPE        COMPLEXITY  NAME
+token:color/brand   token       simple      Brand primary
+component:Button    component   moderate    Button
+```
+
+If no nodes match, say so plainly and suggest a broader filter.
+
+## edges
+
+List edges. `--type <t>` filters by edge type (uses-token, composes, extends, transitions-to, depends-on, mirrors, conflicts-with, referenced-by, tested-by, documented-by, consumes-context, provides-context). Call `edges(graph, { type })`:
+
+```bash
+node -e "const q=require('${CLAUDE_PLUGIN_ROOT}/scripts/lib/design-context-query.cjs'); \
+  const g=q.load('.design/context-graph.json'); \
+  console.log(JSON.stringify(q.edges(g, { type: process.env.EDGE_TYPE || undefined })));"
+```
+
+Render `source -> target (type, weight)` per row. If none match, report it and suggest dropping the filter.
+
+## path
+
+Trace a path between two node ids. Call `path(graph, from, to)`:
+
+```bash
+node -e "const q=require('${CLAUDE_PLUGIN_ROOT}/scripts/lib/design-context-query.cjs'); \
+  const g=q.load('.design/context-graph.json'); \
+  console.log(JSON.stringify(q.path(g, process.env.FROM, process.env.TO)));"
+```
+
+Print the ordered node ids joined by arrows. If no path exists, print `No path from <a> to <b>.` Do not fabricate intermediate nodes.
+
+## consumers-of
+
+List the nodes that consume a given node (the inbound side). Call `consumersOf(graph, id)`:
+
+```bash
+node -e "const q=require('${CLAUDE_PLUGIN_ROOT}/scripts/lib/design-context-query.cjs'); \
+  const g=q.load('.design/context-graph.json'); \
+  console.log(JSON.stringify(q.consumersOf(g, process.env.ID)));"
+```
+
+Render the consumer ids one per row. If the id is unknown, print `No node <id> in the graph.` and suggest `/gdd:context nodes`.
+
+## unreachable
+
+List nodes that no edge reaches (orphans). Call `unreachable(graph)`:
+
+```bash
+node -e "const q=require('${CLAUDE_PLUGIN_ROOT}/scripts/lib/design-context-query.cjs'); \
+  const g=q.load('.design/context-graph.json'); \
+  console.log(JSON.stringify(q.unreachable(g)));"
+```
+
+If the list is empty, print `Every node is reachable.`
+
+## cycles
+
+List dependency cycles. Call `cycles(graph)`:
+
+```bash
+node -e "const q=require('${CLAUDE_PLUGIN_ROOT}/scripts/lib/design-context-query.cjs'); \
+  const g=q.load('.design/context-graph.json'); \
+  console.log(JSON.stringify(q.cycles(g)));"
+```
+
+Print each cycle as its ordered node ids. If there are none, print `No cycles detected.`
+
+## coverage
+
+Report graph coverage. Call `coverage(graph)`:
+
+```bash
+node -e "const q=require('${CLAUDE_PLUGIN_ROOT}/scripts/lib/design-context-query.cjs'); \
+  const g=q.load('.design/context-graph.json'); \
+  console.log(JSON.stringify(q.coverage(g)));"
+```
+
+Surface the returned ratios (for example typed and tagged coverage and node and edge counts) as a short summary.
+
+## Do Not
+
+- Do not edit `.design/context-graph.json` or the fragments under `.design/fragments/`. All writes go through the mapper agents and the synthesizer.
+- Do not invent nodes, edges, or paths. If a query returns nothing, report it plainly.
+- Do not modify `scripts/lib/design-context-query.cjs` or the DesignContext schema.
+
+## CONTEXT COMPLETE

package/dist/claude-code/.claude/skills/migrate-context/SKILL.md

@@ -0,0 +1,123 @@
+---
+name: gdd-migrate-context
+description: "Migrates a pre-Phase-52 project from the flat .design/map/*.md mapper notes to the typed DesignContext graph at .design/context-graph.json. Reads the old map notes, runs the deterministic extract-*.mjs passes to build mapper fragments, merges them with merge-fragments.mjs, validates the result with validate-design-context.cjs, and flags every low-confidence transform for human review before anything is trusted. Read-first and reversible; --dry-run previews the plan without writing. Use when upgrading a project to the DesignContext graph and .design/map/*.md still holds the only structured design notes. Activates for requests involving migrating design maps, building the context graph from old notes, or DesignContext graph migration."
+argument-hint: "[--dry-run]"
+tools: Read, Write, Bash
+user-invocable: true
+---
+
+# /gdd:migrate-context
+
+Closes the pre-graph gap: before Phase 52 a project recorded its structured design knowledge as flat
+`.design/map/*.md` mapper notes (token map, component taxonomy, motion map, a11y map, visual-hierarchy
+map). Phase 52 introduced the typed DesignContext graph at `.design/context-graph.json`. This skill
+carries a project across that boundary: it reads the old map notes, rebuilds the graph deterministically
+from source, validates it, and surfaces anything it could not transform with confidence so a human can
+confirm it. It never trusts a low-confidence guess silently.
+
+Contracts: `../../reference/design-context-schema.md` (the Node / Edge / Fragment / Graph shapes) and
+`../../reference/design-context-tag-vocab.md` (the controlled `tags[]` vocabulary).
+
+## Invocation
+
+| Command | Behavior |
+|---|---|
+| `/gdd:migrate-context` | Run the full migration: read old maps, extract fragments, merge, validate, then report the low-confidence items for review. |
+| `/gdd:migrate-context --dry-run` | Preview only. Print the migration plan and what each step would write, change nothing on disk. |
+
+## Step 1 - Detect the pre-52 state
+
+Read the project layout before touching anything.
+
+1. List `.design/map/*.md`. These are the pre-52 mapper notes (for example `token-map.md`,
+   `component-taxonomy.md`, `motion-map.md`, `a11y-map.md`, `visual-hierarchy.md`). If the directory is
+   absent or empty, there is nothing to migrate: print `No .design/map/*.md notes found; nothing to
+   migrate.` and stop.
+2. Check whether `.design/context-graph.json` already exists. If it does, this is a re-run: keep the
+   existing graph as a backup reference and report that the migration will rebuild it. Do not delete it.
+3. In `--dry-run`, print the file list and the planned outputs (`.design/fragments/<mapper>.json` per
+   mapper, then `.design/context-graph.json`) and stop before Step 2.
+
+## Step 2 - Rebuild fragments deterministically
+
+The graph topology comes from the source tree, not from prose. Run each deterministic extractor over the
+configured source roots (default `src/`; read `source_roots` from `.design/STATE.md` if present). Each
+extractor is pure, dependency-free, and prints a schema-valid Fragment to stdout.
+
+```bash
+mkdir -p .design/fragments
+for mapper in tokens components motion a11y visual-hierarchy; do
+  node "${CLAUDE_PLUGIN_ROOT:-.}/scripts/lib/design-context/extract-${mapper}.mjs" src/ \
+    > ".design/fragments/extract-${mapper}.json"
+done
+```
+
+The extractors fill `id / type / name / subtype / tags / complexity` and every edge they can prove; they
+leave each node `summary` empty for the summary pass. Use the old `.design/map/*.md` notes as the source
+of the human-authored `summary` text and any tags the extractor could not infer: for each node whose name
+matches a map entry, copy that note's one-line description into the node `summary` and add any vocabulary
+tags it implies. This is the only place prose feeds the graph.
+
+## Step 3 - Merge into the canonical graph
+
+Merge the fragments into the single graph. The merger dedupes nodes by `id`, unions tags, prefers a
+non-stub summary over the empty stub, and keeps an edge only when both endpoints resolve to a node in some
+fragment. Dropped dangling edges are reported on stderr as `could-not-fix:` lines.
+
+```bash
+node "${CLAUDE_PLUGIN_ROOT:-.}/scripts/lib/design-context/merge-fragments.mjs" \
+  .design/fragments --out .design/context-graph.json
+```
+
+Capture the stderr `could-not-fix:` lines. Each one is a transform the merge could not complete (a map
+note referenced an entity the extractor never found in source). These are low-confidence items for Step 5,
+not silent drops.
+
+## Step 4 - Validate
+
+Validate the merged graph. The validator checks structure, referential integrity (no dangling edges),
+unique ids, non-stub summaries (soft warning), and the controlled tag vocabulary (soft warning).
+
+```bash
+node "${CLAUDE_PLUGIN_ROOT:-.}/scripts/validate-design-context.cjs" .design/context-graph.json
+```
+
+Exit `0` is clean, `1` is warnings only (stub summaries or unknown tags to tidy later), `2` is a hard
+error (a dangling edge or duplicate id) that must be fixed before the graph is trusted. On exit `2`, do
+not present the graph as migrated: report the errors and stop so a human can resolve them.
+
+## Step 5 - Flag low-confidence transforms
+
+Collect everything that needs human eyes and present it as one review list rather than applying it:
+
+- every `could-not-fix:` line from the merge (an unresolved or dropped edge);
+- every node still carrying an empty `summary` after Step 2 (a map note had no matching entity, or no
+  note existed);
+- every validator `WARN` (stub summary, tag outside the controlled vocabulary).
+
+Print the list with a clear heading and ask the user to confirm or correct each item. Do not auto-resolve
+a low-confidence transform: a wrong edge or a mislabeled node poisons every later graph query.
+
+## Step 6 - Deprecate the old map notes
+
+The flat `.design/map/*.md` notes stay readable for one minor version so nothing breaks mid-upgrade. Add a
+one-line deprecation banner to the top of each migrated map note (do not delete the file):
+
+```text
+> Deprecated: superseded by the DesignContext graph (.design/context-graph.json) as of Phase 52.
+> Read-only for one minor version; regenerate the graph with /gdd:migrate-context.
+```
+
+In `--dry-run`, describe this banner instead of writing it. Announce that the next minor version may remove
+the `.design/map/*.md` notes, and that the graph is now the source of truth.
+
+## Do Not
+
+- Do not trust a low-confidence transform silently. Every `could-not-fix:` line and every stub goes on the
+  Step 5 review list.
+- Do not delete `.design/map/*.md`. Add the deprecation banner and keep the notes for one minor version.
+- Do not hand-edit `.design/context-graph.json` to force validation green. Fix the fragment or the source,
+  then re-merge.
+- Do not edit the extractors, the merger, or the validator. This skill only calls them.
+
+## MIGRATE-CONTEXT COMPLETE

package/dist/claude-code/.claude/skills/progress/SKILL.md

@@ -86,6 +86,10 @@ After the pipeline state (and forensic audit if run), surface a one-line composi
 
 Run `scripts/validate-composition-graph.cjs` for the authoritative cycle and dangling-edge counts when that validator is present; until then report `0` and note the graph is not yet wired. This is a readiness hint, not a gate.
 
+## Step 3.6 - DesignContext graph coverage
+
+When `.design/context-graph.json` exists, surface one line for the typed DesignContext graph using the `coverage` helper in `scripts/lib/design-context-query.cjs` (`node scripts/lib/design-context-query.cjs coverage`), then point at the Atomic-Design map: `DesignContext graph: <pct>% node-type coverage | map: .design/INTEGRATION-MAP.md`. Skip this line entirely when the graph is absent (a pre-Phase-52 project); offer `/gdd:migrate-context` as the next step instead. Readiness hint, not a gate.
+
 ## Step 4 - Update notice (safe-window surface)
 
 After printing the pipeline state, emit the plugin-update banner if one is present. This file is written by `hooks/update-check.sh` subject to the state-machine guard (mid-pipeline stages suppress it) and per-version dismissal.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hegemonart/get-design-done",
-  "version": "1.51.0",
+  "version": "1.52.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",
@@ -59,7 +59,7 @@
     "test:behavior": "node scripts/run-behavior-tests.cjs",
     "typecheck": "tsc --noEmit",
     "codegen:schemas": "node --experimental-strip-types scripts/codegen-schema-types.ts",
-    "lint:md": "npx --yes markdownlint-cli2 \"**/*.md\" \"#node_modules\" \"#.planning\" \"#.claude\" \"#test/fixtures/baselines\"",
+    "lint:md": "npx --yes markdownlint-cli2 \"**/*.md\" \"#**/node_modules\" \"#.planning\" \"#.claude\" \"#test/fixtures/baselines\"",
     "lint:links": "npx --yes lychee --no-progress --accept 200,206,403,429 \"**/*.md\" || true",
     "lint:agentskills": "node scripts/lint-agentskills-spec.cjs",
     "lint:changelog": "node scripts/lint-changelog.cjs",
@@ -74,6 +74,7 @@
     "check:domain-links": "node scripts/check-domain-cross-links.cjs",
     "check:no-duplication": "node scripts/check-no-duplication.cjs",
     "validate:composition-graph": "node scripts/validate-composition-graph.cjs",
+    "validate:design-context": "node scripts/validate-design-context.cjs",
     "validate:skill-frontmatter": "node scripts/validate-skill-frontmatter.cjs",
     "build:skill-graph": "node scripts/generate-skill-graph.cjs",
     "build:skill-graph:check": "node scripts/generate-skill-graph.cjs --check",

package/reference/design-context-schema.md

@@ -0,0 +1,159 @@
+---
+name: design-context-schema
+type: reference
+version: 1.0.0
+phase: 52
+tags: [design-context, knowledge-graph, schema, nodes, edges, mapper, two-phase]
+last_updated: 2026-06-03
+---
+
+# DesignContext Graph Schema
+
+The DesignContext graph is the typed knowledge graph of a design system. It records design
+entities as `nodes` and the relationships between them as `edges`, so an agent can reason about
+a system the way an engineer reads a dependency graph: which token a component consumes, which
+screen a flow transitions to, which pattern an anti-pattern conflicts with. The canonical graph
+lives at `.design/context-graph.json`. It is validated by `scripts/validate-design-context.cjs`
+and queried by `scripts/lib/design-context-query.cjs`.
+
+This file documents the four shapes (Node, Edge, Fragment, Graph), the ten node types, the twelve
+edge types, and the two-phase mapper pattern that builds the graph. The controlled `tags[]`
+vocabulary lives in `./design-context-tag-vocab.md`; the JSON Schema lives at
+`./schemas/design-context.schema.json`.
+
+## Shapes
+
+Four shapes make up the contract. A Graph is the assembled whole; a Fragment is one mapper's
+contribution before merge; Nodes and Edges are the parts.
+
+### Node
+
+```
+{ id, type, name, summary, tags[], complexity }
+```
+
+- `id`: stable unique string; edges reference it. A duplicate id is a hard error.
+- `type`: one of the ten node types below.
+- `name`: human-readable name of the entity.
+- `summary`: a one-line description of what the entity is and does. The deterministic pass may
+  leave this empty; the summary pass fills it. An empty summary, or one identical to `name`, is a
+  soft warning (a stub).
+- `tags[]`: strings from the controlled vocabulary. An unknown tag is a soft warning.
+- `complexity`: one of `simple`, `moderate`, `complex`.
+- `subtype` *(optional)*: a finer class. For a `token` node one of
+  `color / spacing / typography / radius / shadow`; for a `layer` node one of
+  `Atomic / Molecular / Organism / Template`.
+
+### Edge
+
+```
+{ source, target, type, direction, weight }
+```
+
+- `source`, `target`: node ids. Both must resolve to an existing node; a dangling endpoint is a
+  hard error.
+- `type`: one of the twelve edge types below.
+- `direction`: one of `forward`, `backward`, `bidirectional`. A forward edge reads
+  source-to-target; a backward edge reads target-to-source; a bidirectional edge reads both ways.
+  Traversal in the query library honors direction.
+- `weight`: a number in the inclusive range 0 to 1. It expresses relationship strength, not
+  distance, so a stronger tie has a higher weight.
+
+### Fragment
+
+```
+{ schema_version, mapper, generated_at, nodes[], edges[] }
+```
+
+A Fragment is the output of a single mapper (the Figma mapper, the codebase mapper, the docs
+mapper). It carries a `mapper` field naming its origin and is merged into the Graph by union on
+node `id`. Fragments let mappers run independently and write narrow outputs that later combine.
+
+### Graph
+
+```
+{ schema_version, generated_at, nodes[], edges[] }
+```
+
+The Graph is the merged, canonical document at `.design/context-graph.json`. `schema_version` is
+required; `generated_at` is an optional ISO-8601 timestamp recording when the graph was assembled.
+
+## Node types
+
+Ten node types cover the entities a design system holds. Each entry states what the type is and
+when a mapper emits it.
+
+- **token**: a design-token leaf such as a color, a spacing step, or a type ramp value. Emitted
+  for every resolvable token; carries a `subtype` naming the token family.
+- **component**: a reusable UI unit (a button, a card, an input). Emitted once per component
+  regardless of how many variants it has.
+- **variant**: a named configuration of a component (a button's `primary` or `ghost`). Emitted
+  when a component exposes distinct variants worth addressing on their own.
+- **state**: an interaction or lifecycle state of a component (`hover`, `disabled`, `loading`).
+  Emitted when state changes carry their own styling or behavior.
+- **motion-fragment**: a reusable motion unit (an enter transition, an easing curve, a loop).
+  Emitted when motion is named and reused rather than ad hoc.
+- **a11y-pattern**: an accessibility pattern (a focus-trap, a skip-link, an aria-live region).
+  Emitted when a component participates in a named accessibility contract.
+- **screen**: a full page or view in a product flow. Emitted once per distinct screen.
+- **layer**: a composition layer in the atomic taxonomy. Carries a `subtype` of `Atomic`,
+  `Molecular`, `Organism`, or `Template`. Emitted to record where an entity sits in the hierarchy.
+- **pattern**: a recurring solution that spans components (a master-detail layout, a wizard).
+  Emitted when a shape repeats across the system and earns a name.
+- **anti-pattern**: a recurring shape the system wants to retire (a one-off color, a duplicated
+  control). Emitted so the graph can point at debt and the edges can mark conflicts.
+
+## Edge types
+
+Twelve edge types cover how entities relate. Each entry states the relationship and when it
+applies.
+
+- **uses-token**: a component or variant consumes a token. Source is the consumer, target is the
+  token.
+- **composes**: a larger entity is built from a smaller one (a card composes a button). Source is
+  the whole, target is the part.
+- **extends**: a variant or component specializes another (a `primary` button extends the base
+  button). Source is the specialization.
+- **transitions-to**: a screen or state moves to another in a flow. Used for navigation graphs
+  and state machines.
+- **depends-on**: a generic dependency where the more specific edge types do not fit. Source
+  needs target to function.
+- **mirrors**: two entities are intentional reflections of each other (a light-mode and dark-mode
+  pair). Usually bidirectional.
+- **conflicts-with**: two entities collide or duplicate intent (an anti-pattern conflicts with a
+  sanctioned pattern). Used to surface debt.
+- **referenced-by**: an inbound citation: the target points at the source from outside the graph
+  core (a doc or a ticket references this entity). Often backward.
+- **tested-by**: an entity is covered by a test. Source is the entity, target is the test node.
+- **documented-by**: an entity is described by a doc. Source is the entity, target is the doc.
+- **consumes-context**: an entity reads shared context provided elsewhere (a component reads a
+  theme provider). Source is the reader.
+- **provides-context**: an entity supplies shared context to others (a theme provider supplies a
+  palette). Source is the provider; the matching reader uses `consumes-context`.
+
+## The two-phase mapper pattern
+
+A mapper builds the graph in two passes so the cheap, deterministic work is separate from the
+costly, judgment-bearing work.
+
+1. **Deterministic extract.** A pure pass walks the source (a Figma file, a component tree, a docs
+   set) and emits node and edge skeletons: ids, types, names, tags, complexity, and every edge it
+   can prove. Summaries are left empty. This pass is reproducible and dependency-free, so a graph
+   can be rebuilt the same way every run.
+2. **LLM summary.** A second pass fills each node `summary` with a one-line description an agent
+   can read. Only the `summary` field changes; ids, types, and edges stay fixed from the extract
+   pass. This keeps the expensive pass narrow and lets the validator flag any node the summary
+   pass missed as a stub.
+
+Splitting the work this way means the structure of the graph is deterministic and auditable, while
+the prose layer can be regenerated on its own without disturbing the topology. A mapper writes a
+Fragment; the assembler merges fragments into the canonical Graph.
+
+## Cross-references
+
+- Controlled `tags[]` vocabulary the validator enforces: see `./design-context-tag-vocab.md`.
+- The JSON Schema (Draft-07) for the Graph: see `./schemas/design-context.schema.json`.
+- The validator (structural, referential, completeness, tag checks):
+  `scripts/validate-design-context.cjs`.
+- The query library (filters, BFS path, consumers, orphans, cycles, coverage):
+  `scripts/lib/design-context-query.cjs`.

package/reference/design-context-tag-vocab.md

@@ -0,0 +1,82 @@
+---
+name: design-context-tag-vocab
+type: reference
+version: 1.0.0
+phase: 52
+tags: [design-context, knowledge-graph, tags, vocabulary, controlled-vocab]
+last_updated: 2026-06-03
+---
+
+# DesignContext Tag Vocabulary
+
+This is the controlled vocabulary the DesignContext validator checks node `tags[]` against. A tag
+outside this list is a soft warning, not a hard error, so a mapper can ship a new tag and the
+graph still loads; the warning prompts a reviewer to either fix the tag or add it here.
+
+## Source of truth
+
+The canonical list lives in code, in the `TAG_VOCAB` set inside
+`scripts/validate-design-context.cjs`. That set is what the validator enforces. This document
+mirrors it for human readers and groups the tags by concern. When the set changes, update this
+file by hand to match. If the two ever disagree, the code wins.
+
+## Why a controlled vocabulary
+
+Free-form tags drift: one node says `darkmode`, another `dark-mode`, a third `dark`. A query for
+`dark-mode` then misses two of three. A controlled list keeps tags queryable and keeps the
+`nodes(graph, { tag })` filter reliable. The list is deliberately broad rather than minimal, so
+most real tags land inside it; the soft-warning behavior absorbs the rest without blocking a build.
+
+## Tags by concern
+
+The groupings below are for reading only. The validator treats the vocabulary as one flat set, so
+a tag is valid regardless of which group it sits in.
+
+- **Color**: `color`, `palette`, `theme`, `dark-mode`, `light-mode`, `contrast`, `gradient`,
+  `surface`, `brand`.
+- **Spacing and sizing**: `spacing`, `sizing`, `density`, `gap`, `inset`, `stack`.
+- **Typography**: `typography`, `font`, `type-scale`, `heading`, `body-text`, `label`, `numeric`.
+- **Radius, shape, elevation**: `radius`, `shape`, `border`, `shadow`, `elevation`, `depth`.
+- **Motion**: `motion`, `transition`, `animation`, `easing`, `duration`, `enter`, `exit`, `loop`,
+  `gesture`.
+- **Accessibility**: `a11y`, `aria`, `focus`, `keyboard`, `screen-reader`, `reduced-motion`,
+  `contrast-safe`, `touch-target`.
+- **Layout and structure**: `layout`, `grid`, `flex`, `responsive`, `breakpoint`, `container`,
+  `overflow`, `position`, `z-index`.
+- **Interaction state**: `state`, `hover`, `active`, `disabled`, `loading`, `error`, `success`,
+  `selected`, `pressed`, `dragging`.
+- **Component taxonomy**: `atom`, `molecule`, `organism`, `template`, `primitive`, `composite`,
+  `layout-primitive`.
+- **Forms and inputs**: `form`, `input`, `control`, `validation`, `field`.
+- **Navigation and structure**: `navigation`, `overlay`, `modal`, `menu`, `tabs`, `data-display`,
+  `feedback`, `media`.
+- **Semantic role**: `interactive`, `static`, `decorative`, `destructive`, `utility`.
+- **Quality flags**: `deprecated`, `experimental`, `stable`, `anti-pattern`, `review-needed`.
+
+## Machine-readable list
+
+The fenced block below is the same vocabulary as a flat list for any tool that wants to read the
+doc instead of the code. Tokens are separated by commas or newlines (split on `/[\s,]+/`), so the
+grouping into lines is cosmetic. It must stay equal to the `TAG_VOCAB` set in
+`scripts/validate-design-context.cjs`.
+
+```text
+color, palette, theme, dark-mode, light-mode, contrast, gradient, surface, brand,
+spacing, sizing, density, gap, inset, stack,
+typography, font, type-scale, heading, body-text, label, numeric,
+radius, shape, border, shadow, elevation, depth,
+motion, transition, animation, easing, duration, enter, exit, loop, gesture,
+a11y, aria, focus, keyboard, screen-reader, reduced-motion, contrast-safe, touch-target,
+layout, grid, flex, responsive, breakpoint, container, overflow, position, z-index,
+state, hover, active, disabled, loading, error, success, selected, pressed, dragging,
+atom, molecule, organism, template, primitive, composite, layout-primitive,
+form, input, control, validation, field,
+navigation, overlay, modal, menu, tabs, data-display, feedback, media,
+interactive, static, decorative, destructive, utility,
+deprecated, experimental, stable, anti-pattern, review-needed
+```
+
+## Cross-references
+
+- The node and edge type catalogue and the four shapes: see `./design-context-schema.md`.
+- The validator that enforces this vocabulary: `scripts/validate-design-context.cjs`.

package/reference/registry.json

@@ -1156,6 +1156,20 @@
       "type": "meta-rules",
       "phase": 51,
       "description": "Phase 51 instinct unit format: YAML frontmatter (id, trigger, confidence 0.3-0.9, domain, scope, project_id, source, cycles_seen, first/last_seen) + body; promotion gate K=2/M=2; Beta(2,8) prior; TTL decay. Stored via scripts/lib/instinct-store.cjs."
+    },
+    {
+      "name": "design-context-schema",
+      "path": "reference/design-context-schema.md",
+      "type": "schema",
+      "phase": 52,
+      "description": "Phase 52 (KEYSTONE) typed DesignContext graph: 10 node types + 12 edge types, Node/Edge/Fragment/Graph shapes, two-phase mapper pattern. Schema at reference/schemas/design-context.schema.json."
+    },
+    {
+      "name": "design-context-tag-vocab",
+      "path": "reference/design-context-tag-vocab.md",
+      "type": "meta-rules",
+      "phase": 52,
+      "description": "Phase 52 controlled tag vocabulary for DesignContext nodes; validate-design-context.cjs soft-warns on unknown tags."
     }
   ]
 }