ckmirafss/easy-on-the-eyes

Fácil para os Olhos

A maior parte da fadiga ocular em frente a uma tela vem de coisas que um site não pode controlar: piscar, distância focal, visão não corrigida, o ambiente. O que um site controla é quanta carga visual extra ele exige. Esta skill elimina esse trabalho extra e informa o quão forte é a evidência para cada regra.

Ela também mantém uma página confortável longe de parecer um template. Ela estuda sites reais em produção antes de projetar, e carrega um conjunto de regras de ofício para as escolhas que fazem o trabalho parecer gerado.

A afirmação que você pode fazer

Diga que o design "não adiciona esforço visual evitável". Nunca escreva que um design previne, reduz ou cura cansaço ocular, protege os olhos, ou é "azul-luz seguro". Não descreva modo escuro, tons quentes ou fontes especiais como características de saúde. Se o usuário pedir esse tipo de cópia, explique o porquê e ofereça a redação honesta.

Modos

Leia os argumentos com os quais a skill foi invocada.

• Nenhum argumento, ou uma tarefa de construção. Para uma nova página ou seção, primeiro estude referências (veja "Estude antes de projetar"). Depois aplique as regras enquanto escreve ou edita a UI. Comece de assets/tokens.css quando o projeto ainda não tiver tokens de cor ou tipo. Quando a UI estiver escrita, execute audit.mjs no código-fonte e inspect.mjs na página renderizada, e revise "O que o script não pode ver" antes de dizer que está pronto.
• audit (opcionalmente seguido de um caminho). Execute o script, depois revise o que um script não pode ver. Relate com o template abaixo. Não mude nada.
• study seguido de uma ou mais URLs. Inspecione cada página e reporte seu resumo de design: o que ela faz, o que vale a pena pegar emprestado e quais regras de conforto ela quebra. Não mude nada.
• fix (opcionalmente seguido de um caminho). Execute a auditoria. Corrija erros, depois avisos. Deixe uma nota em paz a menos que corrigir um erro ou aviso dependa dela, ou sua própria revisão mostre que é um problema real. Execute o script novamente e relate.

Executando o script

Execute-o da raiz do projeto e forneça o caminho para verificar. O script vive na pasta scripts/ desta skill, então use o caminho de onde esta skill foi carregada:

node <skill-dir>/scripts/audit.mjs src                 # relatório de texto, sai com 1 se qualquer erro
node <skill-dir>/scripts/audit.mjs src --json          # legível por máquina
node <skill-dir>/scripts/audit.mjs src --strict        # sai com 1 também em avisos
node <skill-dir>/scripts/audit.mjs contrast "#1f2328" "#ffffff"          # um par
node <skill-dir>/scripts/audit.mjs contrast "#8a8f98" "#ffffff" --min 3  # uma borda ou ícone

node <skill-dir>/scripts/inspect.mjs https://example.com              # resumo de design e verificação de conforto renderizada
node <skill-dir>/scripts/inspect.mjs http://localhost:3000 --out shots # também salva capturas de tela claras e escuras
node <skill-dir>/scripts/inspect.mjs dist/index.html --json

• audit.mjs lê arquivos-fonte. inspect.mjs abre uma página em um navegador real, então mede o que o leitor obtém: o contraste do texto real em seu fundo real, caracteres reais por linha, se um esquema escuro existe e se o movimento para quando movimento reduzido é solicitado.
• inspect.mjs funciona em qualquer URL ou arquivo HTML local. Ele precisa do Playwright no projeto (npm i -D playwright && npx playwright install chromium). Se estiver faltando e você não puder instalá-lo, diga que a verificação renderizada não foi executada.
• Um caminho é obrigatório. Se o usuário não forneceu nenhum, use a pasta que contém o código-fonte da UI.
• Cores podem ser hex, rgb(), hsl(), oklch(), white ou black.
• Para silenciar um achado que é intencional, coloque um comentário contendo easy-on-the-eyes-ignore naquela linha, ou easy-on-the-eyes-ignore-next-line na linha anterior.
• O script precisa do Node 18 ou superior e não tem dependências. Se o Node estiver faltando, aplique as regras manualmente e diga que o script não foi executado.

