Uma skill de UI Design para o Claude Code

A ui-designer é uma skill gratuita e open source para o Claude Code que lê os tokens de design do seu projeto antes de estilizar qualquer coisa, trabalha em modo marca ou produto e olha a tela renderizada antes de entregar. Ela dá nota de 0 a 10 para telas existentes, discorda uma vez quando um pedido piora a interface e confere o próprio resultado contra 46 padrões que deixam a interface com cara de gerada por IA, adaptados da Impeccable.

Por · · 11 min de leitura · Licença MIT

Instale com um comando

Terminal
$ npx skills add Gustavosilveira23/claude-design-skills -s ui-designer -g

Isso instala a skill para todos os projetos da sua máquina. Peça ao Claude Code para construir, estilizar ou dar acabamento a uma interface e a skill carrega sozinha. Você também pode chamá-la com /ui-designer. Nos meus testes, um pedido comum de nota para uma tela nem sempre carregou a skill, então para auditoria eu chamo pelo nome.

O mesmo comando funciona no Cursor, no Codex e em outros agentes que leem o formato Agent Skills. No claude.ai, compacte a pasta ui-designer em zip e envie em Customize > Skills, com a execução de código ligada. O código está em github.com/Gustavosilveira23/claude-design-skills, com licença MIT, ao lado de outras cinco skills de design.

A tela dos dois últimos guias

Este guia fecha um caso. No guia da ux-research, a pesquisa sobre uma ferramenta de agendamento descobriu que admins novos não conectam a agenda antes de ver o produto funcionando. No guia da ux-designer, esse achado virou uma estratégia com cinco decisões, e o passo de agenda que a ferramenta tem hoje tirou 7 de 25 numa auditoria CLEAR. Aqui, a ui-designer constrói a tela a partir da estratégia.

Gravei numa sessão nova do Claude Code, só com esta skill instalada, dentro de um projeto pequeno com tokens de design (styles/tokens.css) e componentes próprios. A tela antiga ignora os dois, como tela legada costuma fazer. O projeto e as duas telas são fictícios. As respostas da skill são reais, encurtadas e traduzidas do inglês. As minhas falas foram escritas para a demonstração e não dizem nada sobre tokens nem sobre screenshots: o que a skill fez com isso, fez por conta própria.

Uma nota de 0 a 10 para a tela antiga

Claude Code

/ui-designer Este é o passo 3 do nosso onboarding: onboarding/step-calendar.html. Dê uma nota visual de 0 a 10. Não mude nada ainda.

Nota: 3/10. O layout é organizado, mas a página ignora o design system do próprio projeto. A maior parte do texto reprova no contraste, os blocos de provedor nunca mostram qual você escolheu e a página quebra no celular. Tratei como contexto Product. Renderizei a página a 1280px e 375px e testei os estados de hover, selecionado e erro. Não mudei nada. Crítico1. Não usa o design system. styles/tokens.css e components.css existem, mas a página não liga nenhum dos dois: Arial no lugar da Inter, #3b82f6 no lugar do token de destaque, um botão feito à mão no lugar do .btn-primary.2. A maior parte do texto reprova no contraste. O corpo fica em torno de 3,3:1, a etiqueta do passo 2,6:1, os escopos 2:1. O token muted, #5B616E, já passa.3. Escolher um provedor não muda nada na tela. A borda azul no meu screenshot é só o hover, e some quando o mouse sai.4. Quebra no celular. Não há tag de viewport e o card tem 560px fixos: a 375px a página rola de lado até 624px.

As estimativas de contraste se confirmam: medidas no navegador, as três razões são 3,25, 2,64 e 2,0 para 1. Comparada com a auditoria CLEAR do último guia, a lente visual achou dois problemas que a auditoria de UX não citou: a tela ignora um design system que o projeto já tem e rola de lado no celular. Ela também deixou passar o problema que a auditoria de UX pôs em primeiro lugar: a tela pede acesso antes de mostrar qualquer coisa funcionando. Esse é um problema de fluxo, e achá-lo é trabalho da ux-designer.

Ela lê o projeto antes de estilizar

Depois colei a estratégia do guia da ux-designer e pedi uma versão nova do passo.

Claude Code

Nossa revisão de UX gerou esta estratégia para o passo. Ele vem logo depois que a pessoa agenda uma reunião de teste na própria página. Refaça como onboarding/step-calendar-v2.html. Desktop; nosso design system está em styles/. [estratégia colada]

