web-to-design-md

Website zu DESIGN.md

Überblick

Nutze dieses Skill, um eine echte Website in ein wiederverwendbares design.md- oder DESIGN.md-Dokument sowie eine begleitende HTML-Vorschau zu verwandeln.

Das Ziel ist nicht, die Website zu klonen. Das Ziel ist, sie tief genug zu analysieren, dass ein anderer Agent dieselbe Designsprache, denselben Content-Ton und dasselbe Interaktionsgefühl nachbilden kann, ohne die Original-Website sehen zu müssen.

Die HTML-Vorschau ist eine praktische Prüffläche. Sie sollte das Markdown in ein auf einen Blick erfassbares Design Board übersetzen, damit der Nutzer Palette, Typografie, Abstände, Komponenten-Hinweise und die rohe Markdown-Quelle inspizieren kann, ohne die Website erneut öffnen zu müssen.

Universelle Browser-Regel

Dieses Skill sollte immer zuerst agent-browser verwenden.

• Verwende agent-browser open, agent-browser wait und insbesondere agent-browser eval als primären Extraktions-Workflow.
• Beginne nicht damit, zu prüfen, welche App oder Plattform der Nutzer verwendet.
• Verzweige die Logik nicht danach, ob der Nutzer Codex, Trae, Claude, Cursor oder einen anderen Host verwendet.
• Beginne nicht damit, zu prüfen, ob der aktuelle Projektordner Playwright, Chrome CLI oder ein lokales Browserpaket enthält.
• Falls agent-browser nicht verfügbar ist, hilf dem Nutzer, es zu installieren oder auf dem PATH verfügbar zu machen, und fahre dann mit demselben Workflow fort.
• Wechsle nicht stillschweigend zu Playwright, Chrome CLI oder screenshot-basierter Extraktion, es sei denn, der Nutzer bittet explizit um einen separaten Fallback.

Arbeitsweise

Arbeite browser-zuerst und evidenz-zuerst.

• Bevorzuge agent-browser gegenüber rohen HTML-Abrufen. Eine Live-Website versteckt oft wichtiges Verhalten hinter Hydrierung, Scroll-Zustand, Hover-Zustand oder responsiven Layout-Änderungen.
• Behandle agent-browser eval als primäre Extraktionsebene. Die Hauptevidenz sollte aus DOM-Struktur, gerendertem HTML, berechneten Styles, CSS-Variablen, lesbaren Stylesheet-Regeln und Interaktionszuständen stammen, die innerhalb der Browser-Laufzeit gesammelt wurden.
• Verwende Screenshots nicht als Standard-Evidenzquelle. Wenn agent-browser eval oder ein äquivalenter Page-Eval-Pfad verfügbar ist, nutze DOM, berechnete Styles, CSS-Variablen, lesbare Stylesheet-Regeln und extrahierten Text als primäre Evidenz.
• Verwende Screenshots nur als optionalen letzten Ausweg zur Gegenprüfung, wenn DOM-Evidenz nicht ausreicht oder der Nutzer explizit um einen visuellen Überprüfungsdurchlauf bittet.
• Falle nicht stillschweigend auf Playwright oder Chrome CLI zurück. Falls agent-browser nicht verfügbar ist, erkenne das explizit und hilf dem Nutzer, es zu installieren oder verfügbar zu machen.
• Behandle statische Quelldateien als unterstützende Evidenz, nicht als primäre Wahrheitsquelle.
• Übersetze technische Details in eine Designsprache. Gib CSS nicht blind weiter; destilliere es in etwas, das ein Agent tatsächlich verwenden kann.
• Unterscheide beobachtete Fakten von Schlussfolgerungen. Wenn etwas ein Urteil oder eine wahrscheinliche Regel ist und nicht ein direkt beobachteter Wert, kennzeichne es deutlich.
• Behandle die HTML-Vorschau als Teil des Standard-Liefergegenstands, nicht als optionales Extra, es sei denn, der Nutzer lehnt dies explizit ab.

