Guia para IA

Regras absolutas, referências e o passo a passo completo da skill /trdr-ds para qualquer IA construir interfaces TRDR consistentes.

Skill Claude Code — /trdr-ds

Instale uma vez no Claude Code e aplique o TRDR Design System em qualquer projeto em dois passos: análise com aprovação e execução completa. Atualizações chegam automaticamente via npm — sem reinstalar.

auto_fix_high
/trdr-ds — TRDR Design System Installer v1.9.0
Analisa o projeto → gera sprint plan → aguarda aprovação → executa em sprints independentes com rollback via git. Suporte completo a MUI (Material UI).
1 — Análise + Sprint PlanDetecta framework, encontra violações, classifica componentes e gera SPRINT_PLAN.md com sprints independentes
2 — Backup + AprovaçãoCria branch git de backup antes de qualquer modificação. Apresenta o plano — nenhum arquivo é alterado antes da sua resposta
3 — Execução por SprintsCada sprint é independente: Foundation → Violations (por pasta) → Components (3 passes) → Final. Limpe o contexto entre sprints com /clear e retome com /trdr-ds resume

Instalação

Global — recomendado
npx trdr-ds-install@latest

Disponível em todos os projetos. Para atualizar, rode o mesmo comando novamente.

Apenas este projeto
npx trdr-ds-install@latest --project

Instalado em .claude/skills/ do projeto atual. Ideal para equipes sem acesso global.

Após instalar, reinicie o Claude Code para ativar a skill.

Como invocar

Digite o comando direto ou qualquer uma das frases abaixo no Claude Code — a skill detecta automaticamente a intenção.

/trdr-dsaplicar design systemimplement TRDR DSadd TRDR tokensdesign system setupmigrar design systemapply design system

Catálogo offline-first

A skill embute um snapshot completo do catálogo e dos tokens — funciona sem internet. Mantenedores atualizam o snapshot puxando do Hub via npm run sync. Devs recebem a versão nova rodando npx trdr-ds-install@latest.

/components.jsonCatálogo completo em JSON: 25 componentes implementados (com 4 code blocks cada). Abrir endpoint →
/tokens.cssTodas as CSS variables (dark + light), copiadas verbatim para o projeto. Abrir endpoint →
/trdr-ds syncComando do dev — força a skill a buscar o catálogo mais novo do Hub e sobrescrever o snapshot local. Não toca em arquivos do projeto.

Sistema de Sprints — projetos de qualquer tamanho

A migração é dividida em sprints independentes. Cada sprint cabe em uma única janela de contexto — ideal para projetos grandes (4GB+). Entre sprints, use /clear para limpar o contexto e /trdr-ds resume para continuar.

SPRINT_PLAN.mdGerado na Fase 1 — lista todos os sprints com escopo, arquivos e status. Cada sprint processa no máximo 15 arquivos.
/trdr-ds resumeEncontra o próximo sprint pendente no SPRINT_PLAN.md e executa — lê apenas os dados necessários para aquele sprint, sem sobrecarregar o contexto.
/trdr-ds statusTabela de progresso com todos os sprints (completos, em andamento, pendentes), violações corrigidas e próxima ação.
/trdr-ds rollbackReverte TODA a migração ao estado original usando o branch git de backup criado antes do primeiro sprint.

Entre sprints, responda com:

"continuar"

Processa o próximo sprint.

"tudo"

Processa todos os sprints restantes sem pausar.

"pular src/legacy"

Pula a pasta do próximo sprint e vai para o seguinte.

"parar"

Salva o progresso e para — retome com /trdr-ds resume.

Rollback — desfazer a migração

Antes de modificar qualquer arquivo, a skill cria um branch git de backup com o estado completo do projeto. Se algo der errado, desfaça tudo com um comando.

