Extrair Sistema de Design a partir de Código Frontend
Analise o código-fonte frontend para extrair um documento abrangente de sistema de design (DESIGN.md) que captura a linguagem visual do projeto — cores, tipografia, espaçamento, padrões de componentes e princípios de layout — diretamente dos arquivos fonte, sem necessidade de construir ou renderizar a aplicação.
Por que Isso Existe
A skill design-md funciona a partir de HTML renderizado. Mas muitas vezes você tem uma base de código e deseja entender seu sistema de design antes mesmo de executar o aplicativo — talvez faltem dependências, o build esteja quebrado ou você queira apenas uma auditoria rápida. Esta skill lê os próprios arquivos fonte: folhas de estilo, arquivos de componentes, configurações de tema e setups Tailwind. É mais rápida e funciona em qualquer lugar.
Quando Usar
- O usuário tem uma base de código frontend e deseja extrair ou documentar seu sistema de design
- O usuário deseja migrar a identidade visual de um projeto para o Stitch
- O usuário pede para "auditar o estilo" ou "entender a linguagem de design" de um repositório
- O usuário deseja criar um DESIGN.md a partir do código-fonte existente
- O aplicativo não pode ser construído/renderizado, mas o código-fonte está disponível
- O usuário deseja unificar ou reconciliar estilos inconsistentes em uma base de código
Pré-requisitos
- Acesso ao diretório fonte do projeto frontend
- Nenhuma dependência de build ou runtime necessária — esta skill lê apenas arquivos fonte
Fluxo de Trabalho
Fase 1: Descoberta do Projeto
Comece entendendo com o que você está trabalhando. Isso determina quais padrões de extração usar.
1. Detectar o Framework e a Stack
Escaneie a raiz do projeto em busca de arquivos indicadores:
| Arquivo Indicador | Framework / Ferramenta |
|---|---|
package.json com react | React / Next.js |
package.json com vue | Vue / Nuxt |
package.json com svelte | Svelte / SvelteKit |
package.json com @angular/core | Angular |
tailwind.config.js/ts | Tailwind CSS |
postcss.config.js | Pipeline PostCSS |
styled-components ou @emotion em deps | CSS-in-JS |
Arquivos .css / .scss / .less apenas | CSS / SASS puros |
theme.js / theme.ts / tokens.js | Arquivos de tokens de design |
Leia o package.json primeiro — ele revela o framework, as ferramentas CSS e quaisquer bibliotecas de tokens de design (ex.: style-dictionary, @chakra-ui/react, @mui/material, ant-design). Esse contexto informa onde procurar por informações de estilo.
2. Mapear a Árvore de Código Fonte
Identifique os diretórios e arquivos principais que você analisará:
src/
├── components/ ← Estilos de componentes
├── styles/ ← Folhas de estilo globais
├── theme/ ← Definições de tema, tokens
├── assets/ ← Fontes, imagens
├── app.css ← Estilos raiz
└── index.css ← CSS de entrada
Verifique também:
tailwind.config.js/tailwind.config.ts— Cores, fontes, espaçamento personalizadosglobals.css/global.css— Propriedades customizadas CSS (variáveis)- Quaisquer arquivos
theme.*outokens.* - Configuração de bibliotecas de componentes (ex.:
chakra-theme.ts,vuetify.config.ts)
3. Ler o Guia Específico do Framework
Consulte a referência apropriada para padrões de extração:
- React / Next.js / Tailwind → references/react-tailwind.md
- Vue / Nuxt → references/vue.md
- Svelte / SvelteKit → references/svelte.md
- Angular → references/angular.md
- CSS / SASS / Less puros → references/plain-css.md
Essas referências contêm padrões específicos de framework para localizar cores, tipografia, espaçamento e estilos de componentes. Leia a que corresponder antes de prosseguir.
Fase 2: Extração Profunda
Trabalhe cada dimensão de design sistematicamente. Para cada uma, colete dados brutos dos arquivos fonte e, em seguida, sintetize-os em linguagem descritiva.
O objetivo não é despejar cada propriedade CSS — é entender a intenção por trás das escolhas de estilo e descrevê-las em linguagem humana e editorial que outro designer (ou Stitch) possa usar para recriar a mesma sensação visual.
1. Tema Visual e Atmosfera
Leia o estilo mais amplo primeiro para entender o clima geral:
- Fundo raiz: Qual é o fundo do
bodyou elemento raiz? Cremes claros (faixa #f) indicam arejado/limpo; escuro (faixa #0-#2) indica dramático/intenso. - Filosofia de espaços em branco: Os valores de espaçamento são generosos (32px+) ou apertados? Verifique valores de padding/margin em contêineres raiz, wrappers de seção e componentes de cartão.
- Densidade: Conte os componentes por página/seção. Poucos com espaço = minimalista; muitos empacotados = denso em informações.
- Temperatura de cor: Os neutros são quentes (cremes, tons de terra) ou frios (azul-acinzentados, ardósias)?
- Sensação geral: Sintetize em 1-2 frases ricas que capturem o clima.
Procure por esses sinais no código-fonte:
| Localização na Fonte | O Que Informa |
|---|---|
background-color raiz ou bg-* do Tailwind em layouts | Clareza/escurecimento geral |
| Escala de espaçamento no config Tailwind ou variáveis CSS | Filosofia de espaços em branco |
| Número de componentes vs padding do wrapper | Densidade |
Nomenclatura de propriedades customizadas (--warm-* vs --cool-*) | Intenção de temperatura de cor |
| Comentários em arquivos de tema | Intenção de design nas próprias palavras do desenvolvedor |
2. Paleta de Cores e Papéis
Extraia cada cor única da base de código e atribua papéis funcionais. Pesquise em todas as camadas:
Onde encontrar cores:
| Camada | O que Pesquisar |
|---|---|
| Propriedades customizadas CSS | --color-*, --primary, --bg-* |
| Config Tailwind | theme.extend.colors |
| Arquivos de tema/token | Objetos de cor, paletas |
| Estilos de componentes | background-color, color, border-color |
| Estilos inline/scoped | Classes bg-*, text-* em templates |
| Objetos de tema CSS-in-JS | Chaves colors, palette |
Como organizar: Agrupe cores por função, não por matiz:
- Fundação Primária — Cores de fundo e superfície
- Destaque e Interativo — Botões CTA, estados ativos, links
- Tipografia e Hierarquia de Texto — Texto primário, secundário, terciário
- Estados Funcionais — Sucesso, erro, aviso, informação
Para cada cor, crie um nome descritivo que evoque o caráter da cor em vez de seu valor hex bruto:
- ❌
#294056→ "Azul" - ✅
#294056→ "Azul Marinho Teal Profundo" — CTA Primário, navegação ativa
A deduplicação é importante. Bases de código frequentemente têm cores quase duplicadas (ex.: #333 e #2C2C2C). Consolide-as sob um nome que melhor represente a cor pretendida.
3. Regras de Tipografia
Extraia o sistema tipográfico completo:
Famílias de fontes:
- Verifique CSS
font-family, TailwindfontFamily, links do Google Fonts ou declarações locais@font-face. - Observe o caráter de cada fonte: geométrica vs humanista, serifada vs sem serifa, a sensação que evoca.
Escala tipográfica (hierarquia):
- Encontre cada nível de título (H1-H6) e texto do corpo, anotando:
font-size(em rem ou px)font-weight(valor numérico + nome descritivo)letter-spacing(e o porquê — elegância? compactação?)line-height(generoso para legibilidade? apertado para exibição?)
- Mapeie o uso nos componentes: Qual nível de título os cartões de produto usam? E as seções de herói?
Princípios de espaçamento:
- Como o espaçamento do texto se relaciona com a escala geral de espaçamento?
- Padrões de espaçamento entre letras em títulos vs corpo
- Filosofia de altura de linha (generosa/relaxada para corpo, mais apertada para exibição)
4. Estilos de Componentes
Analise os 4-5 primitivos de UI mais importantes:
Botões:
- Raio de borda (e o que comunica — lúdico? profissional? minimalista?)
- Esquema de cores para variantes primária, secundária e fantasma (ghost)
- Estados hover/focus/active e tempo de transição
- Proporções de padding (horizontal vs vertical)
Cartões / Contêineres:
- Raio de borda (frequentemente diferente dos botões — ligeiramente mais arredondado)
- Estratégia de sombra: plana, sombras sutis no hover ou sempre elevada?
- Tratamento de borda: bordas finas, destaques coloridos ou nenhuma?
- Padding interno (generoso ou compacto?)
- Tratamento de imagem dentro dos cartões (sangria total, com padding, arredondada?)
Navegação:
- Padrão de layout (barra horizontal, barra lateral vertical, gaveta)
- Tratamento tipográfico (caixa alta, espaçamento entre letras, peso)
- Indicadores de estado ativo/hover (sublinhado, cor, fundo)
- Comportamento mobile (hambúrguer, navegação inferior, gaveta)
Inputs e Formulários:
- Estilo de borda e comportamento no estado de foco
- Consistência do raio de borda com os botões
- Tamanho do padding e alvo de toque
Componentes Específicos do Domínio:
- Identifique 1-2 componentes únicos deste projeto (ex.: cartões de produto, widgets de dashboard, bolhas de chat) e descreva seus padrões de estilo.
5. Princípios de Layout
Extraia o sistema estrutural:
Grade e Estrutura:
- Largura máxima do conteúdo (a partir de
max-widthem contêineres) - Sistema de colunas (CSS Grid, padrões Flexbox, breakpoints definidos)
- Breakpoints responsivos (a partir de media queries ou config Tailwind)
Estratégia de Espaços em Branco:
- Unidade base de espaçamento (grade de 8px? 4px? personalizada?)
- Margens de seção (quanto espaço entre seções principais)
- Padding nas bordas (margens da página em diferentes breakpoints)
Alinhamento e Equilíbrio Visual:
- Padrões de alinhamento de texto (heróis centralizados, corpo alinhado à esquerda)
- Proporções imagem-texto
- Distribuição de peso visual
Comportamento Responsivo:
- Mobile-first ou desktop-first?
- Como as grades colapsam? Escala de padding?
- Tamanho dos alvos de toque
6. Notas para Geração no Stitch
Sintetize a extração em prompts acionáveis para o Stitch:
- Linguagem da atmosfera: Traduza o clima em descritores naturais
- Referências de cor: Liste as cores por nome descritivo + hex
- Prompts de componentes: Escreva 2-3 exemplos de prompts que recriariam componentes-chave no Stitch
- Orientação para iteração: Dicas para refinar telas neste sistema de design
Fase 3: Escrever o DESIGN.md
Monte tudo no formato padrão DESIGN.md. Coloque-o em .stitch/DESIGN.md no diretório do projeto (crie o diretório .stitch/ se ele não existir).
[!IMPORTANT] Você DEVE incluir o frontmatter YAML no topo do arquivo com o mapeamento de
nameecolors, exatamente como mostrado no exemplo em examples/DESIGN.md. Esses dados estruturados são necessários para que outras skills possam analisar o sistema de design.A falha em incluir este bloco YAML com pelo menos os tokens de cor principais é uma falha no uso correto desta skill.
Use o formato do exemplo em examples/DESIGN.md como seu modelo. O arquivo deve começar com o bloco YAML, seguido pelas seções markdown:
# Design System: [Nome do Projeto]
**ID do Projeto:** [Se conhecido, caso contrário omitir]
## 1. Tema Visual e Atmosfera
[Descrição rica em 2 parágrafos sobre clima, filosofia e características principais]
## 2. Paleta de Cores e Papéis
### Fundação Primária
### Destaque e Interativo
### Tipografia e Hierarquia de Texto
### Estados Funcionais
## 3. Regras de Tipografia
### Hierarquia e Pesos
### Princípios de Espaçamento
## 4. Estilos de Componentes
### Botões
### Cartões e [Contêineres Específicos do Domínio]
### Navegação
### Inputs e Formulários
### [Componentes Específicos do Domínio]
## 5. Princípios de Layout
### Grade e Estrutura
### Estratégia de Espaços em Branco
### Alinhamento e Equilíbrio Visual
### Comportamento Responsivo e Toque
## 6. Notas do Sistema de Design para Geração no Stitch
### Linguagem a Usar
### Referências de Cor
### Prompts de Componentes
### Iteração Incremental
Fase 4: Integração (Opcional)
Se o usuário quiser empurrar o sistema de design para o Stitch:
- Passe para a skill
manage-design-systempara as chamadas de criação/atualização do MCP - O DESIGN.md que você escreveu é a entrada — a skill manage-design-system lida com a integração da API Stitch
Se o usuário quiser apenas o documento, você terminou após a Fase 3.
Checklist de Qualidade
Antes de entregar o DESIGN.md, verifique:
- Cada cor tem um nome descritivo, código hex e papel funcional
- A tipografia inclui família de fontes, descrição do caráter e hierarquia completa
- Os estilos dos componentes descrevem forma, cor, estados e transições
- O layout inclui largura máxima, grade, breakpoints e estratégia de espaçamento
- As notas de geração para Stitch usam linguagem natural, não sintaxe CSS
- A seção de atmosfera parece texto editorial, não documentação técnica
- Cores quase duplicadas são consolidadas
- O documento captura a intenção por trás do estilo, não apenas valores brutos
Dicas para Melhor Extração
- Leia comentários e mensagens de commit. Desenvolvedores frequentemente documentam a intenção de design em comentários de código (
/* seção hero — respirável */) e mensagens de commit. Esses são ouro para entender o porquê. - Verifique bibliotecas de tokens de design. Se o projeto usa
style-dictionary,@tokens-studioou similar, esses arquivos são a fonte mais autoritativa de valores de design. - Arquivos de tema têm mais sinal do que estilos de componentes. Um
theme.tsque define uma paleta informa o sistema de design pretendido; estilos inline espalhados em componentes informam o que realmente foi enviado. Ambos importam, mas comece pelo tema. - Config Tailwind é um sistema de design. Se um projeto tem um
tailwind.config.jspersonalizado, esse é o sistema de design — extraia dele primeiro, depois verifique componentes para sobrescritas. - Propriedades customizadas CSS são intencionais. Se um desenvolvedor definiu
--brand-primary, ele está dizendo que isso é um token de design. Respeite isso.