Polimento de UI
Esta habilidade contém o polimento visual para superfícies, ícones e animações, com o valor exato que cada detalhe assume. Ela é aplicada uma vez que a interação subjacente está sólida, e um achado de polimento nunca substitui uma interação quebrada.
Valores exatos, polimento opcional
Os valores abaixo são exatos, não faixas a serem aproximadas. cubic-bezier(0.2, 0, 0, 1) não é cubic-bezier(0.4, 0, 0.2, 1), e 0.96 não é 0.95. Os ajustes ópticos e o limite de padding concêntrico são as exceções. Eles são pontos de partida, julgados a olho.
Mantenha a biblioteca de componentes, tokens e densidade do projeto, e corresponda à sua linguagem de movimento sempre que nenhuma regra aqui fornecer um valor. Uma convenção de projeto deliberada e consistente, como um estilo sem sombras, é uma preferência e não um achado. O mesmo detalhe feito de duas maneiras dentro do projeto é um achado.
Quebra de texto, renderização de fontes, números tabulares e espaçamento de texto pertencem a better-typography. Áreas de clique, suporte a teclado, ARIA e o requisito de movimento reduzido pertencem a better-accessibility. Agrupamento, espaçamento entre seções, pontos de quebra e RTL espacial pertencem a better-layout, exceto espelhamento de ícones direcionais. Tokens de cor e medição de contraste pertencem a better-colors.
Raio externo igual a raio interno mais padding
Onde superfícies aninhadas compartilham um recuo visível e uniforme, o raio externo é o raio interno mais o padding mais qualquer largura de borda. Acima de 24px de padding, ou onde o padding é deliberadamente assimétrico, trate as camadas como superfícies separadas e mantenha o token de raio de cada uma. As receitas estão em surfaces.md.
Alinhar opticamente onde a geometria parece estranha
Onde o centralização geométrica parece estranha, ajuste a olho. Dê a um botão 2px a menos de padding no lado do ícone, desloque um triângulo de play em direção à sua ponta e corrija glifos assimétricos no próprio SVG. As receitas estão em surfaces.md.
Sombras para elevação, bordas para estrutura
Onde uma borda existe apenas para criar profundidade, substitua-a por valores de box-shadow transparentes em camadas. Mantenha bordas em divisores, separadores, células de tabela e estados selecionados. Mantenha-as também em inputs de formulário, cujo limite precisa de contraste não-textual de 3:1 sob better-accessibility. Anéis de foco também pertencem a better-accessibility.
O modo de cores forçadas remove todos os box-shadow. Mantenha border: 1px solid transparent sob um anel de sombra para que esse modo ainda desenhe uma borda. As receitas estão em surfaces.md.
Contornar imagens em preto ou branco puro
Dê a imagens de conteúdo um outline de 1px embutido por 1px. Use oklch(0 0 0 / 0.1) no modo claro e oklch(1 0 0 / 0.1) no escuro. Nunca use um preto aproximado da paleta, um neutro matizado ou a cor de destaque, porque o matiz aparece como uma franja colorida na borda da imagem. Pule obras de arte transparentes, como logotipos e ilustrações. A receita está em surfaces.md.
Transições, não keyframes, para estado interativo
Direcione mudanças de estado interativo com transições CSS ou molas de uma biblioteca de animação, que redirecionam quando o usuário reverte no meio do trajeto. Keyframes executam uma linha do tempo fixa e não podem reverter, então reserve-os para sequências que rodam uma vez. Veja animations.md.
Escala de pressionar para 0.96
Um botão pressionado escala para 0.96 ao longo de 150ms com ease-out, e um botão desabilitado nunca escala. Dê ao botão uma opção de exclusão onde o movimento distrairia, através da API de variante existente do componente ou de uma prop static. Veja receitas para CSS, Tailwind e Motion.
Interações de alta frequência respondem instantaneamente
Toques de tecla, hovers em linhas e trocas de abas recebem feedback instantâneo, ou uma transição de 150ms ou menos em opacity ou background-color. Reserve movimento expressivo para momentos pouco frequentes, como o primeiro carregamento de uma visualização, um estado de sucesso ou um estado vazio.
Cada mudança de estado animada também deixa uma dica estática na forma de uma cor, ícone ou rótulo. O movimento nunca é o único canal de feedback.
Bloquear movimento atrás da preferência de movimento reduzido
better-accessibility é dona do requisito, e nenhuma receita aqui é enviada sem ele. Execute movimento, escala e desfoque apenas sob prefers-reduced-motion: no-preference. Sob movimento reduzido, substitua-os por uma transição de opacidade em vez de remover o elemento instantaneamente. Receitas para CSS, Tailwind e Motion estão em animations.md.
Espaçar entradas pouco frequentes em 100ms
Onde a sequência comunica hierarquia em uma entrada em palco, divida o conteúdo em partes semânticas, como título, descrição e ações. Espaçe-as com 100ms de diferença, cada uma entrando com opacidade, 4px de desfoque e 12px de translateY ao longo de 300ms com ease-out. Nunca espacie interações rotineiras. Veja enter-exit.md.
Saídas são mais curtas e menores que entradas
Saia com opacidade, 4px de desfoque e um translateY fixo de -12px ao longo de 150ms com ease-out, nunca a altura total do container. Deslize completamente para fora apenas onde o destino carrega significado, como um drawer fechando. Remova o elemento instantaneamente onde o movimento não adiciona informação. Veja enter-exit.md.
Pular animações de estado na primeira renderização
Defina initial={false} em um AnimatePresence que envolve uma troca de estado, para que o estado padrão não anime na montagem. Nunca defina isso em torno de uma entrada intencional, como um herói em palco. Veja animations.md.
Transicionar ícones contextuais com valores exatos
Onde um ícone é trocado em uma mudança de estado pouco frequente, como play para pausa ou copiar para copiado, faça uma transição cruzada. Escala vai de 0.25 para 1, opacidade de 0 para 1 e desfoque de 4px para 0px. Com uma biblioteca de animação, use { type: "spring", duration: 0.3, bounce: 0 }, e bounce é sempre 0. Sem uma, mantenha ambos os ícones no DOM e faça a transição cruzada ao longo de 300ms com cubic-bezier(0.2, 0, 0, 1).
A troca de ícone de uma aba e as ações que uma linha revela ao passar o mouse se enquadram em Interações de alta frequência respondem instantaneamente. Ambas as receitas estão em icon-transitions.md.
Suprimir transições na troca de tema
Desabilite todas as transições para a troca de tema, force uma limpeza de estilo e restaure as transições após o próximo frame. Caso contrário, todas as transições de cor disparam de uma vez e a troca borra. Veja a receita.
Transicionar apenas o que muda
Nomeie as propriedades exatas, como em transition-property: scale, opacity, e nunca all. Veja performance.md.
Nomear a propriedade animada no will-change
Adicione will-change somente após ver gagueira no primeiro frame, e nomeie a propriedade que você anima: scale para scale, transform para transform. Limite-a a propriedades de transformação, opacity e filter, e nunca use all. Veja performance.md.
Efeitos de hover apenas em ponteiros com capacidade de hover
Coloque estilos exclusivos de hover atrás de @media (hover: hover). No toque, :hover trava após um toque e parece um estado selecionado preso. O variant hover: do Tailwind 4 já compila sob essa consulta, e o do Tailwind 3 não. Onde um controle desenha seu próprio estado pressionado, defina -webkit-tap-highlight-color: transparent para que o flash cinza padrão não o duplique.
Conter scroll dentro de sobreposições
Dê a diálogos roláveis, drawers, menus e painéis laterais overscroll-behavior: contain, para que rolar além do final deles nunca role a página atrás.
Corresponder traço do ícone ao peso do texto
O traço renderizado de um ícone acompanha o peso do texto ao lado dele, de 1.5px em 400 a 2.5px em 700. Use uma biblioteca de ícones por superfície. A tabela, regras de dimensionamento e grade estão em icons.md.
Um SVG, recolorido por estado
Ícones usam currentColor e recebem estados hover, selecionado e desabilitado de cor e opacidade CSS, nunca de assets separados. Contorno é a variante padrão, e preenchimento marca o estado ativo. Sob dir="rtl", espelhe apenas ícones cujo significado segue a direção de leitura. Veja icons.md.
Antes de finalizar
| Detecção | Correção |
|---|---|
Pai e filho com o mesmo rounded-* ou border-radius com padding | Adicione o padding ao raio externo |
Anel box-shadow: 0 0 0 1px sem border ao lado | border: 1px solid transparent |
outline-slate-*, outline-zinc-* ou uma cor de contorno hex em img | outline-black/10 e dark:outline-white/10 |
transition-all ou transition: all | Nomeie as propriedades que mudam |
animation: definida em :hover, .open ou outra classe alternada | Uma transição nas mesmas propriedades |
active:scale-95, scale-90 ou whileTap abaixo de 0.96 | 0.96 |
Escala :active sem exclusão :disabled | enabled:active: ou :not(:disabled):active |
bounce: definido para qualquer coisa diferente de 0 | bounce: 0 |
opacity: 0 em uma regra base que apenas uma animation revela | Estado oculto no keyframe from, animation-fill-mode: both |
Animação translate, scale, filter ou motion.* sem proteção prefers-reduced-motion, motion-safe: ou MotionConfig | Bloqueie-a e faça transição cruzada de opacidade sob movimento reduzido |
Transições de cor mais um alternador de tema sem disableTransitionOnChange ou substituição | A receita de supressão na troca de tema |
will-change: all, ou will-change em um elemento que nunca anima | Nomeie a propriedade animada ou exclua-a |
fill="#..." ou stroke="#..." dentro de um SVG de ícone | currentColor |
:hover CSS puro ou hover: do Tailwind 3 fora de @media (hover: hover) | Envolva-o na consulta |
overflow: auto ou overflow-y-auto em um diálogo, drawer ou menu sem overscroll-behavior | overscroll-behavior: contain |
Relatório
Severidade. HIGH quebra uma interação, como uma alternância de keyframe que não pode reverter ou um estado de hover preso no toque. Dois gatilhos de escalada de better-interface caem aqui e são HIGH à vista. Um é movimento que ignora prefers-reduced-motion, e o outro é uma mudança de estado transportada apenas por movimento. MEDIUM é uma inconsistência visível em superfícies, ícones ou movimento. LOW é polimento isolado.
Verificação. Sem um navegador, leia cada estado que o componente define a partir do código, como hover, pressionado, selecionado, carregando e vazio, com suas durações e facilidades. Com um, percorra cada estado e reproduza o movimento a 10% da velocidade no painel de Animations do navegador. Relate cada verificação que você não pôde executar como Not verified.
Formato. Agrupe os achados sob o princípio que cada um viola, ordenados por severidade, uma linha por causa raiz listando cada localização em que aparece:
| Severity | Location | Before | After | Why |
|---|
Location é path/to/file:line. Why nomeia o princípio e o impacto no usuário.
Termine com Block quando qualquer HIGH permanecer, Approve caso contrário, deixando o restante na tabela como trabalho a fazer. Nunca Approve cobertura que você não inspecionou. Sem nada a relatar, declare "Nenhum achado acionável de polimento de UI" e relate a verificação.