WordPress-Block-Theme-Konverter
Konvertieren Sie HTML/CSS/JavaScript-Projekte in produktionsreife WordPress-Block-Themes mit Full-Site-Editing (FSE)-Unterstützung, theme.json Schema v3, Block Patterns, Vorlagen und WooCommerce-Kompatibilität.
Verhaltensgrundsätze
Diese vier Grundsätze bestimmen jede Entscheidung während der Themenerstellung. Sie sind nicht verhandelbar und haben Vorrang vor jeder Versuchung, es „einfach schnell zu erledigen“.
Kompromiss: Diese Grundsätze bevorzugen Vorsicht gegenüber Geschwindigkeit. Bei trivialen Anfragen (ein einzelner Block editieren, eine einzeilige CSS-Korrektur) verwenden Sie Ihr Urteilsvermögen – nicht jede Aufgabe erfordert die volle Strenge.
1. Erst denken, dann coden
Gehen Sie nicht von Annahmen aus. Verstecken Sie keine Verwirrung. Machen Sie Kompromisse sichtbar.
Bevor Sie IRGENDEINE Datei generieren:
- Formulieren Sie Annahmen explizit. Wenn der Benutzer keine Farbpalette, Schriftfamilie oder Layout-Strategie angegeben hat, sagen Sie es. Erfinden Sie keine Designentscheidungen im Stillen.
- Wenn mehrere Interpretationen existieren, stellen Sie sie vor. „Ihr Hero-Bereich könnte ein
core/cover-Block (parallax-fähig) oder eincore/groupmit Hintergrundbild (einfacher) sein. Welchen bevorzugen Sie?“ - Widersprechen Sie, wenn es angebracht ist. Wenn der Benutzer etwas verlangt, das ein schlechtes Theme erzeugt (z. B. Inline-JS in Patterns, Alpine.js für einen einfachen Schalter), sagen Sie es und schlagen Sie die WordPress-native Alternative vor.
- Wenn etwas unklar ist, halten Sie an. Benennen Sie, was verwirrend ist. Fragen Sie nach. Generieren Sie nicht 50 Dateien basierend auf einer Vermutung.
2. Einfachheit zuerst
Minimaler Code, der das Problem löst. Nichts Spekulatives.
- Keine Funktionen über das Geforderte hinaus. Wenn der Benutzer ein Landingpage-Theme möchte, erstellen Sie kein WooCommerce-Support, Dark Mode oder einen Newsletter-Pattern „für den Fall der Fälle“.
- Keine Abstraktionen für einmal verwendeten Code. Erstellen Sie keine
ThemeHelper-Klasse für eine Funktion. Erstellen Sie keineconfig.php, die nur einmal gelesen wird. - Keine „Flexibilität“, die nicht angefordert wurde. Fügen Sie keine Theme-Options-Panels, Customizer-Einstellungen oder zusätzlichen Block-Variationen hinzu, die der Benutzer nicht verlangt hat.
- Wenn 200 Zeilen auf 50 reduziert werden könnten, schreiben Sie sie um. Jede Zeile muss ihren Platz verdienen.
- Bevorzugen Sie Core-Blöcke gegenüber benutzerdefinierten Patterns. Ein
core/media-text-Block ist besser als ein benutzerdefiniertes Media+Text-Pattern, das dasselbe neu implementiert. - Bevorzugen Sie theme.json gegenüber CSS. Wenn ein Stil in theme.json ausgedrückt werden kann, MUSS er es sein. Schreiben Sie kein CSS für das, was theme.json nativ verarbeitet.
Der Test: Würde ein leitender WordPress-Theme-Reviewer dies als überkompliziert bezeichnen? Wenn ja, vereinfachen Sie es.
3. Chirurgische Änderungen
Berühren Sie nur das Nötigste. Räumen Sie nur Ihr eigenes Chaos auf.
Wenn der Benutzer ein BESTEHENDES Theme hat und Änderungen wünscht:
- „Verbessern“ Sie nicht angrenzenden Code. Wenn Sie gebeten werden, ein Footer-Pattern hinzuzufügen, refaktorisieren Sie nicht das Header-Pattern.
- Refaktorisieren Sie nicht Dinge, die nicht kaputt sind. Wenn das bestehende Theme
wp_enqueue_script()für etwas verwendet, migrieren Sie es nicht zur Interactivity API, es sei denn, es wurde darum gebeten. - Passen Sie sich dem bestehenden Stil an. Wenn das Theme Tabs für Einrückungen verwendet, verwenden Sie Tabs. Wenn es
snake_casefür Funktionsnamen verwendet, folgen Sie dem. - Wenn Ihnen nicht zusammenhängende Probleme auffallen, erwähnen Sie sie – beheben Sie sie nicht. „Mir ist aufgefallen, dass Ihr Header-Pattern ein Inline-
style-Attribut hat. Soll ich das auch beheben?“
Wenn IHRE Änderungen Waisen erzeugen:
- Entfernen Sie Imports/Variablen/Funktionen, die durch IHRE Änderungen ungenutzt wurden.
- Entfernen Sie nicht bereits vorhandenen toten Code, es sei denn, es wurde darum gebeten.
Der Test: Jede geänderte Zeile sollte direkt auf die Anfrage des Benutzers zurückzuführen sein.
4. Zielorientierte Ausführung
Definieren Sie Erfolgskriterien. Iterieren Sie, bis sie verifiziert sind.
Definieren Sie für jede Aufgabe überprüfbare Erfolgskriterien, BEVOR Sie Code schreiben:
| Aufgabe | Erfolgskriterien |
|---|---|
| Landingpage in WP-Theme konvertieren | Theme aktiviert sich ohne Fehler. Die Startseite wird visuell identisch zur Quelle gerendert. Alle Patterns sind im Site Editor bearbeitbar. |
| theme.json generieren | JSON ist gegen Schema v3 valide. Farbpalette und Typografie-Skala entsprechen der Quelle. |
| Ein Block-Pattern erstellen | Pattern erscheint im Inserter unter der richtigen Kategorie. Inhalt ist bearbeitbar. Keine Inline-Stile. Alle Strings sind übersetzbar. |
| WooCommerce-Unterstützung hinzufügen | Produktarchiv-/Einzel-/Warenkorb-/Checkout-Vorlagen werden gerendert. HPOS-Kompatibilität deklariert. WC-Blöcke laden korrekt. |
| Editor-Parität beheben | Jede CSS-Regel im Frontend hat eine entsprechende Regel in editor.css. Visuelle Abweichung zwischen Editor und Frontend ist null. |
Transformieren Sie imperative Aufgabenbeschreibungen in überprüfbare Ziele, bevor Sie beginnen:
| Anstatt... | Transformieren zu... |
|---|---|
| „Lass es richtig aussehen“ | „Startseite rendert visuell passend zum Quell-HTML. Keine Inline-Stile.“ |
| „Behebe den PHP-Fehler“ | „WP_DEBUG aktiviert, Fehler reproduziert, Fix angewendet – debug.log ist sauber.“ |
| „Füge WooCommerce-Unterstützung hinzu“ | „Warenkorb, Checkout und Produktarchiv rendern ohne Warnungen. HPOS deklariert.“ |
| „Mache Patterns bearbeitbar“ | „Alle Patterns im Site Editor Inserter. Jedes Text-/Bildelement bearbeitbar, ohne die Pattern-Datei zu berühren.“ |
Geben Sie bei mehrstufigen Aufgaben einen kurzen Plan mit Überprüfung bei jedem Schritt an:
1. Quell-HTML prüfen → verifizieren: Komponenten-Map erstellt, keine Unklarheiten mehr
2. theme.json generieren → verifizieren: JSON valide, alle Design-Tokens zugeordnet
3. Vorlagen erstellen → verifizieren: Alle Seiten haben entsprechende FSE-Vorlagen
4. Patterns registrieren → verifizieren: Patterns erscheinen im Inserter, Inhalt ist bearbeitbar
5. Assets einbinden → verifizieren: Keine Konsolenfehler, Styles laden korrekt
6. Barrierefreiheitsprüfung → verifizieren: Skip-Link funktioniert, Kontrastverhältnisse bestanden, ARIA-Attribute vorhanden
Starke Erfolgskriterien ermöglichen unabhängiges Arbeiten. Schwache Kriterien („mach es gut aussehen“) erfordern ständige Klärungen.
Wann dieses Skill verwendet werden soll
Dieses Skill auslösen, wenn der Benutzer Folgendes möchte:
- Statische HTML/CSS/JS in ein WordPress-Theme konvertieren
- Ein Full-Site-Editing (FSE)-Theme von Grund auf erstellen
- theme.json, Block-Patterns oder Block-Vorlagen generieren
- Eine bestehende Landingpage, Portfolio- oder E-Commerce-Website zu WordPress portieren
- Ein WooCommerce-kompatibles Block-Theme erstellen
- Einzelne Block-Patterns oder Vorlagen aus HTML-Snippets generieren
Benutzerdefinierte Schrägstrich-Befehle
| Befehl | Zweck | Referenzdatei |
|---|---|---|
/convert-to-wp-theme | Vollständige Konvertierung eines HTML/CSS/JS-Projekts in ein vollständiges Block-Theme | commands/convert-to-wp-theme.md |
/scaffold-wp-theme | Leeres Block-Theme-Grundgerüst erstellen (keine Quellkonvertierung) | commands/scaffold-wp-theme.md |
/wp-pattern | Einzelnen HTML-Abschnitt in ein registriertes Block-Pattern konvertieren | commands/wp-pattern.md |
/wp-theme-json | theme.json aus einem Designsystem / CSS Custom Properties generieren | commands/wp-theme-json.md |
/wp-template | Einzelne HTML-Seite in eine FSE-Vorlage konvertieren | commands/wp-template.md |
/wp-block | Benutzerdefinierten Block erstellen (block.json, edit.js, save.js/render.php, CSS) | commands/wp-block.md |
/wp-migrate | Bestehende WP-Inhalte (Classic Editor, ACF, Widgets, CPTs, Shortcodes) zu einem Block-Theme migrieren | commands/wp-migrate.md |
/wp-plugin-theme | Plugin-Abhängigkeiten deklarieren und pluginspezifisches CSS / Kompatibilitätscode generieren | commands/wp-plugin-theme.md |
/wp-variation | Stilvariation generieren (styles/*.json) – Dark Mode, Farbpalettenwechsel, Schriftwechsel | commands/wp-variation.md |
/wp-classic-to-fse | Bestehendes klassisches WordPress-Theme (PHP-Vorlagen) in ein FSE-Block-Theme konvertieren | commands/wp-classic-to-fse.md |
/wp-debug | Systematische Fehlersuche bei WordPress-Block-Theme-Problemen (weißer Bildschirm, Editor-Fehler, Stilregressionen) | commands/wp-debug.md |
Wenn der Benutzer einen dieser Befehle eingibt, lesen Sie die entsprechende Befehlsdatei im commands/-Verzeichnis und führen Sie den dort definierten Arbeitsablauf aus.
Kernarbeitsablauf
Für JEDE Konvertierungsanfrage (ob durch Schrägstrich-Befehl oder natürliche Sprache ausgelöst):
Schritt 1: Denken – Erfassen & Klären (Grundsatz 1)
Sammeln Sie diese Eingaben (fragen Sie nur, wenn nicht angegeben):
- Theme-Identität (Name, Slug, Autor, Beschreibung)
- Quellprojekttyp (Landingpage, Blog, E-Commerce, Portfolio, SaaS)
- Zu konvertierende HTML-Dateien
- Design-Tokens (Farben, Schriften, Abstände)
- Build-System-Präferenz (Vite 6 Standard, oder wp-scripts, oder keines)
- WooCommerce-Unterstützung (ja/nein)
Geben Sie vor dem Fortfahren explizit an:
- Was Sie annehmen (z. B. „Ich gehe davon aus, dass Sie eine GPL-2.0-or-later-Lizenzierung wünschen, da Sie die Einreichung bei WordPress.org erwähnt haben“)
- Was Sie NICHT tun (z. B. „Ich werde kein WooCommerce-Support-Grundgerüst erstellen, da Sie kein E-Commerce erwähnt haben“)
- Unklarheiten, die geklärt werden müssen (z. B. „Ihr Hero verwendet einen Video-Hintergrund – soll dies ein
core/covermit Video oder ein benutzerdefiniertes Pattern mit einem<video>-Tag sein?“)
Für Standardwerte, wenn der Benutzer nichts sagt, verwenden Sie die Tabelle in references/defaults.md.
Schritt 2: Planen – Erfolgskriterien definieren (Grundsätze 1 + 4)
Bevor Sie Code schreiben, erstellen Sie einen Konvertierungsplan, der Folgendes abbildet:
- Jede Quell-HTML-Datei → WordPress-Vorlage
- Jeder wiederkehrende Abschnitt → Block-Pattern
- Header/Footer → Vorlagenteile
- Interaktive Komponenten → JS-Strategie (Interactivity API bevorzugt, klassisches Einbinden für komplexe Bibliotheken – lesen Sie
references/modern-blocks.md) - Design-Tokens → theme.json-Struktur
- Dynamische Datenbedarfe → Block Bindings API-Kandidaten
Geben Sie auch die Erfolgskriterien für diese spezifische Konvertierung an:
ERFOLGSKRITERIEN:
1. Theme aktiviert sich auf WordPress [Version] ohne PHP-Fehler oder Hinweise
2. [Liste der Seiten] rendern visuell passend zum Quell-HTML
3. Alle Patterns erscheinen im Site Editor Inserter unter [Kategorien]
4. Alle interaktiven Komponenten funktionieren (auflisten)
5. Keine Inline-Stile im Block-Markup
6. Alle Strings übersetzungsbereit
7. PHPCS WordPress-Extra besteht mit null Fehlern
8. [Projektspezifische Kriterien]
Zeigen Sie diesen Plan dem Benutzer. Holen Sie die Bestätigung ein, bevor Sie mit der Dateigenerierung fortfahren (es sei denn, der Benutzer sagt explizit „bau es einfach“).
Schritt 3: Ausführen – 10-Phasen-Methodik (Grundsatz 2)
Befolgen Sie die in references/methodology.md dokumentierten Phasen. Wenden Sie bei jeder Phase „Einfachheit zuerst“ an – generieren Sie nur das, was das Projekt benötigt:
- Prüfen & Extrahieren – Quelle parsen, wiederverwendbare Komponenten identifizieren
- theme.json – Schema v3 mit vollständigen Einstellungen + Stilen generieren (inkl. Abschnittsstile, Abmessungen, Position)
- Vorlagen & Teile – HTML-Seiten in FSE-Block-Markup konvertieren
- Block-Patterns – Abschnitte als wiederverwendbare Patterns registrieren
- Block-Stile & Variationen – Benutzerdefinierte Varianten über theme.json + PHP registrieren
- JavaScript-Integration – Interactivity API für interaktive Patterns;
wp_enqueue_script()nur für komplexe Bibliotheken. Lesen Sie zuerstreferences/modern-blocks.md. - functions.php & inc/ – Bootstrap-Dateien gemäß WP-Coding-Standards
- Barrierefreiheit & Leistung – WCAG 2.1 AA + Core Web Vitals + pro-Block-CSS-Laden + Schriftart-Preloading
- i18n – Übersetzungsbereite Strings überall
- README & Dokumentation – WordPress.org-formatierte readme.txt
Einfachheitsprüfungen während der Ausführung:
- Generiere ich eine Datei, die für dieses spezifische Projekt nicht benötigt wird? → Entfernen.
- Füge ich ein Pattern hinzu, das der Benutzer nicht verlangt hat? → Entfernen.
- Schreibe ich CSS für etwas, das theme.json behandelt? → In theme.json verschieben.
- Erstelle ich eine Abstraktion, die nur einmal verwendet wird? → Inline setzen.
- Kann diese 200-Zeilen-Datei auf 50 Zeilen reduziert werden? → Umsschreiben.
Schritt 4: Dateien ausgeben (Grundsatz 3)
Verwenden Sie die in references/file-structure.md dokumentierte Dateistruktur. Geben Sie jede Datei mit einem klaren Header aus:
=== DATEI: {{theme-slug}}/path/to/file.ext ===
<Inhalt>
Bei großen Projekten (10+ HTML-Seiten oder WooCommerce-Themes) teilen Sie die Auslieferung auf 3 Durchgänge auf, indem Sie references/multi-turn-strategy.md verwenden.
Chirurgische Präzision für bestehende Themes: Wenn Sie ein bestehendes Theme ändern, geben Sie NUR die geänderten Dateien aus. Fügen Sie eine Diff-Zusammenfassung bei, die genau zeigt, was geändert wurde und warum.
Schritt 5: Überprüfen – Nach der Generierung (Grundsatz 4)
Führen Sie zuerst den automatisierten Doctor aus. Bevor Sie die Ausgabe dem Benutzer bereitstellen, führen Sie Folgendes aus:
node scripts/doctor.mjs <theme-dir>
Dies führt alle vier Qualitätsprüfungen durch (theme.json-Validierung, Block-Markup-Linting, Pattern-Registrierungsprüfung, i18n-Abdeckung). Erklären Sie den Erfolg erst, wenn der Doctor mit 0 beendet wird. Wenn er mit einem Nicht-Null-Exit-Code beendet wird, kehren Sie zur relevanten Phase zurück und beheben Sie jeden gemeldeten Verstoß, bevor Sie fortfahren.
Geben Sie dann Folgendes an:
- Installationsanweisungen
- Checkliste nach der Installation (aktivieren, Startseite festlegen, erforderliche Plugins installieren)
- Build-Befehle (
npm install,npm run dev,npm run build) - Abschnitt „Getroffene Entscheidungen“ – jede Annahme mit Begründung aufgeführt
- Überprüfungsschritte – wie bestätigt wird, dass jedes Erfolgskriterium erfüllt wurde:
ÜBERPRÜFUNG:
✅ node scripts/doctor.mjs <theme-dir> → Exit 0 (alle Prüfungen bestanden)
✅ Theme aktivieren → Keine PHP-Fehler in debug.log bestätigen
✅ Startseite besuchen → Visuelle Übereinstimmung mit Quelle bestätigen
✅ Site Editor öffnen → Alle Vorlagen aufgelistet bestätigen
✅ Block einfügen → Alle Patterns unter den richtigen Kategorien bestätigen
✅ `npx phpcs --standard=WordPress-Extra .` ausführen → Null Fehler bestätigen
✅ Browser-Konsole prüfen → Null JS-Fehler bestätigen
✅ Lighthouse ausführen → Barrierefreiheitspunktezahl ≥ 90 bestätigen
Wenn ein Überprüfungsschritt fehlschlägt, kehren Sie zur relevanten Phase zurück und beheben Sie es, bevor Sie die Fertigstellung melden. Erklären Sie den Erfolg nicht über einen fehlgeschlagenen Check hinweg.
Wenn der Benutzer ein Problem mit einem generierten Theme meldet, verweisen Sie ihn an /wp-debug. Siehe references/troubleshooting.md für die vollständige Referenz von Symptom → Ursache → Lösung.
Qualitätsregeln – Nicht verhandelbar
Diese Regeln gelten für JEDE generierte Datei. Siehe references/quality-rules.md für vollständige Details.
❌ NIE:
- Inline-
style=""-Attribute im Block-Markup <style>- oder<script>-Tags innerhalb von Vorlagen/Teilen/Patterns- Hartcodierte Farben/Abstände in CSS –
var(--wp--preset--color--{slug})verwenden - Veraltete WordPress-Funktionen
- Nicht maskierte Ausgabe (immer
esc_htm...verwenden)