Construí a versão nova como onboarding/step-calendar-v2.html e deixei a original intacta. Conferi no navegador a 1280px, com o painel de TI fechado e aberto e com foco de teclado, e corrigi os dois problemas que esses screenshots mostraram. - O motivo para conectar é algo que a pessoa vê. O título é "This booking isn't on your calendar yet." Abaixo dele vem um pedaço da quinta-feira dela, com a reunião de teste desenhada como um contorno tracejado marcado "Missing". Isso mira o seu maior risco: ela fica satisfeita com o teste, então a página mostra o que ainda está quebrado.- Conectar é um clique. O padrão antigo de escolher e depois clicar em Submit saiu, junto com o erro 403.- A sua linha de escopo fica logo abaixo dos botões, palavra por palavra.- "Skip for now" é uma saída de verdade, com "Your page stays live." embaixo. Usa o seu design system: toda cor, espaçamento, raio e tamanho de fonte vem dos seus tokens. Para decidir: a reunião e os links são provisórios. A página de resumo para a TI ainda não existe. Os seus tokens só definem cores claras, e eu não inventei cores escuras fora do sistema. Os tokens citam a Inter, mas nada carrega a fonte, então a página cai na fonte do sistema.

A página nova liga o tokens.css e o components.css do projeto, e o CSS dela não tem nenhuma cor fixa. Esse é o Step 0.5 da skill: se existem tokens, usar os tokens e nunca criar valores concorrentes. O visual principal saiu do maior risco da estratégia. Se a reunião de teste for boa o bastante para ninguém se dar ao trabalho de conectar, a página responde mostrando que essa reunião não está na agenda da pessoa.

Ela olha a tela antes de entregar

A maior parte das checagens da skill acontece no código. O Step 6.0 é a exceção: quando a interface pode ser renderizada, a skill abre com o Playwright ou o Chrome DevTools, tira um screenshot, corrige o que vê e olha de novo. Se não consegue renderizar, tem que dizer que pulou a checagem.

Na sessão ela olhou sem ninguém pedir. O navegador bloqueou a abertura de um arquivo local, então ela subiu um servidor local pequeno. O primeiro screenshot mostrou os rótulos de hora fora das linhas. Ela mediu o desvio com um script (16px onde se esperavam 7px), corrigiu, conferiu o painel de TI aberto e o anel de foco pelo teclado e desligou o servidor. A skill resume a divisão de trabalho numa frase curta: "a imagem confirma; o código prova" (tradução minha).

As duas telas a 1280px, mesmo recorte. As duas são fictícias, feitas para a demonstração. A nova é o arquivo que a skill entregou antes do pedido seguinte.
MedidaAntesDepois
Elementos de texto abaixo do contraste WCAG AA4 de 70 de 20
Botões de provedor alcançáveis pelo teclado0 de 22 de 2
Tamanhos de fonte em uso5, de 11 a 20px3: 14, 16 e 24px
Cores fixas no CSS da própria página110
Botões principais"Submit""Google Calendar", "Microsoft Outlook"
Controle mais baixo35px (Submit)24px (dois links de texto)

Medi as duas telas com um script no navegador, a partir dos estilos computados. A última linha é a que a skill não pegou. "Need IT to approve this?" e "Skip for now" têm 24px de altura: passam no mínimo da WCAG 2.2 (SC 2.5.8) e ficam abaixo dos 44pt que a própria skill recomenda.

Ela discute com um degradê roxo

Então fiz o pedido que a maioria das ferramentas de IA simplesmente executaria.

Claude Code

Está meio sem graça. Deixa mais moderno: degradê roxo no card e um efeito de vidro.

Nota de design: eu seguraria estes dois antes de construir. - Um degradê roxo acrescentaria uma segunda cor de marca. O destaque do seu sistema é azul, e a barra de progresso e os links já usam essa cor. Essa pessoa está avaliando se a ferramenta parece confiável o bastante para recomendar ao time. Se o card do onboarding tem uma cor diferente do resto do produto, ele começa a parecer template.- Um efeito de vidro precisa de algo atrás para desfocar. Aqui o card fica sobre um fundo cinza liso, então o desfoque não tem com o que trabalhar. Ele só deixaria o texto lavado. Acho que o "sem graça" vem de três lacunas específicas: carregar a Inter, descolar o card do fundo com uma sombra suave e fazer o pedaço de agenda parecer a agenda real da pessoa. Quer que eu construa do jeito que você pediu ou que eu tente estas três?

Ela não mexeu no arquivo. A skill discorda uma vez e depois faz o que você decidir; se eu tivesse insistido, ela teria construído o degradê. O raciocínio volta ao Step 0. No primeiro turno ela classificou esta tela como contexto Product, uma ferramenta que as pessoas usam todo dia, onde contenção é o padrão. Numa landing page, que é contexto Brand, o mesmo degradê pode ser a escolha certa. Nas palavras da skill: "mesma técnica, veredito oposto" (tradução minha).

De onde vêm os números

Skills e prompts de design repetem os mesmos números como se fossem lei. Alguns são norma, outros são convenção, e um vem da decoração de salas de estar. A skill agora diz qual é qual:

