ckmirafss/easy-on-the-eyes

Leicht für die Augen

Die meiste Augenbelastung am Bildschirm kommt von Dingen, die eine Website nicht beeinflussen kann: Blinzeln, Fokusabstand, unkorrigierte Sehschwäche, der Raum. Was eine Seite kontrolliert, ist, wie viel zusätzliche visuelle Arbeit sie verlangt. Diese Fähigkeit entfernt diese zusätzliche Arbeit und gibt an, wie stark die Belege für jede Regel sind.

Sie verhindert auch, dass eine bequeme Seite wie eine Vorlage aussieht. Sie studiert echte, veröffentlichte Websites vor dem Gestalten und führt eine Reihe von Handwerksregeln für die Entscheidungen, die Arbeit generisch aussehen lassen.

Die Behauptung, die Sie aufstellen dürfen

Sagen Sie, das Design „fügt keine vermeidbare visuelle Belastung hinzu“. Schreiben Sie niemals, dass ein Design Augenbelastung verhindert, reduziert oder heilt, die Augen schützt oder „blaulichtsicher“ ist. Beschreiben Sie den Dark Mode, warme Tönungen oder spezielle Schriftarten nicht als Gesundheitsfunktionen. Wenn der Nutzer nach solcher Werbung fragt, erklären Sie warum und bieten Sie die ehrliche Formulierung an.

Modi

Lesen Sie die Argumente, mit denen die Fähigkeit aufgerufen wurde.

• Kein Argument oder eine Build-Aufgabe. Erstellen Sie für eine neue Seite oder einen neuen Abschnitt zuerst Referenzen (siehe „Studieren Sie vor dem Gestalten“). Wenden Sie dann die Regeln an, während Sie UI schreiben oder bearbeiten. Beginnen Sie mit assets/tokens.css, wenn das Projekt noch keine Farb- oder Schriftart-Tokens hat. Wenn die UI geschrieben ist, führen Sie audit.mjs auf dem Quellcode und inspect.mjs auf der gerenderten Seite aus und gehen Sie „Was das Skript nicht sehen kann“ durch, bevor Sie sagen, dass es fertig ist.
• audit (optional gefolgt von einem Pfad). Führen Sie das Skript aus und überprüfen Sie dann, was ein Skript nicht sehen kann. Melden Sie mit der Vorlage unten. Ändern Sie nichts.
• study gefolgt von einer oder mehreren URLs. Untersuchen Sie jede Seite und melden Sie deren Design-Brief: was sie tut, was es wert ist, auszuleihen, und welche Komfortregeln sie bricht. Ändern Sie nichts.
• fix (optional gefolgt von einem Pfad). Führen Sie das Audit aus. Korrigieren Sie Fehler, dann Warnungen. Lassen Sie einen Hinweis in Ruhe, es sei denn, die Korrektur eines Fehlers oder einer Warnung hängt davon ab, oder Ihre eigene Überprüfung zeigt, dass es ein echtes Problem ist. Führen Sie das Skript erneut aus und melden Sie.

Ausführen des Skripts

Führen Sie es vom Projektstamm aus und geben Sie den zu überprüfenden Pfad an. Das Skript befindet sich im scripts/-Ordner dieser Fähigkeit, also verwenden Sie den Pfad, von dem diese Fähigkeit geladen wurde:

node <skill-dir>/scripts/audit.mjs src                 # Textbericht, Exit 1 bei jedem Fehler
node <skill-dir>/scripts/audit.mjs src --json          # maschinenlesbar
node <skill-dir>/scripts/audit.mjs src --strict        # Exit 1 auch bei Warnungen
node <skill-dir>/scripts/audit.mjs contrast "#1f2328" "#ffffff"          # ein Paar
node <skill-dir>/scripts/audit.mjs contrast "#8a8f98" "#ffffff" --min 3  # ein Rand oder Icon

