Architecture Decision Record · 0022

HTML-First Documentation

Entscheidung. Alle Doku-Strands unter docs/ nutzen ab sofort HTML als Output-Format. Templates kommen aus ThariqS/html-effectiveness und liegen unter docs/_templates/; Brand-Token-Layer liegt unter docs/_assets/styles.css (SOLCOM-Lime, Dark-Blue, Background-Blue, Montserrat, ScalaSans). Bestehende 53 MD-Files werden in einem Big-Bang migriert, ein neuer Skill html-doc-authoring erzwingt das Format ab Skill-Trigger.

Kontext

Markdown war bisher das Default-Format für alle Doku-Strands unter docs/: ADRs, Plans, PRDs, Brainstorms, Context-Snapshots, Design-Mappings, Session-Todos. Mit zunehmender Größe der Doku (53 Files, einzelne >500 Zeilen, Plans mit Mockups und Code-Snippets) stoßen wir an die Grenzen von MD: keine Tabellen-Status-Pills, keine inline-SVG-Diagramme, keine Side-by-Side-Vergleiche von Optionen, keine Sticky-Navigation in langen Specs.

Auslöser ist Thariqs Artikel „Using Claude Code: The Unreasonable Effectiveness of HTML" (x.com/trq212/2026-05-08) plus das begleitende Demo-Repo ThariqS/html-effectiveness mit 20 self-contained HTML-Templates für Plan, PRD, Code-Review, Status-Report, Incident-Timeline, Design-System usw. Kernargument: HTML kann Tabellen, SVG, Tabs, Collapsibles, mobile-responsive Reading darstellen — Markdown nicht.

Trade-off-Realität: HTML-Diffs in Git sind noisier als MD-Diffs, jedes Doku-File wird 2–4× länger zu generieren, und der ADR-MD-Standard (0NNN-…md mit 4 Sektionen) ist seit ADR-0001 etabliert. Diese Kosten sind abgewogen worden.