Ambos os scripts reportam sob os IDs de regra na tabela abaixo. Use esses mesmos IDs em seu relatório.

Estude antes de projetar

Modelos produzem a média do que viram, e a média é o que as pessoas reconhecem como gerado. Olhar para trabalhos específicos e publicados primeiro dá a você decisões reais para reagir.

1. Escolha três a cinco sites ativos na mesma categoria do que você está construindo. Use os que o usuário nomear. Caso contrário, encontre-os com pesquisa na web, ou com qualquer ferramenta de referência de design ou captura de tela conectada à sessão.
2. Execute inspect.mjs em cada um, com --out para que você possa abrir as capturas de tela e observá-las.
3. Para cada um, anote as fontes e escala de tipo, quantas cores usa e onde vai o acento, o comprimento da linha, a estrutura das seções, e a única coisa que a torna reconhecível.
4. Leia os achados de conforto para cada referência. Sites admirados frequentemente têm texto minúsculo, contraste fraco e movimento pesado. Pegue a composição emprestada e deixe esses problemas para trás. references/craft.md tem a tabela.
5. Diga ao usuário quais sites você estudou e o que você tirou de cada um. Pegue estrutura e decisões emprestadas. Nunca copie o nome, logotipo, redação, imagens ou layout exato de uma marca.

Se você não conseguir abrir nenhuma referência, diga isso e projete a partir das regras e de references/craft.md.

Graus de evidência

Cada regra carrega um grau. Repita o grau quando explicar um achado, para que ninguém confunda um hábito com um fato.

Grau	Significado
research	Suportado por estudos controlados ou revisões sistemáticas
standard	Estabelecido por um critério de sucesso da WCAG 2.2. O arquivo de referência dá o critério e seu nível
convention	Sensato e amplamente implementado, mas sem teste por trás
inference	Derivado de pesquisa sobre um estímulo relacionado, não testado em páginas web

Regras

Severidade decide a ordem: erros primeiro, depois avisos, depois notas. Dentro de uma severidade, trabalhe descendo na tabela. A severidade mostrada é a usual. O script a diminui quando não consegue dizer se uma linha é um problema (um tamanho pequeno no que pode ser um rótulo), e você pode aumentá-la quando sua revisão mostrar danos reais.

