One-Pager, KI-Crawler und ein Scrum-Board aus Markdown-Dateien

Ein kleiner Deep-Dive in Architektur, Project Management und die Philosophie hinter meiner modernen persönlichen Website — 2026.

1. Das Konzept: Weniger Seiten, mehr Substanz

Die Website soll kein typischer Portfolio-Auftritt sein

Sie folgt einem klaren architektonischen Prinzip:
Ein einziger URL-Einstiegspunkt. Alle Inhalte als Modal.

Das Modal-Pattern ist keine Kompromiss-Lösung — es ist eine bewusste Designentscheidung.
Statt den Benutzer von Seite zu Seite zu schicken, öffnen sich Projekte, Blog-Beiträge und der Lebenslauf als elegante Overlays, die den Kontext nie verlassen. Die mentale Orientierung bleibt erhalten. Die URL zeigt, wo man ist. Der Inhalt erscheint, ohne Ladezeit zu verursachen.

Das klingt simpel. Die Implikationen sind es nicht.

  • Client-Side Routing muss mit Modul-Tiefe umgehen
  • Semantik muss auch für Inhalte gelten, die nur als Overlay existieren
  • KI-Crawler müssen trotzdem jeden Artikel vollständig lesen können
  • ARIA-Attribute müssen dynamisch korrekt gesetzt werden

Diese vier Punkte sind der rote Faden, der sich durch das gesamte Projekt zieht.

2. Der Tech-Stack: State of the Art, 2026

2.1 Next.js 16 — App Router mit Turbopack

Next.js 16 ist nicht nur ein Versions-Bump.
Die Version bringt fundamentale Verbesserungen, die direkt in den Alltag eingreifen:

  • Turbopack File System Caching: Builds brauchen 5,6 Sekunden statt 15 Sekunden. Der Dev-Server startet in 603 ms statt über 2 Sekunden.
  • Layout Deduplication: Layouts werden nicht mehr neu gerendert, wenn sich nur der Inhalt ändert. Das klingt offensichtlich — war es in früheren Versionen aber nicht.
  • Hot Module Replacement ist 96,3 % schneller als in Next.js 14.
  • React 19.2 ist der Standard: Die neue ` `-Komponente, `useEffectEvent` und der stabile React Compiler mit automatischer Memoization reduzieren `useMemo`/`useCallback`-Boilerplate strukturell.
  • middleware.ts heißt nun proxy.ts: Die Umbenennung ist semantisch — sie macht klar, was die Datei tut.

Der App Router ist hier nicht optional. Er ist die Grundlage für das Modal-System:
Jeder Modal-Inhalt ist ein eigenes Segment, das über Parallel Routes eingeblendet wird.
Das erlaubt Deep-Linking, ohne die URL-Struktur zu opfern.

2.2 Tailwind CSS 4 — Die Oxide Engine

Tailwind CSS 4 ist ein kompletter Relaunch.

Tailwind CSS ist ein beliebtes Framework, mit dem Entwickler moderne Webseiten schnell und effizient gestalten können. Anstatt fertige Design-Bausteine zu liefern, arbeitet es nach dem sogenannten „Utility-First“-Prinzip. Das bedeutet, dass es unzählige kleine, vordefinierte Stil-Klassen bereitstellt, die direkt im HTML-Code wie Legosteine kombiniert werden. Dadurch entfällt größtenteils das Schreiben separater CSS-Dateien, was den Entwicklungsprozess deutlich beschleunigt und die Wartung vereinfacht. Letztendlich bietet Tailwind somit eine enorme Flexibilität, um völlig individuelle und maßgeschneiderte Benutzeroberflächen ohne vorgegebene Design-Einschränkungen umzusetzen.

Das Herzstück von Tailwind 4 ist die Oxide Engine, geschrieben in Rust und Lightning CSS.

Was das bedeutet:

  • Keine tailwind.config.js mehr. Die gesamte Konfiguration lebt in src/app/globals.css über den @theme-Block.
  • Native CSS Custom Properties: --color-primary ist eine echte CSS-Variable, kein Build-Artefakt.
  • Container Queries (@container) sind nativ integriert.
  • CSS Cascade Layers (@layer) ermöglichen deterministische Spezifitätskontrolle.
  • P3 Wide Gamut Colors und native OKLCH-Unterstützung für zukunftssichere Farbdefinitionen.
  • Incremental Builds im Mikrosekunden-Bereich.

Die Architektur im Projekt folgt einem Drei-Ebenen-Modell:

