DESIGN.md für WordPress

Jede Website die über mehr als ein Jahr gewachsen ist, hat dasselbe Problem: Farben die fast gleich sind aber nicht ganz. Abstände die ähnlich wirken aber nicht gleich sind. Schriftgrößen die irgendwann aus dem Gefühl heraus gesetzt wurden statt aus einem System.

Bei werkform.at war (ist) das nicht anders. Nach der Neueinspielung von der Produktions- auf die Staging-Umgebung war der richtige Moment um einen Blick auf den Ist-Zustand zu werfen. Was ich dabei entdeckt habe war lehrreich, und typisch.

Zwei Grautöne mit zu ähnlichen Namen für zu verschiedene Rollen. Spacing-Tokens die sich im Anwendungsbereich überlappen ohne klare Semantik. Vier Legacy-Container mitten in einer ansonsten modernen v4-Architektur. Eine Farbe in einer Global Class die nirgendwo im Farbsystem dokumentiert ist.

Nichts davon ist ein dramatischer Fehler. Zusammen ergeben sie aber ein System das schwer zu warten ist, weil keine Regel sagt welcher Wert der richtige ist.

Eine DESIGN.md ist ein Dokument das dein Designsystem beschreibt. Der entscheidende Unterschied zu einem Screenshot oder einer Figma-Datei: Die DESIGN.md überlebt Sessions. Sie liegt ev. im Repo, wird versioniert, und kann beim nächsten Gespräch mit der KI als erstes eingelesen werden. Damit weiß die KI immer was primary bedeutet, welche Schrift du verwendest, und was dein Borderradius ist.

Was sie nicht löst: bestehende Inkonsistenzen. Die DESIGN.md beschreibt was sein soll, nicht was ist. Wenn deine Website inkonsistent gebaut wurde, bildet das Dokument entweder den Ist-Zustand ab (und dokumentiert damit die Fehler) oder den Soll-Zustand (und ignoriert die Realität). Beides ist nützlich, aber nur wenn du weißt welches Dokument du gerade hast.

Die werkform DESIGN.md die aus diesem Prozess entstanden ist, ist ein Zwischenschritt. Sie dokumentiert den aktuellen Ist-Zustand inklusive der bekannten Inkonsistenzen. Das macht sie ehrlicher und nützlicher als ein idealisiertes Dokument, es bedeutet aber auch dass die Arbeit noch nicht abgeschlossen ist.

Dieser Prozess beschreibt den idealen Ablauf für eine Elementor-Website mit Novamira als MCP. Die Prinzipien gelten für jeden Builder — die konkreten Schritte und Abilities sind Elementor-spezifisch.

Ich verwende Novamira Pro als MCP-Verbindung zu deiner WordPress-Instanz. Ohne diese Verbindung kann die KI die Elementor-Datenstrukturen nicht lesen und sie sieht nur rohe Datenbankeinträge ohne Kontext.

Eine klare Aufgabe für die KI "Erstelle eine DESIGN.md" ist zu vage. Der Prompt der funktioniert:

Die AI macht was sie immer macht und sich wichtig.

Das Ergebnis
Nach diesen fünf Schritten hast du ein DESIGN.md welches:

Builder-agnostische Tokens im YAML-Frontmatter hat — exportierbar zu Tailwind oder CSS Custom Properties. Die Elementor-spezifische Implementierung als eigenen Abschnitt dokumentiert — mit den tatsächlichen Variable-IDs die du in jeder AI-Session als Referenz verwenden kannst. Bekannte Inkonsistenzen benennt statt sie zu verstecken.

Was du danach noch nicht hast: ein bereinigtes Design.

Für andere Builder: Wer Bricks oder Gutenberg verwendet, folgt denselben fünf Schritten. Was sich ändert sind die Novamira-Abilities die verwendet werden, was Novamira gerade unterstützt findest du hier (rasch wachsend!) Oder die KI liest die Daten direkt aus der WordPress-Datenbank. Die Token-Struktur im YAML und die Prosa-Dokumentation sind identisch.

Das Arbeiten mit .md-Datein verrät, dass man KI verwendet hat. Das ist keine Schande, hat aber einen - zu Recht - schlechten Ruf. .md Dateien sollten also nicht im Web auffindbar sein. Aber: es macht durchaus sinn, sie im Webverzeichnis zu speichern, wenn man keine Versionierung benutzt. Ich habe mich daher vorerst für folgenden Weg entschieden:

Bei mir liegt die Datei direkt im Webroot in der Staging-Umgebung. Dazu gibt es 3 Dinge die verhindern können, dass diese Datei gefunden wird.

1. Ich habe in meiner .htaccess-Datei ausserhalb des WordPress-Bereiches (damit die Info nicht beim Neuschreiben von Permalinks übeschrieben wird) eine Regel hinzugefügt:

2. Man kann WP Staging Pro erweitern (siehe WP Staging Hooks) und anweisen, diese Dateien nicht zu pushen.

3. Innerhalb der DESIGN.md steht ein Hinweis darauf, dass diese nicht ausgeliefert werden soll.

In Wirklichkeit habe ich natürlich nicht sofort gewusst was ich wie und warum zu tun habe. So habe ich vergessen zu erwähnen, dass die DESIGN.md den Google-Format entsprechen muss. Claude hat mit das mehrfach vorgeworfen (mein Claude darf das).

