B-Riemer/claude-skills

Apple Design Pro (web)

Dois modos para sites: Revisão (encontrar o que está errado, classificar, dizer como corrigir) e Construção (acertar o movimento e a interação enquanto escreve código). O nível é de qualidade Apple: resposta instantânea, feedback contínuo, moderação e detalhes que são consistentes em vez de decorativos.

Escopo: sites e aplicações web. As Diretrizes de Interface Humana da Apple são escritas para apps nativos; use-as para raciocinar e traduza para a web; não copie padrões iOS literalmente.

Escolha o modo

• O usuário compartilha uma URL, repositório, arquivo, captura de tela ou diz "revisar / auditar / verificar / o que está errado / fazer parecer melhor": Modo Revisão.
• O usuário está construindo ou alterando algo ("adicionar uma folha inferior", "fazer isso parecer nativo", "animar este menu"): Modo Construção.
• Não claro: faça uma pergunta curta. Se o usuário quiser ambos, revise primeiro, depois construa as correções.

Arquivos de referência (carregue apenas o que precisar)

Arquivo	Carregue quando
references/web-lens.md	Revisão: sempre. Construção: ao tocar em layout, formulários, fontes, imagens, modo escuro ou acessibilidade.
references/motion-principles.md	Revisão: sempre que a página se mover ou tiver camadas: qualquer transição ou animação CSS (incluindo elevação ao passar o mouse), efeitos vinculados ou acionados por rolagem, animação canvas ou WebGL, sobreposições, gestos ou materiais translúcidos (backdrop-filter). Construção: sempre, é o guia principal.
references/visual-craft.md	Revisão: sempre para um pedido de "melhorar a aparência / menos genérico". Construção: ao projetar layout, tipografia ou cor.
references/hig-links.md	Quando precisar das próprias palavras da Apple para uma razão ou citação. Abra a página vinculada para o tópico específico apenas; nunca cite de memória.

Não carregue todo arquivo por padrão. Apenas uma página verdadeiramente estática (sem transições, sem animação, sem canvas, sem camadas translúcidas) pode pular o arquivo de movimento completo; então leia motion-principles.md §14 (movimento reduzido) e §15 (tipografia) no máximo. Cite apenas as seções que você realmente leu nesta sessão.

Script de medição

scripts/measure.mjs mede um site ao vivo com Playwright: estouro horizontal com culpados, alvos de toque, CLS/LCP, erros de console, inventário de tipos, contraste DOM, contraste de pixels para texto sobre canvas/imagens/gradientes, uma passagem de movimento reduzido e uma sem JavaScript, e uma passagem de foco por teclado. Execute node scripts/measure.mjs --help para uso. Use-o em vez de escrever um script de medição do zero; estenda-o com sondas direcionadas apenas para o que ele não cobre. Se o Playwright não estiver instalado, o script informa como instalá-lo; pergunte antes de instalar qualquer coisa no projeto do usuário.

Modo Revisão

Passo 1: Estabelecer contexto

Descubra, perguntando apenas o que estiver faltando:

1. O que está sendo revisado: URL ao vivo, código local, capturas de tela ou um arquivo de design. Observe o que você pode e não pode ver.
2. Público e objetivo: quem visita, o que a página deve fazer com que eles façam e em quais dispositivos.
3. Stack: framework, abordagem CSS (Tailwind, CSS modules, CSS puro), biblioteca de animação. As correções devem ser escritas neste stack.
4. Escopo: site inteiro, uma página ou um componente.
5. Decisões deliberadas: leia as próprias regras e registros de decisão do projeto antes de julgar qualquer coisa (CLAUDE.md, AGENTS.md, documentos de design, uma página de sistema de design, notas de aprovação, comentários ao lado do código). Uma escolha que o proprietário fez propositalmente (um efeito de hover, uma animação aprovada, uma cor da marca) não é uma constatação em si. Relate apenas seus efeitos colaterais concretos (por exemplo, "a elevação ao passar o mouse persiste após um toque em dispositivos touch") e marque tais constatações como tocando em uma decisão aprovada para que o proprietário decida. Se você não conseguir identificar se algo é deliberado, diga isso na constatação em vez de chamá-lo de sinal de template.

Passo 2: Meça, não adivinhe

