design-reference — une interface qui devient une référence, pas…

design-reference — une interface qui devient une référence, pas un modèle

Une interface est une référence quand quelqu'un qui connaît le sujet la reconnaît comme faite pour ce produit et par quelqu'un au sommet de son domaine. L'ennemi est le défaut : ce que n'importe quel modèle produirait pour n'importe quel brief similaire.

0. Les règles du projet

La première étape de toute pièce rendue — écran, composant, document HTML, Artifact, PDF, deck, diagramme (cloud-diagram), bannière — est le balayage du système de design du projet, une fois par projet par session :

python3 -I ~/.claude/skills/design-reference/scripts/sweep.py <racine>         # résumé
python3 -I ~/.claude/skills/design-reference/scripts/sweep.py <racine> --css   # :root avec --ds-*

Il lit la spec écrite (DESIGN.md, docs/design*), les tokens (tailwind.config.*, CSS avec :root/@theme, *.tokens.json), le thème de composant, package.json, components.json, les liens Storybook et Figma, et renvoie le verdict : projet (la pièce porte ses tokens) ou neutre (la palette neutre de l'équipe). --css émet --ds-bg --ds-surface --ds-fg --ds-fg-2 --ds-accent --ds-border --ds-font-display --ds-font-body --ds-font-mono et le bloc sombre ; les modèles de l'équipe lisent ces variables. --json renvoie la découverte complète. En cas de conflit, la précédence est : spec > tokens > composants. Un système par page. Dites en une ligne quel système la pièce porte et où il a été trouvé. Pour une marque cliente ou tierce : demandez d'abord. Détails dans references/design-system-sweep.md.

Lisez ensuite les composants partagés que le nouvel écran utilisera. Le brief et le monde visuel déjà engagés l'emportent sur tout goût personnel et toute règle ici. Affiner préserve l'identité, le texte et le comportement ; reconcevoir remplace le monde visuel entier — ne peaufinez jamais l'aspect qui a été abandonné. Une compétence de design propre au projet (.claude/skills/) l'emporte sur celle-ci.

Sans DESIGN.md, le projet n'est pas nécessairement une page vierge : la preuve est dans le code et les écrans existants, pas dans le nom du fichier.

1. Mode de surface (décide tout ce qui suit)

Choisissez en fonction de la surface demandée, pas du produit :

Mode	Succès du visiteur	Exemples	Ce qui compte
Persuader	décide et agit	page d'atterrissage, tarification, campagne	attention, preuve, appel à l'action — le design est le produit
Opérer	accomplit une tâche	application, tableau de bord, admin, éditeur, paramètres	lisibilité par parcours, cohérence, attentes natives ; la marque vit dans le détail
Lire	comprend quelque chose	documentation, article, changelog, aide	structure pour la compréhension, puis confort de lecture
Expérimenter	est à l'intérieur de l'œuvre	portfolio, galerie, musée, vitrine	l'œuvre mène dès le premier pli ; l'interface s'efface

La page d'atterrissage d'un outil est Persuader ; la documentation d'une marque de mode du texte ; la visite d'un musée est Expérimenter.

2. Direction avant le code (deux passes obligatoires)

Passe 1 — plan compact, avant d'ouvrir un fichier de code :

• Sujet : une phrase : à qui il s'adresse, quel est le travail unique de cet écran, et ce qui, dans le monde de ce sujet (matériaux, instruments, vocabulaire, artefacts), peut devenir un choix visuel.
• Couleur : 4 à 6 valeurs nommées (hex ou oklch), avec le rôle sémantique de chacune.
• Typographie : 2+ rôles — une police de titrage avec du caractère utilisée avec retenue, une police de corps complémentaire, une police utilitaire pour les données si nécessaire. Jamais la paire que vous utiliseriez sur n'importe quel autre projet.
• Mise en page : concept en une phrase + maquette ASCII. Comparez deux alternatives.
• Signature : l'élément unique dont l'écran sera mémorisé. Toute l'audace y va ; le reste reste calme et discipliné.
• Mouvement : un moment chorégraphié, ou aucun. Dites lequel.

Passe 2 — auto-critique. Pour chaque élément, demandez : « est-ce que je produirais ceci pour un brief similaire d'un autre produit ? » Si oui, c'est un défaut, pas un choix — réécrivez-le et dites ce qui a changé. Ce n'est qu'après cela que vous commencez à coder, en dérivant chaque couleur et police de caractères du plan.

Les trois looks que l'IA produit par défaut aujourd'hui : (1) crème #F4F1EA + une police à empattements à fort contraste + terre cuite ; (2) presque noir + un accent acide (vert citron ou vermillon) ; (3) un journal de règles fines, rayon zéro, colonnes denses. Tous légitimes si le brief les demande. Là où l'axe est libre, ne dépensez pas la liberté sur eux.

Pour un catalogue de styles, palettes et associations typographiques avec recherche locale, utilisez ui-ux-pro-max (python3 scripts/search.py "<domaine> <produit>") ; c'est un moteur de référence, pas un directeur artistique — la décision vous appartient toujours.

3. Les tokens sont la source de vérité

• Trois couches : primitif → sémantique → composant. Un composant ne lit jamais un primitif ou un hex brut ; il lit --color-surface-raised, pas --gray-100.
• Format : W3C DTCG 2025.10 (tokens.json) quand le projet a un pipeline ; sinon, propriétés CSS personnalisées sur :root avec le mode sombre dans @media (prefers-color-scheme: dark) et [data-theme].
• Couleur en oklch quand c'est possible ; contraste mesuré (APCA ou WCAG), pas estimé.
• Un thème sombre est un mappage de luminance, pas une inversion.
• Quand vous avez terminé, si le projet n'a pas de DESIGN.md, proposez d'en générer un (tokens en YAML + la raison de chaque valeur en prose) — c'est ce qui maintient la cohérence de la prochaine session avec celle-ci.

Échelle, spécification de composant (variantes, tailles, états avec priorité, anatomie) et notes sur shadcn/Tailwind/mode sombre : references/tokens-and-components.md. Pour générer le système complet en DTCG + CSS/Tailwind : sumi:tokens.

4. Construction

• Stack et composants : ceux du projet. shadcn/Tailwind → references/tokens-and-components.md et la documentation en direct via context7 ; un design venant de Figma → figma:figma-design-to-code (MCP) ou la compétence locale propre au projet (par exemple implement-from-figma, refactor-frontend-component) ; écrire dans Figma → figma:figma-use.
• Mobile natif : respectez la plateforme (HIG / Material) avant la marque.
• Un diagramme d'architecture cloud ou infrastructure (AWS, OCI, GCP, Azure, Cloudflare) : cloud-diagram, toujours. C'est la compétence de design pour la tâche ; copiez son kit (le template.html dans les références de cette compétence) et mesurez avec son render.sh. Pas de mermaid, de boîtes génériques ou d'icônes d'images externes.
• Contenu réel dès le début : testez les textes courts, moyens et très longs ; état vide ; chargement ; erreur ; absence d'autorisation. Un espace réservé Lorem est un défaut.
• Le texte est un matériau de design : un contrôle dit ce qui se passe (« Enregistrer les modifications », pas « Soumettre ») ; le même verbe du bouton au toast ; une erreur dit ce qui s'est passé et comment en sortir ; vide est une invitation à agir ; voix active, casse de phrase.
• CSS : attention à la spécificité qui s'annule (.section × .cta), transition: all jamais, seulement transform/opacity anime par défaut.
• Les surfaces du navigateur sont aussi du design : sélection de texte, caret, barre de défilement, focus, décalage de soulignement, chiffres tabulaires. Thématisez-les à partir de la palette — c'est le signe le moins cher que la page a été construite.

Compagnon d'exécution UI produit

Pour l'UI produit native ou responsive, utilisez la compétence mobile-design-studio disponible comme seul compagnon de design optionnel : petites unités d'implémentation, ergonomie mobile (cibles tactiles, zones de sécurité, clavier, mise à l'échelle du texte, retour), vérifications d'état/récupération et preuves de plateforme. design-reference reste l'unique source de direction de design : réutilisez son brief, ses tokens et ses composants approuvés ; n'exécutez pas un second processus de branding/direction et ne créez pas de fichiers de tokens en double. Lisez uniquement la référence du compagnon nécessaire pour l'unité en cours. Ce n'est pas la voie pour les decks, l'art, les affiches ou les diagrammes cloud ; ceux-ci conservent leurs compétences dédiées.

Résolvez le répertoire du compagnon à partir du chemin d'inventaire d'origine de la compétence sélectionnée, jamais à partir d'un cache d'invite généré ou d'une installation ~/.claude supposée. Si le compagnon est absent ou manuel uniquement, ne le publiez pas et ne le chargez pas automatiquement ; continuez avec la méthode du projet. Les compétences du projet et les prérequis obligatoires de la plateforme/Figma (par exemple l'aperçu Expo, React Native et Figma design-to-code/use) s'appliquent toujours ; ils ne sont pas des directions de design concurrentes optionnelles. Gardez le plafond de deux compétences de design : cette méthode plus un compagnon, jamais une pile Sumi/UI style supplémentaire.

5. Seuil de qualité (vérifié dans le résultat, pas dans l'intention)

Lisez references/quality-floor.md immédiatement avant d'éditer l'UI. Les points non négociables :

• Contraste ≥ 4,5:1 (texte), ≥ 3:1 (grand) ; texte secondaire sur une surface colorée teintée à partir de la teinte propre de cette surface, jamais gris.
• Focus visible sur tout ce qui est interactif ; ne supprimez jamais un contour sans le remplacer.
• Cible tactile ≥ 44×44 (natif) / 24×24 px CSS (web), 8px entre les cibles.
• prefers-reduced-motion respecté ; animation interruptible ; rien d'initié par le clavier n'anime.
• Responsive jusqu'à 320px sans défilement horizontal ; zones de sécurité dans les mises en page à fond perdu.
• Image avec dimensions déclarées ; police avec font-display ; longue liste virtualisée.
• États : survol, actif, focus, désactivé, chargement, erreur, vide — tous.
• Zéro emoji comme icônes ; icônes d'une seule bibliothèque, d'un seul trait, d'une seule épaisseur.

Inspection en tours limités, pas en boucle : construisez l'ensemble, capturez le bureau et le mobile ensemble (capture d'écran via le navigateur quand il y en a un), corrigez tout en un seul lot, confirmez avec au plus un tour supplémentaire, arrêtez. Le QA sans fin brûle l'argent du propriétaire en faisant moins bien ce que sumi:audit fait mieux.

6. Mouvement avec des règles (Emil Kowalski)

1. Doit-il animer ? 100+ fois/jour (raccourci, palette) → jamais. Des dizaines/jour (survol, navigation dans la liste) → réduisez considérablement. Occasionnel (modal, tiroir, toast) → standard. Rare (intégration, célébration) → il peut ravir.
2. Un but déclaré : continuité spatiale, indication d'état, explication, retour, évitement d'une coupure brusque. « C'est joli » n'est pas un but pour quelque chose vu fréquemment.
3. Assouplissement : entrée/sortie → assouplissement fort en sortie cubic-bezier(0.23, 1, 0.32, 1) ; déplacement/morphing à l'écran → assouplissement entrée-sortie cubic-bezier(0.77, 0, 0.175, 1) ; survol/couleur → ease ; mouvement constant → linear ; tiroir iOS → cubic-bezier(0.32, 0.72, 0, 1). Jamais d'assouplissement d'entrée en UI.
4. Durée : bouton 100–160ms ; info-bulle 125–200ms ; liste déroulante 150–250ms ; modal/tiroir 200–500ms ; UI toujours < 300ms sauf marketing.
5. Rien n'apparaît de nulle part : scale(0.95) + opacity 0, pas scale(0). Une popup se met à l'échelle à partir de son déclencheur (transform-origin) ; un modal reste centré. :active avec scale(0.97). Une entrée identique sur chaque section est un anti-motif ; un moment conçu ne l'est pas.

7. Art, canvas et travail créatif

Quand la requête est une affiche, une couverture, une pièce graphique, un art génératif, un visuel 3D ou « quelque chose de beau sans brief UI », la méthode change : d'abord une philosophie visuelle (un mouvement nommé en 1–2 mots + 4–6 paragraphes sur l'espace, la couleur, le matériau, l'échelle, le rythme, la composition), puis l'exécution. La référence au thème est subtile — ceux qui le connaissent le ressentent, les autres voient une composition magistrale. 90% visuel, 10% texte. Rien ne dépasse les marges, rien ne se chevauche.

Surface	Outil
PNG/PDF statique (affiche, art, couverture)	vendor/canvas-design (Anthropic)
Art génératif 2D, champs de flux, particules	vendor/algorithmic-art (p5.js, seed reproductible, curseurs)
Scène 3D / shader / interactive	three.js (r160+), GLSL ShaderMaterial ; toujours dispose() et suppression d'écouteur à la destruction
Pièce pour réseaux sociaux / pub / bannière / print	references/identity-and-pieces.md (tailles, zone de sécurité, appel à l'action) + HTML capturé à la taille exacte
Diapositives	slides
Diagramme d'architecture cloud	cloud-diagram
Guide de marque, palette, règles du logo	references/identity-and-pieces.md ; voix de marque et texte → writing
Logo, icône, maquette d'identité générée par IA	design (claudekit : scripts de génération avec une API, nécessite une clé)
Variantes côte à côte sur un canvas infini	plugin superdesign (payant ; nécessite une connexion — décision du propriétaire)
Image/vidéo générée	sumi:generate ou les MCP d'images configurés

Ne copiez jamais le travail d'un artiste identifiable ; citez l'influence, créez le vôtre. Polices : téléchargez et auto-hébergez-en une avec le bon caractère ; la police système « la plus proche » est un échec, pas un recul.

8. Audit et correction de ce qui existe déjà

• Score rapide avec les corrections principales : sumi:roast. Audit complet (heuristique, cognitif, flux) : sumi:audit. Accessibilité WCAG 2.2 AA : sumi:a11y. Checklist web (a11y, formulaires, mouvement, typographie, performances, i18n) : references/quality-floor.md §B, sortie sous forme de fichier:ligne.
• Correction du code UI généré : sumi:fix. Revue du mouvement : un tableau | Avant | Après | Pourquoi |, une ligne par constat.
• Ne chargez jamais plus de deux compétences de design dans la même session : les descriptions entrent en concurrence et le contexte gonfle sans améliorer la réponse.

9. Livraison

Mode             [Persuader | Opérer | Lire | Expérimenter]
Direction        [sujet · palette nommée · association typographique · signature · mouvement]
Défaut           [ce que vous avez réécrit dans l'auto-critique et pourquoi]
Tokens           [fichier et couches ; DESIGN.md généré/mis à jour ?]
Seuil            [chaque vérification du §5 avec la valeur mesurée, pas « ok »]
États            [liste des états implémentés]
Captures         [bureau + mobile, si l'environnement le permet]
En attente       [ressources que seul le propriétaire peut fournir ; décisions qui sont les siennes]