Benchmark mede se agentes de IA respeitam design systems

Por que o benchmark existe

Equipes de design systems vivem a mesma conversa sem números: desenvolvedores geram interfaces com agentes de código e ninguém consegue afirmar se o resultado segue o sistema. O open-design-system-bench é um benchmark aberto, criado dentro da Nord Security a partir do Aurora, seu design system de produção, e generalizado para bibliotecas React e TypeScript. Ele mede duas coisas: se agentes usam o sistema corretamente e quanto cada camada de documentação escrita pela equipe ajuda de fato.

Duas ferramentas em um repositório

A auditoria estática roda em segundos, sem chave de API: sete checagens avaliam presença de AGENTS.md, qualidade do catálogo de componentes, higiene de exports, distância vocabular entre os nomes do sistema e os nomes que modelos inventam, legibilidade de tokens, legibilidade de deprecações e capacidade das páginas de documentação serem lidas como texto. O resultado é um AI-Readiness Score de 0 a 100 com três faixas: Emerging (abaixo de 40), Invested (40 a 70) e AI-native (70 ou mais).

O benchmark executa agentes reais contra componentes reais. Os prompts descrevem necessidades de usuário e nunca citam o componente esperado - um linter verifica isso contra o catálogo extraído e já pegou vazamentos das palavras Switch, Section e Header. A saída é avaliada em seis dimensões: imports, fidelidade de API, disciplina de tokens, acessibilidade estática, compilação e um LLM-as-judge para rubricas que nenhum parser cobre. Uma regra central: a nota final é a pior dimensão, não a média, e "ignorou o design system" é métrica de primeira classe.

O que foi encontrado

O teste rodou contra quatro sistemas reais: Aurora e três sistemas abertos anonimizados (A, B e C). Cinco achados:

1. Todo sistema tinha um bug real. A extração calcula a API pública da união do barrel raiz com o mapa de exports do package.json, e isso revelou defeitos já em produção: três componentes nunca reexportados e um diretório inteiro inalcançável. Nenhum era conhecido; todos foram corrigidos depois.

2. Ninguém é AI-native ainda. Os escores ficaram entre 52,2 e 63,4 - todos na faixa Invested, incluindo times com mais pessoal de documentação. O trabalho restante é tornar o sistema legível a máquinas, algo distinto de escrever mais páginas para humanos.

3. Os modos de falha não aparecem na média. Três padrões podem produzir notas idênticas: engajar e errar (usa o sistema, erra a API), evitar o sistema (recria tudo à mão e passa nas checagens por nunca tocá-lo - o pior caso para a equipe) e arquitetar e colapsar (não compila).

4. Modelos chegam com vocabulário próprio. Modelos esperam nomes como Switch, Box e TextField. Sistemas alinhados a esse léxico empírico (minerado das 898 gerações avaliadas) têm conformidade sem esforço extra; vocabulários idiossincráticos pagam um imposto de alucinação. O alinhamento mais alto medido foi 97,2, de um dos sistemas abertos.

5. As próprias premissas da ferramenta falharam. Ao apontar o extrator para os sistemas abertos, três suposições quebraram (formatos de barrel e de índices de diretório), e a ferramenta precisou ser ajustada.

Comportamento dos agentes

Uma rodada comportamental separada, só contra os dois kits do Aurora com cinco configurações de modelo, mostrou o argumento do gate de pior dimensão: os modelos DeepSeek e o Sonnet single-shot compilam pouco (26% a 11%) mas ignoram Aurora raramente (4% a 9%); as configurações GPT 5.6 compilam 83% e 94%, porém ignoram o design system em 55% e 63% das células.

Sobre documentação: a diferença entre nenhum guia e qualquer guia é maior que a diferença entre níveis de guia. Arquivos de instrução elevam os modelos DeepSeek em 23,1 e 26,1 pontos e o Sonnet em 24,1, mas movem o GPT 5.6 Luna apenas 6,3 e o Terra 11,5. O modelo melhor sem ajuda (Luna, 69,0) termina empatado no último lugar com orientação plena, porque responde pouco à documentação.

Uso e limites

A recomendação é executar a auditoria grátis, corrigir falhas (normalmente exports e deprecações), enviar ganhos baratos (AGENTS.md, changelog legível, arquivo de tokens) e rodar o benchmark antes e depois. O número para conversas de orçamento é o Lift: delta entre contexto guiado e sem guia, reproduzível. Somente uma das seis dimensões é julgada por LLM; as outras cinco são mecânicas. O escopo da versão 1 é React e TypeScript, sem telemetria, e o benchmark custa de alguns dólares (sanidade) a dezenas (varredura mensal) em chamadas de API.