node <skill-dir>/scripts/inspect.mjs https://example.com              # Design-Brief und gerenderter Komfort-Check
node <skill-dir>/scripts/inspect.mjs http://localhost:3000 --out shots # speichert auch helle und dunkle Screenshots
node <skill-dir>/scripts/inspect.mjs dist/index.html --json

• audit.mjs liest Quelldateien. inspect.mjs öffnet eine Seite in einem echten Browser, misst also, was der Leser bekommt: den Kontrast von echtem Text auf seinem echten Hintergrund, echte Zeichen pro Zeile, ob ein dunkles Schema existiert und ob Bewegung stoppt, wenn reduzierte Bewegung angefordert wird.
• inspect.mjs funktioniert mit jeder URL oder lokalen HTML-Datei. Es benötigt Playwright im Projekt (npm i -D playwright && npx playwright install chromium). Wenn es fehlt und Sie es nicht installieren können, sagen Sie, dass der gerenderte Check nicht ausgeführt wurde.
• Ein Pfad ist erforderlich. Wenn der Nutzer keinen angegeben hat, verwenden Sie den Ordner, der die UI-Quelle enthält.
• Farben können hex, rgb(), hsl(), oklch(), white oder black sein.
• Um einen Befund, der beabsichtigt ist, zu unterdrücken, fügen Sie einen Kommentar mit easy-on-the-eyes-ignore in dieser Zeile oder easy-on-the-eyes-ignore-next-line in der Zeile davor ein.
• Das Skript benötigt Node 18 oder neuer und hat keine Abhängigkeiten. Wenn Node fehlt, wenden Sie die Regeln von Hand an und sagen Sie, dass das Skript nicht ausgeführt wurde.

Beide Skripte melden unter den Regel-IDs in der Tabelle unten. Verwenden Sie dieselben IDs in Ihrem Bericht.

Studieren Sie vor dem Gestalten

Modelle produzieren den Durchschnitt dessen, was sie gesehen haben, und der Durchschnitt ist das, was die Leute als generiert erkennen. Wenn Sie sich zuerst spezifische, veröffentlichte Arbeiten ansehen, erhalten Sie echte Entscheidungen, auf die Sie reagieren können.

1. Wählen Sie drei bis fünf Live-Seiten in derselben Kategorie wie das, was Sie bauen. Verwenden Sie diejenigen, die der Nutzer nennt. Finden Sie sie sonst mit einer Websuche oder mit einem Design-Referenz- oder Screenshot-Tool, das mit der Sitzung verbunden ist.
2. Führen Sie inspect.mjs auf jeder aus, mit --out, damit Sie die Screenshots öffnen und ansehen können.
3. Notieren Sie für jede die Schriftarten und die Schriftskala, wie viele Farben sie verwendet und wo der Akzent sitzt, die Zeilenlänge, die Abschnittsstruktur und die eine Sache, die sie erkennbar macht.
4. Lesen Sie die Komfort-Befunde für jede Referenz. Bewunderte Seiten liefern oft winzigen Text, schwachen Kontrast und heftige Bewegung. Entleihen Sie die Komposition und lassen Sie diese zurück. references/craft.md enthält die Tabelle.
5. Sagen Sie dem Nutzer, welche Seiten Sie studiert haben und was Sie von jeder mitgenommen haben. Entleihen Sie Struktur und Entscheidungen. Kopieren Sie niemals den Namen, das Logo, die Wortwahl, Bilder oder das genaue Layout einer Marke.

Wenn Sie keine Referenz öffnen können, sagen Sie es und gestalten Sie nach den Regeln und references/craft.md.

Evidenzgrade

Jede Regel trägt einen Grad. Wiederholen Sie den Grad, wenn Sie einen Befund erklären, damit niemand eine Gewohnheit für eine Tatsache hält.

