Extrair Sistema de Design do Código Frontend

O que Extrair Sistema de Design do Código Frontend faz?

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 precisar construir ou renderizar a aplicação.

Por Que Isso Existe

A habilidade design-md trabalha a partir de HTML renderizado. Mas muitas vezes você tem um código-fonte e deseja entender seu sistema de design antes mesmo de conseguir executar o aplicativo — talvez as dependências estejam faltando, a compilação esteja quebrada, ou você só queira uma auditoria rápida. Esta skill lê os próprios arquivos fonte: folhas de estilo, arquivos de componentes, configurações de tema e configurações do Tailwind. É mais rápida e funciona em qualquer lugar.

Quando Usar

• O usuário tem um código-fonte frontend e quer extrair ou documentar seu sistema de design
• O usuário quer 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 quer criar um DESIGN.md a partir do código-fonte existente
• O aplicativo não pode ser compilado/renderizado, mas o código-fonte está disponível
• O usuário quer unificar ou reconciliar estilos inconsistentes em um código-fonte

Pré-requisitos

• Acesso ao diretório fonte do projeto frontend
• Nenhuma dependência de compilação ou runtime necessária — esta skill lê apenas os 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

Examine a raiz do projeto em busca de arquivos reveladores:

Arquivo Sinalizador	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 nas deps	CSS-in-JS
Apenas arquivos .css / .scss / .less	CSS puro / SASS
theme.js / theme.ts / tokens.js	Arquivos de tokens de design

Leia 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 informações de estilo.

2. Mapear a Árvore de Origem

Identifique os diretórios e arquivos principais que você analisará:

src/
├── components/     ← Estilos em nível de componente
├── 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 e espaçamentos personalizados
• globals.css / global.css — Propriedades personalizadas CSS (variáveis)
• Quaisquer arquivos theme.* ou tokens.*
• Configuração de biblioteca de componentes (ex.: chakra-theme.ts, vuetify.config.ts)

3. Ler Orientações Específicas 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 puro / SASS / Less → 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 corresponde 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 depois sintetize-os em linguagem descritiva.