Backup automáticoBranch trdr-ds/backup-YYYY-MM-DD-HHmmss criado antes do Sprint 1. Mudanças não commitadas são preservadas via git stash.
/trdr-ds rollbackLê o branch de backup do DS_PROGRESS.md, pede confirmação, e executa git reset --hard para restaurar o estado original.
Sem git?Se o projeto não tem repositório git, a skill oferece inicializar com git init ou continuar sem backup (irreversível).

Implementação de componentes — 3 níveis

Na Fase 1, a skill classifica cada candidato a componente em 3 níveis de complexidade. Na Fase 2 (Sprint de Components), cada nível recebe um tratamento diferente:

SimpleElemento simples (só texto, sem handlers). Substituído completamente pela estrutura do componente DS, adaptando o conteúdo do projeto.
Complex-preservableElemento com handlers/bindings/condicionais, mas mapeável ao DS. Recebe classes e estrutura DS, preservando toda a lógica existente.
ManualLógica profunda ou domínio específico. Não é modificado — recebe comentário TODO e entrada detalhada no DS_MIGRATION.md.

Dependências de componentes — ordem topológica

Componentes compostos reutilizam componentes atômicos. A skill resolve a ordem de instalação automaticamente: atômicos primeiro, compostos depois — garantindo que imports de sub-componentes já existam quando um composto é instalado.

BoletaSegmentedControl, TextInput, Checkbox, Button, Dropdown
JanelaFloatingMenu, Abas
NewsCard, Tabelas, HeaderBadge

O campo dependencies no components.json lista os slugs de sub-componentes de cada composto.

Projetos MUI (Material UI) — integração via theme

Quando a skill detecta @mui/material no package.json, ativa o modo mui — uma abordagem completamente diferente dos outros modos. Em vez de aplicar classes CSS, a skill integra os tokens diretamente no sistema de theme do MUI.

