STACK DE SPECS · 3 DE 3

DESIGN.md

UI CONSISTENTE
SIN FIGMA.

Un markdown. El agente lo lee. La UI sale pixel-perfect en el primer intento. Sin design tokens en JSON, sin Storybook, sin export de Figma. Concepto introducido por Google Stitch en 2025.

¿QUÉ ES?

UN SISTEMA DE DISEÑO
QUE EL AGENTE LEE EN UN PASE.

DESIGN.md es la propuesta que Google introdujo con Stitch: un solo archivo markdown que captura todo el sistema de diseño de un producto. Colores, tipografías, componentes, espaciado, jerarquía. Sin tooling propietario, sin export pipeline, sin parser custom.

La razón por la que funciona es la misma por la que funciona AGENTS.md: markdown es el formato que mejor leen los LLMs. No hay que enseñarles a parsear nada. Lo abren, lo entienden, lo respetan.

VoltAgent mantiene el repo awesome-design-md con más de 70 DESIGN.md extraídos de marcas reales (Linear, Stripe, Apple, Vercel, Tesla, Notion). Copias el de la marca que te inspira, le pides al agente "hazme una landing en este estilo" y obtienes algo coherente desde el primer prompt.

ESTRUCTURA

LAS 9 SECCIONES STITCH.

Formato canónico. A diferencia de AGENTS.md y SOUL.md, este sí tiene un schema más establecido — viene de Google.

Visual Theme & Atmosphere

Mood, densidad, filosofía. ¿Es minimal? ¿Brutalista? ¿Editorial? Lo primero que el agente "siente".

Color Palette & Roles

Cada color con nombre semántico (no "azul", sí "primary"), hex y rol funcional. La diferencia entre tokens utilizables y un mood board.

Typography Rules

Familias, jerarquía completa con tamaño, peso, line-height, letter-spacing. De display-xl hasta caption.

Component Stylings

Botones, cards, inputs, navegación con todos sus estados (default, hover, focus, pressed, disabled).

Layout Principles

Escala de spacing, grid, filosofía de whitespace. ¿Denso o aireado? ¿Asimétrico o centrado?

Depth & Elevation

Sistema de sombras y jerarquía de superficies. Surface-1, surface-2, surface-3, hairlines.

Do's and Don'ts

Guardarrieles concretos. "No uses gradientes en CTAs", "siempre alinea labels a la izquierda". Anti-patrones explícitos.

Responsive Behavior

Breakpoints, touch targets mínimos, estrategia de colapso. Cómo se transforma el componente al achicar.

Agent Prompt Guide

Cheatsheet final: paleta resumida, prompts listos para copiar. Le ahorra al agente tener que sintetizar todo el archivo cada vez.

ARCHIVO REAL DE ESTE SITIO

EJEMPLO

EL DESIGN.md DE GNB LABS

Este es un extracto del archivo /DESIGN.md que vive en la raíz de gabrielneuman.com. Los agentes de Claude Code lo cargan al arranque y por eso esta misma página es consistente con el resto del sitio.

DESIGN.md · gabrielneuman.com

