coastdigitalgroup/coastai-skills

Toggle- und Switch-Designsystem

Zweck

Das Toggle- und Switch-Designsystem bietet ein standardisiertes Framework für die Gestaltung, Positionierung und Implementierung binärer Zustandssteuerungen in Web-Oberflächen. Toggle-Switche repräsentieren physische Ein-/Aus-Schalter, die sofort einen Zustandswechsel auslösen, ohne dass ein manueller Formular-Submit-Schritt (z. B. „Speichern“-Klick) erforderlich ist.

Ohne ein dediziertes Designsystem für Schalter werden Switche in Schnittstellen häufig anstelle von Kontrollkästchen verwendet, verletzen WCAG-Kontrastanforderungen in deaktivierten oder inaktiven Zuständen, haben keine klaren Zustandsbeschriftungen, schaffen zu kleine Touch-Ziele für mobile Bildschirme oder lösen unerwartete Layout-Verschiebungen und Hintergrundnebenwirkungen ohne sofortige visuelle Rückmeldung aus.

Dieses System legt Regeln für Schaltergeometrie, Track- und Thumb-Proportionen, Label-Ausrichtung, Zustandsfarbzuordnung, Tastaturzugänglichkeit (role="switch"), Touch-Hit-Bereichserweiterung, responsive Listenlayouts und asynchrone Ladezustände fest.

Anwendungsfälle

• Anwendungseinstellungen und Präferenzen: Umschalten sofortiger Systempräferenzen (z. B. „Push-Benachrichtigungen“, „Dunkles Design“, „Entwürfe automatisch speichern“ oder „Zwei-Faktor-Authentifizierung“).
• Abonnement- und Abrechnungszeitraumauswahl: Umschalten zwischen monatlichen und jährlichen Abrechnungszyklen in Preisübersichten mit integrierten Rabattabzeichen.
• Datenzeilen-Steuerung: Aktivieren oder Deaktivieren einzelner Benutzerzugriffe, API-Integrationen, Webhooks oder automatisierter Regeln direkt in Datenzeilen.
• Feature-Flags und Systemmodus-Schalter: Umschalten von Betriebszuständen in Entwickler-Dashboards (z. B. „Wartungsmodus“, „Debug-Logging“ oder „Beta-Funktionen“).
• Datenschutz- und Cookie-Einwilligungsbereiche: Verwalten granularer Tracking-Berechtigungen (z. B. „Analyse-Cookies“, „Marketing-Cookies“) in ausfahrbaren Drawern oder modalen Dialogen.

Wann NICHT verwenden

• Mehrfachauswahl: Für die Auswahl zwischen 3 oder mehr sich gegenseitig ausschließenden Optionen verwenden Sie segmented-control-system oder custom-select-and-combobox-system.
• Formularübermittlungen mit expliziter Bestätigung: Für Zustimmungsbedingungen (z. B. „Ich akzeptiere die Allgemeinen Geschäftsbedingungen“) innerhalb eines Standard-Mehrfeld-Formulars, das einen „Senden“-Button erfordert, verwenden Sie Standard-Kontrollkästchen (form-design-system).
• Binäre Auswahl ohne sofortige Wirkung: Wenn die Betätigung des Steuerelements erst nach einem sekundären „Übernehmen“- oder „Änderungen speichern“-Button wirksam wird, verwenden Sie ein Kontrollkästchen anstelle eines Schalters.
• Mehrfachauswahl in Tabellen: Verwenden Sie für die Auswahl mehrerer Elemente für Batch-Operationen (z. B. „Ausgewählte löschen“) Kontrollkästchen (data-table-ui-system).

Eingaben

1. Zustandsdefinition: Binäre Zustandsparameter (Aus / Deaktiviert / false vs. Ein / Aktiviert / true).
2. Kontext und Ausführungsmodus: Sofortige clientseitige Zustandsänderung (z. B. Dunkeldesign-Schalter) vs. Asynchroner serverseitiger Seiteneffekt (z. B. API-Webhook aktivieren/deaktivieren).
3. Beschriftungsstruktur: Inline-Text, unterstützender Beschreibungs-/Hilfetext und Anforderung eines Statusabzeichens.
4. Layout-Kontext: Eigenständige Einstellungskarte, dichte Tabellenzeile, Multi-Item-Präferenzgruppe oder Preisauswahl in Heldenbereichen.
5. Design und Token-Palette: Oberflächenfarben, aktive Track-Farbe, inaktive Track-Farbe, Daumenfarbe und Fokusring-Offset-Token.

Ausgaben

