Donner un design system à Bolt

Selon la documentation de Bolt, un design system fournit à Bolt un ensemble de règles visuelles (couleurs, typographie, espacements, styles de composants) à suivre lors de la construction. L'avantage annoncé est que Bolt génère du code UI basé sur vos composants réels plutôt que du code temporaire que vous devriez remplacer plus tard.

Il existe deux niveaux, et la différence est importante avant de planifier votre approche :

Les systèmes préchargés sont un excellent moyen de constater l'impact d'un système : choisissez-en un, cliquez sur *Try example* et comparez la qualité du résultat avec un prompt simple. En revanche, vous ne pouvez pas les adapter à votre marque car ils sont en lecture seule. Dès que vous avez besoin de votre propre identité visuelle, vous devez choisir entre un forfait Team et le terminal.

Le modèle de Bolt repose sur la compilation, pas sur l'upload. Sa documentation précise que Bolt compile votre design system à partir de vos propres sources, de votre bibliothèque de composants et de votre site de design system, et que votre design system *est défini par ces sources*. Lorsque les sources changent, vous synchronisez Bolt pour récupérer la dernière version.

C'est un modèle cohérent, mais avec une conséquence que l'on découvre plus tard : le système compilé est un instantané. Entre deux synchronisations, Bolt génère du code à partir d'une version de votre système qui peut ne plus correspondre à ce qui est en production. C'est le problème que les équipes de design system connaissent sous le nom de "token drift" : la source de vérité conçue et la version déployée divergent. Un agent qui génère avec assurance à partir d'une copie obsolète produit du code prêt pour la production sur des bases erronées, et ce, plus rapidement que jamais. Intégrez la synchronisation dans votre checklist de release, pas dans votre backlog de maintenance.

Bolt n'est pas un cas isolé en nécessitant des sources pour la compilation. Nous avons vérifié la documentation actuelle de chaque constructeur IA et agent de code majeur, et la structure est identique pour tous.

Si vous maintenez une bibliothèque de composants et un site de documentation, le compilateur de Bolt est l'outil idéal et vous devriez souscrire au forfait Team. Si votre design system actuel se résume à « ce que Bolt a affiché sur le premier écran », il n'y a rien à compiler, et la suite de cette page est la solution pratique.

Bolt est une WebContainer StackBlitz, ce qui signifie qu'il exécute un véritable environnement Node avec un véritable terminal dans le navigateur. Presque aucun autre outil de cette catégorie ne le fait. Vous pouvez installer des packages, exécuter des générateurs et écrire des fichiers ; ainsi, un design system s'installe exactement comme sur votre machine, sans restriction de forfait ni étape de compilation.

1. 1

   Assurez-vous que le projet utilise shadcn/ui

   Les starters React + Tailwind de Bolt fonctionnent très bien. Si le projet n'est pas encore initialisé avec shadcn, exécutez d'abord npx shadcn@latest init dans le terminal de Bolt.

2. 2

   Installer le set de tokens

   Exécutez la commande de registry du kit dans le terminal de Bolt. Elle écrit chaque rôle sémantique, en mode clair et sombre, dans votre thème, de sorte que les composants référençant déjà bg-primary se repeignent sans nécessiter de modification.

   Copy

   npx shadcn add https://identityforge.io/r/ambient-sage.json

3. 3

   Placez le brief dans le repo, pas dans le chat

   C'est l'étape que les utilisateurs sautent souvent. La CLI génère un fichier DESIGN.md complet dans le projet, afin que les règles survivent à un nouveau chat, à un rechargement ou au passage de la personne suivante qui ouvrira le projet.

   Copy

   npx --yes identityforge@latest apply ambient-sage

4. 4

   Utilisez le système comme base de prompt

   Construisez ensuite normalement, en nommant explicitement la contrainte lors des premières fois.

   Copy

   Build a landing page using only the theme's design tokens
   and the rules in DESIGN.md. Do not add a new colour or font.

Cette question revient systématiquement, et c'est une intuition légitime. Le repo est la source de vérité, il faut donc diriger l'agent vers lui. Deux obstacles se présentent.

