Guía para principiantes de Open Design: la forma correcta de empezar con la versión open source de Claude Design

Presentación del proyecto

Open Design es una alternativa open source a Claude Design, desarrollada y mantenida por nexu-io/open-design.

Su idea central es directa: no volver a reinventar la rueda. Los agentes de codificación que ya tienes en tu ordenador (Claude Code, Codex, Cursor Agent, etc.; un total de 16 CLI) se convierten directamente en el motor de diseño. Combinados con 31 habilidades de diseño ensamblables y 72 sistemas de diseño de nivel marca, todo el flujo se completa localmente.

Características clave, de un vistazo:

---

Perfil de usuarios objetivo

• Desarrolladores frontend/full-stack: quieren usar IA para ayudar a generar diseños, pero no desean aprender operaciones complejas de Figma
• Desarrolladores individuales: necesitan producir rápidamente landing pages, prototipos para móvil y demostraciones de producto
• Equipos de diseño: buscan una solución de automatización de diseño priorizando lo local y sin depender del cloud
• Aficionados a herramientas de IA: desean explorar el potencial de agentes de codificación existentes en el ámbito del diseño

---

Dependencias y entorno principales

Node.js ~24
pnpm 10.33.x (gestionado mediante Corepack)
Sistema operativo: macOS / Windows / Linux

Open Design escanea automáticamente los agentes de codificación ya instalados en PATH. Si tu máquina no tiene ninguna CLI, te guiará para configurar el modo BYOK (requiere API Key).

---

Estructura completa del proyecto

open-design/
├── apps/
│   ├── daemon/                 # Servicio local (Express + SQLite)
│   │   └── src/
│   │       ├── agents.ts       # Detección de agentes de codificación y adaptadores
│   │       ├── skills.ts       # Cargador de habilidades
│   │       └── server.ts       # Enrutado de la API
│   └── web/                    # Frontend Next.js 16
│       └── src/
│           ├── prompts/        # Plantillas de prompts
│           ├── artifacts/      # Análisis de artefactos
│           └── components/     # Componentes de UI
├── skills/                     # 31 habilidades de diseño
│   ├── web-prototype/          # Prototipo web
│   ├── mobile-app/             # App móvil
│   ├── dashboard/              # Panel
│   ├── guizang-ppt/            # Presentación
│   └── ...
├── design-systems/             # 72 sistemas de diseño
│   ├── linear-app/
│   ├── vercel/
│   ├── anthropic/
│   └── ...
├── assets/frames/              # Marcos de dispositivos (iPhone, Pixel, iPad, MacBook)
└── .od/                        # Datos de ejecución (SQLite, archivos del proyecto)

---

Pasos paso a paso

1) Clona el repositorio e instala dependencias

git clone https://github.com/nexu-io/open-design.git
cd open-design
corepack enable
pnpm install

corepack enable leerá automáticamente la versión de pnpm bloqueada en el package.json (10.33.x) para asegurar la consistencia del entorno en el equipo.

2) Inicia el servidor de desarrollo local

pnpm tools-dev run web

Si el arranque tiene éxito, se mostrarán dos URLs:

✅ Daemon running at http://localhost:17456
✅ Web running at http://localhost:17573

Abre la URL de Web en tu navegador para empezar a usarlo.

3) Elige el agente de codificación

Al abrir por primera vez la interfaz web, Open Design detectará automáticamente los agentes de codificación en tu PATH.

Admite 16 CLI compatibles:

El selector de modelos en la esquina superior derecha mostrará los agentes detectados. Si no hay ninguna CLI, haz clic en seleccionar el modo BYOK y ejecuta mediante tus API Key a través de las interfaces de OpenAI/Anthropic/Azure/Gemini.

4) Elige habilidades de diseño

En la página de entrada se listan 31 habilidades, agrupadas por escenarios:

• Design: web-prototype (por defecto), mobile-app, mobile-onboarding, gamified-app, wireframe-sketch, critique, tweaks
• Marketing: saas-landing, pricing-page, blog-post, email-marketing, social-carousel, magazine-poster, motion-frames, sprite-animation
• Operation/Engineering/Product: dashboard, docs-page, pm-spec, team-okrs, meeting-notes, kanban-board, eng-runbook, finance-report, invoice, hr-onboarding
• Deck (presentación): guizang-ppt (por defecto), simple-deck, replit-deck, weekly-update

Según tus necesidades, haz clic en la habilidad correspondiente. Por ejemplo, elige mobile-app para generar un prototipo móvil.

5) Elige el sistema de diseño

Después de seleccionar una habilidad, se mostrará el panel del sistema de diseño. Por defecto se ofrecen dos sistemas iniciales: default (Neutral Modern) y warm-editorial (Warm Editorial).

La librería completa incluye 72 sistemas de diseño de marca:

