moraneus/preview-first

Was macht preview-first?

Schau, bevor du baust. Diese Fähigkeit fügt eine Designphase ein, bevor Anwendungscode geschrieben wird: Der Entwickler sieht mehrere vollständige, klar unterschiedliche Designrichtungen in seinem Browser, wählt eine aus, und die Wahl wird zu einem schriftlichen Vertrag, dem jede spätere Sitzung folgt.

Dies ist eine Design-Studio-Phase, kein Website-Generator. Die Fähigkeit schreibt niemals den Anwendungscode des Entwicklers. Sie produziert eine Entscheidung und einen Vertrag. Skripte sind deterministisch und verwenden die Standardbibliothek von Python; das Urteilsvermögen (Lesen des Briefings, Benennen der Richtungen, Schreiben von Texten) liegt bei Ihnen.

Wann es ausgeführt und angeboten werden soll

Führe die vollständige Phase aus, wenn der Entwickler kurz davor ist, ein Webprojekt zu starten, neu zu starten oder umzugestalten: "Baue mir eine Landingpage für X", "Starte das Frontend", "Mir gefällt nicht, wie das aussieht", "Wähle Farben und Schriften" oder ein explizites /preview-first.

Biete es in einer Zeile an, wenn ein Projekt bereits UI-Code hat, aber keine design/DESIGN.md: "Möchtest du zuerst Designrichtungen sehen? Ich kann das aktuelle Aussehen neben Alternativen zeigen." Wenn angenommen, importiere das vorhandene Aussehen als eine Richtung (siehe Importe), damit es auf Augenhöhe verglichen wird.

Führe es niemals für kleine Änderungen an einer bereits gestalteten App aus ("Füge einen Button hinzu", "Korrigiere den Abstand"). Wenn design/DESIGN.md existiert, springe zu "Nach der Übergabe".

Der Ablauf

Alle Skripte befinden sich im scripts/-Verzeichnis dieser Fähigkeit. Führe sie mit python3 (oder uv run python3 aus, wenn das Projekt uv verwendet). Pfade unten sind relativ zum Projektstammverzeichnis.

1. Lies das Projekt, dann stelle höchstens vier Fragen

Lies, was existiert, bevor du fragst: package.json, Tailwind-Konfiguration, CSS-Custom-Properties, ein Logo-SVG, vorhandene Schriftarten, eine README. Alles, was gefunden wird, ist eine Einschränkung, keine Frage.

Frage nur das, was das Repository nicht beantworten kann, in einfacher Sprache, eine Nachricht:

1. Was ist das Produkt und für wen ist es, in einem Satz.
2. Drei Wörter, wie es sich anfühlen soll, oder eine Website, die sie bewundern.
3. Alles Festgelegte: eine Markenfarbe, ein Logo, eine Schriftart, nur hell oder nur dunkel.
4. Welche Art von Seite ist am wichtigsten: Marketing, App, Inhalt oder Shop.

2. Schreibe das Briefing

Normalisiere die Antworten in .design-preview/brief.json:

{
  "product": "Ledgerline, ein Abrechnungstool für freiberufliche Entwickler",
  "audience": "solo-entwickler und kleine Studios",
  "product_type": "product-type.saas",
  "moods": ["präzise", "ruhig", "vertrauenswürdig"],
  "page_type": "marketing",
  "constraints": {"brand_colors": ["#154d8c"], "fonts": [], "scheme": "both"},
  "admired": ["https://linear.app"],
  "words": {"name": "Ledgerline", "tagline": "Rechnungen, die zu deinem Git-Log passen"}
}

Ordne Freitext mit recommend.py --list product-types und --list moods den Knoten-IDs zu. Unbekannte Wörter sind in Ordnung; der Empfehlungsalgorithmus greift auf Aliasse und Token-Überschneidungen zurück. Freitext in product_type wird ebenfalls akzeptiert.

3. Schreibe den Text, dann öffne die Vorschau innerhalb einer Minute

Schreibe zuerst .design-preview/copy.json; es dauert eine kurze Antwort und ist das, was einen Entwurf wie das Produkt und nicht wie eine Vorlage lesen lässt. Verwende die eigenen Nomen des Produkts: Die Navigation sind seine Abschnitte, die Funktionen sind die Dinge, die es tut, die Überschrift ist eine Behauptung, die ein Benutzer wiederholen würde.

