@hegemonart/get-design-done 1.53.0 → 1.54.0

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

package/reference/systems/shadcn.md

@@ -0,0 +1,45 @@
+---
+name: shadcn
+kind: system
+composes_into: [token-mapper, component-taxonomy-mapper]
+phase: 54
+---
+<!-- Vendor docs: https://ui.shadcn.com/docs/theming. -->
+
+# shadcn/ui
+
+## Conventions
+
+- Not an npm dependency: components are copied INTO the repo (you own the source), built on Radix primitives plus Tailwind.
+- Color tokens are CSS vars in `globals.css`, semantic and paired: `--background`/`--foreground`, `--primary`, `--muted`, `--border`, `--ring` with `-foreground` partners. Values are HSL channel triplets (newer installs use OKLCH).
+- Variants come from cva with variant and size axes.
+
+## File patterns
+
+- `components.json` (style, tailwind.baseColor, cssVariables, aliases).
+- `lib/utils.ts` exporting the cn() helper (clsx plus tailwind-merge).
+- `components/ui/` source files; `app/globals.css` with `:root` and `.dark`.
+- Identify via: components.json plus lib/utils.ts cn().
+
+## Gotchas
+
+- Components are first-party source: model relationships to Radix as composes or extends, NOT an external depends-on.
+- Bare channel triplets like `240 10% 4%` are token values; capture them as tokens.
+- cn() is plumbing, not a component node.
+
+## Example output
+
+```json
+{
+  "schema_version": "52.0",
+  "nodes": [
+    { "id": "tok.color.primary", "type": "token", "subtype": "color", "name": "--primary", "summary": "Semantic primary color, HSL channel triplet.", "complexity": "simple", "tags": ["color", "brand", "theme"] },
+    { "id": "cmp.button", "type": "component", "name": "Button", "summary": "Owned button source wrapping Radix Slot.", "complexity": "moderate", "tags": ["interactive", "atom"] },
+    { "id": "var.button.destructive", "type": "variant", "name": "destructive", "summary": "cva destructive variant of Button.", "complexity": "simple", "tags": ["destructive", "state"] }
+  ],
+  "edges": [
+    { "source": "cmp.button", "target": "tok.color.primary", "type": "uses-token", "direction": "forward", "weight": 0.8 },
+    { "source": "var.button.destructive", "target": "cmp.button", "type": "extends", "direction": "forward", "weight": 0.7 }
+  ]
+}
+```

package/reference/systems/styled-components.md

@@ -0,0 +1,44 @@
+---
+name: styled-components
+kind: system
+composes_into: [token-mapper, component-taxonomy-mapper]
+phase: 54
+---
+<!-- Vendor docs: https://styled-components.com/docs/advanced#theming. -->
+
+# styled-components
+
+## Conventions
+
+- Runtime CSS-in-JS via tagged templates: ``styled.div`...` `` and ``styled(Base)`...` ``.
+- Tokens live in a plain JS theme passed through `<ThemeProvider theme={}>` and read by interpolation: `${p => p.theme.colors.primary}`.
+- Variants are prop-conditional interpolation (`${p => p.$variant === 'primary' && css`...`}`); ``css`...` `` composes reusable blocks; transient `$`-props drive styles but are not forwarded to the DOM.
+
+## File patterns
+
+- `theme.ts` with the theme object; ThemeProvider at the root.
+- `*.styles.ts` co-located; ``styled.X`...` ``, ``css`...` ``, ``createGlobalStyle`...` ``.
+- Identify via: styled-components in deps plus ThemeProvider.
+
+## Gotchas
+
+- There is no token file format: infer subtype from the key path (`theme.colors.*` to color, `theme.space.*` to spacing).
+- Variants are prop-conditional CSS; derive variant and state from the prop union plus `&:hover` and `&:disabled`.
+- v6 adds createGlobalStyle and RSC createTheme emitting CSS vars; transient `$`-props never reach the DOM.
+
+## Example output
+
+```json
+{
+  "schema_version": "52.0",
+  "nodes": [
+    { "id": "tok.color.primary", "type": "token", "subtype": "color", "name": "theme.colors.primary", "summary": "Primary brand color read via theme interpolation.", "complexity": "simple", "tags": ["color", "brand", "theme"] },
+    { "id": "cmp.button", "type": "component", "name": "Button", "summary": "Styled button reading theme.colors.", "complexity": "moderate", "tags": ["interactive", "atom"] },
+    { "id": "st.button.hover", "type": "state", "name": "hover", "summary": "Hover state via the &:hover selector.", "complexity": "simple", "tags": ["hover", "state"] }
+  ],
+  "edges": [
+    { "source": "cmp.button", "target": "tok.color.primary", "type": "uses-token", "direction": "forward", "weight": 0.9 },
+    { "source": "cmp.button", "target": "st.button.hover", "type": "transitions-to", "direction": "forward", "weight": 0.5 }
+  ]
+}
+```

package/reference/systems/tailwind.md

@@ -0,0 +1,44 @@
+---
+name: tailwind
+kind: system
+composes_into: [token-mapper, component-taxonomy-mapper]
+phase: 54
+---
+<!-- Vendor docs: https://tailwindcss.com/docs/theme. -->
+
+# Tailwind
+
+## Conventions
+
+- v4 inverts the model: tokens are namespaced CSS custom properties in an `@theme {}` block in the CSS entry. Tailwind generates utilities from token names.
+- Namespaces map to subtypes: `--color-*` to color (drives bg/text/border), `--spacing-*` to spacing, `--font-*` to typography, `--radius-*` to radius.
+- v3 defines tokens in `tailwind.config.{js,ts}` under `theme` or `theme.extend`.
+- Utility-class clusters on one element are that component's variants.
+
+## File patterns
+
+- v4: `app.css` or `globals.css` with `@import "tailwindcss"` plus an `@theme` block. May ship NO js config.
+- v3: `tailwind.config.{js,ts,cjs,mjs}`.
+- Identify via: tailwindcss in deps plus either config file or `@theme`.
+
+## Gotchas
+
+- The resolved `--color-*` and `--spacing-*` values are the tokens; utility classes are usage, not token nodes.
+- Arbitrary values `bg-[#1da1f2]` and `p-[3px]` bypass tokens. Flag them as an anti-pattern node, not a token.
+- `@apply` inlines utilities; it is not a token definition.
+
+## Example output
+
+```json
+{
+  "schema_version": "52.0",
+  "nodes": [
+    { "id": "tok.color.primary", "type": "token", "subtype": "color", "name": "--color-primary", "summary": "Brand primary color token from @theme.", "complexity": "simple", "tags": ["color", "brand", "theme"] },
+    { "id": "cmp.button", "type": "component", "name": "Button", "summary": "Primary action button styled with utility clusters.", "complexity": "moderate", "tags": ["interactive", "atom"] },
+    { "id": "ap.arbitrary-bg", "type": "anti-pattern", "name": "Arbitrary bg-[#1da1f2]", "summary": "Hardcoded color bypasses the token system.", "complexity": "simple", "tags": ["anti-pattern", "color"] }
+  ],
+  "edges": [
+    { "source": "cmp.button", "target": "tok.color.primary", "type": "uses-token", "direction": "forward", "weight": 0.9 }
+  ]
+}
+```