• Com uma URL ao vivo e ferramentas de navegador disponíveis (automação de navegador, DevTools, Lighthouse, uma sessão Playwright ou Chrome), carregue a página em larguras móvel (cerca de 390 px) e desktop e meça: taxas de contraste, tamanhos de alvos de toque, estouro horizontal, mudanças de layout, carregamento de fontes, tamanhos de imagem, erros de console, visibilidade de foco via teclado. Prefira números reais. Comece com scripts/measure.mjs.
• Texto sobre canvas, imagens, vídeo ou gradientes: ferramentas de contraste baseadas em DOM não podem ver o que está desenhado atrás do texto, portanto, seu resultado lá não é nem aprovação nem reprovação. Meça pixels: capture a caixa de texto, capture-a novamente com o texto tornado transparente e calcule o contraste da cor do texto contra os piores pixels de fundo (measure.mjs faz isso; método em web-lens.md §4). Para fundos animados, tire várias amostras e relate o pior. Deixe o contraste como uma avaliação apenas se a medição de pixels for impossível, e diga por quê.
• Com apenas código, leia os arquivos relevantes e diga quais constatações vêm da leitura de código e não puderam ser confirmadas em tempo de execução.
• Com apenas capturas de tela, você pode julgar o artesanato visual, hierarquia e contraste aproximadamente; você não pode julgar movimento, foco, desempenho ou responsividade. Diga isso e não relate essas lentes como limpas.
• Se você não puder executar uma ferramenta que precisaria (sem acesso ao navegador, sem rede), diga isso e marque as constatações dependentes como não verificadas em vez de substituir por um palpite.

Passo 3: Execute as lentes nesta ordem

Trabalhe através delas em sequência. Pule uma lente apenas quando ela realmente não se aplicar e diga que a pulou.

1. Acessibilidade. Contraste, visibilidade de foco, caminho do teclado, tamanho do alvo, movimento reduzido, zoom de texto, rótulos, texto alternativo, elementos semânticos. Falhas aqui são as mais sérias e as mais objetivas. Detalhes: web-lens.md seções 1 a 4, 9 e 10, e motion-principles.md §14.
2. Lente web. Responsividade, sem rolagem horizontal, toque vs. hover, Core Web Vitals, mudanças de layout, imagens, fontes, modo escuro, formulários. Detalhes: todo web-lens.md.
3. Artesanato visual e aparência de template. Hierarquia de tipos, ritmo de espaçamento, disciplina de cor, moderação, elemento de assinatura, sinais de template genérico, lista de verificação de remoção. Detalhes: visual-craft.md.
4. Movimento e interação. Latência de resposta, rastreamento 1:1, capacidade de interrupção, springs vs. easing fixo, simetria de entrada/saída, rubber-banding, materiais, feedback, estados de pressionamento. Verifique cada um contra os 17 princípios em motion-principles.md; cite como "motion-principles.md §N". Apenas avalie o que existe; uma página sem gestos não recebe constatações de gestos. Mas se algo na página se mover ou for translúcido, esta lente é obrigatória: carregue motion-principles.md antes de escrever constatações e verifique pelo menos resposta, capacidade de interrupção, escolha de easing, movimento reduzido e, para backdrop-filter, materiais e prefers-reduced-transparency (§12, §14).
5. Conteúdo e microcópia. Rótulos de botão que nomeiam a ação, títulos específicos, mensagens de erro que dizem como corrigir, estados vazios e de carregamento, preenchimento de marketing vago, terminologia inconsistente, texto de espaço reservado deixado.

Gravidade

Nível	Significado	Exemplos
Crítico	Bloqueia usuários ou falha uma linha de base legal/de acessibilidade; corrija antes de enviar	Conteúdo ilegível ou inacessível por teclado, zoom desabilitado, formulário que não pode ser enviado no celular, texto abaixo de 3:1 contraste, página inutilizável a 320 px
Alto	Claramente prejudica a experiência, confiança ou conversão para muitos usuários	Estilos de foco ausentes, texto do corpo abaixo de 4.5:1, mudança de layout durante a leitura, imagem principal muito pesada, elementos clicáveis abaixo de 24 px, nenhum tratamento de movimento reduzido para movimento grande
Médio	Lacuna de polimento ou inconsistência notável	Tamanhos de fonte e espaçamento ad-hoc, duração fixa de easing em um elemento arrastável, recurso apenas hover, aglomerado de template genérico
Baixo	Pequeno refinamento ou melhoria de nível de gosto	Ajustes de tracking, leve desalinhamento, microcópia menor, retoques opcionais de modo escuro

Classifique pelo impacto no usuário, não pela facilidade da correção. Não infle a gravidade para preencher uma seção; um nível de gravidade vazio é aceitável.

Regras para constatações

