Frontend-Qualität
Qualitätsmaßstab für jede benutzerseitige Weboberfläche. Harte Anforderungen (Barrierefreiheit, Leistung, Mobile-First), keine stilistischen Vorlieben. Reviews erkennen die Fehler, die echten Benutzern wichtig sind – langsame Seiten, defekte Tastaturnavigation, Layouts, die sich beim Laden verschieben.
Modell-Routing
Verwenden Sie die Frontend-Präferenz des Operators, wenn ein Modell UI, UX, visuelle Hierarchie, Barrierefreiheitskopien oder Interaktionsdetails kritisieren oder umschreiben soll:
source "$WALTER_OS_HOME/scripts/walter/lib/model-router.sh"
frontend_model=""
walter_model_resolve frontend frontend_model
Standardpräferenz ist Claude. Der Operator kann den Alias auf eine andere LiteLLM-Route in ~/.config/walter-os/overlay/personal.env umleiten.
Diese Fähigkeit wird automatisch bei Diffs ausgelöst, die das Frontend betreffen. Für eine Landing Page, die von Grund auf neu erstellt wird, verwenden Sie landing-page-fast (enthält diese Regeln, bietet aber ein Grundgerüst).
Warum dies für diesen Operator besonders wichtig ist
- [Projekt A]-Nutzer sind argentinische KMU-Lieferanten – viele nutzen Handys, oft mit 3G/4G und zeitweiliger Verbindung. Langsame Website = Nutzer gehen. WCAG ist wichtig, weil einige Nutzer eine geringe Technikkompetenz und Sehbehinderungen haben.
- [Projekt B]-Nutzer umfassen Patienten mit Behinderungen. WCAG ist kein "nice-to-have", sondern eine Benutzerfreundlichkeitsanforderung.
- [Firma]-Dokumentation wird von anspruchsvollen Entwicklern gelesen, die bei langsamen oder defekten Tastaturseiten sofort abspringen.
Barrierefreiheit (WCAG 2.2 AA – erforderlich)
Tastatur
- Jedes interaktive Element ist mit der Tabulatortaste erreichbar. Schaltflächen, Links, Formularfelder, benutzerdefinierte Steuerelemente. Führen Sie einen manuellen Tabulatortest durch; wenn ein Steuerelement übersprungen wird, BLOCKER.
- Fokus sichtbar. Die
:focus-visible-Umrandung muss klar erkennbar sein. Setzen Sieoutline: nonenicht ohne Alternative. - Logische Tabulatorreihenfolge. Die Lesereihenfolge entspricht der DOM-Reihenfolge; vermeiden Sie
tabindex-Werte >0 (sie unterbrechen den natürlichen Fluss). - Skip-Link. Das erste fokussierbare Element auf jeder Seite ist "Zum Hauptinhalt springen".
- Escape schließt Modals. Fokus innerhalb des Modals bis zum Schließen einfangen.
Semantisches HTML
<button>für Aktionen,<a>für Navigation. Niemals<div onClick>für beides.- Überschriften hierarchisch: eine
<h1>pro Seite;<h2>...<h6>überspringen keine Ebenen. - Orientierungspunkte:
<header>,<nav>,<main>,<footer>. ARIA-Rollen nur, wenn kein semantisches Element passt. - Listen sind
<ul>/<ol>. Keine Listen mit<div>vortäuschen. - Formularsteuerelemente haben
<label>. Dasfor-Attribut stimmt mit deridüberein.
Farbe und Kontrast
- WCAG-AA-Kontrastminimum: 4,5:1 für Fließtext, 3:1 für großen Text (18pt+ oder 14pt+ fett), 3:1 für UI-Komponenten und Grafiken.
- Farbe ist nicht der einzige Indikator: Fehlerzustände zeigen Symbol + Text + Farbe, nicht nur roten Rand.
- Getestet mit simulierte Farbschwäche. Verwenden Sie Stark, axe DevTools oder die Farbsehsimulatoren der Browser-Entwicklertools.
Formulare
- Jede Eingabe hat ein sichtbares Label. Platzhalter ist KEIN Label.
- Fehlermeldungen sind programmatisch verknüpft über
aria-describedby. - Pflichtfelder markiert. Sowohl visuell (
*oder "erforderlich") als auch programmatisch (aria-required="true"oderrequired). - Validierungsfehler verschwinden nicht bei Fokus. Bleiben bestehen, bis korrigiert oder verworfen.
- Erfolgszustände bestätigt. Nach dem Absenden wissen Screenreader-Benutzer, dass es funktioniert hat.
Bilder und Medien
alt-Attribut auf jedem<img>. Leer (alt="") für dekorative; beschreibend für Inhalt. KI-generierte Bilder: Beschreiben Sie, was tatsächlich im Bild ist, nicht den Prompt.- Untertitel/Transkripte für Video/Audio.
- Kein Autoplay mit Ton.
- Animationen respektieren
prefers-reduced-motion:@media (prefers-reduced-motion: reduce) { *, *::before, *::after { animation-duration: 0.01ms !important; transition-duration: 0.01ms !important; } }
Tooling
@axe-core/reactim Entwicklungsmodus – protokolliert a11y-Probleme in der Konsole.eslint-plugin-jsx-a11y– erkennt Probleme zur Buildzeit.- Manueller Screenreader-Test vor dem Start: VoiceOver (Mac), NVDA (Windows), TalkBack (Android).
- Lighthouse a11y-Score ≥ 95 in CI.
Leistung – Core Web Vitals
Die 3 Metriken, nach denen Google bewertet. BESTEHEN SIE ALLE DREI, um als "Gut" zu gelten:
LCP (Largest Contentful Paint) – Ladegeschwindigkeit
Ziel: < 2,5 s bei 3G. Realweltlich für [Projekt A] aggressiver, da argentinische Mobilfunknetze langsamer als der Median sind.
Wie:
- Das LCP-Bild vorladen:
<link rel="preload" as="image" href="...">. - Keine renderblockierenden Ressourcen: Nicht kritisches JS aufschieben, kritisches CSS einbetten.
- Schriftarten selbst hosten mit
font-display: swapoder Systemschriftstapel verwenden. - CDN für statische Assets: Vercel, Cloudflare R2, Bunny.net.
- HTTP/2 oder HTTP/3: Standard bei Vercel/Cloudflare.
- Bilder komprimieren: WebP/AVIF, an Viewport angepasst.
- Das Hero-Bild speziell optimieren: Es ist fast immer LCP.
INP (Interaction to Next Paint) – Reaktionsfähigkeit
Ziel: < 200 ms p75. Ersetzte FID im Jahr 2024.
Wie:
- Keine langen Tasks > 50 ms auf dem Hauptthread während der Interaktion.
- Hydratation aufschieben (Astro Islands, Next.js Streaming, Qwik).
- Web Worker für schwere Berechnungen.
- Eingabehandler entprellen/drosseln.
dangerouslySetInnerHTMLmit großen Zeichenfolgen vermeiden – Parsing blockiert.useMemo/memonur wo gemessen, nicht präventiv.
CLS (Cumulative Layout Shift) – visuelle Stabilität
Ziel: < 0,1.
Wie:
- Bild- und Video-Tags haben
width+height(Browser reserviert Platz). - Platz für Anzeigen/Einbettungen reservieren mit min-height.
- Keine Inhalte oberhalb vorhandener Inhalte einfügen: Benachrichtigungsbanner unterhalb des Falzes platzieren oder mittels Transform nach unten schieben, nicht durch Einfügen im DOM darüber.
- Web-Schriftarten:
font-display: swap+size-adjustverwenden, um Metriken anzupassen, ODERfont-display: optional, wenn möglich. - Skelettbildschirme, die an echte Inhalte angepasst sind.
Bundle-Größe
- Anfängliches JS-Budget: < 150 KB gzipped für Landing Pages, < 250 KB für App-Shells.
- Code-Splitting nach Route (Next.js, Astro, SvelteKit machen dies standardmäßig).
- Dynamische Importe für schwere, nicht kritische Abhängigkeiten (Diagramme, Editoren).
- Abhängigkeiten prüfen:
bundle-analyzerodernext-bundle-analyzer. Entfernen Sie die 10 MB UI-Bibliothek, aus der Sie eine Komponente importiert haben. - Tree-Shaking funktioniert: Nur das importieren, was Sie benötigen (
import { thing } from 'lib'nichtimport lib from 'lib').
Lademuster
- Preconnect zu erforderlichen Ursprüngen:
<link rel="preconnect" href="...">. - Prefetch für wahrscheinlich nächste Seiten bei Hover/Fokus (Next.js macht dies).
- Lazy-Load für Bilder unterhalb des Falzes:
loading="lazy". - Lazy-Load für Iframes:
loading="lazy". - Service Worker für Offline-First (wo sinnvoll – [Projekt A] profitiert, Marketingseiten nicht).
Zustände – jede Komponente behandelt alle fünf
Für jede datengesteuerte UI: BLOCKER, wenn ein Zustand nicht behandelt wird:
- Laden – Skelett oder Ladeanimation. KEIN leerer Bildschirm. KEINE Layoutverschiebung.
- Leer – Erster Zustand ohne Daten. Mit CTA zum Befüllen.
- Fehler – Klare Nachricht, Wiederholen-Schaltfläche, kein Stacktrace für den Benutzer. In Sentry protokolliert.
- Teilweise / veraltet – Wenn Daten aus dem Cache oder von einem teilweisen Abruf stammen.
- Erfolg – der glückliche Pfad.
Beispiel für eine Liste:
if (isLoading) return <ListSkeleton />
if (error) return <ErrorState onRetry={refetch} />
if (data.length === 0) return <EmptyState cta={...} />
return <List items={data} />
Wenn Ihre Komponente nur den Erfolgszustand zeigt, den Sie im Diff sehen, fragen Sie: Wo sind die anderen 4?
Mobile-First
- Zuerst für 360px Breite entwerfen, dann hochskalieren.
- Touch-Ziele ≥ 44×44 px (Apple HIG) oder 48×48 px (Material).
- Keine Hover-Only-Interaktionen: Alles, was bei Hover verfügbar ist, hat auch einen Fokus-/Touch-Pfad.
- Auf echtem Gerät oder mit gedrosselten Chrome DevTools testen: 3G-Netz, 4-fache CPU-Verlangsamung.
- Formulare funktionieren ohne Zoom: Eingabe
font-size: 16px+(sonst zoomt iOS bei Fokus).
Tooling-Referenz
CI / vor dem Merge:
- Lighthouse CI mit Budgets pro Metrik.
@axe-core/clioder Lighthouse a11y-Teilmenge.bundlewatch, um PRs abzulehnen, die das Bundle über das Budget hinaus vergrößern.- Visuelle Regression: Chromatic (Storybook), Percy oder Playwright-Screenshots, die geprüft werden.
Lokal:
- Chrome DevTools Leistungs- und Lighthouse-Panels.
unlighthousefür vollständige Site-Überprüfung.@unjs/check-vitalsfür einmalige Web Vitals.
Ausgabeformat
**[BLOCKING|WARN|NIT] [FE-N] <einzeilig>**
Wo: `path/to/Component.tsx:42-58`
Kategorie: <a11y | perf | states | mobile | semantic>
Auswirkung: <welcher Nutzer / welches Szenario / welche Metrik>
Fix: <spezifische Änderung, Code, falls passend>
Verifizieren: <wie bestätigen – Lighthouse-Lauf / manueller Test / etc.>
Schweregrad:
- BLOCKING: WCAG-AA-Verstoß, unterbrochener Kernablauf, Web Vitals im "schlechten" Bereich. Muss behoben werden.
- WARN: Best-Practice-Lücke, Leistungsregression, die noch nicht benutzersichtbar ist.
- NIT: Verbesserungsmöglichkeit (kleineres Bundle, besseres Skelett).
Harte Regeln
- Kein
<div onClick>für Schaltflächen. Immer. - Keine Bilder ohne
alt. Immer. - Keine Layoutverschiebung durch echte Inhalte. Platz immer reservieren.
- Kein Autoplay mit Ton. Immer.
prefers-reduced-motionrespektiert. Immer.
Was diese Fähigkeit NICHT abdeckt
- Backend (verwenden Sie
web-security-baseline). - DB-Schema/Queries (verwenden Sie
data-migration-safety). - Markenidentität/visuelles Design (verwenden Sie
brand-creation). - Neue Landing-Page-Konstruktion (verwenden Sie
landing-page-fast, das ein Grundgerüst bereitstellt).
Referenzen
- WCAG 2.2 Kurzreferenz
- web.dev Core Web Vitals Dokumentation
- web.dev Leistungslernpfad
- Inklusive Komponenten von Heydon Pickering
- Die A11y-Projekt-Checkliste