roast-my-design-system

roast-my-design-system

Sua IA pode escrever a UI. Isto garante que ela escreva a UI do seu sistema.

Uma ferramenta CLI gratuita (e skill do Claude Code) que analisa o design system do seu repositório com dados reais e, em seguida, gera as regras que mantêm seu agente de IA dentro do sistema.

Novo na 5.1: a análise do roast agora acompanha o relatório. Executado como skill do Claude Code, o relatório ganha uma seção "O que os números significam" — a leitura do Claude sobre sua varredura, no mesmo arquivo compartilhável que a pontuação, para que a análise chegue a quem o relatório for encaminhado. Rotulado como escrito por IA, nunca misturado à medição.

Novo na 5.0: roda como um servidor MCP local. Um único comando, e seu agente consulta o design system antes de escrever UI e, em seguida, tem o trabalho verificado depois: qual Button é canônico, qual token contém aquela cor, revise minhas alterações. Local, determinístico, nada sai da sua máquina. Veja Respostas ao vivo via MCP.

Execute no seu código e obtenha, em cerca de um segundo:

• Uma pontuação de saúde que você pode defender em uma reunião. 0-100, determinística, comparada com as normas do Ideal Design System, 34 repositórios públicos varridos e 10 design systems respeitáveis (Primer, Polaris, Carbon, shadcn/ui…).
• Pontuações por pacote em monorepos. Um número único esconde qual pacote é o problema: packages/ui pontua 80 enquanto apps/web pontua 40, e agora você pode ver isso.
• Os comprovantes por trás disso. Cada cor e seu quase-gêmeo idêntico, cada valor de espaçamento, tipografia, componente duplicado ou nunca importado, estilo inline e !important, com caminhos de arquivo reais, em um único relatório HTML autocontido que você pode abrir, enviar no Slack ou por e-mail.
• As primeiras correções ranqueadas por retorno. Uma lista "Por onde começar" derivada dos seus próprios números: mantenha o relatório como auditoria ou entregue-o ao Claude como a lista de tarefas para a correção.
• Regras que impedem o retorno da bagunça. Um design-system-rules.md gerado com componentes canônicos, seu arquivo de tokens e duplicatas conhecidas a evitar, para que seu agente de IA siga seu sistema em vez de adivinhar. --apply os injeta em todos os arquivos de agente que você tem: Claude, Cursor, GitHub Copilot e Windsurf. Cada varredura também verifica as regras que você já tem em busca de referências obsoletas: caminhos que não existem mais, componentes nomeados como canônicos que nada importa mais.

Por que isto existe

Seu agente de IA (Claude, Cursor, Copilot) constrói UI imitando o que já está no seu repositório. Se o seu repositório tem 112 cores e quatro implementações de Button, seu agente adivinha qual é a canônica e erra metade das vezes. É por isso que a UI gerada por IA parece quase-mas-não-bem certa. O primeiro passo para corrigir é ver a bagunça medida.

Todos os comandos

Uma única varredura alimenta tudo; as flags decidem o que vai para o disco. Combine livremente.

