ckmirafss/easy-on-the-eyes

Facile pour les Yeux

La plupart des fatigues oculaires devant un écran proviennent de choses qu'un site web ne peut pas toucher : le clignement des yeux, la distance de mise au point, la vision non corrigée, la pièce. Ce qu'un site contrôle, c'est la quantité de travail visuel supplémentaire qu'il demande. Ce skill supprime ce travail supplémentaire et indique la force des preuves pour chaque règle.

Il empêche également une page confortable de ressembler à un modèle. Il étudie des sites réels et mis en production avant de concevoir, et il contient un ensemble de règles artisanales pour les choix qui donnent l'impression qu'un travail est généré.

L'affirmation que vous êtes autorisé à faire

Dire que le design « n'ajoute pas de tension visuelle évitable ». Ne jamais écrire qu'un design prévient, réduit ou guérit la fatigue oculaire, protège les yeux, ou est « sans lumière bleue ». Ne pas décrire le mode sombre, les teintes chaudes ou les polices spéciales comme des fonctions de santé. Si l'utilisateur demande ce genre de texte, expliquez pourquoi et proposez la formulation honnête.

Modes

Lisez les arguments avec lesquels le skill a été invoqué.

• Aucun argument, ou une tâche de construction. Pour une nouvelle page ou section, étudiez d'abord les références (voir « Étudier avant de concevoir »). Appliquez ensuite les règles pendant que vous écrivez ou modifiez l'UI. Commencez à partir de assets/tokens.css lorsque le projet n'a pas encore de jetons de couleur ou de type. Une fois l'UI écrite, exécutez audit.mjs sur le code source et inspect.mjs sur la page rendue, et parcourez « Ce que le script ne peut pas voir » avant de dire que c'est terminé.
• audit (éventuellement suivi d'un chemin). Exécutez le script, puis examinez ce qu'un script ne peut pas voir. Faites un rapport avec le modèle ci-dessous. Ne changez rien.
• study suivi d'une ou plusieurs URL. Inspectez chaque page et rapportez son brief de conception : ce qu'elle fait, ce qui vaut la peine d'être emprunté et quelles règles de confort elle enfreint. Ne changez rien.
• fix (éventuellement suivi d'un chemin). Exécutez l'audit. Corrigez les erreurs, puis les avertissements. Laissez une note tranquille à moins que la correction d'une erreur ou d'un avertissement en dépende, ou que votre propre examen montre qu'il s'agit d'un vrai problème. Réexécutez le script et faites un rapport.

Exécution du script

Exécutez-le depuis la racine du projet et donnez-lui le chemin à vérifier. Le script se trouve dans le dossier scripts/ de ce skill, utilisez donc le chemin à partir duquel ce skill a été chargé :

node <skill-dir>/scripts/audit.mjs src                 # rapport texte, sortie 1 si erreur
node <skill-dir>/scripts/audit.mjs src --json          # lisible par machine
node <skill-dir>/scripts/audit.mjs src --strict        # sortie 1 aussi pour les avertissements
node <skill-dir>/scripts/audit.mjs contrast "#1f2328" "#ffffff"          # une paire
node <skill-dir>/scripts/audit.mjs contrast "#8a8f98" "#ffffff" --min 3  # une bordure ou icône

node <skill-dir>/scripts/inspect.mjs https://example.com              # brief de conception et vérification de confort rendue
node <skill-dir>/scripts/inspect.mjs http://localhost:3000 --out shots # enregistre aussi les captures d'écran claires et sombres
node <skill-dir>/scripts/inspect.mjs dist/index.html --json

• audit.mjs lit les fichiers sources. inspect.mjs ouvre une page dans un vrai navigateur, il mesure donc ce que le lecteur obtient : le contraste du texte réel sur son fond réel, les caractères réels par ligne, si un thème sombre existe et si le mouvement s'arrête lorsque le mouvement réduit est demandé.
• inspect.mjs fonctionne sur n'importe quelle URL ou fichier HTML local. Il nécessite Playwright dans le projet (npm i -D playwright && npx playwright install chromium). S'il manque et que vous ne pouvez pas l'installer, dites que la vérification rendue n'a pas été effectuée.
• Un chemin est requis. Si l'utilisateur n'en a fourni aucun, utilisez le dossier qui contient le code source de l'UI.
• Les couleurs peuvent être en hexadécimal, rgb(), hsl(), oklch(), white ou black.
• Pour faire taire un résultat intentionnel, mettez un commentaire contenant easy-on-the-eyes-ignore sur cette ligne, ou easy-on-the-eyes-ignore-next-line sur la ligne précédente.
• Le script nécessite Node 18 ou une version ultérieure et n'a pas de dépendances. Si Node est manquant, appliquez les règles manuellement et dites que le script n'a pas été exécuté.

Les deux scripts rapportent sous les identifiants de règle dans le tableau ci-dessous. Utilisez ces mêmes identifiants dans votre rapport.

Étudier avant de concevoir

Les modèles produisent la moyenne de ce qu'ils ont vu, et la moyenne est ce que les gens reconnaissent comme généré. Regarder d'abord un travail spécifique et mis en production vous donne de vraies décisions auxquelles réagir.

1. Choisissez trois à cinq sites en ligne dans la même catégorie que ce que vous construisez. Utilisez ceux que l'utilisateur nomme. Sinon, trouvez-les avec une recherche web, ou avec tout outil de référence de conception ou de capture d'écran connecté à la session.
2. Exécutez inspect.mjs sur chacun, avec --out afin de pouvoir ouvrir les captures d'écran et les regarder.
3. Pour chacun, notez les polices et l'échelle typographique, le nombre de couleurs utilisées et où va l'accent, la longueur de ligne, la structure des sections, et la chose qui le rend reconnaissable.
4. Lisez les résultats de confort pour chaque référence. Les sites admirés publient souvent du texte minuscule, un contraste faible et des animations lourdes. Empruntez la composition et laissez cela derrière vous. references/craft.md contient le tableau.
5. Dites à l'utilisateur quels sites vous avez étudiés et ce que vous avez pris de chacun. Empruntez la structure et les décisions. Ne copiez jamais le nom, le logo, le libellé, les images ou la mise en page exacte d'une marque.

Si vous ne pouvez ouvrir aucune référence, dites-le et concevez à partir des règles et de references/craft.md.

Niveaux de preuve

Chaque règle porte un seul niveau. Répétez le niveau lorsque vous expliquez un résultat, afin que personne ne confonde une habitude avec un fait.

Niveau	Signification
research	Soutenu par des études contrôlées ou des revues systématiques
standard	Défini par un critère de succès WCAG 2.2. Le fichier de référence donne le critère et son niveau
convention	Sensé et largement utilisé, mais sans essai derrière
inference	Dérivé de la recherche sur un stimulus connexe, non testé sur des pages web

Règles

La sévérité détermine l'ordre : d'abord les erreurs, puis les avertissements, puis les notes. À l'intérieur d'une sévérité, parcourez le tableau de haut en bas. La sévérité indiquée est la sévérité habituelle. Le script la diminue lorsqu'il ne peut pas dire si une ligne est un problème (une petite taille sur ce qui peut être une étiquette), et vous pouvez l'augmenter lorsque votre examen montre un réel préjudice.

ID	Règle	Sévérité	Niveau	Référence
type-rem-zoom	Le texte doit survivre au zoom. Tailles en rem, pas de tailles de police uniquement basées sur la fenêtre, zoom jamais désactivé.	erreur	standard	typographie
contrast-floor	Chaque paire de texte au moins 4,5:1. Grand texte et parties UI au moins 3:1.	erreur	standard	contraste-et-couleur
contrast-color-alone	Ne jamais signaler un état avec la seule couleur.	erreur	standard	contraste-et-couleur
motion-flash	Rien ne clignote plus de trois fois par seconde.	erreur	standard	animation
motion-autoplay	Pas de vidéo en lecture automatique sans commandes. Tout ce qui bouge pendant plus de 5 s à côté du texte nécessite une pause. Pas de boucles sans fin à côté du texte.	erreur	standard	animation
motion-reduced	Le mouvement existe uniquement à l'intérieur de prefers-reduced-motion: no-preference.	erreur	standard	animation
theme-focus	Ne jamais supprimer le contour de focus sans un remplacement visible d'au moins 3:1.	erreur	standard	thématisation
type-body-size	Texte du corps 1rem minimum, 1.125rem à 1.25rem pour une longue lecture. Rien de lisible en dessous de 0.875rem.	avertissement	recherche	typographie
motion-triggers	Pas de parallaxe, de détournement de défilement ou de zoom sur grande surface. Les fondus et les changements de couleur sont acceptables.	avertissement	recherche	animation
contrast-dark-secondary	Texte secondaire sur surfaces sombres à 8,5:1 ou mieux. AA seul semble faible là.	avertissement	inférence	contraste-et-couleur
contrast-saturated-on-dark	Pas de rouge ou bleu saturé en petit texte sur fond sombre. Accents plus clairs et plus calmes dans les thèmes sombres.	avertissement	recherche	contraste-et-couleur
lum-section-steps	Pas de sections alternées à fond perdu sombres et blanches. Pas d'embeds ou de modales blancs dans un thème sombre.	avertissement	inférence	mise-en-page-et-motifs
lum-white-flash	Arrière-plan html thématisé et une déclaration color-scheme et une balise meta.	avertissement	convention	thématisation
layout-shift	Réservez les dimensions des médias, faites correspondre les métriques de polices de secours, maintenez le CLS à 0,1 ou moins.	avertissement	recherche	mise-en-page-et-motifs
contrast-pure-extremes	Presque noir sur presque blanc, blanc cassé sur gris foncé. Évitez le noir pur et le blanc pur comme texte de page et arrière-plan.	avertissement	convention	contraste-et-couleur
type-leading	line-height du corps 1,5 (1,4 à 1,6). Titres 1,1 à 1,3.	avertissement	convention	typographie
type-weight	Poids du corps 400 ou plus. Pas de 100 à 300 aux tailles de corps.	avertissement	convention	typographie
type-align	text-align: start. Pas de texte justifié. Majuscules uniquement pour les courtes étiquettes.	avertissement	standard	typographie
layout-targets	Cibles de pointage 24 par 24 px CSS minimum, 44 par 44 pour les actions principales. Les liens dans une phrase sont exemptés.	avertissement	standard	mise-en-page-et-motifs
theme-both-schemes	Livrez le clair et le sombre et suivez prefers-color-scheme. Un basculement manuel est facultatif et par défaut, il suit le système.	note	recherche	thématisation
pattern-stripes	Pas de rayures ou de grilles à contraste élevé avec une période de 7 à 27 px sur de grandes surfaces.	note	inférence	mise-en-page-et-motifs
type-measure	Texte de lecture plafonné à 50ch à 60ch, soit environ 65 à 78 caractères.	note	convention	typographie
motion-duration	100 à 300 ms, plafond de 500 ms, ease-out pour les entrées.	note	convention	animation
theme-preferences	Respectez prefers-contrast, forced-colors et prefers-reduced-transparency.	note	convention	thématisation
pattern-clutter	Un accent principal par vue. Peu de couleurs d'accent, de tailles et de styles de bordure.	note	recherche	mise-en-page-et-motifs
craft-copy	Texte spécifique. N'inventez jamais de statistiques, témoignages, évaluations ou logos de clients.	avertissement	convention	artisanat
craft-reference	Étudiez trois à cinq sites réels dans la même catégorie avant de concevoir. Empruntez des décisions, ne copiez jamais.	note	convention	artisanat
craft-one-idea	Une idée distinctive par vue. Tout le reste reste discret.	note	convention	artisanat
craft-palette	Neutres teintés et un accent. Pas de dégradés indigo ou violet, pas de texte en dégradé.	note	convention	artisanat
craft-show-product	Montrez l'interface réelle, les données ou le code. Pas de rangée de trois cartes icônes identiques, pas d'icônes emoji.	note	convention	artisanat
craft-layout	Ne centrez pas tout. Divisions de grille inégales et structure de section variée.	note	convention	artisanat
craft-restraint	Surfaces planes et traits fins. Peu d'ombres, une échelle de rayon, pas d'empilement de flou et de lueur.	note	convention	artisanat

Les fichiers de référence contiennent le raisonnement, les sources et le code avant/après. Lisez chacun de ceux qui couvrent une règle que vous appliquez ou signalez. Une correction sur une page entière nécessite généralement trois ou quatre d'entre eux.

• references/contraste-et-couleur.md : choisir les couleurs, construire une palette ou un thème sombre, expliquer un résultat de contraste.
• references/typographie.md : taille de police, longueur de ligne, espacement, polices, type fluide.
• references/animation.md : animation, transitions, vidéo, effets de défilement, chargeurs.
• references/mise-en-page-et-motifs.md : tableaux, grilles, rayures, densité, arrière-plans de section, images, décalage de mise en page.
• references/thématisation.md : thèmes clair et sombre, basculement de thème, styles de focus, requêtes média de préférence utilisateur, Tailwind et shadcn/ui.
• references/artisanat.md : concevoir une nouvelle page ou section, un résultat qui a l'air d'un modèle ou généré, quoi emprunter d'un site de référence et quoi laisser.
• references/preuves.md : lorsque l'utilisateur demande pourquoi, questionne une règle, ou demande à propos de la lumière bleue, du mode sombre, des polices pour dyslexiques ou de l'APCA.

Valeurs par défaut à écrire sans qu'on vous le demande

: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; }
}