Detecção automáticaSe @mui/material está no package.json, stylingMode é mui — mesmo que @emotion/* esteja presente (é dependência transitiva, não CSS-in-JS direto). Localiza o theme file (createTheme) e conta arquivos com sx props.
Foundation + ThemeCria tokens.css (fonte de verdade) e atualiza o MUI theme com palette, typography e shape referenciando var(--token). O theme fica na ponte entre CSS vars e componentes MUI.
Violações L / M / NEscaneia valores hardcoded no theme (L), em sx props (M) e em styled(MuiComponent) (N) — categorias que não existem nos outros modos. Substitui por var(--token).
styleOverridesEm vez de substituir HTML tags por classes DS, gera styleOverrides no theme para cada MUI component detectado (MuiButton, MuiTextField, MuiCard, etc.) — aplicando tokens DS globalmente via theme provider.
palette → DSprimary.main = var(--action-brand-default), background.default = var(--bg-primary), text.primary = var(--content-primary), etc.
typography → DSh1-h6 = var(--font-primary), body/caption = var(--font-secondary), button = textTransform: none + 600
sx propsValores hardcoded migrados para tokens. Layout (display, flex, grid) mantido como está. sx é idiomático no MUI e não é eliminado.

Para MUI v6+, a skill recomenda cssVariables: true no createTheme() — habilita suporte nativo a CSS variables e evita problemas com cálculos internos de palette.

Ícones Material Design — tamanho preservado

SVGs inline são substituídos por Material Icons mantendo o tamanho original do ícone. A skill mede width/height do SVG (ou viewBox) antes de substituir.

.mi-2xs12px — indicadores muito pequenos
.mi-xs14px — UI compacta
.mi-sm16px — ícones pequenos
default20px — sem classe, tamanho padrão
.mi-lg24px — tamanho padrão Material Design
.mi-xl28px — ícones maiores
.mi-2xl32px — ícones hero/feature

Para tamanhos não padrão: style="font-size:18px" é aceito APENAS para font-size de ícones, nunca para cor.

Componentes "stub" — fallback inteligente

O TRDR DS tem 82+ componentes no Figma. Os 25 com 4 code blocks completos no catálogo (HTML, CSS, React e prompt) são implementados durante o sprint de Components — com 3 níveis de complexidade (simple/complex-preservable/manual). Os demais entram como stubs (implemented: false) — a skill não inventa código, mas aplica os tokens recomendados, comenta no fonte com figmaId e link para o Hub, e registra em MISSING_COMPONENTS.md no projeto.

Fase 1

Análise — roda automaticamente

A skill examina o projeto em 5 etapas, salva o resultado em DS_ANALYSIS.md e apresenta um plano estruturado. Nenhum arquivo do projeto é modificado até a sua aprovação.

1
Detectar framework

Lê package.json e identifica Next.js, React, Vue, TypeScript e a abordagem de estilos (CSS Modules, Tailwind, plain CSS, MUI). Detecta stylingMode duplo (Tailwind + styled-components) e prioridade MUI — quando @mui/material está presente, ativa modo mui com scan de theme files, sx props e styled(MuiComponent).

2
Mapear arquivos de estilo

Encontra todos os .css e .scss, localiza o arquivo CSS global e detecta conflitos com prefixos TRDR existentes.

3
Encontrar violações e auditar logo

Busca 14 categorias: cores hardcoded A/A*, font-family B, spacing px C, primitivos D, rgba F, gradientes G, font-size H, inline styles I/I.2, SVGs inline J, logo K — e para projetos MUI: valores hardcoded no theme L (palette, typography, shape, styleOverrides), em sx props M, e em styled(MuiComponent) N. Verifica fingerprint do logo oficial (viewBox 105×41, fill #00D4FF).

4
Detectar candidatos a componentes e carregar catálogo

Identifica padrões de UI substituíveis por componentes TRDR (<button>, <input>, <select>, etc.) e carrega o catálogo offline do snapshot embutido. Com --latest, busca trdr.mrocontent.com.br/components.json antes de seguir.

5
Gerar sprint plan e aguardar

Salva DS_ANALYSIS.md + SPRINT_PLAN.md (sprints independentes agrupados por pasta, máx. 15 arquivos cada). Classifica componentes em simple/complex/manual. Nenhum arquivo é alterado antes da sua resposta.

Como responder ao plano

Após ver o plano gerado pela Fase 1, responda com um dos comandos abaixo para iniciar a execução:

"Apply" ou "Executar"

Executa tudo que está no plano sem exceções.

"Apply, batch 15"

Executa com lotes de 15 arquivos por vez na sub-fase Violations (padrão é 5 arquivos). Útil para reduzir o número de interrupções.

"Sync first"

Atualiza o snapshot do catálogo a partir do Hub antes de aplicar — útil quando você sabe que há componentes novos.

"Only tokens"

Cria apenas tokens.css, components.css e CLAUDE.md — sem corrigir violações existentes.

"Apply, skip src/vendor"

Executa mas pula um caminho ou arquivo específico da lista de violações.

"Change ..."

Ajusta um detalhe do plano antes de executar — útil para escolher o diretório de output.

Fase 2

Execução — o que é criado

Após aprovação, a skill cria um backup git e executa por sprints: Sprint 1 — Foundation (tokens, components, CLAUDE.md), Sprints 2-N — Violations (por pasta, máx. 15 arquivos), Sprint N+1 — Components (3 passes: simple/complex/manual), Sprint Final (logos, ícones com tamanho preservado, DS_MIGRATION.md). Os arquivos gerados são:

tokens.cssCópia verbatim do snapshot references/tokens.css — dark + light mode.
components.cssCSS de cada componente implementado no catálogo + classes de tipografia .trdr-h*/.trdr-body-*.
[globals].css@import adicionado no topo para carregar tokens.css e components.css.
CLAUDE.mdRegras do design system + referência rápida + lista dos componentes implementados (gerada do catálogo).
logo-trdr.svgLogos errados encontrados na Fase 1 são substituídos no lugar pelo logo oficial (105×41px). Se não houver logo e public/ existir, o arquivo é copiado para public/logo-trdr.svg.
MISSING_COMPONENTS.mdApenas se algum stub for encontrado no projeto — registra slug, figmaId e tokens recomendados.
DS_MIGRATION.mdLog completo da migração + checklist de passos manuais (fontes, dark mode, trading UI, stubs).
DS_PROGRESS.mdCheckpoint de execução — registra sprints, sub-fases e progresso geral. Permite retomar com /trdr-ds resume.
SPRINT_PLAN.mdPlano de sprints gerado na análise — cada sprint é independente e executável em uma janela de contexto limpa.

