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 real 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 es 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 que adoptan los sistemas de diseño a gran escala 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 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 altera el resultado y uno que no lo hace.

Analizamos 299 archivos DESIGN.md públicos —el mismo tipo de artefacto que un archivo de reglas de diseño, escrito con el mismo propósito— y medimos qué contienen en lugar de qué pretenden 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 excluye nada.

Una vez que la regla permanente contiene solo los universales, las reglas específicas de cada 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 salvedades, 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 suelen poner en los archivos de reglas que pertenecen a otro lugar, y cada una tiene un coste.

El problema de la duplicación de la primera fila merece especial atención. Una vez que un valor hexadecimal aparece tanto en el archivo de reglas como en el de tokens, uno de ellos se actualizará y el otro no, y el agente utilizará con seguridad el valor obsoleto. Las reglas deben apuntar a la fuente de verdad, nunca repetirla.

Todo lo anterior asume que hay algo a lo que valga la pena apuntar. Un archivo de reglas que dice "lea DESIGN.md" es tan bueno como lo sea el propio DESIGN.md, y las estadísticas del corpus indican que la mayoría de esos archivos son solo una paleta con adjetivos adjuntos.

Lo que marca la diferencia es siempre la misma lista: colores como roles semánticos en lugar de valores hexadecimales, una escala tipográfica con números reales, una escala de espaciado, un modo oscuro definido en lugar de derivado, motivos que declaren qué hace el diseño y una lista explícita de lo que está prohibido. Una vez redactado esto, el archivo de reglas se vuelve breve, ya que la mayor parte consiste en punteros.

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

1. design.mdc — alwaysApply: true. Una sola pantalla. Apunta a DESIGN.md, contiene las prohibiciones universales y ordena al agente preguntar antes de inventar un patrón.
2. surface-marketing.mdc — alcance por glob. Las reglas que solo se aplican donde el lector escanea la información durante unos segundos.
3. surface-app.mdc — alcance por glob. Las reglas que solo se aplican donde el usuario pasa todo el día.
4. a11y.mdc — alwaysApply: true si su equipo necesita que se especifique por separado. Estados de foco, mínimos de contraste, elementos semánticos, requisitos de etiquetas.

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