Die Ein-Datei-Version und ihre Schwachstellen
Der erste Rat ist fundiert. Cursor liest .cursor/rules/*.mdc-Dateien, die jeweils Frontmatter enthalten, welches steuert, wann sie geladen werden – alwaysApply für Regeln, die immer im Kontext sind, und globs für Regeln, die greifen, wenn entsprechende Dateien bearbeitet werden. Eine einzelne design.mdc mit alwaysApply: true führt bereits weit.
Dann passieren drei Dinge, in dieser Reihenfolge.
- 1
Die Datei wächst
Jedes Mal, wenn der Coding-Agent einen Fehler macht, fügt jemand eine Zeile hinzu. Nach sechs Monaten umfasst sie vierhundert Zeilen zu Farben, Typografie, Spacing, Animationen, Barrierefreiheit, Formular-Patterns, Empty States und einen Absatz zum Tone of Voice. Sie ist immer im Kontext, konkurriert mit der eigentlichen Aufgabe um Aufmerksamkeit, und die Einhaltung einzelner Zeilen sinkt.
- 2
Die Regeln beginnen, sich zu widersprechen
„Großzügiges Spacing verwenden“ wurde für die Marketing-Seite geschrieben. „Tabellen kompakt halten“ wurde für das Dashboard geschrieben. Beides steht in derselben dauerhaft aktiven Datei, sodass beides überall gilt – und damit keine der beiden Anweisungen mehr eine echte Regel ist.
- 3
Jemand schränkt den Geltungsbereich ein, um dies zu beheben, und die Regel greift nicht mehr
Die naheliegende Lösung ist
globs: components/**. Wenn der Agent dann jedoch ein neues Seitenlayout inapp/schreibt, greift keine Design-Regel und das Ergebnis ist generisch. Neue Layouts sind genau dort, wo Design-Richtlinien am wichtigsten sind, und genau das, was ein Components-Glob übersieht.
Schritt drei ist der häufigste selbst verursachte Fehler bei Cursor-Design-Setups. Eine Design-Regel, die nur an Komponenten-Dateien bindet, ist während der Erstellung einer Seite inaktiv – doch genau dort fallen die Entscheidungen über Komposition, Hierarchie und Spacing.
Aufteilung nach Geltung, nicht nach Inhalt
Der Instinkt ist, nach Themen zu trennen – colors.mdc, typography.mdc, spacing.mdc. Das ist die falsche Achse. Diese drei gelten immer zur gleichen Zeit; eine Trennung ändert also nichts, außer der Anzahl der zu pflegenden Dateien.
Trennen Sie stattdessen nach dem Geltungsbereich der Wahrheit. Die Frage für jede Regel lautet: Wann ist dies falsch? Wenn die Antwort „nie“ ist, gehört sie in die dauerhaft aktive Datei. Wenn die Antwort „im Dashboard“ ist, gehört sie in eine spezifische Regel, und ihr Gegenstück in eine andere.
| Aufteilung nach Thema | Aufteilung nach Geltungsbereich | |
|---|---|---|
| Dateien | Farben, Typografie, Spacing, Motion | Design (immer), Marketing-Oberflächen, kompakte Oberflächen |
| Ladezeitpunkt | Alle gleichzeitig – sie teilen sich einen Scope | Nur dort, wo sie anwendbar sind |
| Widersprüche | Gleichzeitig im Kontext, heben sich gegenseitig auf | Nie gleichzeitig präsent, daher kann jede Regel absolut sein |
| Always-on-Gewichtung | Alles, immer | Nur die nicht verhandelbaren Vorgaben |
Dies ist dieselbe Struktur, zu der große Designsysteme unabhängig voneinander gelangen – Spotify's Encore ist ein Fundament mit spezialisierten Subsystemen darüber, Carbon ist ein Kern mit Domain-Layern. Ein Rules-Verzeichnis ist eine sehr kleine Version derselben Idee und scheitert auf dieselbe Weise, wenn das Fundament Dinge absorbiert, die lokal hätten bleiben sollen.
Was in die Always-on-Regel gehört
Beschränken Sie diese auf einen Bildschirm. Ihr Zweck ist es nicht, das Designsystem zu enthalten – das Designsystem lebt in DESIGN.md und in Ihrer Token-Datei. Ihr Zweck ist es, den Coding-Agent dazu zu bringen, diese zu lesen, und die wenigen Einschränkungen festzuhalten, die nirgendwo verletzt werden dürfen.
---
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.Jede Zeile dort ist eine Einschränkung, die verletzt und geprüft werden kann. Keine einzige beschreibt eine Ästhetik. Das ist beabsichtigt und ist der entscheidende Unterschied zwischen einer Rules-Datei, die den Output verändert, und einer, die es nicht tut.
Der letzte Abschnitt wird unterschätzt. „Nutzen Sie die nächstgelegene existierende Komponente, und falls keine existiert, geben Sie dies an, bevor Sie eine neue schreiben“ verwandelt das häufigste Versagen des Agents – das stille Erfinden eines neuen Patterns – in eine Frage. Dieser eine Absatz verhindert mehr Drift als eine ganze Seite visueller Beschreibungen.
Warum speziell Verbote
Wir haben 299 öffentliche DESIGN.md-Dateien analysiert – dieselbe Art von Artefakt wie eine Design-Rules-Datei, geschrieben für denselben Zweck – und gemessen, was sie tatsächlich enthalten, statt was sie zu enthalten vorgeben.
| Anteil der Dateien | |
|---|---|
| Keinerlei Verbote | 76% |
| Farben als reine Hex-Werte, keine semantische Rolle | 86% |
| Keine Definition für den Dark Mode | 69% |
| Keine markanten Motive | 57% |
| Mindestens ein vages Adjektiv als Richtlinie | 54% |
| Kein konkreter Größenwert vorhanden | 44% |
Die Zahl der Verbote ist die entscheidende. Drei Viertel dieser Dateien sagen einem Modell nur, was erlaubt ist, wodurch alles andere standardmäßig erlaubt bleibt – und alles andere macht den Großteil eines Interfaces aus.
Betrachten Sie den Unterschied konkret. „Nutzen Sie --color-primary für primäre Aktionen“ wird durch eine Seite erfüllt, die die Primärfarbe auch für Überschriften, Links, Icon-Füllungen, einen Rahmen und einen Gradienten verwendet. Fügt man hinzu: „Nutzen Sie die Akzentfarbe niemals für Text, Rahmen, Hintergründe oder Gradienten“, erzeugt derselbe Satz nun ein zurückhaltendes Interface. Die Erlaubnis hat sich nicht geändert. Das Verbot hat die gesamte Wirkung erzielt.
Eine Regel, die nur sagt, was erlaubt ist, lässt alles andere erlaubt. Und alles andere ist der Großteil des Interfaces.
Die Zahl der vagen Adjektive verschärft dies. „Clean“ erscheint in 39 % dieser Dateien und „modern“ in 36 %. Ein Modell, das um „clean und modern“ gebeten wird, produziert das statistische Zentrum seiner Trainingsdaten, was genau der Grund ist, warum KI-generierte Interfaces konvergieren und gleich aussehen. Keines dieser Wörter schließt irgendetwas aus.
Die Scoped-Rules
Sobald die Always-on-Regel nur noch die Universellen enthält, können die oberflächenspezifischen Regeln absolut statt vorsichtig formuliert sein. Zwei Beispiele zur Veranschaulichung der Struktur:
---
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.Keines von beiden enthält einen Vorbehalt, da keines jemals zusammen mit dem anderen im Kontext steht. Das ist der gesamte Vorteil der Aufteilung.
Prüfen Sie Ihre Globs gegen die Realität, bevor Sie ihnen vertrauen. Route-Groups, src/-Präfixe und kolokierte Komponenten-Verzeichnisse durchbrechen naive Patterns, und ein Glob, der nichts findet, schlägt lautlos fehl – Sie erhalten generischen Output ohne Hinweis auf den Grund. Öffnen Sie eine Datei auf der entsprechenden Oberfläche und bestätigen Sie, dass die Regel greift.
Was Regeln nicht enthalten sollten
Drei Dinge landen oft in Rules-Dateien, die eigentlich woanders hingehören, und jedes davon hat Kosten.
| Warum es dort scheitert | Wo es hingehört | |
|---|---|---|
| Die vollständige Token-Liste | Dupliziert die Token-Datei. Beide driften auseinander, und der Agent hat nun zwei widersprüchliche Quellen | Die CSS- oder Theme-Datei, referenziert aus DESIGN.md |
| Komponenten-API-Dokumentation | Zu groß für den permanenten Kontext und bereits mit dem nächsten Release veraltet | Ein MCP-Server, der bei Bedarf abgefragt wird |
| Ästhetische Beschreibung | "Sophisticated, minimal, premium" schränkt nichts ein und verbraucht nur Kontext | Nirgendwo. Ersetzen Sie dies durch die Constraints, die diesen Eindruck erzeugen |
Das Duplikationsproblem in der ersten Zeile ist bemerkenswert. Sobald ein Hex-Wert sowohl in der Rules-Datei als auch in der Token-Datei erscheint, wird einer von beiden aktualisiert und der andere nicht – der Agent wird dann selbstbewusst den veralteten Wert verwenden. Rules sollten auf die Source of Truth verweisen und diese niemals wiederholen.
Die Ebene unter den Rules
All dies setzt voraus, dass es etwas gibt, auf das man verweisen kann. Eine Rules-Datei, die lediglich besagt „lies DESIGN.md“, ist nur so gut wie die DESIGN.md selbst. Die Daten zeigen, dass die meisten dieser Dateien lediglich eine Palette mit angehängten Adjektiven sind.
Den Unterschied macht jedes Mal dieselbe Liste: Farben als semantische Rollen statt als Hex-Werte, eine Typografie-Skala mit realen Werten, eine Spacing-Skala, ein definierter (statt abgeleiteter) Dark Mode, Motive, die beschreiben, was das Design bewirkt, und eine explizite Liste dessen, was verboten ist. Sobald dies schriftlich fixiert ist, wird die Rules-Datei kurz, da sie größtenteils nur aus Verweisen besteht.
Identity Forge Design-Kits liefern genau diese Struktur und serialisieren in eine DESIGN.md. Installieren Sie ein Kit in einem Cursor-Projekt mit npx --yes identityforge@latest install --client cursor oder durchsuchen Sie zuerst die Kits. Der Cursor Designsystem-Guide erklärt die Anbindung des MCP-Servers.
Ein funktionierendes Set
Für die meisten Projekte ist die Anzahl von vier Dateien ideal; mehr ist ein Warnsignal:
design.mdc—alwaysApply: true. Eine Bildschirmseite. Verweist aufDESIGN.md, enthält die überall gültigen Verbote und weist den Agenten an, zu fragen, bevor ein neues Pattern erfunden wird.surface-marketing.mdc— glob-scoped. Die Rules, die nur dort gelten, wo der Leser die Seite in Sekunden überfliegt.surface-app.mdc— glob-scoped. Die Rules, die nur dort gelten, wo der Nutzer den ganzen Tag arbeitet.a11y.mdc—alwaysApply: true, falls Ihr Team dies separat benötigt. Fokus-Zustände, Mindestkontraste, semantische Elemente, Anforderungen an Labels.
Falls Sie eine fünfte Datei wünschen, prüfen Sie, ob es sich wirklich um einen neuen Scope of Truth handelt oder um ein Thema, das in eine bestehende Datei gehört. Themen vermehren sich endlos; Scopes nicht.
Wo liegen Cursor Rules?
In .cursor/rules/ als .mdc-Dateien, jeweils mit Frontmatter zur Steuerung des Ladens. alwaysApply: true hält eine Rule für jede Anfrage im Kontext; globs bindet eine Rule ein, wenn entsprechende Dateien betroffen sind. Eine Design-Rule, die beim Page-Authoring gelten soll, muss permanent aktiv sein und darf nicht per Glob auf Komponenten beschränkt werden.
Sollte mein Designsystem in einer Cursor-Regel oder in der DESIGN.md definiert werden?
In der DESIGN.md, wobei die Rule darauf verweist. Wenn das System in einer versionierbaren, tool-agnostischen Datei liegt, dient dieselbe Definition für Cursor, Claude Code, einen MCP-Server und jeden Menschen, der das Repo liest. Die Duplizierung von Token-Werten in die Rules-Datei führt zwangsläufig zu Drift.
Wie lang sollte eine Cursor Design-Rule sein?
Eine permanent aktive Rule sollte auf eine Bildschirmseite passen. Darüber hinaus konkurriert sie mit der eigentlichen Aufgabe um die Aufmerksamkeit des Modells, und die Einhaltung einzelner Zeilen sinkt. Wenn sie wächst, ist das ein Signal, Inhalte in die DESIGN.md oder in eine scoped Rule auszulagern, nicht ein Signal, weiter zu ergänzen.
Warum ignoriert der Agent meine Design-Rules?
Drei häufige Ursachen: Die Rule ist glob-scoped und wird nicht geladen (prüfen Sie die tatsächlichen Dateipfade), die Rule beschreibt eine Ästhetik, statt Constraints zu definieren, die verletzt werden können, oder die permanent aktive Datei ist so groß geworden, dass keine einzelne Zeile mehr heraussticht. Verbote in einer kurzen Datei werden weitaus zuverlässiger befolgt als Beschreibungen in einer langen.
Kann ich stattdessen .cursorrules verwenden?
Der Ansatz mit einer einzelnen .cursorrules-Datei funktioniert zwar noch, bietet aber kein bedingtes Laden. Jede Rule ist also immer aktiv, wodurch das Problem der Widersprüche schneller auftritt. Das Verzeichnis .cursor/rules/ existiert genau deshalb, um unterschiedliche Rules an unterschiedlichen Stellen anzuwenden – genau die Struktur, die ein Designsystem benötigt.