Exemplos de uso

Aplicar tudo (projeto pequeno)
# No Claude Code, digite:
/trdr-ds

# A skill analisa, gera SPRINT_PLAN.md e apresenta o plano.
# Após o plano aparecer, responda:
Apply
Projeto grande — sprint por sprint
# Análise e primeiro sprint:
/trdr-ds
Apply

# Sprint 1 (Foundation) executa e para.
# Limpe o contexto:
/clear

# Continue o próximo sprint:
/trdr-ds resume

# Repita /clear + /trdr-ds resume até completar.
Desfazer toda a migração
# A qualquer momento durante ou após a migração:
/trdr-ds rollback

# Confirme com:
confirmar

# O projeto volta ao estado exato de antes da migração.
Ver progresso e status dos sprints
# Tabela completa de sprints sem alterar nada:
/trdr-ds status

# Retomar de onde parou:
/trdr-ds resume
Apenas tokens (sem violações nem componentes)
/trdr-ds

# Após o plano:
Only tokens
Pular diretório ou invocar por frase
# Pular um caminho:
/trdr-ds
Apply, skip src/vendor

# Frase natural (sem /trdr-ds):
aplicar design system TRDR neste projeto

Regras Absolutas

Estas regras nunca devem ser quebradas. Elas garantem consistência e suporte a dark/light mode em todo projeto TRDR.

1
Nunca use primitivos diretamente na UI

Primitivos são valores brutos (ex: color.blue.600). A UI deve usar tokens semânticos (ex: action.brand.default) para garantir que o tema dark/light funcione corretamente.

❌ background: #00A8CC
✅ background: var(--action-brand-default)
2
Nunca use color.* ou space.* em componentes finais

Use sempre os equivalentes semânticos: bg.*, surface.*, content.*, scale.spacing.* etc.

❌ color: var(--color-neutral-500)
✅ color: var(--content-tertiary)
3
Números e dados financeiros → Roboto Mono

Tabelas de preços, P&L, quantidades e qualquer dado numérico da plataforma de trading devem usar fonte monoespaçada para alinhamento visual.

font-family: var(--font-mono)
4
Títulos de página e headings → JetBrains Mono

JetBrains Mono é a fonte primária da marca. Usada para display, headings e impacto visual técnico e financeiro.

font-family: var(--font-primary)
5
Todo restante da UI → Inter

Inter é a fonte secundária: body text, labels, inputs, nav, tooltips, tudo que não é heading ou número.

font-family: var(--font-secondary)
6
Espaçamentos → sempre scale.spacing.*

Os tokens de scale respeitam as variações desktop/mobile automaticamente. Usar pixels fixos quebraria a responsividade do sistema.

padding: var(--spacing-lg) — nunca padding: 16px
7
Border radius → sempre scale.radius.*

O sistema de radius é padronizado: sm=4px (botões), md=8px (cards), lg=16px (modais/pills), full=9999px (switches/badges).

border-radius: var(--radius-md)

Hierarquia de Camadas

bg.primary (fundo base)
  └── bg.secondary / bg.tertiary (áreas de conteúdo)
        └── surface.primary / secondary / tertiary (cards, painéis)
              └── componentes interativos (inputs, buttons)
                    └── overlays / modais / tooltips

Como usar tokens de ação

