trdr-ds-install 1.11.0 → 2.0.0

package/plugins/trdr-design-system/skills/trdr-ds/SKILL.md

@@ -6,3314 +6,253 @@ argument-hint: "[analyze|apply|foundation|violations|components|final|resume|sta
 allowed-tools: [Read, Glob, Grep, Edit, Write, Bash, WebFetch]
 ---
 
-**Skill version:** 1.11.0
+**Skill version:** 2.0.0
 **npm package:** trdr-ds-install
 
-You are implementing the **TRDR Design System** in a developer's project. The Design Hub is the single source of truth and lives at **https://trdr.mrocontent.com.br**.
+# TRDR Design System — Skill Router
 
-This skill ships with two **offline-first snapshots** of the Hub:
+You are implementing the **TRDR Design System** in a developer's project. The Design Hub is the single source of truth: **https://trdr.mrocontent.com.br**.
 
-- `references/tokens.css` — all TRDR CSS variables (dark + light mode), copied verbatim from the Hub
-- `data/components.json` — full component catalog (implemented + stubs), with code blocks for everything `implemented: true` and `dependencies` array listing sub-component slugs used by compound components
+## Architecture — Progressive Loading
 
-The snapshots are kept in sync by the skill's maintainer via `npm run sync` in the `trdr-plugins` repo. **Always prefer the local snapshot.** Only fetch from the Hub when the user explicitly asks for the latest (`--latest` argument or `sync` mode).
+This skill is split into multiple files to prevent context overload. **NEVER read all files at once.** Load ONLY the file needed for the current step.
 
