Reglas de Cursor para Tailwind CSS y shadcn/ui

Reglas de Cursor que imponen las convenciones de Tailwind v4 y los patrones de componentes de shadcn/ui, evitando que los agentes reinventen primitivas que ya existen.

Pega esto en .cursor/rules/tailwind-shadcn.mdc (o en tu archivo de reglas de Cursor a nivel de proyecto). Cursor carga automáticamente todos los archivos .mdc en .cursor/rules/ al abrir el proyecto.

Archivo de reglas de Cursor

# 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.

Por qué estas reglas

“Revisa src/components/ui/ antes de crear algo” es la regla de mayor valor para proyectos shadcn. Los agentes por defecto escriben componentes personalizados — un <Button> hecho a medida, un <Select> manual — que duplican las primitivas de shadcn ya existentes en el repositorio. Esto desperdicia tokens, crea inconsistencia y omite el trabajo de accesibilidad que shadcn ofrece de forma gratuita.
Cadenas de nombre de clase estáticas es una restricción estricta del escáner de Tailwind. Los agentes producen rutinariamente interpolaciones de estilo bg-${color}-500 que compilan pero no producen CSS en tiempo de ejecución, causando errores de estilo invisibles que solo aparecen en builds de producción.

Buen ajuste

Proyectos de Next.js o Astro que ya usan shadcn/ui con Tailwind v4, donde el riesgo principal es que los agentes dupliquen primitivas existentes o luchen contra el sistema de diseño.

No es adecuado

Proyectos que usan CSS Modules, Emotion o Styled Components — las reglas de orden de clases de Tailwind son irrelevantes y cn() no existe.

Reglas de Cursor para Tailwind CSS y shadcn/ui

Archivo de reglas de Cursor

Por qué estas reglas

Buen ajuste

No es adecuado

Relacionados