Reglas de Cursor para un sistema de diseño: por qué un solo archivo deja de funcionar

El consejo inicial es acertado. Cursor lee los archivos .cursor/rules/*.mdc, cada uno con un frontmatter que controla cuándo se carga: alwaysApply para reglas que siempre están en contexto, y globs para reglas que se activan cuando hay archivos coincidentes. Un único design.mdc con alwaysApply: true es muy útil al principio.

Entonces ocurren tres cosas, en este orden.

1. 1

   El archivo crece

   Cada vez que el agente comete un error, alguien añade una línea. A los seis meses, tiene cuatrocientas líneas que cubren color, tipografía, espaciado, animación, accesibilidad, patrones de formularios, estados vacíos y un párrafo sobre el tono de voz. Siempre está en contexto, compite con la tarea actual por la atención y el cumplimiento de cualquier línea individual ha disminuido.

2. 2

   Las reglas empiezan a contradecirse

   "Use un espaciado generoso" se escribió para el sitio de marketing. "Mantenga las tablas densas" se escribió para el dashboard. Ambas están en el mismo archivo siempre activo, por lo que ambas son válidas en todas partes; por lo tanto, ninguna es realmente una regla.

3. 3

   Alguien limita el alcance para solucionar esto y la regla deja de activarse

   La solución obvia es globs: components/**. Entonces el agente escribe un nuevo layout de página en app/, no se aplica ninguna regla de diseño y el resultado es genérico. Los nuevos layouts son precisamente donde la guía de diseño es más importante y exactamente lo que un glob de componentes ignora.

El instinto es dividir por tema: colors.mdc, typography.mdc, spacing.mdc. Ese es el eje equivocado. Esas tres reglas son válidas al mismo tiempo, por lo que dividirlas no cambia nada, excepto la cantidad de archivos que debe mantener.

Divida, en cambio, por alcance de validez. La pregunta para cada regla es: ¿cuándo es esto falso? Si la respuesta es «nunca», pertenece al archivo siempre activo. Si la respuesta es «en el dashboard», pertenece a una regla limitada y su contraparte pertenece a otra.

Esta es la misma estructura a la que llegan los sistemas de diseño grandes de forma independiente: Encore de Spotify es una base con subsistemas especializados encima; Carbon es un núcleo con capas de dominio. Un directorio de reglas es una versión muy pequeña de la misma idea, y falla de la misma manera cuando la base absorbe elementos que deberían haber sido locales.

Limítela a una sola pantalla. Su función no es contener el sistema de diseño: el sistema de diseño reside en DESIGN.md y en su archivo de tokens. Su función es obligar al agente a leer esos archivos y mantener el puñado de restricciones que nunca deben violarse en ningún lugar.

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

Cada línea allí es una restricción que puede violarse y verificarse. Ninguna de ellas describe una estética. Esto es deliberado, y es la diferencia fundamental entre un archivo de reglas que cambia el resultado y uno que no lo hace.

Analizamos 299 archivos DESIGN.md públicos (el mismo género de artefacto que un archivo de reglas de diseño, escrito para el mismo propósito) y medimos qué contienen en lugar de qué afirman contener.

La cifra de las prohibiciones es la importante. Tres cuartas partes de estos archivos le dicen al modelo solo lo que está permitido, lo que deja todo lo demás permitido por defecto, y todo lo demás es la mayor parte de una interfaz.

Considere la diferencia concretamente. "Use --color-primary para acciones primarias" se cumple en una página que también usa el color primario para encabezados, enlaces, rellenos de iconos, un borde y un degradado. Añada "nunca use el color de acento para texto, bordes, fondos o degradados" y la misma frase produce ahora una interfaz contenida. El permiso no cambió. La prohibición hizo todo el trabajo.

La cifra de los adjetivos vagos lo agrava. "Limpio" aparece en el 39% de estos archivos y "moderno" en el 36%. Un modelo al que se le pide algo limpio y moderno produce el centro estadístico de sus datos de entrenamiento, que es precisamente por qué las interfaces generadas por IA convergen en la misma apariencia. Ninguna de las dos palabras descarta nada.

Una vez que la regla constante contiene solo los universales, las reglas específicas de la superficie pueden ser absolutas en lugar de ambiguas. Dos ejemplos que muestran la estructura:

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

Ninguna de las dos contiene una salvedad, porque ninguna está nunca en el contexto junto a la otra. Ese es todo el beneficio de la división.

Hay tres cosas que se ponen en los archivos de reglas que pertenecen a otro lugar, y cada una tiene un coste.

Vale la pena analizar el problema de duplicación de la primera fila. Una vez que un valor hex aparece tanto en el archivo de reglas como en el de tokens, uno de ellos se actualizará y el otro no, y el agente usará con total seguridad el valor desactualizado. Las reglas deben apuntar a la fuente de verdad, nunca repetirla.

Todo lo anterior asume algo que merece la pena señalar. Un archivo de reglas que diga «lee DESIGN.md» es tan bueno como lo sea DESIGN.md, y las cifras del corpus indican que la mayoría de esos archivos son solo una paleta con adjetivos adjuntos.

Lo que marca la diferencia es la misma lista de siempre: colores como roles semánticos en lugar de valores hex, una escala tipográfica con números reales, una escala de espaciado, un modo oscuro definido en lugar de derivado, motivos que indiquen qué hace el diseño y una lista explícita de lo que está prohibido. Escriba eso y el archivo de reglas será breve, porque la mayor parte será simplemente una referencia.

Para la mayoría de los proyectos, cuatro archivos es el número adecuado y tener más es una señal de alerta:

1. design.mdc: alwaysApply: true. Una sola pantalla. Apunta a DESIGN.md, contiene las prohibiciones que son válidas en todas partes y le indica al agente que pregunte antes de inventar un patrón.
2. surface-marketing.mdc: con alcance por glob. Las reglas que solo son válidas donde el lector está escaneando durante segundos.
3. surface-app.mdc: con alcance por glob. Las reglas que solo son válidas donde el usuario pasa todo el día.
4. a11y.mdc: alwaysApply: true si su equipo necesita que se especifique por separado. Estados de enfoque, mínimos de contraste, elementos semánticos, requisitos de etiquetas.

Si siente la necesidad de añadir un quinto, compruebe si realmente se trata de un nuevo ámbito de verdad o de un tema que pertenece a uno ya existente. Los temas se multiplican infinitamente; los ámbitos no.