i
Verifikation: Thariq selbst warnt im Artikel davor, das Format vorzeitig in einen Skill zu pressen („I'm a little bit afraid that people will read this article and turn it into a /html skill or something"). Diese Warnung ist bewusst übergangen worden — Begründung siehe Rejected alternatives, Option C.

Entscheidung

Big-Bang HTML-First für alle Doku-Strands, umgesetzt in 8 Phasen (siehe docs/tasks/todo.html für den operativen Plan):

  1. Foundation. 20 Templates aus ThariqS/html-effectiveness 1:1 nach docs/_templates/, plus docs/index.html als Galerie. Shared Style docs/_assets/styles.css mit SOLCOM-Brand-Tokens (Lime #BEDC00, Dark Blue #001F46, Background Blue #011C53), ScalaSans + Montserrat ExtraBold via lokal kopiertem @font-face.
  2. Authoring-Skill html-doc-authoring. Auto-Trigger bei Plan/PRD/ADR/Brainstorm/Report-Begriffen plus Datei-Globs docs/**/*.html. Verlinkt Templates und Conventions.
  3. Doku-schreibende Skills/Agents updaten. solcom-docs-context, solcom-design-mapping, solcom-adr-workflow plus die vier zugehörigen Agents emittieren HTML statt MD.
  4. CLAUDE.md / AGENTS.md. Output-Format-Sektion neu, alle Strand-Pfade auf .html.
  5. Dieser ADR. Erste „echte" HTML-Doku-File, dient als Migrationsanker.
  6. Migration der 53 bestehenden Files. Pro Strand ein Commit, kleinste Strands zuerst, ADRs als Letztes (21 Files). Files werden gelöscht und durch HTML-Pendants ersetzt — Naming bleibt stabil.
  7. Cross-Reference-Update. ~199 Refs in 57 Source-Files: Skill-Files, Code-Files (byte_theme.info.yml, neun Twig-/PHP-Files mit ADR-0004-Refs), CLAUDE.md, AGENTS.md, CONTEXT.md.
  8. Browser-Verifikation. docs/index.html lokal öffnen, Galerie und jeder Strand stichprobenartig durchklicken.

Single-Source-of-Truth über CSS-Cascade-Trick: Templates aus dem Repo behalten ihren inline :root{…}-Block (Anthropic-Palette). Jedes Doku-File lädt nach dem inline <style>-Block die ../_assets/styles.css via <link>. Dadurch überschreibt SOLCOM die Anthropic-Werte automatisch über Custom-Property-Cascade, file-spezifische Tokens bleiben unangetastet.

<head>
  <style>
    :root { /* Anthropic-Palette aus dem Template */
      --ivory: #FAF9F5;
      --clay:  #D97757;
      ...
    }
    /* file-spezifische Tokens bleiben hier */
  </style>
  <link rel="stylesheet" href="../_assets/styles.css">
</head>

Frontmatter via <meta>-Tags

YAML-Frontmatter ist in HTML kein natives Konstrukt. Wir kodieren die kanonischen Felder als <meta name="solcom:<feld>" content="…"> im <head>. Beispiel für einen Context-Snapshot:

<meta name="solcom:type" content="context">
<meta name="solcom:title" content="IT-Landschaft Workshop 2026-04-29">
<meta name="solcom:source" content="adesso-SOLCOM-Kickoff_29042026.pdf">
<meta name="solcom:source-type" content="pdf">
<meta name="solcom:captured" content="2026-04-29">
<meta name="solcom:last-synced" content="2026-05-09">
<meta name="solcom:tags" content="kickoff,it-landscape,workshop">
<meta name="solcom:supersedes" content="">

Rejected alternatives

Option A — Status quo: alles bleibt Markdown rejected

Beibehalt der bestehenden 53 MD-Files, kein Format-Wechsel. Vorteil: keine Migrations-Arbeit, keine HTML-Diff-Noise, ADR-Standard 0NNN-…md bleibt erhalten.

Verworfen, weil längere Plans/PRDs in MD nicht mehr lesbar sind und das Format Mockups, Tabellen-Status-Pills und Side-by-Side-Vergleiche nicht sauber unterstützt — der konkrete Auslöser für diese Initiative.

Option B — Light-Delivery: Templates + CSS + CLAUDE.md, kein Skill, keine Migration rejected

Vorschlag des Advisors: shared styles.css + 2–3 Templates + CLAUDE.md-Output-Format-Section + minimale Skill-Edits. Nur neue Files in HTML, alte bleiben MD. Strand-Routing: Plans/PRDs/Brainstorms HTML; ADRs/Tasks/INVENTORY/MAPPING/Context bleiben MD.

Verworfen, weil hybride Strands („manche HTML, manche MD") für Authoring-Skills und Cross-Refs zu komplex werden. Big-Bang trennt sauber: es gibt nur noch ein Format.

Option C — Kein Skill (nur Konvention) rejected

Thariqs eigene Empfehlung: kein /html-Skill, einfach prompten. Format-Default rein in CLAUDE.md anchorn.

Verworfen, weil der projekt-lokale Skill-Mechanismus (Auto-Trigger via Frontmatter-Phrasen) die Konvention verlässlicher durchsetzt als eine CLAUDE.md-Default-Regel, die eine LLM-Session ggf. überstimmt. Der Skill kann explizit auf Templates und _assets/styles.css verweisen und die Migrations-Heuristik vorhalten.

Option D — Voller Skill + Big-Bang-Migration aller 53 Files chosen

Diese Entscheidung. Voller Skill html-doc-authoring, alle Strands HTML-Default, bestehende MD-Files werden gelöscht und durch HTML ersetzt. ADR-Nummern bleiben stabil, 4-Sektionen-Schema wird in HTML als 4 Sektionen abgebildet.

Gewählt, weil der User explizit „1:1 nachbauen, da haben wir doch alles drin" angewiesen hat — Templates kommen direkt aus dem Repo, Adaption beschränkt sich auf SOLCOM-Style-Anwendung. Saubere Trennung statt Hybrid-Modus.

Consequences

+ Positives

  • Tabellen mit Status-Pills, inline-SVG, Mockup-Grids und Side-by-Side-Vergleiche direkt nativ.
  • Sticky-Side-Nav in langen ADRs/Plans — bei 500-Zeilen-Specs sofort navigierbar.
  • Single-Source-of-Truth für Brand-Tokens via _assets/styles.css; Token-Update zentral.
  • Galerie-Index docs/index.html — Doku ist ein Browser-Klick weit weg.
  • Authoring-Skill triggert auf Format-Phrasen, Tooling muss nicht erst Default kennen.
  • Mobile-responsive Reading — Plans am Telefon lesbar.

− Negatives / Risiken

  • HTML-Diff-Noise. Jeder Edit wird in Git-Reviews schwerer lesbar als MD-Diff. Besonders für tasks/todo.html, design/MAPPING.html, context/INVENTORY.html.
  • Generierungsaufwand 2–4× höher laut Thariq. Bei jedem Authoring-Schritt spürbar.
  • Bruch mit ADR-MD-Standard. Externer Onboarding-Reader muss umlernen.
  • Cross-Reference-Brüche. ~199 Refs in 57 Source-Files müssen angepasst werden. Externe Links auf *.md-Pfade können wir nicht reparieren.
  • Tooling-Risiko. AI-Code-Reviewer und ähnliche Tools, die *.md in PRs lesen, sehen Doku-Änderungen evtl. nicht mehr automatisch.
  • Greppability. grep in HTML ist lauter. Mitigation: grep -o '>[^<]*' oder pup/html2text.

Out of scope

!
Erste „echte" Anwendung dieses ADRs: dieses File selbst. Falls die Migration sich als Dauerproblem erweist (Diff-Noise blockiert Reviews, Tooling bricht kritisch), öffnet ein Folge-ADR mit supersedes: 0022 die Tür zum Rollback.