joo6077/design-system

Trampas

1. Prohibido usar valores concretos en nombres de tokens — blue-500, primary-blue ✗ → color.text.primary, color.background.brand ✓. Si el valor cambia, el nombre se desincroniza y se rompe inmediatamente con el rebranding o el cambio a modo oscuro.

2. No usar solo primitivos sin semánticos — Vincular color.green.500 directamente a un componente imposibilita el cambio de tema. Es obligatorio pasar por las 3 capas: primitivo → semántico (alias) → componente.

3. No incrustar el modo oscuro en el nombre del token — color-dark-text-primary, color-light-surface ✗. Esto obliga al consumidor a ser dependiente del tema. Lo correcto es mapear valores por modo a un solo token semántico.

4. Prohibido agregar valores arbitrarios sin una escala — Acumular valores arbitrarios como 10px, 14px, 18px, 22px en spacing/radius rompe el sistema. Primero define una escala finita como 2/4/8/12/16/24/32 y rechaza cualquier valor fuera de ella.

5. No reutilices tokens de componente como si fueran globales — Usar button.primary.background en otro componente aumenta el acoplamiento. Solo promueve un token a semántico global cuando sea necesario para múltiples componentes.

6. La tipografía debe ser tokens agrupados, no valores individuales — Usar font-size-14 y line-height-20 por separado provoca errores de combinación. Prioriza tokens de estilo semántico agrupados como font.body.medium que incluyan tamaño/weight/interlineado.

7. Es obligatorio documentar la base del espaciado — Si la base no es 4px, debes documentar la razón. La consistencia al usar solo la escala permitida es más importante que el número base.

8. Reglas de nomenclatura DTCG — No uses { } . en nombres de tokens o grupos, y no los inicies con $ (el prefijo $ es para claves de atributo como $value · $type). La jerarquía se crea anidando grupos JSON. El . solo aparece al escribir referencias para unir nombres de grupo ({color.text.primary}) y no es un carácter dentro del nombre. Fuente: DTCG Format Module 2025.10.

9. Prohibido generar código por stack — Esta habilidad solo produce principios y especificaciones de tokens. No generes código Flutter/React/CSS directamente. Delegue eso a los plugins de la toolkit correspondiente.

10. Usa la herencia de grupos con $extends de DTCG — La palabra clave $extends añadida en DTCG 2025.10 permite la herencia por fusión profunda entre grupos. No definas repetidamente el mismo valor primitivo en varios grupos semánticos; crea un grupo común y refiérelo con $extends. Las referencias circulares están prohibidas y el parser debe detectarlas. Fuente: research-log §A.

11. Las variables CSS :root en ejemplos HTML deben coincidir con los archivos existentes del design-kit — Si en el Paso 4 incluyes fragmentos HTML como ejemplo de especificación de tokens, los valores :root { --color-*: ...; } deben coincidir con los valores de variables CSS en los archivos HTML existentes en design-kit/docs/ o design-kit/templates/. La falta de coincidencia es el comienzo de la fragmentación del sistema y fue una razón real de rechazo (AR-06). Al añadir nuevas variables, reflejalas simultáneamente en los archivos existentes o especifica la razón de la discrepancia.

12. Se recomienda OKLCH para colores primitivos — Tailwind CSS v4 (anunciado el 22-01-2025, última versión estable v4.3.3, 2026-07-16) cambió su paleta por defecto de rgb a oklch, y shadcn/ui v4 también completó la transición de HSL a oklch(). OKLCH proporciona rampas uniformes en los ejes de luminosidad perceptual (L), croma (C) y tono (H), y puede aprovechar la gama ancha P3 para superar las limitaciones de sRGB. Al definir primitivos, prioriza la notación oklch(L% C H). Si se necesita un fallback para navegadores antiguos, incluye también el hex sRGB. Soporte de navegadores: Safari 16.4+ / Chrome 111+ / Firefox 128+ (mismo rango que el soporte de Tailwind v4). Aviso de Figma: La ayuda de Figma enumera cinco modelos de color (Hex, HSB, HSL, CSS, RGB) y OKLCH no está en la lista (About color models). No hay una declaración explícita de que Variables no pueda recibir OKLCH, así que no lo afirmes categóricamente; es una práctica común (como en Obra shadcn kit) incluir una aproximación hex al migrar a Figma. Fuentes: Tailwind v4 blog, Tailwind v4.3.3, shadcn Tailwind v4, Evil Martians OKLCH, MDN oklch().

