Better Design

O que Better Design faz?

Torne a tarefa solicitada clara e acionável: o usuário pode ver onde está, entende uma ação antes de ativá-la, recebe um resultado e pode se recuperar de um erro. Avalie coerência, expressividade e acessibilidade separadamente. Não prometa UX perfeita.

1. Estabelecer escopo e base visual

• Escolha um modo: criação, melhoria focada, auditoria ou plano. Mantenha auditorias somente leitura; não implemente mudanças em um plano. Não adicione recursos que o usuário não solicitou.
• Estabeleça a plataforma a partir da solicitação e do projeto. Apenas quando o contexto estiver ausente, use web responsiva, HTML semântico e WCAG 2.2 AA como alvo inicial.
• Defina a matriz real de dispositivos e viewports antes de compor ou alterar uma superfície responsiva. Para um site, inclua layouts para mobile, tablet, desktop e ultrawide que o produto suporta; para um jogo mobile, inclua celulares pequenos e típicos, além de tablets. Restrições de design comportamento de layout devem se adaptar a essas superfícies em vez de meramente encolher uma composição de desktop. Para trabalho em navegador, inclua zoom do navegador na matriz porque 75%, 100% e 150% podem expor diferentes falhas de clipping, densidade, reflow e interação.
• Antes de qualquer trabalho de UI, procure o DESIGN.md do projeto (raiz, docs/, design/ ou o caminho nomeado nas instruções do agente) e leia-o completamente. Ele é a fonte única dos valores de interface: fontes, escala tipográfica, funções de cor, espaçamento, raios, tamanhos de componentes, ícones e movimento. Pegue cada valor em código novo ou alterado a partir dele por função ou nome de token; nunca "olhômetro", arredonde ou introduza um quase-duplicado. As regras estão em design-md.md.
• Inspecione a tela existente no tempo de execução atual ou através de capturas atuais confirmadas, inspecione componentes, tokens, estilos e regras do projeto próximos. A ausência de DESIGN.md não significa que não há sistema de design: os tokens de código são então o sistema. Preserve trabalho em andamento não relacionado.
• Distinga um defeito de implementação de uma solicitação de redesign. Aborde a causa primeiro: ordem pouco clara, uma ação imprevisível, feedback ruim, perda de dados ou conteúdo perdido.
• Tome decisões nesta ordem: tarefa explícita e restrições → DESIGN.md e o sistema existente → convenções da plataforma → tarefas do domínio → esta configuração de baseline da skill. Funcionalidade e requisitos de acessibilidade aplicáveis se aplicam em todos os níveis.
• Direção visual padrão. Quando o usuário não nomeia nenhum estilo visual e o projeto não tem DESIGN.md, marca, tokens de código ou UI ao vivo para herdar, construa no estilo padrão: ultra-mínimo premium no espírito da Apple (tela preta, Geologica quase branca nos pesos 500 e 340, dois cinzas, um azul para links e foco, ações em pílula, superfícies separadas por tom, conteúdo real como a única cor). As regras e o preset DESIGN.md pronto estão em house-style.md; leia-o inteiro antes de escrever qualquer estilo. Duas leituras equivocadas levam agentes para outro lugar, então verifique-as explicitamente (seção 1 do house-style.md): o domínio, indústria, público ou nome do produto não é uma dica visual ("uma torrefação", "para desenvolvedores"), e valores padrão não tocados de scaffolds não são um sistema para herdar (o tema padrão do shadcn/ui, a paleta padrão do Tailwind, create-next-app, Vite ou Expo starters, padrões Bootstrap, MUI ou Chakra); mapeie o estilo da casa sobre eles. Quando se aplicar, comece a partir do arquivo de referência house-style.html, não de uma página em branco: pegue seus tokens, classes de tipo, navegação, botões, tiles e ritmo de seção (ou porte-os para os componentes da pilha), depois substitua seu conteúdo (seção 1 do house-style.md). Qualquer dica visual do usuário (cores, clima, tema, referência, marca, estilo de público) a substitui: siga a solicitação e aplique apenas as partes do estilo da casa que a solicitação deixa em aberto e não contradiz. Nunca reestilize um produto existente para ele a menos que solicitado. Jogos mantêm sua própria direção de arte.
• Preserve a marca estabelecida, densidade, composição lúdica, editorial ou expressiva. Não os substitua por um CRM genérico cinza. Para um conflito real, escolha o menor ajuste acessível e explique o desvio específico.
• Esclareça apenas desconhecidos que alteram materialmente a decisão; declare suposições razoáveis brevemente. Esta skill não introduz uma nova aprovação ou porta HTML. Requisitos existentes do projeto para protótipos, aprovação e builds permanecem aplicáveis.