• AI & LLM: claude, cohere, mistral-ai, ollama, x-ai…
• Herramientas de desarrollo: cursor, vercel, linear-app, supabase, posthog, sentry…
• Productos: notion, figma, airtable, intercom, raycast…
• Comercio electrónico: shopify, airbnb, uber, nike, starbucks…
• Automoción: tesla, bmw, ferrari, lamborghini…
• Otros: apple, ibm, nvidia, spotify…

También puedes subir tu propio archivo DESIGN.md para definir 9 dimensiones de especificaciones de diseño, como colores de marca, tipografías y espaciados.

6) Envía instrucciones de diseño

En el cuadro de entrada escribe tus requisitos de diseño, por ejemplo:

make me a mobile onboarding flow for a fitness app with dark theme

Después de completar el formulario, envíalo. El agente hará:

1. Generar un plan de TodoWrite y actualizarlo en streaming en tiempo real
2. Leer plantillas de habilidades y el sistema de diseño
3. Ejecutar auto-chequeos en 5 dimensiones (filosofía, jerarquía, ejecución, especificidad y contención)
4. Entregar código de <artifact>
5. Renderizar una vista previa en un iframe sandbox

7) Vista previa y exportación

Tras renderizar el diseño, puedes:

• Editar en tiempo real: modificar directamente el HTML/CSS en el área de archivos a la derecha
• Descargar: exportar a HTML (recursos embebidos), PDF, PPTX, ZIP o Markdown
• Guardar en disco: hacer clic en «Save to disk»; los artefactos se guardan en .od/artifacts/
• Continuar la conversación: dile al agente «cambia los botones a esquinas redondeadas» o «cambia el esquema de colores»; trabajará sobre el borrador actual para seguir modificando

Otros comandos de uso común:

# Ver estado de ejecución
pnpm tools-dev status

# Ver logs
pnpm tools-dev logs

# Detener todos los servicios
pnpm tools-dev stop

# Reiniciar (escenario de cambio de puertos)
pnpm tools-dev restart --daemon-port 17456 --web-port 17573

# Diagnosticar problemas
pnpm tools-dev check

---

Modificar proyectos existentes

Mucha gente, al recibir Open Design por primera vez, piensa: «¿No es esto una herramienta para generar páginas nuevas?». En realidad, se puede usar perfectamente para modificar proyectos existentes, y no necesitas que tu proyecto tenga nada de DESIGN.md.

La lógica principal es muy sencilla: el agente tiene acceso completo al sistema de archivos del proyecto: Read, Write, Bash y WebFetch están incluidos. Si le das el código para que lo analice, podrá entender tu lenguaje de diseño y luego producir salidas basadas en el estilo existente.

Crear una línea base visual rápidamente con un selector de dirección

Cuando no hay especificaciones de diseño, en Turn 2 aparecerán 5 direcciones predefinidas, cada una con un set determinista de paletas de color OKLch + una pila de tipografías:

Al elegir una dirección, el agente sobrescribirá las variables :root de las plantillas de habilidades con esta paleta; a partir de ahí, todos los componentes seguirán esa especificación.

Subir capturas para que el agente extraiga el lenguaje de diseño

Este es un uso más alineado con proyectos reales. Open Design trae integrado un protocolo de extracción de activos de marca:

1. Locate  — localizar en la captura los bloques clave de color
2. Download — descargar la captura al directorio del proyecto
3. Grep hex — extraer valores hex
4. Codify   — escribir en brand-spec.md
5. Vocalise — el agente genera basándose en brand-spec.md, no adivinando por memoria

La operación es simple:

"Here's our current app, I want you to match the styles"
# Luego añade una captura o pega la URL de la página existente

El agente analizará en la captura los rasgos de colores principales/secundarios, tipografías y espaciados, generará brand-spec.md y, a partir de ahí, todas las modificaciones se basarán en esa especificación.

Leer directamente el código: más preciso que usar capturas

El directorio de trabajo por defecto del agente es .od/projects/<id>/, pero puedes colocar allí proyectos existentes:

# Copia tu proyecto al directorio de trabajo de Open Design
cp -r ~/my-app/.   .od/projects/<ID_DEL_PROYECTO>/

O también puedes hacer que el agente lea entre directorios directamente usando un servidor MCP (ver la siguiente sección).

Luego envía instrucciones como estas:

"Read all .css files in ./src/styles and extract the color palette"

"Read the component library at ./components/. Generate a new
form component using the same spacing and border-radius tokens"

"I see you use Tailwind. Add a new button variant that matches
your existing primary/secondary button styles"

El agente recorrerá los archivos, analizará variables CSS / configuración de Tailwind, extraerá tokens de diseño y generará artefactos consistentes con el estilo del código existente.

Servidor MCP: leer archivos de diseño entre proyectos

¿No quieres copiar archivos? Open Design ofrece un servidor MCP para que tu agente de codificación pueda leer directamente archivos dentro de los proyectos de Open Design.

En la página Settings → MCP Server de Open Design tienes guías de configuración para diferentes clientes. Una vez configurado, los agentes de Claude Code / Cursor que ejecutas en otros proyectos (por ejemplo ~/my-app) pueden consultar directamente los archivos de diseño del proyecto abierto en Open Design.

