Un sitio web sin plantilla con Claude Code y Refero DESIGN.md

Materiales prácticos sobre cómo trabajar con proyectos y modelos: documentación de Ailoot.

¿Por qué los sitios web de Claude Code parecen plantillas de Tailwind?#

En el ejemplo descrito, en enero se estaba creando un pequeño proyecto paralelo: un marcador para llamadas de venta en frío. En un repositorio vacío, se pidió a Claude Code que creara la página de inicio. El resultado era genérico: un fondo oscuro slate-950, un color de acento purple-500, un encabezado en negrita con fuente sans serif y tres tarjetas debajo con sombras idénticas. El mismo diseño que la primera versión de ChatGPT, la primera versión de Lovable y la primera versión de v0. Tras cinco ediciones del prompt con las palabras «moderno», «premium» y «que no se parezca a los demás», nada cambió. La página seguía pareciendo sacada de un conjunto de plantillas de Tailwind UI Templates.

Es decir, Claude no es que «no sepa» crear algo bonito. Sabe lo que hace la mayoría y reproduce esa mayoría. Para obtener un resultado que no sea una media, el agente necesita restricciones específicas: qué colores usar, qué fuentes, qué espaciado y qué componentes considerar canónicos.

Aquí es donde entra en juego un sistema de diseño como contexto. No «hazlo bonito», sino «hazlo con este estilo concreto; aquí están sus parámetros».

Refero Styles salva esa distancia con un recurso listo para usar: un archivo DESIGN.md con parámetros de productos reales.

¿Qué es Refero Styles?#

La página de inicio de styles.refero.design lo dice claramente: «descubre más de 2.000 sistemas de diseño de sitios web de productos líderes, legibles por agentes de IA». El catálogo incluye marcas que establecen el estándar visual: Apple, Linear, Stripe, Notion, Vercel, ElevenLabs, Mercury, PostHog, xAI, Modal, Duolingo. No se extraen manualmente: el equipo de Refero ejecuta un script que analiza el CSS y el marcado reales de un sitio y empaqueta el resultado en Markdown estructurado. La biblioteca de styles.refero.design es gratuita.

La palabra clave es «estructurados». El archivo no contiene capturas de pantalla ni descripciones como «con un estilo minimalista». Es Markdown con colores hexadecimales concretos, tamaños de fuente exactos en pt, unidades de espaciado y reglas para los componentes. El agente de IA lee el archivo y trabaja con datos específicos, en lugar de intentar describir preferencias estéticas con palabras.

En su página ai-agents, el equipo de Refero enumera las herramientas compatibles como «Cursor, Claude Code, Codex, v0 y Lovable». En otras palabras, DESIGN.md funciona como un recurso universal: un archivo válido para los principales agentes de desarrollo de IA.

¿Qué contiene un DESIGN.md?#

El equipo de Refero describe la estructura del archivo en su página design-md-template:

Así que la estructura del archivo suele ser la siguiente:

Los creadores también destacan un principio que resuelve el 80 % de los problemas de diseño con IA:

Es decir, el código hexadecimal #5E6AD2 es más útil que «como Linear». El valor exacto font-size: 13px / line-height: 18px es más útil que «texto compacto». Los detalles concretos vencen a la interpretación.

DESIGN.md en el repositorio no es una imagen para el equipo. Es un componente del contexto permanente de tu proyecto: conocimiento estructurado que la IA lee con cada solicitud.

Cómo crear un sitio web al estilo de Linear en 4 pasos#

Estos cuatro pasos conforman la secuencia descrita para empezar un sitio web nuevo. No son «cuatro pasos en general», sino una secuencia concreta con una acción para cada paso.

1. Instalar Claude Code

   Instalador nativo de un solo comando: curl -fsSL https://claude.ai/install.sh | bash (el método recomendado en la documentación oficial). En macOS funciona brew install --cask claude-code; en Windows, winget install Anthropic.ClaudeCode. Si ya está instalado, comprueba la versión: claude --version (se necesita la versión 2.1.178+: esta introdujo los permisos Tool(param:value) y el bloqueo de comandos git peligrosos en modo automático). Inicia sesión en tu cuenta: claude abre el asistente. Claude Code está incluido en una suscripción Pro ($17/mes con facturación anual o $20/mes con facturación mensual).

2. Abrir Refero Styles y elegir una marca

   Ve a https://styles.refero.design y abre el catálogo. El principal criterio de selección es cuánto encaja con tu producto, no si «te gusta». ¿Estás creando un panel de control SaaS? Echa un vistazo a Linear, Vercel y Notion. ¿Estás creando un producto fintech? Mira Stripe, Mercury y Column. ¿Estás creando un producto para miembros? Mira Duolingo. Abre la ficha de una marca y haz clic en «Copy DESIGN.md».

