StyleSeed: Design Rules para Agentes de IA Deixarem de Fazer UI Genérica

O teu agente de IA escreve CSS que funciona, mas parece que foi gerado por uma máquina. O StyleSeed é o motor de design que resolve isso e obriga o agente a cumprir as regras.

Pede ao Claude Code para fazer um dashboard e ele devolve-te uma coisa funcional. Botões ali, tabelas acolá. Tecnicamente certo, visualmente insípido. Ao modelo faltam as regras de design que um humano aprende em anos de experiência.

Foi a pensar nisto que o bitjaru criou o StyleSeed. Em vez de mais uma coleção de paletas de cores ou tokens de design, traz um motor de juízo visual: 74 regras escritas de forma explícita para agentes de IA aplicarem. Ao contrário de um PDF bonito, são markdown que o teu agente lê automaticamente sempre que trabalha.

Nota de atualização (11 de outubro de 2026): o README atual reorganizou as skills numa só (styleseed, com 22 workflows). Os comandos /ss-score, /ss-review, /ss-verify, /ss-build e /ss-setup descritos abaixo passaram a /styleseed score, /styleseed review, /styleseed verify, /styleseed build e /styleseed setup (no Codex, $styleseed ...), e a instalação passou a ser npx -y skills add bitjaru/styleseed -a claude-code -y --copy.

O Problema: Dados não são Juízo

A maioria dos projetos que tentam melhorar a UI gerada por IA faz a mesma coisa: despejam tokens de design no contexto do modelo — paletas, fontes, sombras, especificações de componentes. O problema é que um junior designer com a paleta da Toss na mão continua a fazer dashboards feios. Um senior designer com apenas tons de cinzento faz algo refinado.

A diferença não são os dados. É o juízo: saber onde colocar o quê e, mais importante, o que não fazer.

O StyleSeed materializa esse juízo em regras concretas e acionáveis por um LLM. Regras como:

• O preto refinado é #2A2A2A, não #000
• Apenas uma cor de destaque. Tudo o resto em escala de cinzento. Uma segunda cor é o “tell” mais rápido de UI gerada
• Números a 2:1 com a unidade: um valor de 48px sobre uma unidade de 24px. Tamanhos iguais achatam a hierarquia
• Lei do raio aninhado: inner = outer − padding, para um cartão e o botão lá dentro partilharem o mesmo raio visual
• Sombras em camadas com opacidade ≤ 8%: não uma drop shadow única e dura
• Estado “normal” é cinzento: a cor marca a exceção, nunca pintar uma lista toda de arco-íris

Nenhuma destas regras está documentada nos manuais. Estão incorporadas em anos de experiência. O StyleSeed escreve-as, organiza-as em seis categorias (cor, ritmo espacial, hierarquia, elevação, variação de componentes, motion; contagem por confirmar), e entrega-as ao agente num ficheiro que ele lê em cada prompt.

Motor + Skins: A Arquitetura

O StyleSeed separa duas coisas que a maioria dos sistemas mistura:

O motor (engine): agnóstico a marcas. São as 74 regras visuais, 48 componentes React (32 primitivas + 16 padrões), uma skill de agente com 22 workflows internos, e um sistema de motion nomeado. Funciona com qualquer paleta de cores.

As skins — a identidade visual. É só um ficheiro theme.css com variáveis de cor. Vêm 7 skins incluídas (Toss, Stripe, Linear, Notion, Raycast, Arc, Vercel) e mais 58+ disponíveis via awesome-design-md. Ou crias a tua: mudas o --brand e está feito.

O resultado é que podes trocar a skin sem perder as regras de design. O mesmo motor que te dá um dashboard refinado no estilo Linear dá-te uma landing page à Stripe. Coerente, nunca genérico.

Quality Gate: A Peça Que Falta

A inovação mais prática do StyleSeed é o quality gate: um conjunto de skills que reveem a UI gerada, pontuam-na de 0 a 100, e corrigem as violações antes de ta mostrarem.

