trdr-ds-install 1.6.8 → 1.7.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "trdr-ds-install",
-  "version": "1.6.8",
+  "version": "1.7.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]"
+argument-hint: "[analyze|apply|foundation|violations|components|final|resume|status|sync|batch N|rollback]"
 allowed-tools: [Read, Glob, Grep, Edit, Write, Bash, WebFetch]
 ---
 
-**Skill version:** 1.6.8
+**Skill version:** 1.7.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**.
@@ -26,16 +26,17 @@ Execute in multiple checkpointed phases: **PHASE 1: ANALYZE (saves DS_ANALYSIS.m
 
 | Arg | Behaviour |
 |-----|-----------|
-| `analyze` *(default when none given)* | Run Phase 1 only — scan project, save `DS_ANALYSIS.md`, present plan. Do not modify any project file |
+| `analyze` *(default when none given)* | Run Phase 1 only — scan project, save `DS_ANALYSIS.md` + `SPRINT_PLAN.md`, present plan. Do not modify any project file |
 | `apply` | Run Phase 1 + Phase 2 (all 4 sub-phases, with STOP between each) |
 | `foundation` | Run Sub-fase A only — create tokens.css, components.css, CLAUDE.md, @imports. Requires DS_ANALYSIS.md |
 | `violations` | Run Sub-fase B only — process next pending violation batch. Requires DS_ANALYSIS.md + DS_PROGRESS.md |
 | `components` | Run Sub-fase C only — apply DS component classes. Requires DS_ANALYSIS.md + DS_PROGRESS.md |
 | `final` | Run Sub-fase D only — fix logos + generate DS_MIGRATION.md. Requires DS_PROGRESS.md |
-| `resume` | Read `DS_PROGRESS.md` from the project root and continue from the last checkpoint (detects current sub-fase automatically) |
-| `status` | Read `DS_PROGRESS.md` and display a progress summary table — no files modified |
+| `resume` | Read `SPRINT_PLAN.md` + `DS_PROGRESS.md`, find the next pending sprint, and execute it. Designed for use after `/clear` or in a new conversation — each sprint is self-contained |
+| `status` | Read `SPRINT_PLAN.md` + `DS_PROGRESS.md` and display sprint progress table — no files modified |
 | `batch [N]` | Override default violation batch size (default: 5 files/batch) |
 | `sync` | Re-fetch `https://trdr.mrocontent.com.br/components.json` and `https://trdr.mrocontent.com.br/tokens.css`, overwrite `data/components.json` and `references/tokens.css` in the skill directory, report the diff. No project changes. |
+| `rollback` | Read `DS_PROGRESS.md` to find the backup branch, reset working branch to that state, remove DS artifacts. Requires `DS_PROGRESS.md` with a `Backup branch:` entry |
 | `--latest` *(modifier on `analyze` or `apply`)* | Same as `sync` first, then continue normally |
 
 ---
@@ -59,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.6.8)
+  🔄 Nova versão da skill disponível: trdr-ds-install@[registry-version] (instalada: 1.7.0)
 
   Responda:
   - `"atualizar"` / `"update"` — instalar a nova versão agora (requer reiniciar /trdr-ds após)
@@ -337,6 +338,12 @@ Use Grep (not Bash grep) to search for the patterns below. Group patterns from t
 | `card` | `<Card`, `\.card`, `<article` |
 | `boleta` | `<Boleta`, `boleta` |
 | `janela` | `<Janela`, `trading.{0,10}window` |
+| `tabela-cotacoes` | `<TabelaCotacoes`, `.quotes-table`, `.price-list`, `<table` with price/ticker/cotacao columns |
+| `tabela-ordens` | `<TabelaOrdens`, `.orders-table`, `.order-list`, `<table` with order/position columns |
+| `floating-menu` | `<FloatingMenu`, `.floating-menu`, `position:absolute` + `z-index` + list pattern |
+| `news-card` | `<NewsCard`, `.news-card`, `.article-card`, `<article` with image + title + date pattern |
+| `header` | `<Header`, `<header`, `.header`, `.navbar`, `<nav` at top-level page position |
+| `badge` | `<Badge`, `.badge`, `.tag`, `.chip`, `.label-status`, `<span` with short status-like text |
 
 **Rules:**
 - For each slug, count the distinct files that matched (not total lines) — one file counts as one occurrence.
@@ -355,7 +362,55 @@ 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.
 
-**Output:** `replacementCandidates[]` — passed to Step 5 template and Phase 2 Step 6.
+**Output:** `replacementCandidates[]` — passed to Step 3.5b, Step 5 template and Phase 2 Step 6.
+
+### Step 3.5b — Capture structural context for each candidate
+
+For each file:line match found in Step 3.5, read the surrounding context (10 lines before and after the match) and classify the replacement complexity:
+
+| Classification | Criteria | Phase 2 action |
+|---|---|---|
+| `simple` | Element has only text content. No event handlers (`onClick`, `onChange`, etc.), no conditional rendering (`{condition && ...}`, ternary), no dynamic props beyond basic HTML attributes (`id`, `name`, `class`, `placeholder`, `type`) | Full DS component replacement — swap the element entirely with the DS component structure, adapting content |
+| `complex-preservable` | Element has event handlers, data bindings (`value={state}`, `checked={state}`), refs, or conditional rendering, BUT the DOM structure maps cleanly to a DS component | Apply DS structure + classes, preserving ALL handlers, bindings, and conditional logic |
+| `complex-manual` | Element has deeply nested custom logic, multiple conditional branches affecting structure, dynamically generated children, or domain-specific behavior that doesn't map to any DS component pattern | Flag for manual review in DS_MIGRATION.md — do NOT auto-modify |
+
+**For each candidate, store:**
+```json
+{
+  "slug": "button",
+  "file": "src/components/Hero.tsx",
+  "line": 42,
+  "classification": "simple",
+  "existingContent": "Get Started",
+  "existingHandlers": [],
+  "existingClasses": "btn-primary hero-cta",
+  "existingProps": [],
+  "suggestedDsVariant": "trdr-btn-primary"
+}
+```
+
+**Variant detection rules (by signals in existing code):**
+
+| Existing pattern signals | Suggested DS variant |
+|---|---|
+| `.btn-primary`, `.cta`, `type="submit"`, prominent/brand color (cyan, blue) | `trdr-btn-primary` |
+| `.btn-secondary`, `.btn-cancel`, muted/gray color | `trdr-btn-secondary` |
+| `.btn-outline`, `.btn-ghost`, transparent background + border | `trdr-btn-ghost` |
+| `.btn-danger`, `.btn-delete`, red/orange/destructive color | `trdr-btn-destructive` |
+| `.btn-link`, `<a>` styled as button, no border/bg | `trdr-btn-link` |
+| `type="text"`, `type="email"`, `type="password"`, `type="search"`, `<textarea>` | `trdr-text-input` |
+| `type="checkbox"` | `trdr-checkbox` |
+| `type="radio"` | `trdr-radio-button` |
+| `role="switch"`, `.toggle`, `.switch` | `trdr-switch` |
+| `<select>`, `role="listbox"` | `trdr-dropdown` |
+| `role="tablist"`, `.tabs` | `trdr-abas` or `trdr-segment-control` |
+| `.badge` + green/success color | `trdr-badge-success` |
+| `.badge` + blue/brand color | `trdr-badge-brand` |
+| `.badge` + yellow/warning color | `trdr-badge-warning` |
+| `.badge` + neutral/gray color | `trdr-badge-neutral` |
+| `<Tooltip>`, `role="tooltip"`, `data-tooltip` | `trdr-tooltip` |
+
+**Output:** Updated `replacementCandidates[]` — each entry now includes `classification`, `existingContent`, `existingHandlers`, `existingProps`, and `suggestedDsVariant`.
 
 ### Step 3.6 — Logo audit
 
