trdr-ds-install 1.8.1 → 1.9.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "trdr-ds-install",
-  "version": "1.8.1",
+  "version": "1.9.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

@@ -6,7 +6,7 @@ argument-hint: "[analyze|apply|foundation|violations|components|final|resume|sta
 allowed-tools: [Read, Glob, Grep, Edit, Write, Bash, WebFetch]
 ---
 
-**Skill version:** 1.8.1
+**Skill version:** 1.9.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**.
@@ -60,7 +60,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.9.0)
 
   Responda:
   - `"atualizar"` / `"update"` — instalar a nova versão agora (requer reiniciar /trdr-ds após)
@@ -111,10 +111,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 +170,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 +337,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 +425,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 +460,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 +673,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 +750,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 +779,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 +865,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 +902,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
 
 ---
@@ -1163,6 +1302,20 @@ 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`:
@@ -1170,10 +1323,163 @@ Update `DS_PROGRESS.md`:
 - [x] CLAUDE.md — CLAUDE.md
 ```
 
+### 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)
@@ -1298,6 +1604,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 +1774,290 @@ 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
+```
+
+**STOP HERE. Wait for developer reply before starting Sub-fase D.**
+
+---
+
+**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
@@ -2082,6 +2698,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 +2780,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 |
 |---------|------|-----------|