Astro UI Patterns & Portable Component Library
Dieser Leitfaden definiert den standardisierten Katalog von portablen, einsatzbereiten UI-Komponenten für Astro-Websites.
Eigenständige Beispiele verwenden das Portable Component Model: Keine externen npm-Abhängigkeiten, keine Client-Framework-Laufzeiten (kein React/Vue), namensräumliche CSS-Tokens mit integrierten Fallbacks und progressive Verbesserung. In Framework-Projekten behalten Sie die semantischen und Interaktionsanforderungen bei, während Sie die Komposition und das Styling an den ausgewählten Vertrag anpassen. Überprüfen Sie die Barrierefreiheit im gerenderten Projekt; eine Vorlage allein stellt keine WCAG-Konformität her.
Verhaltensverträge und Framework-Komposition
Verwenden Sie für eine Komponente im folgenden Index deren semantischen und Interaktionsvertrag: Tastaturunterstützung, Fokusverwaltung, native Elemente, zugängliche Namen, Zustandsaktualisierungen und progressive Verbesserung. Der ausgewählte Projekt-/Framework-Vertrag regelt Styling, Tokens, Importe und Komponentenkomposition. Benutzeranweisungen bleiben maßgeblich.
Die Beispiele verwenden das folgende standalone portable component model. Verwenden Sie es, wenn Sie eine unabhängige Komponente ohne Framework-Kompositionsvertrag hinzufügen. Wenn ein Projekt eine etablierte Bibliothek hat, passen Sie das Verhalten an dessen geeignete Primitive an, anstatt dessen Schaltflächen, Überschriften oder Formularsteuerelemente zu duplizieren. Bewahren Sie die erforderliche Semantik und das Verhalten, während Sie die Wrapper und Klassen des Beispiels anpassen.
Für ein Projekt, das auf einem Component Framework (z. B. Lumos) basiert, verwenden Sie die Komposition und das Styling dieses Frameworks; dessen Primitive können importiert werden. Die eigenständige Zero-Site-Import-Regel und namensräumliche Fallback-Tokens überschreiben nicht den Vertrag eines ausgewählten Frameworks.
Das Portable Component Model
Verwenden Sie für eigenständige portable Komponenten diese fünf Regeln. Bei einem ausgewählten Framework bewahren Sie die Verhaltensanforderungen und folgen Sie dessen Kompositions-/Styling-Vertrag wie oben beschrieben:
- Keine Externen/Site-Importe: Die Komponentendatei darf KEINE Site-Layouts, Schaltflächen oder UI-Bibliotheken von Drittanbietern importieren. Die einzig katalogisierte Ausnahme ist SelfHostedMap, die einen Kartenrenderer und Tile-Reader benötigt; ihre Spezifikation listet die Pakete auf, und diese werden nur mit Zustimmung des Besitzers installiert.
- Namensräumliche CSS-Variablen mit Fallbacks: Verwenden Sie NIEMALS Host-Tokens (z. B.
var(--color-brand)) direkt im Komponenten-Stylesheet. Schreiben Sie immervar(--comp-property, <fallback>). - Scoped BEM & CSS Logical Properties: Verwenden Sie BEM-Klassennamen (
.c-theme-toggle,.c-accordion__summary) und logische Eigenschaften (inline-size,block-size,padding-inline,margin-block). - Idempotente Vanilla Progressive Enhancement: Skripte müssen beim Laden ausgeführt werden und sich sauber wieder anbinden, wenn Astro View Transitions aktiv sind (
document.addEventListener('astro:after-swap', init)). - Touch-Ziele & ARIA: Schaltflächen und interaktive Steuerelemente müssen mindestens
44px(2.75rem) oder48px(3rem) Touch-Ziele, korrekte ARIA-Zustände (aria-expanded,aria-selected,aria-pressed,aria-controls) und Tastatur-Fokusringe haben.
Komponenten-Index
| Komponente | Spezifikationsdatei | Zweck | Wichtiger Vertrag |
|---|---|---|---|
| 1. ThemeToggle | components/theme-toggle.md | Hell/Dunkel-Theme-Umschalter mit Zero FOUC und SVG-Morphing | <head> Inline-Skript + OKLCH-Token-Zuordnung |
| 2. MobileNavDrawer | components/mobile-nav-drawer.md | Barrierefreie Slide-Down-Navigationsklappe mit animiertem Hamburger | 48px Touch-Ziele, Escape-Taste schließt, kein GPU-Unschärfe-Lag |
| 3. SearchBar | components/search-bar.md | Clientseitiges Suchfeld mit Löschen-Button und Live-Ansager | rAF Entprellung (optimal INP), aria-live, benutzerdefinierter Event-Koordinator |
| 4. FilterChips | components/filter-chips.md | Mehrkategorie-Pillenfilterleiste mit zugänglichen gedrückten Zuständen | role="group", aria-pressed, benutzerdefinierter Event-Koordinator |
| 5. SearchFilterBar | components/search-filter-bar.md | Zusammengesetztes Muster aus SearchBar und FilterChips | Vorkomponierte gestapelte Toolbar, mehrspaltige Flex-Layouts, gemeinsamer Geltungsbereich |
| 6. AccessibleModal | components/accessible-modal.md | Barrierefreier Dialog-Overlay mit nativem HTML5 <dialog> | Native Top-Layer, Klick auf Hintergrund, Escape-Taste, Fokuswiederherstellung |
| 7. AccessibleAccordion | components/accessible-accordion.md | Natives FAQ/Akkordeon mit sanfter CSS-Grid-Erweiterung | Natives <details name="...">, 0 KB JavaScript |
| 8. AccessibleTabs | components/accessible-tabs.md | WAI-ARIA Tab-Umschalter für Preisstufen oder Multi-Panel-Ansichten | Tastatur-Navigation mit Pfeiltasten (Links/Rechts/Pos1/Ende) |
| 9. SocialShare | components/social-share.md | Datenschutzorientierte Social-Sharing-Leiste mit Web Share API | 100 % DSGVO-sicher, 0 Tracker, statische Intent-URLs |
| 10. TableOfContents | components/table-of-contents.md | Inhaltsverzeichnis für lange Artikel mit Scrollspy | IntersectionObserver-Überschriftenverfolgung, paart sich mit einem Artikellayout |
| 11. AccessibleCarousel | components/accessible-carousel.md | Native CSS-Scroll-Snap-Slider für Bewertungen, Karten oder Logos | Natives Touch-Wischen (0 KB JS), zugängliche Zurück-/Weiter-Schaltflächen |
| 12. InfiniteTicker | components/infinite-ticker.md | Reines CSS-Endlos-Logo/Text-Laufband mit Pause bei Hover/Fokus | WCAG 2.2.2-konform, doppelte Spur mit aria-hidden versteckt |
| 13. StatsCounter | components/stats-counter.md | HTML-zuerst-Metrikenzählerleiste mit Ease-Out-Scroll-Animation | 0 CLS, statisches HTML-Fallback, IntersectionObserver |
| 14. AddToCalendar | components/add-to-calendar.md | "Save the Date"-Link zu einer Build-Zeit-iCalendar-Datei | Gleichherkunft-statisches .ics + <a download>, gültig nach RFC 5545, 0 KB JS |
| 15. SelfHostedMap | components/self-hosted-map.md | Karte der Orte einer Liste aus einem selbst gehosteten PMTiles-Extrakt; nummerierte Pins entsprechen der Liste | Lazy MapLibre, HTTP 206 Tile-Route, aria-hidden Karte mit Textäquivalenten, folgt dem Theme. Benötigt npm-Pakete (Zustimmung des Besitzers) |
| 16. ClickableParent | components/clickable-parent.md | Ganze Karte/Zeile durch einen echten Link oder Button anklickbar | ::after gestreckter Trefferbereich, sekundäre Steuerelemente angehoben, Fokusring auf dem Container, 0 KB JS |
| 17. Card | components/card.md | Inhaltskarte mit Medien, Metadaten, Text und sekundären Aktionen | Überschrift-zuerst-DOM, headingLevel-Prop, Container-Query-Layout, ClickableParent-Vertrag wenn verlinkt |
Entscheidungsgate für nicht katalogisierte Komponenten (Menschlicher Entscheidungspunkt)
Wenn eine Projektanforderung oder ein Design eine interaktive UI-Komponente erfordert, die keine der 17 oben katalogisierten Komponenten ist (z. B. ein Vorher/Nachher-Bildvergleichsregler, Datumsauswahl, Bereichsauswahl, Schrittassistent oder benutzerdefinierter Media-Player):
[!IMPORTANT] STOPPEN UND FRAGEN: Der Agent darf NIEMALS stillschweigend Client-Framework-Bibliotheken (React, Vue, Svelte) installieren, ungeprüfte npm-Pakete von Drittanbietern importieren oder temporäre Textplatzhalter-Blöcke (z. B.
<div class="c-placeholder">) hinterlassen.Der Agent MUSS innehalten und dem Projektbesitzer drei verschiedene Optionen präsentieren:
- Option A: Benutzerdefinierte Vanilla-Komponente (Empfohlen): Erstellen Sie eine maßgeschneiderte, abhängigkeitsfreie
.astro-Komponente, die dem unten stehenden Bespoke Component Fallback Contract entspricht.- Option B: Statisches HTML-Baseline: Implementieren Sie ein rein statisches semantisches Layout (z. B. nebeneinanderliegende Bilder oder standardmäßig gestapelte Karten) mit 0 KB JavaScript und verzichten Sie vollständig auf die interaktive Erweiterung.
- Option C: Anpassung des Katalogmusters: Bewerten Sie, ob ein vorhandenes Katalogmuster die Anforderung erfüllen kann (z. B. Anpassung von
AccessibleModalin eine Bild-Lightbox oderAccessibleTabsin eine gestufte Panel-Ansicht).
Der Bespoke Component Fallback Contract
Wenn der Projektbesitzer die Erstellung einer nicht katalogisierten Komponente genehmigt (Option A), muss die Implementierung diese sechs Regeln erfüllen; für Framework-Anpassungen verwenden Sie die Komposition, Klassennamen und Token-Regeln des Frameworks für die Punkte 3–4:
- Semantisches HTML zuerst: Verankern Sie die Schnittstelle in standardmäßigen HTML-Elementen, bevor Sie JavaScript schreiben (z. B.
<input type="range">für Schieberegler,<details>für Offenlegung,<dialog>für Overlays). - Keine externen Laufzeitabhängigkeiten: Keine Client-Framework-Laufzeiten (kein React/Vue) und keine UI-Widget-Pakete von Drittanbietern. Schreiben Sie nur einfaches Vanilla TypeScript/JavaScript, wenn Browser-Interaktion wirklich erforderlich ist.
- Scoped BEM & CSS Logical Properties: Verwenden Sie standardmäßige BEM-Benennung (
.c-block,.c-block__element) und flussrelative Layouteigenschaften (inline-size,block-size,padding-block,margin-inline,inset). - Namensräumliche Tokens mit Fallbacks: Verwenden Sie NIEMALS feste Hex-Werte. Verwenden Sie semantische Host-Tokens oder namensräumliche benutzerdefinierte Eigenschaften mit sinnvollen Fallbacks (
var(--comp-color, var(--color-primary))). - No-JS Progressive Enhancement: Die Komponente muss lesbar, zugänglich und bedienbar bleiben, wenn clientseitiges JavaScript deaktiviert ist. Verwenden Sie
@media (scripting: none)oder native CSS-Fallback-Layouts (z. B. nebeneinanderliegende oder gestapelte Ansichten), damit keine Inhalte verborgen werden. - WCAG 2.2 AA Konformität: Halten Sie mindestens
44px(2.75rem) Touch-Ziele, kontrastreiche sichtbare:focus-visible-Ringe, klare zugängliche Namen (aria-label,<label>) ein und stellen Sie 0 axe-core-Verstöße sicher.
Selektive Ladeanleitung für Agenten
Wenn der Benutzer bittet, eine der oben genannten Komponenten zu implementieren oder zu bearbeiten, lesen Sie nicht den gesamten Katalog. Lesen Sie stattdessen nur die spezifische Komponentendatei, die benötigt wird (z. B. components/accessible-carousel.md).
Integrationsüberprüfung
Überprüfen Sie die ausgewählte Spezifikation an der erstellten/bereitgestellten Ausgabe: Semantik und Namen, Tastatur-/Fokusverhalten, Zustandsübergänge, No-JS-Behandlung, wiederholte Initialisierung und Host-Token-Zuordnung. Die Regeln für eigenständige Pakete gelten nur für eigenständige Komponenten; Frameworks verwenden ihre Primitive wieder. Führen Sie die konfigurierten Check/Build/Tests des Projekts aus und legen Sie nicht verfügbare Checks oder Abdeckungslücken offen. 44px ist die Target-Size-Konvention dieser Bibliothek, nicht der WCAG-AA-Schwellenwert selbst.
Native Auswahl-Popups bleiben Browser-/BS-UI, es sei denn, der Besitzer genehmigt die Abwägungen eines benutzerdefinierten Combobox.