Code Block UI System

Code-Block-UI-System

Zweck

Das Code-Block-UI-System bietet ein standardisiertes, barrierefreies und hochgradig lesbares Layout-Framework zur Darstellung von Quellcode-Snippets, API-Anfrage-/Antwort-Payloads, Multi-Datei-Codebeispielen, Terminal-Befehlszeilen und Code-Diff-Vergleichen. Code-Blöcke sind kritische Interaktionskomponenten in technischen Dokumentationen, Marketingseiten für Entwicklertools, API-Portalen, Engineering-Blogs und SaaS-Plattformen.

Die Gestaltung effektiver Code-Oberflächen erfordert ein Gleichgewicht zwischen der Lesbarkeit nichtproportionaler Schriftarten, der kontrastreichen Hervorhebung von Syntax-Tokens in hellen und dunklen Designs, klebrigen Kopfleisten mit Aktionssymbolleisten (Sprach-Badges, tab-basierte Dateinavigation, Kopieren-in-die-Zwischenablage-Trigger), Zeilennummerierung, Zeilenhervorhebung/-Fokussierung, Verhalten bei Zeilenumbruch vs. horizontalem Scrollen und barrierefreien Screenreader-Erlebnissen. Diese Fähigkeit legt räumliche Regeln, Standardwerte für den Token-Farbkontrast, Interaktionsmechanismen und WCAG-AA-Konformitätsrichtlinien für die Darstellung von Code-UI fest.

Anwendungsfälle

• Entwicklerdokumentationen & API-Referenzportale: Darstellung von mehrsprachigen SDK-Beispielen (z. B. cURL, Node.js, Python, Go, Rust) und API-Antworten.
• Landingpages für Entwicklertools: Präsentation von Hero-Code-Snippets, CLI-Installationsbefehlen und interaktiven Produkt-Demo-Blöcken.
• Engineering-Blogs & Tutorials: Darstellung von Inline- und Block-Codebeispielen mit spezifischen Zeilenauszeichnungen, schrittweisen Code-Hervorhebungen und Inline-Anmerkungen.
• Versionskontroll- & Code-Review-Oberflächen: Anzeige von Code-Diffs (+ Hinzufügungen, - Löschungen), Inline-Kommentaren und Commit-Snippets.
• Code-Playgrounds & Snippet-Sharing-Tools: Strukturierung von Multi-Tab-Dateieditoren, Vorschaubereichen und einbettbaren Snippet-Karten.

Wann NICHT zu verwenden

• Vollwertige In-Browser-Code-Editoren (IDE): Für komplexe interaktive Web-IDs, die Canvas-Rendering, virtualisierte AST-Bäume, Multi-Cursor-Bearbeitung und Integrationen des Language Server Protocol (LSP) erfordern (z. B. Monaco Editor, CodeMirror), verwenden Sie spezielle Editor-Implementierungen.
• Allgemeine Formulartexteingaben: Für mehrzeilige Nur-Text-Felder ohne Syntax-Hervorhebung oder Zeilennummern verwenden Sie form-design-system.
• Inline-Text-Code-Badges: Für kurze einzelwortige Code-Referenzen in Prosatextabschnitten (z. B. npm install) verwenden Sie das Inline-<code>-Styling innerhalb von article-layout-system.
• Strukturierte Datentabellen: Für tabellarische Schlüssel-Wert-Daten oder Datenbankabfragen, die als Zeilen und Spalten formatiert sind, verwenden Sie data-table-ui-system oder property-and-attribute-system.

Eingaben

1. Code-Inhalt & Syntax-Typen: Die Sprach-Taxonomie (z. B. TypeScript, JSON, Bash, YAML, GraphQL, SQL) und strukturelle Merkmale (Einzeldatei, Multi-Datei-Tabs, Diff).
2. Themenkontext: Aktive Farbpaletten-Tokens für Oberflächenhintergründe, Rahmen und Syntax-Tokens im Hell- und Dunkelmodus (aus accessible-color-system und dark-theme-design-system).
3. Nichtproportionale Schriftart-Tokens: Bevorzugter Schriftart-Stack (z. B. ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, "Liberation Mono", "Courier New", monospace), Schriftgrößen und Zeilenhöhen (aus fluid-typography-system).
4. Aktions-Trigger: Spezifische interaktive Fähigkeiten, die pro Block erforderlich sind (z. B. 1-Klick-Kopieren-Button, Zeilennummern-Umschalter, Wortumbruch-Umschalter, Vollbild-Erweiterung, externer Sandbox-Link).

