Communitygithub.com

Xipher-Labs/walter-os

Durchsetzung der Frontend-Qualitätsstandards – Barrierefreiheit (WCAG 2.2 AA), Performance (Core Web Vitals: LCP/INP/CLS), semantisches HTML, Bildoptimierung, Bundle-Größe, Mobile-First-Ansatz sowie Lade-, Leer- und Fehlerzustände.

Was ist walter-os?

Diese AI-Agenten-Fertigkeit stellt sicher, dass jede Benutzeroberfläche im Web die strengen Frontend-Qualitätskriterien erfüllt. Sie umfasst die automatische Überprüfung von Pull Requests (PRs) auf Barrierefreiheit (WCAG 2.2 AA), Performance (Core Web Vitals: LCP, INP, CLS), semantisches HTML, Bildoptimierung, Bundle-Größe, Mobile-First-Design sowie die Handhabung von Lade-, Leer- und Fehlerzuständen. Die Fertigkeit wird automatisch bei Änderungen an Dateien wie `*.tsx`, `*.jsx`, `*.svelte`, `*.vue`, `*.astro` oder `*.css` aktiviert. Sie ist besonders wichtig für Projekte mit Nutzern in Argentinien, die oft über langsame 3G/4G-Netzwerke auf das Web zugreifen, sowie für die Entwickler-Dokumentationsseite des Unternehmens, die schnelle Ladezeiten erfordert. Die Fertigkeit nutzt ein modulares Routing-System, um bei Bedarf auf ein bevorzugtes Sprachmodell (z.B. Claude) zurückzugreifen, und bietet detaillierte Anleitungen zur Umsetzung von Barrierefreiheit (z.B. Tastaturnavigation, semantische HTML-Strukturen, ausreichende Kontraste) sowie Performance-Optimierung (z.B. kürzeste Ladezeiten, flüssige Interaktionen, visuelle Stabilität).

Funktioniert mit✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/Xipher-Labs/walter-os/tree/HEAD/skills/frontend-quality

In Ihrer bevorzugten KI fragen

Öffnet einen neuen Chat, in dem dieser Agent-Skill bereits geladen ist.

Dokumentation

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 Sie outline: none nicht 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>. Das for-Attribut stimmt mit der id ü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" oder required).
  • 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/react im 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: swap oder 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.
  • dangerouslySetInnerHTML mit großen Zeichenfolgen vermeiden – Parsing blockiert.
  • useMemo/memo nur 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-adjust verwenden, um Metriken anzupassen, ODER font-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-analyzer oder next-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' nicht import 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:

  1. Laden – Skelett oder Ladeanimation. KEIN leerer Bildschirm. KEINE Layoutverschiebung.
  2. Leer – Erster Zustand ohne Daten. Mit CTA zum Befüllen.
  3. Fehler – Klare Nachricht, Wiederholen-Schaltfläche, kein Stacktrace für den Benutzer. In Sentry protokolliert.
  4. Teilweise / veraltet – Wenn Daten aus dem Cache oder von einem teilweisen Abruf stammen.
  5. 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/cli oder 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.
  • unlighthouse für vollständige Site-Überprüfung.
  • @unjs/check-vitals fü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-motion respektiert. 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

Individual skills in this repo

This repo contains 1 individual skill — each has its own dedicated page.

Verwandte Skills