Grad	Bedeutung
research	Unterstützt durch kontrollierte Studien oder systematische Übersichten
standard	Festgelegt durch ein WCAG 2.2-Erfolgskriterium. Die Referenzdatei gibt das Kriterium und dessen Niveau an
convention	Sinnvoll und weit verbreitet, aber ohne dahinterstehenden Versuch
inference	Abgeleitet aus Forschung zu einem verwandten Reiz, nicht an Webseiten getestet

Regeln

Der Schweregrad bestimmt die Reihenfolge: zuerst Fehler, dann Warnungen, dann Hinweise. Innerhalb eines Schweregrads arbeiten Sie die Tabelle von oben nach unten ab. Der angezeigte Schweregrad ist der übliche. Das Skript senkt ihn, wenn es nicht sagen kann, ob eine Zeile ein Problem ist (eine kleine Größe bei einem möglichen Label), und Sie können ihn erhöhen, wenn Ihre Überprüfung einen echten Schaden zeigt.

ID	Regel	Schweregrad	Grad	Referenz
type-rem-zoom	Text muss Zoom überleben. Größen in rem, keine Viewport-nur-Schriftgrößen, Zoom nie deaktiviert.	error	standard	typography
contrast-floor	Jedes Textpaar mindestens 4.5:1. Großer Text und UI-Teile mindestens 3:1.	error	standard	contrast-and-color
contrast-color-alone	Niemals Zustand allein mit Farbe signalisieren.	error	standard	contrast-and-color
motion-flash	Nichts blinkt mehr als dreimal pro Sekunde.	error	standard	motion
motion-autoplay	Kein Autoplay-Video ohne Steuerelemente. Alles, das sich länger als 5 s neben Text bewegt, braucht Pause. Keine Endlosschleifen neben Text.	error	standard	motion
motion-reduced	Bewegung existiert nur innerhalb von prefers-reduced-motion: no-preference.	error	standard	motion
theme-focus	Niemals den Fokus-Outline ohne einen sichtbaren Ersatz von mindestens 3:1 entfernen.	error	standard	theming
type-body-size	Fließtext 1rem Minimum, 1.125rem bis 1.25rem für langes Lesen. Nichts Lesbares unter 0.875rem.	warning	research	typography
motion-triggers	Kein Parallax, Scroll-Hijacking oder großflächiger Zoom. Ein- und Ausblendungen und Farbänderungen sind in Ordnung.	warning	research	motion
contrast-dark-secondary	Sekundärer Text auf dunklen Oberflächen bei 8.5:1 oder besser. AA allein liest sich dort schwach.	warning	inference	contrast-and-color
contrast-saturated-on-dark	Kein gesättigtes Rot oder Blau als kleiner Text auf Dunkel. Hellere, ruhigere Akzente in dunklen Designs.	warning	research	contrast-and-color
lum-section-steps	Keine abwechselnden vollflächigen dunklen und weißen Abschnitte. Keine weißen Einbettungen oder Modals in einem dunklen Design.	warning	inference	layout-and-patterns
lum-white-flash	Themed html-Hintergrund und eine color-scheme-Deklaration und ein Meta-Tag.	warning	convention	theming
layout-shift	Reservieren Sie Medienabmessungen, passen Sie Fallback-Schriftmetriken an, halten Sie CLS bei oder unter 0.1.	warning	research	layout-and-patterns
contrast-pure-extremes	Fast-Schwarz auf Fast-Weiß, Off-Weiß auf Dunkelgrau. Vermeiden Sie reines Schwarz und reines Weiß als Seiten-Text und -Hintergrund.	warning	convention	contrast-and-color
type-leading	Fließtext line-height 1.5 (1.4 bis 1.6). Überschriften 1.1 bis 1.3.	warning	convention	typography
type-weight	Fließtext-Gewicht 400 oder mehr. Keine 100 bis 300 bei Fließtext-Größen.	warning	convention	typography
type-align	text-align: start. Kein Blocksatz für Fließtext. Großbuchstaben nur für kurze Labels.	warning	standard	typography
layout-targets	Zeigerziele mindestens 24 x 24 CSS-Px, 44 x 44 für primäre Aktionen. Links innerhalb eines Satzes sind ausgenommen.	warning	standard	layout-and-patterns
theme-both-schemes	Helle und dunkle Designs ausliefern und prefers-color-scheme beachten. Ein manueller Umschalter ist optional und standardmäßig auf System eingestellt.	note	research	theming
pattern-stripes	Keine kontrastreichen Streifen oder Raster mit einer Periode von 7 bis 27 px über große Flächen.	note	inference	layout-and-patterns
type-measure	Lesetext auf 50ch bis 60ch begrenzt, das sind etwa 65 bis 78 Zeichen.	note	convention	typography
motion-duration	100 bis 300 ms, 500 ms Obergrenze, ease-out für Eintritte.	note	convention	motion
theme-preferences	Beachten Sie prefers-contrast, forced-colors und prefers-reduced-transparency.	note	convention	theming
pattern-clutter	Eine primäre Betonung pro Ansicht. Wenige Akzentfarben, -größen und -rahmenstile.	note	research	layout-and-patterns
craft-copy	Spezifischer Text. Nie Statistiken, Testimonials, Bewertungen oder Kundenlogos erfinden.	warning	convention	craft
craft-reference	Studieren Sie drei bis fünf echte Seiten in derselben Kategorie vor dem Gestalten. Entscheidungen ausleihen, nie kopieren.	note	convention	craft
craft-one-idea	Eine unverwechselbare Idee pro Ansicht. Alles andere bleibt ruhig.	note	convention	craft
craft-palette	Getönte Neutrale und ein Akzent. Keine Indigo- oder Lila-Verläufe, kein Gradiententext.	note	convention	craft
craft-show-product	Zeigen Sie die echte Oberfläche, Daten oder Code. Keine Reihe von drei identischen Icon-Karten, keine Emoji-Icons.	note	convention	craft
craft-layout	Nicht alles zentrieren. Ungleichmäßige Rasteraufteilungen und unterschiedliche Abschnittsstruktur.	note	convention	craft
craft-restraint	Flache Oberflächen und Haarstriche. Wenige Schatten, eine Radius-Skala, kein gestapeltes Weichzeichnen und Glühen.	note	convention	craft

