MarketingOS Atomic Design System
Verwandelt eine Marke in ein überprüfbares Designsystem: gestaffelte Tokens, eine Spezifikationsdatei pro Komponente,
und eine statische HTML-Referenzseite, aufgebaut Schritt für Schritt mit
menschlicher Freigabe zwischen den Stufen – alles unter einem design-system/ Ordner, den eine
Person oder ein Agent von einem einzigen README aus navigieren kann.
MarketingOS Kontext und Voraussetzungen
Löse das aktive Business-Brain und das Website-Ziel aus der aktuellen Sitzung und ihren Projektaufzeichnungen auf. Lies die BRAIN.md bzw. Agenten-Anweisungen des Brains, CONTEXT.md, Marke, Stimme, Zielgruppe, Angebot und gespeicherte Design-Referenzen, bevor du nach Informationen fragst. Halte den Kontext jedes Unternehmens getrennt. Notiere das Quell-Brain und das Ziel im Design-Brief. Wenn es ohne MarketingOS verwendet wird, arbeite von den bereitgestellten Markendateien aus und identifiziere echte Lücken.
Verwende Bun für die gebündelten TypeScript-Skripte. Falls es fehlt, leite den Benutzer
zu den offiziellen Installationsanweisungen unter https://bun.com/docs/installation.
Löse $SKILL zum tatsächlichen Verzeichnis auf, das dieses geladene SKILL.md enthält; Agenten
installieren an verschiedenen Orten, also nimm keinen bestimmten Home-Pfad an.
Wenn der Benutzer Taste Skill ausgewählt hat, lies zuerst seine installierten Anweisungen und verwende seine Art-Direction und Referenz-Erkenntnisse als Eingaben für dieses Framework. Behalte die Marken-Vereinbarung, das Token-System und die Stufenentscheidungen des Frameworks bei. Taste Skill ist eine separate optionale Abhängigkeit, nicht in diesem Paket enthalten; prüfe seine aktuellen offiziellen Anweisungen unter https://github.com/leonxlnx/taste-skill, wenn eine Installation angefordert wird.
Eine einzige initiale Eingabeaufforderung kann den gesamten Workflow antreiben. Behalte notwendige Entscheidungen und visuelle Freigaben der Stufen im selben Gespräch und setze nach jeder Antwort fort, ohne eine erneute Kopier- und Einfüge-Aufforderung zu benötigen. Halte bei der vom Benutzer angeforderten Stufe an; behandle einen Aufruf nicht als Erlaubnis, Freigaben zu überspringen.
Die Idee
Ein Designsystem scheitert auf eine von zwei Arten. Entweder wird es erfunden – das Modell wählt eine hübsche Palette aus und das Ergebnis ist selbstbewusst, kohärent, aber nicht die Marke. Oder es wird auf einmal gebaut, so dass sich eine falsche Entscheidung an der Basis stillschweigend über zwanzig Seiten ausbreitet, bevor jemand sie sieht.
Diese Fähigkeit adressiert beides. Entdeckung vor Design: finde heraus, was bereits entschieden wurde, und mache die Lücken explizit. Ein Tor zwischen den Stufen: eine Überarbeitung bei den Grundlagen ist eine Fünf-Zeilen-Änderung; dieselbe Überarbeitung bei den Seiten ist zwanzig Seiten.
Router
Finde heraus, wo der Benutzer steht, und handle dann. Frage nicht, welchen Modus sie möchten.
| Situation | Mach dies |
|---|---|
Kein STATE.json und die Entdeckung findet kein bestehendes atomares System | Starte Stage 0 (v2-Layout) |
Der Bericht zeigt existingAtomicSystem, aber es gibt kein STATE.json (handgebautes HTML, z. B. das public/atomic-framework/ eines bestehenden Projekts, stage-*.html eines Legacy-Projekts) | Legacy-System. Erweitere es in seinen eigenen Dateien und Namenskonventionen: füge seine bestehenden Seiten hinzu, behalte seine Markup-/Klasse-/ID-Konventionen bei, dokumentiere neue Arbeiten in einer kleinen ATOMIC-NOTES.md daneben. Seine Konventionen werden beibehalten, aber die Qualitätsschwelle wird nicht gesenkt: sichtbares :focus-visible, 44px-Ziele, Kontrast und eine Inspirationskarte mit „Nehmen“ und „Lassen“ ausgefüllt. Wenn es in einem Schwester-Repository lebt, ist das ein zweites Repository – frage, bevor du dort schreibst (siehe Sicherheit) und gib dem Ziel eine kurze DESIGN-SYSTEM.md, die darauf verweist. Gerüste keine v2, es sei denn, der Benutzer bittet um Migration. Verifiziere mit verify-stage.ts --legacy <verzeichnis>. Details: references/output-structure.md |
design-system/STATE.json mit schemaVersion: 2 | v2-System: melde Status, führe die nächste nicht freigegebene Stufe aus |
STATE.json ohne schemaVersion: 2 (unter docs/design-system/ oder design-system/docs/) | v1-System, erstellt durch die alte Fähigkeit. Erweitere es in seinem v1-Layout und seinen Konventionen (init-system.ts --schema 1, falls eine v1-Gerüstdatei fehlt). Migriere nicht, es sei denn, der Benutzer bittet darum |
| „zu v2 migrieren“ / „in die neue Struktur verschieben“ | Folge der Migrationsprozedur in references/output-structure.md auf einem Branch |
„die Moleküle neu machen“ (oder --stage <n> in der Anfrage) | Baue diese Stufe neu, markiere nachgelagerte als veraltet |
„wo stehen wir“ (oder --status) | Drucke die Leiter mit Status und Version pro Stufe und stoppe dann |
| „nach Figma exportieren“ / „Figma-Variablen“ | Führe export-figma.ts aus – siehe references/figma-export.md. Niemals Teil der Leiter |
Der Benutzer verzichtet explizit auf die Tore („nicht für Freigaben anhalten“; --non-interactive in einem Eval oder CI) | Führe die Leiter ohne Anhalten durch und präsentiere jedes Tor zusammen am Ende – siehe „Verzichtete Freigaben“ unten |
| Ziel-Repository unklar | Frage einmal. Rate nicht zwischen Schwester-Repositories |
Löse zuerst das Ziel-Repository auf. Alles andere ist relativ dazu.
--stage, --status und --non-interactive oben sind Arten, wie ein Benutzer eine
Anfrage an diese Fähigkeit formuliert – Verhaltensmodi, keine Skript-Flags.
Einrichtung
# Setze SKILL auf das tatsächliche Verzeichnis, das das geladene SKILL.md enthält
bun $SKILL/scripts/discover-brand.ts --target <repo> [--siblings <dir>] # Stage 0
bun $SKILL/scripts/init-system.ts --target <repo> # Gerüst v2; --schema 1 nur für ein v1-System alter Fähigkeit
bun $SKILL/scripts/init-system.ts --target <repo> --page <file> # Stage-Seite von der Shell, Schiene + aria-current ausgefüllt
bun $SKILL/scripts/verify-stage.ts --target <repo> --stage <n> # liest schemaVersion; --legacy <dir> für handgebaute Systeme
bun $SKILL/scripts/build-index.ts --target <repo> # nach jeder freigegebenen Stufe
bun $SKILL/scripts/export-tokens.ts --target <repo> # tokens.css → tokens.json + TOKENS.md (build-index führt es aus)
bun $SKILL/scripts/export-figma.ts --target <repo> # optional
discover-brand.ts durchsucht standardmäßig das Ziel und sein übergeordnetes Verzeichnis.
Verwende --siblings <dir>, wenn das aktive Brain woanders lebt. Lese das
aufgelöste Brain explizit, auch wenn die Entdeckung kein passendes Schwester-Repository findet.
Jedes Skript-Flag ist dokumentiert in references/output-structure.md.
Ausgabe (v2) – ein Stamm, eine Einstiegsdatei, eine Spezifikation pro Komponente:
design-system/
├── README.md START HERE – Einstiegspunkt für Menschen und Agenten
├── STATE.json schemaVersion 2, Stufen, Freigaben, Inventar, Version, Themes
├── CHANGELOG.md ein Eintrag pro freigegebener Stufe / Veröffentlichung
├── brief/DESIGN-BRIEF.md
├── tokens/ tokens.css (kanonisch) · tokens.json · TOKENS.md (generiert) · figma/ (optional)
├── foundations/FOUNDATIONS.md
├── components/ INDEX.md (generiert) · atoms/ molecules/ organisms/ templates/ <ID>-<slug>.md
├── rules/RULES.md
└── reference/ statische HTML-Review-Seite (noindex) · styles.css · pages/P-nn-<slug>.html
Warum es so strukturiert ist, das README-Spezifikation, die v1 → v2-Pfadtabelle und die
Migrationsprozedur: references/output-structure.md. Lies es beim
Gerüstbau, beim Schreiben des README oder bei der Migration.
Die Leiter
Sieben Baustufen. Grundlagen stehen vor Atomen, weil du kein Atom ohne Tokens bauen kannst;
Regeln kommen zuletzt, weil Leitplanken aus dem geschrieben werden, was tatsächlich entschieden wurde.
Pfade sind relativ zu design-system/.
| # | Stufe | Produziert |
|---|---|---|
| 0 | Entdecken | brief/DESIGN-BRIEF.md, STATE.json, README.md-Gerüst, CHANGELOG.md, reference/index.html (00) |
| 1 | Grundlagen | tokens/tokens.css (+ generiertes json/md), foundations/FOUNDATIONS.md, reference/foundations.html (01) |
| 2 | Atome | components/atoms/A-nn-*.md, reference/atoms.html (02), reference/icons.html (02A) |
| 3 | Moleküle | components/molecules/M-nn-*.md, reference/molecules.html (03) |
| 4 | Organismen | components/organisms/O-nn-*.md, reference/organisms.html (04) |
| 5 | Vorlagen | components/templates/T-nn-*.md, reference/templates.html (05) |
| 6 | Seiten | reference/pages.html (06), reference/pages/P-nn-*.html, reference/rules.html (07), rules/RULES.md, finales README.md, Version 1.0.0 |
Vollständige Artefakte und Akzeptanzkriterien pro Stufe: references/stage-specs.md.
Lies den Abschnitt für die Stufe, auf der du dich befindest, nicht die ganze Datei.
Stufe 0 — Entdecken
Drei Eingaben, dann Synthese. Führe die ersten beiden gleichzeitig aus; sie hängen nicht voneinander ab.
1. Design-Inspiration. Verwende zuerst gespeicherte Referenzen aus dem aktiven Brain oder dem Taste Skill-Durchlauf; frage nur nach fehlenden Roh-URLs – drei bis sechs, spezifische Seiten anstatt möglichst Homepages. Erstelle einen Schnappschuss jeder mit dem verfügbaren Browser-Tool und überprüfe die tatsächlichen Schriftarten und das Layout. Verwende Interceptor nur, wenn es installiert und für die Sitzung geeignet ist. Extrahiere die berechnete Palette, den Schriftsatz, den Abstands-Rhythmus und die Radien – tatsächliche gerenderte Werte, keine Marketing-Hexs.
2. Mobbin MCP (optional). Für Muster-Fragen, die die URLs nicht beantworten können: wie diese
Kategorie das Onboarding sequenziert, die Preisgestaltung strukturiert, leere Zustände behandelt. Das
MCP kann installiert, aber nicht authentifiziert sein – wenn nur
mcp__mobbin__authenticate / complete_authentication verfügbar sind, führe den
OAuth-Fluss aus und gib dem Benutzer die URL. Wenn er ablehnt, fahre fort und notiere die
Lücke im Brief. Gib niemals vor, dass eine Muster-Recherche stattgefunden hat, wenn dies nicht der Fall ist.
3. Markenentdeckung. Führe discover-brand.ts aus. Es durchsucht die bekannten Pfad-
konventionen im Ziel und seinen Schwester-Repositories, führt Begleitdokumente zusammen und
teilt sie nach Markenfamilien auf, bevor es sie bewertet – so kann ein poliertes Dokument einer anderen
Marke niemals gewinnen. Lies drei Dinge daraus: welches Dokument, ob der visuelle
Vertrag full/partial/verbal-only ist und ob ein atomares System bereits
existiert (wenn ja, erweitere es, anstatt von vorne zu beginnen).
Bestätige die Markenquelle mit dem Benutzer, bevor du etwas kompilierst. Es ist der eine Fehler, der jede nachgelagerte Stufe ungültig macht.
Dann schreibe DESIGN-BRIEF.md. Seine Inspirationskarte benötigt beide Hälften jeder
Zeile – was wir nehmen und was wir bewusst lassen. Die Spalte „Lassen“ ist, wo das
Urteil sitzt; eine Zeile nur mit „Nehmen“ ist eine Collage-Anweisung. Sein §3
visueller Vertrag benennt jeden Farbton und die Stufe, auf der jeder gegebene Hex sitzt, die Themes,
und das Verhältnis der Schriftgrößen-Skala – die Eingaben, die Stufe 1 kompiliert.
Detail: references/brand-discovery.md und
references/inspiration-research.md.
Stufen 1–6 – die Schleife
Jede Stufe durchläuft die gleichen fünf Schritte.
1. Bauen. Folge der Stufenspezifikation. Setze nur freigegebene untergeordnete Teile zusammen.
Eine Stufe, die ein Token benötigt, das die Grundlagen nicht haben, bedeutet, dass die Grundlagen
unvollständig waren – gehe zurück und ändere sie, anstatt einen lokalen Wert zu definieren, sonst
beginnt sich das System selbst zu widersprechen. Stufe 1: lies
references/token-architecture.md zuerst. Stufen 2–4: lies
references/component-anatomy.md zuerst und schreibe eine Spezifikationsdatei pro
Komponente aus assets/docs/COMPONENT-SPEC.md zusammen mit ihrem Exemplar.
Stufe 1 führt auch export-tokens.ts aus, so dass tokens.json und TOKENS.md existieren
für die Überprüfung. Starte jede Stufenseite mit init-system.ts --page <file>, damit
die Schiene generiert wird, nicht von Hand kopiert.
2. Verifizieren. bun $SKILL/scripts/verify-stage.ts --target <repo> --stage <n>.
Behebe, was es meldet, bevor du etwas zeigst. Es prüft ID-Kontiguität, rohe
Werte außerhalb von tokens.css, Stufenmarkierungen und Stufenreferenzen, Fokus-
behandlungen, noindex, Schienenverkabelung, Organismus-Rezepte und Zustands-Reihenfolge.
3. Zeigen. Betrachte die gerenderte Seite vor dem Prüfer, in dieser Reihenfolge: das verfügbare Browser-Tool der Sitzung über lokalem HTTP, mit geladenen Schriftarten → ein weiteres verfügbares visuelles Browser-Tool → nur DOM-Prüfungen (berechnete Tokens, geladene Schriftarten, kein seitlicher Scroll bei 375px). Headless verpasst Web-Schriftarten und Rendering-Probleme, die einen Großteil dessen ausmachen, was beurteilt wird. Sage, welche Stufe du verwendet hast und was visuell nicht überprüft wurde.
4. Tor. Präsentiere das Artefakt und frage mit dem verfügbaren Frage-Tool oder einer kurzen Nachricht:
- Freigeben → aktualisiere
STATE.json, schalte die nächste Stufe frei - Überarbeiten → nimm die Notizen, baue neu, verifiziere, zeige erneut
- Mit Anmerkungen freigeben → schalte frei, notiere die Anmerkungen als offene Entscheidungen
Schalte nur bei einem expliziten Ja weiter. Das Tor existiert, weil der Prüfer Dinge über diese Marke weiß, die nirgendwo schriftlich festgehalten sind – und weil es die Drossel ist, die es erlaubt, einen großen Build nach Atomen zu stoppen und nächste Woche fortzusetzen.
Verzichtete Freigaben. Wenn der Benutzer explizit sagt, nicht anzuhalten (oder ein Eval oder
CI-Prompt nicht-interaktiv läuft), führe die Leiter ohne Pause durch: beantworte das
Stufe-0-Interview aus der Anfrage und den Beweisen, markiere jede solche Antwort
als vorläufig in den offenen Entscheidungen des Briefs, notiere jede Stufe als „freigegeben ohne Überprüfung (vom Benutzer verzichtet)“ in STATE.json und CHANGELOG.md und präsentiere
alle Tore zusammen am Ende. Verzichte niemals aufgrund deines eigenen Urteils – ein stiller
Benutzer hat nichts verzichtet. Detail: references/stage-specs.md.
5. Indexieren. Bei Freigabe: markiere die Spezifikationen der Stufe als status: approved, führe
build-index.ts aus (regeneriert tokens.json, TOKENS.md, components/INDEX.md
und den README-Datei-Index), füge einen CHANGELOG.md-Eintrag an, der nur auflistet, was
sich geändert hat, und erhöhe die STATE.json-version – 0.1.0 für Grundlagen bis
0.5.0 für Vorlagen; die Freigabe von Seiten veröffentlicht 1.0.0. Die Änderung einer freigegebenen
Stufe ist ein Patch (ebenso die erneute Freigabe jeder veralteten nachgelagerten Stufe); vollständige Regeln in
references/output-structure.md. Generierte Dateien tragen einen „Nicht von Hand bearbeiten“-
Header; bearbeite ihre Quellen und führe sie erneut aus.
Wenn du eine Stufe präsentierst, halte es kurz: was gebaut wurde, die Anzahl pro Ebene, alles, was du ohne Beweise entscheiden musstest, und das eine Ding, das sich am meisten anzusehen lohnt. Kein Rundgang durch jedes Exemplar.
Konventionen, die überall gelten
Vollständige Details in references/html-conventions.md. Die tragenden:
- Null-aufgefüllte zusammenhängende IDs –
A-01,M-17,O-04,T-05,P-02– angezeigt in der UI über.card-label, gespiegelt indata-*und übereinstimmend mit dem Spezifikationsdateinamen. Stabil nach Freigabe; Neunummerierung bricht jede Referenz. - Vier Token-Stufen – Marke → Alias → Mapping → Responsiv, jede geöffnet durch
einen
@tier-Marker intokens.css. Roh-Literale nur in Marke und Responsiv. Farbe, Rahmenbreite und Radius gehen Mapping → Alias → Marke, niemals überspringend; gemappte--space-*,--duration-*,--ease-*,--shado
...
[abgeschnitten für die Übersetzung]