@hegemonart/get-design-done 1.53.0 → 1.55.0

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 }
+  ]
+}
+```

package/reference/motion/motion-one.md

@@ -0,0 +1,44 @@
+---
+name: motion-one
+kind: motion
+composes_into: [motion-mapper]
+phase: 54
+---
+<!-- Vendor docs: https://motion.dev/docs/animate. -->
+
+# Motion One
+
+## Conventions
+
+- Tiny WAAPI core: `animate(element, keyframes, options)` where options carry `duration`, `ease` (named, cubic-bezier, or fn) OR `type: "spring"`.
+- A spring is compiled to a `linear()` easing from stiffness/damping/mass/bounce; `spring()` and `glide()` generators exist (glide carries velocity).
+- `inView()` runs on viewport entry, `scroll()` is scroll-linked, `stagger()` sequences a set.
+- Imperative with no JSX; the React wrapper IS Framer Motion, so JSX absence is the tell.
+
+## File patterns
+
+- `import { animate, inView, scroll, stagger, spring } from "motion"` (or `"motion/mini"`).
+- Markers: `animate(`, `inView(`, `scroll(`, plus a small-footprint import list.
+- Identify via: those imports with NO `motion.*` JSX (which would mean Framer Motion).
+
+## 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: `type: "spring"` or a `spring()` / `glide()` generator is physics; a named or cubic-bezier `ease` is a tween.
+- Gesture vs tween: `inView()` is an entrance, `scroll()` is scroll-linked, a direct `animate` from an event handler is a gesture fragment.
+
+## Example output
+
+```json
+{
+  "schema_version": "52.0",
+  "nodes": [
+    { "id": "mf.section.inview", "type": "motion-fragment", "name": "Section inView", "summary": "Standard tween fade on viewport entry.", "complexity": "simple", "tags": ["motion", "transition", "enter", "duration"] },
+    { "id": "mf.banner.scroll", "type": "motion-fragment", "name": "Banner scroll-link", "summary": "Scroll-linked parallax via scroll().", "complexity": "moderate", "tags": ["motion", "animation", "gesture"] }
+  ],
+  "edges": [
+    { "source": "mf.section.inview", "target": "mf.banner.scroll", "type": "composes", "direction": "forward", "weight": 0.4 }
+  ]
+}
+```

package/reference/motion/react-spring.md

@@ -0,0 +1,44 @@
+---
+name: react-spring
+kind: motion
+composes_into: [motion-mapper]
+phase: 54
+---
+<!-- Vendor docs: https://react-spring.dev/docs/components/use-spring. -->
+
+# React Spring
+
+## Conventions
+
+- Physics-first hooks: `useSpring` (one style), `useTransition` (mount/unmount or list, via from/enter/leave), plus `useTrail` / `useChain` / `useSprings`.
+- Config presets tune the spring: default {tension:170,friction:26}, gentle {120,14}, wobbly {180,12}, stiff {210,20}, slow {280,60}, molasses {280,120}.
+- Hooks return `animated.*` styles applied to `animated.div` (and friends).
+- Gestures come from the companion `@use-gesture/react`, which drives the spring from pointer input.
+
+## File patterns
+
+- `import { useSpring, useTransition, animated, config } from "@react-spring/web"` (or `react-spring`).
+- Markers: `useSpring({ from, to, config })`, `animated.div`, `config.gentle`.
+- Identify via: a `useSpring` / `useTransition` call plus an `animated.*` element.
+
+## Gotchas
+
+- Unit trap: there is NO fixed duration; record the config preset name plus its tension/friction, since the mapper must normalize before bucketing.
+- Map preset to perceived speed (taxonomy): stiff and default read as quick, gentle as standard, slow and molasses as narrative.
+- Easing class: this is almost always a spring (physics), so capture the preset, not an ease curve.
+- Gesture vs tween: `useTransition` enter/leave are transition fragments; a `useSpring` driven by hover or `@use-gesture` is a gesture fragment.
+
+## Example output
+
+```json
+{
+  "schema_version": "52.0",
+  "nodes": [
+    { "id": "mf.modal.transition", "type": "motion-fragment", "name": "Modal useTransition", "summary": "Gentle spring enter and leave, standard speed.", "complexity": "moderate", "tags": ["motion", "transition", "enter", "exit"] },
+    { "id": "mf.tile.drag", "type": "motion-fragment", "name": "Tile drag spring", "summary": "Stiff spring driven by pointer drag.", "complexity": "moderate", "tags": ["motion", "gesture", "dragging"] }
+  ],
+  "edges": [
+    { "source": "mf.modal.transition", "target": "mf.tile.drag", "type": "composes", "direction": "forward", "weight": 0.4 }
+  ]
+}
+```

package/reference/motion.md

@@ -164,3 +164,4 @@ Always respect this. It is not optional.
 - CSS layout transitions: `reference/spatial.md`
 - Typography: `reference/typography.md`
 - UX writing: `reference/ux-writing.md`
+- Per-library motion conventions (Phase 54 composable addendums): `reference/motion/` (framer-motion, gsap, motion-one, react-spring). These reuse the duration classes above and are composed into the motion mapper at spawn time by `scripts/lib/mapper-spawn.cjs` when `detectStack` matches the project; each is a `type:"stack-addendum"` entry in `reference/registry.json`.

package/reference/registry.json

@@ -1,7 +1,7 @@
 {
   "$schema": "./schemas/registry.schema.json",
   "version": 1,
-  "generated_at": "2026-05-20T09:53:00.000Z",
+  "generated_at": "2026-06-03T00:00:00.000Z",
   "entries": [
     {
       "name": "codex-tools",
@@ -1170,6 +1170,168 @@
       "type": "meta-rules",
       "phase": 52,
       "description": "Phase 52 controlled tag vocabulary for DesignContext nodes; validate-design-context.cjs soft-warns on unknown tags."
+    },
+    {
+      "name": "addendum-system-tailwind",
+      "path": "reference/systems/tailwind.md",
+      "type": "stack-addendum",
+      "phase": 54,
+      "kind": "system",
+      "composes_into": ["token-mapper", "component-taxonomy-mapper"],
+      "description": "Phase 54 stack addendum (design-system) — Tailwind CSS. v4 @theme CSS-custom-property token model vs v3 tailwind.config theme, utility-cluster-as-variant reading, arbitrary-value anti-patterns. Composed into the token + component-taxonomy mappers when detectStack reports ds=tailwind."
+    },
+    {
+      "name": "addendum-system-shadcn",
+      "path": "reference/systems/shadcn.md",
+      "type": "stack-addendum",
+      "phase": 54,
+      "kind": "system",
+      "composes_into": ["token-mapper", "component-taxonomy-mapper"],
+      "description": "Phase 54 stack addendum (design-system) — shadcn/ui. components.json + cn() helper signature, copy-in (not dependency) component ownership, CSS-variable theming over the Radix primitive layer. Composed into the token + component-taxonomy mappers when detectStack reports ds=shadcn."
+    },
+    {
+      "name": "addendum-system-radix-themes",
+      "path": "reference/systems/radix-themes.md",
+      "type": "stack-addendum",
+      "phase": 54,
+      "kind": "system",
+      "composes_into": ["token-mapper", "component-taxonomy-mapper"],
+      "description": "Phase 54 stack addendum (design-system) — Radix Themes. The accent/gray scale token system, the 12-step color scales, Theme-prop driven appearance, radius/scaling config. Composed into the token + component-taxonomy mappers when detectStack reports ds=radix-themes."
+    },
+    {
+      "name": "addendum-system-mui",
+      "path": "reference/systems/mui.md",
+      "type": "stack-addendum",
+      "phase": 54,
+      "kind": "system",
+      "composes_into": ["token-mapper", "component-taxonomy-mapper"],
+      "description": "Phase 54 stack addendum (design-system) — MUI (Material UI). createTheme palette/typography/spacing tokens, the sx prop vs styled() usage, theme.vars CSS-variable mode, slot-based component anatomy. Composed into the token + component-taxonomy mappers when detectStack reports ds=mui."
+    },
+    {
+      "name": "addendum-system-chakra",
+      "path": "reference/systems/chakra.md",
+      "type": "stack-addendum",
+      "phase": 54,
+      "kind": "system",
+      "composes_into": ["token-mapper", "component-taxonomy-mapper"],
+      "description": "Phase 54 stack addendum (design-system) — Chakra UI. The theme token scales (colors/space/fontSizes/radii), style-prop usage as token references, semantic tokens, recipe/variant anatomy. Composed into the token + component-taxonomy mappers when detectStack reports ds=chakra."
+    },
+    {
+      "name": "addendum-system-vanilla-extract",
+      "path": "reference/systems/vanilla-extract.md",
+      "type": "stack-addendum",
+      "phase": 54,
+      "kind": "system",
+      "composes_into": ["token-mapper", "component-taxonomy-mapper"],
+      "description": "Phase 54 stack addendum (design-system) — vanilla-extract. The *.css.ts compile-time stylesheet model, createTheme / themeContract token contracts, vars as the token source, recipe() variants. Composed into the token + component-taxonomy mappers when detectStack reports ds=vanilla-extract."
+    },
+    {
+      "name": "addendum-system-styled-components",
+      "path": "reference/systems/styled-components.md",
+      "type": "stack-addendum",
+      "phase": 54,
+      "kind": "system",
+      "composes_into": ["token-mapper", "component-taxonomy-mapper"],
+      "description": "Phase 54 stack addendum (design-system) — styled-components. The ThemeProvider theme object as the token tree, props-driven dynamic styling, the styled() component boundary, css helper composition. Composed into the token + component-taxonomy mappers when detectStack reports ds=styled-components."
+    },
+    {
+      "name": "addendum-system-css-modules",
+      "path": "reference/systems/css-modules.md",
+      "type": "stack-addendum",
+      "phase": 54,
+      "kind": "system",
+      "composes_into": ["token-mapper", "component-taxonomy-mapper"],
+      "description": "Phase 54 stack addendum (design-system) — CSS Modules. The *.module.css locally-scoped class model, :root / var() custom-property tokens, composes for variant reuse, no runtime theme object. Composed into the token + component-taxonomy mappers when detectStack reports ds=css-modules."
+    },
+    {
+      "name": "addendum-framework-nextjs",
+      "path": "reference/frameworks/nextjs.md",
+      "type": "stack-addendum",
+      "phase": 54,
+      "kind": "framework",
+      "composes_into": ["component-taxonomy-mapper", "visual-hierarchy-mapper"],
+      "description": "Phase 54 stack addendum (framework) — Next.js. App Router vs Pages Router layout/route structure, server vs client component split, layout.tsx hierarchy as a screen graph, metadata/loading/error conventions. Composed into the component-taxonomy + visual-hierarchy mappers when detectStack reports framework=nextjs."
+    },
+    {
+      "name": "addendum-framework-remix",
+      "path": "reference/frameworks/remix.md",
+      "type": "stack-addendum",
+      "phase": 54,
+      "kind": "framework",
+      "composes_into": ["component-taxonomy-mapper", "visual-hierarchy-mapper"],
+      "description": "Phase 54 stack addendum (framework) — Remix (v2 / React Router v7 framework mode). Nested-route file conventions as a layout tree, loader/action data boundaries, Outlet composition, the route-as-screen mapping. Composed into the component-taxonomy + visual-hierarchy mappers when detectStack reports framework=remix."
+    },
+    {
+      "name": "addendum-framework-vite-react",
+      "path": "reference/frameworks/vite-react.md",
+      "type": "stack-addendum",
+      "phase": 54,
+      "kind": "framework",
+      "composes_into": ["component-taxonomy-mapper", "visual-hierarchy-mapper"],
+      "description": "Phase 54 stack addendum (framework) — Vite + React SPA. The client-only render tree, react-router route config as the screen graph, entry-point main.tsx, no server-component split. Composed into the component-taxonomy + visual-hierarchy mappers when detectStack reports framework=vite-react."
+    },
+    {
+      "name": "addendum-framework-astro",
+      "path": "reference/frameworks/astro.md",
+      "type": "stack-addendum",
+      "phase": 54,
+      "kind": "framework",
+      "composes_into": ["component-taxonomy-mapper", "visual-hierarchy-mapper"],
+      "description": "Phase 54 stack addendum (framework) — Astro. The .astro component model, island architecture (client:* directives) as the interactivity boundary, file-based pages routing, content collections. Composed into the component-taxonomy + visual-hierarchy mappers when detectStack reports framework=astro."
+    },
+    {
+      "name": "addendum-framework-sveltekit",
+      "path": "reference/frameworks/sveltekit.md",
+      "type": "stack-addendum",
+      "phase": 54,
+      "kind": "framework",
+      "composes_into": ["component-taxonomy-mapper", "visual-hierarchy-mapper"],
+      "description": "Phase 54 stack addendum (framework) — SvelteKit. The +page / +layout route file conventions as a layout tree, load functions, slot composition, the .svelte component anatomy. Composed into the component-taxonomy + visual-hierarchy mappers when detectStack reports framework=sveltekit."
+    },
+    {
+      "name": "addendum-framework-storybook",
+      "path": "reference/frameworks/storybook.md",
+      "type": "stack-addendum",
+      "phase": 54,
+      "kind": "framework",
+      "composes_into": ["component-taxonomy-mapper", "visual-hierarchy-mapper"],
+      "description": "Phase 54 stack addendum (framework) — Storybook. The *.stories.* files as the canonical component + variant catalogue, args/argTypes as the variant matrix, CSF story structure, the component-in-isolation taxonomy signal. Composed into the component-taxonomy + visual-hierarchy mappers when detectStack reports framework=storybook."
+    },
+    {
+      "name": "addendum-motion-framer-motion",
+      "path": "reference/motion/framer-motion.md",
+      "type": "stack-addendum",
+      "phase": 54,
+      "kind": "motion",
+      "composes_into": ["motion-mapper"],
+      "description": "Phase 54 stack addendum (motion) — Framer Motion / motion. Seconds-unit duration trap, the spring-vs-tween default, variants/AnimatePresence/gesture props, mapping onto the instant/quick/standard/slow/narrative duration classes. Composed into the motion mapper when detectStack reports motion_libs includes framer-motion."
+    },
+    {
+      "name": "addendum-motion-gsap",
+      "path": "reference/motion/gsap.md",
+      "type": "stack-addendum",
+      "phase": 54,
+      "kind": "motion",
+      "composes_into": ["motion-mapper"],
+      "description": "Phase 54 stack addendum (motion) — GSAP. Seconds-unit duration, the timeline orchestration model, ease string vocabulary, ScrollTrigger gestures, mapping tweens onto the instant/quick/standard/slow/narrative duration classes. Composed into the motion mapper when detectStack reports motion_libs includes gsap."
+    },
+    {
+      "name": "addendum-motion-motion-one",
+      "path": "reference/motion/motion-one.md",
+      "type": "stack-addendum",
+      "phase": 54,
+      "kind": "motion",
+      "composes_into": ["motion-mapper"],
+      "description": "Phase 54 stack addendum (motion) — Motion One. The Web Animations API foundation, seconds-unit duration, the animate() signature, spring/glide generators, mapping onto the instant/quick/standard/slow/narrative duration classes. Composed into the motion mapper when detectStack reports motion_libs includes motion-one."
+    },
+    {
+      "name": "addendum-motion-react-spring",
+      "path": "reference/motion/react-spring.md",
+      "type": "stack-addendum",
+      "phase": 54,
+      "kind": "motion",
+      "composes_into": ["motion-mapper"],
+      "description": "Phase 54 stack addendum (motion) — react-spring. The physics-first (no-duration) model: tension/friction/mass instead of a duration, useSpring/useTransition hooks, the gesture-driven imperative api, reconciling physics springs with the instant/quick/standard/slow/narrative duration classes. Composed into the motion mapper when detectStack reports motion_libs includes react-spring."
     }
   ]
 }

package/reference/registry.schema.json

@@ -64,9 +64,26 @@
               "layout",
               "performance",
               "component-spec",
-              "domain-index"
+              "domain-index",
+              "stack-addendum"
             ]
           },
+          "kind": {
+            "type": "string",
+            "enum": [
+              "system",
+              "framework",
+              "motion"
+            ],
+            "description": "Phase 54 stack-addendum category. Drives mapper-spawn.cjs composition (1 system + 1 framework + 1 motion cap). Present only on type:stack-addendum entries; classifyEntry also infers it from the path dir, so it is an explicit reinforcement, not strictly required."
+          },
+          "composes_into": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "description": "Phase 54 stack-addendum composition targets — the explore mapper names (e.g. token-mapper, component-taxonomy-mapper, motion-mapper) this addendum is appended into pre-spawn. Read by scripts/lib/mapper-spawn.cjs composeAddendums(). Present only on type:stack-addendum entries."
+          },
           "tier": {
             "enum": [
               "L0",

package/reference/skill-graph.md

@@ -9,7 +9,7 @@ is a `composes_with` edge (the source calls the target as sub-orchestration); a
 a `next_skills` edge (a pipeline hint for what runs next). Stage grouping is best-effort and
 inferred from the skill name; skills with no stage keyword fall under Utility.
 
-Skills: 91. Composition edges: 0 composes_with, 6 next_skills.
+Skills: 92. Composition edges: 0 composes_with, 6 next_skills.
 
 ```mermaid
 flowchart TD
@@ -85,6 +85,7 @@ flowchart TD
     n_list_pins["list-pins"]
     n_locale["locale"]
     n_migrate_context["migrate-context"]
+    n_new_addendum["new-addendum"]
     n_new_skill["new-skill"]
     n_next["next"]
     n_note["note"]

package/reference/systems/chakra.md

@@ -0,0 +1,44 @@
+---
+name: chakra
+kind: system
+composes_into: [token-mapper, component-taxonomy-mapper]
+phase: 54
+---
+<!-- Vendor docs: https://chakra-ui.com/docs/theming/customization/colors. -->
+
+# Chakra UI
+
+## Conventions
+
+- v3 builds a system via `createSystem(defineConfig({ theme: { tokens, semanticTokens, recipes, slotRecipes } }))` (Panda-inspired).
+- Two tiers: raw `tokens` are `{value}`-wrapped (for example `colors.brand.500.value`); `semanticTokens` are condition-aware via `_light` and `_dark` and form the real consistency layer.
+- Style props (bg, px, color, rounded) bind to tokens. v2 uses extendTheme plus useColorModeValue(light, dark).
+
+## File patterns
+
+- `theme.ts` or `system.ts` with createSystem.
+- `<ChakraProvider value={system}>` at the root.
+- Identify via: @chakra-ui/react in deps plus createSystem.
+
+## Gotchas
+
+- v3 tokens are `{value}`-wrapped; the leaf is `.value`.
+- Prefer semanticTokens as the token nodes (they encode light and dark) and treat raw tokens as the backing palette.
+- recipes and slotRecipes are variants; style props are usage, not token nodes.
+
+## Example output
+
+```json
+{
+  "schema_version": "52.0",
+  "nodes": [
+    { "id": "tok.color.bg", "type": "token", "subtype": "color", "name": "semanticTokens.colors.bg", "summary": "Condition-aware surface color across light and dark.", "complexity": "simple", "tags": ["color", "surface", "dark-mode", "light-mode"] },
+    { "id": "tok.color.brand-500", "type": "token", "subtype": "color", "name": "colors.brand.500", "summary": "Raw brand palette step backing the semantic tokens.", "complexity": "simple", "tags": ["color", "brand", "palette"] },
+    { "id": "cmp.button", "type": "component", "name": "Button", "summary": "Button recipe bound to semantic surface tokens.", "complexity": "moderate", "tags": ["interactive", "atom"] }
+  ],
+  "edges": [
+    { "source": "tok.color.bg", "target": "tok.color.brand-500", "type": "uses-token", "direction": "forward", "weight": 0.6 },
+    { "source": "cmp.button", "target": "tok.color.bg", "type": "uses-token", "direction": "forward", "weight": 0.8 }
+  ]
+}
+```

package/reference/systems/css-modules.md

@@ -0,0 +1,44 @@
+---
+name: css-modules
+kind: system
+composes_into: [token-mapper, component-taxonomy-mapper]
+phase: 54
+---
+<!-- Vendor docs: https://github.com/css-modules/css-modules. -->
+
+# CSS Modules
+
+## Conventions
+
+- `*.module.css` files scope class names locally (hashed) and import as a JS object (`styles.button`).
+- No JS theme: tokens are CSS custom properties on `:root` in a shared global stylesheet, or `@value` build-time constants.
+- `composes: base from './x.module.css'` merges classes (the composition signal). `.button--primary` is a variant; `&:hover` and `.button:disabled` are states.
+
+## File patterns
+
+- `Component.module.css` next to `Component.tsx`.
+- `tokens.css` or `theme.css` with `:root`; `composes:` and `@value` declarations.
+- Identify via: a `*.module.css` import plus a `:root` token sheet.
+
+## Gotchas
+
+- The `:root` custom properties ARE the tokens; infer subtype from the name and value.
+- `composes:` is a cross-file edge; model it as extends or composes.
+- Read the source `.module.css`, not the hashed output; `@value` constants are tokens too.
+
+## Example output
+
+```json
+{
+  "schema_version": "52.0",
+  "nodes": [
+    { "id": "tok.color.primary", "type": "token", "subtype": "color", "name": "--color-primary", "summary": "Primary brand color custom property on :root.", "complexity": "simple", "tags": ["color", "brand", "theme"] },
+    { "id": "cmp.button-base", "type": "component", "name": "button base", "summary": "Base button class others compose from.", "complexity": "simple", "tags": ["primitive", "interactive"] },
+    { "id": "var.button-primary", "type": "variant", "name": "button--primary", "summary": "Primary variant composing the base class.", "complexity": "simple", "tags": ["brand", "state"] }
+  ],
+  "edges": [
+    { "source": "var.button-primary", "target": "cmp.button-base", "type": "composes", "direction": "forward", "weight": 0.8 },
+    { "source": "var.button-primary", "target": "tok.color.primary", "type": "uses-token", "direction": "forward", "weight": 0.9 }
+  ]
+}
+```

package/reference/systems/mui.md

@@ -0,0 +1,44 @@
+---
+name: mui
+kind: system
+composes_into: [token-mapper, component-taxonomy-mapper]
+phase: 54
+---
+<!-- Vendor docs: https://mui.com/material-ui/customization/theming/. -->
+
+# MUI (Material UI)
+
+## Conventions
+
+- Tokens live in a JS theme via `createTheme({ palette, typography, spacing, breakpoints, shape, shadows, components })` applied through `<ThemeProvider>`.
+- palette.primary holds main, light, dark, contrastText. spacing is a multiplier function: `theme.spacing(2)` returns 16px. shadows is a 25-entry elevation array. typography variants run h1 through caption.
+- Styling uses sx (one-off), styled() (reusable), and theme.components (per-component variants).
+
+## File patterns
+
+- `theme.ts` with createTheme and ThemeProvider.
+- sx props inline; styled() factories co-located with components.
+- CssVarsProvider or extendTheme emit `--mui-*` vars.
+- Identify via: @mui/material in deps plus createTheme.
+
+## Gotchas
+
+- spacing is a multiplier, not a px value; resolve before recording a spacing token.
+- Customization splits across sx, styled(), and theme.components; gather all three.
+- A shadow is an array index, and `@mui/joy` is not `@mui/material`.
+
+## Example output
+
+```json
+{
+  "schema_version": "52.0",
+  "nodes": [
+    { "id": "tok.color.primary-main", "type": "token", "subtype": "color", "name": "palette.primary.main", "summary": "Primary brand color from the MUI palette.", "complexity": "simple", "tags": ["color", "brand", "theme"] },
+    { "id": "tok.shadow.elev-4", "type": "token", "subtype": "shadow", "name": "shadows[4]", "summary": "Elevation level 4 box-shadow.", "complexity": "simple", "tags": ["shadow", "elevation", "depth"] },
+    { "id": "cmp.button", "type": "component", "name": "Button", "summary": "Contained button bound to primary palette.", "complexity": "moderate", "tags": ["interactive", "atom"] }
+  ],
+  "edges": [
+    { "source": "cmp.button", "target": "tok.color.primary-main", "type": "uses-token", "direction": "forward", "weight": 0.9 }
+  ]
+}
+```

package/reference/systems/radix-themes.md

@@ -0,0 +1,43 @@
+---
+name: radix-themes
+kind: system
+composes_into: [token-mapper, component-taxonomy-mapper]
+phase: 54
+---
+<!-- Vendor docs: https://www.radix-ui.com/themes/docs/theme/color. -->
+
+# Radix Themes
+
+## Conventions
+
+- `@radix-ui/themes` is the styled layer, distinct from the headless `@radix-ui/react-*` primitives.
+- Each hue exposes a 12-step color scale per step role: steps 1 to 2 are backgrounds, 3 to 5 component backgrounds, 6 to 8 borders, 9 is solid, 11 is low-contrast text, 12 is high-contrast text.
+- Global config lives on `<Theme>` props: accentColor, grayColor, radius, scaling, appearance.
+
+## File patterns
+
+- `import "@radix-ui/themes/styles.css"` plus a `<Theme>` at the app root.
+- Per-step vars `--<accent>-1` through `--<accent>-12`.
+- Identify via: @radix-ui/themes in deps plus styles.css import.
+
+## Gotchas
+
+- Map the 12 steps as one scale with step roles; the step number encodes intent, so tag accordingly.
+- Do not confuse `@radix-ui/themes` (themed) with `@radix-ui/react-*` (headless, the shadcn substrate).
+- radius and accentColor are theme-level config, not per-component tokens.
+
+## Example output
+
+```json
+{
+  "schema_version": "52.0",
+  "nodes": [
+    { "id": "tok.color.accent-9", "type": "token", "subtype": "color", "name": "--accent-9", "summary": "Solid accent step 9 used for filled actions.", "complexity": "simple", "tags": ["color", "brand", "theme"] },
+    { "id": "tok.color.accent-11", "type": "token", "subtype": "color", "name": "--accent-11", "summary": "Low-contrast accent text, step 11.", "complexity": "simple", "tags": ["color", "contrast", "body-text"] },
+    { "id": "cmp.button", "type": "component", "name": "Button", "summary": "Themed solid button using accent step 9.", "complexity": "moderate", "tags": ["interactive", "atom"] }
+  ],
+  "edges": [
+    { "source": "cmp.button", "target": "tok.color.accent-9", "type": "uses-token", "direction": "forward", "weight": 0.9 }
+  ]
+}
+```