Cómo escribir principios de diseño que un agente pueda aplicar

El problema con “sé claro”

Los principios de la mayoría de design systems se escribieron para inspirar a personas, no para instruir máquinas. “Sé claro”, “diseña con intención”, “menos es más”: un humano con contexto los interpreta; un agente no puede hacer nada con ellos, porque no contienen ningún criterio de decisión. Cuando un agente recibe “sé claro” como instrucción, el resultado es el promedio de lo que su entrenamiento considera claro, que rara vez coincide con tu sistema.

La prueba que separa un principio decorativo de uno ejecutable es binaria: dada una composición concreta, ¿puede un evaluador (humano o agente) decidir sin debate si la cumple o la viola? Si la respuesta depende de quién mira, el principio no es una regla: es un eslogan.

Anatomía de un principio ejecutable

Un principio ejecutable tiene cuatro partes:

Enunciado. La idea en una frase. Sigue siendo legible para humanos.
Criterios. Las condiciones verificables, con números exactos y ámbito de aplicación.
Contraejemplo. Al menos un caso concreto que viola el principio. Los contraejemplos acotan más que los ejemplos: le dicen al agente dónde está el borde.
Excepciones declaradas. Cuándo no aplica, escrito. Una excepción no declarada se convierte en jurisprudencia oral, y la jurisprudencia oral no llega al contexto del agente.

Antes y después con un caso real:

Aspecto	Versión aspiracional	Versión ejecutable
Enunciado	”La legibilidad es lo primero"	"La legibilidad es lo primero”
Criterios	(ninguno)	Cuerpo de texto: mínimo 16px. Contraste texto-fondo: mínimo 7:1 (WCAG AAA). Línea: máximo 75 caracteres.
Contraejemplo	(ninguno)	Caption de 12px sobre `--smoke-400`: contraste 3.8:1, viola el criterio 2.
Excepciones	(ninguna)	Texto legal y metadatos de tabla pueden bajar a 13px manteniendo 7:1.

El enunciado no cambia. Lo que cambia es que ahora existe una forma de perder la discusión: eso es lo que lo hace aplicable.

El procedimiento, principio a principio

1. Extrae la decisión escondida. Detrás de cada principio aspiracional hay decisiones reales que el equipo ya toma. Pregunta al equipo: “¿cuándo fue la última vez que rechazasteis algo citando este principio?”. La respuesta contiene el criterio implícito; escríbelo con números.

2. Cuantifica o elimina. Cada criterio necesita un umbral medible. Si tras dos intentos un principio no produce ningún criterio medible, no lo borres del manifiesto: márcalo como aspiracional y sácalo del conjunto que se inyecta a agentes. Es honesto y evita que el agente lo trate como ruido.

3. Escribe el contraejemplo con tokens reales. No “texto pequeño sobre fondo claro” sino el token concreto y el valor concreto de contraste. El contraejemplo con datos reales es lo que un agente puede comparar contra su propia salida.

4. Decide el formato de publicación. Tres niveles, acumulativos:

principles.md en el repositorio: texto plano estructurado, consumible por cualquier herramienta que lea el repo, como Claude Code (el flujo completo, aquí).
Metadata en tokens: los umbrales que dependen de un token concreto viajan en $extensions del token DTCG (wcagContrast, allowedSurfaces), de forma que la regla acompaña al dato.
Prompt en el MCP server: los principios se inyectan automáticamente cuando un cliente pide generar con el sistema. La implementación está documentada.

5. Cierra el circuito con verificación. Un principio ejecutable admite test. Los criterios de contraste y tamaño se comprueban con un linter de accesibilidad en CI; los de uso de tokens, con un linter de estilos. Cuando el principio tiene test, deja de depender de que alguien lo recuerde: lo recuerda el pipeline.

Cuántos principios y quién los mantiene

Los sistemas maduros operan con entre 5 y 10 principios ejecutables. Por encima de 10, los criterios empiezan a contradecirse y el agente (también el humano) necesita una regla de precedencia, que es otro documento que mantener. Cada principio tiene la misma mecánica de cambio que un token: propuesta por PR, revisión del equipo del sistema, versión nueva publicada. Esa mecánica es una pieza de la governance agéntica del sistema, y su estado se evalúa en el paso 4 de la auditoría AI-readiness.

Ver también

La reescritura de principios es el entregable de la semana 2 del bootcamp ejecutivo: cada participante sale con los suyos en formato ejecutable. El razonamiento de fondo, con los casos completos, está en el PDF del libro de Joan Arbó.