O objetivo não é despejar todas as propriedades CSS — é entender a intenção por trás das escolhas de estilo e descrevê-las em linguagem humana e editorial que outro designer (ou o 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 body ou elemento raiz? Um tom claro (faixa #f) sinaliza arejado/limpo; escuro (faixa #0-#2) sinaliza dramático/misterioso.
• Filosofia do espaço 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 = mínimo; muitos compactados = denso em informações.
• Temperatura de cor: Os neutros são quentes (cremes, castanhos) ou frios (azul-acinzentados, ardósia)?
• Sensação geral: Sintetize em 1-2 frases ricas que capturem o clima.

Procure por esses sinais no código-fonte:

Localização no Código-Fonte	O Que Isso Te Diz
background-color raiz ou bg-* do Tailwind em layouts	Clareza/escuridão geral
Escala de espaçamento na config do Tailwind ou variáveis CSS	Filosofia do espaço em branco
Número de componentes vs. padding do wrapper	Densidade
Nomes de propriedades personalizadas (--warm-* vs --cool-*)	Intenção da temperatura de cor
Comentários em arquivos de tema	Intenção de design nas próprias palavras do desenvolvedor

2. Paleta de Cores e Funções

Extraia cada cor única do código-fonte e atribua funções. Busque em todas as camadas:

Onde encontrar cores:

Camada	O Que Pesquisar
Propriedades personalizadas CSS	--color-*, --primary, --bg-*
Configuração do 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:

1. Base Primária — Cores de fundo e superfície
2. Destaque e Interativas — Botões CTA, estados ativos, links
3. Tipografia e Hierarquia de Texto — Texto primário, secundário, terciário
4. 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 hexadecimal bruto:

• ❌ #294056 → "Azul"
• ✅ #294056 → "Azul-marinho esverdeado profundo" — CTA primário, navegação ativa

A deduplicação é importante. Os códigos-fonte geralmente têm cores quase duplicadas (ex.: #333 e #2C2C2C). Consolide-as sob um único nome que melhor represente a cor pretendida.

3. Regras Tipográficas

Extraia o sistema tipográfico completo:

Famílias de fontes:

• Verifique font-family no CSS, fontFamily no Tailwind, links do Google Fonts ou declarações locais de @font-face.
• Observe o caráter de cada fonte: geométrico vs. humanista, serifada vs. sans, a sensação que ela 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 por quê — elegância? compacidade?)
  • line-height (generoso para legibilidade? apertado para exibição?)
• Mapeie o uso dos 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. Estilizações de Componentes

Analise os 4-5 primitivos de UI mais importantes:

Botões:

• Raio de canto (e o que ele comunica — divertido? profissional? minimalista?)
• Esquema de cores para variantes primária, secundária e fantasma
• Estados de hover/foco/ativo e temporização de transição
• Proporções de padding (horizontal vs. vertical)

Cartões / Contêineres:

• Raio de canto (geralmente diferente dos botões — ligeiramente mais arredondado)
• Estratégia de sombra: plana, sombras sutis ao passar o mouse ou sempre elevada?
• Tratamento de borda: bordas finas, acentos coloridos ou nenhuma?
• Padding interno (generoso ou compacto?)
• Tratamento de imagem dentro dos cartões (sangria total, com padding ou arredondada?)

Navegação:

• Padrão de layout (barra horizontal, barra lateral vertical, gaveta)
• Tratamento tipográfico (maiúsculas, espaçamento entre letras, peso)
• Indicadores de estado ativo/hover (sublinhado, cor, fundo)
• Comportamento móvel (hambúrguer, navegação inferior, gaveta)

Campos de Entrada e Formulários:

• Estilo de borda e comportamento do estado de foco
• Consistência do estilo de canto com os botões
• Dimensionamento de padding e alvo de toque

Componentes Específicos do Domínio:

• Identifique 1-2 componentes exclusivos deste projeto (ex.: cartões de produto, widgets de painel, 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 (de max-width em contêineres)
• Sistema de colunas (CSS Grid, padrões Flexbox, breakpoints definidos)
• Breakpoints responsivos (de media queries ou configuração do Tailwind)

Estratégia de Espaço em Branco:

• Unidade base de espaçamento (grade de 8px? 4px? personalizada?)
• Margens de seção (quanto espaço entre seções principais)
• Padding de borda (margens de página em diferentes breakpoints)

Alinhamento e Equilíbrio Visual:

• Padrões de alinhamento de texto (heróis centralizados, corpo alinhado à esquerda)
• Proporções de imagem para texto
• Distribuição de peso visual

Comportamento Responsivo:

• Mobile-first ou desktop-first?
• Como as grades se colapsam? Escala de padding?
• Dimensionamento de alvo de toque

6. Notas de Geração para o Stitch

Sintetize a extração em prompts acionáveis para o Stitch:

• Linguagem da atmosfera: Traduza o clima em descritores naturais
• Referências de cores: Liste as cores por nome descritivo + hexadecimal
• Prompts de componentes: Escreva 2-3 exemplos de prompts que recriariam componentes-chave no Stitch
• Orientação de iteração: Dicas para refinar telas neste sistema de design

---

Fase 3: Escrever o DESIGN.md

Monte tudo no formato padrão do 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 name e colors, exatamente como mostrado no exemplo em examples/DESIGN.md. Esses dados estruturados são necessários para que outras habilidades possam interpretar o sistema de design.

A não inclusão deste bloco YAML com pelo menos os tokens de cor principais é uma falha no uso correto desta habilidade.

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:

# Sistema de Design: [Nome do Projeto]
**ID do Projeto:** [Se conhecido, caso contrário omitir]

## 1. Tema Visual e Atmosfera
[Descrição rica em 2 parágrafos do clima, filosofia e características principais]

## 2. Paleta de Cores e Funções
### Base Primária
### Destaque e Interativas
### Tipografia e Hierarquia de Texto
### Estados Funcionais

## 3. Regras Tipográficas
### Hierarquia e Pesos
### Princípios de Espaçamento

## 4. Estilizações de Componentes
### Botões
### Cartões e [Contêineres Específicos do Domínio]
### Navegação
### Campos de Entrada e Formulários
### [Componentes Específicos do Domínio]

## 5. Princípios de Layout
### Grade e Estrutura
### Estratégia de Espaço 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 Cores
### Prompts de Componentes
### Iteração Incremental

---

Fase 4: Integração (Opcional)

Se o usuário quiser enviar o sistema de design para o Stitch:

1. Passe para a habilidade manage-design-system para as chamadas MCP de criar/atualizar
2. O DESIGN.md que você escreveu é a entrada — a habilidade manage-design-system cuida da integração com a API do Stitch

Se o usuário quiser apenas o documento, você termina após a Fase 3.

---

Lista de Verificação de Qualidade

Antes de entregar o DESIGN.md, verifique:

• Cada cor tem um nome descritivo, código hexadecimal e função
• A tipografia inclui família de fontes, descrição de caráter e hierarquia completa
• Os estilos de 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 o 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 uma Melhor Extração

• Leia comentários e mensagens de commit. Os desenvolvedores geralmente documentam a intenção de design em comentários de código (/* seção de herói — arejada */) e mensagens de commit. Eles são ouro para entender o porquê.
• Verifique bibliotecas de tokens de design. Se o projeto usa style-dictionary, @tokens-studio ou similar, esses arquivos são a fonte mais confiável de valores de design.
• Arquivos de tema têm sinal mais forte do que estilos de componentes. Um theme.ts que define uma paleta informa o sistema de design pretendido; estilos inline dispersos em componentes informam o que realmente foi implementado. Ambos importam, mas comece pelo tema.
• A configuração do Tailwind é um sistema de design. Se um projeto tem um tailwind.config.js personalizado, esse é o sistema de design — extraia dele primeiro, depois faça verificações pontuais nos componentes em busca de substituições.
• Propriedades personalizadas CSS são intencionais. Se um desenvolvedor definiu --brand-primary, ele está te dizendo que este é um token de design. Respeite isso.