Regra na skillO que éFonte
Espaçamento em grid de 8pt, passos de 4px dentro de componentesConvenção. O que importa é todo valor sair de uma escala só.Material Design (grid de 8dp), spec.fm
Tamanhos de fonte a partir de uma razão, de 4 a 5 tamanhosConvenção da tipografia editorial.Tim Brown, A List Apart, 2011
Divisão de cor 60-30-10Regra prática da decoração de interiores, usada como proporção inicial para manter o destaque raro.Nenhum estudo em telas
Contraste de texto 4,5:1, texto grande 3:1Norma.WCAG 2.2, SC 1.4.3
Área de toque de 44pt ou 48dp, nunca abaixo de 24pxDiretrizes de plataforma, mais um piso da norma.Apple HIG, Material Design, WCAG 2.2 SC 2.5.8
Superfície escura #121212, texto branco a 87%Diretriz de uma plataforma.Material Design, "Dark theme"

Até a auditoria que fiz antes de escrever este guia, a skill dava a maioria desses números sem dizer de onde vinham. Agora cada um leva a sua etiqueta, e a lista completa está na seção Sources and Credits da skill.

Um detector de slop, com crédito

Antes de mostrar qualquer interface, a skill confere o resultado contra 46 padrões visuais que deixam a interface com cara de gerada por IA. O catálogo é adaptado da Impeccable, a skill de design do Paul Bakaus, filtrado para os contextos desta skill. Cada padrão tem um sinal de detecção, muitos deles um grep que dá para rodar nas classes do Tailwind, e diz se é tolerável em contexto Brand ou nunca aceitável em Product. Cinco que ela confere primeiro:

  • Uma faixa colorida descendo por um lado de um card arredondado.
  • Efeito de vidro usado como enfeite.
  • Texto em degradê em qualquer lugar que não seja um único título de hero.
  • A paleta padrão de roxo ou violeta com ciano, a não ser que a marca peça.
  • Easing com quique ou elástico em elementos de interface.

Para o catálogo completo, com comandos próprios, use a Impeccable direto. Esta skill aplica uma versão filtrada enquanto constrói.

Onde ela ainda erra

Antes de escrever este guia, auditei a skill do jeito que ela audita uma tela. Parte do que encontrei:

  • Ela classificava "Cancel" como ação destrutiva.
  • Ela fazia o anel de foco com box-shadow, que some no modo de alto contraste do Windows.
  • Ela recomendava, como acabamento, três técnicas que o próprio detector de slop condena.
  • Um dos exemplos dela usava transition: all, um padrão que ela proíbe em outro trecho.

Tudo isso está corrigido na skill. A demonstração mostrou mais dois limites. Os links de 24px da tela nova passaram despercebidos. E número estimado no olho ainda precisa de medida: no último guia, a ux-designer contou à mão 5 de 6 pares de cor reprovados; medidos, eram 4 de 6, e aquele guia agora diz isso.

Fontes e créditos

A skill usa o trabalho de outras pessoas no momento em que ele importa. As fontes principais:

Os créditos completos estão no README do repositório.

Perguntas frequentes

Uso a ui-designer ou a frontend-design?

Elas servem a trabalhos diferentes. A frontend-design, skill oficial da Anthropic, puxa para uma estética marcante e combina com uma página nova. A ui-designer trabalha dentro de um projeto que já existe: lê seus tokens e componentes primeiro e parte da contenção em telas de produto. Dá para instalar as duas.

Qual a diferença para a Impeccable?

A Impeccable é uma skill de design completa, com comandos próprios e um catálogo de antipadrões. A ui-designer usa uma versão adaptada e filtrada desse catálogo como uma das checagens. Se o que você quer é o catálogo, instale a Impeccable.

Preciso usar grid de 8pt?

Não. A skill parte dele porque uma escala vale mais que valores soltos, e segue a escala que o seu projeto já tiver. Um valor fora da escala só precisa de um motivo declarado.

A regra 60-30-10 funciona em interface?

Ela vem da decoração de interiores, e não encontrei estudo que teste a regra em telas. A skill usa como proporção inicial para manter a cor de destaque rara, não como meta a medir.

Funciona num projeto que já tem design system?

É o caso para o qual ela foi feita. Antes de gerar qualquer coisa, lê seus tokens e componentes, usa os dois e só estende quando falta algo. Na demonstração, o CSS da tela nova ficou com zero cores fixas.

Ela precisa do Playwright para olhar a tela?

Para olhar, sim: ela usa o servidor MCP do Playwright ou do Chrome DevTools, o que você tiver. Sem nenhum dos dois, ela avisa que pulou a checagem visual e roda mesmo assim as checagens que dá para fazer no código.

Funciona no Cursor ou no Codex?

Sim. O comando de instalação funciona para agentes que leem o formato Agent Skills, incluindo Cursor e Codex. No claude.ai, compacte a pasta ui-designer em zip e envie em Customize > Skills.

Dá para usar depois da ux-designer?

É a ordem que eu uso. A ux-research reúne a evidência, a ux-designer desenha o fluxo e a ui-designer constrói a tela. Este guia é o terceiro passo do mesmo caso. As seis skills estão no índice.

Gustavo Silveira

Product designer sênior. Desenhei produtos na Hotmart e na Sympla e hoje trabalho com produtos de IA. Está construindo um? Vamos conversar.