Sistema de diseño para Claude Code: 4 piezas para una UI de marca

Un sistema de diseño para Claude Code es un stack de contexto dentro del repositorio que muestra al agente cómo es tu marca, cómo debe implementarla y cómo comprobar el resultado. Una versión práctica utiliza tres archivos Markdown y un directorio examples/. Sustituye los prompts repetidos por evidencia, reglas y patrones aprobados que se pueden versionar.

El flujo ganó visibilidad gracias al sistema de marca en cuatro partes y los prompts de Charlie Hills. Lo útil no es que los nombres de archivo sean mágicos. Es que la evidencia visual, las reglas de implementación y los controles de calidad se convierten en entradas duraderas del proyecto, en lugar de perderse en un chat.

Esta guía convierte la idea en un flujo que un equipo de producto puede revisar, probar y mantener. Responde a la búsqueda específica cómo hacer que Claude Code siga un sistema de diseño. No compite con nuestro análisis general sobre contexto para agentes de programación ni con la checklist de software generado con IA, enfocada en producción.

¿Cuáles son las cuatro piezas del sistema?

En sentido estricto, son cuatro piezas y no cuatro archivos, porque la cuarta es un directorio. Solo CLAUDE.md tiene un significado especial para Claude Code. La documentación oficial sobre memoria de Claude Code explica que los archivos CLAUDE.md del proyecto se cargan como instrucciones persistentes y recomienda que sean concretos, concisos y estructurados. REFERENCE.md, DESIGN.md y examples/ funcionan porque indicas expresamente a Claude que los lea.

¿Cómo debe organizarse el proyecto?

tu-proyecto/
├── CLAUDE.md
├── REFERENCE.md
├── DESIGN.md
├── examples/
│   ├── README.md
│   ├── dashboard-aprobado.png
│   ├── landing-aprobada.png
│   └── pricing-card-aprobada.html
├── src/
└── tests/

Añade a examples/README.md una fila por artefacto con responsable, fecha de aprobación, origen, partes reutilizables y excepciones conocidas. Así, una campaña antigua o una pantalla experimental no se convierte por accidente en regla permanente.

Prompt 1: convertir trabajo aprobado en REFERENCE.md

Elige entre tres y cinco ejemplos que representen bien la marca actual. Prioriza pantallas de producción propias, el brand deck, gráficos de marketing o la biblioteca de componentes. No copies al repositorio recursos protegidos de competidores. La inspiración puede orientar una decisión, pero los ejemplos reutilizables deben ser tuyos o tener una licencia adecuada.

Revisa todos los archivos de examples/. Separa lo observable de lo que debes preguntar.

Redacta REFERENCE.md con:
1. inventario de fuentes y estado de aprobación
2. colores con valores medidos y funciones observadas
3. tipografía, tamaños y jerarquía
4. patrones de espaciado, grid y alineación
5. posición del logo y espacio de protección
6. componentes y composiciones recurrentes
7. cinco patrones que la marca debe evitar
8. preguntas abiertas

No inventes valores que falten. Muestra el borrador antes de guardarlo.

El mejor resultado separa evidencia y política. “Las tres pantallas aprobadas usan 24 px entre tarjetas” es una observación. “Todos los grupos de tarjetas deben usar 24 px” es una regla que una persona debe aprobar. Mezclarlas convierte decisiones históricas accidentales en doctrina.

Prompt 2: usar CLAUDE.md como router

Mantén el puntero corto. Un archivo enorme consume contexto en cada sesión, aunque el material de diseño solo sea necesario al trabajar en la interfaz.

## Trabajo de interfaz

Antes de crear o cambiar una UI, lee REFERENCE.md y DESIGN.md. Después, inspecciona el ejemplo aprobado más cercano en examples/.
Reutiliza componentes y tokens semánticos antes de crear otros.
Si las fuentes se contradicen o no cubren una decisión importante, pregunta en lugar de adivinar.
Antes de terminar, compara el resultado renderizado con las reglas y comunica cada excepción intencionada.

Esta capa indica cuándo leer, qué fuente tiene prioridad y cómo verificar. Si tu CLAUDE.md ya es largo, usa reglas limitadas a las rutas del frontend. Un import ordena mejor el contenido, pero la documentación de Anthropic aclara que el texto importado también entra en el contexto inicial.

Prompt 3: convertir la referencia en DESIGN.md

DESIGN.md es el contrato de construcción. El emergente formato DESIGN.md de Google Labs define un archivo autónomo con tokens opcionales y legibles por máquinas en el frontmatter YAML, más razonamiento de diseño en Markdown. Puedes seguirlo para ganar portabilidad, pero Claude Code no lo exige.

