Règles Cursor pour un design system : pourquoi un seul fichier finit par échouer

Le conseil de départ est pertinent. Cursor lit les fichiers .cursor/rules/*.mdc, chacun possédant un frontmatter qui contrôle son chargement : alwaysApply pour les règles toujours présentes dans le contexte, globs pour les règles qui s'activent lorsque des fichiers correspondants sont utilisés. Un seul fichier design.mdc avec alwaysApply: true permet déjà d'aller loin.

Ensuite, trois choses se produisent, dans cet ordre.

1. 1

   Le fichier s'allonge

   Chaque fois que l'agent commet une erreur, quelqu'un ajoute une ligne. Au bout de six mois, on se retrouve avec quatre cents lignes couvrant les couleurs, la typographie, l'espacement, l'animation, l'accessibilité, les modèles de formulaires, les états vides et un paragraphe sur le ton employé. Le fichier est toujours dans le contexte, il concurrence la tâche actuelle pour attirer l'attention, et le respect de chaque ligne individuelle s'effondre.

2. 2

   Les règles commencent à se contredire

   « Utilisez un espacement généreux » a été écrit pour le site marketing. « Gardez les tableaux denses » a été écrit pour le tableau de bord. Les deux sont dans le même fichier actif en permanence, donc les deux sont vrais partout, et donc aucun n'est plus une règle.

3. 3

   Quelqu'un limite la portée pour corriger cela, et la règle cesse de s'appliquer

   La correction évidente est globs: components/**. Mais quand l'agent écrit une nouvelle mise en page de page dans app/, aucune règle de design ne s'active et le résultat est générique. Les nouvelles mises en page sont précisément là où les directives de design sont les plus cruciales, et c'est précisément ce qu'un glob de composants ignore.

L'instinct est de segmenter par sujet : colors.mdc, typography.mdc, spacing.mdc. C'est le mauvais axe. Ces trois éléments sont tous vrais en même temps ; les séparer ne change rien, si ce n'est le nombre de fichiers à maintenir.

Segmentez plutôt par portée de vérité. La question pour chaque règle est : quand est-ce que ceci est faux ? Si la réponse est « jamais », cela appartient au fichier actif en permanence. Si la réponse est « dans le tableau de bord », cela appartient à une règle limitée, et son opposé appartient à une autre.

C'est la même structure que celle adoptée indépendamment par les grands design systems — Encore de Spotify est une fondation avec des sous-systèmes spécialisés au-dessus, Carbon est un noyau avec des couches par domaine. Un répertoire de règles est une version miniature de ce même concept, et il échoue de la même manière lorsque la fondation absorbe des éléments qui devraient rester locaux.

Limitez-vous à un seul écran. Son rôle n'est pas de contenir le design system — le design system réside dans DESIGN.md et dans votre fichier de tokens. Son rôle est de forcer l'agent à lire ces fichiers, et de détenir la poignée de contraintes qui ne doivent jamais être violées, peu importe où.

---
description: Design system policy for all UI work
alwaysApply: true
---

Before writing or editing any UI, read DESIGN.md at the repo root.

## Non-negotiable

- Never write a literal colour value. No hex, no rgb(), no named
  CSS colours. Use the semantic tokens in DESIGN.md.
- Never introduce a font family that is not in DESIGN.md.
- Every spacing value comes from the scale. Any other value is a bug.
- Every interactive element has a visible focus state.
- Anything with a light-mode colour has a dark-mode counterpart.

## When unsure

Match the nearest existing component in this repo rather than
inventing a new pattern. If no similar component exists, say so
before writing one.

Chaque ligne est une contrainte qui peut être vérifiée et violée. Aucune d'entre elles ne décrit une esthétique. C'est délibéré, et c'est la différence majeure entre un fichier de règles qui modifie le rendu et un qui ne le fait pas.

Nous avons échantillonné 299 fichiers DESIGN.md publics — le même type d'artefact qu'un fichier de règles de design, écrit dans le même but — et nous avons mesuré ce qu'ils contiennent réellement plutôt que ce qu'ils prétendent contenir.

Le chiffre des interdictions est le plus important. Les trois quarts de ces fichiers ne disent au modèle que ce qui est permis, ce qui laisse tout le reste autorisé par défaut — et tout le reste constitue la majeure partie d'une interface.

Considérez la différence concrètement. « Utilisez --color-primary pour les actions primaires » est respecté par une page qui utilise également la couleur primaire pour les titres, les liens, le remplissage des icônes, une bordure et un dégradé. Ajoutez « n'utilisez jamais l'accent pour le texte, les bordures, les arrière-plans ou les dégradés » et la même phrase produit désormais une interface sobre. La permission n'a pas changé. L'interdiction a fait tout le travail.

Le chiffre des adjectifs vagues aggrave la situation. « Clean » apparaît dans 39 % de ces fichiers et « modern » dans 36 %. Un modèle à qui l'on demande d'être « clean and modern » produit le centre statistique de ses données d'entraînement, ce qui est précisément la raison pour laquelle les interfaces générées par IA convergent vers le même aspect. Aucun de ces deux mots n'exclut quoi que ce soit.

Une fois que la règle permanente ne contient plus que les universels, les règles spécifiques à la surface peuvent être absolues plutôt que nuancées. Deux exemples illustrant la structure :

---
description: Marketing and landing surfaces
globs: app/(marketing)/**, app/page.tsx, components/marketing/**
---

Spacing runs one step above the app scale. Sections breathe.
Display type (48px+) is allowed here and nowhere else.
Cards may use shadow elevation.
One primary call to action per section. Never two competing buttons.

---
description: Dense application surfaces — tables, dashboards, settings
globs: app/(app)/**, components/table/**, components/dashboard/**
---

Compact spacing: controls 8-12px padding, table rows 32px.
Elevation is a surface step plus a 1px border. Never a shadow.
Type stays at body scale and below. No display type.
Status colours (success, warning, danger) are reserved for status.
Nothing decorative uses them.

Aucune de ces deux règles ne contient de réserve, car aucune des deux n'est jamais en contexte avec l'autre. C'est tout l'avantage de la séparation.

Trois éléments sont placés dans les fichiers de règles alors qu'ils appartiennent ailleurs, et chacun a un coût.

Le problème de duplication de la première ligne mérite d'être approfondi. Dès qu'une valeur hexadécimale apparaît à la fois dans le fichier de règles et dans le fichier de tokens, l'un sera mis à jour et l'autre non, et l'agent utilisera avec assurance la version obsolète. Les règles doivent pointer vers la source de vérité, jamais la reformuler.

Tout ce qui précède suppose qu'il y a quelque chose qui mérite d'être référencé. Un fichier de règles qui dit "lire DESIGN.md" n'est utile que si DESIGN.md l'est, et les données du corpus montrent que la plupart de ces fichiers ne sont qu'une palette accompagnée d'adjectifs.

Ce qui fait la différence est systématiquement la même liste : des couleurs définies comme des rôles sémantiques plutôt que des valeurs hexadécimales, une échelle typographique avec des valeurs réelles, une échelle d'espacement, un mode sombre défini plutôt que dérivé, des motifs qui précisent le comportement du design, et une liste explicite de ce qui est interdit. Une fois ces éléments consignés, le fichier de règles devient court, car il ne sert plus que de pointeur.

Pour la plupart des projets, quatre fichiers sont le nombre idéal ; au-delà, c'est un signal d'alerte :

1. design.mdc — alwaysApply: true. Un seul écran. Pointe vers DESIGN.md, contient les interdictions universelles et demande à l'agent de consulter avant d'inventer un pattern.
2. surface-marketing.mdc — portée glob. Les règles qui ne s'appliquent que là où le lecteur scanne le contenu en quelques secondes.
3. surface-app.mdc — portée glob. Les règles qui ne s'appliquent que là où l'utilisateur passe toute sa journée.
4. a11y.mdc — alwaysApply: true si votre équipe a besoin d'une mention séparée. États de focus, contrastes minimums, éléments sémantiques, exigences d'étiquetage.

Si vous ressentez le besoin d'un cinquième fichier, vérifiez s'il s'agit réellement d'un nouveau périmètre de vérité ou d'un sujet qui appartient à un fichier existant. Les sujets se multiplient à l'infini ; les périmètres, non.