Vorbereitung

1. Normalisiere das Ziel auf eine oder mehrere URLs.
2. Prüfe, ob agent-browser bereits nutzbar ist.
3. Falls agent-browser fehlt, verwende scripts/check-browser-tooling.mjs und hilf dann dem Nutzer, agent-browser zu installieren oder verfügbar zu machen.
4. Durchsuche den aktuellen Ordner nicht als primären Pfad nach Playwright, Chrome CLI oder lokalen Browser-Executables.
5. Falle nicht stillschweigend auf Playwright oder Chrome CLI zurück, es sei denn, der Nutzer bittet explizit um diesen Fallback.
6. Setze die Standard-Markdown-Ausgabedatei auf DESIGN.md.
7. Setze die Standard-Begleitvorschaudatei auf denselben Basisnamen plus -preview.html, z. B. DESIGN-preview.html oder design-preview.html.
8. Wenn der Nutzer explizit nach design.md, einem benutzerdefinierten Dateinamen oder einem benutzerdefinierten Ordner fragt, erfülle das genau und behalte die HTML-Vorschau daneben, es sei denn, der Nutzer bittet darum, dies nicht zu tun.
9. Wenn mehrere URLs angegeben werden, analysiere jede unabhängig und synthetisiere dann nur dann ein gemeinsames Design-System, wenn die visuelle Sprache über die Seiten hinweg eindeutig konsistent ist.

Browser-Tooling-Bootstrap

Behandle die Einrichtung des Browser-Toolings als Teil des Skills, nicht als separate Aufgabe des Nutzers.

Erkennung

Prüfe in dieser Reihenfolge:

• ob agent-browser bereits aufrufbar ist
• wenn nicht, ob es sofort installiert oder verfügbar gemacht werden kann

Das gebündelte Prüfskript berichtet:

• ob node und npm verfügbar sind
• ob agent-browser aufrufbar ist
• welches Tool als nächstes verwendet werden sollte
• ob eine Installation empfohlen wird

Standardinstallation

Falls agent-browser nicht verfügbar ist, hilf dem Nutzer, es zu installieren oder auf dem PATH verfügbar zu machen, und verifiziere es mit agent-browser --help, bevor du das Skill verwendest.

Installationsverhalten

• Erkläre, dass eine Installation erforderlich ist, damit das Skill konsistent agent-browser verwenden kann.
• Wenn der erste Installationsversuch aufgrund von Netzwerk- oder Sandbox-Einschränkungen fehlschlägt, fordere die erforderliche Genehmigung an und wiederhole den Vorgang.
• Wenn die Installation erfolgreich ist, fahre direkt mit der Seitenanalyse im selben Durchgang fort.
• Wenn die Installation fehlschlägt, teile dem Nutzer klar mit, was fehlt, und stoppe, anstatt stillschweigend auf einen anderen Extractor zu wechseln.
• Stufe nicht stillschweigend auf statisches HTML-Scraping herab, nur weil das Tooling fehlt.

Erforderliche Extraktionsdurchgänge

Verwende die Checkliste in references/website-reading-checklist.md, wenn du eine tiefere Erinnerung an das benötigst, was zu inspizieren ist.

1. Seitenumfang bestimmen

• Identifiziere den Seitenzweck.
• Identifiziere, ob die Seite Marketing, Produkt, Dashboard, Dokumentation, E-Commerce, redaktionell oder gemischt ist.
• Identifiziere die wichtigen sichtbaren Abschnitte von oben nach unten.
• Notiere alle gesperrten oder unzugänglichen Bereiche, anstatt sie zu erfinden.

2. Basislinie erfassen