ID	Regra	Severidade	Grau	Referência
type-rem-zoom	O texto deve sobreviver ao zoom. Tamanhos em rem, sem tamanhos de fonte apenas com viewport, zoom nunca desabilitado.	erro	standard	tipografia
contrast-floor	Cada par de texto com pelo menos 4.5:1. Texto grande e partes de UI com pelo menos 3:1.	erro	standard	contraste-e-cor
contrast-color-alone	Nunca sinalize estado com cor sozinha.	erro	standard	contraste-e-cor
motion-flash	Nada pisca mais de três vezes por segundo.	erro	standard	movimento
motion-autoplay	Sem vídeo em autoplay sem controles. Qualquer coisa que se mova por mais de 5 s além de texto precisa de pausa. Sem loops infinitos além de texto.	erro	standard	movimento
motion-reduced	Movimento existe apenas dentro de prefers-reduced-motion: no-preference.	erro	standard	movimento
theme-focus	Nunca remova o contorno de foco sem um substituto visível de pelo menos 3:1.	erro	standard	tematização
type-body-size	Texto do corpo 1rem mínimo, 1.125rem a 1.25rem para leitura longa. Nada legível abaixo de 0.875rem.	aviso	research	tipografia
motion-triggers	Sem parallax, sequestro de scroll ou zoom em grande área. Fades e mudanças de cor são aceitáveis.	aviso	research	movimento
contrast-dark-secondary	Texto secundário em superfícies escuras com 8.5:1 ou melhor. AA sozinho lê fraco ali.	aviso	inference	contraste-e-cor
contrast-saturated-on-dark	Sem vermelho ou azul saturado como texto pequeno em escuro. Acentos mais claros e calmos em temas escuros.	aviso	research	contraste-e-cor
lum-section-steps	Sem alternância de seções escuras e brancas com sangria total. Sem incorporações brancas ou modais em um tema escuro.	aviso	inference	layout-e-padrões
lum-white-flash	Fundo html tematizado e uma declaração color-scheme e meta tag.	aviso	convention	tematização
layout-shift	Reserve dimensões de mídia, combine métricas de fontes substitutas, mantenha CLS em ou abaixo de 0.1.	aviso	research	layout-e-padrões
contrast-pure-extremes	Quase-preto em quase-branco, off-white em cinza escuro. Evite preto puro e branco puro como texto e fundo da página.	aviso	convention	contraste-e-cor
type-leading	line-height do corpo 1.5 (1.4 a 1.6). Cabeçalhos 1.1 a 1.3.	aviso	convention	tipografia
type-weight	Peso do corpo 400 ou mais. Sem 100 a 300 em tamanhos de corpo.	aviso	convention	tipografia
type-align	text-align: start. Sem texto justificado no corpo. Maiúsculas apenas para rótulos curtos.	aviso	standard	tipografia
layout-targets	Alvos de ponteiro com 24 por 24 px CSS no mínimo, 44 por 44 para ações primárias. Links dentro de uma frase são isentos.	aviso	standard	layout-e-padrões
theme-both-schemes	Implemente claro e escuro e siga prefers-color-scheme. Um alternador manual é opcional e padrão para sistema.	nota	research	tematização
pattern-stripes	Sem listras ou grades de alto contraste com período de 7 a 27 px sobre grandes áreas.	nota	inference	layout-e-padrões
type-measure	Texto de leitura limitado a 50ch a 60ch, que é cerca de 65 a 78 caracteres.	nota	convention	tipografia
motion-duration	100 a 300 ms, teto de 500 ms, ease-out para entradas.	nota	convention	movimento
theme-preferences	Respeite prefers-contrast, forced-colors e prefers-reduced-transparency.	nota	convention	tematização
pattern-clutter	Uma ênfase primária por visualização. Poucas cores de acento, tamanhos e estilos de borda.	nota	research	layout-e-padrões
craft-copy	Cópia específica. Nunca invente estatísticas, depoimentos, avaliações ou logotipos de clientes.	aviso	convention	ofício
craft-reference	Estude três a cinco sites reais na mesma categoria antes de projetar. Pegue decisões emprestadas, nunca copie.	nota	convention	ofício
craft-one-idea	Uma ideia distintiva por visualização. Todo o resto permanece quieto.	nota	convention	ofício
craft-palette	Neutros com tom e um acento. Sem gradientes índigo ou roxo, sem texto com gradiente.	nota	convention	ofício
craft-show-product	Mostre a interface, dados ou código reais. Sem fileira de três cartões de ícone idênticos, sem ícones de emoji.	nota	convention	ofício
craft-layout	Não centralize tudo. Divisões de grade desiguais e estrutura de seção variada.	nota	convention	ofício
craft-restraint	Superfícies planas e traços finos. Poucas sombras, uma escala de raio, sem blur e brilho empilhados.	nota	convention	ofício

Os arquivos de referência contêm o raciocínio, fontes e código antes/depois. Leia cada um que cobre uma regra que você está aplicando ou relatando. Uma correção em toda uma página geralmente precisa de três ou quatro deles.

• references/contrast-and-color.md: escolha de cores, construção de uma paleta ou um tema escuro, explicação de um achado de contraste.
• references/typography.md: tamanho de tipo, comprimento de linha, espaçamento, fontes, tipo fluido.
• references/motion.md: animação, transições, vídeo, efeitos de scroll, carregadores.
• references/layout-and-patterns.md: tabelas, grades, listras, densidade, fundos de seção, imagens, mudança de layout.
• references/theming.md: temas claro e escuro, um alternador de tema, estilos de foco, consultas de mídia de preferência do usuário, Tailwind e shadcn/ui.
• references/craft.md: projetar uma nova página ou seção, um resultado que parece template ou gerado, o que pegar emprestado de um site de referência e o que deixar.
• references/evidence.md: quando o usuário pergunta por que, questiona uma regra, ou pergunta sobre luz azul, modo escuro, fontes de dislexia ou APCA.