Ajoutez <meta name="color-scheme" content="light dark"> à l'en-tête de la page.

Le texte du corps mesure 15,75:1 en clair et 15,30:1 en sombre. Le texte atténué mesure 6,25:1 et 9,39:1. L'accent mesure 5,78:1 et 8,14:1, c'est pourquoi il est utilisé pour l'anneau de focus : la couleur système Highlight peut tomber en dessous de 3:1 sur une surface sombre. assets/tokens.css contient l'ensemble complet, y compris les surfaces, les bordures pour les contrôles, une taille pour la lecture longue et un thème atténué sur option.

N'ajoutez color-scheme: light dark qu'une fois que la page a vraiment des couleurs pour les deux thèmes. Sur une page avec des couleurs claires codées en dur, cela donne des barres de défilement et des contrôles de formulaire sombres sur une page blanche. Corrigez theme-both-schemes dans le même changement.

Tailwind et shadcn/ui livrent du blanc pur avec du presque noir (environ 19,8:1) et bg-white / text-black comme valeurs pures. Remplacez --background et --foreground, et utilisez des utilitaires sémantiques tels que bg-background et text-foreground.

Ce que le script ne peut pas voir

inspect.mjs couvre les premier, troisième et cinquième éléments ci-dessous lorsque vous pouvez l'exécuter sur la page rendue. Vérifiez le reste, et tous lorsqu'il n'a pas pu s'exécuter, en lisant le code ou la page. Si vous ne pouvez pas en vérifier un, listez-le sous « Non vérifié » et dites pourquoi.