Comando	O que você obtém
npx roast-my-design-system	A varredura e o design-system-roast.html, abertos no seu navegador
npx roast-my-design-system <caminho>	Varre um repositório diferente do diretório atual
... --apply	As regras de agente geradas injetadas diretamente em todos os arquivos de agente que você tem: CLAUDE.md, AGENTS.md, .cursorrules, .cursor/rules/, .windsurfrules e .github/copilot-instructions.md, dentro de um bloco marcado. Reexecutar substitui apenas esse bloco, nunca seu próprio texto. Windsurf e Copilot recebem uma variante compacta dimensionada para seus limites
... --rules	As mesmas regras gravadas em design-system-rules.md em vez disso, para colar manualmente
... --card	roast-card.svg: um cartão compartilhável de 1200x630 com a pontuação e os piores achados. SVG puro, incorpora em um README
... --sarif	design-system-roast.sarif para varredura de código do GitHub: envie-o no CI e os achados aparecem na aba Security, anotados nos arquivos
... --mcp	A varredura como um servidor MCP local: cinco ferramentas que seu agente chama ao escrever UI, de "já existe um Button?" a "revise minhas alterações". Veja Respostas ao vivo via MCP
... --check	Os arquivos alterados da árvore de trabalho verificados contra o design system, no terminal. Sai com código 1 em caso de achados, então se encaixa em scripts
... --by "Dwayne Hicks"	Um crédito de solicitante no cabeçalho do relatório, ao lado da data da varredura
... --notes <arquivo.md>	Uma análise escrita por agente incorporada no relatório como "O que os números significam": rotulada como escrita por IA, mantida separada dos números medidos. A skill do Claude Code escreve e passa isso automaticamente; a flag existe para que qualquer agente possa
... --section "Título" <arquivo.md>	Um capítulo escrito por agente anexado após as notas, mesma estilização, mesmo rótulo escrito-por-IA, com subtítulos permitidos. Repetível, para que análises que crescem além das notas ainda vivam dentro do relatório em vez de uma página feita à mão
... --exclude lab/	Deixa uma pasta fora da varredura (repita a flag ou separe por vírgula). Ou liste pastas em um arquivo .roastignore na raiz do repositório. De qualquer forma, o relatório informa isso no cabeçalho; veja Escopando a varredura
... --json	O resumo da varredura como JSON no stdout, para scripts e pipelines
... --theme light / --out <arquivo> / --no-open	Relatório claro, caminho de relatório personalizado, não abrir o navegador
/roast-my-design-system (no Claude Code)	A experiência completa: o roast no chat e incorporado no relatório como "O que os números significam", a oferta de regras e o loop de correção com o Claude nos seus próprios números

Uma varredura escreve regras para cada agente: Claude, Cursor, GitHub Copilot e Windsurf. Cada varredura também verifica as regras de agente que você já tem e sinaliza referências obsoletas, sem necessidade de flag.

Exemplos de casos de uso

• Auditoria pré-refatoração. Execute /roast-my-design-system antes de uma limpeza do design system para obter a linha de base medida: cada cor, valor de espaçamento, componente duplicado e estilo inline, com caminhos de arquivo reais.
• Diagnosticando saída de IA quase certa. Quando o Claude continua gerando UI que parece levemente errada, o relatório mostra quais componentes duplicados e valores soltos ele está imitando e onde os canônicos vivem.
• Defendendo o caso sem reunião. Envie o relatório HTML autocontido no Slack: uma pontuação de saúde e três benchmarks (normas ideais, a mediana de 34 repositórios, 10 sistemas respeitáveis) argumentam pelo design system por você.
• O loop de correção. Entregue o relatório de volta ao Claude como a lista de tarefas e trabalhe na seção Por onde começar, arquivo por arquivo.

O relatório completo para vercel/ai-chatbot, de cima a baixo — incluindo "O que os números significam", a leitura do Claude da varredura, incorporada logo abaixo do veredito:

O mesmo relatório em modo claro (um arquivo, alternância embutida):

O que torna os números confiáveis

• Scanner determinístico, não amostragem de IA. Um script Node sem dependências lê todos os arquivos (cerca de um segundo em um repositório normal, alguns em um monorepo grande) e retorna os mesmos números a cada execução. Claude narra; nunca conta.
• Somente leitura. Nada no seu repositório é modificado. As únicas saídas são um JSON temporário e o relatório HTML.
• Sem rede, sem telemetria. Tudo roda localmente. Nada sobre seu código sai da sua máquina.
• Exclusões honestas. Arquivos de teste, histórias do Storybook, sites de documentação, aplicativos de exemplo, arte SVG e modelos de e-mail (que precisam ter estilos inline) são excluídos, para que você não possa desacreditar os números por um tecnicismo. Suas próprias exclusões (.roastignore, --exclude) são impressas no cabeçalho do relatório com contagens de arquivos, para que uma varredura escopada nunca possa se passar pelo repositório inteiro.
• Contagem ciente de intenção (v3). Estilos inline calculados em tempo de execução, APIs de componentes compostos e componentes wrapper não são crimes e não são contados como tais. Repositórios liderados por tokens são julgados pelos desvios codificados, não pela arquitetura de tokens. Valores arbitrários repetidos são lidos como decisões sem nome, não como deriva.
• Um benchmark real. A régua "Design System Médio" vem da varredura de 34 repositórios React públicos (cal.com, excalidraw, supabase, grafana, twenty, dub, langfuse…). Mediana: 130 cores, 17 cinzas, 20 componentes duplicados, 49 blocos de estilo inline, 70 valores arbitrários do Tailwind.
• Uma segunda régua: sistemas respeitáveis. Varreduras curadas e escopadas de 10 design systems conhecidos (shadcn/ui, Primer, Polaris, Carbon, Material UI, Chakra, Ant Design, GOV.UK, Spectrum, Cloudscape) mostram como é a disciplina em escala.