Padrões para escrever sem ser perguntado

:root {
  color-scheme: light dark;
  --bg:     light-dark(oklch(0.985 0.002 90), oklch(0.18 0.01 255));
  --text:   light-dark(oklch(0.24 0.01 255),  oklch(0.93 0.005 255));
  --muted:  light-dark(oklch(0.48 0.01 255),  oklch(0.78 0.01 255));
  --accent: light-dark(oklch(0.5 0.19 255),   oklch(0.74 0.13 255));
}
html { background-color: var(--bg); color: var(--text); }
body { font-size: clamp(1rem, 0.95rem + 0.25vw, 1.125rem); line-height: 1.6; }
p, li { max-inline-size: 55ch; }
:focus-visible { outline: 2px solid var(--accent); outline-offset: 2px; }
@media (prefers-reduced-motion: no-preference) {
  .card { transition: transform 200ms ease-out; }
}

Adicione <meta name="color-scheme" content="light dark"> ao cabeçalho da página.

Texto do corpo mede 15.75:1 em claro e 15.30:1 em escuro. Texto suave mede 6.25:1 e 9.39:1. O acento mede 5.78:1 e 8.14:1, que é por que é usado para o anel de foco: a cor Highlight do sistema pode cair abaixo de 3:1 em uma superfície escura. assets/tokens.css tem o conjunto completo, incluindo superfícies, bordas para controles, um tamanho de leitura longa e um tema escuro opcional.

Só adicione color-scheme: light dark uma vez que a página realmente tenha cores para ambos os esquemas. Em uma página com cores claras codificadas, isso dá barras de rolagem e controles de formulário escuros em uma página branca. Corrija theme-both-schemes na mesma alteração.

Tailwind e shadcn/ui enviam branco puro com quase-preto (cerca de 19.8:1) e bg-white / text-black como valores puros. Sobrescreva --background e --foreground, e use utilitários semânticos como bg-background e text-foreground.

O que o script não pode ver

inspect.mjs cobre o primeiro, terceiro e quinto itens abaixo quando você pode executá-lo na página renderizada. Verifique o resto, e todos eles quando ele não puder executar, lendo o código ou a página. Se você não puder verificar um, liste-o sob "Não verificado" e diga por que.

• Contraste de cada par real de texto e fundo, incluindo texto sobre imagens e gradientes. Meça pares com o comando contrast
• Se texto pequeno é conteúdo do corpo ou um rótulo curto
• Comprimento da linha no layout renderizado. Conte caracteres em algumas linhas completas
• Taxa de flash de animações e vídeo
• Saltos de brilho entre seções e incorporações brancas dentro de temas escuros
• Mudança de layout durante o carregamento, incluindo imagens e vídeo sem width e height
• Se o estado é transmitido apenas pela cor
• Animação orientada por JavaScript que ignora movimento reduzido
• Tamanhos definidos em em, porcentagens ou a abreviação font, e listras construídas a partir de background-size

Template de relatório

Fácil para os Olhos

Caminho auditado: <caminho>
Script: <caminho do audit.mjs>

Erros:
  <nenhum ou lista>

Avisos:
  <nenhum ou lista>

Notas:
  <nenhum ou lista>

Não verificado:
  <ítens com motivo>

Resumo:
  Total de problemas: <número>
  Erros: <número>
  Avisos: <número>

Use uma lista com marcadores para muitos itens na mesma seção. Cada item de problema deve ter o ID da regra, o local (caminho do arquivo e número da linha, ou "no <nome>" para regras que afetam um componente ou elemento nomeado), e uma breve explicação. Se o script foi executado, diga que foi. Se você corrigiu algo, liste as correções.

Quando você reporta para o modo audit, não mude nada e não liste correções. Para o modo fix, liste o que o script corrigiu e qualquer correção manual adicional.

O usuário pode perguntar por que uma regra existe, o que significa um grau, ou o que diferencia dois tipos de severidade. Leia o arquivo de referência da regra e responda com citações das fontes que ele contém.