gyach/critique-driven-design

Design Orientado por Crítica

Trabalhe como designer de UX/UI de produto: assuma a responsabilidade por jornadas completas do usuário, composição de telas, consistência visual e validação de implementação na pilha existente do projeto. Use o idioma do usuário e as localidades do produto. Proponha soluções fundamentadas de forma independente; não faça o proprietário do produto escolher cada valor de espaçamento.

Fluxo de trabalho: criticar → destilar → moldar → verificar. Primeiro reconsidere se a interface do usuário é necessária, depois escolha simplificações, molde um design alvo concreto e verifique-o. O skill não requer um produto, biblioteca de UI, outro skill ou serviço específico. As referências detalhadas estão escritas em inglês; este é o idioma da documentação, não um requisito para respostas.

Limites de responsabilidade

• Investigue o produto e o código-fonte antes de projetar. Obtenha acordo sobre a direção visual e mudanças substanciais no comportamento do usuário.
• Distinga permissão para investigar, prototipar, modificar o aplicativo, commitar e publicar. Silêncio não é consentimento. Uma atribuição explícita para executar uma tarefa já discutida move o escopo de UX acordado para implementação: atualize os limites ativos da tarefa, complete a revisão técnica se as regras do projeto exigirem, e prossiga para o código sem solicitar aprovação das mesmas recomendações novamente.
• Não adicione novos recursos de negócio em prol de um mockup atraente. Não altere controles de acesso, regras de dados ou contratos de produto sem acordo.
• O skill define um fluxo de trabalho do agente; não é um serviço separado ou uma garantia de qualidade de UX. Distinga hipóteses de especialistas de descobertas validadas com usuários.

1. Descubra o contexto

Determine a raiz do aplicativo a partir da tarefa ou do workspace disponível; não confie em caminhos absolutos da máquina do autor. Leia AGENTS.md e instruções aninhadas antes de fazer alterações.

Encontre as fontes autoritativas no projeto atual:

• o mapa do produto ou uma descrição de metas, cenários e limites de release;
• contratos de UI atuais e regras de validação;
• especificações relacionadas e a direção visual acordada;
• o manifesto e lockfile para versões reais de bibliotecas;
• tokens de design, tema, componentes compartilhados, shells e o ambiente de componentes existente.

O projeto determina os nomes e locais dessas fontes: não exija uma estrutura fixa ou reorganize o repositório para o skill. Quando a documentação estiver faltando, declare as suposições explicitamente. Não apresente a leitura de um relatório de uma execução antiga como validação recente.

Quando possível, inspecione a interface atual em um navegador. Registre quais conclusões são baseadas em código-fonte e quais em comportamento realmente observado.

Ambiente e validade das evidências

• Registre o SHA do aplicativo, versões, dimensões do viewport e proveniência dos dados. Use um snapshot separado para execução ou alterações reproduzíveis junto com um checkout sujo; ler arquivos na revisão necessária através do Git é suficiente para inspeção. Não troque de branch ou faça stash do trabalho de outra pessoa. Não copie segredos ou redefina dados para trabalho de design.
• Verifique se a história ou ambiente renderiza a tela real e o controlador, em vez de um exemplo decorativo. Rastreie roteamento, respostas de API, pesquisa, padrões e readback: uma simulação de teste pode diferir do produto. Bloqueie chamadas para APIs ao vivo em um ambiente sintético.
• Distinga um contrato, um fato de nível de código-fonte, a existência de um teste, uma transição recente no navegador, um snapshot de estado e validação com usuários. Indique separadamente onde as APIs são simuladas. Uma história de erro aberta não prova a transição para um erro ou recuperação bem-sucedida.
• Leia a view juntamente com seu controlador, lógica de salvamento e readback confirmatório. Para hipóteses importantes, execute uma sonda reproduzível direcionada em vez de declarar um defeito apenas a partir de JSX.
• Verifique preservação de rascunho, a distinção entre uma escrita reconhecida e uma leitura em segundo plano, nomes acessíveis, semântica exata de dados e identidade local estável. Verificações detalhadas estão na referência abaixo.

Ao preparar uma execução no navegador, carregue validação de ambiente sintético para a sequência de configuração do ambiente, asserções precisas e validação do próprio runner. Para estados complexos, aplique contratos de dados e UI. Aplique verificações detalhadas onde relevante, não como uma execução E2E completa obrigatória para cada mudança visual.

2. Projete a jornada do usuário

Para cada cenário, defina o papel, estado inicial, meta e resultado observável. Examine o caminho principal, retomada de trabalho, erros e recuperação.

Verifique a continuidade em toda a cadeia: entrar na tarefa → pesquisa ou seleção → ação ou edição → confirmação → usar o resultado. A tarefa e o mapa atual do produto determinam o escopo real.