{
  "headline": "Live-Ergebnisse für 501, Cricket und Around the Clock",
  "subhead": "Oche behält den Punktestand, damit die Spieler weiterspielen können.",
  "lead": "Gemacht für Pub-Liga-Spieler und Freunde zu Hause.",
  "cta_primary": "Neues Spiel", "cta_secondary": "Fortsetzen",
  "nav": ["Spiele", "Spieler", "Statistiken", "Einstellungen"],
  "features": [{"title": "501 und 301 mit Checkouts", "body": "Jeder verbleibende Punktestand zeigt den Standard-Checkout-Weg."}],
  "proof": "", "meta": {"city": "Leeds", "year": "2026"},
  "footer": "Oche behält den Punktestand."
}

Dann ein Befehl:

python3 <skill>/scripts/quick_start.py --brief .design-preview/brief.json --copy .design-preview/copy.json --count 5 --open

Es empfiehlt Bundles, erstellt directions.json, baut die Vorschau und startet den Server. Gib dem Entwickler sofort die URL. Wenn du --copy überspringst, verwenden die Entwürfe aus dem Briefing abgeleitete Texte; lasse dies niemals in einer Richtung, die du als fertig präsentierst. Verfeinere directions.json (Namen, Begründung, Layout, Programm), während sie schauen, und baue neu; die Seite aktualisiert sich auf dieselbe URL.

Jede Vorschauseite trägt drei Generatoren in ihrer Leiste, damit der Entwickler nie zurückgehen muss, um mehr zu bekommen: Überrasch mich (eine zufällig zusammengestellte Richtung: ein ungenutzter Stil, eine passende Palette und Paarung, eine zufällige Auswahl von Ideen, Abschnitten und Programm), Variationen (fünf Versionen der Richtung, die sie gerade ansehen: gleicher Stil, andere Paletten, Paarungen, Ideen und Programme) und, in der Galerie, Alle Stile anzeigen (eine Richtung pro Stil für dieses Briefing). Jede landet auf dem neuen Entwurf, der dieselben Schaltflächen trägt. Vom Terminal aus: random_direction.py --directions .design-preview/directions.json --build .design-preview [--like B | --all].

3a. Kandidaten-Bundles von Hand

python3 <skill>/scripts/recommend.py --brief .design-preview/brief.json --count 4

Jedes Bundle ist ein Stil, eine Palette, eine Typografie-Paarung, Komponentenbehandlungen, Bewegungsmuster, ein Icon-Set und acht bis zwölf Designideen (ideas: bezogene bewegungen wie eine geteilte Navigation mit Live-Zeit, ein Proben-Hero, riesige Ziffern, Filmkörnung, Klammer-Buttons, ein Kolophon-Footer), mit den Graph-Kanten, die es rechtfertigen, und Live-Alternativen zum Austauschen. Diversität wird erzwungen: unterschiedliche Stilfamilien, höchstens zwei Paletten einer Temperatur, höchstens zwei Paarungen einer Typografie-Kategorie, keine Palette oder Paarung zweimal verwendet. Standardmäßig drei bis fünf Bundles, bis zu acht, wenn der Entwickler darum bittet, mehr zu sehen. Gehe nicht unter drei herunter; wenn das Briefing eng ist (nur dunkel, eine Markenfarbe), sage dies und zeige trotzdem drei.

4. Erstelle directions.json

Wandle Bundles in .design-preview/directions.json um (Schema in knowledge/schema.json, files.directions). Für jede Richtung liefere, was ein Skript nicht kann:

• name: eine Idee, kein Stil ("Ledger", "Greenhouse", "Night shift"). Niemals "Modern" oder "Clean".
• rationale: ein Absatz, der die eigenen Worte des Briefings zitiert und sagt, warum diese Richtung darauf antwortet. Erwähne die eine mutige Wahl und was leise bleibt.
• copy: echter Text aus dem Briefing: Überschrift, Untertitel, zwei Handlungsaufforderungen, vier Navigationsbezeichnungen, drei bis sechs Funktionen mit einem Titel und jeweils einem Satz, eine ehrliche Beweiszeile (oder leer), ein Formulartitel mit Feldbezeichnungen und Submit-Text, eine Fußzeile. Satzfall, aktive Stimme, Produktnomen, keine Em-Dashes, kein Emoji, keine Pfeile, keine "Ob Sie X oder Y sind", keine Trikolons, kein Lorem Ipsum, keine erfundenen Zahlen. Der Text ist über alle Richtungen hinweg gleich, es sei denn, die Stimme einer Richtung unterscheidet sich tatsächlich.
• layout (optional): Überschreibe Abschnittsvarianten; andernfalls wählen die Ideen der Richtung und dann die Standardeinstellungen des Stils.
• bundle.ideas (behalten oder bearbeiten): Die Ideen, die der Empfehlungsalgorithmus angehängt hat. Entferne eine, die nicht zum Produkt passt, füge eine aus recommend.py --list ideas hinzu, wenn das Briefing oder eine bewunderte Website danach fragt. Ideen mit einem Render-Hook ändern den Entwurf; der Rest geht in den Vertrag.
• copy.numbers und copy.stats (optional): Quellenbezogene Zahlen {value, label, source}; der Zahlen-Hero und die Statistik-Wand werden nur gerendert, wenn diese existieren, niemals mit erfundenen Zahlen.
• copy.meta (optional): {"city": "Lisbon"} für die geteilte Navigation, das Kolophon und die Overlay-Uhr.
• Der Produkttyp trägt ein Themen-Kit (Arten von Grafiken, eine Themen-Komponente wie ein Terminal, ein Saldo, ein Zeitplan, ein Komponist, eine Anzeigetafel und die Nomen des Produkts). Der erste Bildschirm und der Abschnitt danach verwenden es, also öffnet sich eine Anzeigetafel auf einem Ergebnis und ein Shop auf Produkten. Setze layout.topic auf none, um die Themen-Komponente zu entfernen.
• overrides (optional): {"brand_primary": "#hex", "brand_accent": "#hex"}, wenn das Briefing eine Markenfarbe festlegt. Der Builder berechnet die Gegenfarben neu und meldet etwaige Kontrastfehler.