-Execute in multiple checkpointed phases: **PHASE 1: ANALYZE (saves DS_ANALYSIS.md) → PHASE 2: EXECUTE in 4 sub-phases (only after approval)**. Each sub-phase reads from saved files and stops for confirmation — preventing context overload and hallucinations.
-
----
-
-## Argument behaviour
-
-| Arg | Behaviour |
-|-----|-----------|
-| `analyze` *(default when none given)* | Run Phase 1 only — scan project, save `DS_ANALYSIS.md` + `SPRINT_PLAN.md`, present plan. Do not modify any project file |
-| `apply` | Run Phase 1 + Phase 2 (all 4 sub-phases, with STOP between each) |
-| `foundation` | Run Sub-fase A only — create tokens.css, components.css, CLAUDE.md, @imports. Requires DS_ANALYSIS.md |
-| `violations` | Run Sub-fase B only — process next pending violation batch. Requires DS_ANALYSIS.md + DS_PROGRESS.md |
-| `components` | Run Sub-fase C only — apply DS component classes. Requires DS_ANALYSIS.md + DS_PROGRESS.md |
-| `final` | Run Sub-fase D only — fix logos + generate DS_MIGRATION.md. Requires DS_PROGRESS.md |
-| `resume` | Read `SPRINT_PLAN.md` + `DS_PROGRESS.md`, find the next pending sprint, and execute it. Designed for use after `/clear` or in a new conversation — each sprint is self-contained |
-| `status` | Read `SPRINT_PLAN.md` + `DS_PROGRESS.md` and display sprint progress table — no files modified |
-| `batch [N]` | Override default violation batch size (default: 5 files/batch) |
-| `sync` | Re-fetch `https://trdr.mrocontent.com.br/components.json` and `https://trdr.mrocontent.com.br/tokens.css`, overwrite `data/components.json` and `references/tokens.css` in the skill directory, report the diff. No project changes. |
-| `rollback` | Read `DS_PROGRESS.md` to find the backup branch, reset working branch to that state, remove DS artifacts. Requires `DS_PROGRESS.md` with a `Backup branch:` entry |
-| `report` | Generate a bug report (DS_BUG_REPORT.md) with project context, errors encountered, and current migration state. Sends via email to the skill maintainer (mrocontent@gmail.com). Can also be triggered automatically when a sub-phase encounters critical failures |
-| `--latest` *(modifier on `analyze` or `apply`)* | Same as `sync` first, then continue normally |
-
----
-
-## PHASE 1: ANALYSIS (default behaviour on invocation)
-
-Scan the project and produce a structured migration plan. Do NOT modify any project files yet.
-
-### Step 0 — Check for skill updates, then detect previous progress
-
-**Version check (runs on every invocation):**
-
-Run this command silently via Bash:
-```bash
-npm show trdr-ds-install version 2>/dev/null
-```
-
-Compare the result with the **Skill version** constant at the top of this file.
-
-- If the command fails or returns empty (no internet / npm unavailable): skip silently, continue.
-- If registry version == local version: skip silently, continue.
-- If registry version > local version:
-  ```
-  🔄 Nova versão da skill disponível: trdr-ds-install@[registry-version] (instalada: 1.11.0)
-
-  Responda:
-  - `"atualizar"` / `"update"` — instalar a nova versão agora (requer reiniciar /trdr-ds após)
-  - `"continuar"` / `"skip"` — usar a versão atual desta sessão
-  ```
-  **STOP.** Wait for reply.
-
-  If reply is `"atualizar"` / `"update"`:
-  - Run Bash: `npx trdr-ds-install@latest`
-  - Output:
-    ```
-    ✅ Skill atualizada para trdr-ds-install@[registry-version].
-    Use /trdr-ds novamente para continuar com a versão mais recente.
-    ```
-  - STOP. Do not continue with the current (old) instructions.
-
-**After version check, detect previous progress:**
-
-Check if `DS_PROGRESS.md` exists at the project root.
-
-**If found AND `Status:` line is NOT `COMPLETE`:**
-```
-⚠️ Previous TRDR DS migration found (status: [IN_PROGRESS/PAUSED]).
-
-Reply with:
-- `"resume"` — continue from last checkpoint (Batch [N])
-- `"restart"` — discard progress and run a fresh analysis
-- `"status"` — see a progress summary without modifying anything
-```
-**STOP HERE. Wait for the developer's reply.**
-
-**If found AND `Status: COMPLETE`:**
-Inform the dev that a previous migration was already completed (show date). Offer to re-run analysis to detect new files added since then. Continue only if the dev explicitly says so.
-
-**If not found:** Continue normally to Step 1.
-
-### Step 1 — Detect framework and styling mode
-
-Read `package.json` at the project root. Identify:
-- Framework: Next.js (version), React (CRA/Vite), Vue/Nuxt, plain HTML, other
-- Language: TypeScript or JavaScript
-- Styling: CSS Modules, Tailwind, CSS-in-JS, plain CSS, SCSS
-
-**Determine `stylingMode`** — used in Steps 5, 6, 6.6 and 6.7 to generate the correct syntax for each framework:
-
-| stylingMode | Detection | How DS classes are applied |
-|-------------|-----------|---------------------------|
-| `plain-css` | No `tailwind.config.*`, no `*.module.css`, no CSS-in-JS dep | `class="trdr-btn"` in HTML attributes |
-| `css-modules` | `*.module.css` files present | `composes: trdr-btn from global` in module file, `className={styles.btn}` in JSX |
-| `tailwind` | `tailwind.config.*` present | `className="trdr-btn"` alongside Tailwind utilities |
-| `css-in-js` | `styled-components` or `@emotion/*` in package.json (WITHOUT `@mui/material`) | Insert token vars inside template literals / `theme` objects |
-| `mui` | `@mui/material` in package.json (v5+) | Theme-level integration: `createTheme()` palette/typography/shape use `var(--token)`, component `styleOverrides` use DS tokens, `sx` props migrated to token values |
-
-Save `stylingMode` — it must be referenced throughout Phase 2 wherever the output format differs by framework.
-
-**MUI detection priority:**
-If `package.json` contains `@mui/material` (any version >= 5):
-- Set `stylingMode: 'mui'` — do NOT fall through to `css-in-js` even if `@emotion/react` or `@emotion/styled` are present (they are MUI transitive dependencies, not direct CSS-in-JS usage)
-- Record `muiVersion` from package.json (e.g., `7.3.9`)
-- Detect MUI theme file: Glob for `**/theme.ts`, `**/theme.js`, `**/theme/index.ts`, `**/theme/index.js`, `**/theme/*.ts`, `**/createTheme*`, `**/muiTheme*` (exclude node_modules)
-- Record `themeFilePath` — the primary theme entry point (the file containing `createTheme()`)
-- Detect if project uses `ThemeProvider` in the app root: Grep for `<ThemeProvider` or `<MuiThemeProvider` in layout/app entry files
-- Record `hasThemeProvider: boolean`
-
-**MUI + Tailwind simultaneously:**
-If `package.json` contains BOTH `@mui/material` AND `tailwindcss`:
-- Set `stylingMode: 'mui'` (MUI dominant for component styling)
-- Set `hasTailwind: true` — Tailwind utilities may coexist for layout
-- In Step 3, scan BOTH theme files AND `tailwind.config.*` for violations
-
-**Dual stylingMode — tailwind + styled-components simultaneously:**
-If `package.json` contains BOTH `tailwindcss` AND `styled-components` (or `@emotion/*`):
-- Set `stylingMode: 'tailwind'` (dominant — utility classes in className)
-- Set `hasStyledComponents: true` to activate additional scan
-- In Step 3, add a styled-components scan alongside the normal CSS scan:
-  - Pattern in `*.tsx, *.ts, *.jsx, *.js`: `` styled\.\w+`[^`]*(?:#[0-9A-Fa-f]{3,8}|font-family|rgba\()[^`]*` ``
-  - For each template literal matched: run A, B, F violation checks against its content (even though it's not a `.css` file)
-  - Fix: replace hardcoded values inside template literals with CSS var tokens:
-    `background: #00A8CC` → `background: var(--action-brand-default);`
-    `font-family: 'Inter'` → `font-family: var(--font-secondary);`
-- Document in `CLAUDE.md` of the project: "This project uses styled-components AND Tailwind. New components: prefer Tailwind + DS classes. Existing styled-components: use DS tokens via CSS vars in template literals."
-
-### Step 2 — Map style structure
-
-Search for all style files:
-```
-Glob: ["**/*.css", "**/*.scss"] — exclude node_modules, .next, dist, build, out
-```
-
-Identify:
-- Main global CSS file (globals.css, main.css, index.css, app.css, styles.css)
-- Whether CSS custom properties already exist (look for `:root {`)
-- Potential conflicts with TRDR prefixes: `--bg-`, `--content-`, `--action-`, `--surface-`, `--border-`, `--spacing-`, `--radius-`
-- Whether fonts (JetBrains Mono, Inter, Roboto Mono) are already loaded
-
-Determine the best directory for new CSS files:
-- Next.js with `src/`: → `src/styles/`
-- Next.js without `src/`: → `styles/`
-- React CRA/Vite with `src/`: → `src/styles/` or `src/assets/`
-- Plain HTML: → `css/` or `styles/`
-
-**For `tailwind` stylingMode — additional scan:**
-Read `tailwind.config.js` (or `tailwind.config.ts`) and check `theme.colors` and `theme.extend.colors`:
-- If any color value is a hardcoded `#hex` that matches a TRDR DS token, flag it
-- Add `tailwind.config.js` to "FILES TO MODIFY" in the plan
-- Fix during Sub-fase B: replace each `'#hex'` with `'var(--semantic-token)'`
-- Example: `brand: '#00A8CC'` → `brand: 'var(--content-brand)'`
-- This allows Tailwind classes like `text-brand` to use the DS token automatically
-
-**For `mui` stylingMode — additional scan:**
-Read all theme files found during detection. Identify:
-- `createTheme()` call location and structure
-- `palette` object: list all hardcoded `#hex` values and their semantic role (primary, secondary, error, warning, success, info, background, text)
-- `typography` object: list all hardcoded `font-family`, `fontSize`, `fontWeight` values
-- `shape` object: list all hardcoded `borderRadius` values
-- `components` object: list all component `styleOverrides` with hardcoded values
-- Whether `cssVariables: true` is already passed to `createTheme()` (MUI v6+ CSS variables mode)
-- Whether project uses MUI's `sx` prop extensively: Grep for `sx=\{\{` in `*.tsx, *.jsx` — count distinct files
-- `styled(MuiComponent)` calls: Grep for `styled\([A-Z]\w+\)` in `*.tsx, *.ts, *.jsx, *.js` — count distinct files
-- Custom theme augmentation: `declare module '@mui/material/styles'` in `*.d.ts` files
-
-Add theme files and all files with `sx` / `styled(Mui*)` to "FILES TO MODIFY" in the plan.
-
-### Step 3 — Find violations
-
-Search for TRDR rule violations across all source files (*.css, *.scss, *.tsx, *.jsx, *.ts, *.js, *.vue, *.html):
-
-**A — Hardcoded colors** (should be CSS vars):
-Search pattern: `#[0-9A-Fa-f]{3,8}` in CSS/SCSS files; `#[0-9A-Fa-f]{3,8}` in component files within style props or className strings.
-
-**Special case — SVG attribute colors** (`stroke=`, `fill=`, `stop-color=` in HTML/JSX/Vue):
-When `#hex` is found inside an SVG attribute (not a CSS property), the fix is different — CSS variables do NOT work in SVG attributes. Instead:
-- If the SVG is a simple icon with a single solid color → replace with `stroke="currentColor"` / `fill="currentColor"` and control color via a CSS class (e.g., `.icon-brand { color: var(--content-brand); }`)
-- If the SVG has multiple distinct colors (multi-tone icon) → it should be replaced as a Category J violation (inline SVG → icon library)
-- Do NOT write `stroke="var(--token)"` — it is invalid in HTML SVG attributes
-
-Track SVG attribute color violations separately as **A\*** in DS_ANALYSIS.md with the note "SVG attribute — requires currentColor + CSS class approach, not var()."
-
-**B — Hardcoded font-family** (should be var(--font-primary/secondary/mono)):
-Search: `font-family.*Inter|font-family.*JetBrains Mono|font-family.*Space Grotesk|font-family.*Roboto Mono`
-
-**Note — JSX camelCase:** In React/Next.js files, font-family appears as `fontFamily` inside `style={{}}` objects. These are NOT detected by Category B (which scans CSS). They are captured by Category I (inline styles with `font` keyword). Do NOT double-count them in Category B; address them in Category I fix instead.
-
-**C — Hardcoded px spacing** (should be var(--spacing-*)):
-Search: `(margin|padding|gap):\s*\d+px` in CSS/SCSS
-
-**D — Primitive token usage** (should be semantic):
-Search: `var\(--color-|var\(--space-` in CSS/SCSS/component files
-
-Also search for **custom CSS variable definitions with primitive naming** in `:root {}` blocks:
-- Pattern: `--color-[a-z]|--space-[0-9]|--font-size-[0-9]` inside `:root {`
-- Flag as: "Custom CSS variable using primitive-style name: `--color-brand`. This duplicates DS token naming. Remove and replace all `var(--color-brand)` usages with the appropriate semantic token."
-- Do NOT auto-remove — flag for manual review in DS_MIGRATION.md
-
-**E — Missing tokens.css**:
-Check if `tokens.css` already exists in the project and if it's imported in the global CSS.
-
-**F — Hardcoded rgba colors** (should use DS semantic tokens or be flagged):
-Search: `rgba\(` in CSS/SCSS/HTML files (excluding node_modules, vendor)
-
-**G — Custom gradients (non-TRDR)** (should use var(--gradient-*) tokens):
-Search: `linear-gradient|radial-gradient` in CSS/SCSS/HTML files
-Flag any gradient that doesn't reference a TRDR gradient token (`var(--gradient-*)`)
-
-**Gradients with hex stops:** Compare against TRDR gradient token approximate values:
-- `--gradient-bg-hero` ≈ `linear-gradient(180deg, #0E0E0E 0%, #141519 100%)`
-- `--gradient-bg-surface` ≈ `linear-gradient(180deg, #141519 0%, #0E0E0E 100%)`
-- `--gradient-brand` ≈ `linear-gradient(90deg, #00A8CC 0%, #00D4FF 100%)`
-If a gradient closely matches one of these: replace with `var(--gradient-name)`.
-If no match: flag in DS_MIGRATION.md as "Custom gradient — no DS token available."
-Non-DS colors in gradient stops (e.g. `#0a1520`) are also A violations — flag separately.
-
-**Gradients with rgba stops:** When gradient stops use `rgba()` instead of hex:
-1. Extract the base color from each rgba stop and identify it in the TRDR color mapping table.
-2. If the base color has a DS token: recommend `rgba(var(--token-rgb), opacity)` if the DS exposes RGB variables, otherwise flag in DS_MIGRATION.md.
-3. **Fade-to-transparent** pattern (e.g. `rgba(0,212,255,0.04) 0%, transparent 100%`):
-   - This is a glow/haze effect. Very unlikely to have a DS token.
-   - Flag as: "Glow effect gradient — no DS token. Consider converting to `box-shadow: 0 0 Xpx var(--token)` or remove if purely decorative."
-4. **Overlay gradient** (e.g. `rgba(255,204,64,0.1) 0%, rgba(255,204,64,0.05) 100%`):
-   - Flag as: "Tinted overlay gradient — no DS equivalent. Map rgba base color to token; keep gradient as-is or convert to a solid rgba with semantic token."
-
-**H — Hardcoded font-size in px** (should use .trdr-h* / .trdr-body-* text style classes):
-Search: `font-size:\s*\d+px` in CSS/SCSS files (skip tokens.css itself)
-
-**I — Inline styles with design properties** (should be CSS classes with tokens):
-
-**I.1 — JSX/HTML style attribute** (standard inline styles):
-Search in `*.html, *.tsx, *.jsx, *.vue, *.svelte`:
-- HTML/Vue: `style="[^"]*(?:color|background|font|padding|margin|gap|border)[^"]*"`
-- React/JSX: `style=\{\{[^}]*(?:color|background|font|padding|margin|gap|border)[^}]*\}\}`
-- Vue binding: `:style="\{[^}]*(?:color|background|font|padding|margin|gap|border)[^}]*\}"`
-
-Do NOT flag (these are acceptable exceptions):
-- `background-image: url(...)` — dynamic image URL from data
-- `style="--custom-prop: value"` — CSS custom property passing a dynamic value to CSS (e.g. `style="--card-delay:0.1s"`)
-- `style={{ '--custom-prop': value }}` — same in JSX
-
-**I.2 — Dynamic DOM style assignment** (imperative JS manipulation, NOT covered by I.1):
-Search in `*.tsx, *.jsx, *.js, *.ts`:
-- Pattern: `\.style\.[a-zA-Z]+\s*=\s*['"]`
-- Example: `e.currentTarget.style.background = 'rgba(255,255,255,0.03)'`
-- Example: `ref.current.style.color = '#00D4FF'`
-
-This pattern is common in hover handlers (`onMouseEnter/onMouseLeave`) and imperative animations. The assigned value is a hardcoded design value that must be replaced.
-
-**I.2 fix procedure:**
-
-*CASE 1 — onMouseEnter/onMouseLeave hover effect:*
-This is the most common case. Convert to a CSS `:hover` rule:
-```css
-/* Before: onMouseEnter sets background imperatively */
-.item { transition: background 0.15s; }
-.item:hover { background: var(--surface-hover); }
-```
-Remove the `onMouseEnter` and `onMouseLeave` handlers. Add `className="item"` to the element.
-
-*CASE 2 — State-driven imperative style (non-hover):*
-If the DOM assignment is driven by JS logic beyond simple hover, replace the hardcoded value only:
-```tsx
-// Before
-el.style.background = 'rgba(255,255,255,0.03)';
-// After
-el.style.background = 'var(--surface-hover)';
-```
-Document in DS_PROGRESS.md as "I.2 fix — dynamic style value replaced with token."
-
-PRIORITY: Always prefer CASE 1 (CSS pseudo-class) — it's more performant and idiomatic than CASE 2.
-
-**J — SVG icons inline** (should use an icon library):
-Search in `*.html, *.tsx, *.jsx, *.vue`:
-- Pattern: `<svg` in source files (NOT in logo files, NOT in `node_modules/`, `references/`, `assets/icons/`)
-- Do NOT flag: `<svg` in known logo files (those with the official TRDR fingerprint)
-- Count distinct files with inline SVGs, not total occurrences
-
-**Severity sub-classification:**
-- **J.high**: `<svg>` with hardcoded `stroke="#hex"` or `fill="#hex"` — both a J and A* violation; replace with icon library ASAP
-- **J.medium**: `<svg>` with dynamic JSX fill/stroke expression (e.g. `fill={isActive ? 'currentColor' : 'none'}`) — no hex hardcoded, but state-driven SVG attribute that must be preserved during migration; replace with icon library using conditional CSS class
-- **J.low**: `<svg>` using ONLY `currentColor` / `inherit` (no hardcoded colors) — still prefer icon library, but lower priority; note in plan: "SVG uses currentColor (color is CSS-controlled). Migration to Material Icons recommended but non-urgent."
-
-**J.medium fix procedure — dynamic SVG attributes:**
-When an SVG has `fill={condition ? 'currentColor' : 'none'}` or `stroke={value}` (JSX expression):
-1. Identify the two visual states (filled/outlined, active/inactive)
-2. Create CSS classes for each state:
-   ```css
-   .icon-star { color: var(--content-tertiary); }
-   .icon-star.active { color: var(--context-trading-signal); }
-   ```
-3. Replace the SVG with a Material Icon (or equivalent DS icon) using a conditional className:
-   ```tsx
-   <span className={`material-icons icon-star ${isWatching ? 'active' : ''}`}>star</span>
-   ```
-4. The `fill`/`stroke` logic is handled entirely by CSS — never pass state to icon attributes.
-
-**K — Logo missing or incorrect in HTML/JSX** (should use official logo-trdr.svg):
-Search in `*.html, *.tsx, *.jsx, *.vue` using **two separate Grep calls** (the combined pattern is unreliable in ripgrep):
-
-Call 1 — Non-official img logo (HTML):
-- Pattern: `src="[^"]*logo(?!-trdr)[^"]*"` — img/Image with logo in the src value itself (covers JSX where src is first attribute)
-- Secondary: `<img[^>]*(?:logo|brand|mark)[^>]*src="(?!.*logo-trdr)[^"]*"` — catches cases where logo/brand/mark appears in alt= or class= before src=
-
-Call 1b — Next.js `<Image>` component (Next.js projects only):
-- Pattern: `<Image[^>]*src="[^"]*logo(?!-trdr)[^"]*"` — next/image component with non-official logo
-- Also flag `<Image[^>]*src=\{[^}]*logo(?!Trdr)[^}]*\}` for dynamic src with variable name not matching logoTrdr
-
-Call 2 — Text span as logo (use this pattern, NOT the combined version):
-- Pattern: `>\s*TRDR\s*<` — finds any element with text content "TRDR"
-- Then check if the surrounding element is `<span>` or `<div>` (not `<img alt="TRDR">`)
-- Simpler alternative: `class="[^"]*logo[^"]*"` + check if no `<img` tag on the same line
-
-Call 3 — Wrong logo import:
-- Pattern: `import\s+\w+\s+from\s+['"][^'"]*logo(?!-trdr)[^'"]*['"]` — logo import that isn't logo-trdr
-
-Do NOT flag: `logo-trdr.svg` references — those are correct.
-
-**Note:** The pattern `<span[^>]*>[^<]*TRDR[^<]*</span>` is known to fail in ripgrep — do NOT use it.
-
-**L — Hardcoded values in MUI theme** (only when `stylingMode === 'mui'`):
-Search in theme files (`**/theme/**/*.ts`, `**/theme/**/*.js`, `**/theme.ts`, `**/theme.js`, `**/createTheme*`, `**/muiTheme*`):
-
-L.1 — palette hardcoded colors:
-- Pattern: `(?:main|light|dark|contrastText|paper|default):\s*['"]#[0-9A-Fa-f]{3,8}['"]`
-- Also: `primary:|secondary:|error:|warning:|success:|info:|background:|text:` objects with nested hex values
-- Fix: replace with `'var(--semantic-token)'` using the color mapping table
-
-L.2 — typography hardcoded values:
-- Pattern: `fontFamily:\s*['"][^'"]*Inter|fontFamily:\s*['"][^'"]*JetBrains|fontSize:\s*\d+` inside typography object
-- Fix: replace with `'var(--font-*)'` tokens
-
-L.3 — shape hardcoded radius:
-- Pattern: `borderRadius:\s*\d+` inside shape object or component styleOverrides
-- Fix: replace with numeric value from DS radius mapping
-
-L.4 — component styleOverrides hardcoded values:
-- Search inside `components:` > `Mui*` > `styleOverrides` for any `#hex`, `Npx` (spacing/radius), `font-family`
-- Fix: replace with appropriate `var(--token)`
-
-**M — Hardcoded values in MUI sx props** (only when `stylingMode === 'mui'`):
-Search in all component files (`*.tsx, *.jsx`):
-- Pattern: `sx=\{\{` then scan content for `#[0-9A-Fa-f]{3,8}`, `(?:padding|margin|gap):\s*['"]?\d+(?:px)?`, `fontFamily:`, `fontSize:\s*\d+`, `borderRadius:\s*\d+`
-- Also detect hardcoded values inside nested pseudo-selectors (`'&:hover'`, `'& .MuiXxx'`)
-- Fix: replace hardcoded values with `'var(--token)'`
-
-**N — Hardcoded values in styled(MuiComponent) calls** (only when `stylingMode === 'mui'`):
-Search in all component files (`*.tsx, *.jsx, *.ts, *.js`):
-- Pattern: `styled\([A-Z]\w+\)` — then scan the styled block for `#hex`, hardcoded `fontFamily`, `fontSize`, `borderRadius`, spacing px values
-- Fix: replace hardcoded values with `'var(--token)'`
-
-**MUI violation categories L, M, N are ONLY scanned when `stylingMode === 'mui'`** — they do not apply to other modes.
-
-Track:
-- `total_violations` = sum of all A–K occurrences (+ L, M, N when MUI)
-- `total_files_with_violations` = count of unique files with ≥ 1 violation
-- `violations_by_folder` = map of `{ folder: string, files: string[], count: number }[]` grouped by first-level folder inside `src/` (or project root if no `src/`)
-
-### Step 3.5 — Detect component replacement candidates
-
-Scan the project for UI patterns that indicate elements replaceable by TRDR implemented components.
-
-**Scope:** `*.tsx, *.jsx, *.ts, *.js, *.html, *.vue` — exclude `node_modules/, .next/, dist/, build/, out/`.
-
-Use Grep (not Bash grep) to search for the patterns below. Group patterns from the same slug into a single call.
-
-**Pattern table per TRDR implemented component:**
-
-| Slug | Search patterns |
-|------|----------------|
-| `button` | `<button`, `<Button`, `type="submit"`, `type="button"`, `role="button"` |
-| `text-input` | `<input`, `<TextInput`, `<textarea`, `type="text"`, `type="email"`, `type="password"`, `type="search"` |
-| `checkbox` | `type="checkbox"`, `<Checkbox`, `\.checkbox` |
-| `radio-button` | `type="radio"`, `<RadioButton`, `<Radio[^B]` |
-| `switch` | `<Switch`, `role="switch"`, `\.toggle`, `\.switch` |
-| `dropdown` | `<select`, `<Select`, `<Dropdown`, `role="listbox"`, `role="combobox"` |
-| `combo-input` | `<ComboInput`, `combo.{0,10}input` |
-| `tooltip` | `<Tooltip`, `role="tooltip"`, `data-tooltip` |
-| `abas` | `<Tabs`, `role="tablist"`, `role="tab"`, `\.tabs` |
-| `segmented-control` | `<SegmentedControl`, `\.segmented`, `segment.{0,15}control` |
-| `sub-menu-item` | `<MenuItem`, `<SubMenu`, `\.menu-item`, `\.submenu` |
-| `card` | `<Card`, `\.card`, `<article` |
-| `boleta` | `<Boleta`, `boleta` |
-| `janela` | `<Janela`, `trading.{0,10}window` |
-| `tabela-cotacoes` | `<TabelaCotacoes`, `.quotes-table`, `.price-list`, `<table` with price/ticker/cotacao columns |
-| `tabela-ordens` | `<TabelaOrdens`, `.orders-table`, `.order-list`, `<table` with order/position columns |
-| `floating-menu` | `<FloatingMenu`, `.floating-menu`, `position:absolute` + `z-index` + list pattern |
-| `news-card` | `<NewsCard`, `.news-card`, `.article-card`, `<article` with image + title + date pattern |
-| `header` | `<Header`, `<header`, `.header`, `.navbar`, `<nav` at top-level page position |
-| `badge` | `<Badge`, `.badge`, `.tag`, `.chip`, `.label-status`, `<span` with short status-like text |
-
-**Rules:**
-- For each slug, count the distinct files that matched (not total lines) — one file counts as one occurrence.
-- Discard matches in test files (`*.test.*`, `*.spec.*`) — those don't count as UI usage.
-- Store results as a list of `{ slug, files: ["path:line", ...] }` — used in Step 5 and Phase 2 Step 6.
-- If a slug has zero matches, omit it from the replacement candidates list.
-- `title=""` attribute is too noisy — do NOT use it for tooltip detection; prefer `<Tooltip` / `role="tooltip"` / `data-tooltip`.
-
-**Also scan for CSS custom classes that re-implement DS components** (common in plain-HTML projects):
-
-| DS Component | CSS pattern to detect | Signal |
-|---|---|---|
-| Button | `.btn`, `.button`, `[class*="btn"]`, `[class*="button"]` in CSS with `cursor:pointer` | Likely button reimplementation |
-| Text Input | `.input`, `.text-field`, `.search-bar` in CSS with `border` + `padding` | Likely input reimplementation |
-| Segment Control | `.tab`, `.segment`, `.lang-selector` in CSS with `display:flex` + `border-radius` | Likely segmented reimplementation |
-
-For each match, add to `replacementCandidates[]` with a `customCssClass` field noting the project's class name, so Phase 2 Step 6 can add DS classes to those elements.
-
-**MUI component detection (only when `stylingMode === 'mui'`):**
-
-When `stylingMode === 'mui'`, the component candidate scan shifts focus. Instead of searching for HTML tags to replace with DS classes, search for MUI components that need theme-level DS token integration:
-
-| DS Slug | MUI Component patterns |
-|---------|----------------------|
-| `button` | `<Button`, `<IconButton`, `<LoadingButton`, `<Fab` |
-| `text-input` | `<TextField`, `<Input`, `<OutlinedInput`, `<FilledInput` |
-| `checkbox` | `<Checkbox`, `<FormControlLabel` with checkbox |
-| `radio-button` | `<Radio`, `<RadioGroup` |
-| `switch` | `<Switch` (MUI) |
-| `dropdown` | `<Select`, `<Autocomplete`, `<NativeSelect` |
-| `tooltip` | `<Tooltip` (MUI) |
-| `abas` | `<Tabs`, `<Tab` (MUI) |
-| `card` | `<Card`, `<CardContent`, `<CardActions`, `<CardMedia` |
-| `badge` | `<Badge`, `<Chip` (MUI) |
-| `header` | `<AppBar`, `<Toolbar` |
-| `modal` | `<Dialog`, `<Modal`, `<DialogTitle`, `<DialogContent` |
-
-For MUI projects, the purpose of detecting these components is NOT to replace them (they stay as MUI components), but to know WHICH MUI theme `components.MuiXxx.styleOverrides` entries to generate in Sub-fase C.
-
-Store results in the same `replacementCandidates[]` structure — the `slug` and `files` fields are used, but classification follows MUI-specific rules (see Step 3.5b).
-
-**Output:** `replacementCandidates[]` — passed to Step 3.5b, Step 5 template and Phase 2 Step 6.
-
-### Step 3.5b — Capture structural context for each candidate
-
-For each file:line match found in Step 3.5, read the surrounding context (10 lines before and after the match) and classify the replacement complexity:
-
-| Classification | Criteria | Phase 2 action |
-|---|---|---|
-| `simple` | Element has only text content. No event handlers (`onClick`, `onChange`, etc.), no conditional rendering (`{condition && ...}`, ternary), no dynamic props beyond basic HTML attributes (`id`, `name`, `class`, `placeholder`, `type`) | Full DS component replacement — swap the element entirely with the DS component structure, adapting content |
-| `complex-preservable` | Element has event handlers, data bindings (`value={state}`, `checked={state}`), refs, or conditional rendering, BUT the DOM structure maps cleanly to a DS component | Apply DS structure + classes, preserving ALL handlers, bindings, and conditional logic |
-| `complex-manual` | Element has deeply nested custom logic, multiple conditional branches affecting structure, dynamically generated children, or domain-specific behavior that doesn't map to any DS component pattern | Flag for manual review in DS_MIGRATION.md — do NOT auto-modify |
-
-**MUI classification rules (only when `stylingMode === 'mui'`):**
-
-When `stylingMode === 'mui'`, use these classifications instead of the table above:
-
-| Classification | Criteria | Phase 2 action |
-|---|---|---|
-| `theme-override` | Standard MUI component usage — the component should receive DS tokens via theme `components.MuiXxx.styleOverrides` | Generate/update styleOverrides in theme file (Sub-fase C) |
-| `sx-migration` | Component has `sx={{...}}` with hardcoded design values (colors, fonts, radius) | Replace hardcoded sx values with `'var(--token)'` (Sub-fase B/C) |
-| `styled-migration` | Component uses `styled(MuiComponent)` with hardcoded values | Replace values inside styled() call with `'var(--token)'` (Sub-fase B/C) |
-| `complex-manual` | Deeply customized MUI component with renderProp, slots API, complex theme augmentation, or `sx` with dynamic calculations | Flag for manual review in DS_MIGRATION.md |
-
-All detected MUI components default to `theme-override`. Add `sx-migration` or `styled-migration` only for individual instances that also have inline hardcoded values.
-
-**For each candidate, store:**
-```json
-{
-  "slug": "button",
-  "file": "src/components/Hero.tsx",
-  "line": 42,
-  "classification": "simple",
-  "existingContent": "Get Started",
-  "existingHandlers": [],
-  "existingClasses": "btn-primary hero-cta",
-  "existingProps": [],
-  "suggestedDsVariant": "trdr-btn-primary"
-}
-```
-
-**Variant detection rules (by signals in existing code):**
-
-| Existing pattern signals | Suggested DS variant |
-|---|---|
-| `.btn-primary`, `.cta`, `type="submit"`, prominent/brand color (cyan, blue) | `trdr-btn-primary` |
-| `.btn-secondary`, `.btn-cancel`, muted/gray color | `trdr-btn-secondary` |
-| `.btn-outline`, `.btn-ghost`, transparent background + border | `trdr-btn-ghost` |
-| `.btn-danger`, `.btn-delete`, red/orange/destructive color | `trdr-btn-destructive` |
-| `.btn-link`, `<a>` styled as button, no border/bg | `trdr-btn-link` |
-| `type="text"`, `type="email"`, `type="password"`, `type="search"`, `<textarea>` | `trdr-text-input` |
-| `type="checkbox"` | `trdr-checkbox` |
-| `type="radio"` | `trdr-radio-button` |
-| `role="switch"`, `.toggle`, `.switch` | `trdr-switch` |
-| `<select>`, `role="listbox"` | `trdr-dropdown` |
-| `role="tablist"`, `.tabs` | `trdr-abas` or `trdr-segment-control` |
-| `.badge` + green/success color | `trdr-badge-success` |
-| `.badge` + blue/brand color | `trdr-badge-brand` |
-| `.badge` + yellow/warning color | `trdr-badge-warning` |
-| `.badge` + neutral/gray color | `trdr-badge-neutral` |
-| `<Tooltip>`, `role="tooltip"`, `data-tooltip` | `trdr-tooltip` |
-
-**Output:** Updated `replacementCandidates[]` — each entry now includes `classification`, `existingContent`, `existingHandlers`, `existingProps`, and `suggestedDsVariant`.
-
-### Step 3.6 — Logo audit
-
-Glob for logo files across the project:
-
-```
-Patterns: ["**/logo*.svg", "**/*trdr*.svg", "**/brand*.svg", "**/icon-trdr*.svg"]
-Exclude: node_modules/, .next/, dist/, build/, out/, references/
-```
-
-The official TRDR logo fingerprint (both must be present):
-- `viewBox="0 0 105 41"` — exact dimensions of the reference logo
-- `fill="#00D4FF"` — brand cyan used in the symbol paths
-
-For each found SVG file:
-1. Read its content.
-2. Check for both fingerprint markers.
-3. Classify:
-   - ✅ **CORRECT** — contains both markers → already the official logo
-   - ❌ **WRONG** — SVG file exists but doesn't match (different viewBox, colors, or both)
-   - ⚠️ **UNKNOWN** — binary or unusually formatted SVG, can't determine
-
-Store result as `logoAudit = { correct: string[], wrong: string[], unknown: string[] }`.
-
-If no logo files are found at all, check if a `public/` directory exists at the project root — flag it as a suggested location to add the logo.
-
-Include logo findings in the migration plan (Step 5 below).
-
-### Step 4 — Load component catalog (offline-first)
-
-Read the local snapshot from the skill directory:
-
-```
-Read: <skill-dir>/data/components.json
-```
-
-Where `<skill-dir>` is either `~/.claude/skills/trdr-ds/` or `<project>/.claude/skills/trdr-ds/`. Try both.
-
-Expected JSON shape:
-```json
-{
-  "version": "1.0",
-  "generatedAt": "2026-05-08T...",
-  "total": 60,
-  "implemented": 13,
-  "categories": { "formulario": "Formulário / Controles", ... },
-  "components": [
-    {
-      "slug": "button", "name": "Button", "figmaId": "1318:749",
-      "category": "formulario", "description": "...",
-      "implemented": true,
-      "props": [...], "dimensions": [...], "tokens": [...],
-      "code": { "html": "...", "css": "...", "react": "...", "prompt": "..." }
-    },
-    {
-      "slug": "modal", "name": "Modal", "figmaId": "...",
-      "category": "modal", "description": "...",
-      "implemented": false,
-      "tokens": [{ "property": "background", "token": "--surface-secondary", "value": "#222" }, ...]
-    }
-  ]
-}
-```
-
-If `--latest` was passed (or argument is `sync`), first fetch the canonical JSON:
-```
-WebFetch: https://trdr.mrocontent.com.br/components.json
-```
-And overwrite `data/components.json` in the skill directory before continuing.
-
-If both the local snapshot and the Hub fail → STOP with:
-> ❌ Could not load TRDR component catalog (local snapshot missing AND Hub unreachable). Aborting. Run `npm run sync` in the trdr-plugins repo to refresh the snapshot.
-
-Use the loaded data throughout the rest of the workflow. Track:
-- `implementedSlugs` = list of `c.slug` where `c.implemented === true`
-- `stubSlugs` = list of `c.slug` where `c.implemented !== true`
-
-### Step 5 — Present the migration plan and STOP
-
-Output the following report and **do not proceed** until the developer explicitly approves.
-
-All projects use the same checkpointed 4-sub-phase execution regardless of size. This prevents context overload and hallucinations for any project, small or large.
-
-```markdown
-## TRDR Design System — Migration Plan
-
-### Project: [framework] | [language] | [styling approach]
-### Catalog: TRDR DS v[version] (generated [generatedAt])
-### Coverage: [implemented]/[total] components implemented
-
----
-
-### Conformance score: [X]% compliant
-(Percentage of style files with zero hardcoded violations)
-
----
-
-### FILES TO CREATE:
-- [ ] `[detected-styles-dir]/tokens.css` — TRDR CSS custom properties (dark + light mode)
-- [ ] `[detected-styles-dir]/components.css` — TRDR utility classes (.trdr-btn, .trdr-card, etc.)
-- [ ] `CLAUDE.md` (project root) — design system rules for Claude Code
-- [ ] `MISSING_COMPONENTS.md` (only if stubs are referenced) — pending implementations
-
-### FILES TO MODIFY:
-- [ ] `[global-css-file]` — add @import for tokens.css and components.css
-[list each file with violations, e.g.:]
-- [ ] `src/components/Button.css` — 3 violations (hardcoded colors: #00A8CC, #0E0E0E, #FFFFFF)
-- [ ] `src/app/globals.css` — 2 violations (font-family: Inter)
-
-### VIOLATIONS FOUND:
-| Category | Count | Example |
-|----------|-------|---------|
-| A — Hardcoded colors | N | `color: #00A8CC` in Button.css:14 |
-| B — Hardcoded fonts | N | `font-family: Inter` in globals.css:8 |
-| C — Hardcoded spacing | N | `padding: 16px` in Card.css:22 |
-| D — Primitive token use | N | `var(--color-blue-600)` in Badge.css:31 |
-| E — Missing tokens.css | N | not imported in globals.css |
-| F — Hardcoded rgba | N | `background: rgba(0,0,0,.3)` in card.css:88 |
-| G — Custom gradients | N | `linear-gradient(135deg, #FF6B6B...)` in header:24 |
-| H — Hardcoded font-size | N | `font-size: 22px` in card.css:99 |
-| I — Inline styles | N | `style="color:#00D4FF"` in index.html:312 |
-| J — SVG icons inline | N | `<svg>` in index.html (search, close, play icons) |
-| K — Logo incorrect/missing | N | `<span>TRDR</span>` used as logo in index.html:45 |
-
-### TRDR COMPONENTS — IMPLEMENTATION PLAN:
-(Candidatos detectados no Step 3.5 — com classificação de complexidade)
-
-#### Simple swaps (substituição completa pelo componente DS):
-| Componente | Variante DS | Arquivo | Conteúdo atual |
-|------------|------------|---------|----------------|
-[For each candidate where classification === 'simple':]
-| [c.name] | [suggestedDsVariant] | [file:line] | "[existingContent]" |
-
-#### Complex-preservable (estrutura DS + lógica preservada):
-| Componente | Arquivo | Handlers/Props preservados |
-|------------|---------|----------------------------|
-[For each candidate where classification === 'complex-preservable':]
-| [c.name] | [file:line] | [existingHandlers], [existingProps] |
-
-#### Manual review (complexidade alta — sem modificação automática):
-| Componente | Arquivo | Motivo |
-|------------|---------|--------|
-[For each candidate where classification === 'complex-manual':]
-| [c.name] | [file:line] | [reason] |
-
-> **Simple:** substituição completa, conteúdo adaptado do projeto.
-> **Complex-preservable:** estrutura DS aplicada, toda lógica (handlers, bindings, conditionals) preservada.
-> **Manual:** flagged em DS_MIGRATION.md para revisão pelo desenvolvedor.
-
-#### Stubs e catálogo:
-| Componente | Status no catálogo | Arquivos detectados |
-|------------|--------------------|---------------------|
-[For each entry in replacementCandidates[], look up the slug in the loaded catalog:]
-[If c.implemented === true:]
-| [c.name] | ✅ implementado | [list of file:line from Step 3.5] |
-[If c.implemented === false:]
-| [c.name] | ⚠️ stub (figmaId [c.figmaId]) | [list of file:line] — receberá banner comment |
-[If replacementCandidates is empty:]
-| — | Nenhum candidato detectado | — |
-
-> **Implementados:** o CSS estará em `components.css` após a Fase 2, **E** as classes DS serão aplicadas diretamente nos elementos HTML/JSX/Vue durante o Step 6 — não é necessária nenhuma ação manual.
-> **Stubs:** receberão banner comment com tokens recomendados + entrada em `MISSING_COMPONENTS.md`.
-
-[If `stylingMode === 'mui'`:]
-
-### MUI THEME INTEGRATION PLAN:
-| Area | Current state | Action |
-|------|--------------|--------|
-| palette | [N] hardcoded hex values | Replace with `var(--token)` references |
-| typography | [N] hardcoded font values | Map to DS font tokens |
-| shape | borderRadius: [value] | Map to DS radius token |
-| components | [N] MUI components detected | Generate/update styleOverrides with DS tokens |
-| sx props | [N] files with hardcoded sx values | Migrate to token references |
-| styled() | [N] styled(MuiComponent) calls | Migrate to token references |
-
-**Theme file:** `[themeFilePath]`
-**MUI version:** [muiVersion]
-**CSS Variables mode:** [yes/no — if no, will be recommended for MUI v6+]
-**ThemeProvider:** [found at file:line / not found — will need manual setup]
-
-> **Note:** MUI projects receive DS tokens via the theme object. Sub-fase A creates `tokens.css` AND updates the MUI theme to reference those tokens via `var()`. Sub-fase C generates `styleOverrides` for each detected MUI component instead of swapping HTML tags.
-
-### SCOPE ESTIMATE: [Small / Medium / Large]
-Small = <10 violations | Medium = 10–50 | Large = 50+
-
-### ⚙️ EXECUTION MODE
-Phase 2 runs in **4 sub-phases with checkpoints** — always, regardless of project size.
-Sub-fase B (violations) processes **5 files/batch** to prevent context overload.
-
-~[ceil(total_files_with_violations/5)] violation batches estimated.
-Progress saved to `DS_PROGRESS.md` — resumable anytime with `/trdr-ds resume`.
-
-To change batch size: reply with `"Apply, batch 10"` or `"Apply, batch 3"`.
-
-### LOGOS:
-[If logoAudit.correct.length > 0:]
-| ✅ [file] | Official TRDR logo — no action needed |
-
-[If logoAudit.wrong.length > 0:]
-| ❌ [file] | Wrong logo — will be replaced with the official TRDR logo |
-
-[If logoAudit.unknown.length > 0:]
-| ⚠️ [file] | Could not verify — manual check recommended |
-
-[If no logo files found AND public/ exists:]
-> ℹ️ No logo file detected. The official TRDR logo will be copied to `public/logo-trdr.svg`.
-
-[If no logo files found AND no public/ exists:]
-> ℹ️ No logo file detected. Specify a path to add the official TRDR logo, or skip.
-
-### WHAT WILL NOT BE TOUCHED:
-- Correct TRDR logo files (already match the official reference)
-- Images, fonts, non-SVG assets
-- node_modules/, .next/, dist/, build/, out/
-- Third-party library files
-- Any file you explicitly exclude
-
----
-
-**Reply with one of:**
-- `"Apply"` or `"Executar"` — proceed with everything above
-- `"Apply, batch [N]"` — proceed with custom violation batch size (default: 5)
-- `"Apply, skip [file or directory]"` — proceed but exclude specific paths
-- `"Only tokens"` — only create tokens.css, components.css, and CLAUDE.md (no violation fixes)
-- `"Change [detail]"` — adjust a specific part of the plan before executing
-- `"Sync first"` — pull the latest catalog from the Hub before applying
-```
-
-### Step 5.5 — Write DS_ANALYSIS.md (MANDATORY before stopping)
-
-Before presenting the plan to the developer and before any STOP, write `DS_ANALYSIS.md` to the **project root** with the complete analysis captured in Steps 1–4. This file is the context anchor for all Phase 2 sub-phases — they will read it instead of relying on conversation history.
-
-```markdown
-# TRDR DS — Analysis
-Generated: [ISO datetime]
-Skill version: [X.Y.Z]
-
-## Project
-Framework: [next.js|react|vue|html]
-Language: [ts|js]
-Styling: [css-modules|tailwind|plain-css|css-in-js|mui]
-Global CSS file: [path]
-Styles dir: [detected-styles-dir]
-[If stylingMode === 'mui':]
-MUI version: [muiVersion]
-Theme file: [themeFilePath]
-Has ThemeProvider: [yes/no]
-MUI CSS Variables mode: [yes/no]
-Files with sx props: [count]
-Files with styled(Mui*): [count]
-
-## Violations Summary
-Total violations: [total_violations]
-Total files with violations: [total_files_with_violations]
-
-### By Category
-| Cat | Type | Count | Files |
-|-----|------|-------|-------|
-| A | Hardcoded colors | N | file1.css, file2.jsx |
-| B | Hardcoded font-family | N | ... |
-| C | Hardcoded px spacing | N | ... |
-| D | Primitive token use | N | ... |
-| E | Missing tokens.css | N | ... |
-| F | Hardcoded rgba | N | ... |
-| G | Custom gradients | N | ... |
-| H | Hardcoded font-size | N | ... |
-| I | Inline styles | N | ... |
-| J | SVG icons inline | N | ... |
-| K | Logo incorrect/missing | N | ... |
-[If stylingMode === 'mui':]
-| L | MUI theme hardcoded values | N | theme.ts |
-| M | MUI sx prop hardcoded values | N | Component1.tsx, Component2.tsx |
-| N | styled(MuiComponent) hardcoded values | N | StyledButton.tsx |
-
-### By File
-[For each file with violations:]
-#### [file path]
-- A: [value] (line [N]), [value] (line [N])
-- C: [value] (line [N])
-- I: [value] (line [N])
-[list all violations with line numbers]
-
-## Component Replacement Candidates
-
-### Simple swaps (full DS component replacement)
-[For each candidate where classification === 'simple':]
-| Component | DS Variant | File | Existing Content |
-|-----------|-----------|------|------------------|
-| [c.name] | [suggestedDsVariant] | [file:line] | "[existingContent]" |
-
-### Complex-preservable (DS structure + preserved logic)
-[For each candidate where classification === 'complex-preservable':]
-| Component | File | Handlers/Props Preserved |
-|-----------|------|--------------------------|
-| [c.name] | [file:line] | [existingHandlers], [existingProps] |
-
-### Manual review required
-[For each candidate where classification === 'complex-manual':]
-| Component | File | Reason |
-|-----------|------|--------|
-| [c.name] | [file:line] | [brief description of why it's complex] |
-
-### Stubs (not yet implemented in DS)
-[For each candidate where c.implemented === false:]
-- [slug]: [file:line] — ⚠️ stub (figmaId: [c.figmaId])
-
-### Dependency Graph
-[For each candidate with non-empty dependencies in components.json:]
-| Compound Component | Dependencies (install first) |
-|--------------------|----------------------------|
-| [c.name] | [c.dependencies.join(', ')] |
-
-[If no compound components among candidates:]
-> All candidates are atomic — no dependency ordering needed.
-
-## Logo Audit
-[For each file in logoAudit.correct:] - [path] — ✅ CORRECT
-[For each file in logoAudit.wrong:] - [path] — ❌ WRONG (will be replaced)
-[For each file in logoAudit.unknown:] - [path] — ⚠️ UNKNOWN
-
-## Execution Plan
-Batch size: [N] (default 5)
-[Group files by folder, max batch_size files per batch:]
-### Batch 1 — [folder/] ([N] files)
-- [file1]
-- [file2]
-### Batch 2 — [folder/] ([N] files)
-- ...
-```
-
-### Step 5.6 — Generate SPRINT_PLAN.md
-
-After writing `DS_ANALYSIS.md`, generate `SPRINT_PLAN.md` at the project root. This file breaks the entire migration into **self-contained sprints** — each sprint can be executed in an independent conversation with a clean context window.
-
-**Sprint sizing rules:**
-- Each sprint should process at most **15 files** (keeps context comfortable even for complex files)
-- Group files by **folder** (natural boundary — violations in the same folder share CSS patterns)
-- If a folder has >15 files, split into sub-sprints (e.g., `Sprint 3a`, `Sprint 3b`)
-- Foundation, Components, and Final are each their own sprint (regardless of file count)
-
-**Generate the plan:**
-
-```markdown
-# TRDR DS — Sprint Plan
-Generated: [ISO datetime]
-Project: [project name]
-Total sprints: [N]
-Estimated context windows: [N] (one per sprint + one for this analysis)
-
-> Cada sprint é independente. Entre sprints, você pode limpar o contexto (`/clear`) ou iniciar uma nova conversa.
-> Para continuar: `/trdr-ds resume`
-
----
-
-## Sprint 1 — Foundation
-[If stylingMode !== 'mui':]
-**Scope:** Create tokens.css, components.css, CLAUDE.md, @import in global CSS
-[If stylingMode === 'mui':]
-**Scope:** Create tokens.css, components.css, CLAUDE.md, @import in global CSS, AND generate/update MUI theme with DS token references (palette, typography, shape)
-**Sub-fase:** A
-**Files to create:** 3 (tokens.css, components.css, CLAUDE.md)
-[If stylingMode === 'mui':]
-**Files to modify:** 2 (global CSS, [themeFilePath])
-[else:]
-**Files to modify:** 1 (global CSS)
-**Status:** PENDING
-
----
-
-## Sprint 2 — Violations: [first-folder/]
-**Scope:** Fix [N] violations in [M] files
-**Sub-fase:** B
-**Files:** [list each file path]
-**Violation count:** [N] (A:[n], B:[n], C:[n], ...)
-**Status:** PENDING
-
----
-
-## Sprint 3 — Violations: [second-folder/]
-**Scope:** Fix [N] violations in [M] files
-**Sub-fase:** B
-**Files:** [list each file path]
-**Violation count:** [N]
-**Status:** PENDING
-
----
-
-[... repeat for each folder/batch ...]
-
----
-
-## Sprint [N-1] — Components
-[If stylingMode !== 'mui':]
-**Scope:** Implement DS components ([S] simple, [P] complex-preservable, [M] manual review)
-**Candidates:** [total]
-**Install order:** [topological order from dependency graph — atomics first, then compounds]
-[If stylingMode === 'mui':]
-**Scope:** Generate MUI theme component styleOverrides for [N] detected MUI components, migrate [M] sx prop violations
-**Candidates:** [total MUI components]
-**Sub-fase:** C
-**Status:** PENDING
-
----
-
-## Sprint [N] — Final
-**Scope:** Replace logos, replace SVG icons with Material Icons (size-preserved), generate DS_MIGRATION.md
-**Sub-fase:** D
-**Status:** PENDING
-```
-
-**Sprint naming convention:**
-- Foundation sprints: `Sprint 1 — Foundation`
-- Violation sprints: `Sprint N — Violations: [folder/]`
-- If folder split: `Sprint Na — Violations: [folder/] (part 1 of 2)`
-- Component sprint: `Sprint N — Components`
-- Final sprint: `Sprint N — Final`
-
-After writing `SPRINT_PLAN.md`, update the output to include the sprint summary:
-
-```
-✅ DS_ANALYSIS.md e SPRINT_PLAN.md salvos.
-
-📋 Sprint Plan: [N] sprints planejados
-  Sprint 1: Foundation (4 arquivos)
-  Sprint 2-[M]: Violations ([total_files] arquivos em [folders] pastas)
-  Sprint [M+1]: Components ([candidates] candidatos)
-  Sprint [N]: Final (logos + ícones + DS_MIGRATION.md)
-
-Cada sprint é independente — entre sprints, limpe o contexto com /clear.
-Para continuar de qualquer ponto: /trdr-ds resume
-
-Responda 'Apply' para iniciar o Sprint 1.
-```
-
-**STOP HERE. Wait for explicit developer approval before Phase 2.**
-
----
-
-## PHASE 2: EXECUTION (only after explicit approval)
-
-Parse the developer's reply:
-- Extract batch size override from `"Apply, batch N"` → use N; otherwise default to **5**.
-- Extract skip paths from `"Apply, skip [path]"` → exclude those from violation processing.
-- `"Only tokens"` → skip Sub-fases B and C (no violation fixes, no component banners).
-
-### Sprint execution model
-
-Each sprint is a **self-contained unit of work** designed to fit comfortably in a single context window. The developer can `/clear` or start a new conversation between sprints and resume with `/trdr-ds resume`.
-
-**Context rule (critical):** At the start of EVERY sprint, before doing anything else:
-1. Read `SPRINT_PLAN.md` from the project root — find the current sprint (first with `Status: PENDING` or `Status: IN_PROGRESS`)
-2. Read `DS_ANALYSIS.md` from the project root — but ONLY the sections relevant to the current sprint's scope (e.g., for a violation sprint, only read the `§ By File` entries for the files listed in that sprint)
-3. Read `DS_PROGRESS.md` from the project root — this is the canonical source of progress state
-
-**Never read the entire DS_ANALYSIS.md at once for large projects.** Only read the sections needed for the current sprint. This prevents context overflow.
-
-Never rely on conversation memory for violation counts, file paths, batch assignments, or framework detection. Always re-read from files.
-
-**Sprint lifecycle:**
-1. Read state files (SPRINT_PLAN.md + relevant sections of DS_ANALYSIS.md + DS_PROGRESS.md)
-2. Update SPRINT_PLAN.md: set current sprint `Status: IN_PROGRESS`
-3. Execute the sprint's scope (Foundation / Violations for specific files / Components / Final)
-4. Update DS_PROGRESS.md with results
-5. Update SPRINT_PLAN.md: set current sprint `Status: ✅ COMPLETE`
-6. Output sprint summary with next sprint info
-7. **STOP** — wait for developer to continue or `/clear` + `/trdr-ds resume`
-
-**End-of-sprint output (MANDATORY after every sprint):**
-```
-✅ Sprint [N] completo — [sprint name]
-[Brief summary of what was done: files modified, violations fixed, components applied, etc.]
-
-📋 Progresso: [done]/[total] sprints ([percentage]%)
-Próximo: Sprint [N+1] — [next sprint name]
-
-→ Você pode limpar o contexto agora: /clear
-→ Para continuar: /trdr-ds resume
-→ Para ver status completo: /trdr-ds status
-```
-
-Report progress after each major step within a sprint.
-
-### Step 0 — Initialize checkpoint
-
-**Create `DS_PROGRESS.md` at the project root** (always — no size threshold):
-
-```markdown
-# TRDR DS Migration — Progress
-Started: [ISO datetime]
-Project: [project name from package.json]
-Batch size: [N]
-Status: IN_PROGRESS
-Backup branch: [branch-name or NONE]
-Original branch: [branch-name]
-Sprint plan: SPRINT_PLAN.md
-Current sprint: 1
-
-## Sub-fase A: Foundation — PENDING
-- [ ] tokens.css
-- [ ] components.css
-- [ ] CLAUDE.md
-- [ ] @import no CSS global
-
-## Sub-fase B: Violations — PENDING
-Total de arquivos com violações: [total_files_with_violations]
-Total de violações: [total_violations]
-Total de lotes: [N]
-
-[For each batch from DS_ANALYSIS.md § Execution Plan:]
-### Lote 1 — [folder/] ([N] arquivos) — PENDING
-### Lote 2 — [folder/] ([N] arquivos) — PENDING
-...
-### Lote [n] — raiz ([N] arquivos) — PENDING
-
-## Sub-fase C: Components — PENDING
-Install order: [topological — atomics first, then compounds by dependency]
-[list component replacement candidates from DS_ANALYSIS.md]
-
-## Sub-fase D: Final — PENDING
-- [ ] logos incorretos substituídos
-- [ ] DS_MIGRATION.md gerado
-
-## Padrões Sem Token (revisão manual)
-[empty — filled during execution]
-
-## Execution Log
-[Each action appends a row here — this is the canonical audit trail for the report]
-```
-
-**Execution Log rule (applies to ALL sub-phases):**
-
-After every file creation or modification by the skill, append a row to the `## Execution Log` section of `DS_PROGRESS.md`:
-
-```
-| [ISO datetime] | [sub-phase] | [action] | [file path] | [details] |
-```
-
-Actions: `CREATE`, `MODIFY`, `SKIP`, `FAIL`
-
-Examples:
-```
-| 2026-05-14T10:23:01 | A | CREATE | src/styles/tokens.css | 292 CSS variables (dark+light) |
-| 2026-05-14T10:23:02 | A | CREATE | src/styles/components.css | 25 component classes + typography |
-| 2026-05-14T10:23:03 | A | MODIFY | src/styles/globals.css | @import tokens.css + components.css |
-| 2026-05-14T10:23:04 | A | CREATE | CLAUDE.md | DS context for Claude Code |
-| 2026-05-14T10:25:11 | B | MODIFY | src/components/Header.tsx | 5 violations fixed: A(3), C(2) |
-| 2026-05-14T10:25:12 | B | MODIFY | src/components/Card.css | 3 violations fixed: A(1), B(2) |
-| 2026-05-14T10:25:13 | B | SKIP | src/legacy/old.css | 0 violations — already compliant |
-| 2026-05-14T10:30:01 | C | MODIFY | src/components/Button.tsx | simple swap → .trdr-btn |
-| 2026-05-14T10:30:02 | C | FAIL | src/components/Modal.tsx | stub — not yet implemented in DS |
-| 2026-05-14T10:35:01 | D | MODIFY | public/logo.svg | replaced with logo-trdr.svg |
-| 2026-05-14T10:35:02 | D | CREATE | DS_MIGRATION.md | manual checklist generated |
-```
-
-This log is cumulative — never clear it. Each `/trdr-ds resume` session appends to the existing log.
-
-### Step 0.5 — Git backup (safety net)
-
-Before modifying any project file, create a git backup so the entire migration can be rolled back.
-
-**Step 0.5a — Check git status:**
-
-Run via Bash:
-```bash
-git rev-parse --is-inside-work-tree 2>/dev/null
-```
-
-**If NOT a git repo:**
-```
-⚠️ Este projeto não tem repositório git. Um backup automático não é possível sem git.
-
-Responda:
-- "git init" — inicializar repositório git e criar backup antes de continuar
-- "continuar sem backup" — prosseguir sem safety net (irreversível)
-```
-**STOP. Wait for reply.**
-
-If reply is `"git init"`:
-1. Run: `git init`
-2. Run: `git add -A && git commit -m "Initial commit (before TRDR DS migration)"`
-3. Continue to Step 0.5b.
-
-If reply is `"continuar sem backup"`:
-- Update `DS_PROGRESS.md`: set `Backup branch: NONE (user opted out)`
-- Skip to Sub-fase A.
-
-**If IS a git repo:** Continue to Step 0.5b.
-
-**Step 0.5b — Check for existing backup branch:**
-
-Run via Bash:
-```bash
-git branch --list "trdr-ds/backup-*"
-```
-
-If one or more `trdr-ds/backup-*` branches exist:
-```
-⚠️ Backup branch(es) encontrado(s) de execução anterior:
-[list each branch name]
-
-Responda:
-- "manter" — criar novo backup com timestamp diferente (mantém os anteriores)
-- "substituir" — apagar o backup anterior e criar um novo
-```
-**STOP. Wait for reply.**
-
-If `"substituir"`: delete all existing `trdr-ds/backup-*` branches via `git branch -D [name]` for each.
-
-**Step 0.5c — Create the backup branch:**
-
-1. Record the current branch name:
-   ```bash
-   git branch --show-current
-   ```
-   Save as `originalBranch`. If in detached HEAD state (empty output), save the commit hash via `git rev-parse HEAD` instead.
-
-2. Generate timestamp branch name: `trdr-ds/backup-{YYYY-MM-DD-HHmmss}` (use current local time).
-
-3. Check for uncommitted changes:
-   ```bash
-   git status --porcelain
-   ```
-   If output is non-empty (uncommitted changes exist):
-   ```bash
-   git stash push -m "trdr-ds-pre-migration-stash"
-   ```
-
-4. Create the backup branch from current HEAD:
-   ```bash
-   git branch trdr-ds/backup-{timestamp}
-   ```
-
-5. If stash was created in step 3, pop it back:
-   ```bash
-   git stash pop
-   ```
-
-6. Update `DS_PROGRESS.md`:
-   ```
-   Backup branch: trdr-ds/backup-{timestamp}
-   Original branch: {originalBranch}
-   ```
-
-7. Output:
-   ```
-   ✅ Backup criado: branch `trdr-ds/backup-{timestamp}`
-   Para desfazer toda a migração a qualquer momento: `/trdr-ds rollback`
-   ```
-
----
-
-## Sub-fase A: Foundation
-
-> **Before starting:** Read `DS_ANALYSIS.md` and `DS_PROGRESS.md` from the project root.
-
-Update `DS_PROGRESS.md`: set `Sub-fase A: Foundation — IN_PROGRESS`.
-
-### Step 1 — Create tokens.css
-
-Copy the local snapshot verbatim:
-
-```
-Read: <skill-dir>/references/tokens.css
-Write: <project>/<detected-styles-dir>/tokens.css
-```
-
-Do NOT regenerate the file. Do NOT inline tokens from any other source. The snapshot is authoritative.
-
-If `references/tokens.css` is missing in the skill directory:
-1. Try `WebFetch: https://trdr.mrocontent.com.br/tokens.css`, save it to the skill dir, then proceed.
-2. If the Hub is also unreachable → STOP with error message asking the maintainer to run `npm run sync`.
-
-Update `DS_PROGRESS.md`:
-```
-- [x] tokens.css — [path]/tokens.css ([ISO datetime])
-```
-
-### Step 2 — Create components.css
-
-Build `components.css` by concatenating the `.code.css` block of every implemented component plus the typography utility classes.
-
-```
-For each c in components where c.implemented === true:
-  append c.code.css to components.css (with a "/* === <c.name> === */" header)
-```
-
-After all component CSS blocks, append the text style utility classes:
-
-```css
-/* ==========================================================================
-   TRDR Design System — Text Style Utility Classes
-   ========================================================================== */
-
-/* Headings — var(--font-primary) = JetBrains Mono */
-.trdr-h1 { font-family: var(--font-primary); font-size: 80px; font-weight: 500; line-height: 1.1; }
-.trdr-h2 { font-family: var(--font-primary); font-size: 56px; font-weight: 500; line-height: 1.1; }
-.trdr-h3 { font-family: var(--font-primary); font-size: 46px; font-weight: 700; line-height: 1.15; }
-.trdr-h4 { font-family: var(--font-primary); font-size: 38px; font-weight: 500; line-height: 1.15; }
-.trdr-h5 { font-family: var(--font-primary); font-size: 32px; font-weight: 500; line-height: 1.2; }
-.trdr-h6 { font-family: var(--font-primary); font-size: 26px; font-weight: 500; line-height: 1.2; }
-.trdr-h7 { font-family: var(--font-secondary); font-size: 22px; font-weight: 600; line-height: 1.3; }
-
-/* Body — var(--font-secondary) = Inter */
-.trdr-body-b1  { font-family: var(--font-secondary); font-size: 18px; font-weight: 400; line-height: 1.6; }
-.trdr-body-b2  { font-family: var(--font-secondary); font-size: 16px; font-weight: 500; line-height: 1.5; }
-.trdr-body-b3  { font-family: var(--font-secondary); font-size: 14px; font-weight: 400; line-height: 1.5; }
-.trdr-body-b4  { font-family: var(--font-secondary); font-size: 12px; font-weight: 500; line-height: 1.4; letter-spacing: 0.2px; }
-.trdr-body-b5  { font-family: var(--font-secondary); font-size: 10px; font-weight: 400; line-height: 1.4; }
-.trdr-body-aux { font-family: var(--font-secondary); font-size: 12px; font-weight: 400; line-height: 1.4; letter-spacing: 0.24px; }
-
-/* Labels — var(--font-secondary) = Inter */
-.trdr-label-lg { font-family: var(--font-secondary); font-size: 16px; font-weight: 600; line-height: 1.4; }
-.trdr-label-l2 { font-family: var(--font-secondary); font-size: 16px; font-weight: 600; line-height: 1.4; }
-.trdr-label-l3 { font-family: var(--font-secondary); font-size: 14px; font-weight: 600; line-height: 1.4; }
-
-/* Mono — var(--font-mono) = Roboto Mono */
-.trdr-mono { font-family: var(--font-mono); font-size: 12px; font-weight: 400; line-height: 1.4; letter-spacing: 0.04em; }
-```
-
-Update `DS_PROGRESS.md`:
-```
-- [x] components.css — [path]/components.css ([ISO datetime])
-```
-
-### Step 3 — Update global CSS
-
-Find the main global CSS file (globals.css, main.css, index.css, app.css) and add at the very top:
-
-```css
-@import './tokens.css';
-@import './components.css';
-```
-
-Adjust the relative path if tokens.css is in a subdirectory.
-
-If the project already imports a different design system's variables and there are naming conflicts, warn the developer before proceeding.
-
-Update `DS_PROGRESS.md`:
-```
-- [x] @import — [global-css-file] ([ISO datetime])
-```
-
-### Step 4 — Create CLAUDE.md
-
-Create `CLAUDE.md` at the project root, populated dynamically from the catalog:
-
-- The list of "Pre-built component classes" must be generated from the loaded JSON's `implementedSlugs` and their CSS class prefixes (parse the first `.trdr-<prefix>` from each `c.code.css`).
-- The list of "Pending stubs" should mention the count of stubs and link to MISSING_COMPONENTS.md if generated.
-
-Template (replace `[…]` with actual values):
-
-```markdown
-# [Project Name] — Context for Claude Code
-
-## Design System
-This project uses the TRDR Design System.
-Reference Hub: https://trdr.mrocontent.com.br
-Local catalog: TRDR DS v[catalog-version] ([implemented]/[total] components)
-
-## Absolute Rules (never break these)
-1. NEVER use primitive tokens directly (--color-*, --space-*) — always use semantic tokens
-2. Backgrounds: --bg-primary (#0E0E0E), --bg-secondary (#141519), --bg-tertiary (#1A1A1A)
-3. Text: --content-primary (white), --content-secondary (#E8E8E8), --content-tertiary (#A4A4A4)
-4. Primary CTA: --action-brand-inverse-default (#005266) for filled buttons
-5. Fonts: --font-primary = JetBrains Mono (headings) | --font-secondary = Inter (body) | --font-mono = Roboto Mono (numbers)
-6. Spacing: always var(--spacing-xs/sm/md/lg/xl/2xl/3xl) — never hardcoded px
-7. Border radius: always var(--radius-sm/md/lg/full) — never hardcoded px
-8. Text styles: use .trdr-h1/.../h7, .trdr-body-b1/.../b5, .trdr-label-l2/l3 — never raw font-size px
-9. No colors outside the DS anywhere — rgba(), inline gradients, hardcoded hex all require a semantic token. No exceptions.
-
-## Token files
-- Tokens: [detected-path]/tokens.css
-- Components: [detected-path]/components.css
-
-## Quick reference — most used tokens
-| Token | CSS Variable | Value |
-|-------|-------------|-------|
-| Background | --bg-primary | #0E0E0E |
-| Surface | --surface-secondary | #222222 |
-| Text primary | --content-primary | #FFFFFF |
-| Text secondary | --content-tertiary | #A4A4A4 |
-| Brand (text/icon) | --content-brand | #00A8CC |
-| Primary button | --action-brand-inverse-default | #005266 |
-| Border | --border-default | #4A4A4A |
-| Focus ring | --border-focus | #00D4FF |
-| Success | --content-success | #4FE290 |
-| Error | --content-error | #F34F45 |
-| Warning | --content-warning | #FFCC40 |
-
-## Implemented components
-[Generate from catalog: list each implemented component as a row "slug — figmaId — Hub URL"]
-
-## Pending components (stubs)
-[N] components in the catalog have no canonical code yet. When using one of these, the skill applies tokens and a banner comment, then logs the gap in MISSING_COMPONENTS.md. See https://trdr.mrocontent.com.br/componentes for status.
-
-## Layer hierarchy
-bg.primary (base) → bg.secondary/tertiary (content areas) → surface.* (cards, panels)
-→ interactive components → overlays/modals/tooltips
-
-## Inline Styles
-- **NUNCA** usar `style=""` ou `style={{}}` com propriedades de design (color, background, font, padding, margin, border)
-- Exceção aceita: `background-image: url(...)` para URLs de imagem dinâmicas de dados externos
-- Exceção aceita: `style="--css-var: valor"` para passar valores dinâmicos ao CSS (ex: `style="--card-delay:0.1s"`)
-- Para `animation-delay` calculado: use `style="--delay: Xs"` + CSS `animation-delay: var(--delay, 0s)`
-- Todos os outros valores de design devem vir de classes CSS com tokens TRDR
-
-## Ícones
-- HTML/Vue: `<span class="material-icons mi-sm">nome</span>` via Google Fonts CDN
-- React: `<NomeIcon />` via @mui/icons-material
-- Cor: SEMPRE via classe CSS com token DS (`.icon-brand`, `.icon-success`, `.icon-dim`, etc.)
-- Tamanho: `.mi-2xs` (12px), `.mi-xs` (14px), `.mi-sm` (16px), default (20px), `.mi-lg` (24px), `.mi-xl` (28px), `.mi-2xl` (32px)
-- Para tamanhos não padrão: `style="font-size:Npx"` (aceito APENAS para font-size de ícones, nunca para cor)
-- **NUNCA** usar `<svg>` inline para ícones
-- **NUNCA** usar `style=""` para cor de ícones
-
-## Logo
-- HTML: `<img src="logo-trdr.svg" alt="TRDR" height="24">`
-- Next.js: `<Image src="/logo-trdr.svg" alt="TRDR" width={105} height={41} />`
-- Vue: `<img src="/logo-trdr.svg" alt="TRDR" :height="24">`
-- Inline SVG: usar o conteúdo de `references/logo-trdr.svg` (viewBox="0 0 105 41", fill="#00D4FF")
-- **NUNCA** usar texto ("TRDR" em `<span>`) como logo
-- **NUNCA** usar outro arquivo SVG que não seja logo-trdr.svg
-
-[If `stylingMode === 'mui'`, add this section to CLAUDE.md:]
-
-## MUI Theme Integration
-This project uses Material UI with TRDR DS tokens integrated via the theme.
-
-### Rules
-1. NEVER hardcode colors in palette, sx props, or styleOverrides — always use `var(--token)`
-2. Theme file (`[themeFilePath]`) is the single source for MUI component styling — do not override via individual sx props unless necessary for one-off layout adjustments
-3. When adding new MUI components: check if a styleOverride exists in the theme's `components` section. If not, add one using DS tokens.
-4. sx props: acceptable for layout (padding, margin, display, flex) using DS spacing tokens. NOT acceptable for colors, fonts, or borders with hardcoded values.
-5. styled(MuiComponent): use `'var(--token)'` for all design values
-6. Typography: use MUI variants (h1-h6, body1, body2, etc.) — they are mapped to TRDR DS text styles in the theme
-7. tokens.css is the source of truth — the MUI theme references tokens via `var(--token)` strings
-```
-
-Update `DS_PROGRESS.md`:
-```
-- [x] CLAUDE.md — CLAUDE.md ([ISO datetime])
-```
-
-### Step 5 — Generate/update MUI theme with DS tokens (only when `stylingMode === 'mui'`)
-
-This step creates the bridge between `tokens.css` (CSS variables source of truth) and MUI's theme system. MUI components read from the theme object, so tokens must be explicitly referenced there via `var()`.
-
-**Step 5a — Ensure tokens.css is imported:**
-The `@import './tokens.css'` added in Step 3 makes CSS variables available to MUI's Emotion runtime. This is sufficient — Emotion styles CAN reference `var(--token)` in string values.
-
-**Step 5b — Create or update the MUI theme file:**
-
-If `themeFilePath` exists: READ the entire existing theme file. Preserve all non-DS customizations (breakpoints, transitions, zIndex, custom component logic, defaultProps, variants).
-
-If `themeFilePath` does NOT exist: Create a new theme file at `src/theme.ts` (or `src/theme/index.ts` if a `theme/` directory exists).
-
-Generate/update the theme with DS token references:
-
-```typescript
-import { createTheme } from '@mui/material/styles';
-
-const theme = createTheme({
-  // cssVariables: true, — recommended for MUI v6+ (enables native CSS variable support)
-  palette: {
-    mode: 'dark',
-    primary: {
-      main: 'var(--action-brand-default)',        // #00D4FF
-      dark: 'var(--action-brand-active)',          // #007D99
-      contrastText: 'var(--content-inverse)',      // #1A1A1A
-    },
-    secondary: {
-      main: 'var(--action-secondary-default)',     // #4A4A4A
-      dark: 'var(--action-secondary-active)',      // #A4A4A4
-      contrastText: 'var(--content-primary)',      // #FFFFFF
-    },
-    error: {
-      main: 'var(--content-error)',                // #F34F45
-    },
-    warning: {
-      main: 'var(--content-warning)',              // #FFCC40
-    },
-    success: {
-      main: 'var(--content-success)',              // #4FE290
-    },
-    info: {
-      main: 'var(--content-info)',                 // #CCFDFF
-    },
-    background: {
-      default: 'var(--bg-primary)',                // #0E0E0E
-      paper: 'var(--bg-secondary)',                // #141519
-    },
-    text: {
-      primary: 'var(--content-primary)',            // #FFFFFF
-      secondary: 'var(--content-secondary)',        // #E8E8E8
-      disabled: 'var(--content-disabled)',          // #4A4A4A
-    },
-    divider: 'var(--border-default)',               // #4A4A4A
-    action: {
-      hover: 'var(--surface-hover, rgba(255,255,255,0.08))',
-      selected: 'var(--surface-brand)',
-      disabled: 'var(--content-disabled)',
-      disabledBackground: 'var(--surface-disabled)',
-    },
-  },
-  typography: {
-    fontFamily: 'var(--font-secondary)',            // Inter
-    h1: { fontFamily: 'var(--font-primary)', fontSize: 80, fontWeight: 500, lineHeight: 1.1 },
-    h2: { fontFamily: 'var(--font-primary)', fontSize: 56, fontWeight: 500, lineHeight: 1.1 },
-    h3: { fontFamily: 'var(--font-primary)', fontSize: 46, fontWeight: 700, lineHeight: 1.15 },
-    h4: { fontFamily: 'var(--font-primary)', fontSize: 38, fontWeight: 500, lineHeight: 1.15 },
-    h5: { fontFamily: 'var(--font-primary)', fontSize: 32, fontWeight: 500, lineHeight: 1.2 },
-    h6: { fontFamily: 'var(--font-primary)', fontSize: 26, fontWeight: 500, lineHeight: 1.2 },
-    subtitle1: { fontFamily: 'var(--font-secondary)', fontSize: 22, fontWeight: 600, lineHeight: 1.3 },
-    body1: { fontFamily: 'var(--font-secondary)', fontSize: 16, fontWeight: 400, lineHeight: 1.5 },
-    body2: { fontFamily: 'var(--font-secondary)', fontSize: 14, fontWeight: 400, lineHeight: 1.5 },
-    caption: { fontFamily: 'var(--font-secondary)', fontSize: 12, fontWeight: 400, lineHeight: 1.4 },
-    overline: { fontFamily: 'var(--font-secondary)', fontSize: 10, fontWeight: 400, lineHeight: 1.4 },
-    button: { fontFamily: 'var(--font-secondary)', fontWeight: 600, textTransform: 'none' as const },
-  },
-  shape: {
-    borderRadius: 8,  // --radius-md = 8px — MUI shape.borderRadius must be numeric
-  },
-  components: {
-    // styleOverrides are generated in Sub-fase C
-  },
-});
-
-export default theme;
-```
-
-**MUI palette role → DS token mapping table:**
-
-| MUI palette key | DS token | Hex reference |
-|---|---|---|
-| `palette.primary.main` | `var(--action-brand-default)` | #00D4FF |
-| `palette.primary.dark` | `var(--action-brand-active)` | #007D99 |
-| `palette.primary.contrastText` | `var(--content-inverse)` | #1A1A1A |
-| `palette.secondary.main` | `var(--action-secondary-default)` | #4A4A4A |
-| `palette.secondary.dark` | `var(--action-secondary-active)` | #A4A4A4 |
-| `palette.error.main` | `var(--content-error)` | #F34F45 |
-| `palette.warning.main` | `var(--content-warning)` | #FFCC40 |
-| `palette.success.main` | `var(--content-success)` | #4FE290 |
-| `palette.info.main` | `var(--content-info)` | #CCFDFF |
-| `palette.background.default` | `var(--bg-primary)` | #0E0E0E |
-| `palette.background.paper` | `var(--bg-secondary)` | #141519 |
-| `palette.text.primary` | `var(--content-primary)` | #FFFFFF |
-| `palette.text.secondary` | `var(--content-secondary)` | #E8E8E8 |
-| `palette.text.disabled` | `var(--content-disabled)` | #4A4A4A |
-| `palette.divider` | `var(--border-default)` | #4A4A4A |
-
-**MUI typography variant → DS token mapping table:**
-
-| MUI variant | DS equivalent | Font family token |
-|---|---|---|
-| `h1` | `.trdr-h1` | `var(--font-primary)` — 80px/500 |
-| `h2` | `.trdr-h2` | `var(--font-primary)` — 56px/500 |
-| `h3` | `.trdr-h3` | `var(--font-primary)` — 46px/700 |
-| `h4` | `.trdr-h4` | `var(--font-primary)` — 38px/500 |
-| `h5` | `.trdr-h5` | `var(--font-primary)` — 32px/500 |
-| `h6` | `.trdr-h6` | `var(--font-primary)` — 26px/500 |
-| `subtitle1` | `.trdr-h7` | `var(--font-secondary)` — 22px/600 |
-| `body1` | `.trdr-body-b2` | `var(--font-secondary)` — 16px/500 |
-| `body2` | `.trdr-body-b3` | `var(--font-secondary)` — 14px/400 |
-| `caption` | `.trdr-body-b4` | `var(--font-secondary)` — 12px/500 |
-| `overline` | `.trdr-body-b5` | `var(--font-secondary)` — 10px/400 |
-| `button` | `.trdr-label-l3` | `var(--font-secondary)` — 14px/600 |
-
-**MUI shape/radius → DS token mapping table:**
-
-| Value (px) | DS token (for CSS) | MUI shape (numeric) |
-|---|---|---|
-| `0` | `var(--radius-none)` | `0` |
-| `2` | `var(--radius-xs)` | `2` |
-| `4` | `var(--radius-sm)` | `4` |
-| `8` | `var(--radius-md)` | `8` |
-| `12` | — (no DS token) | `12` |
-| `16` | `var(--radius-lg)` | `16` |
-| `20` | `var(--radius-xl)` | `20` |
-| `9999` | `var(--radius-full)` | `9999` |
-
-**Important MUI + CSS var() caveat:**
-MUI accepts string values for palette colors. `'var(--token)'` works for rendering in MUI v5+. However, MUI internally uses `palette.primary.main` for color calculations (alpha, lighten, darken). When `main` is a `var()` string, those calculations produce invalid CSS.
-
-**Solution by MUI version:**
-- **MUI v6+**: Add `cssVariables: true` to `createTheme()` — MUI handles CSS variables natively, calculations work
-- **MUI v5 / v7 without cssVariables mode**: Provide `main`, `light`, `dark`, and `contrastText` ALL explicitly using DS tokens. Do NOT rely on MUI's auto-generated `light`/`dark` variants. Document this caveat in `CLAUDE.md` and `DS_MIGRATION.md`.
-
-**Step 5c — Update DS_PROGRESS.md:**
-```
-- [x] MUI theme — [themeFilePath] (palette, typography, shape with DS tokens)
-```
-
-Update `DS_PROGRESS.md`: set `Sub-fase A: Foundation — ✅ COMPLETE`.
-
-Output:
-```
-[If stylingMode === 'mui':]
-✅ Sub-fase A completa — tokens.css, components.css, CLAUDE.md, @import e MUI theme criados/atualizados.
-
-[else:]
-✅ Sub-fase A completa — tokens.css, components.css, CLAUDE.md e @import criados.
-
-Próximo: Sub-fase B — Violations ([total_files_with_violations] arquivos em [N] lotes de até [batch_size] cada)
-Responda:
-- "continuar" / "continue" — iniciar Sub-fase B
-- "parar" / "stop" — salvar progresso e parar aqui
-- "não funcionou" / "report" — reportar problema ao maintainer
-```
-
-**STOP HERE. Wait for developer reply before starting Sub-fase B.**
-If the developer indicates the implementation didn't work (see DEVELOPER DISSATISFACTION DETECTION below), trigger REPORT MODE.
-
----
-
-## Sub-fase B: Violations
-
-> **Before starting:** Read `DS_ANALYSIS.md` (§ By File and § Execution Plan) and `DS_PROGRESS.md` (§ Sub-fase B) from the project root.
-
-Update `DS_PROGRESS.md`: set `Sub-fase B: Violations — IN_PROGRESS`.
-
-### Step 5 — Migrate violations
-
-Process one batch at a time, always with a STOP between batches. Batch assignments come from `DS_ANALYSIS.md` § Execution Plan. Maximum [batch_size] files per batch (default: 5).
-
-For each batch listed as PENDING in `DS_PROGRESS.md` § Sub-fase B:
-
-1. Update `DS_PROGRESS.md` — change batch status to `IN_PROGRESS`
-2. For each file in the batch:
-   - Apply all applicable violation fixes (see mapping tables below)
-   - Count violations fixed
-3. Update `DS_PROGRESS.md` — change batch status to `COMPLETED` with per-file detail:
-   ```
-   ### Lote [N] — [folder/] ([N] arquivos) — COMPLETED
-   Completed: [ISO datetime]
-   Violações corrigidas: [N] | Arquivos: [N]/[N]
-
-   | Arquivo | Violações | Categorias | Tokens aplicados |
-   |---------|-----------|------------|------------------|
-   | src/components/Header.tsx | 5 | A(3), C(2) | --content-brand, --spacing-md, --bg-primary |
-   | src/components/Card.css | 3 | A(1), B(2) | --surface-secondary, --font-primary, --font-secondary |
-   ```
-   Add any unfixable patterns to the "Padrões Sem Token" section of `DS_PROGRESS.md`.
-4. Output batch summary:
-   ```
-   ✅ Lote [N] concluído — [folder/] ([N] arquivos, [N] violações corrigidas)
-   Progresso geral: [done]/[total] lotes | [total_fixed] violações corrigidas
-   ```
-5. If more batches are PENDING:
-
-   **STOP HERE.** Output:
-   ```
-   Próximo: **Lote [N+1] — [folder/]** ([N] arquivos)
-   Responda:
-   - "continuar" / "continue" — processar próximo lote
-   - "pular [pasta]" — skip this folder and go to the next batch
-   - "parar" / "stop" — save progress and stop here (resume later with `/trdr-ds resume`)
-   - "tudo" / "all" — process all remaining batches without pausing
-   - "não funcionou" / "report" — reportar problema ao maintainer
-   ```
-   **Wait for developer reply.**
-
-   If reply is `"tudo"` / `"all"`: process all remaining batches without pausing (update DS_PROGRESS.md after each).
-   If reply is `"pular [pasta]"`: mark that batch as SKIPPED in DS_PROGRESS.md and move to the next.
-   If reply is `"parar"`: set `Status: PAUSED` in DS_PROGRESS.md. STOP. Do not proceed to Step 6 or 7.
-   If the developer indicates the implementation didn't work (see DEVELOPER DISSATISFACTION DETECTION below), trigger REPORT MODE.
-
-6. After ALL batches are COMPLETED (or skipped):
-
-   Update `DS_PROGRESS.md`: set `Sub-fase B: Violations — ✅ COMPLETE`.
-
-   Output:
-   ```
-   ✅ Sub-fase B completa — [total_violations_fixed] violações corrigidas em [total_files_with_violations] arquivos.
-
-   Próximo: Sub-fase C — Components ([N] candidatos a substituição)
-   Responda:
-   - "continuar" / "continue" — iniciar Sub-fase C
-   - "parar" / "stop" — salvar progresso e parar aqui
-   - "não funcionou" / "report" — reportar problema ao maintainer
-   ```
-
-   **STOP HERE. Wait for developer reply before starting Sub-fase C.**
-   If the developer indicates the implementation didn't work (see DEVELOPER DISSATISFACTION DETECTION below), trigger REPORT MODE.
-
----
-
-**Violation mapping tables (used in Step 5):**
-
-**Color mapping (hardcoded → semantic):**
-| Hardcoded value | Context | Replace with |
-|----------------|---------|-------------|
-| `#0E0E0E` | background | `var(--bg-primary)` |
-| `#141519` | background | `var(--bg-secondary)` |
-| `#1A1A1A` | background/surface | `var(--bg-tertiary)` or `var(--surface-tertiary)` |
-| `#222222` | surface/border | `var(--surface-secondary)` or `var(--border-subtle)` |
-| `#4A4A4A` | surface/border | `var(--surface-primary)` or `var(--border-default)` |
-| `#FFFFFF` | text/bg | `var(--content-primary)` or `var(--bg-inverse)` |
-| `#E8E8E8` | text | `var(--content-secondary)` |
-| `#A4A4A4` | text | `var(--content-tertiary)` |
-| `#00A8CC` | action/text brand | `var(--action-brand-default)` or `var(--content-brand)` |
-| `#005266` | button bg CTA | `var(--action-brand-inverse-default)` |
-| `#00D4FF` | focus/info | `var(--border-focus)` or `var(--content-info)` |
-| `#F34F45` | error/trading | `var(--content-error)` or `var(--context-trading-down)` |
-| `#4FE290` | success/trading | `var(--content-success)` or `var(--context-trading-up)` |
-| `#FFCC40` | warning | `var(--content-warning)` |
-| `#F57C00` | destructive | `var(--action-destructive-default)` |
-
-**Font mapping:**
-| Hardcoded | Replace with |
-|-----------|-------------|
-| `font-family: 'Inter'` or `font-family: 'Inter', -apple-system, ...` | `font-family: var(--font-secondary)` |
-| `font-family: 'JetBrains Mono'` or `font-family: 'JetBrains Mono', monospace` | `font-family: var(--font-primary)` |
-| `font-family: 'Space Grotesk'` | `font-family: var(--font-primary)` |
-| `font-family: 'Roboto Mono'` or `font-family: 'Roboto Mono', monospace` | `font-family: var(--font-mono)` |
-
-**Note:** System font fallbacks (`-apple-system`, `BlinkMacSystemFont`, `sans-serif`) are removed when replacing with a DS token. The token's value in tokens.css already defines the complete font stack including fallbacks — no manual fallback needed.
-
-**Spacing mapping:**
-| Hardcoded | Replace with |
-|-----------|-------------|
-| `4px` | `var(--spacing-xs)` |
-| `8px` | `var(--spacing-sm)` |
-| `12px` | `var(--spacing-md)` |
-| `16px` | `var(--spacing-lg)` |
-| `20px` | `var(--spacing-xl)` |
-| `24px` | `var(--spacing-2xl)` |
-| `32px` | `var(--spacing-3xl)` |
-| `0` / `0px` | Keep as `0` (no token needed) |
-| Any other value (48px, 64px, 96px, etc.) | **Keep the value as-is** — no DS token exists for it. Flag in DS_MIGRATION.md as "Custom spacing value: [Npx] in [file:line] — consider refactoring or proposing a new token in the Hub." Do NOT invent a `--spacing-4xl` or similar that doesn't exist in tokens.css. |
-
-**Multi-value spacing shorthands** (`padding: 16px 32px`, `margin: 12px 0 8px`):
-- Replace each value independently using the mapping above
-- Example: `padding: 16px 32px` → `padding: var(--spacing-lg) var(--spacing-3xl)`
-- Example: `margin: 12px 0 8px` → `margin: var(--spacing-md) 0 var(--spacing-sm)`
-- If one value has no token: replace only the mappable ones; keep the others as-is and flag
-
-**MUI sx spacing shorthand mapping** (only when `stylingMode === 'mui'`):
-
-When fixing violations in MUI `sx` props, MUI uses a numeric spacing multiplier (default 8px base). Use this mapping:
-
-| sx prop | MUI value | Pixels | DS token (for string replacement) |
-|---|---|---|---|
-| `p`, `m`, `gap`, etc. | `0.5` | 4px | `'var(--spacing-xs)'` |
-| `p`, `m`, `gap`, etc. | `1` | 8px | `'var(--spacing-sm)'` |
-| `p`, `m`, `gap`, etc. | `1.5` | 12px | `'var(--spacing-md)'` |
-| `p`, `m`, `gap`, etc. | `2` | 16px | `'var(--spacing-lg)'` |
-| `p`, `m`, `gap`, etc. | `2.5` | 20px | `'var(--spacing-xl)'` |
-| `p`, `m`, `gap`, etc. | `3` | 24px | `'var(--spacing-2xl)'` |
-| `p`, `m`, `gap`, etc. | `4` | 32px | `'var(--spacing-3xl)'` |
-
-Prefer keeping MUI numeric scale when the project consistently uses it (`p: 2`, `m: 1`). Only use `'var(--spacing-*)'` string replacement when the sx value uses hardcoded px string (e.g., `padding: '16px'` instead of `p: 2`).
-
-**MUI-specific violation processing** (only when `stylingMode === 'mui'`):
-
-In addition to standard A-K violations in CSS/JSX files, process these MUI-specific violations during batch processing:
-
-- **Category L** (theme file): Read the theme file. For each hardcoded `#hex`, font-family, fontSize, or borderRadius value, look up in the mapping tables and replace with `'var(--token)'`. If no DS token match exists, flag in DS_MIGRATION.md.
-- **Category M** (sx props): For each file with `sx={{}}` containing hardcoded values, replace colors with `'var(--token)'`, spacing with token or MUI scale, fonts with `'var(--font-*)'`, radius with `'var(--radius-*)'`.
-- **Category N** (styled() calls): For each `styled(MuiComponent)()` call with hardcoded values, replace with `'var(--token)'` in the style object.
-
-Theme files (Category L) should be processed in the FIRST violation batch, before component files, so that theme-level tokens are in place before scanning individual components.
-
-**Ambiguous colors:** Use property context to decide — `background-color` → bg/surface token, `color` → content token, `border-color` → border token, `accent-color` → action token.
-
-**Tailwind arbitrary value colors** (only when `stylingMode: tailwind`):
-
-Detect in `*.tsx, *.jsx, *.html, *.vue`:
-- Pattern: `(?:bg|text|border|ring|from|to|via|outline|fill|stroke)-\[#[0-9A-Fa-f]{3,8}\]`
-- Also detect `hover:`, `focus:`, `active:`, `dark:` prefixed variants
-
-Fix strategy — apply in order of preference:
-
-1. **DS class exists for element role → Opção A (DS class):**
-   Replace the arbitrary Tailwind classes with the DS class, keeping non-color utilities:
-   ```jsx
-   // Before
-   className="bg-[#005266] text-white px-4 py-2 rounded cursor-pointer"
-   // After
-   className="trdr-btn trdr-btn-primary px-4 rounded"
-   ```
-
-2. **No DS class, but color maps to DS token → Opção B (CSS var arbitrary):**
-   ```jsx
-   // Before
-   className="bg-[#1A1A1A] border border-[#222222]"
-   // After
-   className="bg-[var(--bg-tertiary)] border border-[var(--border-subtle)]"
-   ```
-   Token mapping (use same color → semantic table as CSS):
-   - `bg-[#0E0E0E]` → `bg-[var(--bg-primary)]`
-   - `bg-[#141519]` → `bg-[var(--bg-secondary)]`
-   - `bg-[#1A1A1A]` → `bg-[var(--bg-tertiary)]`
-   - `text-[#FFFFFF]` → `text-[var(--content-primary)]`
-   - `text-[#A4A4A4]` → `text-[var(--content-tertiary)]`
-   - `border-[#222222]` → `border-[var(--border-subtle)]`
-   - `border-[#4A4A4A]` → `border-[var(--border-default)]`
-   - `focus:border-[#00D4FF]` → `focus:border-[var(--border-focus)]`
-   - `text-[#4FE290]` → `text-[var(--context-trading-up)]`
-   - `text-[#F34F45]` → `text-[var(--context-trading-down)]`
-
-3. **Color has no DS token (e.g. `hover:bg-[#3DD980]`, `hover:bg-[#E03D3A]`):**
-   - Flag in DS_MIGRATION.md: "Custom hover color `#hex` — no DS token equivalent"
-   - Suggestion: replace with CSS hover effect: `hover:[filter:brightness(1.15)]` or use a utility class
-   - Do NOT invent a token or leave the hardcoded color silently
-
-**`accent-color` property:** Controls native checkbox/radio/range styling.
-- `accent-color: #00A8CC` → `accent-color: var(--action-brand-default)`
-- `accent-color: #4FE290` → `accent-color: var(--content-success)`
-
-**rgba() mapping:**
-| Hardcoded pattern | Context | Replace with |
-|-------------------|---------|-------------|
-| `rgba(0,0,0,*)` | box-shadow | No TRDR shadow token exists → flag in DS_PROGRESS.md / DS_MIGRATION.md as "Missing shadow token" |
-| `rgba(255,255,255,0.03–0.08)` | border / subtle divider | `var(--border-subtle)` if token exists, otherwise flag |
-| `rgba(255,255,255,0.10–0.20)` | hover/hover overlay | `var(--surface-hover)` if token exists, otherwise flag |
-| `rgba(255,255,255,.29)` approx | overlay/backdrop | `var(--bg-overlay)` |
-| `rgba(255,255,255,*)` other | overlay | flag |
-| `rgba(0,212,255,*)` | focus glow/shadow | No alpha token exists for `--border-focus` → flag as "Missing focus-alpha token" |
-| `rgba(0,168,204,*)` | brand alpha bg | Use `var(--surface-brand)` if available, otherwise flag |
-| `rgba(79,226,144,*)` | success alpha bg | Use `var(--surface-success)` if available, otherwise flag |
-| `rgba(243,79,69,*)` | error alpha bg | Use `var(--surface-error)` if available, otherwise flag |
-| `rgba(255,204,64,*)` | warning alpha bg | Use `var(--surface-warning)` if available, otherwise flag |
-| Any other `rgba(N,N,N,*)` | various | Map to nearest semantic alpha token (--surface-brand, --surface-info, --action-*-alpha, etc.) or flag |
-
-**Gradient mapping:**
-
-Known TRDR gradient token values (use to match):
-| Token | Approximate value |
-|-------|------------------|
-| `--gradient-text-brand` | `linear-gradient(90deg, var(--content-brand), var(--border-focus))` — cyan to bright-cyan, horizontal |
-| `--gradient-bg-hero` | `linear-gradient(180deg, var(--bg-secondary), var(--bg-primary))` — dark vertical fade |
-| `--gradient-bg-fade` | `linear-gradient(180deg, var(--bg-tertiary) 0%, transparent 100%)` — surface to transparent |
-
-| Pattern | Replace with |
-|---------|-------------|
-| Gradient whose colors map to `--content-brand` + `--border-focus` (horizontal) | `var(--gradient-text-brand)` |
-| Gradient whose colors map to `--bg-secondary` → `--bg-primary` (vertical fade) | `var(--gradient-bg-hero)` |
-| Gradient whose colors map to `--bg-tertiary` → transparent | `var(--gradient-bg-fade)` |
-| Gradient using only TRDR bg colors but not matching any token above | Flag — add comment `/* gradient-bg-custom: consider adding to Hub */` |
-| `linear-gradient(...)` using any non-DS colors | Flag — developer must decide: remove, replace with TRDR gradient token, or add new token to Hub |
-| Gradient inside SVG data URI embedded in CSS | Flag |
-
-**Font-size mapping (bidirectional — CSS + HTML/JSX/Vue):**
-
-**Exception for global selectors:** If `font-size: Npx` is inside a `body {}`, `html {}`, `:root {}`, or `* {}` rule:
-- **Remove the `font-size` property entirely** — do NOT add a DS class to the element
-- Document in DS_MIGRATION.md: "Global font-size reset removed — TRDR DS typography classes manage sizes per-element"
-- Do NOT apply DS text class to `<body>` or `<html>` tags
-
-When a CSS class has a `font-size` that maps to a DS text style, the fix is **two-part**:
-
-**Part 1 — In the CSS file**: remove the properties already provided by the DS class:
-- Remove: `font-family`, `font-size`, `font-weight`, `line-height` (the DS class provides these)
-- Keep: `color`, `margin`, `padding`, `text-transform`, `letter-spacing` (project-specific overrides)
-
-**Part 2 — In the HTML/JSX/Vue file**: add the DS class to the element that uses that CSS class:
-
-| stylingMode | How to add |
-|-------------|-----------|
-| `plain-css` / `tailwind` | `<h1 class="hero-title trdr-h2">` |
-| React/Next.js | `<h1 className="hero-title trdr-h2">` |
-| Vue | `<h1 class="hero-title trdr-h2">` or `:class="['hero-title', 'trdr-h2']"` |
-| `css-modules` | Add `composes: trdr-h2 from global;` inside `.hero-title` in the `.module.css` |
-
-**CSS Modules local composition:** If a class uses `composes: AnotherClass` (without `from global`), it inherits styles from that class within the same file. When fixing:
-- Add `composes: trdr-X from global` to the **base class** (AnotherClass)
-- Do NOT add `composes: trdr-X from global` to the **inheriting class** — it inherits the token transitively
-- Example: `.select { composes: input; }` — add `composes: trdr-text-input from global` only to `.input`, not to `.select`
-- Adding `composes: trdr-X from global` to both would apply DS styles twice, causing doubled specificity
-
-**font-size → DS class table:**
-| font-size | DS Class | Notes |
-|-----------|----------|-------|
-| `80px` | `.trdr-h1` | JetBrains Mono 500 |
-| `56px` | `.trdr-h2` | JetBrains Mono 500 |
-| `46px` | `.trdr-h3` | JetBrains Mono 700 |
-| `38px` | `.trdr-h4` | JetBrains Mono 500 |
-| `32px` | `.trdr-h5` | JetBrains Mono 500 |
-| `26px` | `.trdr-h6` | JetBrains Mono 500 |
-| `22px` | `.trdr-h7` | Inter 600 |
-| `18px` | `.trdr-body-b1` | Inter 400 |
-| `16px` | `.trdr-body-b2` or `.trdr-label-l2` | check font-weight: 400→b2, 600→l2 |
-| `14px` | `.trdr-body-b3` or `.trdr-label-l3` | check font-weight: 400→b3, 600→l3 |
-| `12px` | `.trdr-body-b4` or `.trdr-body-aux` | check letter-spacing: 0.2px→b4, 0.24px→aux |
-| `10px` | `.trdr-body-b5` | Inter 400 |
-| other px | nearest DS class below the value | flag in DS_MIGRATION.md |
-| `font-family: var(--font-mono)` (any size) | `.trdr-mono` | Roboto Mono 400 |
-
-**IMPORTANT:** Always scan for the HTML element that uses the CSS class and add the DS class there. Do not only fix the CSS — the element in HTML/JSX/Vue must also receive the DS class so the typography takes effect immediately, before any cascading.
-
-**Do NOT replace:**
-- Hex values inside binary image files (PNG, JPG, GIF)
-- SVG external files — flag them but do not auto-edit
-- Values in commented-out code
-
-**All other values MUST be replaced or flagged.** No exceptions for "decorative" gradients, shadows, or overlays.
-
----
-
-## Sub-fase C: Components
-
-> **Before starting:** Read `DS_ANALYSIS.md` (§ Component Replacement Candidates) and `DS_PROGRESS.md` (§ Sub-fase C) from the project root.
-> Also read `data/components.json` from the skill directory to have all component code blocks available.
-
-Update `DS_PROGRESS.md`: set `Sub-fase C: Components — IN_PROGRESS`.
-
-**If `stylingMode === 'mui'`: skip directly to Step 6-MUI below.** MUI projects do NOT use Pass 1/2/3 (HTML tag replacement). All visual changes come from MUI theme styleOverrides + sx prop migration.
-
-### Step 6-MUI — Generate MUI component styleOverrides (only when `stylingMode === 'mui'`)
-
-#### Step 6-MUI.0 — DS slug to MUI component mapping
-
-| DS Component (slug) | MUI Component | Theme key |
-|---|---|---|
-| `button` | Button, IconButton, LoadingButton | `MuiButton`, `MuiIconButton`, `MuiLoadingButton` |
-| `text-input` | TextField, OutlinedInput, FilledInput | `MuiTextField`, `MuiOutlinedInput` |
-| `checkbox` | Checkbox | `MuiCheckbox` |
-| `radio-button` | Radio | `MuiRadio` |
-| `switch` | Switch | `MuiSwitch` |
-| `dropdown` | Select, Autocomplete | `MuiSelect`, `MuiAutocomplete` |
-| `tooltip` | Tooltip | `MuiTooltip` |
-| `abas` | Tabs, Tab | `MuiTabs`, `MuiTab` |
-| `card` | Card, CardContent, CardActions | `MuiCard`, `MuiCardContent` |
-| `badge` | Badge, Chip | `MuiBadge`, `MuiChip` |
-| `header` | AppBar, Toolbar | `MuiAppBar`, `MuiToolbar` |
-| `modal` | Dialog, DialogTitle, DialogContent | `MuiDialog`, `MuiDialogTitle`, `MuiDialogContent` |
-
-#### Step 6-MUI.1 — Generate styleOverrides block
-
-For each MUI component detected in `replacementCandidates[]`:
-
-1. Read the corresponding DS component from `data/components.json` — look up by slug.
-2. Extract the visual properties (colors, spacing, typography, border-radius) from its `code.css` block.
-3. Translate each CSS property into a MUI `styleOverrides` entry using DS tokens.
-
-**Reference template for common MUI components:**
-
-```typescript
-components: {
-  MuiButton: {
-    styleOverrides: {
-      root: {
-        fontFamily: 'var(--font-secondary)',
-        fontWeight: 600,
-        textTransform: 'none' as const,
-        borderRadius: 'var(--radius-sm)',
-        transition: 'all 0.15s ease',
-        '&:focus-visible': {
-          outline: '2px solid var(--border-focus)',
-          outlineOffset: '2px',
-        },
-      },
-      containedPrimary: {
-        backgroundColor: 'var(--action-brand-inverse-default)',
-        color: 'var(--content-primary)',
-        '&:hover': { backgroundColor: 'var(--action-brand-inverse-hover)' },
-        '&:active': { backgroundColor: 'var(--action-brand-inverse-active)' },
-        '&.Mui-disabled': {
-          backgroundColor: 'var(--action-brand-inverse-disabled)',
-          color: 'var(--content-disabled)',
-        },
-      },
-      outlinedPrimary: {
-        borderColor: 'var(--action-brand-default)',
-        color: 'var(--action-brand-default)',
-        '&:hover': {
-          borderColor: 'var(--action-brand-hover)',
-          backgroundColor: 'var(--action-brand-alpha)',
-        },
-      },
-      textPrimary: {
-        color: 'var(--action-brand-default)',
-        '&:hover': { backgroundColor: 'var(--action-brand-alpha)' },
-      },
-    },
-  },
-  MuiTextField: {
-    styleOverrides: {
-      root: {
-        '& .MuiOutlinedInput-root': {
-          fontFamily: 'var(--font-secondary)',
-          fontSize: 14,
-          color: 'var(--content-primary)',
-          '& fieldset': { borderColor: 'var(--border-default)' },
-          '&:hover fieldset': { borderColor: 'var(--border-strong)' },
-          '&.Mui-focused fieldset': { borderColor: 'var(--border-focus)' },
-          '&.Mui-error fieldset': { borderColor: 'var(--content-error)' },
-        },
-        '& .MuiInputLabel-root': {
-          color: 'var(--content-tertiary)',
-          fontFamily: 'var(--font-secondary)',
-          '&.Mui-focused': { color: 'var(--content-brand)' },
-        },
-      },
-    },
-  },
-  MuiCard: {
-    styleOverrides: {
-      root: {
-        backgroundColor: 'var(--bg-secondary)',
-        borderRadius: 'var(--radius-md)',
-        border: '1px solid var(--border-subtle)',
-      },
-    },
-  },
-  MuiTooltip: {
-    styleOverrides: {
-      tooltip: {
-        backgroundColor: 'var(--bg-inverse)',
-        color: 'var(--content-inverse)',
-        fontFamily: 'var(--font-secondary)',
-        fontSize: 12,
-        borderRadius: 'var(--radius-sm)',
-      },
-      arrow: { color: 'var(--bg-inverse)' },
-    },
-  },
-  MuiSwitch: {
-    styleOverrides: {
-      root: { width: 44, height: 24, padding: 0 },
-      switchBase: {
-        padding: 4,
-        '&.Mui-checked': {
-          color: 'var(--content-primary)',
-          '& + .MuiSwitch-track': {
-            backgroundColor: 'var(--action-brand-default)',
-            opacity: 1,
-          },
-        },
-      },
-      track: {
-        borderRadius: 'var(--radius-full)',
-        backgroundColor: 'var(--surface-primary)',
-        opacity: 1,
-      },
-      thumb: { width: 16, height: 16 },
-    },
-  },
-  MuiCheckbox: {
-    styleOverrides: {
-      root: {
-        color: 'var(--border-default)',
-        '&.Mui-checked': { color: 'var(--action-brand-default)' },
-        '&.Mui-disabled': { color: 'var(--content-disabled)' },
-      },
-    },
-  },
-  MuiRadio: {
-    styleOverrides: {
-      root: {
-        color: 'var(--border-default)',
-        '&.Mui-checked': { color: 'var(--action-brand-default)' },
-      },
-    },
-  },
-  MuiTabs: {
-    styleOverrides: {
-      indicator: { backgroundColor: 'var(--action-brand-default)' },
-    },
-  },
-  MuiTab: {
-    styleOverrides: {
-      root: {
-        fontFamily: 'var(--font-secondary)',
-        fontWeight: 600,
-        textTransform: 'none',
-        color: 'var(--content-tertiary)',
-        '&.Mui-selected': { color: 'var(--content-brand)' },
-      },
-    },
-  },
-  MuiChip: {
-    styleOverrides: {
-      root: {
-        fontFamily: 'var(--font-secondary)',
-        borderRadius: 'var(--radius-sm)',
-      },
-      colorPrimary: {
-        backgroundColor: 'var(--surface-brand)',
-        color: 'var(--content-brand)',
-      },
-      colorSuccess: {
-        backgroundColor: 'var(--surface-success)',
-        color: 'var(--content-success)',
-      },
-      colorWarning: {
-        backgroundColor: 'var(--surface-warning)',
-        color: 'var(--content-warning)',
-      },
-      colorError: {
-        backgroundColor: 'var(--surface-error)',
-        color: 'var(--content-error)',
-      },
-    },
-  },
-  MuiDialog: {
-    styleOverrides: {
-      paper: {
-        backgroundColor: 'var(--bg-secondary)',
-        borderRadius: 'var(--radius-md)',
-        border: '1px solid var(--border-subtle)',
-      },
-    },
-  },
-  MuiAppBar: {
-    styleOverrides: {
-      root: {
-        backgroundColor: 'var(--bg-secondary)',
-        borderBottom: '1px solid var(--border-subtle)',
-        boxShadow: 'none',
-      },
-    },
-  },
-  MuiSelect: {
-    styleOverrides: {
-      root: {
-        fontFamily: 'var(--font-secondary)',
-        fontSize: 14,
-      },
-    },
-  },
-},
-```
-
-**IMPORTANT:** This template is a REFERENCE. For each project:
-1. Only include `MuiXxx` entries for components actually detected in `replacementCandidates[]`
-2. Read the DS component's `code.css` for accurate token values — the template above covers the most common tokens, but individual components may have specific values
-3. If the DS component has variants (e.g., button primary/secondary/ghost), map each to the appropriate MUI variant prop or className
-
-#### Step 6-MUI.2 — Insert styleOverrides into theme file
-
-Read the existing theme file (`themeFilePath`). Find the `components: {}` block (or create it if absent). Merge the generated styleOverrides:
-
-- If a `MuiXxx` key already exists in the theme: **MERGE** the DS overrides into the existing overrides, preserving any project-specific customizations that do not conflict with DS tokens
-- If a `MuiXxx` key does NOT exist: ADD the DS override block
-- **NEVER** overwrite project-specific `defaultProps`, `variants`, or slot customizations
-
-#### Step 6-MUI.3 — Process individual sx prop violations
-
-For components with `sx-migration` classification in `replacementCandidates[]`:
-
-1. Read each sx prop with hardcoded values
-2. Replace with token references:
-   ```tsx
-   // Before
-   <Box sx={{ backgroundColor: '#141519', padding: '16px', borderRadius: '8px' }}>
-   // After
-   <Box sx={{ backgroundColor: 'var(--bg-secondary)', padding: 'var(--spacing-lg)', borderRadius: 'var(--radius-md)' }}>
-   ```
-3. If the sx prop becomes empty after migration (all values now come from theme), consider removing it
-4. Preserve all layout-related sx values (display, flex, grid, position) as-is
-
-#### Step 6-MUI.4 — Process styled(MuiComponent) violations
-
-For components with `styled-migration` classification:
-
-1. Replace hardcoded values inside `styled()` calls with `'var(--token)'`
-2. Preserve all theme-based logic (`theme.breakpoints`, `theme.palette.*` references, `theme.spacing()`)
-3. If the styled() call uses `({ theme }) =>` destructuring: theme references will now pull from the updated theme with DS tokens — this is correct and expected
-
-#### Step 6-MUI.5 — Skip HTML tag replacement
-
-Do NOT run Pass 1/2/3 (HTML tag replacement) for MUI projects. Jump directly to updating DS_PROGRESS.md after completing Steps 6-MUI.1 through 6-MUI.4.
-
-Document in `DS_PROGRESS.md` each styleOverride generated and each sx prop migrated:
-```
-## Sub-fase C: Components — ✅ COMPLETE
-- [x] MuiButton — styleOverrides (containedPrimary, outlinedPrimary, textPrimary)
-- [x] MuiTextField — styleOverrides (root, label, fieldset states)
-- [x] MuiCard — styleOverrides (root)
-- [x] sx migrations: [N] files, [M] values replaced
-- [x] styled() migrations: [N] files
-```
-
-Output:
-```
-✅ Sub-fase C completa — [N] MUI component styleOverrides gerados, [M] sx props migrados.
-
-Próximo: Sub-fase D — Final (logos, ícones, DS_MIGRATION.md)
-Responda:
-- "continuar" / "continue" — iniciar Sub-fase D
-- "parar" / "stop" — salvar progresso e parar aqui
-- "não funcionou" / "report" — reportar problema ao maintainer
-```
-
-**STOP HERE. Wait for developer reply before starting Sub-fase D.**
-If the developer indicates the implementation didn't work (see DEVELOPER DISSATISFACTION DETECTION below), trigger REPORT MODE.
-
----
-
-**For non-MUI projects (`stylingMode !== 'mui'`), continue with the standard Step 6 below:**
-
-### Step 6 — Implement DS components in project files
-
-#### Step 6.0 — Resolve dependency order
-
-Components in `data/components.json` may have a `dependencies` array listing slugs of sub-components they use (e.g., `boleta` depends on `["segmented-control", "text-input", "checkbox", "button", "dropdown"]`). Before processing candidates:
-
-1. Read the `dependencies` field of every candidate component from `data/components.json`.
-2. Build a topological order: **atomic components** (empty `dependencies`) first, then **compound components** (non-empty `dependencies`) sorted so that each component's dependencies appear before it.
-3. Process candidates in this order across all three passes below. Within the same pass, respect the topological order.
-
-This ensures that when a compound component's code block imports a sub-component (e.g., `import Badge from './Badge'`), the sub-component's DS class is already installed in the project.
-
-If a dependency is NOT in the candidate list (i.e., no existing element in the project matched that atomic component), skip it — the compound component's code block will still reference the DS class, and the sub-component can be added later.
-
----
-
-Process candidates in three passes (respecting the dependency order above):
-1. **Pass 1** — Simple replacements (full DS component swap)
-2. **Pass 2** — Complex-preservable (DS structure + logic preservation)
-3. **Pass 3** — Manual review flagging (no auto-modification)
-
----
-
-#### Step 6 — Pass 1: Simple replacements
-
-For each candidate classified as `simple` in DS_ANALYSIS.md:
-
-1. **Load the DS component code** from `data/components.json` — look up the component by slug and read `c.code.html` (for plain-css/tailwind projects) or `c.code.react` (for React/Next.js projects) or adapt for Vue.
-
-2. **Adapt the content** — the DS component's code block has placeholder content (e.g., "Confirmar", "Badge"). Replace placeholders with the ACTUAL content from the project:
-   - Button text: extract the text content from the existing `<button>` element
-   - Input placeholder: extract the existing `placeholder` attribute
-   - Label text: extract the existing label/text node
-   - Badge text: extract the existing text content
-   - Preserve `id`, `name`, `data-*`, `aria-*` attributes from the original element
-
-3. **Select the correct variant** using `suggestedDsVariant` from DS_ANALYSIS.md.
-
-4. **Replace the element in the source file** — examples by component:
-
-   **Buttons (slug: `button`):**
-   ```html
-   <!-- BEFORE -->
-   <button class="btn-primary hero-cta">Get Started</button>
-   <!-- AFTER -->
-   <button class="trdr-btn trdr-btn-primary">Get Started</button>
-   ```
-   - Remove custom CSS classes that duplicate DS styles (background, padding, height, font, border, border-radius, cursor, transition)
-   - Keep classes used for layout/positioning (margin, width, grid placement)
-   - Keep `id`, `name`, `type`, `data-*`, `aria-*` attributes
-
-   **Text inputs (slug: `text-input`):**
-   ```html
-   <!-- BEFORE -->
-   <input type="text" class="search-bar" placeholder="Search...">
-   <!-- AFTER -->
-   <input type="text" class="trdr-text-input" placeholder="Search...">
-   ```
-   - If the existing input has a wrapper with icon (search icon + input), restructure to match DS anatomy:
-     ```html
-     <div class="trdr-text-input-wrapper">
-       <span class="material-icons mi-sm icon-muted">search</span>
-       <input type="text" class="trdr-text-input" placeholder="Search...">
-     </div>
-     ```
-
-   **Checkboxes (slug: `checkbox`):**
-   ```html
-   <!-- BEFORE -->
-   <input type="checkbox" id="terms"> <label for="terms">Accept terms</label>
-   <!-- AFTER -->
-   <label class="trdr-checkbox">
-     <input type="checkbox" id="terms" />
-     <span class="trdr-checkbox-box"></span>
-     <span>Accept terms</span>
-   </label>
-   ```
-   - DS checkbox requires a specific DOM structure (label > input + box-span + text-span)
-   - Preserve `id`, `name`, `checked`, `disabled` attributes from the original input
-
-   **Radio buttons (slug: `radio-button`):**
-   Similar to checkbox — restructure to DS anatomy while preserving `name`, `value`, `checked`.
-
-   **Switches (slug: `switch`):**
-   ```html
-   <!-- BEFORE -->
-   <div class="toggle"><input type="checkbox"></div>
-   <!-- AFTER -->
-   <button class="trdr-switch" role="switch" aria-checked="false">
-     <span class="trdr-switch-track"><span class="trdr-switch-knob"></span></span>
-     <span>Label text</span>
-   </button>
-   ```
-
-   **Dropdowns (slug: `dropdown`):**
-   ```html
-   <!-- BEFORE -->
-   <select class="lang-selector"><option>PT</option><option>EN</option></select>
-   <!-- AFTER -->
-   <select class="trdr-dropdown"><option>PT</option><option>EN</option></select>
-   ```
-   - Preserve all `<option>` children, `name`, `id`, `value` attributes
-
-   **Badges (slug: `badge`):**
-   ```html
-   <!-- BEFORE -->
-   <span class="badge badge-success">Active</span>
-   <!-- AFTER -->
-   <span class="trdr-badge trdr-badge-success">Active</span>
-   ```
-   - Detect variant from existing color/class: green/success → `trdr-badge-success`, blue/brand → `trdr-badge-brand`, etc.
-
-   **Segmented controls / tabs (slug: `segmented-control`, `abas`):**
-   ```html
-   <!-- BEFORE -->
-   <div class="tabs">
-     <button class="tab active">Tab 1</button>
-     <button class="tab">Tab 2</button>
-   </div>
-   <!-- AFTER -->
-   <div class="trdr-segment-control">
-     <button class="trdr-segment trdr-segment-active">Tab 1</button>
-     <button class="trdr-segment trdr-segment-inactive">Tab 2</button>
-   </div>
-   ```
-
-   **Tooltips (slug: `tooltip`):**
-   - If `title=""` attribute: remove `title`, add DS tooltip structure around the element
-   - If `data-tooltip=""`: adapt to DS tooltip pattern
-   - Preserve the tooltip content text
-
-5. **Icons inside replaced components:** When the original element contained an inline SVG icon (e.g., Button with search icon), replace that SVG immediately with a Material Icon `<span>` using the correct size class from Step 6.6c-2 rules. Do NOT leave inline SVGs inside new DS component structures — this is an exception to "SVG replacement happens in Sub-fase D."
-
-6. **Clean up redundant CSS** — for each replaced element's custom class, remove properties now provided by DS:
-   - Remove: `height`, `padding`, `font-family`, `font-size`, `font-weight`, `border`, `border-radius`, `background`, `color`, `cursor`, `transition`, `display`, `align-items`, `justify-content`
-   - Keep: `width`, `min-width`, `gap`, position-specific props, state overrides, layout props (margin, grid-area)
-
-7. **Document in DS_PROGRESS.md** each replacement:
-   ```
-   - [x] button: src/Hero.tsx:42 — "Get Started" → trdr-btn-primary (simple swap)
-   ```
-
----
-
-#### Step 6 — Pass 2: Complex-preservable replacements
-
-For each candidate classified as `complex-preservable` in DS_ANALYSIS.md:
-
-1. **Read the full element context** — read the file and identify all:
-   - Event handlers: `onClick`, `onChange`, `onSubmit`, `onKeyDown`, `onFocus`, `onBlur`, etc.
-   - Conditional rendering: ternary expressions, `&&` conditionals
-   - Dynamic props: `className={...}`, `style={...}`, spread props `{...rest}`
-   - Data bindings: `value={state}`, `checked={state}`, `ref={ref}`
-
-2. **Apply DS structure while preserving all logic, using one of two strategies:**
-
-   **Strategy A — Class addition (when existing DOM structure is compatible with DS):**
-   The element's DOM structure is close enough to the DS component. Add DS classes and remove conflicting custom CSS.
-   ```tsx
-   // BEFORE
-   <button
-     className={`btn ${isActive ? 'btn-active' : ''}`}
-     onClick={handleClick}
-     disabled={isLoading}
-   >
-     {isLoading ? 'Loading...' : 'Submit'}
-   </button>
-
-   // AFTER — DS classes added, handlers/bindings preserved
-   <button
-     className={`trdr-btn trdr-btn-primary ${isActive ? 'btn-active' : ''}`}
-     onClick={handleClick}
-     disabled={isLoading}
-   >
-     {isLoading ? 'Loading...' : 'Submit'}
-   </button>
-   ```
-
-   **Strategy B — Structure wrap (when DS component requires different DOM structure):**
-   The element needs DS DOM structure but has logic that must stay.
-   ```tsx
-   // BEFORE — checkbox with complex state
-   <div className="filter-option">
-     <input
-       type="checkbox"
-       id={`filter-${id}`}
-       checked={filters.includes(id)}
-       onChange={() => toggleFilter(id)}
-     />
-     <label htmlFor={`filter-${id}`}>{label}</label>
-   </div>
-
-   // AFTER — DS checkbox structure, ALL logic preserved
-   <label className="trdr-checkbox">
-     <input
-       type="checkbox"
-       id={`filter-${id}`}
-       checked={filters.includes(id)}
-       onChange={() => toggleFilter(id)}
-     />
-     <span className="trdr-checkbox-box"></span>
-     <span>{label}</span>
-   </label>
-   ```
-
-3. **NEVER remove or alter any of the following** (absolute rule):
-   - `onClick`, `onChange`, `onSubmit`, `onKeyDown`, `onFocus`, `onBlur` handlers
-   - `ref=`, `key=` props
-   - `disabled={condition}`, `checked={condition}`, `value={state}` bindings
-   - Conditional rendering (`{condition && ...}`, `{condition ? ... : ...}`)
-   - Spread props (`{...rest}`, `{...props}`)
-   - `id`, `name`, `data-*`, `aria-*` attributes
-   - Custom `className` parts used in JS selectors (`querySelector`, `classList.toggle`)
-
-4. **For dynamically-toggled classes** (e.g., `classList.toggle('active')`):
-   - Map the custom state class to a DS state class
-   - Update ALL `classList.toggle/add/remove` calls to also toggle the DS class
-   - Example: `el.classList.toggle('active')` → also add `el.classList.toggle('trdr-segment-active')`
-
-5. **Clean up redundant CSS** — same rules as Pass 1 step 6.
-
-6. **Document in DS_PROGRESS.md:**
-   ```
-   - [x] checkbox: src/Filters.tsx:88 — preserved: onChange, checked binding → trdr-checkbox (complex-preservable, Strategy B)
-   ```
-
----
-
-#### Step 6 — Pass 3: Manual review flagging
-
-For each candidate classified as `complex-manual` in DS_ANALYSIS.md:
-
-1. **Do NOT modify** the source file's component structure.
-
-2. **Add a TODO comment** in the source file above the element:
-   ```
-   <!-- TODO: TRDR DS — replace with [c.name] component. See DS_MIGRATION.md for details. -->
-   ```
-   For React/JSX:
-   ```
-   {/* TODO: TRDR DS — replace with [c.name] component. See DS_MIGRATION.md for details. */}
-   ```
-
-3. **Add an entry to `DS_MIGRATION.md`** under `## Manual component review`:
-   ```markdown
-   ### [file:line] — [c.name]
-   - **Reason:** [brief description of complexity]
-   - **Existing structure:** [brief DOM outline]
-   - **Suggested DS component:** [slug] ([variant])
-   - **Suggested approach:** Strategy A (class addition) / Strategy B (structure wrap) / custom adaptation
-   - **Handlers to preserve:** [list of event handlers found]
-   - **Dynamic props:** [list of dynamic bindings]
-   ```
-
----
-
-#### Step 6 — Stubs and unmapped patterns
-
-**If `c.implemented === false`** (stub — not yet implemented in DS):
-- Add this banner comment above the affected element in the source file:
-  ```
-  /* TRDR DS — <c.name> (figmaId: <c.figmaId>) */
-  /* Implementação canônica pendente. Consulte https://trdr.mrocontent.com.br/componentes/<c.slug> */
-  /* Tokens recomendados: <list c.tokens[].token> */
-  ```
-- Append an entry to `MISSING_COMPONENTS.md`:
-  ```markdown
-  ## <c.name>
-  - Slug: `<c.slug>` | figmaId: `<c.figmaId>` | Category: `<c.category>`
-  - Found in: <list of file:line>
-  - Description: <c.description>
-  - Recommended tokens: <c.tokens[]>
-  - Status: ⚠️ stub — code blocks pending
-  ```
-
-**If no slug matches** the detected pattern:
-- Flag the pattern in `MISSING_COMPONENTS.md` under "Unmapped patterns" with the file location and a one-line description of the UI need.
-
-**Do NOT replace domain-specific components** (course cards, lesson rows, trading panels, etc.) — document them as "sem equivalente DS".
-
----
-
-#### Step 6 — Final: Update progress
-
-Update `DS_PROGRESS.md`: set `Sub-fase C: Components — ✅ COMPLETE` and add summary:
 ```
-### Componentes DS Aplicados
-Simple swaps: [S]
-Complex-preservable: [P]
-Manual review: [M] (see DS_MIGRATION.md)
-Stubs: [T]
-Total: [S+P+M+T] candidates processed
-
-[List each replacement with its classification]
+trdr-ds/
+├── SKILL.md              ← YOU ARE HERE (router + sprint orchestration)
+├── phases/
+│   ├── analyze.md        ← Phase 1: scan project, find violations, plan sprints
+│   ├── foundation.md     ← Sub-fase A: tokens.css, components.css, CLAUDE.md, imports
+│   ├── violations.md     ← Sub-fase B: fix violations batch-by-batch
+│   ├── components.md     ← Sub-fase C: apply DS component classes
+│   └── final.md          ← Sub-fase D: logos, icons, inline styles, DS_MIGRATION.md
+├── modes/
+│   ├── resume.md         ← Resume from last checkpoint
+│   ├── status.md         ← Show sprint progress
+│   ├── rollback.md       ← Undo entire migration
+│   ├── report.md         ← Generate & send bug report
+│   └── sync.md           ← Re-fetch Hub snapshots
+├── data/
+│   ├── components/       ← One JSON file per component (button.json, checkbox.json, ...)
+│   ├── index.json        ← Component catalog index (slugs, names, categories, implemented flag)
+│   └── mappings.json     ← Color/font/spacing/rgba/gradient mapping tables
+├── references/
+│   ├── tokens.css        ← All TRDR CSS variables (dark + light mode)
+│   ├── rules.md          ← 12 absolute rules
+│   └── logo-trdr.svg     ← Official TRDR logo
+└── templates/
+    ├── ds-analysis.md    ← Template for DS_ANALYSIS.md
+    ├── ds-progress.md    ← Template for DS_PROGRESS.md
+    ├── sprint-plan.md    ← Template for SPRINT_PLAN.md
+    ├── claude-md.md      ← Template for project CLAUDE.md
+    └── ds-migration.md   ← Template for DS_MIGRATION.md
 ```
 
-Output:
-```
-✅ Sub-fase C completa — [N] componentes DS implementados ([S] simple, [P] complex-preservable), [M] flagged para revisão manual, [T] stubs marcados.
+## Offline-first Snapshots
 
-Próximo: Sub-fase D — Final (logos + ícones + DS_MIGRATION.md)
-Responda:
-- "continuar" / "continue" — finalizar migração
-- "parar" / "stop" — salvar progresso e parar aqui
-- "não funcionou" / "report" — reportar problema ao maintainer
-```
+- `references/tokens.css` — all TRDR CSS variables, copied from Hub
+- `data/components/` — individual component files with code blocks
+- `data/index.json` — catalog index (lightweight, always loaded)
 
-**STOP HERE. Wait for developer reply before starting Sub-fase D.**
-If the developer indicates the implementation didn't work (see DEVELOPER DISSATISFACTION DETECTION below), trigger REPORT MODE.
+Snapshots synced via `npm run sync` in trdr-plugins repo. **Always prefer local snapshots.** Only fetch from Hub when user passes `--latest` or runs `sync`.
 
 ---
 
-## Sub-fase D: Final
-
-> **Before starting:** Read `DS_ANALYSIS.md` (§ Logo Audit) and `DS_PROGRESS.md` from the project root.
-
-Update `DS_PROGRESS.md`: set `Sub-fase D: Final — IN_PROGRESS`.
-
-### Step 6.5 — Replace wrong logos and fix logo usage in HTML/JSX
+## Argument Routing
 
-**Step 6.5a — Replace the SVG file on disk:**
+| Arg | Action | File to Read |
+|-----|--------|-------------|
+| *(none)* / `analyze` | Scan project, generate plan | `phases/analyze.md` |
+| `apply` | Analyze + execute all phases | `phases/analyze.md` → then route per sprint |
+| `foundation` | Sub-fase A only | `phases/foundation.md` |
+| `violations` | Sub-fase B only | `phases/violations.md` |
+| `components` | Sub-fase C only | `phases/components.md` |
+| `final` | Sub-fase D only | `phases/final.md` |
+| `resume` | Continue from checkpoint | `modes/resume.md` |
+| `status` | Show progress table | `modes/status.md` |
+| `sync` | Re-fetch Hub data | `modes/sync.md` |
+| `rollback` | Undo migration | `modes/rollback.md` |
+| `report` | Send bug report | `modes/report.md` |
+| `batch N` | Override batch size | Set batch_size=N, then route as `apply` |
+| `--latest` | Sync first, then continue | Run `modes/sync.md` first, then route normally |
 
-Load the official TRDR logo from the skill directory:
-```
-Read: <skill-dir>/references/logo-trdr.svg
-```
-
-Where `<skill-dir>` is `~/.claude/skills/trdr-ds/` or `<project>/.claude/skills/trdr-ds/`. Try both.
-
-If `references/logo-trdr.svg` is missing from the skill directory → STOP with:
-> ❌ Logo reference missing. Run `npx trdr-ds-install@latest` to restore it.
+**Routing procedure:**
 
-For each file in `logoAudit.wrong`:
-- Overwrite the file in place with the official logo content (same path, same filename).
-- Report: `✅ Replaced [path] with official TRDR logo (105×41px, #00D4FF)`
-
-If no logo files were found AND `public/` exists at the project root:
-- Write the official logo to `public/logo-trdr.svg`.
-- Report: `✅ Added official TRDR logo → public/logo-trdr.svg`
-
-If no logo files found AND no `public/` exists:
-- Log in DS_MIGRATION.md under "Manual steps": "Add logo-trdr.svg to your assets directory. Reference: <skill-dir>/references/logo-trdr.svg"
-
-**Never modify correct logos** (`logoAudit.correct`) — they already match the official reference.
+1. Parse the argument from the user's invocation
+2. Run the version check (Step 0 below)
+3. Read **ONLY** the file indicated in the table above
+4. Execute the instructions in that file
+5. When a phase completes and the next phase should run, read the NEXT file — never preload
 
 ---
 
-**Step 6.5b — Fix logo usage in HTML/JSX/Vue (Category K violations):**
-
-After the SVG is on disk, scan for incorrect logo usage in HTML/JSX/Vue files and replace by framework:
-
-**Plain HTML:**
-- `<span [class]>TRDR</span>` used as logo → `<img src="logo-trdr.svg" alt="TRDR" height="[N]">` (preserve the original height or use 24px default)
-- `<img src="[any-non-official-logo]">` → update `src` to `"logo-trdr.svg"`
-- Remove any `style=""` attribute from the logo element after replacement
-
-**React / Next.js:**
-- `import Logo from './[non-official-logo]'` → `import LogoTrdr from './logo-trdr.svg'` (or from `@/public/logo-trdr.svg`)
-- `<Image src="[non-official]" />` → `<Image src="/logo-trdr.svg" alt="TRDR" />`
-- `<span>TRDR</span>` in a logo context → `<Image src="/logo-trdr.svg" alt="TRDR" height={24} width={105} />`
-- Remove `style={{...}}` from the logo element after replacement
-
-**Vue / Nuxt:**
-- `:src="[non-official-logo-var]"` → update to `"/logo-trdr.svg"` (static string)
-- `<span>TRDR</span>` → `<img src="/logo-trdr.svg" alt="TRDR" :height="24" />`
-
-Update `DS_PROGRESS.md`:
-```
-- [x] logos incorretos substituídos — [N] SVG replaced, [M] HTML usages fixed, [P] already correct
-```
-
-### Step 6.6 — Replace inline SVG icons with icon library (Category J violations)
-
-If Category J detected inline `<svg>` elements that are not the TRDR logo:
-
-**Step 6.6a — Detect and install icon library by framework:**
-
-| Framework | Library | Detection | Action if missing |
-|-----------|---------|-----------|-------------------|
-| Plain HTML | Material Icons (CDN) | Check `<link>` in `<head>` for `fonts.googleapis.com/icon` | Add CDN link to `<head>` |
-| React/Next.js | @mui/icons-material | Check `package.json` | Suggest: `npm install @mui/icons-material` — do not install automatically |
-| Vue | via CDN or vue-material-icons | Check `<link>` in template/index.html | Add CDN link |
-
-For plain HTML and Vue (CDN approach), add to `<head>`:
-```html
-<link href="https://fonts.googleapis.com/icon?family=Material+Icons" rel="stylesheet">
-```
-
-**Step 6.6b — Add icon CSS helpers (plain HTML / Vue CDN only):**
-
-Add to the project's main CSS:
-```css
-/* Material Icons helpers — TRDR DS */
-.material-icons {
-  font-size: 20px;                /* default = mi-md */
-  display: inline-flex;
-  align-items: center;
-  color: inherit;
-  user-select: none;
-}
-.mi-2xs { font-size: 12px; }     /* very small indicators */
-.mi-xs  { font-size: 14px; }     /* compact UI */
-.mi-sm  { font-size: 16px; }     /* small icons */
-/* .mi-md — 20px — default, no class needed */
-.mi-lg  { font-size: 24px; }     /* standard Material Design size */
-.mi-xl  { font-size: 28px; }     /* larger icons */
-.mi-2xl { font-size: 32px; }     /* hero/feature icons */
-```
-
-**Step 6.6c — Add icon color classes** (do NOT use inline style for icon color — create CSS classes instead):
-```css
-.icon-brand   { color: var(--content-brand); }
-.icon-success { color: var(--context-trading-up); }
-.icon-error   { color: var(--content-error); }
-.icon-warning { color: var(--content-warning); }
-.icon-dim     { color: var(--content-disabled); }
-.icon-muted   { color: var(--content-tertiary); }
-```
-
-**Step 6.6c-2 — Measure original SVG dimensions before replacement:**
-
-For EACH inline `<svg>` element that will be replaced, determine the original rendered size:
-
-1. **Read the SVG's explicit size** — check for `width` and `height` attributes:
-   ```html
-   <svg width="24" height="24" ...>  →  originalSize = 24
-   <svg width="16" height="16" ...>  →  originalSize = 16
-   ```
-   Use the `width` attribute value (icons are typically square). If `width` and `height` differ, use the larger value.
-
-2. **If no width/height attributes** — check the `viewBox`:
-   ```html
-   <svg viewBox="0 0 24 24" ...>  →  originalSize = 24 (4th value = viewBox height)
-   ```
-
-3. **If no explicit size and no viewBox** — check CSS for the SVG's container:
-   - Look for the SVG's parent element class or the SVG's own class
-   - Search CSS files for `width`, `height`, or `font-size` applied to that selector
-   - Example: `.icon { width: 18px; height: 18px; }` → originalSize = 18
-
-4. **If still undetermined** — assume 20px (the DS default) and add a comment:
-   ```html
-   <!-- TODO: verify icon size — original SVG had no explicit dimensions -->
-   ```
-
-5. **Map originalSize to the correct size class/style:**
+## Step 0 — Version Check (runs on EVERY invocation)
 
-   | Original SVG size | Replacement class/style | Notes |
-   |---|---|---|
-   | 12px | `.mi-2xs` | Very small indicator |
-   | 14px | `.mi-xs` | Compact UI |
-   | 16px | `.mi-sm` | Small icons |
-   | 18px | `style="font-size:18px"` | Between sm and md — no standard class |
-   | 20px | *(none — default)* | No class needed |
-   | 22px | `style="font-size:22px"` | Between md and lg — no standard class |
-   | 24px | `.mi-lg` | Standard Material Design size |
-   | 28px | `.mi-xl` | Larger icons |
-   | 32px | `.mi-2xl` | Hero/feature icons |
-   | Any other Npx | `style="font-size:Npx"` | Exact size preservation |
-
-   **Priority:** Use a size class if one matches exactly. Only use inline `font-size` for non-standard sizes. NEVER use inline `style="color:..."` — color is ALWAYS via CSS class (Rule 11).
-
-**Step 6.6d — Map SVG content to icon names:**
-
-Analyze the SVG path/shape content to identify the icon:
-| SVG shape/content | Material Icon name |
-|---|---|
-| Circle + diagonal line (magnifying glass) | `search` |
-| X / diagonal paths (close) | `close` |
-| Left arrow / chevron | `chevron_left` or `arrow_back` |
-| Right arrow / chevron | `chevron_right` or `arrow_forward` |
-| Triangle play | `play_arrow` |
-| Square stop | `stop` |
-| Padlock | `lock` |
-| Checkmark | `check` |
-| Star | `star` |
-| Three horizontal lines (hamburger) | `menu` |
-| Plus sign | `add` |
-| Warning triangle | `warning` |
-| Info circle | `info` |
-| Bell | `notifications` |
-| User/person | `person` |
-| Gear/cog | `settings` |
-| Trash | `delete` |
-| Pencil/edit | `edit` |
-
-For SVG icons that cannot be mapped automatically: leave a `<!-- TODO: replace with Material Icon: [description] -->` comment and document in DS_MIGRATION.md.
-
-**Step 6.6e — Replace by framework (with size preservation):**
-
-Use the `originalSize` measured in Step 6.6c-2 to select the correct size class or inline font-size.
-
-| Framework | Standard size (has class) | Non-standard size (no class) |
-|-----------|--------------------------|------------------------------|
-| Plain HTML | `<span class="material-icons {sizeClass}">icon_name</span>` | `<span class="material-icons" style="font-size:{N}px">icon_name</span>` |
-| React (CDN) | `<span className="material-icons {sizeClass}">icon_name</span>` | `<span className="material-icons" style={{fontSize:{N}}}>icon_name</span>` |
-| React (@mui) | `<IconName sx={{ fontSize: {originalSize} }} />` (omit `sx` if 24px — @mui default) | Same — @mui always uses `sx.fontSize` |
-| Vue (CDN) | `<span class="material-icons {sizeClass}">icon_name</span>` | `<span class="material-icons" style="font-size:{N}px">icon_name</span>` |
-
-**Examples with size + color combined:**
-```html
-<!-- Original: 16×16 search icon with brand color -->
-<svg width="16" height="16"><path d="M..." stroke="#00A8CC"/></svg>
-<!-- Replacement: class mi-sm (16px) + class icon-brand -->
-<span class="material-icons mi-sm icon-brand">search</span>
-
-<!-- Original: 24×24 close icon, neutral color (currentColor) -->
-<svg width="24" height="24"><path d="M..." stroke="currentColor"/></svg>
-<!-- Replacement: class mi-lg (24px), no color class (inherits) -->
-<span class="material-icons mi-lg">close</span>
-
-<!-- Original: 20×20 icon (default size) -->
-<svg width="20" height="20" viewBox="0 0 20 20"><path d="M..."/></svg>
-<!-- Replacement: no size class needed (20px is default) -->
-<span class="material-icons">settings</span>
-
-<!-- Original: 18×18 icon (non-standard size) -->
-<svg width="18" height="18" viewBox="0 0 18 18"><path d="M..."/></svg>
-<!-- Replacement: inline font-size for non-standard size -->
-<span class="material-icons" style="font-size:18px">settings</span>
-
-<!-- React @mui — 16px icon with brand color -->
-<SearchIcon className="icon-brand" sx={{ fontSize: 16 }} />
+```bash
+npm show trdr-ds-install version 2>/dev/null
 ```
 
-**Color of icon** — ALWAYS via class, NEVER inline style:
-```html
-<!-- Correct -->
-<span class="material-icons mi-xs icon-success">check</span>
-<!-- Wrong — never do this -->
-<span class="material-icons" style="color: var(--context-trading-up)">check</span>
-```
+- If fails or empty: skip silently
+- If registry == local (2.0.0): skip silently
+- If registry > local:
+  ```
+  Nova versao da skill disponivel: trdr-ds-install@[registry] (instalada: 2.0.0)
+  
+  - "atualizar" / "update" — instalar agora (requer reiniciar /trdr-ds)
+  - "continuar" / "skip" — usar versao atual
+  ```
+  STOP. Wait for reply.
+  If update: run `npx trdr-ds-install@latest`, output success, STOP.
 
 ---
 
-### Step 6.7 — Eliminate inline styles (Category I violations)
-
-For each `style=""` / `style={{}}` violation detected in Category I:
-
-**Decision tree:**
-
-1. **Dynamic image URL** → keep as-is (acceptable exception):
-   ```html
-   style="background-image: url('data/image.jpg')"  ✅ keep
-   ```
+## Sprint Orchestration (Critical for Context Management)
 
-2. **CSS custom property for dynamic value** → keep as-is (acceptable pattern):
-   ```html
-   style="--card-delay: 0.1s"  ✅ keep
-   style={{ '--delay': animDelay }}  ✅ keep
-   ```
+### The Problem
+Large projects generate hundreds of violations across dozens of files. Processing everything in a single context window causes hallucination, missed mappings, and incomplete work.
 
-3. **`animation-delay` with calculated value** → convert to CSS custom property:
-   ```html
-   <!-- Before -->
-   style="animation-delay: 0.15s"
-   <!-- After -->
-   style="--delay: 0.15s"
-   ```
-   Then add to CSS: `animation-delay: var(--delay, 0s);`
+### The Solution: Sprints
+Every migration is split into **self-contained sprints** (defined in `SPRINT_PLAN.md`). Each sprint:
+- Processes at most **15 files**
+- Has a single clear scope (one phase or one folder of violations)
+- Reads state from files, NEVER from conversation memory
+- Saves all progress to `DS_PROGRESS.md`
+- Ends with a STOP checkpoint
 
-4. **`background-size` / `background-position` alongside `background-image`** → move to CSS:
-   ```css
-   /* Add selector that matches elements with background-image inline style */
-   .element[style*="background-image"] { background-size: cover; background-position: center; }
-   ```
+### Context Clearing Protocol
 
-5. **Design token value as inline style** → create a CSS class:
-   | Inline style | Action |
-   |---|---|
-   | `style="color: #hex"` | Create `.text-[name] { color: var(--semantic-token); }` and add class |
-   | `style="background: #hex"` | Create `.bg-[name] { background: var(--semantic-token); }` and add class |
-   | `style="font-family: X"` | Remove (handled by typography DS class from Step 5F) |
-   | `style="padding: Npx"` | Create `.p-[name] { padding: var(--spacing-*); }` or use existing utility |
+**After every sprint, output this block:**
 
-**By framework:**
-
-Plain HTML:
-```html
-<!-- Before -->
-<span style="color: var(--teal)">TRDR</span>
-<!-- After -->
-<span class="text-brand">TRDR</span>
-<!-- + CSS: .text-brand { color: var(--content-brand); } -->
-```
-
-React/Next.js:
-```jsx
-// Before
-<span style={{ color: '#00D4FF' }}>TRDR</span>
-// After
-<span className="text-brand">TRDR</span>
-// + CSS: .text-brand { color: var(--content-brand); }
 ```
+--- SPRINT [N] COMPLETO ---
 
-Vue:
-```html
-<!-- Before -->
-<span :style="{ color: brandColor }">TRDR</span>
-<!-- After — if value is always the brand token -->
-<span class="text-brand">TRDR</span>
-<!-- Keep :style only if the value is truly dynamic (changes at runtime based on data) -->
-```
+[Brief summary of what was done]
 
-**Conditional / ternary values in `style={{}}`** (common in React):
-When a style value is a ternary expression or computed value:
-```jsx
-// Before — conditional style object
-style={{
-  background: isActive ? '#4A4A4A' : 'transparent',
-  color: isActive ? '#FFFFFF' : '#A4A4A4',
-}}
-// After — state classes
-className={isActive ? 'tab-active' : 'tab-inactive'}
-// + CSS:
-// .tab-active  { background: var(--surface-primary);  color: var(--content-primary); }
-// .tab-inactive { background: transparent;             color: var(--content-tertiary); }
-```
-Steps:
-1. Identify the boolean condition controlling the state
-2. Create two CSS classes (active/inactive) with semantic token values
-3. Replace `style={{...}}` with `className={condition ? 'active-class' : 'inactive-class'}`
-4. Keep all business logic intact — only change how styles are applied
-5. Document in DS_PROGRESS.md: "Ternary style at [file:line] converted to state classes"
+Progresso: [done]/[total] sprints ([percentage]%)
+Proximo: Sprint [N+1] — [name]
 
-**Special: trading up/down ternary** — when the two values are `#4FE290`/`#F34F45` (or any trading up/down pair):
-```css
-/* Use context.trading tokens, NOT content.success/error */
-.price-up   { color: var(--context-trading-up); }
-.price-down { color: var(--context-trading-down); }
-/* WRONG: .price-up { color: var(--content-success); } — success is for non-trading contexts */
-```
+IMPORTANTE: Para melhor resultado no proximo sprint,
+limpe o contexto agora com /clear e depois execute:
+/trdr-ds resume
 
-**Add new utility classes to the project's main CSS** (not to components.css or tokens.css — those are skill-managed):
-Group new classes in a clearly labelled block at the bottom of the project's CSS, e.g.:
-```css
-/* === Project utilities (added by TRDR DS migration) === */
-.text-brand { color: var(--content-brand); }
-.icon-brand { color: var(--content-brand); }
-/* ... */
+Isto libera a janela de contexto e evita alucinacoes.
+Se preferir continuar sem limpar: "continuar"
 ```
 
-**MUI sx prop migration (only when `stylingMode === 'mui'`):**
-
-MUI's `sx` prop is the idiomatic way to style MUI components. Unlike inline `style={{}}`, `sx` props should NOT be eliminated — they should be migrated to use DS tokens.
-
-**Decision tree for MUI `sx` props:**
-
-1. **Value already uses theme reference** (`theme.palette.primary.main`, `theme.spacing(2)`) → keep as-is (theme was updated with DS tokens in Sub-fase A)
-
-2. **Hardcoded color** → replace with token:
-   ```tsx
-   // Before
-   sx={{ color: '#00A8CC' }}
-   // After
-   sx={{ color: 'var(--content-brand)' }}
-   ```
-
-3. **Hardcoded spacing with string px** → replace with token:
-   ```tsx
-   // Before
-   sx={{ padding: '16px', gap: '8px' }}
-   // After
-   sx={{ padding: 'var(--spacing-lg)', gap: 'var(--spacing-sm)' }}
-   ```
-
-4. **Hardcoded fontFamily** → remove (theme typography handles this globally)
+**STOP. Wait for developer reply.**
 
-5. **Hardcoded borderRadius** → replace with token:
-   ```tsx
-   // Before
-   sx={{ borderRadius: '12px' }}
-   // After
-   sx={{ borderRadius: 'var(--radius-md)' }}
-   ```
+- If developer says "continuar": proceed to next sprint (warn that quality may degrade)
+- If developer clears context and runs `/trdr-ds resume`: the resume mode reads all state from files
 
-6. **Conditional sx values** → replace both branches:
-   ```tsx
-   // Before
-   sx={{ color: isActive ? '#00D4FF' : '#A4A4A4' }}
-   // After
-   sx={{ color: isActive ? 'var(--content-brand)' : 'var(--content-tertiary)' }}
-   ```
+### Sprint State Files
 
-7. **Layout-only sx** (display, flex, grid, position, width, height) → keep as-is (not DS concern)
+Three files at the project root serve as the "database" for the migration:
 
-Do NOT convert `sx` props to CSS classes — `sx` is idiomatic MUI and is acceptable when using DS tokens.
+| File | Purpose | When to Read |
+|------|---------|-------------|
+| `DS_ANALYSIS.md` | Full analysis (violations, candidates, logo audit) | At sprint start — read ONLY the section relevant to current sprint |
+| `SPRINT_PLAN.md` | Sprint definitions and status | At sprint start — find current sprint |
+| `DS_PROGRESS.md` | Execution log, batch status, overall progress | At sprint start and after every action |
 
----
-
-### Step 7 — Generate DS_MIGRATION.md
-
-Create `DS_MIGRATION.md` at the project root:
-
-```markdown
-# TRDR Design System — Migration Log
-Applied: [date]
-Catalog: TRDR DS v[catalog-version] ([implemented]/[total] components, generated [generatedAt])
-Hub: https://trdr.mrocontent.com.br
-
-## What was applied
-- ✅ [path]/tokens.css — TRDR CSS custom properties (snapshot v[catalog-version])
-- ✅ [path]/components.css — [implemented] component utility class blocks + typography
-- ✅ CLAUDE.md — design system rules for Claude Code
-- ✅ [N] violations fixed in [M] files
-- ✅ [global-css] updated with @import
-- ⚠️ [S] stub components flagged in MISSING_COMPONENTS.md (if any)
-- ✅ Migrated in [N] batches across 4 sub-phases — see DS_PROGRESS.md for details
-
-## Files modified
-[List each file and what changed]
-
-## Violations fixed
-[List by category with file:line references]
-
-## Manual steps required
-- [ ] **Fonts**: Ensure JetBrains Mono, Inter, and Roboto Mono are loaded
-  - Next.js: use `next/font/google` in layout.tsx (`JetBrains_Mono`, `Inter`, `Roboto_Mono`)
-  - Others: add Google Fonts `<link>` in HTML head
-- [ ] **Dark/light mode**: tokens.css uses [data-theme="light"] for overrides — add `data-theme="light"` to `<html>` to activate light mode
-- [ ] **Trading UI**: If this project has price/position displays, verify context.trading.* tokens are applied (see Hub: /tokens/semanticos)
-- [ ] **Stubs**: Review MISSING_COMPONENTS.md and decide whether to wait for canonical implementation in the Hub or hand-roll using the listed tokens
-- [ ] **Skipped files**: [list any files excluded from migration]
+**NEVER read the entire DS_ANALYSIS.md at once for large projects.** Only read the section needed for the current sprint.
 
-[If `stylingMode === 'mui'`, add these additional manual steps:]
-- [ ] **MUI CSS Variables mode**: If MUI version >= 6, add `cssVariables: true` to `createTheme()` for native CSS variable support. Without it, MUI's internal color calculations (alpha, lighten, darken) may produce invalid CSS when palette values are `var()` strings.
-- [ ] **MUI palette auto-generation**: Verify that `primary.light`, `primary.dark`, and `primary.contrastText` are all explicitly set with DS tokens. MUI auto-generates these from `main`, which fails when `main` is a `var()` string.
-- [ ] **MUI theme composition**: If the project composes themes across multiple files (`createTheme()` + `deepmerge`), verify that DS token references are preserved in the final merged theme.
-- [ ] **MUI component slots**: Complex MUI components (DataGrid, DatePicker, Autocomplete) have many internal slots not covered by the standard styleOverrides. Review these manually if used in the project.
-- [ ] **sx props audit**: Run a quick grep for `sx=\{\{.*#[0-9A-Fa-f]` to verify no hardcoded hex values remain in sx props.
+### Sprint Lifecycle (EVERY sprint follows this)
 
-## Missing DS tokens (flagged — no semantic token available)
-| Pattern | File | Suggestion |
-|---------|------|-----------|
-| `box-shadow: rgba(0,0,0,*)` | [file:line] | Request shadow token in Hub |
-| `linear-gradient(...)` non-TRDR | [file:line] | Request gradient token or remove |
-
-## Stub components encountered (See MISSING_COMPONENTS.md)
-[List each stub slug + figmaId that was referenced in the project]
-
-## Design System Reference
-- Hub: https://trdr.mrocontent.com.br
-- JSON catalog: https://trdr.mrocontent.com.br/components.json
-- Tokens: https://trdr.mrocontent.com.br/tokens/semanticos
-- Components: https://trdr.mrocontent.com.br/componentes
-- Rules: https://trdr.mrocontent.com.br/para-ia
-```
-
-After writing DS_MIGRATION.md, update `DS_PROGRESS.md`:
-```
-Sub-fase D: Final — ✅ COMPLETE
-Status: COMPLETE
-Completed: [ISO datetime]
-```
+1. Read `SPRINT_PLAN.md` — find current sprint (first PENDING or IN_PROGRESS)
+2. Read relevant section of `DS_ANALYSIS.md`
+3. Read `DS_PROGRESS.md` for current state
+4. Update SPRINT_PLAN.md: set current sprint `Status: IN_PROGRESS`
+5. Read the phase file for this sprint's sub-fase (from `phases/`)
+6. Execute the sprint's scope
+7. Update DS_PROGRESS.md with results
+8. Update SPRINT_PLAN.md: set current sprint `Status: COMPLETE`
+9. Output sprint summary with context clearing protocol
+10. **STOP**
 
 ---
 
-## EXECUTION SUMMARY
+## Component Loading Protocol
 
-After all steps are complete, output:
+Components are stored as individual JSON files in `data/components/`.
 
+**To load a component:**
 ```
-✅ TRDR Design System applied
-
-Created:
-  • [path]/tokens.css (snapshot v[catalog-version], dark + light mode)
-  • [path]/components.css ([implemented] component classes + typography)
-  • CLAUDE.md (design system context for Claude Code)
-  • DS_ANALYSIS.md (analysis snapshot)
-  • DS_PROGRESS.md (migration log — status: COMPLETE)
-  • DS_MIGRATION.md (migration log + manual checklist)
-  • MISSING_COMPONENTS.md ([S] stubs flagged) — only if applicable
-
-Modified:
-  • [global-css] — @import added
-  • [N] files — [X] violations replaced with semantic tokens
-
-Catalog: TRDR DS v[catalog-version] ([implemented]/[total] components)
-Hub: https://trdr.mrocontent.com.br
-→ Check DS_MIGRATION.md for manual steps
-→ Stubs not yet canonical: see MISSING_COMPONENTS.md
-→ Backup branch: `trdr-ds/backup-{timestamp}` — para desfazer: `/trdr-ds rollback`
-→ Para remover o backup após validar: `git branch -D trdr-ds/backup-{timestamp}`
-→ Algo deu errado? `/trdr-ds report` para enviar um bug report ao maintainer
+Read: <skill-dir>/data/components/<slug>.json
 ```
 
----
-
-## RESUME MODE (when invoked with `resume` argument)
-
-This is the primary way to continue a migration across multiple context windows. Each `/trdr-ds resume` picks up the next pending sprint.
-
-1. Look for `SPRINT_PLAN.md` and `DS_PROGRESS.md` at the project root.
-   - If neither found: output `❌ No previous migration found. Run /trdr-ds to start a new one.`
-   - If `DS_PROGRESS.md` has `Status: COMPLETE`: output `✅ Migration already complete (finished [date]). Run /trdr-ds to check for new violations.`
-
-2. Read `SPRINT_PLAN.md`. Find the first sprint with `Status: PENDING` or `Status: IN_PROGRESS`.
-   - If all sprints are `✅ COMPLETE`: mark migration as COMPLETE in DS_PROGRESS.md and output summary.
-
-3. Read `DS_PROGRESS.md` to understand overall state.
-
-4. Read **only the relevant section** of `DS_ANALYSIS.md` for the current sprint:
-   - Foundation sprint: read `§ Project` section only
-   - Violation sprint: read `§ By File` entries ONLY for the files listed in that sprint's scope
-   - Components sprint: read `§ Component Replacement Candidates`
-   - Final sprint: read `§ Logo Audit`
-
-5. Output a resume summary:
-   ```
-   Resumindo migração TRDR DS — [project name]
-
-   📋 Sprint Plan: [done]/[total] sprints completos ([percentage]%)
-
-   [For each sprint in SPRINT_PLAN.md:]
-   Sprint 1 — Foundation                          ✅
-   Sprint 2 — Violations: src/components/          ✅
-   Sprint 3 — Violations: src/pages/               🔄 ← retomando aqui
-   Sprint 4 — Violations: src/app/                 ⏳
-   Sprint 5 — Components                           ⏳
-   Sprint 6 — Final                                ⏳
-
-   Retomando: **Sprint [N] — [name]**
-   Escopo: [sprint scope description]
-   ```
-
-6. Execute the current sprint following the sprint lifecycle (read → execute → save → STOP).
-   All context is read from `SPRINT_PLAN.md` + `DS_ANALYSIS.md` (relevant section only) + `DS_PROGRESS.md` — never from conversation history.
-
----
-
-## STATUS MODE (when invoked with `status` argument)
-
-1. Look for `SPRINT_PLAN.md` and `DS_PROGRESS.md` at the project root.
-   - If neither found: output `No migration in progress. Run /trdr-ds to start.`
-
-2. Read `SPRINT_PLAN.md` and `DS_PROGRESS.md` — do NOT modify any files. Output:
-
+**To get the catalog index (lightweight):**
 ```
-## TRDR DS — Migration Status
-
-Project: [name] | Started: [date] | Status: [IN_PROGRESS/PAUSED/COMPLETE]
-Backup: [branch name or NONE]
-
-### Sprint Progress
-| Sprint | Scope | Files | Violations | Status |
-|--------|-------|-------|------------|--------|
-| 1 | Foundation | 4 | — | ✅ |
-| 2 | Violations: src/components/ | 12 | 34 | ✅ |
-| 3 | Violations: src/pages/ | 8 | 21 | 🔄 IN_PROGRESS |
-| 4 | Violations: src/app/ | 15 | 45 | ⏳ PENDING |
-| 5 | Violations: src/styles/ | 6 | 18 | ⏳ PENDING |
-| 6 | Components | [N] candidates | — | ⏳ PENDING |
-| 7 | Final | logos + icons | — | ⏳ PENDING |
-
-### Summary
-Sprints completos: [done]/[total] ([percentage]%)
-Violações corrigidas: [fixed]/[total_violations]
-Componentes aplicados: [applied]/[total_candidates]
-
-### Next Action
-→ Sprint [N]: [name] — `/trdr-ds resume`
-→ Para desfazer tudo: `/trdr-ds rollback`
+Read: <skill-dir>/data/index.json
 ```
 
----
-
-## SYNC MODE (when invoked as `/trdr-ds sync`)
-
-1. WebFetch `https://trdr.mrocontent.com.br/components.json` → save as `<skill-dir>/data/components.json`
-2. WebFetch `https://trdr.mrocontent.com.br/tokens.css` → save as `<skill-dir>/references/tokens.css`
-3. Compare new vs previous (if a previous version exists). Report:
-   - New components: [list slugs]
-   - Newly implemented: [list slugs that flipped from stub → implemented]
-   - Removed: [list slugs no longer in catalog]
-4. No project files are touched.
-
-If either fetch fails, report which one and exit. Do NOT touch the snapshot if the response is malformed (e.g., missing `components` array).
-
----
-
-## ROLLBACK MODE (when invoked as `/trdr-ds rollback`)
-
-1. Look for `DS_PROGRESS.md` at the project root.
-   - If not found: output `❌ Nenhuma migração encontrada. Nada para reverter.` and STOP.
-   - If `Backup branch:` line is `NONE (user opted out)`: output `❌ Nenhum backup foi criado (você optou por continuar sem backup durante a migração). Rollback manual necessário.` and STOP.
-
-2. Read the `Backup branch:` value from `DS_PROGRESS.md`. Save as `backupBranch`.
-   Read the `Original branch:` value. Save as `originalBranch`.
+The index contains slug, name, category, implemented flag, and dependencies for ALL components — but NO code blocks. Code blocks are loaded on demand from individual files.
 
-3. Verify the backup branch still exists:
-   ```bash
-   git rev-parse --verify {backupBranch} 2>/dev/null
-   ```
-   If it doesn't exist: output `❌ Branch de backup \`{backupBranch}\` não encontrado. Pode ter sido apagado manualmente.` and STOP.
+**When building components.css (Sub-fase A):**
+1. Read `data/index.json` to get list of implemented slugs
+2. For EACH implemented slug, read `data/components/<slug>.json` and extract `code.css`
+3. Concatenate all CSS blocks
 
-4. Confirm with the user:
-   ```
-   ⚠️ ROLLBACK: Isto vai reverter TODAS as alterações feitas pela migração TRDR DS.
-
-   Backup branch: {backupBranch}
-   Branch atual: {currentBranch}
-   Status da migração: {status from DS_PROGRESS.md}
-
-   Todos os arquivos modificados pela migração serão restaurados ao estado do backup.
-   Arquivos DS criados (DS_ANALYSIS.md, DS_PROGRESS.md, DS_MIGRATION.md, MISSING_COMPONENTS.md, CLAUDE.md, tokens.css, components.css) serão revertidos ou removidos.
-
-   Responda:
-   - "confirmar" — executar rollback
-   - "cancelar" — abortar
-   ```
-   **STOP. Wait for reply.**
-
-5. If `"cancelar"`: output `Rollback cancelado.` and STOP.
-
-6. If `"confirmar"`, execute the rollback:
-
-   a. Ensure we're on the original branch:
-   ```bash
-   git checkout {originalBranch}
-   ```
-
-   b. Reset the working tree to the backup state:
-   ```bash
-   git reset --hard {backupBranch}
-   ```
-
-7. Output:
-   ```
-   ✅ Rollback completo.
-
-   Branch `{originalBranch}` restaurado ao estado de `{backupBranch}`.
-   Todos os arquivos modificados pela migração foram revertidos.
-
-   O backup branch `{backupBranch}` ainda existe. Para removê-lo:
-   git branch -D {backupBranch}
-   ```
+**When applying components (Sub-fase C):**
+1. Read `data/index.json` to find candidates
+2. For EACH candidate being processed, read its individual component file
+3. Process ONE component at a time, then move to the next
 
 ---
 
-## REPORT MODE (when invoked as `/trdr-ds report` or triggered automatically)
-
-This mode generates a structured bug report and sends it to the skill maintainer via email.
-
-**Maintainer email:** `mrocontent@gmail.com`
-
-### When it triggers automatically
-
-After each sub-phase (A, B, C, D) completes — or fails to complete — evaluate these conditions:
-
-| Condition | Severity | Auto-report? |
-|-----------|----------|--------------|
-| Sub-phase crashed or could not complete (e.g., missing files, parse errors, Hub unreachable after local snapshot also missing) | CRITICAL | ✅ Yes |
-| Build fails after sub-phase changes (if detectable via `npm run build` or framework equivalent) | CRITICAL | ✅ Yes |
-| More than 30% of violations in a batch could not be mapped to any DS token (flagged as "no match") | HIGH | ✅ Yes |
-| Component replacement produced malformed JSX/HTML (unclosed tags, syntax errors caught by grep) | CRITICAL | ✅ Yes |
-| Rollback was invoked (indicates the migration went wrong enough to revert) | HIGH | ✅ Yes |
-
-When auto-report triggers, inform the developer:
-```
-⚠️ A skill detectou problemas críticos nesta migração.
-Um bug report será gerado e enviado ao maintainer (mrocontent@gmail.com).
-
-Deseja incluir observações adicionais no report?
-- Escreva seu comentário e pressione Enter
-- "pular" / "skip" — enviar sem comentários extras
-```
-**Wait for reply.** Save the developer's comment (if any) as `developerNotes` for inclusion in the report.
-
-### Manual invocation (`/trdr-ds report`)
-
-When invoked manually, the developer may optionally describe the problem:
-- `/trdr-ds report` — generates report from current state
-- `/trdr-ds report Violações não foram aplicadas nos arquivos .vue` — includes the description
-
-Ask the developer:
-```
-📝 Bug report — descreva o problema que encontrou com a skill:
-(Se já descreveu no comando, pressione Enter para confirmar)
-```
-**Wait for reply.** Save as `developerNotes`.
-
-### Step R1 — Collect project context
-
-Gather the following data silently (no output to the developer):
-
-1. **Project info:**
-   - `package.json` → name, framework, framework version, stylingMode detected
-   - Node.js version: `node --version`
-   - OS: read from environment (platform)
-   - Skill version: read from top of this file
-
-2. **Migration state:**
-   - Read `DS_ANALYSIS.md` (if exists) — extract: total violations, categories breakdown, total files
-   - Read `DS_PROGRESS.md` (if exists) — extract: current status, which sub-phases completed, which pending, and the full `## Execution Log` section (per-file audit trail with timestamps)
-   - Read `SPRINT_PLAN.md` (if exists) — extract: sprint progress
-   - Read `DS_MIGRATION.md` (if exists) — extract: manual items count
-
-3. **Error context:**
-   - If auto-triggered: capture the specific error/condition that triggered the report
-   - If manual: use `developerNotes`
-   - Last 3 files modified by the skill (from `DS_PROGRESS.md` batch logs)
-   - If build failed: capture the first 50 lines of build error output
-
-4. **Snapshot versions:**
-   - `data/components.json` → `generatedAt` and count of implemented components
-   - `references/tokens.css` → count of CSS variables (grep `--` in `:root`)
-
-### Step R2 — Generate DS_BUG_REPORT.md
-
-Write `DS_BUG_REPORT.md` at the project root:
+## Mapping Tables Protocol
 
-```markdown
-# TRDR DS — Bug Report
+Violation mapping tables (color→token, font→token, spacing→token, etc.) are in `data/mappings.json`.
 
-**Date:** [ISO datetime]
-**Skill version:** [version from SKILL.md]
-**Report type:** [AUTOMATIC | MANUAL]
-**Severity:** [CRITICAL | HIGH | MEDIUM]
+**Load ONLY during Sub-fase B (violations).** Do NOT preload during analysis or other phases.
 
 ---
 
-## Problem Description
-
-[developerNotes — or auto-trigger condition description]
-
-## Project Context
-
-| Field | Value |
-|-------|-------|
-| Project | [package.json name] |
-| Framework | [framework] [version] |
-| Styling mode | [stylingMode] |
-| Node.js | [version] |
-| OS | [platform] |
-
-## Migration State
-
-| Sub-phase | Status |
-|-----------|--------|
-| Analysis | [✅ COMPLETE / ⏳ PENDING / ❌ FAILED] |
-| A — Foundation | [status] |
-| B — Violations | [status — N/M batches done] |
-| C — Components | [status — N/M candidates done] |
-| D — Final | [status] |
-
-**Overall status:** [from DS_PROGRESS.md]
-**Backup branch:** [branch name or N/A]
-
-## Violation Summary
-
-| Category | Found | Fixed | Unfixable |
-|----------|-------|-------|-----------|
-| A — Hardcoded colors | [n] | [n] | [n] |
-| B — Hardcoded fonts | [n] | [n] | [n] |
-| C — Hardcoded spacing | [n] | [n] | [n] |
-| ... | ... | ... | ... |
-
-## Error Details
-
-[If build failed: first 50 lines of error output]
-[If unmapped violations: list of values that had no token match]
-[If component replacement failed: file path + what went wrong]
-
-## Files Affected
-
-[List of last files modified by the skill, from DS_PROGRESS.md]
-
-## Snapshot Info
-
-- Components catalog: [generatedAt] — [N] implemented / [M] total
-- Tokens CSS: [N] variables
-
-## Execution Log
-
-[Copy the entire `## Execution Log` section from DS_PROGRESS.md here — this is the full audit trail of every file the skill created, modified, skipped, or failed on, with timestamps]
+## Developer Dissatisfaction Detection
 
-| Timestamp | Phase | Action | File | Details |
-|-----------|-------|--------|------|---------|
-| ... | ... | ... | ... | ... |
+At every STOP checkpoint, if the developer expresses the implementation didn't work, trigger report mode. Match patterns (case-insensitive):
 
-## Developer Notes
-
-> [Raw text from the developer, if provided]
-```
-
-### Step R3 — Send via email (Resend API)
-
-Execute via Bash:
-
-```bash
-node -e "
-const https = require('https');
-
-const report = require('fs').readFileSync('DS_BUG_REPORT.md', 'utf8');
-const projectName = '[project-name-from-package.json]';
-const severity = '[CRITICAL|HIGH|MEDIUM]';
-const skillVersion = '[version]';
-
-const data = JSON.stringify({
-  from: 'TRDR DS Skill <onboarding@resend.dev>',
-  to: ['mrocontent@gmail.com'],
-  subject: '[TRDR DS ' + severity + '] Bug report — ' + projectName + ' (v' + skillVersion + ')',
-  text: report
-});
-
-const req = https.request({
-  hostname: 'api.resend.com',
-  path: '/emails',
-  method: 'POST',
-  headers: {
-    'Authorization': 'Bearer ' + process.env.RESEND_API_KEY,
-    'Content-Type': 'application/json',
-    'Content-Length': Buffer.byteLength(data)
-  }
-}, (res) => {
-  let body = '';
-  res.on('data', c => body += c);
-  res.on('end', () => {
-    if (res.statusCode >= 200 && res.statusCode < 300) {
-      console.log('OK: ' + body);
-    } else {
-      console.log('FAIL (' + res.statusCode + '): ' + body);
-    }
-  });
-});
-req.write(data);
-req.end();
-"
-```
-
-**If `RESEND_API_KEY` is not set in the environment:**
-```
-⚠️ RESEND_API_KEY não encontrada no ambiente.
-O report foi salvo em DS_BUG_REPORT.md mas não pôde ser enviado por email.
-
-Para configurar:
-1. Obtenha sua API key em https://resend.com/api-keys
-2. Adicione ao ambiente: export RESEND_API_KEY="re_xxxxxxxx"
-3. Ou adicione no .env do projeto e execute novamente /trdr-ds report
-```
-
-**If the email send fails (non-2xx response):**
-```
-⚠️ Falha ao enviar email (HTTP [status]): [response body]
-O report foi salvo localmente em DS_BUG_REPORT.md.
-Envie manualmente para mrocontent@gmail.com.
-```
-
-### Step R4 — Output to developer
-
-```
-[If email sent successfully:]
-✅ Bug report gerado e enviado.
-
-  📄 DS_BUG_REPORT.md (salvo no projeto)
-  📧 Email enviado para mrocontent@gmail.com
-  🏷️ Severidade: [CRITICAL|HIGH|MEDIUM]
-
-O maintainer será notificado e entrará em contato.
-
-[If email failed:]
-📄 Bug report salvo em DS_BUG_REPORT.md
-⚠️ Email não enviado — veja instruções acima.
-
-[In both cases:]
-→ Para continuar a migração: /trdr-ds resume
-→ Para reverter: /trdr-ds rollback
-```
-
-### DEVELOPER DISSATISFACTION DETECTION
-
-At every STOP checkpoint and at any point during the conversation, if the developer expresses that the implementation didn't work correctly, trigger REPORT MODE automatically. Match any of these patterns (case-insensitive, partial match):
-
-| Pattern (PT) | Pattern (EN) |
-|--------------|--------------|
-| "não funcionou" | "didn't work" |
-| "não deu certo" | "it's broken" |
+| PT | EN |
+|----|-----|
+| "nao funcionou" | "didn't work" |
+| "nao deu certo" | "it's broken" |
 | "deu errado" | "went wrong" |
 | "ficou errado" | "messed up" |
 | "quebrou" | "broke" |
-| "não aplicou" | "didn't apply" |
-| "não tá certo" | "not right" |
-| "tá errado" | "it's wrong" |
+| "nao aplicou" | "didn't apply" |
+| "nao ta certo" | "not right" |
+| "ta errado" | "it's wrong" |
 | "report" | "bug report" |
 
 When detected:
-1. Acknowledge the developer's feedback
-2. Execute REPORT MODE (Steps R1–R4) with `reportType: MANUAL` and `severity: HIGH`
-3. Use the developer's message as `developerNotes` — ask for additional details if the message is too vague (less than 10 characters)
-4. After sending the report, offer the developer options to continue:
-   ```
-   Responda:
-   - "rollback" — reverter todas as mudanças
-   - "continuar" — tentar prosseguir mesmo assim
-   - "parar" — salvar progresso e parar aqui
-   ```
+1. Acknowledge feedback
+2. Read `modes/report.md` and execute report mode
+3. After report, offer: rollback / continuar / parar
 
-### Auto-report integration points
+---
 
-When auto-report is triggered during a sub-phase, execute Steps R1–R4 **after** saving progress to `DS_PROGRESS.md` but **before** the STOP checkpoint. The sub-phase continues normally after the report — the developer can still choose to continue, stop, or rollback.
+## Phase Flow (for `apply` argument)
 
-Add to `DS_PROGRESS.md` when a report is sent:
 ```
-Bug report: DS_BUG_REPORT.md (sent [ISO datetime] — [AUTOMATIC|MANUAL] — [severity])
+analyze.md → STOP (wait approval)
+                ↓ "Apply"
+         foundation.md → STOP
+                ↓ "continuar"
+         violations.md → STOP (per batch)
+                ↓ all batches done
+         components.md → STOP
+                ↓ "continuar"
+         final.md → DONE
 ```
 
----
+Each arrow is a STOP checkpoint. Between any two checkpoints, the developer can:
+- `/clear` + `/trdr-ds resume` — clean context, continue
+- "parar" — save progress, stop
+- "rollback" — undo everything
+- "report" — send bug report
 
-## LIVE HUB REFERENCE (canonical fallback)
+---
 
-When the developer asks about a component, token, or rule that is not in the local snapshot, fetch from the Hub:
+## Live Hub Reference (canonical fallback)
 
 | Need | URL |
 |------|-----|
@@ -3324,5 +263,3 @@ When the developer asks about a component, token, or rule that is not in the loc
 | All components | https://trdr.mrocontent.com.br/componentes |
 | Rules & CLAUDE.md template | https://trdr.mrocontent.com.br/para-ia |
 | Full design spec | https://trdr.mrocontent.com.br/design-md |
-
-The Hub is the single source of truth. The local snapshot is the offline mirror. When in doubt, refresh the snapshot via `/trdr-ds sync`.