Ebene Datei Funktion
Root colors.css Rohe Design-Tokens, unveränderlich
Konfiguration globals.css Mapping via @theme, TW4-Paradigma
Komponenten .tsx-Dateien Semantische Utility-Klassen

Das Ergebnis: Ein Theme-Switch von Dark zu Light ist eine Änderung von zwei CSS-Variablen — keine JavaScript-Logik, kein Re-Render des DOM-Baums.

2.3 shadcn/ui — Full Ownership über jede Zeile Code

shadcn/ui ist kein klassisches npm-Paket.
Es ist ein Copy-Paste-CLI-System, das Komponenten einmalig via `npx shadcn@latest add

` ins Projekt kopiert.

Das hat eine entscheidende Konsequenz:
Jede Zeile Code gehört mir. Kein Update-Risiko. Keine Black Box.

Im Projekt werden u.a. folgende Primitives aktiv genutzt:

| Primitive | Hauptnutzung | |—|—| | button | Copy-Button, Icon-Button, Search-Actions | | dialog | OnePageShell, UnifiedModalShell | | sheet | Header-Menü, LeftSidebar | | card | MDX-Viewer, About-Page | | dropdown-menu | Header-Navigation | | input | Graph-Editor, Knowledge-Sidebar | | tabs | Code-Beispiele |

Die Basis dahinter ist Radix UI: Eine headless Komponenten-Bibliothek, die WAI-ARIA-Konformität, korrekte Focus-Modelle und strukturierte Interaktion deterministisch liefert.
Das ist kein Nice-to-have — das ist die Grundlage für die A11Y-Strategie (mehr dazu in Abschnitt 4).

2.4 MDX mit Registry-Pattern

Alle Inhalte — Blog-Artikel, Projektseiten, Dokumentation — leben als MDX-Dateien.

MDX ist Markdown mit einer Superkraft: JSX-Komponenten direkt im Fließtext.
Das erlaubt Inhalte wie:

„`mdx import { ProjectModal } from ‚@/registry/components/project-modal‘

„`

Das Registry-Pattern ist der Schlüssel zur Skalierbarkeit:
Alle Komponenten liegen in einer zentralen Registry und können in MDX-Dateien importiert werden.
Content und Design sind vollständig getrennt — aber trotzdem vollständig integriert.

Konkret bedeutet das: – Blog-Artikel können interaktive Code-Playgrounds enthalten – Projekt-Seiten können Live-Komponenten einbetten – Rechtliche Seiten (Datenschutz, Impressum) sind MDX-Dateien, die in Modals geöffnet werden – Jede Änderung am Content erfordert keine Deployment-Pipeline — nur eine MDX-Datei

2.5 pnpm 9 — Content-Addressable Storage

pnpm ist der Package Manager der Wahl.
Der Grund: Content-Addressable Store mit Hardlinks.

Pakete werden genau einmal auf der Festplatte gespeichert.
Jedes Projekt, das dieselbe Version von React nutzt, bekommt einen Hardlink — keine Kopie.

Das ergibt: – Schnellere Installationen durch globalen Cache – Deterministischer Dependency-Graph ohne Phantom-Dependencies – Non-flat node_modules — Import-Pfade können nicht versehentlich auf nicht-deklarierte Abhängigkeiten zugreifen

—

3. Das Projekt-Management-System: Ein dateibasiertes Scrum-Board

Das Projekt ist kein Solo-Experiment ohne Struktur.
Es wird mit einem vollständig selbst entwickelten, dateibasierten PM-System verwaltet, das unter .plans/ lebt.

3.1 Die Philosophie: Source of Truth ohne externen Dienst

Die meisten Projekte dieser Größenordnung enden in einem Jira-Board, das nie jemand pflegt, oder in einem GitHub-Project, das zu früh aufgegeben wird.

Das hier ist anders:
Alle PM-Informationen sind Markdown-Dateien im Repository.

Was das konkret bedeutet:

– Tickets sind .md-Dateien mit YAML-Frontmatter – Das Board ist ein Verzeichnis mit 6 Spalten (00_Backlog bis 05_Archive) – Der Event-Log ist eine append-only JSONL-Datei (ledger.jsonl) – Der aktuelle Snapshot ist state.json – Auto-Tagging läuft als Node.js-Daemon

3.2 Die Ticket-Struktur: Kanonische IDs

Jedes Ticket hat eine kanonische ID:
I-P <epic>&#8211;<globalseq>&#8211;<guid4>

Beispiel: I-P002-0042-A7F3

Das ist keine kosmetische Entscheidung.
Diese Struktur erlaubt:

– Tickets, die ohne Kontext eindeutig einem Epic zugeordnet werden können – Automatisches Issue-Routing in CodeQL-Findings – GitHub-Sync ohne manuelle Nacharbeit – Ledger-Events, die maschinenlesbar auf jedes Ticket zeigen

3.3 Die 4 aktiven Epics

Das Projekt ist in vier Epics organisiert, die parallel laufen:

P-001 · Website-Hardening
Enthält alle produktiven Website-Umsetzungen:
Modal-System, Pagination, Semantik-Audits, Runtime-Fixes.
Zielbild: Onepage, Collections und Modals sind stabil, semantisch und regressionsarm.

P-002 · Workspace-PM-System
Standardisierung des dateibasierten PM-Systems:
Kanonische IDs, Ledger-Historie, Sprint-Planning-Automation, Board-View.
Zielbild: Jede PM-Änderung ist als Event nachvollziehbar. Sprint-Planung ist reproduzierbar scriptbasiert.

P-003 · CodeQL-System
Ein operatives CodeQL-Subsystem mit eigenem Lifecycle:
Custom Query-Packs, Findings-Normalisierung, PM-Issue-Sync, hartes lokales Gate.
Baseline (Stand 2026-03-01): 274 normalisierte Findings, 44 automatisch erzeugte PM-Issues.

P-004 · Agent System Handbook
Eine modulare, kopierbare Betriebsdokumentation:
Next.js 16, Tailwind v4, shadcn/ui, PM-System, CodeQL — alles dokumentiert, sodass ein neuer Agent ohne Chat-Kontext arbeiten kann.

3.4 Das PM-Script-Ökosystem

Das Board wird nicht manuell verwaltet.
Es gibt ein vollständiges Script-Ökosystem unter .plans/99_Scripts/:

„`bash

Board validieren (lokales Gate)

node .plans/99_Scripts/pm-validate-board.mjs

Prioritäts-Audit

node .plans/99_Scripts/pm-priority-audit.mjs

Epic-Report generieren

node .plans/99_Scripts/pm-epic-report.mjs –id P-001

Sprint planen

node .plans/99_Scripts/pm-plan-sprint.mjs

GitHub-Sync

node .plans/99_Scripts/pm-sync-github-issues.mjs

Board-View starten (read-only, Port 3009)

node .plans/99_Scripts/pm-workspace-daemon.mjs –interval 120000 –port 3009 „`

3.5 Auto-Epic-Tagging und Workspace-Daemon

Ein laufender Node.js-Daemon überwacht das Board alle 2 Minuten:

„bash node .plans/99_Scripts/pm-auto-epic-tags.mjs &#8211;watch &#8211;interval 120000 &#8222;

Wenn ein neuer Epic-Plan angelegt wird, erzeugt der Daemon automatisch Git-Tags: – epic/P-XXX/start-* — bei neuem Epic-Plan – epic/P-XXX/change-* — bei Epic-Änderungen
– epic/P-XXX/end-* — wenn Epic auf done geht

Das Board ist unter http://127.0.0.1:3009 als read-only Webansicht erreichbar — mit Epics, Sprints, Issues und dem vollständigen Ledger.

3.6 Das Linking-System

Seit dem letzten Ausbau hat das PM-System auch ein Linking-System:

– Frontmatter-Feld links: mit strukturierten {type, target, note}-Einträgen – Scripts für Link-Management: pm-link-add.mjs, pm-link-remove.mjs, pm-link-graph-report.mjs – Board-API: /api/links, /api/work-item/:id/links, /api/graph

Das erlaubt echte Abhängigkeits-Graphen zwischen Issues und Epics — ohne externen Dienst.

—

4. A11Y als AIO — Barrierefreiheit als KI-Parsing-Optimierung

Das ist der ungewöhnlichste Teil des Projekts.
Und gleichzeitig der Teil, der am meisten Substanz hat.

4.1 Die These: A11Y = maschinelle Parsing-Optimierung

KI-Crawler, LLM-Scraper und RAG-Pipelines lesen das Web nicht wie Menschen.
Sie ignorieren visuelles Rendering. Sie verwerfen CSS. Sie wandeln den rohen DOM-Baum in einen sequenziellen Textstrom um.

Für eine Maschine existiert kein „oben rechts“ oder „rot hervorgehoben“.
Es existiert eine lineare Abfolge von Knoten.

Axiom: Alles, was strukturierte Semantik liefert, reduziert die Entropie für Transformer-Modelle.

Bei verschachtelten generischen `

`- und ``-Tags muss die KI mehr Compute für Kontextrekonstruktion aufwenden. Semantisches HTML (`
`, `