3. Colocar DESIGN.md en el proyecto como contexto

   Crea un archivo docs/DESIGN.md en la raíz del proyecto y pega el contenido copiado. Después, abre CLAUDE.md y añade una línea: @docs/DESIGN.md. Es una directiva de importación: Claude Code carga el contenido en el contexto al iniciar una sesión. Para saber más sobre las importaciones en CLAUDE.md, consulta la guía sobre un archivo de instrucciones para Claude Code, Codex y Cursor.

4. Pedir una página concreta

   No digas «hazla bonita». Sé específico: «Con el DESIGN.md del contexto, crea una página de inicio para un producto SaaS de gestión de tareas. Estructura: hero con un encabezado y un subtítulo, dos botones CTA (principal y secundario), debajo un bloque con 3 funciones e iconos y, después, un bloque de testimonios. Usa exactamente los colores y la tipografía de DESIGN.md; no inventes los tuyos».

Después del cuarto paso, Claude crea la página. Según la experiencia descrita, una página de inicio tarda una media de 8–12 minutos y realmente se parece al estilo de la marca elegida. No es una copia píxel a píxel, pero sí tiene una estética reconocible: las mismas fuentes, la misma paleta, el mismo ritmo de espaciado y las mismas pequeñas decisiones de diseño en los botones.

Los creadores de Refero describen el mismo principio de tres pasos de forma un poco más breve en su página ai-agents/design-resources:

Esta secuencia de cuatro pasos sigue la misma lógica, con los pasos explícitos añadidos de instalar Claude Code e importar el archivo en CLAUDE.md.

¿Qué estilo deberías elegir para tu producto?#

Los creadores de Refero dan este consejo en el primer paso de su guía: elige una referencia no solo por el nombre de la marca, sino también por la densidad, el tono y el público.

¿Qué significa esto en la práctica? Los colores, tipografía, jerarquía y movimiento moderado derivados de Apple pueden funcionar en un dashboard SaaS, aunque el espaciado de una página concreta de marketing quizá no. Inspecciona la referencia específica en vez de elegir por marca. En un panel contable, define alturas de fila, espaciado y densidad compactos conservando números y controles legibles; no copies sin adaptar una presentación espaciosa.

Una guía sencilla para elegir según el tipo de producto:

Si todavía tienes dudas, elige Linear. Tiene una base muy versátil: una paleta neutra, tipografía legible (Inter / Söhne) y un espaciado discreto. Un sitio web basado en Linear tendrá un aspecto profesional para 9 de cada 10 tipos de producto.

¿Por qué incluir DESIGN.md en el contexto permanente de tu proyecto?#

En la práctica descrita, DESIGN.md se guarda junto a CLAUDE.md en cada proyecto gestionado con agentes de IA. No se considera un archivo «temporal para una tarea». Es un canon permanente en el que se apoyan todas las sesiones futuras. Dentro de un mes, puedes pedir a Claude que añada una página al proyecto: abrirá el mismo DESIGN.md y la creará con el mismo estilo. Dentro de seis meses, puedes entregar el proyecto a otro miembro del equipo: también podrá ejecutar Claude y obtener un resultado coherente, porque DESIGN.md está en el repositorio.

Aplicado al diseño, el principio funciona así: se toma una decisión una sola vez —la paleta, la tipografía y el ritmo de espaciado—. Después, todos los agentes de IA la dan por sentada.

Es decir, el diseño existe como código (Markdown es código), no como archivo de Figma que la IA no puede leer. Cuando el diseño está en un archivo del repositorio, Claude Code lo lee, Codex lo lee y cualquier herramienta futura podrá leerlo. Cuando el diseño está en Figma, vive en un plano separado y hay que traducirlo manualmente para cada sesión.

En los proyectos paralelos descritos, se utilizó esta estructura:

project/
├── CLAUDE.md            (imports @docs/DESIGN.md)
├── docs/
│   ├── DESIGN.md        (canon visual, copiado de Refero)
│   ├── ARCHITECTURE.md  (estructura del proyecto)
│   └── BRAND.md         (voz de marca, vocabulario)
└── ...

Estos tres archivos son una forma de organizar el contexto permanente del proyecto. DESIGN.md se ocupa de lo visual, ARCHITECTURE.md de la estructura y BRAND.md de la voz. Cualquier agente de IA con acceso al repositorio recibe los tres como contexto.

¿Qué son Refero MCP y refero_skill?#

Refero Styles es la capa base (DESIGN.md como archivo). La siguiente ola está formada por integraciones que hacen que el acceso a la biblioteca sea «nativo» para los agentes de IA.

Refero MCP (oficial). Es una API de servidor en https://api.refero.design/mcp a la que Claude Code se conecta con un token bearer. El agente obtiene acceso a más de 150.000 pantallas y más de 6.000 flujos de usuario de productos reales. Puedes instalarlo con un skill:

npx skills add https://github.com/referodesign/refero_skill --skill refero-design

Tras la instalación, Claude inicia una «investigación de diseño» al comienzo de cada sesión como primer paso obligatorio: examina qué opciones visuales convienen a la tarea y, si hace falta, propone tres direcciones vinculadas a la referencia seleccionada. A fecha de 23 de junio de 2026, el repositorio refero_skill tiene 67 commits y 135 estrellas. Un producto nuevo en desarrollo activo.

