brandmd

brandmd est un outil en ligne de commande qui transforme n'importe quel site web actif en une spécification de design lisible par machine. Il rend la page, observe comment elle est réellement stylisée et écrit le résultat sous forme de DESIGN.md, le format défini par la spécification ouverte @google/design.md : un frontmatter YAML contenant des jetons typés pour les couleurs, la typographie, les coins arrondis, l'espacement et les composants, suivi de sections de prose telles que Overview, Colors, Typography, Layout, Elevation & Depth, Shapes, Components et Do's and Don'ts. Les fichiers générés sont destinés à être validés sans erreur via la commande de lint officielle @google/design.md. La motivation réside dans le fait que les agents de codage IA produisent des interfaces génériques lorsqu'ils manquent des couleurs, polices, espacements et conventions de composants du projet. Placer DESIGN.md à la racine d'un projet fournit ce contexte d'emblée à des agents tels que Claude Code, Cursor, Gemini CLI, Codex et Google Stitch. Une seule invocation, par exemple l'exécution de npx brandmd contre une URL pour écrire DESIGN.md, est suffisante ; aucune rédaction manuelle de la spécification n'est requise. L'extraction est locale. L'outil lance un navigateur headless via Playwright, fait défiler la page pour déclencher le contenu chargé en différé, rejette les bannières de cookies et les superpositions, lit les propriétés CSS personnalisées de :root (y compris les media queries) et collecte les styles calculés des éléments visibles. Il regroupe ensuite les couleurs similaires, dérive une échelle d'espacement et une unité de grille de base, identifie les rayons de bordure et les styles d'ombre, et reconnaît les modèles de composants tels que les boutons, les cartes et les champs de saisie. La détection de la typographie est sensible au rôle, privilégiant les polices d'affichage sur les titres, puis sur le corps de texte, tout en ignorant les polices monospace, de secours et d'icônes. Aucun appel LLM ni clé API n'est impliqué dans le flux par défaut. Plusieurs formats de sortie sont proposés en plus du DESIGN.md par défaut : des jetons JSON bruts pour les scripts et les chaînes d'outils, des propriétés CSS personnalisées, un bloc @theme Tailwind v4, et un guide de marque HTML autonome avec des échantillons, des spécimens typographiques, une visualisation de l'espacement et des exemples d'ombres. Plusieurs URL peuvent être passées pour fusionner les jetons entre les pages, avec des fréquences normalisées par page afin qu'une page de documentation riche en boutons ne puisse pas l'emporter sur une page d'accueil. Un flag dark optionnel extrait les jetons du thème sombre via prefers-color-scheme. Un flag vision optionnel utilise une clé API Gemini pour ajouter le style d'illustration, l'ambiance photographique et des indices de ton rédactionnel lus à partir d'une capture d'écran. Un flag agent écrit additionally des règles Cursor et des fichiers de compétences dans le chemin universel .agents/skills ainsi que dans le répertoire de compétences de Claude Code, afin que le contexte de marque soit récupéré sans configuration manuelle. brandmd est lui-même distribué en tant qu'Agent Skill installable, et un dépôt compagnon fournit des compétences de marque prêtes à l'emploi pour Tailwind CSS, shadcn/ui, Vercel, Mintlify et Anthropic. L'outil est délibérément conçu pour échouer en toute sécurité (fail-closed). Les pages bloquées, les réponses d'accès refusé, les murs de connexion et les pages avec trop peu de preuves provoquent un refus avec le code de sortie 2 dans tous les formats et aucun artefact n'est écrit, afin qu'une capture médiocre ne puisse pas écraser un bon DESIGN.md ; un flag override force la sortie mais marque l'artefact dans chaque format. Les écritures sont transactionnelles, utilisant des fichiers temporaires et un renommage avec rollback. Les codes de sortie distinguent le succès, les erreurs opérationnelles ou de validation, les refus et la dérive détectée par la sous-commande check. Une sous-commande check compare une page déployée à un fichier DESIGN.md commis pour détecter une dérive de design, comparant les couleurs par rôle sémantique plutôt que comme un ensemble non ordonné de valeurs hexadécimales, et fait échouer les builds en cas de rôles perdus ou repeints ou de changement des polices primaires ou secondaires. La documentation est honnête sur ses limites : la dérive des composants est signalée mais ne fait pas échouer un build, les changements de polices secondaires peuvent passer inaperçus, et les pages changeant dynamiquement peuvent produire des changements majeurs spurieux, les résultats doivent donc être reproduits avant d'être approuvés. Une sous-commande diff distincte compare deux fichiers DESIGN.md et produit un rapport markdown des couleurs, typographies, espacements, rayons partagés et uniques, ainsi que les différences par composant et une synthèse de ce qu'il faut copier. Une galerie d'exemples de sorties provenant de Stripe, Linear, GitHub, Vercel, Notion, Cursor, Anthropic, Figma, Supabase, Raycast et d'autres est incluse dans le dépôt. Le projet est sous licence MIT.