Flujo recomendado para escenarios de modificación

1. Abre Open Design y elige una habilidad similar al estilo de tu proyecto (p. ej., web-prototype)

2. Turn 1 (formulario):
   - Surface: Web
   - Audience: el público existente
   - Tone: mantener coherencia con el producto actual

3. Turn 2 (selección de dirección):
   - Si quieres mantener la coherencia → sube capturas de la página existente para que el agente extraiga brand-spec.md
   - Si permites un rediseño moderado → elige una dirección como línea base visual

4. Envía una instrucción:
   "Add a settings page to my existing project at ./src,
    match the color palette and typography from the attached screenshot"

El agente:

1. Lee la captura y extrae brand-spec.md (o lee variables CSS desde el código)
2. Lee los archivos existentes de tu proyecto
3. Reutiliza los colores principales/secundarios y la tipografía en la nueva página
4. Genera HTML ejecutable con un estilo coherente con el proyecto existente

---

Solución de problemas frecuentes

Q1: Versión de Node incorrecta; error Requested version v24.x.x is not currently installed

Open Design requiere Node 24. Instálalo con nvm o fnm:

nvm install 24 && nvm use 24
# o
fnm install 24 && fnm use 24

Si usas fnm, asegúrate de que el archivo de configuración de tu shell carga fnm env (consulta la documentación oficial de fnm ).

Q2: No se detectó el agente de codificación

Open Design escanea PATH en el primer arranque. Verifica que la CLI esté instalada y sea global:

# Verifica algún agente
which claude     # macOS/Linux
where claude     # Windows

# Si está instalado pero aun así no se detecta, prueba reiniciar el servicio
pnpm tools-dev stop && pnpm tools-dev start web

Q3: El puerto está ocupado

Los puertos por defecto 17456 (daemon) y 17573 (web) pueden estar ocupados:

# Cambia a otros puertos
pnpm tools-dev run web --daemon-port 17457 --web-port 17574

Q4: Al cambiar el sistema de diseño no cambia el estilo

El sistema de diseño de Open Design inyecta estilos leyendo variables CSS desde DESIGN.md. Cada vez que cambias el sistema, el agente lo usa en una nueva conversación; las conversaciones antiguas ya generadas no se actualizan automáticamente. Abre una conversación nueva para aplicar el sistema actualizado.

Q5: El iframe de vista previa carga en blanco

El iframe sandbox usa srcdoc para renderizar. Si no se muestra el contenido:

1. Revisa si hay errores de CSP en la consola del navegador
2. Confirma que el plugin/bloqueador de anuncios no esté bloqueando la carga del iframe
3. Descarga haciendo clic en «Download HTML» y ábrelo localmente para verificar

Q6: Error de API Key en modo BYOK

El agente BYOK se encuentra en /api/proxy/{anthropic,openai,azure,google}/stream. Verifica:

1. Que el baseUrl configurado en la página Settings sea correcto (formato compatible con OpenAI)
2. Que la API Key sea válida y tenga permisos para el modelo correspondiente
3. Que no hayas dejado vacío el campo apiKey; si no se completa, el servidor rechazará la solicitud (protección SSRF)

---

Lecturas adicionales / direcciones avanzadas

Agregar habilidades de diseño personalizadas

Las habilidades existen con la forma de carpetas SKILL.md + assets/ + references/, siguiendo el estándar de SKILL.md de Claude Code.

En skills/ crea una nueva carpeta, agrega SKILL.md y define el frontmatter od: (mode, scenario, design_system.requires, etc.). Después de reiniciar el servicio, aparecerá automáticamente en el selector de habilidades.

Importar el paquete exportado de Claude Design

Claude Design de Anthropic admite exportación ZIP. Arrastra el ZIP al cuadro de diálogo de bienvenida de Open Design; POST /api/import/claude-design lo analizará y reconstruirá el proyecto para que el agente pueda continuar editando sin problemas.

Integrar un servidor MCP

Open Design ofrece un servidor MCP por stdio. Configúralo en clientes MCP como Claude Code/Cursor/VS Code; el agente podrá leer directamente archivos de diseño y recursos de los proyectos de Open Design, sin necesidad de exportar ZIP manualmente.

Construir apps de escritorio

La versión de escritorio de Electron admite macOS (Apple Silicon) y Windows (x64):

# macOS
pnpm tools-pack mac build --to all
pnpm tools-pack mac install

# Windows
pnpm tools-pack win build --to nsis
pnpm tools-pack win install

La App empaquetada puede ejecutarse de forma independiente; los datos se guardan en el directorio AppData del sistema.

Extender capacidades de generación multimedia

Además de los artefactos de código, Open Design también integra modelos para generar imágenes (gpt-image-2), videos (Seedance 2.0, HyperFrames) y audio (Suno, Udio). Tras configurar una API Key, el flujo de diseño puede producir directamente archivos multimedia como .mp4, .png, etc.

---

Dirección del proyecto: nexu-io/open-design