trdr-ds-install 1.8.1 → 1.11.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "trdr-ds-install",
-  "version": "1.8.1",
+  "version": "1.11.0",
   "description": "Installs the TRDR Design System skill for Claude Code",
   "bin": {
     "trdr-ds-install": "./bin/install.js"

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

@@ -2,11 +2,11 @@
 name: trdr-ds
 description: Applies the TRDR Design System to any project. Runs a multi-phase workflow - first analyzes the project and saves DS_ANALYSIS.md, then executes implementation in 4 checkpointed sub-phases (Foundation → Violations → Components → Final), each saving progress to DS_PROGRESS.md and resumable at any time. Trigger when developer mentions "apply design system", "implement TRDR DS", "add TRDR tokens", "design system setup", "migrar design system", "aplicar design system", or invokes /trdr-ds.
 user-invocable: true
-argument-hint: "[analyze|apply|foundation|violations|components|final|resume|status|sync|batch N|rollback]"
+argument-hint: "[analyze|apply|foundation|violations|components|final|resume|status|sync|batch N|rollback|report]"
 allowed-tools: [Read, Glob, Grep, Edit, Write, Bash, WebFetch]
 ---
 
-**Skill version:** 1.8.1
+**Skill version:** 1.11.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**.
@@ -37,6 +37,7 @@ Execute in multiple checkpointed phases: **PHASE 1: ANALYZE (saves DS_ANALYSIS.m
 | `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 |
 
 ---
@@ -60,7 +61,7 @@ Compare the result with the **Skill version** constant at the top of this file.
 - 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.8.1)
+  🔄 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)
@@ -111,10 +112,26 @@ Read `package.json` at the project root. Identify:
 | `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 | Insert token vars inside template literals / `theme` objects |
+| `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)
@@ -154,6 +171,20 @@ Read `tailwind.config.js` (or `tailwind.config.ts`) and check `theme.colors` and
 - 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):
@@ -307,8 +338,41 @@ 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–H occurrences
+- `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/`)
 
@@ -362,6 +426,29 @@ Use Grep (not Bash grep) to search for the patterns below. Group patterns from t
 
 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
@@ -374,6 +461,19 @@ For each file:line match found in Step 3.5, read the surrounding context (10 lin
 | `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
 {
@@ -574,6 +674,25 @@ All projects use the same checkpointed 4-sub-phase execution regardless of size.
 > **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+
 
@@ -632,9 +751,16 @@ Skill version: [X.Y.Z]
 ## Project
 Framework: [next.js|react|vue|html]
 Language: [ts|js]
-Styling: [css-modules|tailwind|plain-css|css-in-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]
@@ -654,6 +780,10 @@ Total files with violations: [total_files_with_violations]
 | 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:]
@@ -736,9 +866,15 @@ Estimated context windows: [N] (one per sprint + one for this analysis)
 ---
 
 ## 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
 
@@ -767,10 +903,14 @@ Estimated context windows: [N] (one per sprint + one for this analysis)
 ---
 
 ## Sprint [N-1] — Components
+[If stylingMode !== 'mui':]
 **Scope:** Implement DS components ([S] simple, [P] complex-preservable, [M] manual review)
-**Sub-fase:** C
 **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
 
 ---
@@ -895,8 +1035,38 @@ Install order: [topological — atomics first, then compounds by dependency]
 
 ## 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.
@@ -1015,7 +1185,7 @@ If `references/tokens.css` is missing in the skill directory:
 
 Update `DS_PROGRESS.md`:
 ```
-- [x] tokens.css — [path]/tokens.css
+- [x] tokens.css — [path]/tokens.css ([ISO datetime])
 ```
 
 ### Step 2 — Create components.css
@@ -1062,7 +1232,7 @@ After all component CSS blocks, append the text style utility classes:
 
 Update `DS_PROGRESS.md`:
 ```
-- [x] components.css — [path]/components.css
+- [x] components.css — [path]/components.css ([ISO datetime])
 ```
 
 ### Step 3 — Update global CSS
@@ -1080,7 +1250,7 @@ If the project already imports a different design system's variables and there a
 
 Update `DS_PROGRESS.md`:
 ```
-- [x] @import — [global-css-file]
+- [x] @import — [global-css-file] ([ISO datetime])
 ```
 
 ### Step 4 — Create CLAUDE.md
@@ -1163,26 +1333,195 @@ bg.primary (base) → bg.secondary/tertiary (content areas) → surface.* (cards
 - 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
+- [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.
 
 ---
 
@@ -1202,10 +1541,16 @@ For each batch listed as PENDING in `DS_PROGRESS.md` § Sub-fase B:
 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`:
+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:
@@ -1223,12 +1568,14 @@ For each batch listed as PENDING in `DS_PROGRESS.md` § Sub-fase B:
    - "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):
 
@@ -1242,9 +1589,11 @@ For each batch listed as PENDING in `DS_PROGRESS.md` § Sub-fase B:
    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.
 
 ---
 
@@ -1298,6 +1647,32 @@ For each batch listed as PENDING in `DS_PROGRESS.md` § Sub-fase B:
 - 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`):
@@ -1442,6 +1817,292 @@ When a CSS class has a `font-size` that maps to a DS text style, the fix is **tw
 
 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
@@ -1746,9 +2407,11 @@ 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
 ```
 
 **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.
 
 ---
 
@@ -2082,6 +2745,52 @@ Group new classes in a clearly labelled block at the bottom of the project's CSS
 /* ... */
 ```
 
+**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)
+
+5. **Hardcoded borderRadius** → replace with token:
+   ```tsx
+   // Before
+   sx={{ borderRadius: '12px' }}
+   // After
+   sx={{ borderRadius: 'var(--radius-md)' }}
+   ```
+
+6. **Conditional sx values** → replace both branches:
+   ```tsx
+   // Before
+   sx={{ color: isActive ? '#00D4FF' : '#A4A4A4' }}
+   // After
+   sx={{ color: isActive ? 'var(--content-brand)' : 'var(--content-tertiary)' }}
+   ```
+
+7. **Layout-only sx** (display, flex, grid, position, width, height) → keep as-is (not DS concern)
+
+Do NOT convert `sx` props to CSS classes — `sx` is idiomatic MUI and is acceptable when using DS tokens.
+
 ---
 
 ### Step 7 — Generate DS_MIGRATION.md
@@ -2118,6 +2827,13 @@ Hub: https://trdr.mrocontent.com.br
 - [ ] **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]
 
+[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.
+
 ## Missing DS tokens (flagged — no semantic token available)
 | Pattern | File | Suggestion |
 |---------|------|-----------|
@@ -2170,6 +2886,7 @@ Hub: https://trdr.mrocontent.com.br
 → 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
 ```
 
 ---
@@ -2325,6 +3042,275 @@ If either fetch fails, report which one and exit. Do NOT touch the snapshot if t
 
 ---
 
+## 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:
+
+```markdown
+# TRDR DS — Bug Report
+
+**Date:** [ISO datetime]
+**Skill version:** [version from SKILL.md]
+**Report type:** [AUTOMATIC | MANUAL]
+**Severity:** [CRITICAL | HIGH | MEDIUM]
+
+---
+
+## 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]
+
+| Timestamp | Phase | Action | File | Details |
+|-----------|-------|--------|------|---------|
+| ... | ... | ... | ... | ... |
+
+## 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" |
+| "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" |
+| "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
+   ```
+
+### 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.
+
+Add to `DS_PROGRESS.md` when a report is sent:
+```
+Bug report: DS_BUG_REPORT.md (sent [ISO datetime] — [AUTOMATIC|MANUAL] — [severity])
+```
+
+---
+
 ## 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: