brandmd

brandmd é uma ferramenta de linha de comando que transforma qualquer site ativo em uma especificação de design legível por máquina. Ela renderiza a página, observa como ela é estilizada e escreve o resultado como DESIGN.md, o formato definido pela especificação aberta @google/design.md: frontmatter YAML contendo tokens tipados para cores, tipografia, cantos arredondados, espaçamento e componentes, seguido por seções de prosa como Visão Geral, Cores, Tipografia, Layout, Elevação e Profundidade, Formas, Componentes e O que fazer e o que não fazer. Os arquivos gerados destinam-se a ser validados sem erros sob o comando de lint oficial do @google/design.md. A motivação é que agentes de codificação de IA produzem interfaces genéricas quando carecem das cores, fontes, espaçamento e convenções de componentes do projeto. Colocar o DESIGN.md na raiz de um projeto fornece esse contexto antecipadamente para agentes como Claude Code, Cursor, Gemini CLI, Codex e Google Stitch. Uma única invocação, por exemplo, executar npx brandmd contra uma URL e gravar o DESIGN.md, é suficiente; não é necessária a redação manual da especificação. A extração é local. A ferramenta inicia um navegador headless via Playwright, rola a página para acionar conteúdo carregado dinamicamente, descarta banners de cookies e sobreposições, lê propriedades personalizadas de CSS do :root (incluindo media queries) e coleta estilos computados de elementos visíveis. Em seguida, agrupa cores semelhantes, deriva uma escala de espaçamento e unidade de grade base, identifica raios de borda e estilos de sombra, e reconhece padrões de componentes como botões, cartões e inputs. A detecção de tipografia é consciente da função, preferindo fontes de exibição sobre cabeçalhos e corpo, enquanto ignora fontes monoespaçadas, de fallback e de ícones. Nenhuma chamada de LLM ou chaves de API estão envolvidas no caminho padrão. Diversos formatos de saída são oferecidos além do DESIGN.md padrão: tokens JSON brutos para scripts e toolchains, propriedades personalizadas de CSS, um bloco @theme do Tailwind v4 e um guia de marca HTML autossuficiente com amostras, espécimes de tipo, visualização de espaçamento e exemplos de sombra. Múltiplas URLs podem ser passadas para mesclar tokens entre páginas, com frequências normalizadas por página para que uma página de documentação repleta de botões não prevaleça sobre a página inicial. Uma flag dark opcional extrai tokens de tema escuro usando prefers-color-scheme. Uma flag vision opcional usa uma chave de API do Gemini para adicionar estilo de ilustração, humor de fotografia e dicas de voz de redação lidas a partir de uma captura de tela. Uma flag agent adicional escreve regras do Cursor e arquivos de skill tanto no caminho universal .agents/skills quanto no diretório de skills do Claude Code, para que o contexto da marca seja capturado sem configuração manual. O próprio brandmd também é distribuído como uma Agent Skill instalável, e um repositório companheiro fornece skills de marca prontas para Tailwind CSS, shadcn/ui, Vercel, Mintlify e Anthropic. A ferramenta é deliberadamente fail-closed. Páginas de bloqueio, respostas de acesso negado, paredes de login e páginas com pouca evidência causam uma recusa com código de saída 2 em todos os formatos e nenhum artefato é gravado, para que uma captura ruim não sobrescreva um DESIGN.md bom; uma flag de override força a saída, mas marca o artefato em cada formato. As gravações são transacionais, usando arquivos temporários e renomeação com rollback. Os códigos de saída distinguem sucesso, erros operacionais ou de validação, recusas e drift detectado pelo subcomando check. Um subcomando check compara uma página implantada com um DESIGN.md commitado para detectar drift de design, comparando cores por função semântica em vez de um conjunto não ordenado de valores hexadecimais, e falhando builds em funções perdidas ou repintadas e fontes primárias ou secundárias alteradas. A documentação é franca sobre seus limites: o drift de componentes é relatado, mas não falha o build, alterações de fontes secundárias podem passar despercebidas e páginas que mudam dinamicamente podem produzir alterações principais espúrias, portanto, os resultados devem ser reproduzidos antes de serem confiados. Um subcomando diff separado compara dois arquivos DESIGN.md e produz um relatório em markdown de cores, tipografia, espaçamento, raios compartilhados e únicos, além de diferenças por componente, junto com uma síntese do que copiar. Uma galeria de exemplos de saídas do Stripe, Linear, GitHub, Vercel, Notion, Cursor, Anthropic, Figma, Supabase, Raycast e outros está incluída no repositório. O projeto possui licença MIT.