Le premier est d'ordre pratique : un dépôt n'est pas un design system sous une forme qu'un agent peut appliquer. C'est un ensemble de milliers de fichiers, dont la plupart sont sans rapport avec une décision de style, avec les règles réelles distribuées entre une config Tailwind, un theme provider, quelques fichiers CSS et la mémoire collective de l'équipe. La compilation existe précisément parce qu'il faut réduire tout cela en tokens, un catalogue de composants et un ensemble de contraintes.

Le second est qu'un repo répond à *ce qui existe* et non à *ce qu'il faut faire*. Il contient un Button avec cinq variantes ; il ne dit pas quelle variante utiliser pour une action destructive, que vous ne devez jamais mettre deux accents sur un écran, ou ce qui se passe en mode sombre sur une surface qui n'a pas encore de variante sombre. Ce sont des jugements qui résident dans la prose ; si personne ne les a consignés, l'agent en fournira ses propres : de manière plausible, mais différemment à chaque fois.

Nous avons échantillonné 299 fichiers DESIGN.md publics pour voir à quelle fréquence ces jugements sont réellement consignés. 76 % ne listent que des préférences et jamais d'interdictions. 69 % ne mentionnent jamais le mode sombre. 86 % donnent des valeurs hex brutes sans rôle sémantique associé, ce qui signifie que la question « quelle est la couleur d'un bouton désactivé » n'a aucune réponse dans le fichier.

L'approche à suivre : liez le dépôt si l'outil le permet, mais rédigez tout de même les règles. Le contenu d'un fichier complet est détaillé dans ce qu'est un DESIGN.md.

Si vous optez pour la voie native et vous demandez s'il faut donner à Bolt un package npm, une structure de dossiers ou un lien vers une documentation, la réponse honnête est que cela dépend de l'outil utilisé, et les outils divergent réellement :

• Bolt compile les informations à partir de votre bibliothèque de composants et de votre site de design system, puis se resynchronise lors de leurs modifications.
• v0 demande un package installable : npm, un .tgz ou un répertoire source avec son propre package.json, et en créera un à partir de sources moins structurées si vous n'en avez pas.
• Lovable demande des composants React, livrés sous la forme d'un projet Lovable dédié, et les copie dans les dépôts connectés.
• Les agents de code ne veulent ni l'un ni l'autre : ils veulent un fichier de tokens et un brief écrit présents dans le dépôt.

Le seul artefact accepté par ces quatre outils est le duo auquel ils reviennent tous : un ensemble complet de tokens sémantiques et les règles écrites qui l'accompagnent. Produire ces éléments en premier ne vous coûte rien si vous publiez ultérieurement un package, et c'est la seule version qui fonctionne aujourd'hui avec un plan gratuit.

L'élément du registre à l'adresse https://identityforge.io/r/<slug>.json contient chaque rôle sémantique. Ainsi, Bolt n'improvise jamais les valeurs qu'une palette simple laisse indéfinies : texte atténué, bordures, états de survol (hover) et actifs, anneaux (ring), éléments destructifs, séries de graphiques, et tout cela à nouveau pour le mode sombre. Fournir trois couleurs de marque définit trois valeurs et en laisse environ vingt-cinq en suspens. Voir explication des tokens de couleur sémantiques.

• Laisser le brief dans le chat. Les builds longs tronquent le contexte. Un fichier DESIGN.md dans le projet n'est pas tronqué.
• Supposer qu'un système pré-chargé peut être orienté vers votre marque. Ils sont conçus pour être en lecture seule.
• Ne synchroniser que lorsqu'un élément semble incorrect. À ce stade, Bolt génère du contenu à partir d'un instantané obsolète depuis des semaines.
• Donner des couleurs à Bolt sans rôles. Une palette ne peut pas répondre à la question de l'apparence d'un contrôle désactivé ; Bolt choisit donc lui-même, et différemment à chaque écran.
• Négliger le mode sombre. Ce n'est pas une simple inversion du mode clair, et c'est là que l'improvisation se manifeste en premier.