Escopando a varredura

Alguns repositórios hospedam mais de um mundo visual de propósito: o produto mais um site de marketing, um playground, um lote de experimentos. Misturá-los produz uma pontuação que não descreve nenhum deles. Escope a varredura para o design system que você está realmente julgando:

npx roast-my-design-system --exclude lab/ --exclude playground/

Ou torne isso permanente com um arquivo .roastignore na raiz do repositório, uma pasta relativa ao repositório por linha:

# separate visual worlds, not the product's design system
lab/
playground/

Ambas as rotas se mesclam, e ambas são barulhentas de propósito. O JSON da colheita registra cada padrão ativo e quantos arquivos ele removeu, e o relatório imprime uma linha no cabeçalho ("2 pastas excluídas por .roastignore (lab/, playground/) · 946 arquivos mantidos fora desta varredura"). Você pode estreitar a pergunta, mas o relatório sempre diz qual pergunta foi feita, para que uma pontuação escopada não possa ser silenciosamente manipulada. Não há negação nem sintaxe de glob: prefixos de pasta simples, nada sofisticado.

Respostas ao vivo via MCP

O relatório e o arquivo de regras descrevem o repositório como estava no momento da varredura. --mcp mantém o mesmo motor rodando enquanto seu agente trabalha, para que perguntas sejam respondidas a partir do código como ele está agora e erros sejam pegos antes de chegarem:

Ferramenta	A pergunta que ela responde
roast_get_context	O que devo saber antes de tocar na UI aqui? Roteado pela pasta sendo editada
roast_find_component	Já existe um componente para isso, e qual é o canônico? Com um exemplo de uso real. Quando dois candidatos empatam, ela diz isso e nomeia ambos
roast_find_token	Tenho #111111 / 13px em mãos. O que eu deveria ter usado?
roast_validate	Estou prestes a salvar isto. Isso quebra o sistema?
roast_review	Revise meus arquivos alterados. Lê o diff do git por conta própria, então nenhum código é colado de volta

O loop: contexto antes de construir, encontrar enquanto constrói, validar antes de salvar, revisar antes de terminar.

Adicione ao Claude Code:

claude mcp add roast -- npx roast-my-design-system --mcp

Qualquer cliente MCP pode registrar o mesmo comando stdio (testado com Claude Code; Cursor e Windsurf falam o mesmo protocolo). Mesma promessa da varredura: local, somente leitura, uma varredura na inicialização, sem porta, sem conta, nada sobre seu código sai da sua máquina. E uma resposta limpa lê "nenhuma violação medida encontrada" com a lista de verificações anexada, porque um scanner só pode certificar o que pode contar.

No CI

O scanner já fala SARIF, então conectá-lo à varredura de código do GitHub são seis linhas. Os achados aparecem na aba Security, anotados nos próprios arquivos:

- uses: actions/checkout@v4
- run: npx roast-my-design-system . --sarif --no-open
- uses: github/codeql-action/upload-sarif@v3
  with:
    sarif_file: design-system-roast.sarif

Instalação

Sem instalação, sem precisar de Claude — apenas experimente:

npx roast-my-design-system

Execute dentro de qualquer repositório. Mesmo scanner, mesmo relatório, direto do npm. A skill do Claude Code abaixo adiciona a conversa por cima: o roast no chat e, em seguida, uma lista de tarefas com a qual você pode realmente trabalhar com o Claude.

Claude Code (recomendado):

/plugin marketplace add pencilrebel/roast-my-design-system
/plugin install roast-my-design-system@roast-my-design-system

Se esses comandos falharem, seu Claude Code provavelmente é mais antigo que o recurso de marketplace de plugins: atualize o Claude Code e tente novamente, ou use o caminho manual abaixo (funciona em qualquer lugar e instala a mesma skill).

