Levango7/design-md-skill

design-md · Fluxo de trabalho de contrato de design com DESIGN.md

Extraia "decisões de design" do código de estilo espalhado e consolide-as em um DESIGN.md — um contrato de design legível tanto por agentes de IA quanto por humanos. Este skill cobre o ciclo completo:

Pesquisa (opcional, com internet) → Extrair (extract) → Gerar (scaffold) → Aplicar ao código → Verificar (verify) → Gate de CI

DESIGN.md é um conceito proposto pelo Google Stitch: um documento de sistema de design em texto simples, colocado na raiz do projeto, para que qualquer agente de IA de codificação que o leia produza UIs visualmente consistentes. AGENTS.md gerencia "como construir", enquanto DESIGN.md define "qual é a aparência".

Estrutura de Diretórios

Localização	Finalidade
scripts/wcag.py	Motor de contraste WCAG 2.1: analisa tokens.css / design-tokens.json, combina pares automaticamente conforme regras (texto 4.5:1, UI 3:1), exit code pode ser usado como gate de CI
scripts/extract.py	Extrai um rascunho de tokens de design de qualquer URL (cores dominantes, pilha de fontes, cantos arredondados), produzindo tokens-draft.json + esqueleto DESIGN.draft.md
scripts/scaffold.py	Gera tudo a partir de um JSON de tokens: tokens.css (tokens em formato duplo) + tailwind.extend.js + preview.html + relatório de contraste
scripts/fetch_ref.py	Busca DESIGN.md de referência do awesome-design-md (84 marcas, com fallback de dois canais: raw → gh api)
scripts/research.py	Pesquisa online DeepSeek Search/Fetch (faturamento direto, desligado por padrão: requer consentimento explícito do usuário com a flag --yes-billing; chave lida de arquivo local / variável de ambiente, nunca ecoada)
references/spec.md	Especificação do arquivo DESIGN.md: frontmatter + tokens YAML + 11 seções do corpo + regras de escrita
references/lessons.md	Lições aprendidas: tokens em formato duplo, armadilhas de diluição alfa, divisão de accent, contratos de dados (de auditorias reais de produção)
references/research.md	Uso da API DeepSeek Search/Fetch + catálogo de referência do awesome-design-md (84 slugs completos)
references/verify.md	Lista de verificação + template de integração com CI (npm script / GitHub Actions)
templates/design-tokens.example.json	Exemplo de entrada funcional (dois temas, todos passando AA) — basta adaptar

Início Rápido

# 0) Ambiente: python3 ≥ 3.9, apenas bibliotecas padrão
python3 scripts/wcag.py --help

# 1) Pesquisa (opcional): extrair rascunho de tokens de um site de referência
python3 scripts/extract.py --url https://example.com --out-dir ./design-draft
#    → design-draft/tokens-draft.json + design-draft/DESIGN.draft.md

# 2) Buscar DESIGN.md de uma marca conhecida como referência (para inspiração, não cópia)
python3 scripts/fetch_ref.py --list                 # Ver os 84 slugs disponíveis
python3 scripts/fetch_ref.py --slug linear.app      # → ./DESIGN.reference-linear.app.md

# 2b) (Opcional) Pesquisa online DeepSeek — faturamento direto (5 yuans / 1000 requisições
#     bem-sucedidas), desligado por padrão:
#     Só execute com --yes-billing após consentimento explícito do usuário; a chave
#     é fornecida por arquivo local, nunca entra no diálogo/log
python3 scripts/research.py --yes-billing check     # Verificar chave (lê %USERPROFILE%\.deepseek\api_key por padrão)
python3 scripts/research.py --yes-billing search --query "fintech dashboard design site:dribbble.com" --count 8

# 3) Gerar o conjunto completo de engenharia de tokens (usando seu JSON de tokens alinhado como entrada)
python3 scripts/scaffold.py --tokens meus-tokens.json --out ./design-out
#    → tokens.css / design-tokens.json / tailwind.extend.js / preview.html / contrast-report.txt

# 4) Verificar (execução independente ou integrada ao CI)
python3 scripts/wcag.py --tokens ./design-out/tokens.css     # Entrada CSS
python3 scripts/wcag.py --tokens ./design-out/design-tokens.json   # Entrada JSON
python3 scripts/wcag.py --pair "#E6E9EF:#0A0C10:4.5"         # Consulta rápida de par hex

Fluxo de Trabalho Padrão (Ordem de Execução para o Agente)