Vor dem Bauen führe den Anti-Tell-Check in references/anti-patterns.md für jede Richtung durch. Lehne einen Tell ab, es sei denn, das Briefing hat ausdrücklich danach gefragt, und sage dies dann in der Begründung.

Die Regel für den ersten Bildschirm: Keine Richtung beginnt mit der generischen Vorlage (zentrierte Überschrift, zwei Buttons, ein Screenshot, dann drei identische Karten). Jeder Stil standardmäßig auf ein auf bewunderten Websites beobachtetes Layout-Archetyp (Aussageabsatz mit beschrifteten Zahlen, um einen flachen Kreis gewickelter Text, produkt-zentrierte Bühne, Anzeigeschrift neben einem Objekt, randlose Grafik, Sidebar-Index, Plakattyp) und auf aus der Palette generierte Grafiken (Blaupause, isometrische Figuren, Terminal, Schweizer Komposition, Konturen, Raster, Orbitringe, Aufkleber, Sparklines, eine einzelne Markierung). Behalte diese Standardeinstellungen bei, es sei denn, das Briefing fragt namentlich nach dem vertrauten Aussehen. Mindestens zwei der Richtungen stammen von als distinct markierten Stilen; der Empfehlungsalgorithmus erzwingt dies und stellt auch sicher, dass sich keine zwei Richtungen ein Navigationsgerät, ein Erstbildschirmgerät oder eine Textur teilen.

5. Baue und öffne die Vorschau

python3 <skill>/scripts/build_preview.py --directions .design-preview/directions.json
python3 <skill>/scripts/serve_preview.py --dir .design-preview --open

build_preview.py schreibt .design-preview/: eine Galerie und für jede Richtung eine Stil-Kachel (Palette mit Kontraststufen in beiden Modi, Typografie-Skala, Abstand, Radius, Höhe, Icons, jede Komponente in jedem Zustand, abspielbare Bewegungsmuster), eine entworfene Seite für den Seitentyp des Briefings und eine Geräteansicht, die den Entwurf innerhalb von CSS-gezeichneten Rahmen der gängigsten Telefone, Faltgeräte, Tablets und Laptops in echten Viewport-Größen rendert. Steuerelemente auf jeder Seite tauschen live Palette, Typografie-Paarung, Radius, Dichte, Bewegungsstufe und Thema aus.

serve_preview.py startet einen abgetrennten Localhost-Server, schreibt .design-preview/server.json, gibt die URL aus und kehrt sofort zurück. Füge --vendor-fonts zum Build für eine Offline-Sitzung hinzu; andernfalls zeigt die Kachel eine sichtbare Benachrichtigung an, wenn eine Webschriftart nicht geladen werden konnte.

Wenn der Browser nicht geöffnet werden kann (SSH, Container, CI), gib die URL und die Liste der Richtungen mit jeweils einer Zeile aus und fahre im Chat fort.

6. Sage es dem Entwickler, dann warte

Sage, was du gebaut hast, gib die URL, nenne die Richtungen in jeweils einer Zeile und höre auf. Entscheide nicht für sie, beginne nicht mit dem Coden, frage nicht nach. Der Entwickler kann viel Zeit in der Vorschau verbringen. Wenn sie antworten:

