MarketingOS Atomic Design System
Transforme une marque en un système de design vérifiable : tokens hiérarchisés, un fichier de spécification par composant, et un site HTML de référence statique, construit une étape à la fois avec une validation humaine entre chaque — le tout dans un dossier design-system/ qu’un humain ou un agent peut parcourir à partir d’un seul README.
Contexte et prérequis MarketingOS
Identifiez le brain d’entreprise actif et la cible du site à partir de la session en cours et de ses enregistrements de projet. Lisez le BRAIN.md du brain ou les instructions de l’agent, CONTEXT.md, la marque, la voix, l’audience, l’offre et les références de design sauvegardées avant de demander des informations. Gardez le contexte de chaque entreprise séparé. Enregistrez le brain source et la cible dans le brief de design. En l’absence de MarketingOS, travaillez à partir des fichiers de marque fournis et identifiez les lacunes réelles.
Utilisez Bun pour les scripts TypeScript groupés. S’il est manquant, guidez l’utilisateur vers les instructions d’installation officielles à https://bun.com/docs/installation. Résolvez $SKILL vers le répertoire réel contenant ce SKILL.md chargé ; les agents s’installent à différents endroits, ne présumez donc pas d’un chemin d’accueil particulier.
Si l’utilisateur a sélectionné Taste Skill, lisez d’abord ses instructions installées et utilisez sa direction artistique et ses résultats de référence comme entrées pour ce framework. Préservez le contrat de marque, le système de tokens et les décisions d’étape de ce framework. Taste Skill est une dépendance optionnelle distincte, non incluse dans ce pack ; inspectez ses instructions officielles actuelles à https://github.com/leonxlnx/taste-skill lorsque l’installation est demandée.
Une seule invite initiale peut piloter l’ensemble du flux de travail. Gardez les décisions requises et les validations visuelles d’étape dans la même conversation, en reprenant après chaque réponse sans nécessiter une autre invite copier-coller. Arrêtez-vous à l’étape demandée par l’utilisateur ; ne traitez pas une invocation comme une autorisation de sauter les validations.
L’idée
Un système de design échoue de deux manières. Soit il est inventé — le modèle choisit une belle palette et le résultat est confiant, cohérent, mais pas la marque. Soit il est construit d’un seul coup, de sorte qu’une mauvaise décision à la base se propage silencieusement à travers vingt pages avant que quiconque ne la voie.
Ce skill adresse les deux. Découverte avant design : trouvez ce qui a déjà été décidé et soyez explicite sur les lacunes. Une barrière entre les étapes : retravailler les Fondations est une modification de cinq lignes ; le même retravail sur les Pages est vingt pages.
Routeur
Déterminez où se trouve l’utilisateur, puis agissez. Ne demandez pas quel mode ils souhaitent.
| Situation | Action à mener |
|---|---|
Pas de STATE.json et la découverte ne trouve aucun système atomique existant | Démarrer l’Étape 0 (v2 layout) |
La découverte rapporte existingAtomicSystem mais il n’y a pas de STATE.json (HTML construit à la main, ex. public/atomic-framework/ d’un projet existant, stage-*.html d’un projet legacy) | Système legacy. Étendez-le dans ses propres fichiers et conventions : ajoutez à ses pages existantes, conservez ses conventions de balisage/classe/ID, enregistrez le nouveau travail dans un petit ATOMIC-NOTES.md à côté. Ses conventions sont conservées, mais le plancher de qualité n’est pas abaissé : :focus-visible visible, cibles de 44 px, contraste, et une Carte d’Inspiration avec ce qui est pris et ce qui est laissé. S’il se trouve dans un dépôt frère, c’est un deuxième dépôt — demandez avant d’y écrire (voir Sécurité) et donnez à la cible un court DESIGN-SYSTEM.md pointant vers lui. Ne scaffoldez pas la v2 sauf si l’utilisateur demande une migration. Vérifiez avec verify-stage.ts --legacy <dir>. Détail : references/output-structure.md |
design-system/STATE.json avec schemaVersion: 2 | Système v2 : rapportez l’état, exécutez la prochaine étape non approuvée |
STATE.json sans schemaVersion: 2 (sous docs/design-system/ ou design-system/docs/) | Système v1 construit par l’ancien skill. Étendez-le dans son layout et ses conventions v1 (init-system.ts --schema 1 si un fichier de scaffold v1 est manquant). Ne migrez pas sauf si l’utilisateur le demande |
| "migrer vers v2" / "passer à la nouvelle structure" | Suivez la procédure de migration dans references/output-structure.md, sur une branche |
"refaire les molécules" (ou --stage <n> dans la requête) | Reconstruisez cette étape, marquez les suivantes comme obsolètes |
"où en sommes-nous" (ou --status) | Affichez l’échelle avec l’état et la version par étape, puis arrêtez |
| "exporter vers figma" / "figma variables" | Lancez export-figma.ts — voir references/figma-export.md. Ne fait jamais partie de l’échelle |
L’utilisateur renonce explicitement aux barrières ("ne pas s’arrêter pour les validations" ; --non-interactive dans une évaluation ou CI) | Lancez l’échelle sans vous arrêter et présentez toutes les barrières ensemble à la fin — voir "Validations levées" ci-dessous |
| Dépôt cible peu clair | Demandez, une fois. Ne devinez pas entre des dépôts frères |
Résolvez d’abord le dépôt cible. Tout le reste lui est relatif.
--stage, --status et --non-interactive ci-dessus sont des façons dont un utilisateur formule une demande à ce skill — des modes de comportement, pas des drapeaux de script.
Configuration
# Définissez SKILL comme le répertoire réel contenant le SKILL.md chargé
bun $SKILL/scripts/discover-brand.ts --target <repo> [--siblings <dir>] # Étape 0
bun $SKILL/scripts/init-system.ts --target <repo> # scaffold v2 ; --schema 1 seulement pour un système v1 d’ancien skill
bun $SKILL/scripts/init-system.ts --target <repo> --page <file> # crée une page depuis le shell, rail + aria-current remplis
bun $SKILL/scripts/verify-stage.ts --target <repo> --stage <n> # lit schemaVersion ; --legacy <dir> pour les systèmes construits à la main
bun $SKILL/scripts/build-index.ts --target <repo> # après chaque étape approuvée
bun $SKILL/scripts/export-tokens.ts --target <repo> # tokens.css → tokens.json + TOKENS.md (build-index l’exécute)
bun $SKILL/scripts/export-figma.ts --target <repo> # optionnel
discover-brand.ts cherche par défaut dans la cible et son répertoire parent. Utilisez --siblings <dir> lorsque le brain actif se trouve ailleurs. Lisez explicitement le brain résolu même lorsque la découverte ne trouve aucun frère correspondant. Tous les drapeaux de script sont documentés dans references/output-structure.md.
Sortie (v2) — une racine, un fichier d’entrée, une spécification par composant :
design-system/
├── README.md COMMENCEZ ICI — point d’entrée pour les humains et les agents
├── STATE.json schemaVersion 2, étapes, validations, inventaire, version, thèmes
├── CHANGELOG.md une entrée par étape approuvée / publication
├── brief/DESIGN-BRIEF.md
├── tokens/ tokens.css (canonique) · tokens.json · TOKENS.md (généré) · figma/ (optionnel)
├── foundations/FOUNDATIONS.md
├── components/ INDEX.md (généré) · atoms/ molecules/ organisms/ templates/ <ID>-<slug>.md
├── rules/RULES.md
└── reference/ site HTML statique de validation (noindex) · styles.css · pages/P-nn-<slug>.html
Pourquoi il est formaté ainsi, la spécification du README, la table de passage v1 → v2 et la procédure de migration : references/output-structure.md. Lisez-le lors du scaffolding, de l’écriture du README ou de la migration.
L’échelle
Sept étapes de construction. Les Fondations se situent avant les Atomes parce que vous ne pouvez pas construire un atome sans tokens ; les Règles arrivent en dernier parce que les garde-fous sont rédigés à partir de ce qui a été réellement décidé. Les chemins sont relatifs à design-system/.
| # | Étape | Produit |
|---|---|---|
| 0 | Découverte | brief/DESIGN-BRIEF.md, STATE.json, squelette README.md, CHANGELOG.md, reference/index.html (00) |
| 1 | Fondations | tokens/tokens.css (+ json/md généré), foundations/FOUNDATIONS.md, reference/foundations.html (01) |
| 2 | Atomes | components/atoms/A-nn-*.md, reference/atoms.html (02), reference/icons.html (02A) |
| 3 | Molécules | components/molecules/M-nn-*.md, reference/molecules.html (03) |
| 4 | Organismes | components/organisms/O-nn-*.md, reference/organisms.html (04) |
| 5 | Templates | components/templates/T-nn-*.md, reference/templates.html (05) |
| 6 | Pages | reference/pages.html (06), reference/pages/P-nn-*.html, reference/rules.html (07), rules/RULES.md, README.md final, version 1.0.0 |
Artefacts complets par étape et critères d’acceptation : references/stage-specs.md. Lisez la section de l’étape sur laquelle vous êtes, pas tout le fichier.
Étape 0 — Découverte
Trois entrées, puis synthèse. Faites les deux premières en parallèle ; elles ne dépendent pas l’une de l’autre.
1. Inspiration design. Réutilisez d’abord les références sauvegardées du brain actif ou du passage Taste Skill ; ne demandez que les URLs brutes manquantes — trois à six, des pages spécifiques plutôt que des pages d’accueil si possible. Prenez un instantané de chacune avec l’outil de navigation disponible, en vérifiant les polices et la mise en page réelles. Utilisez Interceptor uniquement s’il est installé et approprié à la session. Extrayez la palette calculée, la pile typographique, le rythme d’espacement et les rayons — les valeurs rendues réelles, pas les hex marketing.
2. Mobbin MCP (optionnel). Pour les questions de motif que les URLs ne peuvent pas répondre : comment cette catégorie séquence l’intégration, structure la tarification, gère les états vides. Le MCP peut être installé mais non authentifié — si seulement mcp__mobbin__authenticate / complete_authentication sont exposés, lancez le flux OAuth et remettez l’URL à l’utilisateur. S’il décline, continuez et enregistrez la lacune dans le brief. Ne suggérez jamais qu’une recherche de motifs a eu lieu si ce n’est pas le cas.
3. Découverte de marque. Lancez discover-brand.ts. Il sonde les conventions de chemins connues à travers la cible et ses dépôts frères, fusionne les documents compagnons, et partitionne par famille de marque avant de classer — afin qu’un document soigné d’une autre marque ne puisse jamais gagner. Lisez-en trois choses : quel document, si le contrat visuel est full/partial/verbal-only, et si un système atomique existe déjà (si oui, étendez-le plutôt que de recommencer).
Confirmez la source de la marque avec l’utilisateur avant de compiler quoi que ce soit. C’est l’erreur qui invalide chaque étape en aval.
Ensuite, rédigez DESIGN-BRIEF.md. Sa Carte d’Inspiration a besoin des deux moitiés de chaque ligne — ce que nous prenons et ce que nous laissons délibérément. La colonne "laissé" est là où réside le jugement ; une ligne avec seulement "pris" est une instruction de collage. Son §3 contrat visuel nomme chaque teinte et le pas auquel chaque hex donné se trouve, les thèmes, et le ratio d’échelle typographique — les entrées que l’Étape 1 compile.
Détail : references/brand-discovery.md et references/inspiration-research.md.
Étapes 1 à 6 — la boucle
Chaque étape suit les cinq mêmes temps.
1. Construire. Suivez la spécification de l’étape. Composez uniquement des pièces de niveau inférieur approuvées. Une étape qui a besoin d’un token que les Fondations n’ont pas signifie que les Fondations étaient incomplètes — revenez en arrière et modifiez-les plutôt que de définir une valeur locale, sinon le système commence à se contredire. Étape 1 : lisez d’abord references/token-architecture.md. Étapes 2 à 4 : lisez d’abord references/component-anatomy.md, et écrivez un fichier de spécification par composant à partir de assets/docs/COMPONENT-SPEC.md à côté de son spécimen. L’Étape 1 exécute également export-tokens.ts afin que tokens.json et TOKENS.md existent pour la validation. Commencez chaque page d’étape avec init-system.ts --page <file> afin que le rail soit généré, non copié à la main.
2. Vérifier. bun $SKILL/scripts/verify-stage.ts --target <repo> --stage <n>. Corrigez ce qu’il rapporte avant de montrer quoi que ce soit. Il vérifie la contiguïté des ID, les valeurs brutes en dehors de tokens.css, les marqueurs de niveau et les références de niveau, les traitements de focus, noindex, le câblage du rail, les recettes d’organisme et l’ordre des états.
3. Montrer. Regardez la page rendue avant le relecteur, dans cet ordre : l’outil de navigation disponible de la session sur HTTP local, avec les polices chargées → un autre outil de navigation visuelle disponible → vérifications DOM uniquement (tokens calculés, polices chargées, pas de défilement latéral à 375 px). Headless manque les polices web et les problèmes de rendu, qui constituent une grande partie de ce qui est jugé. Dites quel niveau vous avez utilisé et ce qui n’a pas été vérifié visuellement.
4. Barrière. Présentez l’artefact et demandez à l’aide de l’outil de question disponible ou d’un message concis :
- Approuver → avancez
STATE.json, déverrouillez l’étape suivante - Réviser → prenez les notes, reconstruisez, vérifiez, montrez à nouveau
- Approuver avec notes → avancez, enregistrez les notes comme décisions ouvertes
N’avancez que sur un oui explicite. La barrière existe parce que le relecteur sait des choses sur cette marque qui ne sont écrites nulle part — et parce que c’est l’accélérateur qui permet à une grande construction de s’arrêter après les Atomes et de reprendre la semaine suivante.
Validations levées. Lorsque l’utilisateur dit explicitement de ne pas s’arrêter (ou qu’une invite d’évaluation ou CI s’exécute en mode non interactif), lancez l’échelle sans faire de pause : répondez à l’entretien de l’Étape 0 à partir de la requête et des preuves, marquez chaque réponse comme provisoire dans les décisions ouvertes du brief, enregistrez chaque étape comme "approuvée sans relecture (levée par l’utilisateur)" dans STATE.json et CHANGELOG.md, et présentez toutes les barrières ensemble à la fin. Ne levez jamais de votre propre jugement — un utilisateur silencieux n’a rien levé. Détail : references/stage-specs.md.
5. Indexer. Sur approbation : marquez les spécifications de l’étape status: approved, lancez build-index.ts (régénère tokens.json, TOKENS.md, components/INDEX.md et l’index du fichier README), ajoutez une entrée CHANGELOG.md listant uniquement ce qui a changé, et augmentez la version de STATE.json — 0.1.0 pour les Fondations jusqu’à 0.5.0 pour les Templates ; approuver les Pages publie 1.0.0. Modifier une étape approuvée est un correctif (de même que la ré-approbation de chaque étape en aval obsolète) ; règles complètes dans references/output-structure.md. Les fichiers générés portent un en-tête ne pas modifier à la main ; éditez leurs sources et relancez.
Lorsque vous présentez une étape, restez concis : ce qui a été construit, le nombre par niveau, tout ce que vous avez dû décider sans preuve, et la chose qui mérite le plus d’être regardée. Pas une visite guidée de chaque spécimen.
Conventions qui tiennent partout
Détail complet dans references/html-conventions.md. Les essentielles :
- ID contigus à zéro-padding —
A-01,M-17,O-04,T-05,P-02— affichés dans l’UI via.card-label, reflétés dansdata-*, et correspondant au nom du fichier de spécification. Stables une fois approuvés ; renuméroter casse toutes les références. - Quatre niveaux de tokens — marque → alias → mappé → responsive, chacun ouvert par un marqueur
@tierdanstokens.css. Littéraux bruts uniquement dans Marque et Responsive. La couleur, la largeur de bordure et le rayon vont Mappé → Alias → Marque, jamais en sautant ;--space-*,--duration-*,--ease-*,--shado…sont mappés. - Responsive : les tokens viennent en étapes fixes, pas de
min-widtharbitraire —--viewport-sm,--viewport-md,--viewport-lg,--viewport-xl. La règle de l’étape de base n’a pas de condition médiatique ; les étapes supérieures ont une condition demin-widthchacune. Un--space-sm-1aux deux premières étapes remplace les deux. - Cuisson : les jetons d’ombre sont
--shadow-*, pas--elevation-*. Le composant fait référence au jeton d’ombre, pas à l’effet. La cuisson est de niveau. - Recettes : les organismes ont des recettes dans leurs fichiers de spécification montrant comment les molécules sont disposées.
flex/griduniquement — pas deposition: absolutesauf pour le chevauchement intentionnel, et chaque composant positionné documente pourquoi dans sa section de recette. - Barrière de qualité : 44 px de zone cliquable minimale,
:focus-visiblesur chaque élément interactif, rapport de contraste WCAG 2.1 AA (4.5:1 texte normal, 3:1 texte grand). Vérifié statiquement parverify-stage.ts, pas uniquement visuellement. noindex: chaque page HTML de référence porte<meta name="robots" content="noindex">. Ce sont des artefacts de validation, pas des pages de production.
Rédaction de spécification de composant
Chaque composant obtient un fichier .md dans components/{type}/. Lisez assets/docs/COMPONENT-SPEC.md pour la structure détaillée. Les champs requis :
ID:(ex.A-01)name:(slug court)type:(atom / molecule / organism / template)stage:(numéro d’étape)status:(draft / reviewed / approved)description:phrase en langage naturelspec:tableau des variations de l’élément (taille, état, thème, dosage)token usage:quels tokens de marque / alias / mappés ce composant consommerecipes:pour les organismes, comment les enfants sont disposésacceptance:conditions à vérifier avant d’approuvernotes:décisions ouvertes ou commentaires
L’init-system.ts --page <file> génère le rail et aria-current pour que la page tienne dans le site de validation.
Sécurité
- Ne jamais écrire dans un dépôt frère sans confirmation. Si un système legacy se trouve dans un dépôt frère, demandez explicitement avant d’y toucher. Donnez au dépôt frère un
DESIGN-SYSTEM.mdde liaison pointant vers le dossier du système. - Ne jamais supposer un chemin de brain. Résolvez
$SKILLdepuis le chargement du SKILL.md, pas depuis un chemin codé en dur. - Ne pas écraser des fichiers sans vérifier.
build-index.tsrégénère les fichiers marqués "généré". Les modifications manuelles dans ces fichiers seront perdues ; prévenez l’utilisateur. - Validation. Utilisez
verify-stage.tsavant de présenter quoi que ce soit à un humain. Les scripts qui échouent ne produisent pas d’artefacts.
Dépendances optionnelles
| Dépendance | Usage | Documentation |
|---|---|---|
| Taste Skill | Direction artistique et références de design | https://github.com/leonxlnx/taste-skill |
| Mobbin MCP | Recherche de motifs (onboarding, tarification, états) | Installé via le client MCP (session) |
Problèmes connus et limites
- Export Figma : Limité aux tokens de couleur et de typographie ; les formes complexes et les grilles nécessitent une configuration manuelle dans Figma. Voir
references/figma-export.md. - Systèmes legacy : La vérification de
verify-stage.ts --legacyne peut pas tout couvrir ; des ajustements manuels peuvent être nécessaires. - Mobbin MCP non authentifié : Le flux OAuth peut échouer dans les environnements headless ; le skill continue sans, mais les lacunes de motifs sont enregistrées.
- Validation de page statique : Les pages HTML de référence sont statiques ; les interactions JavaScript et les données dynamiques ne sont pas testées.