Communitygithub.com

Revisão Material Design 3

Revisa uma interface do usuário (capturas de tela, HTML/CSS/JS, páginas renderizadas) com base no Material Design 3 e retorna um relatório numerado e pronto para decisão, com evidências mensuradas ou estimadas. Apenas revisão.

O que é Revisão Material Design 3?

Esta skill capacita um agente de IA a realizar revisões de interface do usuário (UI) contra as diretrizes do Material Design 3 (M3). Ela analisa capturas de tela, código-fonte ou páginas renderizadas, gerando um relatório numerado e detalhado com descobertas classificadas, evidências (mensuradas ou estimadas) e propostas de mudança concretas. A skill é ideal para desenvolvedores e designers que precisam garantir a conformidade com M3 antes de um lançamento, decidindo quais desvios manter ou corrigir. Suporta plataformas como web, Android, Flutter e iOS, com um fluxo de trabalho que prioriza medição sobre estimativa, usa um protocolo de adaptador para incorporar diretrizes de projeto e decisões registradas, e classifica as descobertas por camadas de prioridade (F: acessibilidade obrigatória, C: núcleo M3, E: expressivo/opcional). O agente não altera código durante a revisão, apenas após as decisões do usuário, garantindo um processo de revisão focado e controlado.

Funciona com~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/sbk-jdm/m3-skills/tree/HEAD/skills/m3-design-review

Perguntar na sua IA favorita

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

Documentação

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.

  1. 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.
  2. Diretrizes do projeto e decisões registradas, encontradas através do protocolo do adaptador (references/adapter-protocol.md).
  3. 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.
  4. 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:

  1. Página renderizada disponível (Playwright, uma ferramenta de automação de navegador, DevTools): avalie scripts/measure.js na 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.
  2. 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.
  3. Apenas imagens disponíveis: estime, rotule como estimated e 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 expectWidth com a largura CSS que você pretendia testar.
  • Se warnings contiver viewport-meta-missing ou viewport-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émCarregar
Qualquer superfície (sempre)references/layout-interaction-a11y.md, seções "Piso de acessibilidade" e "Regras entre componentes" primeiro
Cores, temas, modo escuro, tokens, contrastereferences/color.md
Tipografia, cantos, elevação, espaçamento, movimento, íconesreferences/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, divisorreferences/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çãoreferences/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 ferramentasreferences/components-3.md
Recursos expressivos, movimento elástico, morfologia de forma, ou o usuário pergunta sobre Expressivoreferences/expressive.md
Escrever o relatórioreferences/report-template.md
Registrar decisões, convenções, lista de alteraçõesreferences/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:

  1. Classifique o controle por sua função primeiro (CMP-01), depois encontre a regra. Cite seu ID e sua Fonte exatamente 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").
  2. 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 ou WCAG 2.2 SC x.y.z como sua fonte (casos típicos: atributo lang ausente, uma meta tag de viewport que desabilita o zoom). Caso contrário, deixe-o de fora.
  3. Verifique o livro-razão: um desvio registrado não é relatado novamente (mencione a contagem de itens suprimidos em uma linha).
  4. 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).
  5. 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.
  6. 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"):

  1. Para cada desvio em 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 de references/adapter-protocol.md. Uma constatação de nível F não pode ser um desvio: registre-a como risco aceito e 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.
  2. 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".
  3. Para cada constatação rejeitada com uma justificativa curta: adicione uma entrada com status rejeitado e o motivo.
  4. 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.
  5. 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.
  6. 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.

Individual skills in this repo

This repo contains 1 individual skill — each has its own dedicated page.

Habilidades Relacionadas