Cursor-Regeln für Tailwind CSS und shadcn/ui

Cursor-Regeln, die Tailwind v4-Konventionen und shadcn/ui-Komponentenmuster erzwingen und verhindern, dass Agenten bereits vorhandene Primitive neu erfinden.

Fügen Sie dies in .cursor/rules/tailwind-shadcn.mdc ein (oder in Ihre projektbezogene Cursor-Regeldatei). Cursor lädt alle .mdc-Dateien in .cursor/rules/ automatisch beim Öffnen des Projekts.

Cursor-Regeldatei

# Tailwind CSS + shadcn/ui Rules

## Tailwind conventions
- Use Tailwind CSS v4. Class names follow the v4 API — do NOT use deprecated v3
  class names (e.g. use `shadow-sm` not `drop-shadow-sm` for box shadows on elements).
- All utility classes must be static strings so Tailwind's content scanner can detect
  them. Never build class names with string concatenation or template literals unless
  the full class name is in the source (e.g. `bg-${color}` is forbidden; use a lookup
  object instead).
- Class order: layout → box model → typography → visual (bg, border, shadow) →
  interactive (hover, focus) → responsive breakpoints. Use `prettier-plugin-tailwindcss`
  to enforce this automatically — do not manually reorder.
- Never write custom CSS for spacing, color, or typography that can be expressed with a
  Tailwind utility. Custom CSS lives in `src/styles/` and must be justified by a comment.
- Use `cn()` from `@/lib/utils` to merge conditional classes. Never use `clsx` or
  `classnames` directly elsewhere — they are already re-exported from `cn()`.

## shadcn/ui conventions
- Before creating a new UI component, check `src/components/ui/` for an existing
  shadcn/ui primitive. Use it. Do not re-implement Button, Dialog, Input, Select,
  Tooltip, or any other component that shadcn already provides.
- Add new shadcn components with `npx shadcn@latest add <component>` — never copy-paste
  component source manually from the docs.
- Extend shadcn components by wrapping them, not by editing the file in
  `src/components/ui/` directly. Edits there are overwritten by future `shadcn add` runs.
- Use shadcn's `variant` and `size` props before adding className overrides. If a new
  variant is needed, add it to the component's `cva()` definition in `src/components/ui/`.
- Dark mode is handled by the `dark` class on `<html>`. Never use `prefers-color-scheme`
  media queries alongside shadcn — they conflict with the class strategy.
- Do not install `@radix-ui/*` packages directly. They are transitive dependencies of
  shadcn components; adding them directly risks version mismatches.

## Accessibility
- Every interactive shadcn component must have an accessible label. Use `aria-label`,
  `aria-labelledby`, or a visually-hidden `<span>` — never omit it.
- Icon-only buttons must include `<span className="sr-only">Description</span>`.

## Definition of done
- `bun run build` completes without Tailwind class warnings.
- No `className` strings contain dynamic concatenation (`bg-` + variable).
- No new Radix packages in `package.json` that aren't installed via `shadcn add`.
- Storybook (if present) renders the new/modified component without console errors.

Warum diese Regeln

“Überprüfen Sie src/components/ui/, bevor Sie etwas erstellen” ist die wertvollste Regel für shadcn-Projekte. Agenten tendieren dazu, maßgeschneiderte Komponenten zu schreiben – eine eigene <Button>, ein selbst gebautes <Select> – die die bereits im Repository vorhandenen shadcn-Primitive duplizieren. Dies verschwendet Tokens, erzeugt Inkonsistenzen und umgeht die Barrierefreiheitsarbeit, die shadcn kostenlos mitliefert.
Statische Klassennamen-Strings ist eine harte Einschränkung von Tailwinds Scanner. Agenten produzieren routinemäßig Interpolationen im Stil von bg-${color}-500, die kompilieren, aber zur Laufzeit kein CSS erzeugen, was unsichtbare Styling-Fehler verursacht, die nur in Produktions-Builds auftreten.

Geeignet für

Next.js- oder Astro-Projekte, die bereits shadcn/ui mit Tailwind v4 verwenden, bei denen das Hauptrisiko darin besteht, dass Agenten vorhandene Primitive duplizieren oder gegen das Designsystem arbeiten.

Nicht geeignet

Projekte, die CSS Modules, Emotion oder Styled Components verwenden – Tailwind-Klassenreihenfolge-Regeln sind irrelevant und cn() existiert nicht.

Cursor-Regeln für Tailwind CSS und shadcn/ui

Cursor-Regeldatei

Warum diese Regeln

Geeignet für

Nicht geeignet

Verwandt