Manual (Claude Code, qualquer versão):

git clone https://github.com/pencilrebel/roast-my-design-system.git
cp -r roast-my-design-system/skills/roast-my-design-system ~/.claude/skills/

(Use .claude/skills/ dentro de um repositório para compartilhar com seu time.)

OpenAI Codex CLI (mesmo SKILL.md, mesma pasta):

git clone https://github.com/pencilrebel/roast-my-design-system.git
cp -r roast-my-design-system/skills/roast-my-design-system ~/.codex/skills/

Invoque com $roast-my-design-system (ou deixe o Codex encontrar automaticamente). Use .codex/skills/ dentro de um repositório para compartilhar com seu time.

npx skills: npx skills add pencilrebel/roast-my-design-system funciona para agentes que leem ~/.agents/skills/. O Claude Code atualmente lê ~/.claude/skills/, então prefira uma das rotas acima.

Requer Node 18+.

Uso

Abra o Claude Code no repositório que você quer "roastar" e digite:

/roast-my-design-system

Você recebe o roast no chat, além de design-system-roast.html na raiz do seu repositório: uma página autossuficiente (abra, compartilhe no Slack, envie por e-mail, sem requisições externas) com:

• um score de saúde calculado a partir de como seus números se comparam ao ideal
• "O que os números significam": a leitura do Claude sobre seu scan — quais descobertas realmente importam, quais números bons são acidentes, o que corrigir primeiro — embutida no mesmo arquivo que você vai encaminhar, rotulada como escrita pelo Claude e mantida separada dos números medidos. O score sozinho pode lisonjear; esta seção é o que mantém um 85/100 compartilhado honesto
• tiles de estatísticas comparando você com os três parâmetros: Ideal, a média de 34 repositórios e os sistemas respeitáveis
• um alternador de tema claro/escuro em um único arquivo
• a barra de paleta ponderada por uso, a rampa de cinzas, os recibos de espaçamento fora de escala, os recibos de componentes duplicados com caminhos de arquivo clicáveis e o registro dos piores infratores
• um fechamento Por onde começar: até três movimentos derivados dos números do seu próprio repositório, cada um com um recibo de caminho de arquivo
• um presente 🎁 abaixo: você aguentou o roast, então design-system-rules.md está embrulhado dentro do próprio relatório. Desembrulhe e copie ou baixe as regras de agente geradas a partir do seu scan.

Após o roast, a skill também oferece escrever design-system-rules.md no disco e mesclá-lo no seu CLAUDE.md, .cursor/rules ou AGENTS.md.

Exemplos ao vivo

Três roasts reais de repositórios públicos, hospedados como estão (o mesmo HTML autossuficiente que a skill gera):

• excalidraw/excalidraw
• dubinc/dub
• vercel/ai-chatbot

O que ele mede

Métrica	Design System Ideal	Mediana de 34 repositórios escaneados	Mediana de 10 sistemas respeitáveis
Cores distintas	~24	130	24
Tons de cinza	até 13	17	5
Valores de espaçamento fora de escala	~12	34	6
Tipografias	2–3	3	1
Raios de borda	até 10	13	2
Componentes duplicados	0	20	12
Blocos de estilo inline	0	49	12
Valores arbitrários do Tailwind	~20	70	0
Pares de cores quase idênticos	0	13	1
Declarações !important	0	7	3
Componentes nunca importados	0	0	0

Sim, o repositório mediano já é uma bagunça. É exatamente esse o ponto.

Sua IA pode escrever a UI. Isso garante que ela escreva sua UI.

Licença

MIT. O código é seu para fazer fork, modificar e redistribuir; o aviso de copyright acompanha.

Se você criar um relatório, resumo ou auditoria própria a partir dos scores, contagens ou comparações de benchmark desta ferramenta, mantenha uma linha: Built with roast-my-design-system by Greg Kozakiewicz. Os dados do scan pedem o mesmo dos agentes de IA que os consomem.

roast-my-design-system™ e a marca GK são marcas registradas de Greg Kozakiewicz. Fazer fork é bem-vindo; republicar com este nome não é: veja marca e atribuição.

Construído e projetado por Greg Kozakiewicz.