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 die Datei vierhundert Zeilen zu Farben, Typografie, Spacing, Animationen, Barrierefreiheit, Formular-Patterns, Empty States und einen Absatz zum Tone of Voice. Die Datei 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 der Output 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 selbstverschuldete Fehler bei Cursor-Design-Setups. Eine Design-Regel, die nur an Komponenten-Dateien bindet, ist während der Erstellung von Seiten 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 Aufteilung ändert also nichts, außer der Anzahl der Dateien, die gewartet werden müssen.
Teilen Sie stattdessen nach dem Geltungsbereich der Wahrheit auf. 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 | Alles gleichzeitig: Sie teilen sich einen Geltungsbereich | 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: Spotifys Encore ist ein Fundament mit spezialisierten Subsystemen darüber, Carbon ist ein Core 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 Agenten dazu zu bringen, diese zu lesen, und die wenigen Constraints zu halten, 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 ein Constraint, der 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. "Passen Sie sich an die nächste existierende Komponente an, und falls keine existiert, geben Sie dies an, bevor Sie eine neue erstellen" verwandelt den häufigsten Fehler des Agenten – 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 beanspruchen.
| 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. "Verwenden 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: "Verwenden 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 Universalien enthält, können die oberflächenspezifischen Regeln absolut statt vorsichtig formuliert sein. Zwei Beispiele, die die Struktur zeigen:
---
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-Gruppen, src/-Präfixe und kolokierte Komponenten-Verzeichnisse durchbrechen naive Patterns, und ein Glob, der nichts findet, schlägt stillschweigend 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. Die beiden Versionen driften auseinander, sodass der Agent zwei widersprüchliche Quellen hat | Die CSS- oder Theme-Datei, referenziert aus DESIGN.md |
| Dokumentation der Komponenten-API | 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 | Gar nicht. 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 voller Zuversicht 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 aus dem Corpus 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 beschreibt die Anbindung des MCP-Servers.
Ein funktionales 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, das steuert, wann sie geladen werden. 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 Rule oder in der DESIGN.md liegen?
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. Das Duplizieren 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 einen Bildschirm passen. Darüber hinaus konkurriert sie mit der eigentlichen Aufgabe um die Aufmerksamkeit des Modells, wodurch die Einhaltung einzelner Zeilen sinkt. Wenn sie wächst, ist das ein Signal, Inhalte in die DESIGN.md oder in eine scoped Rule auszulagern, und kein Signal, immer 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 hervorsticht. 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. Somit ist jede Rule immer aktiv, und das Problem der Widersprüche tritt schneller auf. Das Verzeichnis .cursor/rules/ existiert genau deshalb, um unterschiedliche Rules an unterschiedlichen Stellen anzuwenden – genau die Struktur, die ein Designsystem benötigt.