• Analysiere die Seite zuerst auf dem Desktop.
• Analysiere sie auch auf Tablet und Mobilgerät, wenn sich das Layout wesentlich ändert.
• Scrolle die gesamte Seite langsam, bevor du etwas schreibst, damit du keine verzögerten Animationen, klebrige UI oder progressive Offenlegung übersiehst.
• Erfasse browser-seitige Code-Evidenz, während die Seite live ist: gerendertes HTML, outerHTML wichtiger Knoten, root CSS-Variablen, lesbare Stylesheet-Regeln und berechnete Styles für repräsentative Komponenten.
• Bevorzuge direkte agent-browser eval-Aufrufe oder ein von agent-browser gesteuertes Wrapper-Skript, anstatt zu einem anderen Browser-Stack zu wechseln.
• Verwende scripts/extract-browser-evidence.mjs nur, wenn der Nutzer explizit ein Shell-generiertes JSON-Artefakt wünscht, während er dennoch bei agent-browser bleibt.
• Halte während des Standarddurchgangs nicht für Screenshot-Aufnahmen an. Verwende Seitenauswertung, um die Struktur und Styles direkt aus der laufenden Seite zu extrahieren.

2.1 Bevorzugter Eval-Workflow

Wenn agent-browser eval oder ein äquivalenter Browser-Eval-Pfad verfügbar ist, befolge diese Reihenfolge:

1. öffne die Seite
2. warte auf Laden und Hydrierung
3. scrolle die Seite, um Lazy-Content und Sticky-State-Änderungen auszulösen
4. extrahiere gerendertes HTML für repräsentative Knoten
5. extrahiere berechnete Styles für Überschriften, Buttons, Karten, Navigation und Abschnittsumschläge
6. extrahiere root CSS-Variablen und lesbare Stylesheet-Regeln
7. extrahiere sichtbare Textausschnitte und CTA-Kopien
8. untersuche Hover-, Active-, Sticky- oder Expanded-Zustände durch DOM- oder berechnete Style-Änderungen

Ersetze die Schritte 4 bis 8 nicht durch Screenshots.

3. Design-System extrahieren

Erfasse die wiederverwendbaren Regeln, nicht nur die seiten-spezifische Oberfläche:

• Farben und ihre Rollen
• Light- und Dark-Theme-Varianten, wenn die Site sie unterstützt
• Typografie-Hierarchie
• Abstandsrhythmus und Grid-Verhalten
• Eckenradius-Sprache
• Randbehandlung
• Schatten und Oberflächenstaffelung
• Bildstil
• Symbolstil
• Bewegungs- und Übergangsstil
• Dichte und Weißraum-Philosophie
• Stylesheet- und CSS-Variablen-Konventionen, wenn beobachtbar
• DOM-Muster, die erklären, wie wiederholte Komponenten tatsächlich strukturiert sind

4. Komponenten und Zustände extrahieren

Untersuche die wichtigsten wiederholten Muster:

• Navigation
• Ankündigungsbanner
• Hero-Blöcke
• Buttons und Links
• Karten
• Badges
• Formulare und Eingabefelder
• Tabs oder Pills
• Akkordeons
• Tabellen
• Footer

Für jede wichtige Komponente untersuche die relevanten sichtbaren Zustände:

• Standard
• Hover
• Aktiv oder ausgewählt
• Fokussiert, wenn sichtbar
• Deaktiviert, wenn sichtbar
• Gescrollte oder sticky-Varianten
• Offene oder erweiterte Zustände
• Light-Mode- und Dark-Mode-Varianten, wenn die Site Theme-Umschaltung unterstützt

5. Interaktionsverhalten extrahieren

Höre nicht bei statischen Grafiken auf.

Dokumentiere:

• was sich beim Scrollen ändert
• was sich beim Hover ändert
• was sich beim Klick ändert
• was sich beim Umschalten zwischen Light- und Dark-Mode ändert
• was animiert in den Blick kommt
• ob Karussells, Tabs oder sticky Sidebars klickgesteuert, scrollgesteuert oder zeitgesteuert sind
• wie schnell die Bewegung wirkt und ob sie subtil, knackig, filmisch, verspielt oder zurückhaltend ist
• welche CSS- oder DOM-Zustände sich während dieser Interaktionen ändern, wenn sie im Browser beobachtbar sind