13. Enumerate-before-Act — Es obligatorio enumerar exhaustivamente antes de modificar tokens — Ante una solicitud de mejora de un sistema de diseño existente (por ejemplo, "maneja el modo oscuro", "limpia los tokens semánticos"), antes de editar, enumera obligatoriamente en el siguiente orden: (1) Lista completa de archivos de tokens existentes + recuento por categoría, (2) Distribución entre Tier 1 primitivo / Tier 2 semántico / Tier 3 componente, (3) Presenta una lista de violaciones para categorías faltantes, violaciones de nomenclatura y elementos sin soporte de modo oscuro, (4) Edita solo después de la aprobación del usuario. Evita el antipatrón de modificar solo una parte y decir "el resto puedes hacerlo siguiendo el ejemplo" (respuesta a insights-report #1 "Proactive quality gaps" · principio skill-design-guide §5.5 Enumerate-before-Act).

14. Cumplimiento del esquema DTCG v1 — los alias son referencias entre llaves — El Design Tokens Community Group publicó el Design Tokens Format Module 2025.10 el 2025-10-28 como su primer informe estable "Final Community Group Report" (DTCG v1). El formato JSON usa los prefijos $value, $type, $description. Los objetos de grupo (sin $value) pueden establecer un valor $type por defecto para el grupo. $extensions es para metadatos de herramientas de proveedores. $schema no está en la lista de atributos de grupo del Informe Final 2025.10 — si una herramienta lo usa como extensión, distingue de la especificación DTCG.

    Notación de alias (punto donde se comete errores frecuentemente): La sintaxis de referencia de la especificación es una cadena entre llaves {group.token}. La Trampa 8 prohíbe { } en los nombres de tokens, porque las llaves están reservadas como envoltorio de referencia — en el valor de la referencia, las llaves son obligatorias. Ambas reglas no entran en conflicto. Una cadena en notación de puntos sin llaves ("color.background.surface") se interpreta como un valor de cadena literal, no como una referencia. Una referencia entre llaves solo puede apuntar a un token completo (objeto con $value), y para apuntar a propiedades individuales dentro del valor de un token, se usa $ref en formato JSON Pointer (RFC 6901) (#/path/to/target).

    {
      "color": {
        "brand": { "$type": "color", "$value": { "colorSpace": "srgb", "components": [0, 0.4, 0.8], "hex": "#0066cc" } },
        "surface": { "$value": "{color.brand}" }
      }
    }
    

    Prohibido: claves value/type heredadas (sin prefijo), claves personalizadas con prefijo $, alias en notación de puntos sin llaves. El valor de un token de color debe usar una estructura de objeto con colorSpace / components / hex (opcional) / alpha (opcional) — la especificación no tiene un formato de cadena hex simple. Herramientas posteriores como Tokens Studio / Style Dictionary / zeroheight asumen este formato. Fuentes: W3C DTCG v1 announcement 2025-10-28, W3C Final Report, DTCG Format Module (drafts), Tokens Studio DTCG vs Legacy.

15. No reemplaces los colores de la aplicación existente con una nueva paleta (Visual Source of Truth Precedence) — Al introducir tokens en un proyecto que ya tiene un esquema de color funcionando, no crees una paleta "mejor" basada en investigación. Primero, extrae y presenta exhaustivamente los valores que realmente se están usando, y luego usa esos valores como base para envolverlos en tokens. Cambiar los valores en sí es una propuesta separada que requiere la aprobación del usuario. Si existen colores de maqueta aprobados visualmente por el usuario (registrados en .design/approvals/), eso tiene prioridad sobre la paleta del proyecto — normalizar un valor aprobado a un solo tinte o token de acento existente es una regresión. Tabla de prioridades: ../../references/visual-change-protocol.md §1.

    Mal:  "He definido el token de color de fondo" (sin leer el fondo de la app existente, creando una nueva rampa neutra)
          → "El color de fondo sigue raro, ¿no deberían estar los colores que se usaban antes?"
    Mal:  Reemplazar el acento de la maqueta aprobada por el token de acento del proyecto → "¿Por qué usas otro color?"
    Bien: Extraer exhaustivamente los valores existentes → presentarlos en una tabla → "Envolveré estos valores en tokens semánticos.
          Si hay algún elemento que necesite ajuste, házmelo saber"
    

16. Las solicitudes de cambio parcial deben afectar solo a ese token — prohibido ajustar valores circundantes simultáneamente — Ante solicitudes como "solo oscurece el color del borde" o "oscurece el surface un paso", no ajustes tokens no mencionados (fondo, fill, texto, radio, elevación) junto con él. Tampoco recalcules pasos adyacentes por consistencia de rampa si eso está fuera del alcance de la solicitud. Antes de editar, deja una lista de cambios / conservación y, después de editar, verifica que los valores en la lista de conservación sigan siendo los mismos. Si un token no intencionado ha cambiado, reviértelo y aplica solo los cambios solicitados. Para reversiones parciales como "el color está bien ahora, pero solo el degradado a como estaba antes", revierte solo el eje solicitado. Detalles: ../../references/visual-change-protocol.md §2.

17. Define solo la categoría de token solicitada — prohibido extender arbitrariamente el andamiaje completo del sistema (respuesta a insights-report #1 malentendido de alcance · #3 sobrediseño) — Si solo te piden "crea la paleta de colores" o "define la escala de espaciado", define solo esa categoría. No andamies todo el sistema (tipografía, radio, elevación, movimiento) de una vez si no fue solicitado. El requisito de "sistema de tokens completo" (otras Trampas imponen las 3 capas y la semántica) se refiere a la integridad dentro de la categoría solicitada, no a la extensión arbitraria de las categorías en sí. Si el alcance es ambiguo, no adivines; en su lugar, pregunta explícitamente: "¿Solo definimos colores o configuramos todo el sistema de tokens?". Si crees que una extensión es valiosa, no la incluyas en la entrega; sepárala como una propuesta independiente con la pregunta: "También recomiendo configurar los tokens de tipografía/espaciado, ¿procedemos?". Lo mismo aplica para la construcción completa de 3 capas (primitivo→semántico→componente) — según la investigación de 2026, la mayoría de los equipos se las arreglan con 2 capas (primitivo+semántico), y la capa de componente solo es necesaria a escala empresarial. No generes 3 capas por defecto sin una solicitud o justificación de escala. Fuente: zeroheight Design Systems Report 2026 (dos capas es el estándar en la práctica, solo la mitad de los equipos usan tres capas completas), material-design.md:281 (adopción progresiva).

Proceso

Paso 1: Detectar el sistema de diseño del proyecto

Busca archivos de tokens/tema en la raíz del proyecto:

# Patrones de búsqueda (independientes del stack)
**/theme/**
**/tokens/**
**/design/**
**/styles/**
**/colors.*
**/typography.*

• Si se encuentra: HAS_DS=true, analiza la estructura de tokens existente
• Si no se encuentra: HAS_DS=false, modo de propuesta de nuevo sistema de tokens

Paso 2: Diseñar la arquitectura de tokens de 3 capas

Todos los tokens se separan en las siguientes 3 capas. No se permite saltarse capas para conectar directamente.

Capa 1 — Primitivo (almacén de valores)
  Ej: color.palette.green.500 = #22c55e
      space.scale.4 = 4px

Capa 2 — Semántico (alias de rol/intención)
  Ej: color.text.success → {color.palette.green.500}
      color.background.surface → {color.palette.neutral.50}  (modo claro)
      color.background.surface → {color.palette.neutral.900} (modo oscuro)

Capa 3 — Componente (anulación de excepción de componente)
  Ej: button.primary.background → {color.background.brand}
      card.border.radius → {radius.md}
  ※ Solo promueve a Capa 2 cuando sea necesario para múltiples componentes

Criterios de obligatoriedad/opcionalidad y nomenclatura semántica por categoría:

Categoría	¿Obligatorio?	Ejemplo Semántico	Criterio de Escala
Color	Obligatorio	text.primary, text.secondary, text.disabled, background.surface, background.brand, border.default, border.subtle	—
Tipografía	Obligatorio	font.display.lg, font.heading.md, font.body.sm, font.label.xs (tamaño+peso+interlineado agrupados)	Se recomienda una proporción de Escala Modular (1.125 Major Second ~ 1.618 Golden Ratio). Fluido: clamp(min, preferred, max)
Espaciado	Obligatorio	space.xs(4), space.sm(8), space.md(16), space.lg(24), space.xl(32), space.2xl(48)	Base 4px. También considera el espaciado fluido basado en clamp().
Radio	Obligatorio	radius.none(0), radius.sm(4), radius.md(8), radius.lg(16), radius.full(9999)	Escala finita
Elevación	Opcional	elevation.level-0 ~ level-4 (valores de sombra)	—
Movimiento	Opcional	motion.duration.fast(100ms), motion.duration.normal(200ms), motion.easing.standard	—

Nota — Material 3 Expressive (anunciado en mayo de 2025): La documentación oficial de Material indica que M3 Expressive, basado en 46 estudios y más de 18.000 participantes, proporciona una gama de colores más amplia, color dinámico, personalización y un sistema de física de movimiento basado en spring. El uso de HCT para crear una paleta tonal para cada color y asignar esos tonos a roles de color no es una característica exclusiva de Expressive, sino parte de la descripción general del sistema de color M3. Las fuentes variables como Roboto Flex son una opción para la expresión y no forman parte de la escala tipográfica M3. Mapear los tonos de la paleta tonal como primitivos y los roles de color como alias semánticos no es una regla oficial, sino una convención de este repositorio para la estructura de tokens de 3 capas. Fuentes: Start building with Material 3 Expressive, Color system, Tipografía, Motion (consultado el 2026-09-28).

Paso 3: HAS_DS=true → Analizar el sistema existente

Compara los tokens existentes con la arquitectura de 3 capas y genera un informe:

• Capas faltantes: Elementos que conectan primitivos directamente con componentes
• Violaciones de nomenclatura: Tokens con valores incrustados en el nombre (blue-500, color-dark-*)
• Falta de soporte de modo oscuro: Tokens semánticos de color sin alias de modo
• Desviación de escala: Uso de valores numéricos arbitrarios fuera de la escala permitida
• Mal uso de tokens de componente: Reutilización de tokens de componente en otros componentes
• Problema de tipografía separada: Casos donde solo se proporcionan tokens individuales de tamaño/weight/interlineado en lugar de tokens agrupados

Paso 4: HAS_DS=false → Generar especificación de tokens

Genera la especificación de tokens siguiendo el formato de templates/design-tokens.md. Presenta al usuario las opciones de cada categoría en el siguiente orden y obtén su acuerdo:

1. Confirmar la paleta de colores de marca (primitivos)
2. Tokens de color semánticos — incluyendo el mapeo para modo claro y oscuro
3. Escala de espaciado (por defecto base 4px, justificar si se cambia)
4. Paquetes de tokens de estilo de tipografía
5. Escala de radio
6. Elevación/movimiento (si es necesario)

Paso 5: Verificar la entrega

• Verificar que todas las categorías obligatorias estén divididas en 3 capas
• Verificar que los tokens semánticos se definan como alias de primitivos (no valores directos ✗)
• Verificar que exista el mapeo semántico para modo claro y oscuro
• Verificar que no haya valores numéricos arbitrarios fuera de la escala permitida
• Si hay tokens de componente, verificar que su alcance esté limitado a ese componente
• *Verificar la consistencia de las variables CSS :root (Trampa #11) — Si la entrega incluye fragmentos HTML :root, comparar con los valores de variables CSS en los archivos HTML existentes en design-kit/docs/ y design-kit/templates/ para asegurar que no haya discrepancias. Si se encuentran discrepancias, actualiza los archivos existentes simultáneamente o especifica la razón.
• *Guía de pipeline Figma Variables → Tokens Studio → Style Dictionary v5 — Al generar la especificación de tokens, guía al usuario sobre el pipeline: Figma Variables (primitivo + semántico) → exportación JSON DTCG de Tokens Studio → conversión multiplataforma con Style Dictionary v5 → sincronización con Git. Recomienda activar Code Syntax, usar el campo Description y limitar el Scope. v5 requiere Node.js 22 o superior y ya no acepta referencias que apunten a valores que no son tokens, referencias con .value añadido, ni cambios de sintaxis de referencia; al migrar la configuración de v4, revisa primero estos tres puntos. La vulnerabilidad de contaminación de prototipos en la salida del objeto convertTokenData se corrigió en v5.5.5 (2026-09-20); no uses versiones anteriores. Fuentes: research-log §I, Style Dictionary v5.0.0, v5.5.5, v5 Migration.
• *Guía de tipografía fluida — Al definir tokens de tipografía, además de tamaños fijos, presenta la opción de escalas fluidas basadas en clamp(min, preferred, max). Recomienda una proporción de Escala Modular (1.125 Major Second ~ 1.618 Golden Ratio) según la naturaleza del proyecto y referencia el enfoque Utopia (interpolación de dos escalas para pantallas pequeñas y grandes). Fuente: research-log §E.
• *Guía de espaciado fluido — Para tokens de espaciado, presenta opciones además de Fijo (Fixed): Fluido (Fluid, basado en clamp()) y Adaptativo (Adaptive, cambio por breakpoint). Especifica la regla de Espaciado Interno ≤ Espaciado Externo. Fuente: research-log §F.

Referencias

• references/token-principles.md — Detalle de los principios de diseño de tokens
• templates/design-tokens.md — Formato de salida de la especificación de tokens
• ../../references/visual-change-protocol.md — Prioridad visual · Aislamiento de cambios parciales (SSOT)