• Wenn .design-preview/selection.json existiert, lies es. Es enthält die Richtungs-ID und die Live-Überschreibungen (Palette, Paarung, Radius, Dichte, Bewegung, Thema), bei denen sie gelandet sind.
• Andernfalls übernimm die Wahl aus ihren Worten ("B", "die dunkle", "A aber mit dem Typ von D") und schreibe selection.json selbst mit den passenden Überschreibungen.
• Bei einer Mutation ("B aber wärmer", "weniger abgerundete Ecken", "tausche die Überschriftenschriftart"), bearbeite directions.json (oder verwende eine Alternative aus dem Bundle), baue neu und verweise sie zurück auf dieselbe URL. Der Server läuft weiter; bitte sie, die Seite zu aktualisieren.
• Bei "Zeig mir mehr", führe recommend.py erneut mit --count 5 oder einem geänderten Briefing aus, füge die neuen Richtungen unter neuen IDs hinzu und baue neu.

serve_preview.py --dir .design-preview --wait 1800 blockiert, bis eine Auswahl existiert, nur für die Skriptnutzung. --status und --stop verwalten den Server.

7. Exportiere den Vertrag

python3 <skill>/scripts/export_design.py --selection .design-preview/selection.json \
  --directions .design-preview/directions.json --project .

Dies schreibt design/DESIGN.md (den Vertrag: Identität, Designideen mit Quellen und Build-Notizen, Palette mit Kontrasttabelle, Typografie, Abstand und Radius, Höhe, Layout, jede Komponente mit Zuständen und Tokens, Bewegungs-Tokens und erlaubte Muster, Ikonografie, Bildsprache, Schreibstil, Zugänglichkeitsminimum, Geräteprüfungen und eine "Nicht-"Liste), design/tokens.json (W3C-Design-Tokens-Format), design/tokens.css, design/tailwind.css, wenn Tailwind v4 erkannt wird, eine Zeigerzeile in CLAUDE.md und einen .gitignore-Eintrag für .design-preview/. Ein erneuter Export behält den Abschnitt "Projektnotizen" und kopiert die vorherigen Dateien in design/history/.

Bestätige in einer kurzen Nachricht, was geschrieben wurde und was der Entwickler committen sollte (design/ und die CLAUDE.md-Zeile). Baue dann unter dem Vertrag.

Nach der Übergabe

Wann immer design/DESIGN.md existiert:

• Lies es vor jeder UI-Änderung. Verwende --pf-*-Tokens aus design/tokens.css, niemals rohe Hex-, Pixel- oder Millisekundenwerte in Komponenten.
• Halte dich an die erlaubten Bewegungsmuster und die Bewegungsstufe. Respektiere die reduzierte Bewegung.
• Führe contrast.py FG BG --role body|label|large|ui für jedes neue Farbpaar aus.
• Folge der "Nicht-"-Liste; wenn eine Anfrage mit dem Vertrag kollidiert, sage dies und biete an, die Phase erneut auszuführen, anstatt stillschweigend abzuweichen.
• Nachdem eine bedeutende Seite erstellt wurde, biete die Geräteprüfung an: Öffne .design-preview/<id>/devices.html?url=http://localhost:PORT/pfad, um die echte Seite in denselben Rahmen zu sehen. Seiten, die Frame-Blockierungs-Header senden, können nicht angezeigt werden; sage dies.
• Halte die freien Abschnitte von design/DESIGN.md (unterhalb des Endmarkers) für Projektentscheidungen.

Importe

Um das aktuelle Aussehen des Projekts oder eine Website, die der Entwickler bewundert, als Richtung zu vergleichen:

python3 <skill>/scripts/import_direction.py --css src/styles.css --into .design-preview/directions.json --name "Heute"
python3 <skill>/scripts/import_direction.py --tailwind tailwind.config.js --into .design-preview/directions.json
python3 <skill>/scripts/import_direction.py --tokens design-tokens.json --into .design-preview/directions.json
python3 <skill>/scripts/import_direction.py --url https://example.com --into .design-preview/directions.json --name "Referenz"

Der Import leitet eine Palette, Paarung und den nächsten Stil ab und baut dann neu. Importierte Paletten werden wie jede andere überprüft; Fehler erscheinen in der Kachel.

Wissen und Aktualisierung

Entscheidungen stammen aus knowledge/graph.json: Stile, Paletten (OKLCH, beide Modi), Typografie-Paarungen, Komponentenbehandlungen, Bewegungsmuster, Produkttypen, Stimmungen, Icon-Sets, Plattformfunktionen, Referenzseiten, verbunden durch gewichtete pairs_with, suits, avoid_with, requires, `ex