Communitygithub.com

UI (21 Grams UI)

Polimento de UI que foi construída por IA para que deixe de parecer gerada por IA e siga princípios comprovados de UX e animação, usando os próprios componentes e tokens do projeto.

O que é UI (21 Grams UI)?

Esta skill, conhecida como 21 Grams UI, é uma ferramenta profissional para polir interfaces de usuário que foram originalmente geradas por IA, eliminando as marcas típicas de design automatizado e aplicando um conjunto fixo de regras de UX e animação. Em vez de substituir o design system do projeto, ela trabalha exclusivamente com os componentes, tokens de design e bibliotecas já existentes, garantindo que o resultado pareça nativo e bem pensado. A skill oferece um inventário completo de regras que cobrem desde raio de borda aninhado, botões com escala ao pressionar, tipografia enxuta, espaçamento baseado em escala 4pt, até motion design sem bounce e com easing adequado. Além disso, referencia 20 princípios de UX e animação (como squash & stretch, anticipation, Fitts's law), 10 hacks de design CSS (como bordas alpha, paletas OKLCH, dvh para altura mobile) e 20 técnicas de animação (como transform-origin no gatilho, stagger de listas, layout compartilhado entre cartão e detalhe). Seu fluxo de trabalho é rigoroso: inventário e auditoria antes de qualquer alteração, aplicação de correções nos tokens e componentes compartilhados, verificação no navegador com screenshots antes/depois e relatório detalhado. A skill é ativada quando o usuário pede para "deixar menos IA", "refinar", "aplicar 21 grams" ou auditar a UI contra o estilo da casa e os princípios mencionados. Suporta qualquer projeto JavaScript/TypeScript com design system (shadcn/ui, Radix, MUI, Chakra, etc.) ou sem ele, usando valores padrão para preencher lacunas.

Funciona com~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/ilbognov/21grams/tree/HEAD/skills/ui

Perguntar na sua IA favorita

Abre um novo chat com esta habilidade de agente já pré-carregada.

Documentação

21 Grams UI

Uma passagem sobre a UI que já existe. 21 Grams UI (o pacote de UI da família 21 Grams) não redesenha o produto e não traz seu próprio kit de UI. Ela remove as marcas de UI construída por IA e aplica um conjunto fixo de regras através dos componentes e tokens que o projeto já possui, para que o resultado pareça pensado, pareça rápido e ainda pertença ao produto.

Regra zero: usar os componentes do próprio projeto

Cada mudança passa pelo que o projeto já usa. 21 Grams UI nunca constrói um conjunto paralelo de componentes.

  1. Faça um inventário antes de tocar em qualquer coisa. Anote os tokens de design ou tema (variáveis CSS, configuração Tailwind, arquivos de tema), a biblioteca de componentes (shadcn/ui, Radix, MUI, Chakra, um kit interno, um sistema de design do cliente), o conjunto de ícones, a biblioteca de gráficos e a biblioteca de animação. Registre como cada componente compartilhado é chamado e onde ele vive.
  2. Corrija as coisas onde elas vivem. Uma regra de botão vai para o Button do projeto (um token, uma variante, uma prop ou seus estilos), nunca em uma cópia avulsa em uma única tela. Uma regra de cor ou raio vai para o token, nunca para valores fixos.
  3. Nunca adicione um componente quando já existe um para o trabalho, e nunca adicione uma dependência (kit de UI, conjunto de ícones, gráfico ou biblioteca de animação) para obter um efeito 21 Grams UI. Use o que já está instalado. Sem uma biblioteca de animação, use transições CSS.
  4. Quando uma peça está genuinamente faltando (sem controle segmentado, sem switch), construa-a a partir dos primitivos e tokens existentes do projeto, seguindo sua estrutura de arquivos e nomenclatura. Diga isso no relatório.
  5. Os valores do estilo da casa são padrões apenas para lacunas. rules/ e tokens/tokens.css fornecem valores para o que o projeto não decidiu. Mapeie-os para os tokens do projeto. Nunca cole tokens.css junto a um sistema existente.
  6. A marca permanece a do projeto. Cores, fontes, logotipos, estilo de ícone e voz da marca nunca são substituídos. 21 Grams UI muda como eles são usados (contraste, hierarquia, espaçamento, movimento), não o que eles são.

Precedência: as palavras do usuário, depois o sistema de design e marca do projeto, depois o estilo da casa 21 Grams UI. Os princípios, hacks e técnicas de animação se aplicam em todos os lugares, expressos nos próprios componentes do projeto.

O que está dentro

  1. Estilo da casa. Oito áreas em rules/: radius.md (aninhado 12/8/4), buttons.md (36px, press .97), motion.md (suave, a partir do gatilho, sem bounce), type.md (enxuto, poucos tamanhos), spacing.md (escala 4pt agrupada), colour.md (um acento, AA), elevation.md (preenchimentos tonais), copy.md (claro e útil). Mais três arquivos de componente: icons.md (um estilo, line, solid ou duotone, nunca misturado), charts.md (linhas, colunas e barras horizontais) e toggles.md (switch e controle segmentado). Valores padrão estão em tokens/tokens.css.
  2. Os 20 princípios. Princípios de UX e animação em references/principles.md.
  3. Os 10 hacks de design. Detalhes de artesanato em nível CSS em references/design-hacks.md.
  4. As 20 técnicas de animação. Regras de movimento em nível de implementação (origens, durações, stagger, press, drag, layout compartilhado) em references/animation-craft.md.
  5. Os 10 hacks de tipografia. Largura reservada para negrito, text-box trim, underline offset, espaçamento de sobrescrito, tipo de exibição fluido, siglas em small-caps, aspas curvas, truncamento médio, hifenização automática e títulos com limite de linhas, em references/typography.md.
  6. As 20 regras unslop. Composição e conteúdo (badges de preenchimento, rótulos redundantes, itálicos aleatórios, mono decorativo, arte de herói abstrata, recursos de peso igual, títulos vagos, brilhos, alinhamento óptico, estados de carregamento) em references/unslop.md.

Se uma skill de visualização de dados estiver instalada, carregue-a também sempre que um gráfico estiver envolvido.

Fluxo de trabalho

  1. Faça o inventário (regra zero). Se o projeto não tiver nenhum sistema de design, diga isso e use os padrões do estilo da casa.
  2. Audite antes de mudar qualquer coisa. Percorra a tela ou componente e liste as descobertas agrupadas por área (raio … cópia), número do princípio, número do hack e número da técnica. Use as listas de verificação no final de references/principles.md, references/design-hacks.md, references/animation-craft.md, references/typography.md, references/unslop.md e rules/icons.md. Cada descoberta recebe o arquivo e linha, o que está errado, a correção e em qual componente ou token existente a correção vai. Sinalize cada lugar onde uma regra 21 Grams UI entra em conflito com o sistema de design do projeto, para que o usuário possa decidir qual vence.
  3. Mostre a auditoria ao usuário como uma lista curta e pergunte antes de aplicar mudanças amplas. Correções pequenas e óbvias no escopo solicitado podem ser aplicadas diretamente.
  4. Aplique as correções nesta ordem: tokens → componentes compartilhados → telas. Mantenha os diffs limitados ao que foi auditado e nas convenções do próprio projeto (formatação, lint, nomenclatura).
  5. Verifique no navegador. Screenshots antes e depois de cada tela alterada. Verifique hover, press, focus, loading, erro, ambos os temas e movimento reduzido. Meça o contraste do botão e do texto; não olhe de olho. Para movimento, grave o antes e depois se possível. Uma página antes/depois com um divisor arrastável e interações funcionais em ambos os lados é a maneira mais clara de revisar um polimento.
  6. Relate o que mudou por área, princípio, hack e técnica, quais componentes e tokens foram tocados, e qualquer coisa que ficou por fazer.

Estilo da casa em resumo (padrões para lacunas)

  • Raio 12 containers / 8 controles / 4 partes pequenas, aninhado como externo − padding. Sem formato pílula, exceto tags e toggles.
  • Botões 36px (32 compactos, 40 proeminentes), raio 8, 14/500, um primary sólido, um primary por visualização, hover = apenas passo de cor, press = passo de cor + scale(.97) 150ms, carregamento mantém largura.
  • Movimento: sem bounce em UI do dia a dia. Menus 220ms in / 175ms out de scale(.95) no gatilho, painéis 240 / 190, entradas ease-out, saídas ease-in (~80% da entrada), linhas de lista com stagger 30ms, interações frequentes instantâneas.
  • Tipo: as fontes do projeto (Geist quando não há nenhuma). Mono é apenas para código, nunca para rótulos, sobrancelhas, badges, timestamps ou números (tabular-nums na sans alinha figuras). Tamanhos 12/14/16/22/28, pesos 400/500/600, títulos −0.022em, no máximo quatro tamanhos por tela. No mobile, títulos sobem um degrau: seção 18, card 16.
  • Envio de chat no mobile é um botão de avião de papel 44×44 apenas com ícone e aria-label="Send".
  • Espaçamento: escala 4pt. Mais apertado dentro de grupos do que entre eles (4 / 6 / 16 / 24–32 / 48). Chevron de select 12px da direita, padding-right 36px.
  • Cor: um acento (ações, foco, seleção), cores de status separadas, texto do botão ≥ 4.5:1 em ambos os temas com --on-accent por tema.
  • Elevação: superfícies em repouso são um passo de preenchimento sem borda ou sombra. Apenas camadas flutuantes recebem um anel e sombra. Modo escuro é mais claro por camada.
  • Ícones: um estilo por produto, line, solid ou duotone, e nunca misturado em um menu, nav, toolbar, lista ou card. Estados selecionados mudam de cor, não de estilo de ícone. Uma biblioteca de ícones, uma largura de traço, um tamanho por grupo.
  • Cópia: botões verbo + objeto, erros com causa e correção, letra inicial maiúscula em cada item (sentence case), sem emoji, sem palavras de hype.

Não negociáveis (dos 20 princípios)

  • Movimento de UI acionado pelo usuário é 120–300ms, e saídas são cerca de 80% da entrada. Nunca linear para movimento.
  • Easing corresponde à direção: enter ease-out, exit ease-in, A→B na tela ease-in-out. Sem overshoot em UI do dia a dia.
  • Interações de alta frequência (navegação por teclado, destaque de lista, abas em ferramentas) são instantâneas.
  • Cada entrada é reconhecida em menos de 100ms. Use UI otimista para salvamentos. Mostre progresso após 400ms.
  • Áreas de toque são pelo menos 44×44 em touch e 32×32 em desktop denso, mesmo quando o ícone é menor.
  • Um foco e uma ação primária por visualização. Escureça o contexto quando algo ganha foco.
  • Números longos são agrupados. Inputs aceitam formatos bagunçados e retornam o valor limpo.
  • Posicionamento e ícones padrão, a menos que haja um motivo para não fazer.
  • Cada estado do componente é projetado: idle, hover, pressed, loading, success, error, disabled.
  • prefers-reduced-motion: remova movimento, escala e overshoot, mantenha uma breve mudança de opacidade.

Não negociáveis (dos 10 hacks)

  • Raio aninhado: interno = externo − padding.
  • Bordas são alpha (rgb(0 0 0 / .12)), nunca hex cinza sólido em superfícies variadas.
  • Paletas e gradientes em OKLCH (in oklch em gradientes).
  • Traço do ícone corresponde ao peso do texto adjacente.
  • Scroll horizontal desbota nas bordas com uma máscara.
  • Troca de ícones com crossfade usando filter: blur(4px).
  • Modo escuro: cada camada superior é mais clara (página < card < menu).
  • Altura total mobile: dvh/svh, nunca 100vh puro.
  • Fotos de produtos com fundo branco em cards com fundo colorido: mix-blend-mode: multiply.

Não negociáveis (dos 10 hacks de tipografia)

  • Negrito ao passar o mouse ou ao selecionar nunca desloca o layout (reserve a largura do negrito).
  • Rótulos de linha única em botões e badges são centralizados opticamente (text-box-trim).
  • Sublinhados de links evitam descendentes (text-underline-offset: 0.2em). Sobrescritos não quebram o ritmo da linha.
  • Pontuação real no texto: aspas curvas, apóstrofos, travessões, ….
  • Nomes que diferem no final são truncados no meio. Títulos de cards em grades são limitados ao mesmo número de linhas.

Não negociáveis (das 20 técnicas de animação)

  • Popovers e menus crescem a partir do seu gatilho (transform-origin no gatilho), começam em scale(.95), nunca scale(0), e saem de volta para o gatilho.
  • Estados antigos e novos se sobrepõem. Nunca há um quadro em branco entre Save e Saved.
  • Arrastos acompanham o ponteiro 1:1 sem transição enquanto segurados, e fazem rubber band além dos limites.
  • Expansão card → detalhe expande o mesmo elemento (layoutId / view transition compartilhado), nunca uma substituição desconectada.
  • Controles segmentados e abas revelam o rótulo ativo com uma máscara que viaja com o indicador.
  • Knobs em movimento esticam cerca de 12% (preservando área). Sucesso ganha um pulso.

Marcas de IA a remover

Estilos de ícone misturados (um house sólido ao lado de uma pasta outline, um outline que se torna sólido quando selecionado), duas bibliotecas de ícones em uma tela, emoji usado como ícone, badges "NEW" de preenchimento acima de manchetes, sobrancelhas que repetem o título, uma palavra aleatória em itálico ou mono em uma manchete, rótulos em mono, sobrancelhas, badges, timestamps ou números ("tech" mono maiúsculo como // 01 STATUS), orbes 3D brilhantes no lugar do produto real, fileiras de cards de recursos iguais, manchetes "X, conheça Y.", bordas de gradiente brilhantes, gradientes índigo-para-violeta, texto gradiente, sombras coloridas de brilho, o mesmo raio de 16px em tudo (raio interno igual ao externo), botões pílula ao lado de inputs arredondados, hover com scale-up em cards e botões, 300ms ease-in-out em tudo, fade-up no carregamento da página, p-6 gap-6 uniforme, cards dentro de cards, sombra mais borda mais raio em cada bloco, grey-500 para todo texto secundário, emoji em títulos e texto como "Desbloqueie", "Turbo", "Perfeito" ou "Ops!".

Créditos

Os princípios, hacks e técnicas de animação são parafraseados e estendidos de cinco vídeos de design de curta duração: "20 Principles of UX & Animation", "10 Niche Design Hacks", "20 Ways to Make Beautiful AI Animations", "10 Niche Typography Hacks" e "20 Ways to Unslop AI Designs". Veja o README para créditos.

Habilidades Relacionadas