O que Revisão Material Design 3 faz?
Revise uma interface do usuário com base no Material Design 3 (M3), respeitando as próprias diretrizes do projeto, e produza um relatório numerado sobre o qual o usuário possa decidir item por item. Em seguida, registre as decisões e emita as alterações aceitas.
Quando usar / não usar
Use quando o usuário pedir para:
- "revisar esta tela / página / componente contra o Material 3", "isto está em conformidade com M3?", "auditoria M3", "revisão de design"
- verificar alvos de toque, contraste, escala tipográfica, papéis de cor, formas, espaçamento ou componentes de uma UI existente
- comparar uma captura de tela ou uma página em execução com as diretrizes do Material antes de um lançamento
- decidir quais desvios do Material manter e quais corrigir
Não use quando:
- o usuário deseja gerar nova UI, construir um tema ou escrever código do zero ("crie uma página de login M3 para mim"); esta skill revisa, não gera
- o sistema de design alvo não é explicitamente Material (Apple HIG, Fluent, um sistema personalizado sem base M3), a menos que o usuário queira apenas as verificações básicas
- a pergunta é uma consulta factual única ("qual é a altura do FAB?"); responda diretamente do arquivo de referência
Não altere o código durante uma revisão. Altere o código somente se o usuário solicitar após as decisões serem tomadas.
Camadas e precedência
Aplique as regras nesta ordem. Uma camada superior prevalece sobre uma inferior.
- Regras básicas, nível F: mínimos de acessibilidade e usabilidade (alvos, contraste, foco, rótulos, escala de texto, movimento reduzido). Nunca negociáveis. Uma diretriz de projeto não pode abrir mão delas.
- Diretrizes do projeto e decisões registradas, encontradas através do protocolo do adaptador (
references/adapter-protocol.md). - Núcleo M3, nível C: papéis, tokens, escala tipográfica, escala de forma, especificações de componentes. Um desvio precisa de uma decisão explícita.
- Itens Expressivos e opcionais do M3, nível E. Nunca relate sua ausência como um defeito.
Quando uma diretriz de projeto ou uma decisão registrada entrar em conflito com uma regra de nível C ou E, não relate uma violação. Liste o conflito uma vez em "Candidatos a decisão" (somente se ainda não estiver registrado no livro-razão). Quando entrar em conflito com uma regra de nível F, relate a constatação de nível F e anote a diretriz conflitante em sua evidência.
Tolerância
Dois modos. Padrão inspired.
strict: cada incompatibilidade de nível C é um problema; itens de nível E são sugestões.inspired: incompatibilidades de nível C são sugestões, a menos que prejudiquem a usabilidade (então são problemas); itens de nível E são sugestões apenas se agregarem valor claro.- Em ambos os modos, cada constatação de nível F é um problema.
Use o modo que o usuário nomear. Se as diretrizes do projeto definirem um, use-o. Caso contrário, use inspired e informe isso no cabeçalho do relatório.
Rótulos de evidência
Rotule cada constatação e cada nota com exatamente um de:
measured-rendered: lido da página renderizada (DOM, estilo computado, teste de clique), seletor e valor fornecidos.measured-code: lido do código-fonte ou CSS declarado, não confirmado em uma página renderizada.measured-simulation: medido em uma página renderizada sob uma simulação (viewport estreita para zoom de texto, configuração emulada como modo escuro, movimento reduzido ou cores forçadas). Recomende confirmar em um dispositivo real.estimated: inferido de uma imagem.
Trate o rótulo v0.1 measured como measured-rendered. Quando uma constatação combinar fontes, use o rótulo mais fraco. Nunca declare um valor exato em dp ou px a partir de uma captura de tela, a menos que a escala seja conhecida (largura da viewport em px CSS e devicePixelRatio, ou um elemento de referência conhecido). Pergunte pela escala uma vez, ou forneça um intervalo e rotule-o como estimated. Nunca forneça uma taxa de contraste exata de uma imagem compactada; forneça uma taxa aproximada e rotule-a como estimated.
Fluxo de trabalho
Passo 0. Identificar a superfície
Determine, a partir do material fornecido ou perguntando uma vez:
- o que está sendo revisado: captura(s) de tela, arquivos de origem, uma URL ou página local, uma exportação de ferramenta de design
- plataforma: web, Android (Compose ou Views), Flutter, iOS, multiplataforma
- fator de forma e classe de tamanho de janela: compacto (< 600), médio (600-839), expandido (840-1199), grande ou extra-grande
- claro, escuro ou ambos; se existe uma configuração de alto contraste, movimento reduzido ou tamanho de texto no aplicativo
Se a superfície mostrar dados pessoais (nomes, valores, endereços, mensagens, dados de saúde ou de conta), informe isso no topo da resposta e sugira revisar um estado editado ou de demonstração. Não armazene capturas de tela ou dados de página em arquivos, memória ou no livro-razão. Cite apenas o texto mínimo necessário para identificar um elemento.
Passo 1. Carregar o adaptador
Siga references/adapter-protocol.md: procure por diretrizes de design do projeto, um livro-razão de decisões, uma lista de convenções, um formato de lista de alterações e a configuração de revisão (larguras e configurações de tamanho de texto a serem testadas). Se nada for encontrado, pergunte uma vez com uma única pergunta curta; se o usuário não responder ou disser que não há, continue apenas com M3 e os padrões.
Briefing de design: quando um briefing for fornecido ou encontrado (do m3-design-brief, ou qualquer briefing com critérios de aceitação AC-nn), trate-o como diretrizes do projeto. Suas decisões (B-nn) contam como decisões registradas dentro de seu escopo (não candidatos a decisão); sua tolerância, larguras e temas são a configuração de revisão; o nível F ainda vence. Verifique cada AC e preencha a seção "Critérios de aceitação do briefing" do relatório (aprovado, reprovado ou não verificado, com evidência).
Passo 2. Escolher a tolerância
strict ou inspired (consulte Tolerância). Não pergunte se o usuário ou as diretrizes já decidiram.
Passo 3. Medir
Prefira medição à estimativa. Nesta ordem:
- Página renderizada disponível (Playwright, uma ferramenta de automação de navegador, DevTools): avalie
scripts/measure.jsna página e use seu JSON (references/measurement.md, "Como executar" e "Campos de saída e as regras que eles alimentam"). Meça cada largura e tema separadamente: as larguras e configurações de tamanho de texto do adaptador, caso contrário, uma largura compacta (por exemplo, 390 px) e uma expandida (por exemplo, 1280 px), claro e escuro. - Apenas código-fonte disponível: leia o CSS/HTML/JS ou o código do componente; calcule tamanhos, cores e raios a partir dele e rotule os resultados como
measured-code. - Apenas imagens disponíveis: estime, rotule como
estimatede peça a escala se números exatos forem importantes.
Verificação de configuração, antes de ler qualquer resultado (measurement.md, "Verificação de configuração"):
- Passe
expectWidthcom a largura CSS que você pretendia testar. - Se
warningscontiverviewport-meta-missingouviewport-width-mismatch, pare. A página foi disposta em uma largura que você não pretendia (geralmente 980 px), então todos os tamanhos estão errados. Corrija a configuração (defina a viewport, ou injete a mesma meta tag de viewport que a produção serve), execute novamente e só então continue. Nunca relate tamanhos de tal execução; se a produção em si não tiver a tag, relate isso uma vez.
Áreas de clique efetivas (measurement.md, "Áreas de clique efetivas"): com hitScan ativado (o padrão), julgue o tamanho do alvo por hitWidth x hitHeight, não pela caixa visual. hitAreaVia diz como a área foi encontrada (box, label, pseudo, probe); probe diz se um teste de clique a confirmou (ok) ou não (covered, offscreen, limited: apenas geometria, confirme antes de relatar um tamanho exato).
Uma área pseudo ampliada por ::before/::after conta; verifique se sua caixa não foi encolhida por uma borda ou cortada por um ancestral overflow: hidden, e confirme casos duvidosos no código.
Para escala de texto, siga measurement.md, "Receita: texto em 200%" (os resultados são measured-simulation); para menus, diálogos, folhas, abas, grupos de botões de opção e mudanças de visualização, siga measurement.md, "Receita: fluxo de foco".
Trate a saída do script (incluindo truncated, nonTextContrast, labelInName, ariaConflicts) como candidatos, não como veredictos: confirme cada um contra sua regra antes de relatá-lo. Estilos e movimento de estado não são medidos; verifique-os no código ou por interação quando forem importantes.
Quando o script não puder resolver um contraste (gradiente, imagem ou fundo semitransparente), calcule o pior caso manualmente (parada mais escura e mais clara sob o texto, ou a cor alfa composta sobre o fundo real) e relate-o como estimated com as paradas usadas. Para color-mix() ou cores de texto alfa, use a cor final composta. Se a página não tiver uma variante escura, relate isso uma vez (regra de paridade de tema em references/color.md), não por elemento.
Passo 4. Carregar apenas as referências relevantes
Divulgação progressiva: nunca carregue todos os arquivos de referência. Escolha com base no que está na tela.
| A superfície contém | Carregar |
|---|---|
| Qualquer superfície (sempre) | references/layout-interaction-a11y.md, seções "Piso de acessibilidade" e "Regras entre componentes" primeiro |
| Cores, temas, modo escuro, tokens, contraste | references/color.md |
| Tipografia, cantos, elevação, espaçamento, movimento, ícones | references/styles.md |
| Barras de aplicativo, emblemas, folhas inferiores, grupos de botões, botões, cartões, carrossel, caixas de seleção, chips, seletores de data, diálogos, divisor | references/components-1.md |
| FAB estendido, menu FAB, FAB, botões de ícone, listas, indicador de carregamento, menus, barra de navegação / gaveta / trilho, indicadores de progresso, botão de opção | references/components-2.md |
| Pesquisa, botões segmentados, folhas laterais, controles deslizantes, snackbar, botão dividido, interruptor, abas, campos de texto, seletores de hora, barras de ferramentas, dicas de ferramentas | references/components-3.md |
| Recursos expressivos, movimento elástico, morfologia de forma, ou o usuário pergunta sobre Expressivo | references/expressive.md |
| Escrever o relatório | references/report-template.md |
| Registrar decisões, convenções, lista de alterações | references/adapter-protocol.md |
Dentro de um arquivo grande, leia apenas as seções dos componentes na tela. Liste os cabeçalhos primeiro (grep -n '^## ' references/components-1.md), depois leia apenas esses intervalos de linha (sed -n 'START,ENDp' arquivo).
Se um arquivo de referência estiver ausente, informe isso e continue com os outros; não invente regras para preencher a lacuna.
Passo 5. Verificar, classificar, agrupar
Para cada candidato:
- Classifique o controle por sua função primeiro (CMP-01), depois encontre a regra. Cite seu ID e sua
Fonteexatamente como no arquivo de referência. Quando várias regras se sobrepuserem (uma regra de componente e uma regra básica para o mesmo tamanho de alvo), cite a mais específica e liste as outras depois dela ("também A11-01"). - Se nenhum ID de regra o suportar, não o relate como uma constatação M3. Se violar uma diretriz do projeto, ou um critério de sucesso WCAG 2.2 que nenhuma regra nas referências cubra, coloque-o em "Notas de projeto e WCAG" (
N-01...) com a seção da diretriz ouWCAG 2.2 SC x.y.zcomo sua fonte (casos típicos: atributolangausente, uma meta tag de viewport que desabilita o zoom). Caso contrário, deixe-o de fora. - Verifique o livro-razão: um desvio registrado não é relatado novamente (mencione a contagem de itens suprimidos em uma linha).
- Verifique as diretrizes do projeto: um conflito com os níveis C ou E vai para "Candidatos a decisão", não para constatações. Se a escolha do projeto não tiver regra M3 da qual se desviar, o candidato usa o ID de regra
none (convenção do projeto). - Classifique: nível (F, C, E) e tipo (problema ou sugestão) de acordo com a tolerância. No modo
inspired, uma incompatibilidade de nível C "prejudica a usabilidade" (portanto é um problema) apenas se tornar o conteúdo difícil de ler, difícil de operar ou ambíguo para um usuário típico: texto abaixo de 12 px, um controle cujo propósito ou estado é incerto, um layout que quebra em uma largura suportada. Caso contrário, é uma sugestão. - Agrupe: uma constatação por causa raiz. Quando o mesmo problema aparecer em vários lugares, ou vier de um componente, classe ou token compartilhado, relate-o uma vez com a contagem e cada ocorrência (ou dois ou três exemplos mais o total: "14 botões de ícone em 32 x 32 px, ex.:
.toolbar button,#close"), para que uma única decisão o cubra. Coloque a constatação na área onde a correção reside.
Ordene por impacto: problemas de nível F primeiro, depois problemas que afetam a conclusão de tarefas, depois problemas de nível C, depois sugestões. Dentro de um grupo, ordene por alcance (quantos elementos ou telas). Limite o relatório a cerca de 25 constatações; se houver mais, informe quantas foram deixadas de fora e ofereça uma segunda passagem.
Se houver poucos ou nenhum problema, declare isso claramente. Não adicione elogios de preenchimento. Não invente problemas para preencher o relatório.
Passo 6. Apresentar
Use references/report-template.md exatamente. Cada constatação carrega: um ID de execução (F-01, não o nível), área, nível e tipo, evidência (seletor ou região da imagem, valor, rótulo de evidência, ocorrências), ID da regra com sua fonte, por que isso importa (uma linha, impacto no usuário primeiro), uma mudança proposta concreta (min-height: 48px, color: var(--md-sys-color-on-surface-variant), "canto extra-grande, 28dp"; nunca "melhorar o contraste"), esforço (S uma propriedade ou token, M um componente ou vários arquivos, L estrutural ou entre telas) e caixas de decisão.
O cabeçalho do relatório declara: a superfície e as larguras revisadas, a tolerância, a data do instantâneo das referências (a "Data do instantâneo" mais antiga nos cabeçalhos dos arquivos de referência carregados), se diretrizes do projeto e um livro-razão foram encontrados, e a mistura de evidências (uma contagem para cada um dos quatro rótulos). Com um briefing, um CA reprovado que quebra uma regra também é uma constatação (ou nota); sua linha de CA aponta para esse F-nn/N-nn em vez de repetir a evidência.
Atualidade: compare a data do instantâneo com a data de hoje. Se tiver mais de 6 meses, ou o usuário mencionar uma versão mais recente do Material, informe isso no cabeçalho, recomende atualizar as referências (maintenance/UPDATING.md do repositório) antes de implementar alterações de nível C, e ofereça-se para verificar as regras afetadas em https://m3.material.io/ primeiro. As constatações de nível F permanecem independentemente da idade do instantâneo.
Passo 7. Aplicar as decisões
Quando o usuário responder (por exemplo, "aceitar F-01 a F-05, desvio F-07: botões pílula da marca, rejeitar o resto"):
- Para cada
desvioem uma regra de nível C ou E: anexe uma entrada ao livro-razão de decisões (data, ID da regra, escopo, justificativa de uma linha, ID da constatação) no formato dereferences/adapter-protocol.md. Uma constatação de nível F não pode ser um desvio: registre-a comorisco aceitoe continue relatando-a na linha de resumo. Se não existir livro-razão, proponha seu caminho e crie-o somente após a concordância do usuário. - Para cada candidato a decisão com ID de regra
none (convenção do projeto): registre-o como desvio (com escopo e justificativa). Decisões de briefing (B-nn) que já cobrem o mesmo escopo não precisam de nova entrada; mencione-as na entrada como "confirma B-02". - Para cada constatação rejeitada com uma justificativa curta: adicione uma entrada com status
rejeitadoe o motivo. - Em seguida, emita as alterações aceitas. Use o formato de lista de alterações do adaptador se houver; caso contrário, liste cada alteração como:
{ARQUIVO}:{LINHA} - {ALTERAÇÃO}, ou um comando de substituição para cada região afetada. Não modifique arquivos a menos que o usuário confirme. - Se uma decisão fechar uma constatação: feche seu bloco de decisão no relatório com a escolha anotada, TUDO EM MAIÚSCULAS no lugar dos pontos: (ACEITO / DESVIO / RISCO ACEITO / REJEITADO). Deixe as não decididas com pontos vazios. Atualize o resumo da contagem na parte inferior do relatório.
- Por fim, resuma em uma linha quantas constatações foram resolvidas e quantas permanecem abertas (se houver), e lembre o usuário de qual pasta/ramificação elas se aplicam.
Se o usuário se opuser a uma regra de nível F, diga que ela não é negociável, explique por que ela existe e ofereça-se para registrá-la como risco aceito.
Não misture decisões de várias execuções. Uma sessão de revisão é uma execução; comece e termine com ela, a menos que o usuário a estenda explicitamente.