• Contraste de chaque paire réelle de texte et d'arrière-plan, y compris le texte sur les images et les dégradés. Mesurez les paires avec la commande contrast
• Si le petit texte est un corps de texte ou une courte étiquette
• Longueur de ligne dans la mise en page rendue. Comptez les caractères dans quelques lignes complètes
• Taux de scintillement des animations et vidéos
• Sauts de luminosité entre les sections et les embeds blancs dans les thèmes sombres
• Décalage de mise en page pendant le chargement, y compris les images et vidéos sans width et height
• Si l'état est transporté par la seule couleur
• Animation pilotée par JavaScript qui ignore le mouvement réduit
• Tailles définies en em, pourcentages ou la forme abrégée font, et rayures construites à partir de background-size

Modèle de rapport

Easy on the Eyes - Audit de <chemin>

Erreurs
-------
- [type-rem-zoom] Ligne 42 : font-size: 12px; (utilisez rem).

Avertissements
------------
- [type-body-size] Ligne 15 : font-size: 0.75rem; (minimum 0.875rem).

Notes
-----
- [theme-both-schemes] Seul un thème clair est présent. Ajoutez un thème sombre.

Non vérifié
----------
- Contraste du texte sur les images (inspect.mjs n'a pas pu s'exécuter - pas de Playwright).

Facile pour les yeux ✔ / ✘

Remplacez le ✔ par la coche appropriée (✔ si tout va bien, ✘ si des problèmes persistent après correction).