Referenzdateien enthalten die Begründung, Quellen und Vorher/Nachher-Code. Lesen Sie jede, die eine Regel abdeckt, die Sie anwenden oder melden. Eine Korrektur über eine ganze Seite erfordert normalerweise drei oder vier von ihnen.

• references/contrast-and-color.md: Farbauswahl, Erstellen einer Palette oder eines dunklen Designs, Erklären eines Kontrastbefunds.
• references/typography.md: Schriftgröße, Zeilenlänge, Abstände, Schriftarten, fließende Schrift.
• references/motion.md: Animation, Übergänge, Video, Scrolleffekte, Ladebalken.
• references/layout-and-patterns.md: Tabellen, Raster, Streifen, Dichte, Abschnittshintergründe, Bilder, Layout-Verschiebung.
• references/theming.md: Helle und dunkle Designs, ein Themen-Umschalter, Fokus-Stile, Medienabfragen für Benutzereinstellungen, Tailwind und shadcn/ui.
• references/craft.md: Gestalten einer neuen Seite oder eines neuen Abschnitts, ein Ergebnis, das wie eine Vorlage oder generiert aussieht, was man von einer Referenzseite ausleihen und was man lassen sollte.
• references/evidence.md: Wenn der Nutzer nach dem Warum fragt, eine Regel hinterfragt oder nach Blaulicht, Dunkelmodus, Dyslexie-Schriftarten oder APCA fragt.

Standardwerte, die ohne Nachfrage geschrieben werden sollen

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