2. Definir a tarefa e um contrato proporcional

• Descreva o cenário primário em linguagem simples e seu resultado observável. Percorra entrada → ação → resultado → erro/retentativa → voltar/cancelar.
• Separe a tarefa primária, ações secundárias e ajuda. Escolha nomes e padrões familiares para o usuário; mantenha a navegação e localizações das ações consistentes entre telas.
• Uma correção única precisa apenas de um breve registro da decisão alterada e verificações. Para um novo fluxo, escreva um contrato compacto antes da implementação; é uma ferramenta de trabalho, não um documento obrigatório para o usuário.
• Use design-contract.md para estrutura, padrões numéricos e exceções. O exemplo JSON ilustra o formato; não o adicione integralmente ao projeto para uma pequena mudança.
• Limite o contrato à plataforma, objetivos, sistema existente, direção, componentes afetados, suas ações/estados, comportamento responsivo e evidência de aceitação. Uma verificação planejada não é uma verificação concluída.

3. Definir uma direção de arte antes de estilizar

Regras negativas apenas movem a saída para o próximo template mais comum; carácter vem de um processo. Ao criar ou redesenhar uma superfície cuja identidade faz parte da tarefa (marca, landing, portfólio, aplicativo de consumo, jogo, editorial, launcher), siga art-direction.md antes de escolher tokens. Quando o estilo da casa se aplicar (seção 1), paleta, tipo, forma e tokens de movimento vêm do seu preset; ainda escreva o conceito, e deixe-o escolher as imagens, o elemento principal de cada seção e um detalhe de assinatura (seção 10 do house-style.md). Caso contrário:

• Derive um conceito de uma frase do domínio, público e conteúdo do produto — um objeto, lugar ou ofício desse mundo — não de adjetivos como "moderno, limpo, minimalista". Adicione três qualidades alvo e três anti-qualidades concretas.
• Colete 3–5 referências reais (fornecidas pelo usuário primeiro; nunca imagens geradas por IA) e anote para cada exatamente o que é retirado: ritmo, densidade, apresentação numérica, material, luz.
• Esboce 2–3 direções que diferem pelo seu dispositivo principal (tipográfico, liderado por imagem, estrutural), então escolha uma com uma razão vinculada à tarefa e ao público.
• Derive paleta e tipo do conceito: uma paleta com uma origem declarada e neutros matizados; três candidatos a tipo e uma escolha fundamentada. Planeje um ou dois detalhes de assinatura; o pool opcional em effects-library.md contém os testados.
• Derive o carácter do movimento do mesmo conceito: como as coisas naquele mundo se movem (tempo, peso, física, se algo salta) mais um detalhe de movimento de assinatura. Paleta, tipo, e movimento devem ler como uma só voz; veja motion.md.
• Dentro do DESIGN.md, uma marca existente ou um sistema de design onde a direção é herdada: pegue-a do DESIGN.md ou declare-a em uma frase da superfície ao vivo e trabalhe dentro dela. Ferramentas densas de trabalho expressam carácter através de precisão e tipografia de dados; sem sistema e sem dica do usuário, elas pegam o estilo da casa escala de aplicativo e paleta com a densidade neutra de fallback.
• Registre a direção no contrato (direction, incluindo direction.motion) e planeje verificações de distinctiveness e motion. Escreva a direção escolhida e seus tokens em DESIGN.md para que telas e sessões posteriores construam a partir dos mesmos valores.

4. Construir um sistema coerente de decisões