@@ -480,9 +535,32 @@ All projects use the same checkpointed 4-sub-phase execution regardless of size.
 | J — SVG icons inline | N | `<svg>` in index.html (search, close, play icons) |
 | K — Logo incorrect/missing | N | `<span>TRDR</span>` used as logo in index.html:45 |
 
-### TRDR COMPONENTS REFERENCED IN PROJECT:
-(Candidatos detectados no Step 3.5 — substituição recomendada)
+### TRDR COMPONENTS — IMPLEMENTATION PLAN:
+(Candidatos detectados no Step 3.5 — com classificação de complexidade)
+
+#### Simple swaps (substituição completa pelo componente DS):
+| Componente | Variante DS | Arquivo | Conteúdo atual |
+|------------|------------|---------|----------------|
+[For each candidate where classification === 'simple':]
+| [c.name] | [suggestedDsVariant] | [file:line] | "[existingContent]" |
+
+#### Complex-preservable (estrutura DS + lógica preservada):
+| Componente | Arquivo | Handlers/Props preservados |
+|------------|---------|----------------------------|
+[For each candidate where classification === 'complex-preservable':]
+| [c.name] | [file:line] | [existingHandlers], [existingProps] |
+
+#### Manual review (complexidade alta — sem modificação automática):
+| Componente | Arquivo | Motivo |
+|------------|---------|--------|
+[For each candidate where classification === 'complex-manual':]
+| [c.name] | [file:line] | [reason] |
 
+> **Simple:** substituição completa, conteúdo adaptado do projeto.
+> **Complex-preservable:** estrutura DS aplicada, toda lógica (handlers, bindings, conditionals) preservada.
+> **Manual:** flagged em DS_MIGRATION.md para revisão pelo desenvolvedor.
+
+#### Stubs e catálogo:
 | Componente | Status no catálogo | Arquivos detectados |
 |------------|--------------------|---------------------|
 [For each entry in replacementCandidates[], look up the slug in the loaded catalog:]
@@ -586,8 +664,28 @@ Total files with violations: [total_files_with_violations]
 [list all violations with line numbers]
 
 ## Component Replacement Candidates
