La documentación que hace que un asistente genere interfaz correcta a la primera: tokens con su intención, componentes con reglas de uso, y los antipatrones declarados.
Cuándo usarlo: Documentar tokens, componentes y antipatrones de un design system para que un agente de código genere interfaz correcta sin supervisión
Herramienta recomendada: Claude Code
Actúa como responsable de un design system con experiencia en equipos donde el código de interfaz lo escribe en parte un agente de IA. Quiero documentar el sistema para que genere interfaz correcta sin supervisión constante. ## Contexto que necesito 1. Estado del sistema: tokens, componentes, dónde vive la documentación. 2. Tecnología del frontend y librería de componentes. 3. Los tres errores de interfaz que el equipo (o el agente) repite. 4. Quién consume la documentación hoy: diseño, desarrollo, ambos. ## El problema Un asistente que no encuentra la regla, la inventa: usa un color aproximado en lugar del token, crea un botón nuevo en lugar de usar el existente y espacia a ojo. No es un fallo del modelo, es documentación que solo funciona si ya conoces el sistema. ## Paso 1 — Tokens con intención, no solo con valor Cada token necesita, además del valor, cuándo se usa y cuándo no: | Token | Valor | Se usa para | No se usa para | |---|---|---|---| | `color-surface-raised` | #FFFFFF | Tarjetas y menús sobre el fondo | Fondo de página | | `space-4` | 16px | Separación entre elementos relacionados | Márgenes de sección | Sin la columna «no se usa para», el agente elegirá por similitud de nombre. ## Paso 2 — Componentes con reglas de decisión Para cada componente: qué resuelve, cuándo usarlo, cuándo usar otro en su lugar (con el nombre del otro), variantes permitidas, propiedades obligatorias, comportamiento responsivo, estados (por defecto, hover, foco, deshabilitado, carga, error) y accesibilidad exigida. Añade el árbol de decisión de los casos que se confunden: botón contra enlace, modal contra panel lateral contra página, aviso en línea contra notificación flotante. ## Paso 3 — Antipatrones declarados Lista explícita de lo que no se hace, con el motivo y la alternativa correcta: - Valores de color, espaciado o tipografía escritos a mano. - Componentes nuevos que duplican uno existente con otro nombre. - Anular estilos del sistema desde el consumidor. - Iconos fuera del set. - Texto de interfaz que no sigue la guía de voz. ## Paso 4 — Ejemplos completos Tres pantallas de referencia montadas solo con el sistema, con el código completo y comentado. Un ejemplo completo enseña más que veinte páginas de prosa, y es lo que un agente imita. ## Paso 5 — Bloque de instrucciones Redacta el fragmento listo para pegar en el archivo de instrucciones del repositorio: dónde están los tokens y los componentes, las cinco reglas duras, los antipatrones y la orden de preguntar antes de crear un componente nuevo. ## Entregables 1. Tabla de tokens con intención y contraindicaciones. 2. Fichas de los componentes con árboles de decisión. 3. Lista de antipatrones con alternativa. 4. Las tres pantallas de referencia con código. 5. Bloque de instrucciones para el repositorio.