• Reutilize tokens e componentes do DESIGN.md e dos tokens de código. Para um novo sistema, defina funções semânticas para cor, tipografia, espaçamento, raio, camadas e movimento; então selecione variantes de componente.
• Mantenha os conjuntos fechados para que cada tela seja construída a partir das mesmas partes: uma ou duas famílias de fontes, uma escala tipográfica escalonada de algumas funções, uma escala fixa de espaçamento, alguns raios e tamanhos fixos de componentes (por exemplo, botão sm/md/lg). Mesma função, mesmo valor em cada tela. Um valor ausente é uma decisão de sistema: adicione a função ao DESIGN.md e aos tokens de código na mesma alteração.
• Crie DESIGN.md a partir do template ao criar uma interface do zero (a partir do preset de estilo da casa quando o estilo da casa se aplicar), ou quando um redesign ou mudança de vários componentes não encontrar nenhum; derive-o dos tokens de código ao vivo em vez de inventar valores e registre contradições em vez de silenciosamente corrigi-las. Não o crie para uma correção de um único elemento a menos que solicitado; ofereça-o em uma linha. Mantenha DESIGN.md e tokens de código sincronizados em cada alteração que toque em qualquer um.
• A API expressa intenção, tamanho, densidade e estado. Preserve props nativas, participação em formulários, links e nomes acessíveis; não exija onClick em um botão de envio ou um link com href.
• Não ajuste cada elemento com seu próprio hex, gap, sombra e raio. Altere um token compartilhado ou variante quando a causa for compartilhada. Matemática de layout, uma borda de 1px, 0, fr, %, calc, aspect-ratio e valores de projeto permitidos não são violações por si só.
• Escolha o tamanho do texto por função e contêiner.
• Construa geometria; nunca a posicione "a olho". Siga layout-geometry.md para cada tela, painel e menu de jogo e meça o resultado (seção 8). Corrija um desalinhamento em sua causa (pivôs, âncoras, um grupo de layout ausente, padding de sprite, métricas de fonte), nunca empurrando um elemento:
  • Intervalos iguais. Irmãos de um tipo ficam em um contêiner de layout (flex/grid gap, grupos de layout Unity, contêineres de caixa Godot, caixas UMG) com um token de espaçamento, então cada gap entre eles é idêntico. Um gap diferente deve significar um novo grupo e um passo claro acima na escala. Escada de proximidade: dentro de um controle < entre itens < entre grupos ≤ padding.
  • Linhas compartilhadas. Itens em uma linha compartilham seu topo/centro/base (alturas mistas compartilham centros); itens em uma coluna e cada rótulo em uma lista de configurações começam em uma linha de chave vertical, com controles em uma segunda linha de chave. Use uma grade ou uma coluna de rótulo fixa, nunca deslocamentos por linha. Conjuntos de botões compartilham um tamanho.
  • Conteúdo dentro de controles pequenos é centralizado por sua tinta visível (altura da capitular, pixels de ícone cortados), não pela caixa de linha da fonte ou por um rect de sprite com padding; ícones assimétricos recebem um deslocamento óptico declarado embutido no componente. Pares de ícone + rótulo usam um token de gap.
  • Espaço de respiro. Nada transborda ou fica na borda do seu contêiner: padding é de pelo menos os gaps que contém, com reserva para a localização mais longa, escala de hover e anéis de foco; UI interativa permanece dentro da área segura em cada proporção de aspecto suportada. Quando o conteúdo não couber, mude o layout, não as margens.
• Selecione tipografia através de um processo, não de uma lista negra: liste três famílias derivadas do conceito (era, material, voz, densidade de dados), então escolha com uma razão declarada. A família deve ser legível em seus tamanhos e idiomas reais e fornecer os pesos, estilos, algarismos, cobertura de glifos (incluindo cirílico quando suportado) e comportamento de fallback necessários. Nenhuma família é proibida, mas uma família escolhida por hábito é um defeito: trocar um padrão de tendência (Inter, Uni Sans) pelo próximo (Space Grotesk, DM Sans, Instrument Serif) sem uma razão é o mesmo modelo. Tipo elegante nunca deve tornar a interface mais difícil de ler.
• Construa hierarquia através de dominância e contraste: um elemento principal por tela ou seção, uma escala tipográfica claramente escalonada (display 3–5× corpo em superfícies expressivas, passos menores em ferramentas densas), assimetria intencional onde serve o conceito e seções adjacentes que diferem em estrutura em vez de repetir um padrão de bloco.
• A proporção áurea pode informar proporções, hierarquia, corte ou espaço em branco quando melhora a composição, mas é uma ferramenta visual em vez de uma fórmula obrigatória. Prefira a tarefa real, conteúdo, restrições responsivas, legibilidade e sistema existente sempre que eles entrarem em conflito.
• Não torne uma tela primária uma parede de prosa ininterrupta quando seu conteúdo pode ser compreendido através de ações, agrupamento ou âncoras visuais. Divida explicações densas em seções escaneáveis e pareie-as, onde útil, com controles significativos, ícones, ilustrações, pré-visualizações, diagramas ou outras imagens relevantes para a tarefa. Um painel de controle ou área de conta, por exemplo, deve expor suas seções principais e próximas ações em vez de apenas descrever o que um usuário poderia configurar. Não adicione visuais decorativos que compitam com a compreensão ou criem falsas affordances.
• Use cor para significado e ênfase; não transmita estado apenas com cor. Pareie informação de erro/sucesso/obrigatório/selecionado com texto, um ícone, forma, padrão ou outra dica não cromática que permaneça visível em escala de cinza e para deficiências de visão de cores.
• Verifique contraste no par real de primeiro plano/fundo adjacente após opacidade, sobreposições, gradientes, imagens e cada tema necessário serem aplicados; não arredonde um resultado próximo ao limite. Atenda pelo menos 4.5:1 para texto normal e imagens significativas de texto, e 3:1 apenas para texto grande (pelo menos 24 CSS px regular ou 18.5 CSS px negrito). Mire mais alto para tipo fino, pequeno ou incomum.
• Garanta uma taxa de contraste mínima de 3:1 para informação visual necessária para identificar um controle ativo, seu foco ou estado e objetos gráficos significativos contra sua cor adjacente. Uma borda é necessária apenas quando é o que torna o controle identificável; quando usada para esse propósito, dela deve cumprir o mesmo requisito de 3:1.