---
version: 1.0
name: gabrielneuman.com
brand: GNB Labs / Gabriel Neuman
description: "Editorial-consultor canvas. Casi todo
  blanco, tipografía brutal (uppercase, font-black,
  tracking apretado), un solo azul-violeta como
  acento (#2f4ac8) y secciones gray-900 que rompen
  el ritmo en momentos de autoridad. Mezcla la
  disciplina monocroma de Vercel, los token roles
  de Linear y la gravedad editorial de un boutique
  de consultoría."
inspiredBy:
  - vercel.com (shadow-as-border, neutralidad)
  - linear.app (token roles, hairlines)
  - editorial consulting (jerarquía eyebrow→headline→lead)

colors:
  primary: "#2f4ac8"        # brand-600
  primary-hover: "#2340b5"  # brand-700
  primary-tint: "#c5d5f8"   # brand-200
  primary-wash: "#f0f4ff"   # brand-50
  canvas: "#ffffff"
  canvas-muted: "#f9fafb"   # gray-50
  surface-dark: "#111827"   # gray-900 — heroes oscuros
  ink: "#111827"
  ink-subtle: "#4b5563"
  hairline: "#e5e7eb"

typography:
  display-xxl:
    fontSize: 80px         # text-7xl
    fontWeight: 900        # font-black
    lineHeight: 0.85
    letterSpacing: -0.04em # tracking-tighter
    transform: uppercase
  eyebrow:
    fontSize: 14px
    fontWeight: 700
    letterSpacing: 0.2em
    transform: uppercase
    color: primary
  italic-flourish:
    fontFamily: Georgia
    fontStyle: italic
    transform: lowercase
    notes: "Único caso lowercase del sistema."

components:
  card:
    backgroundColor: "{colors.canvas}"
    border: "1px solid {colors.hairline}"
    rounded: 16px            # rounded-2xl
    padding: 24px            # p-6
    hover:
      borderColor: "{colors.primary-tint}"
      shadow: "0 10px 25px -10px rgba(0,0,0,0.12)"

  button-primary:
    backgroundColor: "{colors.primary}"
    textColor: "#ffffff"
    rounded: 12px            # rounded-xl
    padding: "16px 40px"
    transform: uppercase
    letterSpacing: 0.15em

dos:
  - Headlines: uppercase + font-black + tracking-tighter.
  - Una licencia cromática por headline: <span text-brand-600>
    en la última línea.
  - Eyebrow ANTES de cada heading. Sin eyebrow flota.
  - Secciones gray-900 son acento, no fondo (max 2/página).

donts:
  - NO gradientes en superficies grandes.
  - NO drop-shadows generosas.
  - NO emojis decorativos en headlines.
  - NO photoshop, NO stock, NO ilustración.
    La página es typeset puro.

Versión condensada. El archivo completo (~330 líneas) está en github.com/gneuman/websitegnb/blob/main/DESIGN.md

MEJORES PRÁCTICAS

QUÉ MARCA LA DIFERENCIA.

✅

Sí hacer

→Nombrar tokens por rol, no por color. primary sobrevive un rebrand; azul no.
→Incluir todos los estados de cada componente. Default, hover, focus, pressed, disabled. El agente no los inventa, los reproduce.
→Sección Don'ts explícita. "No uses gradientes" pesa más que 20 ejemplos positivos.
→Cerrar con un Agent Prompt Guide. Resumen ejecutable que el agente puede pegar al inicio de cada generación.
→Dos previews HTML (light/dark) en el repo. Validación visual rápida sin levantar el sitio.

⛔

No hacer

×Convertirlo en un design system completo de 3000 líneas. El agente se pierde. Apunta a 200-400 líneas máximo.
×Mezclar lo aspiracional con lo real. Si en producción no usas esa fuente, no la pongas.
×Solo paleta y tipos. Sin componentes el agente sigue inventando bordes y radios al azar.
×Versiones contradictorias. Un solo DESIGN.md por marca. Si tienes light + dark, va en el mismo archivo con tokens específicos.

CÓMO LO USO

EN GNB LABS,
ESTO ES LO QUE HAGO.

Tokens en Tailwind config + DESIGN.md espejo

Los tokens del sitio viven en tailwind.config.ts (la fuente de verdad para producción) y un DESIGN.md espejo que los agentes leen. Mismo dato, dos formatos: uno para el build, uno para los modelos.

Generar landings nuevas en minutos

Cuando lanzo una oferta nueva (workshop, asesoría, lead magnet) le paso al agente el DESIGN.md de GNB + un brief de 5 líneas. La landing sale en el estilo correcto desde el primer commit. Ahorro 2-3 horas de pulir colores y espaciados.

Don'ts agresivos para no caer en plantilla

Mi DESIGN.md tiene una lista larga de qué no hacer: nada de gradientes vibrantes, nada de iconos line genéricos, nada de hero con foto stock. Sin esos límites el agente cae en el look "SaaS de 2022" por default.

Multi-marca: GNB + Teknobuilding

Cada marca tiene su propio DESIGN.md. Cuando trabajo en Teknobuilding cargo ese archivo y la salida cambia de identidad sin tocar una línea de prompt. La marca vive en el archivo, no en mi memoria.

Recursos

El stack completo

1 de 3

AGENTS.md →

Cómo construir.

2 de 3

SOUL.md →

Cómo hablar.

EL TRÍO COMPLETO

CONSTRUIR. HABLAR. VERSE.
tres archivos, cero tooling.

Si tu agente no tiene los tres, le falta una pata. La buena noticia: son markdowns. Empieza por uno y agrega los demás cuando duela.

Hablemos de tu stack →

UI CONSISTENTESIN FIGMA.