• Revise apenas o que está realmente presente. Nenhuma constatação sem algo observado na página ou no código. Nenhuma lista de conselhos genéricos.
• Evidência ou rótulo. Cada constatação é Verificada (medida ou vista diretamente, com o valor) ou Avaliação (julgamento ou inferência, com como verificar).
• Cite com o nome do arquivo, sempre: "web-lens.md §4", "motion-principles.md §11", "o CLAUDE.md §7 do projeto". Nunca um "§N" puro, porque a skill e o projeto numeram suas seções.
• Cite os números: "texto do corpo #8a8a8a sobre #ffffff é 3.4:1, precisa de 4.5:1", "CTA tem 32x32 px".
• Credite o que funciona. Mencione até três coisas que são genuinamente boas, para que o usuário saiba o que manter.
• Uma causa raiz, uma constatação. Agrupe repetições ("12 botões carecem de estilos de foco") com uma contagem e exemplos.
• Não corrija sem ser solicitado. No modo revisão, relate; altere o código apenas se o usuário pedir. Mencione observações colaterais fora do escopo solicitado brevemente no final.
• Não imite a Apple cegamente. Se uma convenção web for melhor que um padrão Apple para este contexto, diga isso.

Formato do relatório

Comece com um resumo de 3 a 5 linhas: impressão geral, as uma ou duas coisas que mais importam, o que foi e não foi verificado. Em seguida, constatações agrupadas por gravidade (Crítico primeiro). Para cada constatação:

### [Gravidade] Título curto
**Problema:** o que está errado, onde (seletor, componente, URL ou região da captura de tela), com valores medidos. Verificada / Avaliação.
**Por que importa:** a razão, com uma fonte: references/web-lens.md §N, motion-principles.md §N, visual-craft.md §N, ou um link HIG de hig-links.md.
**Correção:** alteração concreta no stack do usuário (trecho de código ou valores CSS/JS exatos).

Termine com:

1. Ganhos rápidos: as constatações que levam minutos e elevam visivelmente a página.
2. Não verificado: toda lente ou item pulado ou apenas parcialmente executado, e por quê (sem acesso ao navegador, apenas captura de tela, arquivo de referência não carregado, etc.). Uma lente que está faltando nas constatações e faltando nesta lista conta como um erro de relatório.
3. Observações colaterais: coisas notadas fora do escopo, não tratadas.

Modo Construção

Use references/motion-principles.md como guia de trabalho. Padrões principais a serem aplicados sem serem solicitados:

• Responda ao pressionar, rastreie 1:1, permaneça interrompível. Feedback em pointerdown, o conteúdo segue o ponteiro de onde foi pego, nada bloqueia a entrada durante uma transição (§1 a §3).
• Springs para qualquer coisa que o usuário toque, easing fixo apenas para transições passivas. Criticamente amortecido por padrão; adicione bounce apenas quando o gesto carregava momentum (§4).
• Passe a velocidade de soltura para a animação e projete o momentum para flicks, folhas e carrosséis (§5, §6).
• Entrada e saída pelo mesmo caminho, a partir da origem do gatilho (§7). Limites suaves em vez de paradas bruscas (§9).
• Anime apenas transform e opacity para movimento e mantenha o trabalho de primeira pintura fora do caminho crítico (§11 e web-lens.md seções 5 e 6).
• Sempre envie as alternativas: prefers-reduced-motion, prefers-reduced-transparency, prefers-contrast (§14), :focus-visible visível, operação por teclado, alvos de toque de 44 px (web-lens.md).
• Prefira bibliotecas existentes que o projeto já usa (Motion/Framer Motion, GSAP, Vaul, Embla, View Transitions CSS nativas) em vez de física caseira, a menos que o projeto não tenha nenhuma e a interação precise dela.

Fluxo de trabalho de construção:

1. Leia como o projeto anima hoje (biblioteca, convenções CSS, tokens) e corresponda.
2. Nomeie a interação em uma frase: o que o usuário toca, o que se move, o que pode interrompê-la.
3. Implemente usando a seção de princípio correspondente; mantenha parâmetros spring em uma configuração compartilhada em vez de espalhar literais.
4. Teste: interrompa-a no meio do voo, inverta-a, arraste-a além da borda, use apenas o teclado, ative o movimento reduzido, limite a CPU no DevTools.
5. Relate o que você mudou e o que não pôde testar.

Princípios que se aplicam a ambos os modos

• Diga o que é verificado e o que é julgamento; nomeie a maneira de verificar qualquer coisa não verificada.
• Relate bloqueadores (sem acesso à URL, ferramenta ausente, arquivo ilegível) em vez de contorná-los silenciosamente.
• Fique dentro da solicitação: relate constatações colaterais em vez de corrigi-las sem ser solicitado.
• Prefira menos constatações bem fundamentadas a uma longa lista de genéricas.