ContextoTokenExemplo de uso
Botão primário (CTA)action.brand.*OPERAR, Salvar, Confirmar
Botão secundárioaction.secondary.*Cancelar, Voltar
Botão terciário / FigJamaction.tertiary.*Ações de anotação
Botão destrutivoaction.destructive.*Fechar posição, Excluir

Como usar tokens de trading

ContextoToken
Preço em alta / Compracontext.trading.up / context.trading.long.*
Preço em baixa / Vendacontext.trading.down / context.trading.short.*
Stop Losscontext.trading.stop.*
Candle verdecontext.chart.candles.up
Candle vermelhocontext.chart.candles.down

Template de CLAUDE.md

Este é o CLAUDE.md gerado automaticamente pela skill /trdr-ds. Adicione-o na raiz de qualquer projeto TRDR para que o Claude Code sempre use o Design System correto.

# [Nome do Projeto] — Context for Claude Code

## Design System
Este projeto usa o TRDR Design System.
Referência completa: https://trdr.mrocontent.com.br

## Regras Absolutas (nunca quebre estas)
1. NUNCA use tokens primitivos diretamente (--color-*, --space-*) — use sempre tokens semânticos
2. Backgrounds: --bg-primary (#0E0E0E), --bg-secondary (#141519), --bg-tertiary (#1A1A1A)
3. Texto: --content-primary (branco), --content-secondary (#E8E8E8), --content-tertiary (#A4A4A4)
4. CTA principal: --action-brand-inverse-default (#005266) para botões preenchidos
5. Fontes: --font-primary = JetBrains Mono (headings) | --font-secondary = Inter (body) | --font-mono = Roboto Mono (números)
6. Espaçamento: sempre var(--spacing-xs/sm/md/lg/xl/2xl/3xl) — nunca px hardcoded
7. Border radius: sempre var(--radius-sm/md/lg/full) — nunca px hardcoded

## Arquivos de tokens
- Tokens: src/styles/tokens.css (300+ CSS custom properties — dark + light mode)
- Componentes: src/styles/components.css (classes utilitárias .trdr-*)

## Referência rápida — tokens mais usados
| Token | CSS Variable | Valor (dark) |
|-------|-------------|-------|
| Background | --bg-primary | #0E0E0E |
| Surface | --surface-secondary | #222222 |
| Texto principal | --content-primary | #FFFFFF |
| Texto secundário | --content-tertiary | #A4A4A4 |
| Brand (texto/ícone) | --content-brand | #00A8CC |
| Botão primário (bg) | --action-brand-inverse-default | #005266 |
| Borda | --border-default | #4A4A4A |
| Foco | --border-focus | #00D4FF |
| Sucesso | --content-success | #4FE290 |
| Erro | --content-error | #F34F45 |
| Aviso | --content-warning | #FFCC40 |

## Classes de componentes disponíveis
.trdr-btn, .trdr-btn-primary, .trdr-btn-secondary, .trdr-btn-ghost, .trdr-btn-destructive
.trdr-btn-long (compra), .trdr-btn-short (venda)
.trdr-badge, .trdr-badge-brand, .trdr-badge-success, .trdr-badge-neutral
.trdr-card, .trdr-card-hover
.trdr-input, .trdr-table
.trdr-segment-control, .trdr-segment-active, .trdr-segment-inactive

## Código de componentes
Para qualquer componente: https://trdr.mrocontent.com.br/componentes/[slug]
Disponíveis: button, text-input, switch, dropdown, checkbox, radio-button, combo-input, tooltip, boleta, segmented-control, abas, sub-menu-item, janela, floating-menu, tabela-cotacoes, tabela-ordens, news-card, header, badge
(Verifique o Hub — novos componentes são adicionados regularmente)

## Hierarquia de camadas
bg.primary (base) → bg.secondary/tertiary (áreas de conteúdo) → surface.* (cards, painéis)
→ componentes interativos → overlays/modais/tooltips