Fügen Sie <meta name="color-scheme" content="light dark"> in den Seitenkopf ein.

Fließtext misst 15.75:1 in hell und 15.30:1 in dunkel. Gedämpfter Text misst 6.25:1 und 9.39:1. Der Akzent misst 5.78:1 und 8.14:1, weshalb er für den Fokusring verwendet wird: Die Systemfarbe Highlight kann unter 3:1 auf einer dunklen Oberfläche fallen. assets/tokens.css enthält den vollständigen Satz, einschließlich Oberflächen, Ränder für Steuerelemente, eine Größe für langes Lesen und ein opt-in-Dim-Design.

Fügen Sie color-scheme: light dark nur hinzu, sobald die Seite wirklich Farben für beide Schemata hat. Auf einer Seite mit hartcodierten hellen Farben erzeugt es dunkle Scrollleisten und Formularsteuerelemente auf einer weißen Seite. Beheben Sie theme-both-schemes in derselben Änderung.

Tailwind und shadcn/ui liefern reines Weiß mit Fast-Schwarz (etwa 19.8:1) und bg-white / text-black als reine Werte. Überschreiben Sie --background und --foreground und verwenden Sie semantische Dienstprogramme wie bg-background und text-foreground.

Was das Skript nicht sehen kann

inspect.mjs deckt den ersten, dritten und fünften Punkt unten ab, wenn Sie es auf der gerenderten Seite ausführen können. Überprüfen Sie den Rest und alle davon, wenn es nicht ausgeführt werden konnte, indem Sie den Code oder die Seite lesen. Wenn Sie einen nicht überprüfen können, listen Sie ihn unter „Nicht verifiziert“ auf und sagen Sie warum.

• Kontrast jedes echten Text- und Hintergrundpaars, einschließlich Text über Bildern und Verläufen. Messen Sie Paare mit dem Befehl contrast
• Ob kleiner Text Fließtext oder ein kurzes Label ist
• Zeilenlänge im gerenderten Layout. Zählen Sie Zeichen in einigen vollen Zeilen
• Blinkrate von Animationen und Videos
• Helligkeitssprünge zwischen Abschnitten und weiße Einbettungen in dunklen Designs
• Layout-Verschiebung während des Ladens, einschließlich Bilder und Videos ohne width und height
• Ob Zustand allein durch Farbe getragen wird
• JavaScript-gesteuerte Animation, die reduzierte Bewegung ignoriert
• Größen, die in em, Prozentwerten oder der font-Kurzschreibweise gesetzt sind, und Streifen, die aus background-size gebaut sind

Berichtsvorlage

Easy on the Eyes – Prüfbericht
===============================

Seite: <URL oder Pfad>
Modus: <audit/inspect/fix>

Ergebnis: <bestanden/nicht bestanden/teilweise bestanden>

Fehler
------
- <ID>: <Beschreibung> (Evidenzgrad: <Grad>)

Warnungen
---------
- <ID>: <Beschreibung> (Evidenzgrad: <Grad>)

Hinweise
--------
- <ID>: <Beschreibung> (Evidenzgrad: <Grad>)

Nicht verifiziert
-----------------
- <Punkt>: <Grund>

Kommentare
----------
- <optional: zusätzliche Notizen>

---

Dieser Bericht wurde automatisch generiert. Überprüfen Sie die Punkte unter „Nicht verifiziert“ manuell.

Lizenz und Einschränkungen

Diese Fähigkeit wird unter der MIT-Lizenz bereitgestellt. Sie ist nicht als medizinisches Gerät oder als Ersatz für professionelle augenärztliche Beratung konzipiert. Verwenden Sie sie, um die Lesbarkeit und den Komfort von Web-Oberflächen zu verbessern, aber konsultieren Sie bei persönlichen gesundheitlichen Bedenken einen Augenarzt.

---

Für weitere Informationen siehe die Referenzdateien im references/-Verzeichnis.