@hegemonart/get-design-done 1.52.0 → 1.54.0

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

package/reference/systems/vanilla-extract.md

@@ -0,0 +1,44 @@
+---
+name: vanilla-extract
+kind: system
+composes_into: [token-mapper, component-taxonomy-mapper]
+phase: 54
+---
+<!-- Vendor docs: https://vanilla-extract.style/documentation/theming/. -->
+
+# vanilla-extract
+
+## Conventions
+
+- Zero-runtime CSS-in-TS: `*.css.ts` files are extracted to static CSS at build time.
+- `createTheme(tokens)` returns `[themeClass, vars]`. `createThemeContract(shape)` declares a typed token CONTRACT (null leaves) that several `createTheme(contract, values)` implement, the canonical light and dark multi-theme pattern.
+- `style({})` defines a class; `styleVariants({})` and `recipe()` produce variant APIs; sprinkles add atomic utilities.
+
+## File patterns
+
+- `*.css.ts` such as `theme.css.ts`, `contract.css.ts`, `sprinkles.css.ts`.
+- `@vanilla-extract/vite-plugin` (or webpack) in config.
+- Identify via: @vanilla-extract/css in deps plus a `*.css.ts` file.
+
+## Gotchas
+
+- Tokens are the vars from createTheme or contract keys, NOT the literal values in the generated CSS.
+- The contract is the source of truth; each theme mirrors or extends it (model with mirrors or extends edges).
+- styleVariants and recipe are variants. Read the `.css.ts` source, not the generated `.css`.
+
+## Example output
+
+```json
+{
+  "schema_version": "52.0",
+  "nodes": [
+    { "id": "tok.color.brand", "type": "token", "subtype": "color", "name": "vars.color.brand", "summary": "Brand color slot declared in the theme contract.", "complexity": "simple", "tags": ["color", "brand", "theme"] },
+    { "id": "tok.space.md", "type": "token", "subtype": "spacing", "name": "vars.space.md", "summary": "Medium spacing scale step.", "complexity": "simple", "tags": ["spacing", "gap"] },
+    { "id": "cmp.button", "type": "component", "name": "Button", "summary": "Recipe-driven button consuming contract vars.", "complexity": "moderate", "tags": ["interactive", "atom"] }
+  ],
+  "edges": [
+    { "source": "cmp.button", "target": "tok.color.brand", "type": "uses-token", "direction": "forward", "weight": 0.9 },
+    { "source": "cmp.button", "target": "tok.space.md", "type": "uses-token", "direction": "forward", "weight": 0.5 }
+  ]
+}
+```