6. Content und Markenstimme extrahieren

Erfasse den Ton, der das Design prägt:

• Überschriftenstil
• CTA-Formulierung
• Satzdichte
• Produkt-Framing
• Vertrauenssignale
• Benennungsmuster von Funktionen
• ob der Text technisch, verspielt, hochwertig, direkt, akademisch oder konversationell ist

Dies ist wichtig, weil eine gute DESIGN.md sowohl die visuelle Darstellung als auch den Präsentationsstil leiten sollte.

6.1 Theme-Mode-Durchlauf

Wenn die Site die Umschaltung des Erscheinungsbilds unterstützt:

• löse den Light- und Dark-Mode-Umschalter direkt im Browser aus
• extrahiere DOM- und berechnete Style-Evidenz für beide Modi
• dokumentiere, welche Tokens invertiert werden, im Vergleich zu welchen Akzenten stabil bleiben
• notiere, ob Bilder, Schatten, Rahmen, Karten und Code-Blöcke ihre Behandlung zwischen den Modi ändern
• übernimm beide Modi in das endgültige Markdown und die HTML-Vorschau

Ausgabevertrag

Schreibe das endgültige Dokument unter Verwendung der Struktur in assets/DESIGN.template.md.

Nachdem das Markdown geschrieben ist, generiere eine begleitende HTML-Vorschau mit scripts/render-design-preview.mjs, wenn möglich.

Wenn Browser-Tooling verfügbar ist, bevorzuge einen DOM-und-Style-Extraktionsdurchgang vor dem Schreiben. Die erwartete Evidenzreihenfolge ist:

1. gerendertes HTML und Schlüsselknotenstruktur
2. berechnete Styles und CSS-Variablen
3. Interaktionszustands-Diffs
4. optionaler Screenshot-Abgleich nur, wenn der Nutzer explizit danach fragt oder DOM-Evidenz mehrdeutig ist

Wenn die Seite Light- und Dark-Themes unterstützt, erfordert der Ausgabevertrag auch:

1. explizite Theme Modes-Dokumentation in DESIGN.md
2. getrennte Light-Mode- und Dark-Mode-Token-Notizen, wenn sie sich wesentlich unterscheiden
3. einen sichtbaren Light-/Dark-Theme-Zusammenfassungsblock in der begleitenden HTML-Vorschau

Das Dokument sollte normalerweise diese Abschnitte enthalten:

1. Visual Theme & Atmosphere
2. Color Palette & Roles
3. Typography Rules
4. Component Stylings
5. Layout Principles
6. Depth & Elevation
7. Do's and Don'ts
8. Responsive Behavior
9. Agent Prompt Guide

Füge optionale Anhänge nur hinzu, wenn sie echten Mehrwert bieten:

• Interaction Patterns
• Content & Messaging Patterns
• Observed Pages
• Evidence Notes

Bevorzuge innerhalb dieser Abschnitte reichhaltigere Stitch-artige Unterabschnitte, wenn die Site sie unterstützt:

• Key Characteristics
• Primary, Interactive, Neutral Scale, Surface & Overlay, Shadows & Depth
• Font Family, Hierarchy, Principles
• Buttons, Cards & Containers, Inputs & Forms, Navigation, Image Treatment, Distinctive Components
• Spacing System, Grid & Container, Whitespace Philosophy, Border Radius Scale
• Breakpoints, Touch Targets, Collapsing Strategy
• Quick Color Reference, Example Component Prompts, Iteration Guide

Belasse das Dokument nicht auf dem Niveau einer zusammenfassenden Übersicht, wenn die Site genügend Evidenz für präzisere Angaben bietet.

HTML-Vorschau-Vertrag