Lee REFERENCE.md y examples/README.md. Después, revisa todos los ejemplos aprobados.

Redacta DESIGN.md como contrato de implementación con:
1. tokens de color semánticos nombrados por función
2. escalas tipográficas y de espacio con valores exactos
3. reglas de layout, grid y breakpoints
4. anatomía, estados y política de reutilización de componentes
5. interacción, movimiento y comportamiento reduced-motion
6. requisitos de accesibilidad
7. ejemplos responsive y casos límite
8. registro de decisiones con fecha, responsable y motivo

Marca cada regla inferida y no aprobada. Pregunta cuando las fuentes discrepen. Muestra el archivo antes de guardarlo.

Los nombres basados en función sobreviven mejor a un rediseño. color-text-primary explica la intención; dark-gray solo describe el valor actual. Si los valores deben circular por herramientas de diseño y build, conserva además una fuente de tokens legible por máquinas.

¿Por qué importan más los ejemplos que un prompt largo?

Las reglas muestran lo permitido. Los ejemplos aprobados enseñan proporción, densidad, jerarquía y composición funcionando juntas. Anthropic ofrece un consejo parecido para su producto separado Claude Design: la guía oficial de configuración del sistema de diseño acepta repositorios, prototipos, presentaciones y recursos de marca, y recomienda aportar ejemplos reales, no solo especificaciones.

Elige por cobertura y no por cantidad. Un dashboard denso, una página de marketing, un flujo con formularios y un estado móvil suelen enseñar más que cincuenta secciones hero casi iguales.

¿Debe DESIGN.md sustituir a los design tokens?

No. DESIGN.md explica la intención; un archivo de tokens ofrece un formato estricto para herramientas. Utiliza ambos cuando los valores deban entrar en código, diseño y validación. El formato estable del Design Tokens Community Group define un modelo JSON para nombres, valores, tipos y metadatos. El archivo de tokens gobierna los valores exactos; DESIGN.md explica cuándo y por qué aplicarlos.

¿Cómo evitar que el sistema copie errores?

1. Etiqueta cada fuente. Aprobada, histórica, experimental o solo inspiración.
2. Define precedencia. Los tokens actuales ganan a una captura en valores exactos. Un componente revisado gana a un gráfico antiguo en comportamiento.
3. Registra excepciones. Si una campaña rompe el grid a propósito, anótalo en el manifiesto.
4. Pide variantes. Solicita tres alternativas antes de pulir. Elegir sigue siendo una decisión humana.
5. Promociona solo lo revisado. Añade el resultado a examples/ después de aprobarlo, no al generarlo.

¿Qué debe comprobar el ciclo de validación?

No dejes que el agente que produce sea el único juez. Puede hacer la primera comparación. Después hacen falta controles deterministas y una persona con autoridad para aprobar.

Archivos de Claude Code o Claude Design: ¿cuál conviene?

¿Cómo desplegarlo en un equipo?

1. Selecciona trabajo representativo. Incluye UI de producto, marketing y al menos un estado difícil.
2. Redacta y revisa las fuentes. Diseño es responsable de la verdad visual; ingeniería, de la viabilidad.
3. Conecta el router. Mantén CLAUDE.md corto y comprueba que Claude carga las fuentes.
4. Pilota tres tareas. Un componente nuevo, un cambio de pantalla y una reparación responsive.
5. Mide el retrabajo. Registra rondas de revisión, tokens no aprobados, duplicados, defectos de accesibilidad y primeras versiones aceptadas.
6. Asigna mantenimiento. Nombra responsables para tokens, componentes, ejemplos y decisiones.

La decisión de compra no es “¿qué pack de prompts elegimos?”, sino “¿quién posee el contrato de diseño, cómo comprobamos su cumplimiento y qué cambios exigen aprobación?”. El servicio de AI Enablement de Wavect ayuda a convertir el uso puntual de agentes en un flujo gobernado con contexto del repositorio, evaluaciones y gates de revisión. Si el producto generado ya necesita hardening, la guía del prototipo vibe-coded a producción ayuda a definir el siguiente paso.

Límite de la investigación

Revisado el 2 de septiembre de 2026 con el flujo original, la documentación actual de memoria de Claude Code, la especificación DESIGN.md de Google Labs, la guía de Claude Design de Anthropic y el formato estable del Design Tokens Community Group. El comportamiento del producto y la disponibilidad beta pueden cambiar. No afirmamos una mejora cuantitativa porque no existe un benchmark independiente entre equipos para este flujo.