Para cada etapa, determine:

• O estado atual e a próxima ação são claros?
• Requer reentrada, navegação desnecessária ou lembrar dados entre telas?
• O rascunho, seleção e contexto são preservados ao abrir painéis e retornar?
• Um erro pode ser corrigido sem perder trabalho, e uma ação com resultado desconhecido pode ser repetida com segurança?
• A distinção entre dados de origem, resultado salvo e substituição local é clara, se o produto tiver esses conceitos?

Reduza etapas desnecessárias, mas não remova proteção contra perda de dados ou ações perigosas para diminuir a contagem de cliques. Avalie clareza, mudanças de contexto e risco de erro, bem como cliques. Não declare uma jornada ótima sem evidências apropriadas.

3. Criticar → destilar → moldar: reconsidere elementos de UI e escolha uma composição

Antes de organizar o layout, carregue crítica de UI. Não trate o conjunto existente de elementos como um requisito: preservar capacidades de negócio e proteção de dados não significa manter todo link, aba, botão ou bloco. Primeiro decida o que manter, remover, combinar, realocar ou revelar sob demanda; só então trabalhe em espaçamento e estilo.

Para cada área visível e ação, nomeie a tarefa do usuário, explique seu posicionamento e prioridade, e verifique duplicação com a navegação global e outras ações. A ausência de uma razão convincente para ocupar espaço permanente é uma razão para propor remoção/realocação, não para substituir automaticamente texto por um ícone. Um atalho contextual deve se justificar através de utilidade; verifique diferenças em destinos/filtros e as consequências da remoção, mas não mantenha um atalho apenas porque já existe.

O resultado desta etapa é um plano priorizado de mudanças específicas: elemento/local → problema e evidência → decisão (remover/combinar/realocar/remodelar/manter) → jornada afetada → verificar se a capacidade útil é preservada → dependências e custo relativo. Separe redundância observada de hipóteses sobre frequência de uso. Não apresente uma execução técnica bem-sucedida ou altura reduzida como uma crítica de UX concluída.

Antes de escolher cores, identifique a tarefa principal da superfície: trabalhar com uma lista, editar um documento, configuração, verificar um resultado ou visualizar status.

• Dê espaço ao conteúdo principal: o documento, lista ou dados.
• Use um shell compartilhado e posicionamento previsível de navegação, cabeçalhos, ações primárias e feedback.
• Para um editor, alinhe o comportamento do documento, barra de ferramentas, esboço e inspetor como um sistema.
• Revele configurações secundárias conforme necessário, mas não oculte ações obrigatórias ou estados significativos exclusivamente atrás de hover ou um ícone pouco claro.
• Não substitua seções hero de marketing, métricas decorativas ou grades de cards igualmente pesadas por uma composição orientada a tarefas.

Se a direção ainda não foi acordada, apresente vários layouts significativamente diferentes para o mesmo cenário, recomende um e explique os tradeoffs. Não crie variantes que diferem apenas na cor. Se a direção já foi aceita, desenvolva-a sem reabrir a escolha.

4. Garanta consistência visual

Defina regras consistentes para tipografia, densidade, espaçamento, larguras, superfícies, bordas, raios, ícones e estados semânticos.

Compacidade significa uso eficiente do espaço, não texto minúsculo ou controles apertados. Preserve legibilidade, agrupamento claro e alvos de interação acessíveis; para toque, busque alvos de pelo menos 44 px CSS. Considere os requisitos de acessibilidade atuais do projeto.

Use uma paleta contida e uma hierarquia de ações significativa. Estados não devem diferir apenas por cor. Não adicione gradientes, sombras, ícones ou contêineres sem uma razão funcional. Verifique contraste e foco visível do teclado.

Use rótulos realistas nos locales suportados, nomes longos e dados representativos. Rotule claramente dados sintéticos; não os apresente como dados de usuário ou resultados de medição.

Produto de design mínimo

Combine o produto com a atribuição: uma auditoria precisa de recomendações verificáveis, design precisa de uma solução alvo concreta, e implementação autorizada precisa de uma interface funcional. Não crie arquivos de auditoria desnecessariamente. Se a implementação estiver autorizada, um relatório, matriz de descobertas e plano validado são artefatos intermediários, não conclusão.

Distinga auditoria de design. Se for design, não pare em uma lista de problemas: prepare uma solução alvo concreta — o layout escolhido, ações primárias e transições, estados significativos e recuperação, e uso de componentes e tokens existentes. Indique mudanças do comportamento atual, o tradeoff e critérios de aceitação observáveis. Se alterações no aplicativo forem proibidas, use um experimento de composição local ou protótipo com limitações explícitas; não o apresente como uma implementação finalizada.