Generiere standardmäßig eine HTML-Datei neben dem Markdown.

Die Vorschau sollte:

• das endgültige DESIGN.md als Quelle der Wahrheit verwenden, nicht eine separate, manuell gepflegte Zusammenfassung
• eine feste Vorschau-Shell-Vorlage verwenden, kein neu erfundenes HTML-Framework pro Durchlauf
• die nützlichsten visuellen Regeln links anzeigen, z. B. Überblick, Palette, Typografie, Abstände, Radius, Buttons, Karten, Tiefe und responsive Notizen
• die Markdown-Quelle in einem dedizierten Bereich sichtbar halten, damit der Nutzer das Originaldokument schnell inspizieren oder kopieren kann
• sich wie ein poliertes Design Board anfühlen, nicht wie ein einfaches Markdown-Rendering
• die extrahierten Design-Tokens verwenden, wo praktisch, sodass die Vorschau selbst das dokumentierte System widerspiegelt

Verwende assets/design-preview-shell.template.html als Standard-Shell, wenn verfügbar. Behandle diese Vorlage als stabile Infrastruktur und fülle nur die dokumentierten Tokens und Inhalte ein, es sei denn, der Nutzer bittet explizit um eine neue Layout-Richtung.

Wenn der Nutzer eine visuelle Referenz für das Layout bereitstellt, folge ihr genau genug, damit das HTML erkennbar in derselben Familie liegt, während es dennoch aus den Markdown-Daten generiert wird.

Syntheseregeln

Beim Schreiben der endgültigen Datei:

• Bevorzuge semantische Namen gegenüber rohen Token-Bezeichnern.
• Gib genaue Hex-Werte an, wenn Farbgenauigkeit wichtig ist.
• Übersetze Radius, Abstände, Schatten und Schriftgrößenskalen in Klartext, den ein anderer Agent sofort verwenden kann.
• Halte das Dokument meinungsstark und nutzbar; vermeide große Datenmüllhalden.
• Erkläre funktionale Rollen, nicht nur das Aussehen.
• Gruppiere wiederkehrende Muster zu einem System.
• Bewahre Nuancen. Wenn die Site zwei visuelle Modi mischt, beschreibe beide und wann jeder erscheint.
• Bevorzuge präzise numerische Details, wenn sie beobachtbar sind: genaue Hex-Werte, Schriftgrößen, Zeilenhöhen, Buchstabenabstände, Radius-Werte, Abstandseinheiten und mehrschichtige Schattenformeln.
• Füge eine kurze Philosophie oder Begründung hinzu, wenn ein Muster zentral für die Identität der Site ist, z. B. "Schatten-als-Rand" oder "Kompression als Identität".
• Füge komponentenspezifische Implementierungshinweise hinzu, wenn sie einem anderen Agenten helfen, passende UI ohne die Quellseite zu erstellen.
• Füge prompt-ready Beispiele in den Agent Prompt Guide für mindestens Hero, Card, Button oder Navigationsmuster auf substanziellen Websites ein.
• Wenn einige Werte basierend auf Beobachtungen geschlussfolgert werden und nicht direkt observiert, kennzeichne sie deutlich, aber halte sie dennoch nützlich.

Gut:

• "Primäre Aktionen verwenden ein kühles elektrisches Blau #3B82F6 (inferred from computed style on hover and button backgrounds)"

Nicht gut:

• "Die Site verwendet hauptsächlich Blau."

Schluss

Nachdem das Markdown und die HTML-Vorschau geschrieben sind:

• Bestätige dem Nutzer, was erstellt wurde und wo die Dateien liegen.
• Biete die nächsten sinnvollen Schritte an, z. B. "Soll ich die beschriebene Hero-Sektion auf Basis dieser Designregeln implementieren?" oder "Soll ich die Vorschau im Browser öffnen?"
• Füge keine nicht angeforderte Code-Erstellung hinzu, es sei denn, der Nutzer bittet darum.