• /ss-score: analisa o código, atribui uma pontuação com categorias e devolve uma lista prioritária de correções
• /ss-review: auditoria profunda de compliance com as regras de design
• /ss-verify: renderiza o ecrã, tira screenshot, e pontua o que vê (espaço morto, fontes não carregadas, estados vazios)
• /ss-build: o loop completo: bloqueia o look → constrói → pontua → corrige até ≥ 80 → depois mostra

O próprio README é honesto sobre o alcance: em 120 células de teste, as regras sozinhas deram resultados inconsistentes (Codex +1,6 pontos; Claude Code −3,7) e foi o ciclo de renderizar, pontuar e rever que melhorou ambos em 5,3 pontos; 80 pontos não equivalem a aprovação de um designer. Mesmo assim, isto muda o workflow. Em vez de pedires um ecrã e receberes uma primeira versão fraca para iterar, o agente faz o trabalho de refinamento sozinho. E como as regras estão num ficheiro de design lock (STYLESEED.md), a próxima sessão não começa do zero.

Sistema de Motion Nomeado

Uma área onde a UI gerada é particularmente fraca é a animação. O default é sempre o mesmo fade genérico. O StyleSeed resolve isto com motion seeds — cinco personalidades de animação que se aplicam consistentemente em cinco contextos (entrance, exit, hover, press, layout; contagens por confirmar):

• Spring: saltitante, energético, divertido (Arc, Toss)
• Silk: suave, elegante, contínuo (Stripe, Linear)
• Snap: instantâneo, decisivo, preciso (Raycast, Linear)
• Float: leve, gentil, sonhador (Apple)
• Pulse: rítmico, vivo, marcado (Discord, apps de música)

Além disso, há uma biblioteca de moves nomeados (toggle-flip, tilt-3d, magnetic, glow-pulse, shimmer) que se podem invocar por palavra-chave. E o sistema respeita prefers-reduced-motion automaticamente.

E Para Quem Já Tem UI Feita?

O StyleSeed também funciona para retrofit. Se já tens um ecrã construído que parece “gerado por IA”, podes executar /ss-score src/... para obter uma pontuação e lista de problemas, e depois /ss-review para aplicar correções: retintar para a cor de destaque correta, remover icon-chips, ajustar a escala tipográfica, criar um ponto focal. O objetivo é ≥ 80 pontos.

Como Começar

A forma mais rápida é copiar uma frase para o teu agente:

Refer to https://github.com/bitjaru/styleseed — read engine/CLAUDE.md
and engine/DESIGN-LANGUAGE.md, then build a SaaS dashboard.
Use skins/stripe/theme.css for the color palette.

Para teres as skills instaladas (e o quality gate a funcionar):

npx skills add bitjaru/styleseed

Depois é só executar /ss-setup no Claude Code ou $ss-setup no Codex, escolher uma skin, e começar a construir. O agente faz o resto.

Se usas Cursor, copia o ficheiro .cursorrules para a raiz do projeto. Se usas Windsurf ou Copilot, a frase do prompt acima chega, com menos enforcement, mas ainda com 90% dos benefícios.

Conclusão

O StyleSeed não compete com o shadcn/ui nem com o Tailwind UI: é a camada que falta entre os componentes e o resultado final: o juízo de design que transforma código funcional em UI refinada. E como é markdown simples e MIT, não tens desculpa para continuares a receber dashboards com gradiente indigo, três cores de destaque e body text a 14px no desktop.

O repo está em github.com/bitjaru/styleseed, e a demo ao vivo em styleseed-demo.vercel.app. Vale a pena ver o before/after para perceberes a diferença que um quality gate faz.

Recursos adicionais

• StyleSeed Demo: antes e depois ao vivo
• StyleSeed no GitHub (MIT)
• awesome-design-md: 58+ skins de marca
• shadcn/ui: componentes base do StyleSeed