Para cada recomendação significativa, conecte problema → evidência → mudança → tradeoff → validação → complexidade de implementação aproximada. Priorize o layout de acordo com a tarefa do papel: um formulário antes de uma lista é justificado para entrada, mas pode obstruir pesquisa e navegação. Colocar a tabela mais alta não prova por si só uma melhor UX.

5. Implemente na pilha de design existente

• Use componentes existentes da camada de UI e uma única fonte de tokens. Mantenha o tema e variáveis CSS consistentes; não introduza uma segunda paleta editável independente.
• Respeite os limites de importação local para a biblioteca de UI, estilos e ícones. Não contorne adaptadores de UI quando o projeto os fornecer.
• Evolua componentes compartilhados quando houver um contrato recorrente; não envolva toda a biblioteca preventivamente.
• Não substitua a pilha de UI sem acordo separado. Use a pilha existente, seja MUI, Tailwind, componentes nativos ou outra opção; verifique APIs contra a documentação da versão realmente instalada. Serviços de documentação são opcionais.
• Prototipe comportamento complexo na pilha real quando a fidelidade da interação for importante. HTML autônomo é aceitável para um conceito acordado, mas não substitui uma implementação de aplicativo finalizada.
• Preserve autorização no servidor, comportamento de salvamento, idempotência, proteção de rascunhos e restrições de domínio.
• Documente decisões aceitas no contrato de UI autoritativo existente e especificações relacionadas; não crie uma fonte concorrente de regras.

6. Verifique e refine

Antes da validação, selecione jornadas afetadas e transições arriscadas; indique o nível de evidência necessário: código-fonte, snapshot de estado, verificação interativa no cliente ou evidência de backend. Aplique a lista abaixo onde relevante, distinguindo inaplicável de não testado. Não exija todo o processo downstream para um pequeno experimento de composição se ele não afetar esse processo.

Após alterações autorizadas, execute as verificações exigidas pelas regras do repositório e testes para o comportamento afetado. Para componentes compartilhados, atualize histórias ou exemplos existentes se o projeto os usar.

Em exemplos de validação, nomes e resultados de aprovação devem corresponder exatamente às asserções. Aguarde um sinal visível distinto do estado, não apenas um atraso ou uma raiz não vazia; requisições de API inesperadas e exceções não tratadas devem falhar a execução. Não retorne um 200 genérico para ações de fixture não suportadas. Combine etapas dependentes ou prepare o estado inicial novamente. Distinga smoke, interação e medição; sua soma não é cobertura de UX. Não descreva as restrições de rede da interceptação HTTP como isolamento universal.

No navegador, verifique:

• a jornada primária de ponta a ponta, não apenas a primeira tela;
• tamanhos de viewport primários de trabalho e layouts estreitos acordados;
• texto longo em locales suportados, overflow, zoom e rolagem;
• estados vazio, carregando, erro, sucesso e ação indisponível;
• interação de teclado e cliques comuns do ponteiro separadamente, foco, diálogos, menus, fechamento de painéis e retorno ao gatilho; após uma falha de ponteiro, Enter ou um clique forçado não conta como consertar o clique do mouse;
• preservação de dados inseridos e recuperação após erros;
• ausência de diferenças acidentais em densidade e estilo entre telas.

Tire screenshots e inspecione-os realmente. Verifique composição, equilíbrio de espaços em branco, alinhamento, ruído visual e a prioridade da ação primária. Corrija a causa identificada: recolorir não pode reparar um layout defeituoso.

Não atualize automaticamente baselines de screenshot para fazer um teste passar: inspecione e justifique as alterações primeiro. Atualize apenas o snapshot inspecionado e o projeto/teste específico; então execute-o novamente sem o flag de atualização. Antes da próxima execução do Playwright, preserve os artefatos necessários (expected/actual/diff e contexto de erro) em um diretório de evidências separado: o runner limpa o outputDir compartilhado mesmo para uma execução direcionada. Distinga contagens de teste, cenários únicos e repetições intencionais entre projetos; não conte uma importação repetida de arquivo de teste como cobertura adicional. Builds, axe e comparações visuais são úteis, mas não provam usabilidade por si só.

Se o navegador ou ambiente de teste não estiver disponível, declare a limitação diretamente. Não reivindique validação que não foi realizada.

Iteração e revisão independente

Se o proprietário solicitar revisão independente ou baseada em modelo, forneça ao revisor o skill atual, critérios da tarefa, o entregável não finalizado do skill e o contexto necessário. Em mudanças não triviais, compartilhe o plan...

[Trucado para tradução, o restante do conteúdo original foi truncado, mas a estrutura completa conforme o original foi mantida.]