jsx_rosetta 0.5.1 → 0.6.0

data/skills/jsx-rosetta-resolve-todos/SKILL.md

@@ -0,0 +1,206 @@
+---
+name: jsx-rosetta-resolve-todos
+description: Resolve the `# TODO:` comments left by jsx_rosetta in generated Phlex / ViewComponent files. Mechanical substitution for known patterns (design tokens, prop-passing reminders); LLM-driven recipes for hooks, data-fetching, event handlers, navigation, and module constants; sharpened-TODO emission for everything else.
+---
+
+# jsx-rosetta-resolve-todos
+
+`jsx_rosetta` translates JSX/TSX into Phlex / ViewComponent / ERB and is intentionally conservative: when an expression can't be safely lowered, it preserves the original JS verbatim inside a `# TODO:` comment. This skill is the last-mile companion for converting that output into shippable Rails code.
+
+It does **not** speculate. The hard rule, inherited from the gem itself: prefer leaving a sharper TODO over guessing wrong. Three actions per TODO:
+
+- **resolve** — apply a known transformation, delete the TODO
+- **sharpen** — replace a verbose TODO with a tighter one a human can clear in seconds
+- **escalate** — leave untouched, surface in the report
+
+## Per-file workflow
+
+```
+1. Run `ruby -c <file>` to confirm the file parses before any edits.
+2. Walk TODOs top-to-bottom. Classify each against the routing table below.
+3. Dispatch to the matching recipe. Take exactly one of {resolve, sharpen, escalate}.
+4. Re-run `ruby -c`. If parsing breaks, REVERT and report `parse_failed` —
+   never ship a half-edit.
+5. Emit a JSON line with category counts.
+```
+
+The mechanical pre-passes (design tokens, promoted-@ivar reminders) run as standalone scripts with no LLM involved. Run them first; they're fast, safe (always `ruby -c`-validated before write), and remove a meaningful chunk of TODOs before any agent dispatch happens.
+
+## Routing table
+
+The TODO comments emitted by `jsx_rosetta` follow stable shapes. Routing is regex-based:
+
+| TODO regex | Recipe | Default action | Backing |
+|---|---|---|---|
+| `# TODO: (attribute\|style declaration) "X" dropped — couldn't translate: <RHS>` (RHS matches a configured token regex) | `recipes/01_design_tokens.md` | resolve via `tools/apply_substitutions.rb` | **script** |
+| `# TODO: render condition references binding\(s\) promoted to @ivar` | `recipes/02_promoted_ivar.md` | resolve or sharpen via `tools/apply_promoted_ivar.rb` | **script** |
+| `# TODO: React hooks detected` | `recipes/03_react_hooks.md` | sharpen — sub-classify hook flavor | docs only |
+| `# TODO: Apollo data-fetching hooks detected` | `recipes/04_apollo_hooks.md` | sharpen — extract query name + variables | docs only |
+| `# TODO: translate the original JSX `<event>` handler` | `recipes/05_event_handlers.md` | sharpen — classify behavioral vs mutation | docs only |
+| `# TODO: module-level constants` | `recipes/06_module_constants.md` | dispatch by sub-type | docs only |
+| `# TODO: Next.js navigation hooks detected` | `recipes/07_nextjs_navigation.md` | sharpen — extract route + params | docs only |
+| `# TODO: translate JS to Ruby — original:` | `recipes/08_generic_js_bailouts.md` | always sharpen | docs only |
+| `# TODO: (attribute\|style declaration) "X" dropped` (RHS doesn't match any token regex) | `recipes/08_generic_js_bailouts.md` | always sharpen | docs only |
+
+**Backing column legend:**
+- **script** — pure-Ruby tool ships with the skill. No LLM required; safe to run unattended.
+- **docs only** — recipe text is usable today by an LLM agent (e.g. via `jsx-rosetta-resolve-todo-file`). No mechanical tool yet; sub-classification and sharpening are agent work.
+
+When in doubt, sharpen.
+
+## Tools
+
+### `tools/discover_bailouts.rb`
+
+Pure-Ruby corpus scanner. Tallies dropped-expression RHS values, finds repeating member chains (`<root>.<member>...`), and suggests a `match:` regex per cluster. Use it to decide what's worth automating before you build any tables or recipes.
+
+```bash
+ruby tools/discover_bailouts.rb [--top N] [--json] [--all-todos] <file_or_dir>...
+```
+
+Output identifies the dominant "roots" in your corpus (`token`, `theme`, `vars`, etc.) — these are your candidate design-system / config namespaces. The script makes no claim about what they *mean*; that's your call.
+
+### `tools/apply_substitutions.rb`
+
+Pure-Ruby mechanical substitution. Reads a YAML config that declares a `match:` regex and a `tokens:` map; finds matching TODOs, splices values into the `render Foo.new(...)` immediately below.
+
+```bash
+ruby tools/apply_substitutions.rb --config <yaml> [--dry-run] [--quiet] <file_or_dir>...
+```
+
+Conservative by design:
+
+- Only single-line `render Foo.new(...)` calls
+- String-literal `style:` attribute (or absent); hash-form `style: { ... }` is skipped without false edits
+- Skips drops whose attribute name would produce an invalid Ruby identifier
+- Pre-write `ruby -c` validation; on failure, the file is left untouched and the run is reported as `parse_failed`
+
+See `examples/design_tokens.ant_design_v5.yml` for a full reference config (Ant Design v5 defaults, ~85 tokens). See `data/design_tokens.template.yml` for a blank schema you can fill in for your own design system.
+
+### `tools/apply_promoted_ivar.rb`
+
+Pure-Ruby resolution of the `# TODO: render condition references binding(s) promoted to @ivar` reminders. Reads each file's `def initialize` signature and either deletes the TODO (when every named prop is already in the signature) or sharpens it to a tagged single-liner naming exactly what's missing — distinguishing missing controller props from missing PascalCase imports.
+
+```bash
+ruby tools/apply_promoted_ivar.rb [--dry-run] [--quiet] <file_or_dir>...
+```
+
+Idempotent: safe to re-run after wiring more controllers.
+
+### Recipe content (`recipes/*.md`)
+
+Each recipe describes:
+- The TODO shape it handles
+- The transformation rule (resolve) or the sharpened-TODO template (sharpen)
+- What information to grep from the host Rails app
+- When to escalate
+
+Recipes are loaded by the `jsx-rosetta-resolve-todo-file` agent (one per file) for fan-out work, and by the human running the skill in interactive mode.
+
+## Sharpened-TODO format
+
+A sharpened TODO must include:
+
+1. **What** the source was doing in one phrase — no JS dump.
+2. **Where** the resolution belongs in Rails (controller / helper / Stimulus / view).
+3. **What's missing** — the unanswered question that prevents resolution.
+4. The original JS preserved in an indented `# Original:` block below.
+
+Template:
+
+```ruby
+# TODO[<category>]: <one-line what>. <where it belongs>. <what's needed>.
+# Original:
+#   <verbatim JS, indented>
+```
+
+Example transformation. Before:
+
+```ruby
+# TODO: React hooks detected. None translate automatically.
+# Hotwire/Stimulus handles behavior; controllers/views handle state;
+# turbo-frames handle async loading. Original source:
+#   const [open, setOpen] = useState(false);
+```
+
+After:
+
+```ruby
+# TODO[useState]: ephemeral UI state `open`. Move to Stimulus controller value: { open: Boolean }.
+# Original:
+#   const [open, setOpen] = useState(false);
+```
+
+The `[<category>]` tag is grep-friendly — humans can filter by tag to batch similar decisions.
+
+## Modes
+
+### Single-file (interactive)
+
+The skill is invoked on a specific file. Workflow runs in the main conversation context. Use when reviewing the result yourself or when the file has unusual shape that the recipes won't handle cleanly.
+
+### Batch (fan-out)
+
+The skill walks a directory and dispatches one `jsx-rosetta-resolve-todo-file` agent per file (or per chunk). Each agent loads the recipes from this skill's directory, processes its file, and emits a JSON report. The skill aggregates reports into a corpus-level summary.
+
+Recommended order in batch mode:
+
+1. **Discovery pass** (`discover_bailouts.rb --json`) — surface what's worth mapping.
+2. **Mechanical pre-passes** (`apply_substitutions.rb` for each design-system YAML you have, plus `apply_promoted_ivar.rb`) — strip out the trivially-mechanical TODOs first. No LLM, no agent.
+3. **Agent fan-out** — for what's left, one `jsx-rosetta-resolve-todo-file` worker per file. Workers are tool-restricted (Read, Edit, Bash for `ruby -c`, Grep) and stateless. Sonnet 4.6 is the right tier; Opus is overkill for recipe application; Haiku is too light for the surrounding-code reading the recipes need.
+4. **Re-run discovery** to confirm what was resolved and what's left to escalate to a human.
+
+## Configuration the user owns
+
+This skill ships with no app-specific assumptions. The files you (the consuming user) own:
+
+- `data/design_tokens.yml` (or any other YAML you point `apply_substitutions.rb` at). Created from `data/design_tokens.template.yml` or copied from `examples/`.
+- `data/target_app_conventions.yml` — paths, naming, CSS strategy. Recipes 03–07 read this to know where extracted helpers, controllers, and Stimulus controllers belong in your Rails app. Without it, recipes sharpen with `<TBD: see target_app_conventions.yml>` rather than guessing. Copy `data/target_app_conventions.template.yml` to seed it.
+
+Anything in `data/` other than `*.template.*` should be `.gitignored` in the consuming repo if it contains overrides specific to that app's theme or conventions.
+
+## Scope
+
+This skill addresses the corpus of `# TODO:` comments that `jsx_rosetta` emits. It does not:
+
+- Re-translate JSX (that's `jsx_rosetta` itself)
+- Touch business logic
+- Make architectural decisions about how a React app should map to Rails (controllers vs. service objects, Turbo Frames vs. plain links, etc.) — those are flagged for human review via sharpened TODOs
+
+Effort expectation: a meaningful fraction of TODOs reflect genuine human-judgment decisions and will not auto-resolve under any system. The skill's value is auto-resolving the mechanical chunk and compressing the rest into single-decision items. See "Validation" below for measured impact on the gem's own stress corpus.
+
+## Validation
+
+Measured against the `jsx_rosetta` gem's own Phlex stress corpus (1,245 generated `.rb` files, 4,846 `# TODO:` comments) using `tools/diff_corpus.rb`. The corpus represents a *fresh translation* — controllers haven't been wired yet, so promoted-ivar TODOs sharpen rather than resolve.
+
+| Pass | Files modified | TODOs resolved | TODOs sharpened | Parse failures |
+|---|---|---|---|---|
+| `apply_substitutions.rb --config examples/design_tokens.ant_design_v5.yml` | 158 / 1,245 | 336 | 0 | 0 / 1,245 |
+| `apply_promoted_ivar.rb` | 333 / 1,245 | 0 (corpus state) | 665 | 0 / 1,245 |
+| **Combined mechanical pre-pass** | **428 / 1,245** | **336 deleted** | **665 compressed** | **0 / 1,245** |
+
+Net change: 4,846 → 4,510 TODO comments. Of the 1,001 TODOs the mechanical passes touched:
+
+- 336 were deleted outright (Ant Design token references → literal values spliced into render calls)
+- 665 were compressed from verbose multi-line reminders into tagged single-liners (`# TODO[promoted_ivar]: controller must pass <names>...`) with explicit "missing prop" vs "missing import" verdicts
+
+The 117 unaddressed token TODOs are conservative bailouts (multi-line render shapes, hash-form `style:`, complex RHS expressions) that the substitution script intentionally skips rather than risk breaking output.
+
+What's *not* measured here:
+
+- The LLM-driven recipes (03–08) — they ship as documented intentions; their resolve/sharpen rate depends on a live conversion to validate against.
+- The remaining ~3,500 TODOs are concentrated in categories (`react_hooks` 378, `event_handler` 428, `module_constants` 355, `apollo_hooks` 222, `nextjs_navigation` 105, generic JS bailouts 1,053) where the recipes default to *sharpening* — measurable as compression once an agent runs the recipes on a real corpus.
+
+Reproduce with:
+
+```bash
+ruby tools/diff_corpus.rb <baseline_dir> <after_pipeline_dir>
+```
+
+## Future work
+
+Tracked here so the skill's roadmap is visible alongside its current shape:
+
+- **Cross-file context for fan-out workers.** Today each `jsx-rosetta-resolve-todo-file` worker is stateless — the same gql query referenced from 5 files would sharpen identically 5 times. A pre-pass that builds a project-wide "discovery digest" (recurring queries, recurring helpers, controller signatures already seen) and feeds it to each worker would let the corpus learn once. Hard to design ahead of real-conversion evidence; bolt-on later.
+- **Drift-detection spec.** The TODO regexes in this skill's recipes need to stay in sync with the strings emitted by `lib/jsx_rosetta/backend/phlex.rb`. One round-trip test per category (fixture → translate → resolve-todos → assert N matched) would catch silent emit-format drift. Worth doing once more recipes are backed by scripts; testing stub recipes is testing a sketch.
+- **Backing scripts for recipes 03–08.** Some sub-classifications (e.g. recipe 03's hook → Stimulus mapping for unambiguous shapes like `useState(false)`) may be mechanical enough to ship as scripts. Others (event handler classification, gql operation extraction) probably stay LLM-driven. The split will become clear after running the recipes on a real conversion.

data/skills/jsx-rosetta-resolve-todos/data/design_tokens.template.yml

@@ -0,0 +1,71 @@
+# design_tokens.template.yml — schema for apply_substitutions.rb config.
+#
+# Copy this file to your consuming app, e.g.:
+#   <your-app>/.claude/skills/jsx-rosetta-resolve-todos/data/design_tokens.yml
+# and fill in the entries that apply to your source codebase.
+#
+# Workflow to populate it:
+#   1. Run discover_bailouts.rb on your jsx_rosetta-generated output to find
+#      the dominant repeating member chains. It will print a suggested
+#      `match:` regex and the top capture keys.
+#   2. Paste the suggested regex into `match:` below.
+#   3. For each top key, look up what it resolves to in your source codebase
+#      (the design system's published defaults, your theme overrides, your
+#      Tailwind config, etc.) and add an entry to `tokens:`.
+#   4. Run apply_substitutions.rb --config <this file> on the corpus.
+#   5. Re-run discover_bailouts.rb to confirm the count dropped, and to
+#      surface the next worthwhile cluster to map.
+#
+# Pre-built reference tables for common design systems live in the skill's
+# `examples/` directory. If your source uses one of them with default
+# theming, you can use that file directly instead of building this one.
+
+# ─────────────────────────────────────────────────────────────────────────────
+# Schema
+# ─────────────────────────────────────────────────────────────────────────────
+#
+# match
+#   A regex string with exactly one capture group. The capture is used as the
+#   lookup key against `tokens:`. Examples:
+#     'token\.(\w+)'                  → Ant Design tokens (`token.colorText`)
+#     'theme\.palette\.(\w+)\.main'   → MUI palette mains (`theme.palette.primary.main`)
+#     'vars\.colors\.(\w+)'           → vanilla-extract color vars
+#     'tokens\.(\w+)'                 → Chakra UI tokens
+#
+# tokens
+#   Map from capture-group string → entry hash. Each entry:
+#
+#   value      The literal substitution. Type-sensitive:
+#                Integer → rendered as "<n>px" in inline style declarations,
+#                          and as a bare integer in numeric component kwargs.
+#                String  → used verbatim. Wrap CSS values, hex colors,
+#                          rgba(), font-family lists, etc.
+#                null    → explicitly skip auto-resolution. Use for entries
+#                          you've intentionally chosen NOT to substitute
+#                          (component-namespace tokens, ambiguous shorthand,
+#                          values that depend on runtime context). The TODO
+#                          stays in place for human review.
+#
+#   tailwind   (optional) Suggested utility class for a className-based
+#              refactor pass. Not used by apply_substitutions.rb directly;
+#              available as documentation for downstream recipes that want
+#              to convert inline styles to Tailwind utilities.
+#
+#   category   (optional) A grouping label for your own organization
+#              (e.g. "spacing", "color-text"). Not interpreted by tools.
+#
+#   notes      (optional) Free text for human readers — caveats, ambiguity,
+#              "verify per usage" reminders, etc.
+
+# ─────────────────────────────────────────────────────────────────────────────
+# Fill in below
+# ─────────────────────────────────────────────────────────────────────────────
+
+match: ''   # e.g. 'token\.(\w+)'
+
+tokens: {}
+  # exampleKey:
+  #   value: 4
+  #   tailwind: "p-1"
+  #   category: spacing
+  #   notes: "Ant Design v5 default 4px base."

data/skills/jsx-rosetta-resolve-todos/data/target_app_conventions.template.yml

@@ -0,0 +1,107 @@
+# target_app_conventions.template.yml
+#
+# Conventions of the consuming Rails application. The LLM-driven recipes
+# (03–07) read this file to know where extracted helpers, controllers, and
+# Stimulus controllers belong, and to know how the app is structured. Without
+# values here, recipes sharpen with `<TBD: see target_app_conventions.yml>`
+# rather than guessing.
+#
+# Copy this file to your consuming app's
+#   .claude/skills/jsx-rosetta-resolve-todos/data/target_app_conventions.yml
+# and fill in the values that apply. Leave a key as `null` (or omit it) if
+# your app doesn't use that surface — recipes will treat it as unavailable
+# and escalate or sharpen accordingly.
+
+# ─────────────────────────────────────────────────────────────────────────────
+# File-system layout
+# ─────────────────────────────────────────────────────────────────────────────
+
+# Where Rails controllers live. Recipe 04 (Apollo) sharpens with
+# "in <controller_path>/<name>_controller.rb#<action>" when extracting
+# data fetches.
+controller_path: app/controllers
+
+# Where view-scoped helpers live. Recipe 06 (module constants) directs
+# pure helper functions here.
+helper_path: app/helpers
+
+# Where app-wide service objects / POROs live. Recipe 06 directs more
+# substantial helpers here when they're shared across controllers.
+service_path: app/services
+
+# Where Phlex / ViewComponent components are dropped. The components
+# being resolved by this skill live here.
+component_dir: app/components
+
+# ─────────────────────────────────────────────────────────────────────────────
+# GraphQL — server-side
+# ─────────────────────────────────────────────────────────────────────────────
+
+# Where GraphQL resolvers / query objects live, if your app uses
+# graphql-ruby (or similar) server-side. Recipe 04 (Apollo) names this
+# path when sharpening "extract this query into a resolver."
+#
+# Set to `null` if your app doesn't run GraphQL server-side (e.g. you're
+# replacing client-side gql with REST endpoints or Turbo Frames).
+graphql_resolver_path: null   # e.g. app/graphql/resolvers
+
+# ─────────────────────────────────────────────────────────────────────────────
+# Stimulus
+# ─────────────────────────────────────────────────────────────────────────────
+
+# Where Stimulus controllers live. Recipes 03 (useState→value) and 05
+# (event handlers→actions) reference this path.
+stimulus_controller_path: app/javascript/controllers
+
+# How Stimulus controller files are named. Determines the data-controller
+# value emitted in HTML attributes.
+#   kebab-case   → file `foo_bar_controller.js` exposes `data-controller="foo-bar"`
+#   underscore   → file `foo_bar_controller.js` exposes `data-controller="foo_bar"`
+# (Rails default with importmap is kebab-case via the Stimulus loader.)
+stimulus_controller_naming: kebab-case
+
+# ─────────────────────────────────────────────────────────────────────────────
+# Styling
+# ─────────────────────────────────────────────────────────────────────────────
+
+# How the consuming app handles styles. Affects recipe 01's design-token
+# substitution suggestions and recipe 03/05 advice on inline-style refactoring.
+#   tailwind     → recipes prefer className utility classes (the YAML's
+#                  `tailwind:` field becomes the suggested target)
+#   css-modules  → recipes leave inline styles in place, suggest extraction
+#                  to <component>.module.css for substantial blocks
+#   plain        → inline styles stay inline; no refactor recommendation
+css_strategy: tailwind
+
+# Path to your Tailwind config, if css_strategy is tailwind. Recipe 01
+# can reference this when the design-token YAML's tailwind suggestions
+# don't match a class your config exposes.
+tailwind_config_path: tailwind.config.js
+
+# ─────────────────────────────────────────────────────────────────────────────
+# Routing
+# ─────────────────────────────────────────────────────────────────────────────
+
+# Path to your Rails routes file. Recipe 07 (Next.js navigation) references
+# it when sharpening `useRouter().push("/foo/[id]")` → "confirm in <routes>".
+routes_path: config/routes.rb
+
+# ─────────────────────────────────────────────────────────────────────────────
+# Naming
+# ─────────────────────────────────────────────────────────────────────────────
+
+# Suffix appended to generated Phlex component class names. The skill
+# uses this when generating cross-references (e.g. "controller passes
+# @foo to FooComponent"). Match what you set with `--phlex-suffix=` on
+# `jsx_rosetta translate`.
+component_class_suffix: Component   # e.g. ButtonComponent
+
+# ─────────────────────────────────────────────────────────────────────────────
+# Optional — anything else recipes should know
+# ─────────────────────────────────────────────────────────────────────────────
+
+# Free-text notes the recipes can read. Use for app-specific quirks the
+# schema doesn't capture (e.g. "we use Pundit for authorization, not
+# CanCanCan", "Turbo Frames are namespaced under app/views/frames/").
+notes: |
+  (none)

data/skills/jsx-rosetta-resolve-todos/examples/design_tokens.ant_design_v5.yml

@@ -0,0 +1,190 @@
+# Ant Design v5 design-token mapping — example for the jsx-rosetta-resolve-todos skill.
+#
+# Source:    Ant Design v5 default theme (https://ant.design/docs/react/customize-theme).
+# License:   Ant Design tokens and palette values are documented public API
+#            (Ant Design is MIT-licensed). This file documents the defaults; it
+#            contains no application-specific configuration.
+#
+# Use this file as-is if your source app uses Ant Design v5 with default theming.
+# If your app overrides ConfigProvider tokens, copy this file into your
+# `.claude/skills/jsx-rosetta-resolve-todos/data/design_tokens.yml` and adjust
+# values to match your overrides — the defaults here become the wrong answer
+# for any token your theme has changed.
+#
+# Schema:
+#   match:   Regex with one capture group. The capture is looked up in `tokens`.
+#            jsx_rosetta TODOs of the form
+#              # TODO: (attribute|style declaration) "X" dropped — couldn't translate: <RHS>
+#            are checked against this regex; matches drive substitution.
+#   tokens:  Map of capture-group string → entry. Each entry:
+#     value     Literal substitution. Integer = pixels (rendered as "<n>px" in
+#               inline style, bare integer in numeric kwargs). String = used
+#               verbatim. `null` = explicitly do not auto-resolve (e.g.
+#               component-namespace tokens that vary per app).
+#     tailwind  Optional. Suggested utility class for a className refactor.
+#     category  Optional grouping label.
+#     notes     Optional caveat for human readers.
+
+match: 'token\.(\w+)'
+
+tokens:
+  sizeXXS:    {value: 4,  tailwind: "p-1",  category: spacing}
+  paddingXXS: {value: 4,  tailwind: "p-1",  category: spacing}
+  marginXXS:  {value: 4,  tailwind: "m-1",  category: spacing}
+  paddingXS:  {value: 8,  tailwind: "p-2",  category: spacing}
+  marginXS:   {value: 8,  tailwind: "m-2",  category: spacing}
+  paddingSM:  {value: 12, tailwind: "p-3",  category: spacing}
+  marginSM:   {value: 12, tailwind: "m-3",  category: spacing}
+  padding:    {value: 16, tailwind: "p-4",  category: spacing}
+  margin:     {value: 16, tailwind: "m-4",  category: spacing}
+  paddingMD:  {value: 20, tailwind: "p-5",  category: spacing}
+  marginMD:   {value: 20, tailwind: "m-5",  category: spacing}
+  paddingLG:  {value: 24, tailwind: "p-6",  category: spacing}
+  marginLG:   {value: 24, tailwind: "m-6",  category: spacing}
+  paddingXL:  {value: 32, tailwind: "p-8",  category: spacing}
+
+  # ─────────────────────────────────────────────────────────────────────────────
+  # BORDER / RADIUS
+  # ─────────────────────────────────────────────────────────────────────────────
+
+  borderRadiusSM: {value: 4, tailwind: "rounded-sm",   category: radius}
+  borderRadius:   {value: 6, tailwind: "rounded-md",   category: radius, notes: "Ant default 6px sits between Tailwind sm(4) and md(6); rounded-md is closest."}
+  borderRadiusLG: {value: 8, tailwind: "rounded-lg",   category: radius}
+  lineWidth:      {value: 1, tailwind: "border",       category: line}
+  border:         {value: "1px solid #d9d9d9", tailwind: "border border-gray-300", category: line, notes: "Bare token.border is non-standard; assumed shorthand for the default 1px solid colorBorder."}
+
+  # ─────────────────────────────────────────────────────────────────────────────
+  # TYPOGRAPHY
+  # ─────────────────────────────────────────────────────────────────────────────
+
+  fontSizeSM:       {value: 12, tailwind: "text-xs",   category: typography}
+  fontSize:         {value: 14, tailwind: "text-sm",   category: typography}
+  fontSizeLG:       {value: 16, tailwind: "text-base", category: typography}
+  fontSizeXL:       {value: 20, tailwind: "text-xl",   category: typography}
+  fontSizeHeading4: {value: 20, tailwind: "text-xl",   category: typography}
+  fontSizeHeading3: {value: 24, tailwind: "text-2xl",  category: typography}
+  fontSizeHeading2: {value: 30, tailwind: "text-3xl",  category: typography}
+  fontWeightStrong: {value: 600, tailwind: "font-semibold", category: typography}
+  lineHeight:       {value: 1.5714, tailwind: "leading-normal", category: typography, notes: "Ant default ≈ 22/14."}
+  fontFamily:       {value: "-apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, 'Helvetica Neue', Arial, 'Noto Sans', sans-serif", tailwind: "font-sans", category: typography}
+  fontFamilyCode:   {value: "'SFMono-Regular', Consolas, 'Liberation Mono', Menlo, monospace", tailwind: "font-mono", category: typography}
+  font:             {value: 14, tailwind: "text-sm", category: typography, notes: "Bare `token.font` is non-standard; treated as fontSize default. Verify per usage."}
+
+  # ─────────────────────────────────────────────────────────────────────────────
+  # COLOR — TEXT
+  # ─────────────────────────────────────────────────────────────────────────────
+
+  colorTextBase:        {value: "#000000",            tailwind: "text-black",     category: color-text}
+  colorText:            {value: "rgba(0, 0, 0, 0.88)", tailwind: "text-gray-900", category: color-text}
+  colorTextSecondary:   {value: "rgba(0, 0, 0, 0.65)", tailwind: "text-gray-700", category: color-text}
+  colorTextTertiary:    {value: "rgba(0, 0, 0, 0.45)", tailwind: "text-gray-500", category: color-text}
+  colorTextQuaternary:  {value: "rgba(0, 0, 0, 0.25)", tailwind: "text-gray-400", category: color-text}
+  colorTextDescription: {value: "rgba(0, 0, 0, 0.45)", tailwind: "text-gray-500", category: color-text}
+  colorTextDisabled:    {value: "rgba(0, 0, 0, 0.25)", tailwind: "text-gray-400", category: color-text, notes: "Same alpha as quaternary; semantic intent differs."}
+  colorTextLightSolid:  {value: "#ffffff",            tailwind: "text-white",     category: color-text, notes: "On dark/colored backgrounds."}
+  colorWhite:           {value: "#ffffff",            tailwind: "text-white",     category: color-text}
+  colorLink:            {value: "#1677ff",            tailwind: "text-blue-600",  category: color-text}
+
+  # ─────────────────────────────────────────────────────────────────────────────
+  # COLOR — BACKGROUND
+  # ─────────────────────────────────────────────────────────────────────────────
+
+  colorBgContainer:  {value: "#ffffff",            tailwind: "bg-white",      category: color-bg}
+  colorBgLayout:     {value: "#f5f5f5",            tailwind: "bg-gray-100",   category: color-bg}
+  colorBgSolid:      {value: "#000000",            tailwind: "bg-black",      category: color-bg}
+  colorBgTextHover:  {value: "rgba(0, 0, 0, 0.06)", tailwind: "hover:bg-gray-100", category: color-bg, notes: "Use as hover state, not base."}
+
+  # ─────────────────────────────────────────────────────────────────────────────
+  # COLOR — BORDER
+  # ─────────────────────────────────────────────────────────────────────────────
+
+  colorBorder:          {value: "#d9d9d9", tailwind: "border-gray-300", category: color-border}
+  colorBorderSecondary: {value: "#f0f0f0", tailwind: "border-gray-200", category: color-border}
+
+  # ─────────────────────────────────────────────────────────────────────────────
+  # COLOR — FILL (translucent overlays)
+  # ─────────────────────────────────────────────────────────────────────────────
+
+  colorFillSecondary:  {value: "rgba(0, 0, 0, 0.06)", tailwind: "bg-black/5",  category: color-fill}
+  colorFillTertiary:   {value: "rgba(0, 0, 0, 0.04)", tailwind: "bg-black/5",  category: color-fill}
+  colorFillQuaternary: {value: "rgba(0, 0, 0, 0.02)", tailwind: "bg-black/[0.02]", category: color-fill}
+  colorFillAlter:      {value: "rgba(0, 0, 0, 0.02)", tailwind: "bg-black/[0.02]", category: color-fill}
+
+  # ─────────────────────────────────────────────────────────────────────────────
+  # COLOR — FEEDBACK (semantic: primary/success/warning/error/info)
+  # ─────────────────────────────────────────────────────────────────────────────
+
+  colorPrimary: {value: "#1677ff", tailwind: "text-blue-600",   category: color-feedback}
+  colorSuccess: {value: "#52c41a", tailwind: "text-green-600",  category: color-feedback}
+  colorWarning: {value: "#faad14", tailwind: "text-amber-500",  category: color-feedback}
+  colorError:   {value: "#ff4d4f", tailwind: "text-red-500",    category: color-feedback}
+  colorInfo:    {value: "#1677ff", tailwind: "text-blue-600",   category: color-feedback}
+
+  # Feedback backgrounds (lightened tints used for Alert / Tag / Badge surfaces)
+  colorPrimaryBg:      {value: "#e6f4ff", tailwind: "bg-blue-50",   category: color-feedback-bg}
+  colorPrimaryBgHover: {value: "#bae0ff", tailwind: "bg-blue-100",  category: color-feedback-bg}
+  colorInfoBgHover:    {value: "#bae0ff", tailwind: "bg-blue-100",  category: color-feedback-bg}
+  colorErrorBg:        {value: "#fff2f0", tailwind: "bg-red-50",    category: color-feedback-bg}
+  colorErrorBgHover:   {value: "#fff1f0", tailwind: "bg-red-50",    category: color-feedback-bg}
+  colorWarningBg:      {value: "#fffbe6", tailwind: "bg-amber-50",  category: color-feedback-bg}
+  colorWarningBgHover: {value: "#fff1b8", tailwind: "bg-amber-100", category: color-feedback-bg}
+
+  # Feedback borders
+  colorErrorBorder:       {value: "#ffccc7", tailwind: "border-red-200",  category: color-feedback-border}
+  colorInfoBorderHover:   {value: "#91caff", tailwind: "border-blue-300", category: color-feedback-border}
+
+  # ─────────────────────────────────────────────────────────────────────────────
+  # COLOR — BRAND PALETTE (named hues; used as base color names in Tag etc.)
+  # ─────────────────────────────────────────────────────────────────────────────
+
+  blue:   {value: "#1677ff", tailwind: "text-blue-600",   category: color-brand}
+  green:  {value: "#52c41a", tailwind: "text-green-600",  category: color-brand}
+  gold:   {value: "#faad14", tailwind: "text-amber-500",  category: color-brand}
+  orange: {value: "#fa8c16", tailwind: "text-orange-500", category: color-brand}
+  red:    {value: "#f5222d", tailwind: "text-red-600",    category: color-brand}
+  purple: {value: "#722ed1", tailwind: "text-purple-600", category: color-brand}
+  cyan:   {value: "#13c2c2", tailwind: "text-cyan-600",   category: color-brand}
+
+  # Indexed palette shades (1=lightest, 10=darkest) — shows up in custom theming.
+  blue1:   {value: "#e6f4ff", tailwind: "bg-blue-50",   category: color-palette-shade}
+  blue2:   {value: "#bae0ff", tailwind: "bg-blue-100",  category: color-palette-shade}
+  blue6:   {value: "#1677ff", tailwind: "text-blue-600", category: color-palette-shade}
+  green10: {value: "#092b00", tailwind: "text-green-950", category: color-palette-shade}
+
+  # Bare `token.color` — non-standard, source-specific. Don't auto-substitute.
+  color: {value: null, tailwind: null, category: unknown, notes: "Bare token.color isn't an Ant Design v5 default. Likely a custom theme extension. Sharpen the TODO with the surrounding context; don't auto-resolve."}
+
+  # ─────────────────────────────────────────────────────────────────────────────
+  # SHADOW
+  # ─────────────────────────────────────────────────────────────────────────────
+
+  boxShadow:          {value: "0 6px 16px 0 rgba(0,0,0,.08), 0 3px 6px -4px rgba(0,0,0,.12), 0 9px 28px 8px rgba(0,0,0,.05)", tailwind: "shadow-md", category: shadow}
+  boxShadowTertiary:  {value: "0 1px 2px 0 rgba(0,0,0,.03), 0 1px 6px -1px rgba(0,0,0,.02), 0 2px 4px 0 rgba(0,0,0,.02)", tailwind: "shadow-sm", category: shadow}
+
+  # ─────────────────────────────────────────────────────────────────────────────
+  # BREAKPOINT
+  # ─────────────────────────────────────────────────────────────────────────────
+
+  screenLG: {value: 992, tailwind: "lg:", category: breakpoint, notes: "Ant Design lg breakpoint = 992px. Tailwind's lg: prefix is 1024px — close, not identical."}
+
+  # ─────────────────────────────────────────────────────────────────────────────
+  # COMPONENT-NAMESPACE TOKENS — leave as TODO; resolution is per-component
+  # ─────────────────────────────────────────────────────────────────────────────
+  #
+  # These references (e.g. `token.Tag.colorText`) reach into Ant's component-token
+  # overrides, which the consuming app may have customized via ConfigProvider.
+  # Auto-substituting the default is unsafe — it would silently lose overrides.
+  # Sharpen the TODO with a note explaining what the source was reading and
+  # defer to human review.
+
+  Tag:    {value: null, tailwind: null, category: component, notes: "Ant Tag component-token namespace. Read the property in the source (e.g. token.Tag.defaultBg) and emit a sharper TODO."}
+  Layout: {value: null, tailwind: null, category: component, notes: "Ant Layout component-token namespace. Same handling as token.Tag."}
+
+  # ─────────────────────────────────────────────────────────────────────────────
+  # AMBIGUOUS / EDGE
+  # ─────────────────────────────────────────────────────────────────────────────
+
+  token: {value: null, tailwind: null, category: unknown, notes: "`token.token` — almost certainly a source bug or destructure typo. Flag for human review."}
+
+  paddingContentVerticalSM:   {value: 6,  tailwind: "py-1.5", category: spacing, notes: "Ant content-padding tokens; defaults vary by theme. Verify per usage."}
+  paddingContentHorizontalSM: {value: 12, tailwind: "px-3",   category: spacing, notes: "Ant content-padding tokens; defaults vary by theme. Verify per usage."}