1. Definir requisitos: Leia o estado atual do projeto (existe DESIGN.md / tokens / biblioteca de componentes?), defina a direção do tema (escuro primeiro? cores da marca? tom do setor — finanças / ferramentas de desenvolvedor / saúde…).
2. Pesquisar (opcional): Use os métodos em references/research.md para fazer pesquisa de design — DeepSeek Search para encontrar sites de referência (faturamento direto e desligado por padrão: primeiro informe ao usuário a estrutura de custos e obtenha consentimento explícito, só então use --yes-billing; sem consentimento, use apenas coleta embutida), DeepSeek Fetch / coleta embutida para converter páginas em Markdown e analisá-las; busque 1-3 DESIGN.md do mesmo setor no awesome-design-md.
3. Extrair / Rascunhar: extract.py gera rascunho → Com base na estrutura de 11 seções de references/spec.md, mescle e dê significado manualmente/pelo agente (transforme "cor #5e6ad2 aparecendo 200 vezes" em "cor primária da marca, usada para CTA e anéis de foco").
4. Gerar: Organize em um JSON de tokens padronizado → scaffold.py produz todo o conjunto de arquivos de engenharia (incluindo página de visualização para o usuário ver o resultado).
5. Aplicar: Integre tokens.css / mapeamento Tailwind ao projeto; implemente componentes conforme §4 do DESIGN.md.
6. Verificar: wcag.py passa verde + checklist de references/verify.md item por item; conecte o gate ao CI (veja template em verify.md).
7. Iterar: Qualquer alteração de cor → deve executar wcag.py novamente, não confie na intuição; mudanças de decisão de design devem ser registradas de volta no DESIGN.md (com anotações de versão).

Regras Rígidas (Devem Ser Seguidas)

1. Contraste não é baseado em intuição: Qualquer alteração de cor deve executar wcag.py. Texto ≥4.5:1, componentes de interface / bordas ≥3:1.
2. Tokens em formato duplo: Cada cor deve gerar --x (hex) e --x-rgb (canais), caso contrário os modificadores de opacidade do Tailwind falham silenciosamente (veja lessons.md #1).
3. Não use bg-{warn}/10 (diluição alfa) para fundos claros — fundos claros devem ser tokens independentes (--warn-soft). Na prática, a diluição piora o contraste em temas claros.
4. Divida a cor da marca em duas variações: --accent (texto / links) e --accent-solid (botões com fundo sólido). Um único valor não pode satisfazer simultaneamente "texto claro em fundo escuro" e "fundo escuro sob texto branco" para ≥4.5:1.
5. Use --border-strong para bordas interativas (3:1), --border apenas para separação decorativa.
6. Marque honestamente Known Gaps: Itens não extraídos (estados de erro de formulário, versão clara, substitutos de fontes privadas) devem ser registrados no DESIGN.md, não finja completude.
7. Referência ≠ Cópia: O awesome-design-md analisa características CSS públicas de cada marca; ao citar, leia seus "métodos" (hierarquia, ritmo, trade-offs), não se passe pela marca; projetos comerciais devem observar licenças de marca e fontes.

Segurança

• Nunca ecoe nenhuma chave de API. Ordem de resolução da chave: --key-file → variável de ambiente DEEPSEEK_API_KEY → variável de ambiente DEEPSEEK_API_KEY_FILE → arquivo padrão %USERPROFILE%\.deepseek\api_key (recomenda-se que o usuário o crie no terminal, a chave não passa pelo diálogo/log). A saída completa do research.py tem a chave mascarada como sk-***.
• Proteção de faturamento (desligado por padrão, 2026-10): DeepSeek Search/Fetch são APIs de faturamento direto (5 yuans / 1000 requisições bem-sucedidas cada; limite de conta: Search 100 QPS / Fetch 25 QPS). research.py sem --yes-billing (e variável de ambiente DEEPSEEK_BILLING_CONSENT diferente de 1) recusa-se a executar (exit 3) — o agente deve primeiro explicar os custos ao usuário e obter consentimento explícito antes de adicionar a flag; ambientes de faturamento por consumo como opencode são considerados como não consentidos por padrão.
• Sem chave configurada, não assuma que "é necessário internet" como indicado no docstring — extract.py usa coleta local com urllib, DeepSeek é apenas um aprimoramento.
• A coleta respeita robots.txt e frequência de acesso; extract.py coleta no máximo 5 folhas de estilo, cada uma com limite de 512KB.

Relação com Outros Recursos

• awesome-design-md (VoltAgent, MIT): Conjunto de 84 análises DESIGN.md de sites reais. Este skill fornece fetch_ref.py para acesso imediato; é uma "biblioteca de material de referência", e este skill é o "motor de fluxo de trabalho".
• DeepSeek Search/Fetch: https://api.deepseek.com/v1/tools/search|fetch. Pesquisa web em tempo real e coleta de conteúdo (com sintaxe site:/lang:/after:). Cobrado por requisição (5 yuans / 1000 requisições bem-sucedidas — apenas requisições com retorno 200 e resultado não vazio são cobradas; falhas/timeouts/resultados vazios não são cobrados). Limite de conta: Search 100 QPS / Fetch 25 QPS (exceder retorna 429, research.py faz backoff automático e retenta). Este skill fornece scripts/research.py como wrapper de chamada (chave nunca ecoada; desligado por padrão — requer consentimento explícito do usuário e a flag --yes-billing, veja §Segurança).
• Google Stitch lint oficial (opcional): npx @google/design.md lint DESIGN.md.