La práctica descrita utiliza un enfoque sencillo: abrir el sitio manualmente, copiar DESIGN.md y ponerlo en un archivo. MCP resulta útil cuando trabajar con sistemas de diseño se vuelve habitual; por ejemplo, si gestionas varios proyectos de clientes y cambias de canon visual cada día. Para saber más sobre cómo conectar servidores MCP a Claude Code, consulta la guía sobre NotebookLM y MCP.

¿Qué 4 errores arruinan el proceso?#

Estos cuatro errores aparecen en la experiencia descrita de trabajo con contexto de diseño. Cada uno parece inofensivo, pero cada uno devuelve el resultado a la plantilla estándar de Tailwind.

Error 1. El prompt «haz que parezca moderno». Es el patrón de error más común. La gente abre Claude Code y escribe: «hazme un sitio web SaaS, estilo moderno, aspecto premium». El resultado es un fondo oscuro con un acento morado. En los datos de entrenamiento, la palabra «moderno» se correlaciona con todas las páginas de destino de 2022–2024 construidas a partir de la misma plantilla. Sin los parámetros exactos de DESIGN.md, «moderno» significa «promedio».

Error 2. Pegar DESIGN.md en el chat como mensaje. A veces la gente copia DESIGN.md en la ventana de chat de Claude Code y dice: «aquí tienes el estilo, úsalo». Funciona una vez, hasta que termina la sesión. Abre una sesión nueva (o cambia a otra tarea, /clear) y el contexto se pierde. Si quieres que el estilo se conserve, el archivo debe estar en el repositorio e importado en CLAUDE.md. Para saber por qué CLAUDE.md es el punto de referencia del contexto permanente, consulta la guía sobre la memoria de Claude.

Error 3. Elegir un estilo porque «te gusta». Una referencia espaciosa de marketing de Apple puede ser una mala distribución para copiar sin cambios en un dashboard inmobiliario que necesita 30 anuncios visibles. Eso no excluye tipografía, paleta o jerarquía derivadas de Apple: adapta espaciado y densidad de filas y comprueba la información realmente visible en la pantalla objetivo. Elige la referencia concreta por densidad, tono y público, no solo por marca.

Error 4. No mencionar DESIGN.md en el propio prompt. DESIGN.md puede estar en el repositorio, importado mediante CLAUDE.md y visible para el agente. Pero si el prompt dice «crea un sitio web», Claude puede seguir el camino habitual sin hacer referencia explícita al archivo. Para cada prompt de diseño, resulta útil esta frase: «Usa exactamente los colores, las fuentes y el espaciado de docs/DESIGN.md. No inventes valores: tómalos del archivo». Así te aseguras de que el agente utilice DESIGN.md en vez de ignorarlo.

Los tokens exactos son códigos hexadecimales, tamaños de fuente en pt y unidades de espaciado en DESIGN.md. El lenguaje natural significa «moderno», «premium», «limpio» o «como Apple». Los tokens exactos funcionan; las palabras libres no.

¿Qué deberías hacer ahora?#

Ya tienes el flujo de trabajo básico: Claude Code + DESIGN.md de Refero + 4 pasos = un sitio web sin plantilla. Esto cubre el 70 % de las necesidades. El 30 % restante corresponde a casos en los que necesitas más precisión, rapidez o verificación.

Tres direcciones que puedes seguir después de dominar lo básico:

1. Frontend Design Skill. Es un skill oficial para Claude Code que añade comentarios visuales. El agente toma una captura de pantalla de la página montada con Puppeteer, la mira con sus «ojos» (un modelo de visión), la compara con DESIGN.md y propone correcciones por sí mismo. Es un ciclo automatizado de «prompt → código → captura de pantalla → crítica → prompt». Es útil cuando una página es compleja y no puedes acertar en una sola iteración.

2. Refero MCP en modo de producción. Cuando gestionas 3–5 proyectos en paralelo, añadir manualmente DESIGN.md a cada uno resulta tedioso. Refero MCP puede encontrar 3 estilos adecuados a partir de la descripción de un proyecto y permite elegir uno. Así se reduce el inicio de un nuevo proyecto de 30 minutos a 3.

3. Combinarlo con Context Engineering. DESIGN.md es uno de los recursos de contexto. Junto a él, normalmente encontrarás ARCHITECTURE.md (estructura del proyecto), BRAND.md (voz de marca) y business/audience.md (público objetivo). Todos se importan en CLAUDE.md. Al crear una página, Claude se basa en lo visual, el público y la estructura del producto. En esencia, esto es Context Engineering: trabajar de forma sistemática en lo que le proporcionas al agente antes de hacer una solicitud.

Materiales prácticos: documentación de Ailoot.

Materiales prácticos: documentación de Ailoot.

Más materiales y herramientas: Ailoot.