Ausgaben

1. Spezifikation des Code-Containers und der Kopfzeilen-Symbolleiste: Räumliche Layouts für Code-Block-Container, klebrige Kopfzeilenleisten, Sprachindikatoren, Dateipfad-Tabs und Aktionsschaltflächengruppen.
2. Barrierefreie Syntax-Token-Farbpalette: WCAG-AA (Mindestkontrastverhältnis 4,5:1) Token-Farbzuordnung für Schlüsselwörter, Zeichenfolgen, Funktionen, Variablen, Kommentare, Operatoren und Typen in hellen und dunklen Designs.
3. Zeilenebenen-Hierarchie- & Annotationssystem: Blaupause für Zeilennummerierung, Zeilenhervorhebung/Fokus-Overlays, Diff-Indikatoren (+ / -) und zeilenbezogene Ankerverlinkung.
4. Barrierefreies Screenreader- & Tastaturnavigationsmodell: ARIA-Rollenattribute, Tastaturfokus-Routen, Zeilennummern-Masking (aria-hidden="true") und aria-live-Kopierstatus-Ansagen.
5. Responsive Überlauf- & Scroll-Strategie: Regeln für horizontale Bildlaufleisten, klebrige Aktionssymbolleisten, Wortumbruch-Umschalter und Anpassungen an mobile Viewports.

---

Arbeitsablauf

1. Strukturieren Sie die Code-Block-Hülle & Kopfzeilenleiste

Entwerfen Sie den Container und die Aktionsleiste im Kopfbereich als eine einheitliche, zusammenhängende Einheit:

• Container-Architektur: Legen Sie einen abgerundeten Container fest (border-radius: 8px; border: 1px solid var(--border-subtle); overflow: hidden; background: var(--surface-code);). Verwenden Sie einen deutlichen Oberflächenhintergrund (standardmäßig dunkler Modus oder passend zur Themenoberfläche).
• Kopfzeilen-Symbolleisten-Layout: Rendern Sie eine klebrige obere Kopfzeilenleiste (display: flex; align-items: center; justify-content: space-between; padding: 8px 16px; background: var(--surface-code-header); border-bottom: 1px solid var(--border-subtle);).
• Linker Bereich der Kopfzeile (Tabs & Metadaten):
  • Einzeldatei: Zeigen Sie den Dateipfad/-namen (z. B. src/auth/jwt.ts) mit einem dezenten Dateityp-Symbol oder einem großgeschriebenen Sprach-Badge (z. B. TYPESCRIPT) an.
  • Multi-Datei / Multi-Sprache: Rendern Sie Registerkarten-Buttons (role="tablist"). Der aktive Tab hat einen kontrastreichen Text und einen unteren Rahmen/Pillen-Indikator (border-bottom: 2px solid var(--brand-primary)).
• Rechter Bereich der Kopfzeile (Aktionen): Gruppieren Sie die Auslöser für Hilfsaktionen:
  • Kopieren-Button: 32x32px Symbol-Button (aria-label="Code in die Zwischenablage kopieren") mit einem klaren Kopiersymbol und einer Beschriftung auf breiteren Viewports.
  • Umbruch / Scroll-Umschalter (Optional): Symbol-Button zum Umschalten zwischen weichem Umbruch (white-space: pre-wrap) und horizontalem Scrollen (white-space: pre).
  • Erweitern / Sandbox-Link (Optional): Auslöser zum Öffnen des Snippets in StackBlitz, CodeSandbox oder im Vollbildmodus.

2. Etablieren Sie nichtproportionale Typografie & Layout-Raster

Stellen Sie eine optimale Lesbarkeit für technisches Lesen und Code-Scannen sicher:

• Schriftart-Stack: Definieren Sie einen sauberen, gut lesbaren nichtproportionalen Schriftart-Stack: ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, "Liberation Mono", "Courier New", monospace. Stellen Sie sicher, dass die Schriftarteinstellungen eine klare Unterscheidung zwischen 0 (Null) und O (großes O) sowie zwischen 1 (Eins), l (Kleinbuchstabe L) und I (großes I) ermöglichen.
• Schriftgröße & Zeilenhöhe: Setzen Sie font-size: 0.875rem (14px) mit einer großzügigen Zeilenhöhe (line-height: 1.6 / 22,4px). Vermeiden Sie enge Zeilenhöhen, die dazu führen, dass Code-Klammern und Operatoren kollidieren.
• Code-Text-Container: Verwenden Sie <pre class="code-block"><code class="language-typescript"> mit display: block; overflow-x: auto; padding: 16px 0; margin: 0; font-family: var(--font-mono);.

3. Entwerfen Sie Zeilennummern, Zeilenhervorhebungen und Diffs

Strukturieren Sie Elemente auf Zeilenebene, ohne das Kopierverhalten oder die Screenreader-Funktionalität zu beeinträchtigen:

• Zeilenstruktur: Formatieren Sie jede Zeile als separaten Block-Container (display: table-row; oder display: flex; width: 100%;).
• Zeilennummern: Rendern Sie Zeilennummern in einer linken Spalte (display: table-cell; text-align: right; width: 40px; padding-right: 16px; user-select: none; color: var(--text-code-muted);).
  • Barrierefreiheitsregel: Wickeln Sie Zeilennummern in <span aria-hidden="true"> ein oder verwenden Sie CSS-Counter-Inhalte (content: counter(line)), damit Zeilennummern beim Markieren von Text nicht kopiert und von Screenreadern zwischen Code-Anweisungen nicht vorgelesen werden.
• Hervorgehobene / Fokussierte Zeilen: Um in einem Tutorial oder Diff die Aufmerksamkeit auf wichtige Zeilen zu lenken:
  • Wenden Sie einen expliziten Zeilenhervorhebungs-Hintergrund an (background: var(--surface-code-highlight); border-left: 3px solid var(--brand-primary);).
  • Stellen Sie sicher, dass die Hervorhebungsüberlagerung die gesamte scrollbare Breite des Code-Containers abdeckt (min-width: 100%).
• Diff-Ansichtszeilen (+ Hinzufügung / - Löschung):
  • Hinzugefügte Zeile: Dezenter grüner Hintergrund (background: rgba(34, 197, 94, 0.15); border-left: 3px solid var(--color-success);). Zeigen Sie ein +-Symbol in der Spalte an, umgeben von <span class="sr-only">Hinzugefügt:</span> für Screenreader.
  • Gelöschte Zeile: Dezenter roter Hintergrund (background: rgba(239, 68, 68, 0.15); border-left: 3px solid var(--color-danger);). Zeigen Sie ein --Symbol in der Spalte an, umgeben von <span class="sr-only">Entfernt:</span> für Screenreader.

4. Erstellen Sie eine barrierefreie Syntax-Token-Farbpalette

Syntax-Tokens müssen die WCAG-AA-Kontrastverhältnisse (mindestens 4,5:1) gegenüber dem Code-Block-Hintergrund (var(--surface-code)) erfüllen:

• Basistext / Variablen: Neutrales Hell (z. B. #E2E8F0 auf #0F172A Hintergrund; Verhältnis ~12,5:1).
• Schlüsselwörter (const, import, return, async): Lebendiges Lila/Magenta (z. B. #C084FC; Verhältnis ~7,2:1).
• Funktionen & Methoden (fetchData, useState): Helles Blau/Cyan (z. B. #38BDF8; Verhältnis ~8,5:1).
• Zeichenfolgen ("https://api.example.com"): Sanftes Grün/Smaragd (z. B. #4ADE80; Verhältnis ~9,1:1).
• Zahlen & Booleans (404, true): Warmes Orange/Bernstein (z. B. #FB923C; Verhältnis ~7,8:1).
• Kommentare (// Handle token response): Gedämpftes Kühlgrau mit WCAG-AA-Konformität (z. B. #94A3B8; Verhältnis ~5,1:1). Verwenden Sie niemals kontrastarme Grautöne (z. B. 2:1) für Kommentare.
• Operatoren & Satzzeichen (=>, {, }, ;): Mittleres Neutral (z. B. #CBD5E1; Verhältnis ~10,2:1).

5. Erstellen Sie Kopieren-in-die-Zwischenablage & Aktions-Feedback-Zustände

Die Bereitstellung von sofortigem Feedback für Kopieraktionen verhindert doppelte Klicks und Benutzerfrustration:

• Standardzustand: Zeigen Sie einen Symbol-Button mit einem Kopiersymbol (zwei überlappende Rechtecke) und optionaler Beschriftung („Kopieren“) an.
• Hover / Fokus-Zustand: Erhöhter Oberflächenhintergrund oder Randhervorhebung (background: var(--surface-hover); outline: 2px solid var(--focus-ring)).
• Aktiv / Erfolgszustand: Ändern Sie bei einem Klick das Symbol in ein Häkchen-Symbol, aktualisieren Sie die Button-Beschriftung auf „Kopiert!“ und wenden Sie einen Erfolgsfarbton an (color: var(--color-success)).
• Screenreader-Benachrichtigung: Geben Sie den Kopierstatus dynamisch über einen unsichtbaren aria-live="polite"-Bereich bekannt: „Code in die Zwischenablage kopiert“.
• Timeout-Reset: Setzen Sie den Button nach 2000ms auf den Standardzustand zurück.

6. Mobile & responsive Anpassung

Stellen Sie sicher, dass lange Code-Snippets auf kleinen Viewports funktionsfähig bleiben:

• Horizontaler Scroll-Container: Erlauben Sie horizontalen Scroll (overflow-x: auto) für lange Zeilen auf Mobilgeräten, ohne dass horizontale Bildlaufleistenüberläufe auf Seitenebene ausgelöst werden.
• Klebrige Kopfzeilen-Symbolleiste: Halten Sie die Kopfzeilen-Symbolleiste fixiert (position: sticky; top: 0; z-index: 10;), damit der Kopier-Button und der aktive Datei-Tab auch beim Scrollen durch 100+ Codezeilen zugänglich bleiben.
• Mobile Touch-Ziele: Stellen Sie sicher, dass Kopier-Buttons, Umbruch-Umschalter und Multi-Datei-Tabs auf Touch-Geräten eine minimale Touch-Zielgröße von 44x44px erfüllen.

---

Entscheidungsregeln

Syntax-Token-Kontrast & Themenmodi

Syntax-Kategorie	Empfohlene Token-Rolle	Farbe helles Design (auf #F8FAFC)	Farbe dunkles Design (auf #0F172A)	Mindestkontrastverhältnis
Schlüsselwörter	--token-keyword	Tiefviolett (#6B21A8)	Helles Violett (#C084FC)	≥ 4,5:1
Funktionen	--token-function	Dunkelcyan (#0369A1)	Himmelblau (#38BDF8)	≥ 4,5:1
Zeichenfolgen	--token-string	Waldgrün (#15803D)	Helles Smaragd (#4ADE80)	≥ 4,5:1
Zahlen / Booleans	--token-number	Dunkelbernstein (#C2410C)	Helles Bernstein (#FB923C)	≥ 4,5:1
Kommentare	--token-comment	Gedämpftes Schiefer (#475569)	Weiches Schiefer (#94A3B8)	≥ 4,5:1
Basis / Variablen	--token-base	Holzkohle (#0F172A)	Knackiges Hell (#F8FAFC)	≥ 7,0:1

Strategie für Umbruch vs. horizontales Scrollen

• Horizontales Scrollen (white-space: pre) (Standard empfohlen): Bewahrt die Integrität des Code-Layouts, Einrückungsausrichtungen und mehrzeilige Formatierung. Unverzichtbar für Python, YAML und Code-Diffs, bei denen Einrückungen semantische Struktur vermitteln.
• Weicher Wortumbruch (white-space: pre-wrap) (Optionaler Modus): Empfohlen für lange Terminal-Ausgabezeichenfolgen, Befehlszeilenbeispiele oder schmale Seitenleisten-Widgets, bei denen horizontales Scrollen den Lesefluss stört.

---

Einschränkungen

• Barrierefreiheit (WCAG 2.1 AA):
  • SC 1.4.3 Kontrast (Minimum): Alle Farben für Syntax-Hervorhebungs-Tokens und Kommentare müssen ein minimales Kontrastverhältnis von 4,5:1 gegenüber dem Code-Hintergrund erreichen.
  • SC 2.1.1 Tastatur: Benutzer müssen in der Lage sein, mit Tab und Leertaste/Enter zu den Kopf-Buttons des Code-Blocks (Tabs, Kopier-Button) zu navigieren und diese zu aktivieren.
  • SC 4.1.3 Statusmeldungen: Das Feedback des Kopier-Buttons muss der unterstützenden Technologie über einen aria-live="polite"-Bereich mitgeteilt werden.
  • SC 1.3.1 Informationen und Beziehungen: Zeilennummern müssen für Screenreader ausgeblendet werden (aria-hidden="true" oder CSS-Counter), um das Einlesen von Ziffern während des Lesens zu vermeiden.
• Textauswahl & Kopieren: Das Markieren von Text innerhalb des Code-Blocks darf niemals Zeilennummern oder Diff-Markierungen (+ / -) in den Zwischenablagenpuffer übernehmen.
• Verhinderung von Layoutverschiebungen: Das Erweitern von Multi-Datei-Tabs oder das Umschalten des Zeilenumbruchs muss feste Zeilenhöhen oder Containergrenzen festlegen, um kumulative Layoutverschiebungen (CLS) zu verhindern.

---

Häufige Fehlermuster

• Unlesbare kontrastarme Kommentare: Verwenden von schwachem grauem Text (z. B. #4A5568 auf #1A202C, 2,8:1 Kontrast) für Kommentare, in der Annahme, Kommentare seien unwichtig, was gegen die WCAG-AA-Richtlinien verstößt.
• Kopieren von Zeilennummern: Rendern von Zeilennummern als Rohtext innerhalb von <pre>, was dazu führt, dass beim Kopieren/Einfügen ungültige Code-Snippets mit vorangestellten 1 2 3 4 entstehen.
• Nicht angekündigte Kopieraktionen: Ändern von visuellen Symbolen des Kopier-Buttons, ohne das aria-label zu aktualisieren oder eine aria-live-Ansage zu senden, sodass Screenreader-Benutzer unsicher sind, ob die Aktion erfolgreich war.
• Überläufe auf Seitenebene: Fehlende Angabe von max-width: 100% und overflow-x: auto auf <pre>, wodurch 120-Zeichen-Codezeilen das Seitenlayout auf mobilen Bildschirmen sprengen.
• Unzugängliche Fokusfallen beim horizontalen Scrollen: Setzen von tabindex="0" auf den scrollbaren Code-Block ohne klare visuelle Tastaturfokus-Indikatoren, wodurch Tastaturbenutzer in langen Code-Blöcken stecken bleiben.

---

Validierungskriterien

• Der Code-Block verfügt über einen strukturierten Container mit einer klebrigen Kopfzeilen-Symbolleiste, die Sprache, Dateipfad und Aktionsschaltflächen anzeigt.
• Die Syntax-Token-Farben erfüllen das WCAG-AA-Mindestkontrastverhältnis von 4,5:1 gegenüber dem Code-Hintergrund in den Modi Hell und Dunkel.
• Zeilennummern sind von der Textauswahl und Kopierfunktion ausgeschlossen und für Screenreader verborgen (aria-hidden="true").
• Der Kopier-Button bietet ein klares visuelles Erfolgs-Feedback (Häkchen-Symbol, „Kopiert!“-Beschriftung) und eine aria-live-Ansage für Screenreader.
• Diff-Ansichten zeigen visuelle Indikatoren (+/-), wobei Screenreader-Alternativen (sr-only-Span) die Bedeutung vermitteln.
• Der Code-Block-Container verhindert horizontale Überläufe auf Seitenebene auf Mobilgeräten (overflow-x: auto).
• Alle interaktiven Elemente (Tabs, Buttons) sind über die Tastatur erreichbar und bedienbar.
• Die Schriftart und Zeilenhöhe sind für monospacebasiertes technisches Lesen optimiert.
• Zeilenhervorhebungen und Fokus-Zustände sind visuell unterscheidbar und erstrecken sich über die gesamte Code-Breite.