DESIGN.md: el sistema de diseño que la IA sí puede entender
Qué es DESIGN.md, cómo exporta reglas de diseño y cómo ayuda a agentes y equipos a validar accesibilidad WCAG con más contexto.
El anuncio de Google sobre DESIGN.md apunta a algo más ambicioso que “otro formato de tokens”. La propuesta consiste en reunir, en un solo archivo, dos cosas que hoy suelen vivir separadas: por un lado, valores estructurados que una herramienta puede procesar; por otro, la intención visual y de producto que normalmente queda dispersa entre documentación, notas de equipo y decisiones implícitas. Esa combinación es la razón por la que DESIGN.md resulta especialmente interesante para flujos con agentes.
A partir del anuncio oficial de Stitch sobre DESIGN.md y del repositorio abierto en GitHub (README.md, docs/spec.md, varios archivos de packages/cli/* y los ejemplos de examples/*) se ve con bastante claridad cuál es la apuesta: convertir el sistema de diseño en un artefacto portable, legible por humanos y útil para agentes, con capacidad para exportarse a otros formatos y para ser validado con comprobaciones automáticas de accesibilidad y consistencia técnica.
La idea es potente, pero ahora mismo (abril de 2026), DESIGN.md debe entenderse como una especificación abierta y aún en evolución. El repositorio lo presenta como alpha, y hay detalles prácticos que siguen sin quedar cerrados en la documentación pública, como una sintaxis de import de CLI equivalente a export. Dicho de otra forma: hoy ya sirve para pilotar, documentar y automatizar mejor; todavía no conviene tratarlo como un estándar definitivo e inmutable.
Qué es DESIGN.md y qué problema intenta resolver
DESIGN.md no es “un archivo Markdown con YAML”, sino un formato pensado para describir una identidad visual de forma que tanto las personas como los agentes puedan entenderla y reutilizarla.
La estructura está diseñada precisamente para eso. En el front matter se guardan tokens y propiedades de sistema —colores, tipografía, espaciado, radios, componentes— y en el cuerpo Markdown se explican el tono visual, las reglas de uso, las prioridades de jerarquía y los matices que una tabla de valores por sí sola no puede capturar. Es una decisión muy relevante, porque desplaza el centro del sistema de diseño desde la “lista de variables” hacia una fuente de verdad con contexto.
Visto así, DESIGN.md intenta resolver tres problemas bastante comunes.
- El primero es la fragmentación. Muchas organizaciones tienen design tokens en un sitio, variables en otro, guidelines en una wiki, reglas de accesibilidad en documentación separada y decisiones reales repartidas entre diseñadores y desarrolladores. DESIGN.md intenta reunir esas capas en un artefacto único.
- El segundo es la pérdida de intención. Un token te dice qué color usar; no siempre te dice por qué existe ese color, cuál es su papel jerárquico o en qué casos no conviene usarlo. Con DESIGN.md, la IA no tiene que “adivinar” tanto la intención del sistema visual porque puede leerla directamente en el archivo.
- El tercero es la interoperabilidad. La especificiación (
spec.md) deja claro que el formato está pensado para poder convertirse desde y hacia otros formatos ya existentes, especialmente en entornos de design tokens, variables y theming. No pretende sustituir de golpe a todo lo demás; pretende funcionar como una capa semántica y portable entre herramientas.
Un ejemplo mínimo resume bien la filosofía:
mdCopiar---
name: Heritage
colors:
primary: "#1A1C1E"
secondary: "#6C7278"
tertiary: "#B8422E"
neutral: "#F7F5F2"
typography:
h1:
fontFamily: Public Sans
fontSize: 3rem
body-md:
fontFamily: Public Sans
fontSize: 1rem
rounded:
sm: 4px
md: 8px
spacing:
sm: 8px
md: 16px
---
## Overview
Architectural Minimalism meets Journalistic Gravitas.
La parte superior fija los valores. La parte inferior empieza a contar la intención. Y ahí está la diferencia de fondo: un agente puede respetar el color primary, pero también entender que la experiencia busca un tono “sobrio”, “editorial” o “arquitectónico”.
Qué cambia con el anuncio y qué capacidades añade
La novedad del anuncio no es solo abrir un repositorio. Lo realmente nuevo es que Stitch presenta DESIGN.md como un formato abierto y reutilizable entre herramientas, no como una función encerrada en un único producto. Ese matiz cambia mucho su alcance.
Las capacidades que se ponen sobre la mesa son estas:
- Exportar reglas de diseño desde un proyecto para reutilizarlas en otros contextos.
- Importar reglas ya definidas para no empezar siempre desde cero.
- Dar contexto semántico a agentes, no solo valores de estilo.
- Validar decisiones frente a criterios de accesibilidad, especialmente WCAG.
- Favorecer la portabilidad entre diseño, código y herramientas intermedias.
Lo interesante es que el repositorio aterriza esa promesa en piezas muy concretas. Una CLI con comandos como lint, diff, export y spec. Eso significa que DESIGN.md no se queda en una idea conceptual: ya existe una capa práctica para validar archivos, comparar evoluciones del sistema y exportar salidas a otros formatos.
Hay además un cambio cultural de fondo. Hasta ahora, buena parte del “hilo conductor” de un sistema de diseño dependía de documentos largos, reuniones de handoff o conocimiento tácito del equipo. DESIGN.md propone que ese hilo conductor sea un archivo que viaje con el proyecto y que tanto un revisor humano como un agente puedan leer.
En términos prácticos, las capacidades nuevas no solo afectan al diseño. También afectan a:
- el onboarding de equipos,
- la auditoría de cambios,
- la automatización de validaciones,
- y la consistencia entre múltiples productos o marcas.
La documentación pública no fija una versión cerrada y estable del estándar en el artículo del blog, y el repositorio se presenta como alpha, así que cualquier lectura responsable debería mantener ese matiz: la dirección está clara; algunos detalles de producto y ecosistema siguen evolucionando.
Cómo funciona el flujo de exportación, validación e importación
La mejor forma de entender DESIGN.md es verlo como un puente entre cuatro momentos: autoría, exportación, validación por agentes e importación o consumo en otro entorno.
Autoría
Se parte de un archivo DESIGN.md con front matter y secciones descriptivas. La spec propone encabezados y una organización consistente para que los consumidores puedan reconocer partes como visión general, colores, tipografía, layout, elevación, formas, componentes y reglas de uso.
Exportación
Existe la capacidad de export hacia, al menos, DTCG y Tailwind. Esta parte es importante: el archivo fuente puede transformarse en una salida más propia de tokens o de theming de front-end sin perder del todo su estructura de origen.
En los ejemplos del repositorio se ve bien cómo funciona esa idea. El caso de examples/atmospheric-glass/DESIGN.md y su correspondiente design_tokens.json es especialmente ilustrativo.
Este fragmento JSON, adaptado de examples/atmospheric-glass/design_tokens.json, muestra cómo una definición de componente puede acabar serializada en un formato cercano a DTCG:
jsonCopiar{
"components": {
"glass-card-standard": {
"backgroundColor": {
"$type": "color",
"$value": {
"colorSpace": "srgb",
"components": [1.0, 1.0, 1.0],
"alpha": 0.1
}
},
"textColor": "{colors.primary}",
"rounded": "{rounded.lg}",
"padding": "{spacing.glass-padding}"
}
}
}
Aquí se ve bien la promesa de portabilidad: un sistema expresado primero como intención + tokens puede traducirse a una salida más estructurada para otras herramientas.
Validación
La capa de validación es uno de los puntos más interesantes del repositorio. La CLI incorpora lint, y dentro del código aparecen reglas específicas en archivos como packages/cli/src/linter/linter/rules/contrast-ratio.ts. También hay manejadores de salida en packages/cli/src/linter/dtcg/handler.ts y packages/cli/src/linter/tailwind/handler.ts.
Además, diff permite comparar dos archivos y detectar qué ha cambiado. Eso es muy útil para gobernanza: el sistema de diseño deja de ser algo “difuso” y pasa a ser un artefacto versionable.
Importación
Aquí conviene ser precisos. El artículo del blog habla de export/import de reglas. Sin embargo, en las fuentes técnicas del repositorio no aparece documentada una sintaxis pública de comando import equivalente a export. Ese detalle, por tanto, debe considerarse no especificado en la documentación abierta revisada.
Eso no invalida la promesa del flujo; simplemente significa que, a día de hoy, la parte de importación parece más ligada a Stitch como producto y al diseño del formato como artefacto interoperable que a un comando público claramente descrito en el CLI del repositorio.
Cómo los agentes interpretan intención y comprueban accesibilidad
Aquí es donde DESIGN.md realmente se vuelve distinto.
Un sistema basado solo en tokens puede responder a preguntas como “¿cuál es el color primario?” o “¿qué radio usa este botón?”. Pero un agente que además lee secciones descriptivas puede responder preguntas más interesantes: “¿cuándo conviene usar ese color?”, “¿qué tono emocional busca la interfaz?”, “¿qué jerarquía debe priorizarse?” o “¿qué decisión encaja mejor con el sistema cuando hay ambigüedad?”.
La lógica del repositorio apunta justo en esa dirección. El archivo packages/cli/src/linter/lint.ts muestra que el linter no trabaja solo con valores resueltos; también opera con la estructura del documento y sus secciones. Eso abre la puerta a flujos donde un agente consuma tanto datos de sistema como prosa de intención.
Una forma sencilla de explicarlo es esta:
- Los tokens responden al “qué”.
- El Markdown responde al “por qué” y al “cómo”.
- El linter ayuda a comprobar si lo que se declara es consistente.
- El agente puede tomar decisiones mejores porque no parte de un lienzo ciego.
A nivel de accesibilidad, el caso más claro hoy es el contraste. La regla de contrast-ratio.ts encaja con criterios de la guía rápida de W3C para WCAG 2.2 y también aplicaría a WCAG 2.1, especialmente en torno a SC 1.4.3 Contrast (Minimum). Eso significa que un archivo de diseño ya no solo describe una interfaz: también puede empezar a comprobar, de forma automatizada, si algunas decisiones visuales se acercan o no a requisitos mínimos.
Aun así, conviene no sobredimensionar lo que hoy hace el repositorio. La validación integrada no equivale a una “conformidad WCAG completa”. Por las fuentes revisadas, su alcance visible se centra sobre todo en el contraste texto/fondo y en la consistencia estructural del archivo. Criterios como 1.4.11 Non-text Contrast, 2.4.11 Focus Not Obscured o 2.5.8 Target Size (Minimum) no aparecen documentados como checks integrados equivalentes, aunque son muy razonables como extensiones futuras o internas.
Ahí es donde encajan dos referencias clave:
- Las ACT Rules, que ayudan a formalizar pruebas repetibles de accesibilidad. Son muy útiles para automatización, aunque no sustituyen por sí solas la evaluación completa.
- WCAG2ICT, especialmente valioso cuando el sistema de diseño no acaba solo en web, sino también en software no web o documentación.
Un patrón práctico para agentes podría ser este pseudocódigo, inspirado en la estructura del linter descrita en lint.ts y complementado con una comprobación interna para tamaño táctil mínimo. No pretende reproducir una API pública exacta al detalle; ilustra el tipo de flujo que habilita DESIGN.md:
jsCopiar// Esquema ilustrativo basado en packages/cli/src/linter/lint.ts
const report = lint(markdownString);
// Leer intención desde el documento
const overview = report.documentSections?.find(
section => /overview|brand|style/i.test(section.heading)
)?.content ?? "";
// Añadir una validación interna de accesibilidad
const extraFindings = [];
for (const [name, component] of report.designSystem.components ?? []) {
const width = component.properties?.get?.("width");
const height = component.properties?.get?.("height");
if (width?.unit === "px" && height?.unit === "px") {
if (width.value < 24 || height.value < 24) {
extraFindings.push({
path: `components.${name}`,
severity: "warning",
message: "Objetivo interactivo por debajo de 24x24 CSS px"
});
}
}
}
return {
intent: overview,
findings: [...(report.findings ?? []), ...extraFindings]
};
Ese ejemplo muestra bien la tesis de fondo: si el sistema de diseño vive en un archivo con semántica, un agente puede inferir intención y aplicar reglas sin depender solo de capturas o señales débiles.
También hay una observación técnica interesante en los ejemplos del repositorio. En examples/atmospheric-glass/DESIGN.md aparecen componentes con valores rgba(...), mientras que ciertas partes del modelo y de validación visibles en packages/cli/* parecen estar más claramente orientadas a colores resueltos y contrastes comparables de forma directa. Eso sugiere que, en casos de transparencias o superficies complejas, la validación automática puede necesitar reglas adicionales o una interpretación más rica para no quedarse corta.
Dónde encaja frente a DTCG, Figma, Tokens Studio y Tailwind
Para evaluar DESIGN.md con criterio conviene compararlo no con una caricatura, sino con herramientas y formatos que ya resuelven problemas reales.
En el ecosistema actual, el estándar más cercano en términos de intercambio estructurado de tokens es la especificación del Design Tokens Community Group. Por su parte, el equivalente oficial en Figma hoy no son “tokens” como producto independiente, sino variables, colecciones y modos. A eso se suman herramientas como Tokens Studio y la configuración de tema de Tailwind CSS, que en muchos equipos funciona como la traducción práctica del sistema al front-end.
La comparación más útil sería esta:
| formato | tipo de archivo | validación accesibilidad | soporte de herramientas | portabillidad |
|---|---|---|---|---|
| DESIGN.md | Markdown + front matter YAML | Sí, con linter y reglas técnicas visibles en packages/cli/*; útil para contraste y consistencia, no para cubrir todo WCAG | Alta dentro del repositorio oficial: lint, diff, export, spec y API de linter | Alta para flujos con agentes y handoff; aún en evolución |
| DTCG Design Tokens | JSON | No intrínseca; necesita validadores externos o reglas propias | Muy alta en ecosistema de design tokens | Muy alta para intercambio estructurado |
| Figma Variables | Modelo nativo de variables, colecciones y modos | No equivale a una validación WCAG integrada de sistema | Muy alta dentro del entorno de diseño | Media-alta, especialmente dentro del ecosistema Figma |
| Tokens Studio JSON | JSON gestionado por plugin y sincronización | Depende del pipeline; no es un motor WCAG generalista por sí mismo | Alta en equipos que ya trabajan con Tokens Studio | Alta, especialmente cuando se alinea con DTCG |
| Tailwind theme | Configuración JS/TS/CSS de tema | No intrínseca; se apoya en procesos y pruebas externas | Muy alta en front-end web | Media-alta, orientada a implementación |
| JSON Schema | Esquemas JSON | Valida estructura, no intención visual ni accesibilidad como tal | Muy alta en validación técnica | Alta como capa complementaria |
La conclusión importante aquí es que DESIGN.md no sustituye exactamente a DTCG, Figma Variables o Tailwind. Más bien los complementa.
- Frente a DTCG, aporta prosa e intención.
- Frente a Figma Variables, aporta un formato más textual y agent-friendly.
- Frente a Tokens Studio, aporta una capa menos dependiente del plugin y más centrada en semántica.
- Frente a Tailwind, aporta contexto y portabilidad más allá del front-end final.
- Frente a JSON Schema, aporta algo que un esquema no puede expresar bien: el criterio de diseño.
Ese es probablemente su valor real: no competir por ser el único formato, sino convertirse en la capa donde el sistema visual gana sentido para humanos y agentes.
Casos de uso, límites y criterios de adopción
Casos de uso y beneficios
El caso más evidente es el de equipos que ya trabajan con sistema de diseño + IA + desarrollo. En ese contexto, DESIGN.md puede funcionar como la pieza que conecta el lenguaje del diseño con el del código y con el de los agentes.
También tiene mucho sentido en escenarios de multi-marca o multi-producto. Cuando una organización comparte principios pero necesita adaptar tonos, componentes o temas, un archivo que combina valores y reglas narrativas resulta muy útil para que la consistencia no dependa de memoria tribal.
Otro uso especialmente valioso es el de gobernanza y revisión continua. Con diff, lint y exportación a otros formatos, el sistema de diseño deja de ser un PDF bonito o una librería que se da por supuesta. Pasa a ser un artefacto que se puede revisar, versionar, comparar y automatizar.
Y hay una ventaja menos visible, pero importante: la mejora del prompting implícito. Un agente que recibe un DESIGN.md bien escrito necesita menos instrucciones externas para producir propuestas visuales y de implementación que respeten el sistema.
Limitaciones y preguntas abiertas
La primera limitación es la madurez. El repositorio se presenta como alpha, y eso obliga a adoptar con prudencia. Es una base sólida para explorar, pero no conviene venderla internamente como si ya fuese un estándar cerrado.
La segunda limitación es la asimetría documental del flujo. La exportación sí aparece en la documentación pública revisada; la importación, en cambio, se menciona en el producto y en el discurso general, pero su implementación exacta en CLI o sintaxis pública no queda especificada en las fuentes técnicas citadas.
La tercera es la profundidad de la validación de accesibilidad. El hecho de que DESIGN.md pueda comprobar ciertas reglas no significa que sustituya a una auditoría WCAG ni a pruebas con usuarios. El contexto visual real, los estados interactivos, la navegación y los componentes complejos siguen requiriendo una estrategia más amplia.
La cuarta es más conceptual. Cuando un archivo incluye intención narrativa, también introduce un margen de interpretación. Eso es una ventaja frente a tokens desnudos, pero implica que la calidad del resultado dependerá de cómo escriba el equipo, de cómo consuman el archivo los agentes y de qué reglas adicionales se definan.
Criterios sensatos de adopción
La forma más razonable de adoptar DESIGN.md hoy no es sustituir de golpe todo lo demás. Es usarlo como capa maestra.
Un camino realista sería:
- definir un
DESIGN.mdcanónico por producto o marca; - convertirlo en referencia editorial y técnica;
- integrarlo con validaciones en CI;
- exportarlo a DTCG o Tailwind cuando haga falta;
- conectarlo con variables de Figma o con Tokens Studio en los puntos donde eso ya tenga sentido para el equipo;
- ampliar las comprobaciones WCAG con reglas propias, especialmente en contraste no textual, tamaño de objetivo y foco.
Ese enfoque aprovecha el valor del formato sin obligar a una migración brusca.
Siguientes pasos
Como pasos recomendados, la propuesta sería empezar por un piloto pequeño: un solo producto, un solo DESIGN.md, validación básica de contraste, una exportación de prueba a DTCG o Tailwind y una revisión editorial de las secciones narrativas.
Si esa primera versión funciona, el siguiente salto natural es convertir el archivo en parte real del flujo de diseño, revisión y entrega, no en documentación “extra”. Ahí es donde la propuesta de DESIGN.md gana de verdad.
Este post está basado fundamentalmente en las siguientes fuentes: anuncio oficial de Stitch sobre DESIGN.md, el README.md del repositorio, la draft spec en docs/spec.md, la lógica visible en packages/cli/src/linter/lint.ts, la regla de contraste en packages/cli/src/linter/linter/rules/contrast-ratio.ts, los manejadores de exportación en packages/cli/src/linter/dtcg/handler.ts y packages/cli/src/linter/tailwind/handler.ts, además de los ejemplos en examples/atmospheric-glass/DESIGN.md y examples/atmospheric-glass/design_tokens.json.
Para la parte de accesibilidad y formatos relacionados, merece la pena tener a mano la WCAG 2.2 Quick Reference, la WCAG 2.1 Quick Reference, las ACT Rules, WCAG2ICT, la especificación DTCG 2025.10, la documentación oficial de Figma Variables, la de Tokens Studio y la guía de Tailwind Theme. Si tu equipo necesita validación estrictamente estructural sobre salidas JSON, JSON Schema 2020-12 encaja muy bien como complemento.