-[For each entry in replacementCandidates[]:]
-- [slug]: [file:line] — [implemented ✅ | stub ⚠️]
+
+### Simple swaps (full DS component replacement)
+[For each candidate where classification === 'simple':]
+| Component | DS Variant | File | Existing Content |
+|-----------|-----------|------|------------------|
+| [c.name] | [suggestedDsVariant] | [file:line] | "[existingContent]" |
+
+### Complex-preservable (DS structure + preserved logic)
+[For each candidate where classification === 'complex-preservable':]
+| Component | File | Handlers/Props Preserved |
+|-----------|------|--------------------------|
+| [c.name] | [file:line] | [existingHandlers], [existingProps] |
+
+### Manual review required
+[For each candidate where classification === 'complex-manual':]
+| Component | File | Reason |
+|-----------|------|--------|
+| [c.name] | [file:line] | [brief description of why it's complex] |
+
+### Stubs (not yet implemented in DS)
+[For each candidate where c.implemented === false:]
+- [slug]: [file:line] — ⚠️ stub (figmaId: [c.figmaId])
 
 ## Logo Audit
 [For each file in logoAudit.correct:] - [path] — ✅ CORRECT
@@ -604,9 +702,97 @@ Batch size: [N] (default 5)
 - ...
 ```
 
-After writing `DS_ANALYSIS.md`, confirm with:
+### Step 5.6 — Generate SPRINT_PLAN.md
+
+After writing `DS_ANALYSIS.md`, generate `SPRINT_PLAN.md` at the project root. This file breaks the entire migration into **self-contained sprints** — each sprint can be executed in an independent conversation with a clean context window.
+
+**Sprint sizing rules:**
+- Each sprint should process at most **15 files** (keeps context comfortable even for complex files)
+- Group files by **folder** (natural boundary — violations in the same folder share CSS patterns)
+- If a folder has >15 files, split into sub-sprints (e.g., `Sprint 3a`, `Sprint 3b`)
+- Foundation, Components, and Final are each their own sprint (regardless of file count)
+
+**Generate the plan:**
+
+```markdown
+# TRDR DS — Sprint Plan
+Generated: [ISO datetime]
+Project: [project name]
+Total sprints: [N]
+Estimated context windows: [N] (one per sprint + one for this analysis)
+
+> Cada sprint é independente. Entre sprints, você pode limpar o contexto (`/clear`) ou iniciar uma nova conversa.
+> Para continuar: `/trdr-ds resume`
+
+---
+
+## Sprint 1 — Foundation
+**Scope:** Create tokens.css, components.css, CLAUDE.md, @import in global CSS
+**Sub-fase:** A
+**Files to create:** 3 (tokens.css, components.css, CLAUDE.md)
+**Files to modify:** 1 (global CSS)
+**Status:** PENDING
+
+---
+
+## Sprint 2 — Violations: [first-folder/]
+**Scope:** Fix [N] violations in [M] files
+**Sub-fase:** B
+**Files:** [list each file path]
+**Violation count:** [N] (A:[n], B:[n], C:[n], ...)
+**Status:** PENDING
+
+---
+
+## Sprint 3 — Violations: [second-folder/]
+**Scope:** Fix [N] violations in [M] files
+**Sub-fase:** B
+**Files:** [list each file path]
+**Violation count:** [N]
+**Status:** PENDING
+
+---
+
+[... repeat for each folder/batch ...]
+
+---
+
+## Sprint [N-1] — Components
+**Scope:** Implement DS components ([S] simple, [P] complex-preservable, [M] manual review)
+**Sub-fase:** C
+**Candidates:** [total]
+**Status:** PENDING
+
+---
+
+## Sprint [N] — Final
+**Scope:** Replace logos, replace SVG icons with Material Icons (size-preserved), generate DS_MIGRATION.md
+**Sub-fase:** D
+**Status:** PENDING
 ```
-✅ DS_ANALYSIS.md salvo. Revise o plano acima e responda 'Apply' para iniciar.
+
+**Sprint naming convention:**
+- Foundation sprints: `Sprint 1 — Foundation`
+- Violation sprints: `Sprint N — Violations: [folder/]`
+- If folder split: `Sprint Na — Violations: [folder/] (part 1 of 2)`
+- Component sprint: `Sprint N — Components`
+- Final sprint: `Sprint N — Final`
+
+After writing `SPRINT_PLAN.md`, update the output to include the sprint summary:
+
+```
+✅ DS_ANALYSIS.md e SPRINT_PLAN.md salvos.
+
+📋 Sprint Plan: [N] sprints planejados
+  Sprint 1: Foundation (4 arquivos)
+  Sprint 2-[M]: Violations ([total_files] arquivos em [folders] pastas)
+  Sprint [M+1]: Components ([candidates] candidatos)
+  Sprint [N]: Final (logos + ícones + DS_MIGRATION.md)
+
+Cada sprint é independente — entre sprints, limpe o contexto com /clear.
+Para continuar de qualquer ponto: /trdr-ds resume
+
+Responda 'Apply' para iniciar o Sprint 1.
 ```
 
 **STOP HERE. Wait for explicit developer approval before Phase 2.**
@@ -620,13 +806,42 @@ Parse the developer's reply:
 - Extract skip paths from `"Apply, skip [path]"` → exclude those from violation processing.
 - `"Only tokens"` → skip Sub-fases B and C (no violation fixes, no component banners).
 
-**Context rule (critical):** At the start of EVERY sub-phase, before doing anything else:
-1. Read `DS_ANALYSIS.md` from the project root — this is the canonical source of all analysis data
-2. Read `DS_PROGRESS.md` from the project root — this is the canonical source of progress state
+### Sprint execution model
+
+Each sprint is a **self-contained unit of work** designed to fit comfortably in a single context window. The developer can `/clear` or start a new conversation between sprints and resume with `/trdr-ds resume`.
+
+**Context rule (critical):** At the start of EVERY sprint, before doing anything else:
+1. Read `SPRINT_PLAN.md` from the project root — find the current sprint (first with `Status: PENDING` or `Status: IN_PROGRESS`)
+2. Read `DS_ANALYSIS.md` from the project root — but ONLY the sections relevant to the current sprint's scope (e.g., for a violation sprint, only read the `§ By File` entries for the files listed in that sprint)
+3. Read `DS_PROGRESS.md` from the project root — this is the canonical source of progress state
+
+**Never read the entire DS_ANALYSIS.md at once for large projects.** Only read the sections needed for the current sprint. This prevents context overflow.
 
 Never rely on conversation memory for violation counts, file paths, batch assignments, or framework detection. Always re-read from files.
 
-Report progress after each major step.
+**Sprint lifecycle:**
+1. Read state files (SPRINT_PLAN.md + relevant sections of DS_ANALYSIS.md + DS_PROGRESS.md)
+2. Update SPRINT_PLAN.md: set current sprint `Status: IN_PROGRESS`
+3. Execute the sprint's scope (Foundation / Violations for specific files / Components / Final)
+4. Update DS_PROGRESS.md with results
+5. Update SPRINT_PLAN.md: set current sprint `Status: ✅ COMPLETE`
+6. Output sprint summary with next sprint info
+7. **STOP** — wait for developer to continue or `/clear` + `/trdr-ds resume`
+
+**End-of-sprint output (MANDATORY after every sprint):**
+```
+✅ Sprint [N] completo — [sprint name]
+[Brief summary of what was done: files modified, violations fixed, components applied, etc.]
+
+📋 Progresso: [done]/[total] sprints ([percentage]%)
+Próximo: Sprint [N+1] — [next sprint name]
+
+→ Você pode limpar o contexto agora: /clear
+→ Para continuar: /trdr-ds resume
+→ Para ver status completo: /trdr-ds status
+```
+
+Report progress after each major step within a sprint.
 
 ### Step 0 — Initialize checkpoint
 
@@ -638,6 +853,10 @@ Started: [ISO datetime]
 Project: [project name from package.json]
 Batch size: [N]
 Status: IN_PROGRESS
+Backup branch: [branch-name or NONE]
+Original branch: [branch-name]
+Sprint plan: SPRINT_PLAN.md
+Current sprint: 1
 
 ## Sub-fase A: Foundation — PENDING
 - [ ] tokens.css
@@ -667,6 +886,99 @@ Total de lotes: [N]
 [empty — filled during execution]
 ```
 
+### Step 0.5 — Git backup (safety net)
+
+Before modifying any project file, create a git backup so the entire migration can be rolled back.
+
+**Step 0.5a — Check git status:**
+
+Run via Bash:
+```bash
+git rev-parse --is-inside-work-tree 2>/dev/null
+```
+
+**If NOT a git repo:**
+```
+⚠️ Este projeto não tem repositório git. Um backup automático não é possível sem git.
+
+Responda:
+- "git init" — inicializar repositório git e criar backup antes de continuar
+- "continuar sem backup" — prosseguir sem safety net (irreversível)
+```
+**STOP. Wait for reply.**
+
+If reply is `"git init"`:
+1. Run: `git init`
+2. Run: `git add -A && git commit -m "Initial commit (before TRDR DS migration)"`
+3. Continue to Step 0.5b.
+
+If reply is `"continuar sem backup"`:
+- Update `DS_PROGRESS.md`: set `Backup branch: NONE (user opted out)`
+- Skip to Sub-fase A.
+
+**If IS a git repo:** Continue to Step 0.5b.
+
+**Step 0.5b — Check for existing backup branch:**
+
+Run via Bash:
+```bash
+git branch --list "trdr-ds/backup-*"
+```
+
+If one or more `trdr-ds/backup-*` branches exist:
+```
+⚠️ Backup branch(es) encontrado(s) de execução anterior:
+[list each branch name]
+
+Responda:
+- "manter" — criar novo backup com timestamp diferente (mantém os anteriores)
+- "substituir" — apagar o backup anterior e criar um novo
+```
+**STOP. Wait for reply.**
+
+If `"substituir"`: delete all existing `trdr-ds/backup-*` branches via `git branch -D [name]` for each.
+
+**Step 0.5c — Create the backup branch:**
+
+1. Record the current branch name:
+   ```bash
+   git branch --show-current
+   ```
+   Save as `originalBranch`. If in detached HEAD state (empty output), save the commit hash via `git rev-parse HEAD` instead.
+
+2. Generate timestamp branch name: `trdr-ds/backup-{YYYY-MM-DD-HHmmss}` (use current local time).
+
+3. Check for uncommitted changes:
+   ```bash
+   git status --porcelain
+   ```
+   If output is non-empty (uncommitted changes exist):
+   ```bash
+   git stash push -m "trdr-ds-pre-migration-stash"
+   ```
+
+4. Create the backup branch from current HEAD:
+   ```bash
+   git branch trdr-ds/backup-{timestamp}
+   ```
+
+5. If stash was created in step 3, pop it back:
+   ```bash
+   git stash pop
+   ```
+
+6. Update `DS_PROGRESS.md`:
+   ```
+   Backup branch: trdr-ds/backup-{timestamp}
+   Original branch: {originalBranch}
+   ```
+
+7. Output:
+   ```
+   ✅ Backup criado: branch `trdr-ds/backup-{timestamp}`
+   Para desfazer toda a migração a qualquer momento: `/trdr-ds rollback`
+   ```
+
 ---
 
 ## Sub-fase A: Foundation
@@ -828,9 +1140,10 @@ bg.primary (base) → bg.secondary/tertiary (content areas) → surface.* (cards
 - HTML/Vue: `<span class="material-icons mi-sm">nome</span>` via Google Fonts CDN
 - React: `<NomeIcon />` via @mui/icons-material
 - Cor: SEMPRE via classe CSS com token DS (`.icon-brand`, `.icon-success`, `.icon-dim`, etc.)
-- Tamanho: via classe `.mi-sm` (16px), `.mi-xs` (14px); padrão sem classe = 20px
+- Tamanho: `.mi-2xs` (12px), `.mi-xs` (14px), `.mi-sm` (16px), default (20px), `.mi-lg` (24px), `.mi-xl` (28px), `.mi-2xl` (32px)
+- Para tamanhos não padrão: `style="font-size:Npx"` (aceito APENAS para font-size de ícones, nunca para cor)
 - **NUNCA** usar `<svg>` inline para ícones
-- **NUNCA** usar `style=""` para cor ou tamanho de ícones
+- **NUNCA** usar `style=""` para cor de ícones
 
 ## Logo
 - HTML: `<img src="logo-trdr.svg" alt="TRDR" height="24">`
@@ -1114,90 +1427,297 @@ When a CSS class has a `font-size` that maps to a DS text style, the fix is **tw
 ## Sub-fase C: Components
 
 > **Before starting:** Read `DS_ANALYSIS.md` (§ Component Replacement Candidates) and `DS_PROGRESS.md` (§ Sub-fase C) from the project root.
+> Also read `data/components.json` from the skill directory to have all component code blocks available.
 
 Update `DS_PROGRESS.md`: set `Sub-fase C: Components — IN_PROGRESS`.
 
-### Step 6 — Apply DS component classes to HTML/JSX/Vue elements
+### Step 6 — Implement DS components in project files
 
-Use the `replacementCandidates[]` list from `DS_ANALYSIS.md` § Component Replacement Candidates. For each entry:
+Process candidates from `DS_ANALYSIS.md` § Component Replacement Candidates in three passes:
+1. **Pass 1** — Simple replacements (full DS component swap)
+2. **Pass 2** — Complex-preservable (DS structure + logic preservation)
+3. **Pass 3** — Manual review flagging (no auto-modification)
 
-1. **Look up the component** in the loaded catalog by slug (or by category, if slug is ambiguous).
+---
 
-2. **If `c.implemented === true`** — apply DS classes to the actual elements (CSS alone is not enough):
+#### Step 6 — Pass 1: Simple replacements
 
-   **Step 6a — Identify the project's custom CSS class** for that component role.
-   Grep the CSS/HTML/JSX for classes like `.btn-enroll`, `.lang-selector`, `.search-bar`, etc. that serve the same function.
+For each candidate classified as `simple` in DS_ANALYSIS.md:
 
-   **Step 6b — Map to DS classes:**
-   | Component role | DS classes to add |
-   |---|---|
-   | Primary / CTA button | `.trdr-btn .trdr-btn-primary` (+ `.trdr-btn-lg` if height ≥ 28px) |
-   | Ghost / outline button | `.trdr-btn .trdr-btn-ghost` |
-   | Secondary button | `.trdr-btn .trdr-btn-secondary` |
-   | Text input / search | `.trdr-text-input` |
-   | Segment / tab control | `.trdr-segment-control` on wrapper + `.trdr-segment` on each item |
-   | Active segment item | also add `.trdr-segment-active` |
-   | Inactive segment item | also add `.trdr-segment-inactive` |
-   | Generic card | `.card` (only for non-domain-specific cards) |
-   | Dropdown / select | `.trdr-dropdown` |
-
-   **Step 6c — Apply to HTML/JSX by framework:**
-   | stylingMode | How to add |
-   |---|---|
-   | `plain-css` | `class="custom-btn trdr-btn trdr-btn-primary"` |
-   | React/Next.js | `className="custom-btn trdr-btn trdr-btn-primary"` |
-   | Vue | `class="custom-btn trdr-btn trdr-btn-primary"` |
-   | JS template strings | Update the string template that generates the HTML |
-
-   **For JS-toggled state classes** (active/inactive managed by JavaScript):
-   - Keep the original class for `querySelector` selectors
-   - Add DS classes to the element's initial HTML
-   - Update any `classList.toggle`, `classList.add`, `classList.remove`, `setAttribute('class', ...)` calls to also toggle the DS state classes (e.g. `trdr-segment-active` / `trdr-segment-inactive`)
-   - Remove base CSS from the custom class (let DS provide height, padding, font, border, border-radius, background, color, cursor, transition)
-   - Keep only state-specific overrides in the custom class (e.g. `.custom-btn.active { border-color: var(--teal-mid); }`)
-
-   **Step 6d — Clean up redundant custom CSS:**
-   For each custom class that received DS classes, remove these properties (now provided by DS):
-   - `height`, `padding`, `font-family`, `font-size`, `font-weight`, `border`, `border-radius`, `background`, `color`, `cursor`, `transition`, `display`, `align-items`, `justify-content`
-   - Keep: `width`, `min-width`, `gap`, position-specific props, state overrides
-
-   **Step 6e — Document in DS_PROGRESS.md:**
+1. **Load the DS component code** from `data/components.json` — look up the component by slug and read `c.code.html` (for plain-css/tailwind projects) or `c.code.react` (for React/Next.js projects) or adapt for Vue.
+
+2. **Adapt the content** — the DS component's code block has placeholder content (e.g., "Confirmar", "Badge"). Replace placeholders with the ACTUAL content from the project:
+   - Button text: extract the text content from the existing `<button>` element
+   - Input placeholder: extract the existing `placeholder` attribute
+   - Label text: extract the existing label/text node
+   - Badge text: extract the existing text content
+   - Preserve `id`, `name`, `data-*`, `aria-*` attributes from the original element
+
+3. **Select the correct variant** using `suggestedDsVariant` from DS_ANALYSIS.md.
+
+4. **Replace the element in the source file** — examples by component:
+
+   **Buttons (slug: `button`):**
+   ```html
+   <!-- BEFORE -->
+   <button class="btn-primary hero-cta">Get Started</button>
+   <!-- AFTER -->
+   <button class="trdr-btn trdr-btn-primary">Get Started</button>
    ```
-   ### Componentes DS Aplicados
-   - [x] .btn-enroll → .trdr-btn .trdr-btn-ghost .trdr-btn-lg (index.html, cursos.js)
-   - [x] .lang-selector → .trdr-segment-control + .trdr-segment (index.html)
-   - [ ] .search-bar → .trdr-text-input (estrutura incompatível com ícone — revisão manual)
+   - Remove custom CSS classes that duplicate DS styles (background, padding, height, font, border, border-radius, cursor, transition)
+   - Keep classes used for layout/positioning (margin, width, grid placement)
+   - Keep `id`, `name`, `type`, `data-*`, `aria-*` attributes
+
+   **Text inputs (slug: `text-input`):**
+   ```html
+   <!-- BEFORE -->
+   <input type="text" class="search-bar" placeholder="Search...">
+   <!-- AFTER -->
+   <input type="text" class="trdr-text-input" placeholder="Search...">
    ```
+   - If the existing input has a wrapper with icon (search icon + input), restructure to match DS anatomy:
+     ```html
+     <div class="trdr-text-input-wrapper">
+       <span class="material-icons mi-sm icon-muted">search</span>
+       <input type="text" class="trdr-text-input" placeholder="Search...">
+     </div>
+     ```
 
-   **Do NOT replace domain-specific components** (course cards, lesson rows, trading panels, etc.) — document them as "sem equivalente DS".
+   **Checkboxes (slug: `checkbox`):**
+   ```html
+   <!-- BEFORE -->
+   <input type="checkbox" id="terms"> <label for="terms">Accept terms</label>
+   <!-- AFTER -->
+   <label class="trdr-checkbox">
+     <input type="checkbox" id="terms" />
+     <span class="trdr-checkbox-box"></span>
+     <span>Accept terms</span>
+   </label>
+   ```
+   - DS checkbox requires a specific DOM structure (label > input + box-span + text-span)
+   - Preserve `id`, `name`, `checked`, `disabled` attributes from the original input
 
-3. **If `c.implemented === false`** (stub):
-   - Add this banner comment above the affected element in the source file:
-     ```
-     /* TRDR DS — <c.name> (figmaId: <c.figmaId>) */
-     /* Implementação canônica pendente. Consulte https://trdr.mrocontent.com.br/componentes/<c.slug> */
-     /* Tokens recomendados: <list c.tokens[].token> */
-     ```
-   - Append an entry to `MISSING_COMPONENTS.md`:
-     ```markdown
-     ## <c.name>
-     - Slug: `<c.slug>` | figmaId: `<c.figmaId>` | Category: `<c.category>`
-     - Found in: <list of file:line>
-     - Description: <c.description>
-     - Recommended tokens: <c.tokens[]>
-     - Status: ⚠️ stub — code blocks pending
-     ```
+   **Radio buttons (slug: `radio-button`):**
+   Similar to checkbox — restructure to DS anatomy while preserving `name`, `value`, `checked`.
 
-4. **If no slug matches** the detected pattern:
-   - Flag the pattern in `MISSING_COMPONENTS.md` under "Unmapped patterns" with the file location and a one-line description of the UI need.
+   **Switches (slug: `switch`):**
+   ```html
+   <!-- BEFORE -->
+   <div class="toggle"><input type="checkbox"></div>
+   <!-- AFTER -->
+   <button class="trdr-switch" role="switch" aria-checked="false">
+     <span class="trdr-switch-track"><span class="trdr-switch-knob"></span></span>
+     <span>Label text</span>
+   </button>
+   ```
+
+   **Dropdowns (slug: `dropdown`):**
+   ```html
+   <!-- BEFORE -->
+   <select class="lang-selector"><option>PT</option><option>EN</option></select>
+   <!-- AFTER -->
+   <select class="trdr-dropdown"><option>PT</option><option>EN</option></select>
+   ```
+   - Preserve all `<option>` children, `name`, `id`, `value` attributes
+
+   **Badges (slug: `badge`):**
+   ```html
+   <!-- BEFORE -->
+   <span class="badge badge-success">Active</span>
+   <!-- AFTER -->
+   <span class="trdr-badge trdr-badge-success">Active</span>
+   ```
+   - Detect variant from existing color/class: green/success → `trdr-badge-success`, blue/brand → `trdr-badge-brand`, etc.
+
+   **Segmented controls / tabs (slug: `segmented-control`, `abas`):**
+   ```html
+   <!-- BEFORE -->
+   <div class="tabs">
+     <button class="tab active">Tab 1</button>
+     <button class="tab">Tab 2</button>
+   </div>
+   <!-- AFTER -->
+   <div class="trdr-segment-control">
+     <button class="trdr-segment trdr-segment-active">Tab 1</button>
+     <button class="trdr-segment trdr-segment-inactive">Tab 2</button>
+   </div>
+   ```
+
+   **Tooltips (slug: `tooltip`):**
+   - If `title=""` attribute: remove `title`, add DS tooltip structure around the element
+   - If `data-tooltip=""`: adapt to DS tooltip pattern
+   - Preserve the tooltip content text
+
+5. **Icons inside replaced components:** When the original element contained an inline SVG icon (e.g., Button with search icon), replace that SVG immediately with a Material Icon `<span>` using the correct size class from Step 6.6c-2 rules. Do NOT leave inline SVGs inside new DS component structures — this is an exception to "SVG replacement happens in Sub-fase D."
+
+6. **Clean up redundant CSS** — for each replaced element's custom class, remove properties now provided by DS:
+   - Remove: `height`, `padding`, `font-family`, `font-size`, `font-weight`, `border`, `border-radius`, `background`, `color`, `cursor`, `transition`, `display`, `align-items`, `justify-content`
+   - Keep: `width`, `min-width`, `gap`, position-specific props, state overrides, layout props (margin, grid-area)
+
+7. **Document in DS_PROGRESS.md** each replacement:
+   ```
+   - [x] button: src/Hero.tsx:42 — "Get Started" → trdr-btn-primary (simple swap)
+   ```
+
+---
+
+#### Step 6 — Pass 2: Complex-preservable replacements
+
+For each candidate classified as `complex-preservable` in DS_ANALYSIS.md:
+
+1. **Read the full element context** — read the file and identify all:
+   - Event handlers: `onClick`, `onChange`, `onSubmit`, `onKeyDown`, `onFocus`, `onBlur`, etc.
+   - Conditional rendering: ternary expressions, `&&` conditionals
+   - Dynamic props: `className={...}`, `style={...}`, spread props `{...rest}`
+   - Data bindings: `value={state}`, `checked={state}`, `ref={ref}`
+
+2. **Apply DS structure while preserving all logic, using one of two strategies:**
+
+   **Strategy A — Class addition (when existing DOM structure is compatible with DS):**
+   The element's DOM structure is close enough to the DS component. Add DS classes and remove conflicting custom CSS.
+   ```tsx
+   // BEFORE
+   <button
+     className={`btn ${isActive ? 'btn-active' : ''}`}
+     onClick={handleClick}
+     disabled={isLoading}
+   >
+     {isLoading ? 'Loading...' : 'Submit'}
+   </button>
+
+   // AFTER — DS classes added, handlers/bindings preserved
+   <button
+     className={`trdr-btn trdr-btn-primary ${isActive ? 'btn-active' : ''}`}
+     onClick={handleClick}
+     disabled={isLoading}
+   >
+     {isLoading ? 'Loading...' : 'Submit'}
+   </button>
+   ```
+
+   **Strategy B — Structure wrap (when DS component requires different DOM structure):**
+   The element needs DS DOM structure but has logic that must stay.
+   ```tsx
+   // BEFORE — checkbox with complex state
+   <div className="filter-option">
+     <input
+       type="checkbox"
+       id={`filter-${id}`}
+       checked={filters.includes(id)}
+       onChange={() => toggleFilter(id)}
+     />
+     <label htmlFor={`filter-${id}`}>{label}</label>
+   </div>
+
+   // AFTER — DS checkbox structure, ALL logic preserved
+   <label className="trdr-checkbox">
+     <input
+       type="checkbox"
+       id={`filter-${id}`}
+       checked={filters.includes(id)}
+       onChange={() => toggleFilter(id)}
+     />
+     <span className="trdr-checkbox-box"></span>
+     <span>{label}</span>
+   </label>
+   ```
+
+3. **NEVER remove or alter any of the following** (absolute rule):
+   - `onClick`, `onChange`, `onSubmit`, `onKeyDown`, `onFocus`, `onBlur` handlers
+   - `ref=`, `key=` props
+   - `disabled={condition}`, `checked={condition}`, `value={state}` bindings
+   - Conditional rendering (`{condition && ...}`, `{condition ? ... : ...}`)
+   - Spread props (`{...rest}`, `{...props}`)
+   - `id`, `name`, `data-*`, `aria-*` attributes
+   - Custom `className` parts used in JS selectors (`querySelector`, `classList.toggle`)
+
+4. **For dynamically-toggled classes** (e.g., `classList.toggle('active')`):
+   - Map the custom state class to a DS state class
+   - Update ALL `classList.toggle/add/remove` calls to also toggle the DS class
+   - Example: `el.classList.toggle('active')` → also add `el.classList.toggle('trdr-segment-active')`
+
+5. **Clean up redundant CSS** — same rules as Pass 1 step 6.
+
+6. **Document in DS_PROGRESS.md:**
+   ```
+   - [x] checkbox: src/Filters.tsx:88 — preserved: onChange, checked binding → trdr-checkbox (complex-preservable, Strategy B)
+   ```
+
+---
+
+#### Step 6 — Pass 3: Manual review flagging
+
+For each candidate classified as `complex-manual` in DS_ANALYSIS.md:
+
+1. **Do NOT modify** the source file's component structure.
+
+2. **Add a TODO comment** in the source file above the element:
+   ```
+   <!-- TODO: TRDR DS — replace with [c.name] component. See DS_MIGRATION.md for details. -->
+   ```
+   For React/JSX:
+   ```
+   {/* TODO: TRDR DS — replace with [c.name] component. See DS_MIGRATION.md for details. */}
+   ```
+
+3. **Add an entry to `DS_MIGRATION.md`** under `## Manual component review`:
+   ```markdown
+   ### [file:line] — [c.name]
+   - **Reason:** [brief description of complexity]
+   - **Existing structure:** [brief DOM outline]
+   - **Suggested DS component:** [slug] ([variant])
+   - **Suggested approach:** Strategy A (class addition) / Strategy B (structure wrap) / custom adaptation
+   - **Handlers to preserve:** [list of event handlers found]
+   - **Dynamic props:** [list of dynamic bindings]
+   ```
+
+---
+
+#### Step 6 — Stubs and unmapped patterns
+
+**If `c.implemented === false`** (stub — not yet implemented in DS):
+- Add this banner comment above the affected element in the source file:
+  ```
+  /* TRDR DS — <c.name> (figmaId: <c.figmaId>) */
+  /* Implementação canônica pendente. Consulte https://trdr.mrocontent.com.br/componentes/<c.slug> */
+  /* Tokens recomendados: <list c.tokens[].token> */
+  ```
+- Append an entry to `MISSING_COMPONENTS.md`:
+  ```markdown
+  ## <c.name>
+  - Slug: `<c.slug>` | figmaId: `<c.figmaId>` | Category: `<c.category>`
+  - Found in: <list of file:line>
+  - Description: <c.description>
+  - Recommended tokens: <c.tokens[]>
+  - Status: ⚠️ stub — code blocks pending
+  ```
+
+**If no slug matches** the detected pattern:
+- Flag the pattern in `MISSING_COMPONENTS.md` under "Unmapped patterns" with the file location and a one-line description of the UI need.
+
+**Do NOT replace domain-specific components** (course cards, lesson rows, trading panels, etc.) — document them as "sem equivalente DS".
+
+---
+
+#### Step 6 — Final: Update progress
 
-Update `DS_PROGRESS.md`: set `Sub-fase C: Components — ✅ COMPLETE` and mark each component as done.
+Update `DS_PROGRESS.md`: set `Sub-fase C: Components — ✅ COMPLETE` and add summary:
+```
+### Componentes DS Aplicados
+Simple swaps: [S]
+Complex-preservable: [P]
+Manual review: [M] (see DS_MIGRATION.md)
+Stubs: [T]
+Total: [S+P+M+T] candidates processed
+
+[List each replacement with its classification]
+```
 
 Output:
 ```
-✅ Sub-fase C completa — [N] componentes DS aplicados, [M] stubs marcados.
+✅ Sub-fase C completa — [N] componentes DS implementados ([S] simple, [P] complex-preservable), [M] flagged para revisão manual, [T] stubs marcados.
 
-Próximo: Sub-fase D — Final (logos + DS_MIGRATION.md)
+Próximo: Sub-fase D — Final (logos + ícones + DS_MIGRATION.md)
 Responda:
 - "continuar" / "continue" — finalizar migração
 - "parar" / "stop" — salvar progresso e parar aqui
@@ -1287,10 +1807,21 @@ For plain HTML and Vue (CDN approach), add to `<head>`:
 
 Add to the project's main CSS:
 ```css
-/* Material Icons helpers */
-.material-icons { font-size: 20px; display: inline-flex; align-items: center; color: inherit; user-select: none; }
-.mi-sm { font-size: 16px; }
-.mi-xs { font-size: 14px; }
+/* Material Icons helpers — TRDR DS */
+.material-icons {
+  font-size: 20px;                /* default = mi-md */
+  display: inline-flex;
+  align-items: center;
+  color: inherit;
+  user-select: none;
+}
+.mi-2xs { font-size: 12px; }     /* very small indicators */
+.mi-xs  { font-size: 14px; }     /* compact UI */
+.mi-sm  { font-size: 16px; }     /* small icons */
+/* .mi-md — 20px — default, no class needed */
+.mi-lg  { font-size: 24px; }     /* standard Material Design size */
+.mi-xl  { font-size: 28px; }     /* larger icons */
+.mi-2xl { font-size: 32px; }     /* hero/feature icons */
 ```
 
 **Step 6.6c — Add icon color classes** (do NOT use inline style for icon color — create CSS classes instead):
@@ -1303,6 +1834,49 @@ Add to the project's main CSS:
 .icon-muted   { color: var(--content-tertiary); }
 ```
 
+**Step 6.6c-2 — Measure original SVG dimensions before replacement:**
+
+For EACH inline `<svg>` element that will be replaced, determine the original rendered size:
+
+1. **Read the SVG's explicit size** — check for `width` and `height` attributes:
+   ```html
+   <svg width="24" height="24" ...>  →  originalSize = 24
+   <svg width="16" height="16" ...>  →  originalSize = 16
+   ```
+   Use the `width` attribute value (icons are typically square). If `width` and `height` differ, use the larger value.
+
+2. **If no width/height attributes** — check the `viewBox`:
+   ```html
+   <svg viewBox="0 0 24 24" ...>  →  originalSize = 24 (4th value = viewBox height)
+   ```
+
+3. **If no explicit size and no viewBox** — check CSS for the SVG's container:
+   - Look for the SVG's parent element class or the SVG's own class
+   - Search CSS files for `width`, `height`, or `font-size` applied to that selector
+   - Example: `.icon { width: 18px; height: 18px; }` → originalSize = 18
+
+4. **If still undetermined** — assume 20px (the DS default) and add a comment:
+   ```html
+   <!-- TODO: verify icon size — original SVG had no explicit dimensions -->
+   ```
+
+5. **Map originalSize to the correct size class/style:**
+
+   | Original SVG size | Replacement class/style | Notes |
+   |---|---|---|
+   | 12px | `.mi-2xs` | Very small indicator |
+   | 14px | `.mi-xs` | Compact UI |
+   | 16px | `.mi-sm` | Small icons |
+   | 18px | `style="font-size:18px"` | Between sm and md — no standard class |
+   | 20px | *(none — default)* | No class needed |
+   | 22px | `style="font-size:22px"` | Between md and lg — no standard class |
+   | 24px | `.mi-lg` | Standard Material Design size |
+   | 28px | `.mi-xl` | Larger icons |
+   | 32px | `.mi-2xl` | Hero/feature icons |
+   | Any other Npx | `style="font-size:Npx"` | Exact size preservation |
+
+   **Priority:** Use a size class if one matches exactly. Only use inline `font-size` for non-standard sizes. NEVER use inline `style="color:..."` — color is ALWAYS via CSS class (Rule 11).
+
 **Step 6.6d — Map SVG content to icon names:**
 
 Analyze the SVG path/shape content to identify the icon:
@@ -1329,14 +1903,42 @@ Analyze the SVG path/shape content to identify the icon:
 
 For SVG icons that cannot be mapped automatically: leave a `<!-- TODO: replace with Material Icon: [description] -->` comment and document in DS_MIGRATION.md.
 
-**Step 6.6e — Replace by framework:**
+**Step 6.6e — Replace by framework (with size preservation):**
+
+Use the `originalSize` measured in Step 6.6c-2 to select the correct size class or inline font-size.
 
-| Framework | Replacement |
-|-----------|------------|
-| Plain HTML | `<span class="material-icons mi-sm">icon_name</span>` |
-| React (CDN) | `<span className="material-icons mi-sm">icon_name</span>` |
-| React (@mui) | `import SearchIcon from '@mui/icons-material/Search'` + `<SearchIcon sx={{ fontSize: 16 }} />` |
-| Vue (CDN) | `<span class="material-icons mi-sm">icon_name</span>` |
+| Framework | Standard size (has class) | Non-standard size (no class) |
+|-----------|--------------------------|------------------------------|
+| Plain HTML | `<span class="material-icons {sizeClass}">icon_name</span>` | `<span class="material-icons" style="font-size:{N}px">icon_name</span>` |
+| React (CDN) | `<span className="material-icons {sizeClass}">icon_name</span>` | `<span className="material-icons" style={{fontSize:{N}}}>icon_name</span>` |
+| React (@mui) | `<IconName sx={{ fontSize: {originalSize} }} />` (omit `sx` if 24px — @mui default) | Same — @mui always uses `sx.fontSize` |
+| Vue (CDN) | `<span class="material-icons {sizeClass}">icon_name</span>` | `<span class="material-icons" style="font-size:{N}px">icon_name</span>` |
+
+**Examples with size + color combined:**
+```html
+<!-- Original: 16×16 search icon with brand color -->
+<svg width="16" height="16"><path d="M..." stroke="#00A8CC"/></svg>
+<!-- Replacement: class mi-sm (16px) + class icon-brand -->
+<span class="material-icons mi-sm icon-brand">search</span>
+
+<!-- Original: 24×24 close icon, neutral color (currentColor) -->
+<svg width="24" height="24"><path d="M..." stroke="currentColor"/></svg>
+<!-- Replacement: class mi-lg (24px), no color class (inherits) -->
+<span class="material-icons mi-lg">close</span>
+
+<!-- Original: 20×20 icon (default size) -->
+<svg width="20" height="20" viewBox="0 0 20 20"><path d="M..."/></svg>
+<!-- Replacement: no size class needed (20px is default) -->
+<span class="material-icons">settings</span>
+
+<!-- Original: 18×18 icon (non-standard size) -->
+<svg width="18" height="18" viewBox="0 0 18 18"><path d="M..."/></svg>
+<!-- Replacement: inline font-size for non-standard size -->
+<span class="material-icons" style="font-size:18px">settings</span>
+
+<!-- React @mui — 16px icon with brand color -->
+<SearchIcon className="icon-brand" sx={{ fontSize: 16 }} />
+```
 
 **Color of icon** — ALWAYS via class, NEVER inline style:
 ```html
@@ -1541,71 +2143,86 @@ Catalog: TRDR DS v[catalog-version] ([implemented]/[total] components)
 Hub: https://trdr.mrocontent.com.br
 → Check DS_MIGRATION.md for manual steps
 → Stubs not yet canonical: see MISSING_COMPONENTS.md
+→ Backup branch: `trdr-ds/backup-{timestamp}` — para desfazer: `/trdr-ds rollback`
+→ Para remover o backup após validar: `git branch -D trdr-ds/backup-{timestamp}`
 ```
 
 ---
 
 ## RESUME MODE (when invoked with `resume` argument)
 
-1. Look for `DS_ANALYSIS.md` and `DS_PROGRESS.md` at the project root.
-   - If `DS_PROGRESS.md` not found: output `❌ No previous migration found. Run /trdr-ds to start a new one.`
-   - If `Status: COMPLETE`: output `✅ Migration already complete (finished [date]). Run /trdr-ds to check for new violations.`
+This is the primary way to continue a migration across multiple context windows. Each `/trdr-ds resume` picks up the next pending sprint.
+
+1. Look for `SPRINT_PLAN.md` and `DS_PROGRESS.md` at the project root.
+   - If neither found: output `❌ No previous migration found. Run /trdr-ds to start a new one.`
+   - If `DS_PROGRESS.md` has `Status: COMPLETE`: output `✅ Migration already complete (finished [date]). Run /trdr-ds to check for new violations.`
 
-2. Read both `DS_ANALYSIS.md` and `DS_PROGRESS.md`. Determine the current sub-fase:
-   - If `Sub-fase A: Foundation — PENDING` or `IN_PROGRESS` → resume Sub-fase A
-   - If `Sub-fase A: Foundation — ✅ COMPLETE` AND `Sub-fase B: Violations — PENDING` or `IN_PROGRESS` → resume Sub-fase B from first PENDING or IN_PROGRESS batch
-   - If `Sub-fase B — ✅ COMPLETE` AND `Sub-fase C: Components — PENDING` or `IN_PROGRESS` → resume Sub-fase C
-   - If `Sub-fase C — ✅ COMPLETE` AND `Sub-fase D: Final — PENDING` or `IN_PROGRESS` → resume Sub-fase D
+2. Read `SPRINT_PLAN.md`. Find the first sprint with `Status: PENDING` or `Status: IN_PROGRESS`.
+   - If all sprints are `✅ COMPLETE`: mark migration as COMPLETE in DS_PROGRESS.md and output summary.
 
-3. Output a resume summary:
+3. Read `DS_PROGRESS.md` to understand overall state.
+
+4. Read **only the relevant section** of `DS_ANALYSIS.md` for the current sprint:
+   - Foundation sprint: read `§ Project` section only
+   - Violation sprint: read `§ By File` entries ONLY for the files listed in that sprint's scope
+   - Components sprint: read `§ Component Replacement Candidates`
+   - Final sprint: read `§ Logo Audit`
+
+5. Output a resume summary:
    ```
-   Resuming TRDR DS migration — [project name]
-   Sub-fase A (Foundation): [✅ / 🔄 / ⏳]
-   Sub-fase B (Violations): [done]/[total] lotes | [N] violações corrigidas
-   Sub-fase C (Components): [✅ / 🔄 / ⏳]
-   Sub-fase D (Final):      [✅ / 🔄 / ⏳]
+   Resumindo migração TRDR DS — [project name]
+
+   📋 Sprint Plan: [done]/[total] sprints completos ([percentage]%)
+
+   [For each sprint in SPRINT_PLAN.md:]
+   Sprint 1 — Foundation                          ✅
+   Sprint 2 — Violations: src/components/          ✅
+   Sprint 3 — Violations: src/pages/               🔄 ← retomando aqui
+   Sprint 4 — Violations: src/app/                 ⏳
+   Sprint 5 — Components                           ⏳
+   Sprint 6 — Final                                ⏳
 
-   Resuming at: **[Sub-fase atual]**
+   Retomando: **Sprint [N] — [name]**
+   Escopo: [sprint scope description]
    ```
 
-4. Continue the detected sub-fase from the correct point. All context is read from `DS_ANALYSIS.md` + `DS_PROGRESS.md` — not from conversation history.
+6. Execute the current sprint following the sprint lifecycle (read → execute → save → STOP).
+   All context is read from `SPRINT_PLAN.md` + `DS_ANALYSIS.md` (relevant section only) + `DS_PROGRESS.md` — never from conversation history.
 
 ---
 
 ## STATUS MODE (when invoked with `status` argument)
 
-1. Look for `DS_PROGRESS.md` at the project root.
-   - If not found: output `No migration in progress. Run /trdr-ds to start.`
+1. Look for `SPRINT_PLAN.md` and `DS_PROGRESS.md` at the project root.
+   - If neither found: output `No migration in progress. Run /trdr-ds to start.`
 
-2. Read `DS_PROGRESS.md` (and `DS_ANALYSIS.md` if present) and output a progress table — do NOT modify any files:
+2. Read `SPRINT_PLAN.md` and `DS_PROGRESS.md` — do NOT modify any files. Output:
 
 ```
 ## TRDR DS — Migration Status
 
 Project: [name] | Started: [date] | Status: [IN_PROGRESS/PAUSED/COMPLETE]
-
-### Sub-fase A: Foundation
-| Step | File | Status |
-|------|------|--------|
-| tokens.css | [path] | ✅ / ⏳ |
-| components.css | [path] | ✅ / ⏳ |
-| CLAUDE.md | CLAUDE.md | ✅ / ⏳ |
-| @import | [global-css] | ✅ / ⏳ |
-
-### Sub-fase B: Violations
-| Lote | Pasta | Arquivos | Violações | Status |
-|------|-------|----------|-----------|--------|
-| 1 | src/components/ | 5 | 12 | ✅ COMPLETE |
-| 2 | src/pages/ | 4 | 8 | 🔄 IN_PROGRESS |
-| 3 | src/app/ | 5 | — | ⏳ PENDING |
-| 4 | src/styles/ | 3 | — | ⏳ PENDING |
-
-### Sub-fase C: Components — [✅ COMPLETE / ⏳ PENDING]
-### Sub-fase D: Final — [✅ COMPLETE / ⏳ PENDING]
-
-Progress: [N]% ([done]/[total] batches — [violations_fixed]/[total_violations] violations fixed)
-
-To continue: `/trdr-ds resume`
+Backup: [branch name or NONE]
+
+### Sprint Progress
+| Sprint | Scope | Files | Violations | Status |
+|--------|-------|-------|------------|--------|
+| 1 | Foundation | 4 | — | ✅ |
+| 2 | Violations: src/components/ | 12 | 34 | ✅ |
+| 3 | Violations: src/pages/ | 8 | 21 | 🔄 IN_PROGRESS |
+| 4 | Violations: src/app/ | 15 | 45 | ⏳ PENDING |
+| 5 | Violations: src/styles/ | 6 | 18 | ⏳ PENDING |
+| 6 | Components | [N] candidates | — | ⏳ PENDING |
+| 7 | Final | logos + icons | — | ⏳ PENDING |
+
+### Summary
+Sprints completos: [done]/[total] ([percentage]%)
+Violações corrigidas: [fixed]/[total_violations]
+Componentes aplicados: [applied]/[total_candidates]
+
+### Next Action
+→ Sprint [N]: [name] — `/trdr-ds resume`
+→ Para desfazer tudo: `/trdr-ds rollback`
 ```
 
 ---
@@ -1624,6 +2241,65 @@ If either fetch fails, report which one and exit. Do NOT touch the snapshot if t
 
 ---
 
+## ROLLBACK MODE (when invoked as `/trdr-ds rollback`)
+
+1. Look for `DS_PROGRESS.md` at the project root.
+   - If not found: output `❌ Nenhuma migração encontrada. Nada para reverter.` and STOP.
+   - If `Backup branch:` line is `NONE (user opted out)`: output `❌ Nenhum backup foi criado (você optou por continuar sem backup durante a migração). Rollback manual necessário.` and STOP.
+
+2. Read the `Backup branch:` value from `DS_PROGRESS.md`. Save as `backupBranch`.
+   Read the `Original branch:` value. Save as `originalBranch`.
+
+3. Verify the backup branch still exists:
+   ```bash
+   git rev-parse --verify {backupBranch} 2>/dev/null
+   ```
+   If it doesn't exist: output `❌ Branch de backup \`{backupBranch}\` não encontrado. Pode ter sido apagado manualmente.` and STOP.
+
+4. Confirm with the user:
+   ```
+   ⚠️ ROLLBACK: Isto vai reverter TODAS as alterações feitas pela migração TRDR DS.
+
+   Backup branch: {backupBranch}
+   Branch atual: {currentBranch}
+   Status da migração: {status from DS_PROGRESS.md}
+
+   Todos os arquivos modificados pela migração serão restaurados ao estado do backup.
+   Arquivos DS criados (DS_ANALYSIS.md, DS_PROGRESS.md, DS_MIGRATION.md, MISSING_COMPONENTS.md, CLAUDE.md, tokens.css, components.css) serão revertidos ou removidos.
+
+   Responda:
+   - "confirmar" — executar rollback
+   - "cancelar" — abortar
+   ```
+   **STOP. Wait for reply.**
+
+5. If `"cancelar"`: output `Rollback cancelado.` and STOP.
+
+6. If `"confirmar"`, execute the rollback:
+
+   a. Ensure we're on the original branch:
+   ```bash
+   git checkout {originalBranch}
+   ```
+
+   b. Reset the working tree to the backup state:
+   ```bash
+   git reset --hard {backupBranch}
+   ```
+
+7. Output:
+   ```
+   ✅ Rollback completo.
+
+   Branch `{originalBranch}` restaurado ao estado de `{backupBranch}`.
+   Todos os arquivos modificados pela migração foram revertidos.
+
+   O backup branch `{backupBranch}` ainda existe. Para removê-lo:
+   git branch -D {backupBranch}
+   ```
+
+---
+
 ## 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:

package/plugins/trdr-design-system/skills/trdr-ds/references/rules.md

@@ -93,7 +93,9 @@ Para `animation-delay` calculado: converter para `style="--delay: Xs"` + CSS `an
 - ✅ `class="text-brand"` com `.text-brand { color: var(--content-brand); }` no CSS
 
 ### Regra 11 — Ícones via biblioteca, nunca SVG inline
-Use Material Icons (HTML/Vue) ou @mui/icons-material (React). A cor dos ícones SEMPRE via classe CSS com token — nunca inline style.
+Use Material Icons (HTML/Vue) ou @mui/icons-material (React). A cor dos ícones SEMPRE via classe CSS com token — nunca inline style. O tamanho deve preservar as dimensões do ícone original.
+- Escala de tamanhos: `.mi-2xs` (12px), `.mi-xs` (14px), `.mi-sm` (16px), default (20px), `.mi-lg` (24px), `.mi-xl` (28px), `.mi-2xl` (32px)
+- Para tamanhos não padrão: `style="font-size:Npx"` (aceito APENAS para font-size de ícones, nunca para cor)
 - ❌ `<svg><path d="..."/></svg>` para ícones
 - ❌ `<span class="material-icons" style="color:#00D4FF">search</span>`
 - ✅ `<span class="material-icons mi-sm icon-brand">search</span>` com `.icon-brand { color: var(--content-brand); }`