5. Construir e verificar

• Implemente cada componente do contrato contra o sistema de design em vigor (DESIGN.md ou tokens de código existentes). Traduza cada decisão no contrato diretamente para código, componentes ou artefatos de tela, usando os tokens definidos sem desvio.
• Para cada estado e interação, verifique o resultado no tempo de execução real ou em uma captura de tela confirmada:
  • O layout está de acordo com as regras de geometria? Meça espaçamentos, alinhamentos e bordas com uma ferramenta de régua (inspetor do navegador, ferramenta de pauta de design), não apenas "parece bom". Se ocorrer desalinhamento, corrija a causa e verifique novamente.
  • Os estados estão completos? Estado vazio (sem dados), estados de erro, estado de carregamento (osciladores/esqueletos), confirmação de sucesso, feedback desfeito? Acessibilidade (tabulável, nomes de função, anúncios ao vivo, movimento reduzido, alvo de toque ≥48 px)?
  • Os caminhos de usuário são completos? Fluxo feliz, fluxo de erro, cancelar/sair, retornar, compatibilidade com formulários e navegador?
  • Vazamentos visuais: conteúdo que transborda seu contêiner em qualquer ponto de interrupção, texto que se sobrepõe, ícones que flutuam sem contexto, rolagem horizontal inesperada?
  • A direção de arte é coerente com o conceito? Algo contradiz a declaração de paleta, escolha de tipo ou carácter de movimento? A personalidade da superfície corresponde ao domínio e ao público-alvo?
  • O movimento é coerente (não apenas um flash de fade de opacidade de 300 ms padrão)? Os tempos, atenuações e física das transições correspondem ao carácter do movimento documentado? Existe um detalhe de movimento de assinatura?
• Documente quaisquer descobertas, desvios ou alterações no contrato. Se uma verificação falhar, corrija ou justifique por que o desvio é aceitável.
• Para um plano, produza fases ordenadas com critérios de aceitação e dívida técnica; para um design, produza o DESIGN.md atualizado e implemente a mudança ou, se solicitado como rascunho, um documento de design separado.
• Conclua com um resumo do que foi feito e por quê, ou liste as próximas ações para o plano, auditoria ou mudança adiada. Não conclua uma auditoria com mudanças.

6. Pós-condições

• DESIGN.md existe e está sincronizado com decisões de design e tokens de código.
• A tarefa específica está implementada ou documentada como um plano com próximas ações.
• Mudanças justificadas externamente ao DESIGN.md são explicadas por escrito.
• Verificações foram executadas.
• Contrato (se usado) está no lugar, preenchido ou resumido em uma nota.
• Nenhum recurso adicional não solicitado foi adicionado.
• O sistema existente foi preservado onde não foi instruído a mudar.

---

Esta skill depende de arquivos de referência para ser executada corretamente; certifique-se de que eles estejam presentes e acessíveis.

Veja também: design-md.md para a especificação DESIGN.md, layout-geometry.md para regras de layout, design-contract.md para o formato do contrato, art-direction.md para o processo de direção de arte, motion.md para a linguagem de movimento, house-style.md para o estilo padrão Apple e effects-library.md para efeitos de assinatura opcionais.