Ein große Vorteil der Idee ist auch, dass man automatisch eine Konsistenzprüfung seines Designs erhält. 4 Fehler verdienen beschrieben zu werden. Natürlich habe ich nicht die ganze Website mit 100 Posts zur Analyse herangezogen sondern das Post-Template, das mir als Vorlage bei allen neuen Artikeln dient.

Beim Lesen der Elementor-Daten aus Template 25694 tauchte das erste Problem auf: vier v3-Legacy-Container mitten in einer ansonsten modernen v4-Architektur. Das Template war über mehrere Sessions gewachsen - jedes Mal wurde das gebaut was gebraucht wurde, ohne den Gesamtzustand zu prüfen.

Das Ergebnis: v3-Elemente referenzierten v3 Custom Colors statt v4 Variables. Dieselbe Farbe existierte an zwei Stellen im System unter zwei verschiedenen Referenzen. Das Template sah im Editor korrekt aus - im Frontend auch. Der Fehler war unsichtbar bis jemand (oder etwas) die Datenstruktur las.

Das ist der häufigste Typ von Inkonsistenz auf gewachsenen Elementor-Sites: nicht falsche Werte, sondern doppelte Pfade zum richtigen Wert. Die Korrektur war chirurgisch: jeden v3-Container löschen, als v4 e-flexbox neu aufbauen, Farbreferenzen auf v4 Variables umstellen. Vier Elemente, vier separate Operationen mit Bestätigung nach jedem Schritt.

Learning: Bevor du eine DESIGN.md schreibst, lass die KI das Template auf v3/v4-Hybride prüfen. Ein Dokument das einen inkonsistenten Ist-Zustand beschreibt, beschreibt zwei verschiedene Systeme gleichzeitig.

Das Template hatte zwei separate Content-Sektionen mit je eigenem TOC. Das Designschema sah eine einzige Content-Sektion vor — TOC links fixiert, gesamter Content rechts scrollend. Zwei verschiedene Dinge die identisch aussehen können aber strukturell entgegengesetzt sind.

Das wurde erst sichtbar als das ursprüngliche Schema als Bild gezeigt wurde. Die KI hatte die Struktur korrekt gelesen und korrekt dokumentiert — das falsche Layout wäre in die DESIGN.md eingeflossen als wäre es korrekt.

Ein Screenshot hat aufgedeckt was eine Datenanalyse nicht kann: ob die gebaute Struktur der Designintention entspricht. Der Umbau war komplett - beide alten Sektionen gelöscht, eine neue gebaut. Das war kein Feintuning sondern ein Strukturfehler der behoben werden musste bevor das Template als Basis taugte.

Learning: Eine DESIGN.md beschreibt was sein soll, nicht was gebaut wurde. Wenn du nicht weißt ob das Gebaute der Intention entspricht, kläre das zuerst, sonst dokumentierst du den falschen Zustand.

Die Analyse der Elementor-Daten zeigte keine Layout-Bugs. Die Screenshots auf Tablet und Mobile zeigten sofort zwei: Ghost-Spalten mit width: 0% statt display: none, die unsichtbar Platz wegnahmen. Boxen die auf Desktop 49% breit waren und auf Tablet nicht auf 100% wechselten.

Beide Fehler waren in den Styles korrekt dokumentiert — aber trotzdem eben Fehler. width: 0% ist technisch kein Fehler, es produziert nur das falsche Ergebnis. Die KI hatte die Werte gelesen und weitergegeben ohne zu wissen dass das visuelle Ergebnis falsch ist.

Learning: Lass die KI nie ohne visuelle Verifikation arbeiten wenn Layout-Entscheidungen getroffen werden. Datenanalyse findet strukturelle Fehler. Screenshots finden visuelle Bugs. Beides ist nötig.

Post 25354 existierte bereits als Pattern-Bibliothek — angelegt in einer früheren Session, nie wieder angeschaut. Beim Prüfen stellte sich heraus: drei der vier Pattern waren v3-Legacy, das gesuchte 50/50 Text+Bild Pattern fehlte komplett.

Das ist der typische Zustand gewachsener Websites: Dinge die existieren aber niemand mehr weiß in welchem Zustand sie sind. Eine DESIGN.md zwingt dich dazu, diesen Zustand explizit zu machen — weil du die Daten liest statt zu vermuten.

Learning: Eine Pattern-Bibliothek ist nur nützlich wenn sie aktuell ist. Plane bei jeder größeren Template-Änderung explizit ein, die Pattern-Bibliothek zu prüfen und zu aktualisieren.

Die werkform DESIGN.md die aus dieser Session entstanden ist, benennt sieben bekannte technische Schulden. Keine davon wurde in dieser Session behoben. Das ist die richtige Entscheidung — eine DESIGN.md-Session ist nicht der Moment um alle Probleme zu lösen. Sie ist der Moment um sie sichtbar zu machen.

Die offenen Punkte werden in zukünftigen Sessions adressiert: die sechs identischen Marginalspalten-Definitionen die eine einzige Global Class sein sollten, die fehlenden mittleren Schriftgrößen als Tokens, die Farbe in einer Global Class die nirgendwo im Farbsystem steht. Jede dieser Korrekturen ist ein separates Projekt. Die DESIGN.md ist das Dokument das sicherstellt dass sie nicht vergessen werden — und dass die KI in jeder zukünftigen Session weiß was noch aussteht.