1. Schaltergeometrie und Token-Spezifikation: Räumliche Abmessungen für Track-Breite, -Höhe, Daumendurchmesser, Eckradius und Übergangszeiten (width: 44px, height: 24px, thumb: 20px).
2. Zustands- und Kontrast-Blaupause: Paletten-Token, die einen minimalen WCAG-3:1-Grafikkontrast für Tracks und Daumen in den Zuständen Standard (Aus), Aktiv (Ein), Hover, Focus-Visible, Deaktiviert und Ausstehend gewährleisten.
3. Strukturelle Layout- und Typografie-Spezifikation: Abstandsbeziehungen zwischen Schalterelement, primärer Beschriftung (h4/span), Beschreibungstext und optionalen Statusindikatoren (EIN/AUS).
4. Barrierefreiheit und ARIA-Zuordnung: Semantisches HTML <button role="switch" aria-checked="true|false"> mit Screenreader-Label-Association (aria-labelledby / aria-describedby).
5. Asynchrones Behandlungshandbuch: Spezifikation des visuellen Ladezustands (Spinner-Daumen oder reduzierte Track-Transparenz) für Hintergrundnetzwerküberprüfungen.

---

Workflow

1. Steuerungssemantik bestimmen (Switch vs. Checkbox)

Vor dem visuellen Design bestätigen, dass die Interaktionsabsicht dem mentalen Modell eines physischen Schalters entspricht:

• Sofortige Wirkung: Das Umschalten des Schalters wirkt sich sofort aus (oder löst eine sofortige Hintergrundanfrage aus).
• Eigenständige Aktion: Funktioniert unabhängig, ohne dass ein expliziter „Speichern“- oder „Senden“-Bestätigungsbutton erforderlich ist.
• Ein/Aus-Zustandsmetapher: Stellt das Ein- oder Ausschalten einer Funktion oder eines Status dar, nicht die Auswahl in einem Mehrfachfragebogen.

2. Räumliche Geometrie und Touch-Ränder festlegen

Entwerfen Sie Schalterkomponenten mit Proportionen, die den mobilen Touch-Richtlinien entsprechen und gleichzeitig die visuelle Harmonie auf dem Desktop wahren:

[   INAKTIVER / AUS TRACK   ]          [    AKTIVER / EIN TRACK    ]
+---------------------------+          +---------------------------+
|  (Daumen)                 |  ----->  |                  (Daumen) |
|   20px                    |          |                   20px    |
+---------------------------+          +---------------------------+
<-------- 44px ------------->          <-------- 44px ------------->
           24px Höhe                                   24px Höhe

• Standard-Schaltermaßstab:
  • Track-Breite: 44px (oder 2.75rem)
  • Track-Höhe: 24px (oder 1.5rem)
  • Track-Randradius: 999px (Volle Pillenform)
  • Daumen-Durchmesser: 20px (lässt einen 2px inneren Track-Einzug auf allen Seiten)
  • Daumen-Randradius: 50% (Kreis)
• Kompakter / dichter Schaltermaßstab (Tabellenzeilen):
  • Track-Breite: 36px
  • Track-Höhe: 20px
  • Daumen-Durchmesser: 16px (mit 2px Einzug)
• Touch-Ziel-Bereich:
  • Die interaktive Trefferzone MUSS auf mindestens 44x44px auf mobilen Geräten erweitert werden, indem Pseudo-Elemente (::before / ::after) oder Padding verwendet werden, um Fehlklicks auf Touchscreens zu vermeiden.

3. Zustandsfarbe-Token und Kontrastmetriken definieren

Um die WCAG 2.1 / 2.2 AA-Anforderungen für Nicht-Text-Kontrast (SC 1.4.11 - 3:1 Mindestkontrast) zu erfüllen, befolgen Sie strenge Farbtoken-Paare:

• Inaktiver / Aus-Zustand:
  • Track-Hintergrund: Neutrale graue Oberfläche (#E2E8F0 / Dark Mode: #334155).
  • Track-Rand: 1px Rand (#CBD5E1 / Dark Mode: #475569), um 3:1-Kontrast gegen helle Hintergrundoberflächen zu gewährleisten.
  • Daumenfarbe: Reines Weiß oder helle Oberfläche (#FFFFFF / Dark Mode: #F8FAFC).
  • Optionales Symbol im Daumen: Mond/Sonne oder Kreuz/Haken-Symbol (12px) für doppeltes visuelles Feedback.
• Aktiver / Ein-Zustand:
  • Track-Hintergrund: Hochkontrast-Marken- oder System-Aktionsfarbe (#2563EB Primärblau oder #16A34A Erfolgsgrün). Das Kontrastverhältnis zur Hintergrundseitenoberfläche muss 3:1 überschreiten.
  • Track-Rand: Transparent oder passender aktiver Rand.
  • Daumenfarbe: Reines Weiß (#FFFFFF) mit glattem CSS-Übergang (transform: translateX(20px) über 200ms cubic-bezier(0.4, 0, 0.2, 1)).
• Hover- und Fokus-Zustände:
  • Hover: Leichte Helligkeitsverschiebung des Tracks (+5% oder -5%) oder Vergrößerung des Daumenschattens (box-shadow: 0 0 0 4px rgba(37, 99, 235, 0.15)).
  • Focus-Visible: Deutlicher 2px versetzter Fokusring (outline: 2px solid #2563EB; outline-offset: 2px).
• Deaktivierter Zustand:
  • Track- & Daumen-Transparenz: Reduziert auf 0.5 oder 0.4 mit cursor: not-allowed.

4. Label-Ausrichtung und Beschreibungshierarchie anordnen

Schalter sollten immer von klaren Textbeschriftungen begleitet werden. Präsentieren Sie niemals einen isolierten Schalter ohne zugängliche Beschriftung oder sichtbaren Kontext.

• Horizontales Zeilenlayout (Standard-Präferenzkarte):
  • Platzieren Sie den Textblock links (Titel + Beschreibung) und den Schalter rechts.
  • Richten Sie die vertikale Mitte der Schalterspur an der ersten Zeile des Titels aus (nicht zentriert über mehrzeiligen Beschreibungen).
  • Halten Sie einen Mindestabstand von 16px zwischen Titeltext und Schalterelement ein.
• Formular-Inline-Layout:
  • Platzieren Sie den Schalter links und den Beschriftungstext rechts (gap: 12px), empfohlen, wenn Schalter in dichte Formularfelder integriert sind.
• Preisstufen-Toggle-Layout:
  • Zentrieren Sie den Schalter horizontal zwischen zwei expliziten Beschriftungsoptionen (z. B. „Monatlich“ — [ Schalter ] — „Jährlich (20% sparen)“). Das Klicken auf eine der beiden Textbeschriftungen oder den Schalter schaltet den aktiven Zustand um.

5. Asynchrone Seiteneffekte und Ladezustände handhaben

Wenn ein Schalter einen asynchronen API-Aufruf auslöst (z. B. Ändern einer Cloud-Ressourceneinstellung oder Aktivieren einer Integration):

1. Optimistischer visueller Zustand: Verschieben Sie den Daumen sofort in die Zielposition (aria-checked="true").
2. Ausstehendes Feedback: Zeigen Sie einen subtilen Spinner-Overlay im Daumen an oder reduzieren Sie die Track-Transparenz während der Netzwerklatenz leicht.
3. Fehlerbehebung: Wenn der Server einen Fehler zurückgibt, zeigen Sie eine Inline-Toast-/Alarmmeldung an und animieren Sie den Daumen sanft mit aria-checked="false"" in seinen vorherigen Zustand zurück.

6. WCAG AA-Barrierefreiheitsmuster implementieren

Stellen Sie die native Tastaturnavigation und Screenreader-Unterstützung in allen Browser-Engines sicher:

• Semantisches HTML-Markup:

  <button
    type="button"
    role="switch"
    aria-checked="true"
    id="push-notifications-switch"
    aria-labelledby="push-notifications-label"
    aria-describedby="push-notifications-desc"
    class="toggle-switch">
    <span class="toggle-switch__track">
      <span class="toggle-switch__thumb"></span>
    </span>
  </button>
  

• Tastaturinteraktion:
  • Fokussierbar über die Tab-Taste.
  • Drücken der Leertaste oder Eingabetaste schaltet den aria-checked-Zustand um (true <-> false) und löst den zugehörigen Handler aus.
• Screenreader-Ansagen:
  • Screenreader kündigen explizit an: „Push-Benachrichtigungen, Schalter, ein“ oder „Push-Benachrichtigungen, Schalter, aus“.
  • Schreiben Sie NICHT Text wie „Ein/Aus“ in die Beschriftung, wenn dieser den nativen ARIA-Zustand des Schalters dupliziert.

---

Entscheidungsregeln

Switch vs. Checkbox vs. Segmented Control Auswahlmatrix

Szenario / Anforderung	Empfohlenes Steuerelement	Grund
Einfache binäre Auswahl mit sofortiger Wirkung (z. B. Dunkles Design)	Toggle Switch	Sofortiges Ausführungsmodell entspricht physischem Schalter.
Einfache binäre Auswahl innerhalb eines übermittelten Formulars (z. B. AGB akzeptieren)	Checkbox	Änderungen werden erst mit Klick auf „Senden“ wirksam.
Mehrfachauswahl aus einer Liste (z. B. 5 E-Mails auswählen)	Checkboxen	Standard-Mehrfachauswahlverhalten.
Auswahl zwischen 2 verschiedenen Modi (z. B. Raster- vs. Listenansicht)	Segmented Control	Beide Zustandsbeschriftungen bleiben nebeneinander sichtbar.
Option ein/aus in einer mobilen Listenansicht schalten	Toggle Switch	Klares Daumenziel und explizites Zustandsfeedback.

Beschriftungspositionsmatrix

Layout-Kontext	Schalterposition	Beschriftungsposition	Räumliches Verhalten
Einstellungspräferenzliste	Rechtsbündig	Linksbündig	justify-content: space-between über den Zeilencontainer.
Inline-Formularfeld	Linksbündig	Rechtsbündig	display: inline-flex; align-items: center; gap: 12px.
Heldenbereichs-Preisschalter	Zentriert	Links und rechts flankierend	Flankiert von „Monatlich“- und „Jährlich“-Textoptionen.

---

Einschränkungen

• Barrierefreiheit (WCAG 2.1 / 2.2 AA):
  • Mindestens 3:1 Nicht-Text-Kontrastverhältnis für Track-Rand/-Hintergrund und Daumen gegen den Seitenhintergrund in beiden Zuständen „Ein“ und „Aus“.
  • Mindestens 4.5:1 Textkontrastverhältnis für alle zugehörigen Beschriftungen und Beschreibungshilfetexte.
  • Der Fokusring muss mindestens 3:1 Kontrast zum umgebenden Hintergrund bieten und mindestens 2px dick sein.
• Touch-Ziele:
  • Der interaktive Touch-Bereich muss auf Touch-Geräten mindestens 44x44px messen (WCAG 2.5.5 / 2.5.8).
• Farbunabhängigkeit:
  • Farbe darf NICHT der alleinige Indikator des Zustands sein. Die physische räumliche Position des Daumens (links = aus, rechts = ein) und der semantische aria-checked-Wert müssen den Zustand unabhängig von der Farbe kommunizieren.

---

Häufige Fehlermuster

• Falsche Verwendung von Switches in übermittelten Formularen: Verwendung von Switches in Formularen, bei denen Änderungen erst nach Klick auf einen separaten „Speichern“-Button wirksam werden, was Benutzer verwirrt, die eine sofortige Anwendung erwarten.
• Unzureichender Track-Kontrast: Verwendung hellgrauer Tracks (#F1F5F9) auf weißem Hintergrund ohne Rand, wodurch der Schalter für sehbehinderte Benutzer unsichtbar wird.
• Farbbasierte Zustandskommunikation: Ausschließliches Verlassen auf rote vs. grüne Track-Farben, ohne die Position des Daumenschiebers zu bewegen oder ARIA-Attribute zu aktualisieren.
• Mikroskopische Touch-Ziele: Einschränken der Trefferzone auf den 36x20px großen visuellen Track, was zu Frustration und Fehltaps auf mobilen Bildschirmen führt.
• Fehlende zugängliche Beschriftungen: Darstellung eigenständiger Symbolschalter ohne aria-label oder aria-labelledby-Referenz.
• Überlappender mehrzeiliger Text: Vertikale Zentrierung des Schalters an einem langen 4-zeiligen Beschreibungsabsatz, wodurch die visuelle Ausrichtung mit dem Haupttitel zerstört wird.

---

Validierungskriterien

• Der Schalter verwendet die semantische HTML-Struktur <button role="switch" aria-checked="true|false">.
• Track und Daumen erfüllen das Mindestkontrastverhältnis von 3:1 gegenüber dem Hintergrund in den Zuständen EIN und AUS.
• Die Tastaturnavigation (Tab, Leertaste, Eingabetaste) schaltet den Schalterzustand reibungslos um und aktualisiert aria-checked.
• Der Touch-Hit-Bereich wird mit unsichtbarem Padding oder Pseudo-Elementen auf mindestens 44x44px erweitert.
• Der Schalter ist mit sichtbarem, kontrastreichem Beschriftungstext gepaart, der über aria-labelledby verknüpft ist.
• Die Schalterposition wechselt reibungslos (transform: translateX()) über 150ms–250ms mit prefers-reduced-motion-Konformität.
• Responsive Einstellungslisten behalten korrekte Abstände (gap: 16px) bei, ohne dass sich Text auf schmalen mobilen Bildschirmen überlappt.