Guia de início com Open Design: a forma correta de usar o Claude Design na versão open source

Visão geral do projeto

Open Design é uma alternativa open source ao Claude Design, desenvolvida e mantida por nexu-io/open-design.

A ideia central é bem direta: não reinventar a roda. Os seus agentes de codificação já existentes (Claude Code, Codex, Cursor Agent etc., 16 tipos de CLI) viram o motor do design. Junto com 31 habilidades de design componíveis e 72 sistemas de design no nível de marca, todo o fluxo de design é feito localmente.

Principais recursos:

---

Perfil do público-alvo

• Desenvolvedores front-end/full-stack: querem usar IA para gerar layouts de design, mas não querem aprender operações complexas no Figma
• Desenvolvedores individuais: precisam produzir rapidamente landing pages, protótipos mobile e demonstrações de produto
• Equipes de design: buscam uma solução de automação de design com prioridade local, sem depender do cloud
• Entusiastas de ferramentas de IA: querem explorar o potencial dos agentes de codificação existentes no campo do design

---

Dependências principais e ambiente

Node.js ~24
pnpm 10.33.x (gerenciado via Corepack)
Sistema operacional: macOS / Windows / Linux

O Open Design faz uma varredura automática no PATH para detectar os agentes de codificação já instalados. Se não houver nenhuma CLI na sua máquina, ele vai te orientar a configurar o modo BYOK (requer uma API Key).

---

Estrutura completa da árvore do projeto

open-design/
├── apps/
│   ├── daemon/                 # serviço local (Express + SQLite)
│   │   └── src/
│   │       ├── agents.ts       # detecção de agentes de codificação e adaptadores
│   │       ├── skills.ts       # carregador de habilidades
│   │       └── server.ts       # rotas de API
│   └── web/                    # Front-end Next.js 16
│       └── src/
│           ├── prompts/        # templates de prompts
│           ├── artifacts/      # análise dos artefatos
│           └── components/     # componentes de UI
├── skills/                     # 31 habilidades de design
│   ├── web-prototype/          # protótipo web
│   ├── mobile-app/             # app mobile
│   ├── dashboard/              # dashboard
│   ├── guizang-ppt/            # apresentação
│   └── ...
├── design-systems/             # 72 sistemas de design
│   ├── linear-app/
│   ├── vercel/
│   ├── anthropic/
│   └── ...
├── assets/frames/              # frames de dispositivos (iPhone, Pixel, iPad, MacBook)
└── .od/                        # dados em tempo de execução (SQLite, arquivos do projeto)

---

Passo a passo

1) Clone o repositório e instale as dependências

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

corepack enable lê automaticamente a versão do pnpm fixada no package.json (10.33.x), garantindo consistência no ambiente do time.

2) Inicie o servidor de desenvolvimento local

pnpm tools-dev run web

Quando iniciar com sucesso, ele imprimirá dois URLs:

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

Abra o URL da Web no navegador para começar a usar.

3) Selecione o agente de codificação

Ao abrir a interface Web pela primeira vez, o Open Design detecta automaticamente os agentes de codificação que estão no seu PATH.

Suportado: 16 CLIs:

O seletor de modelo no canto superior direito da interface mostrará os agentes detectados. Se não houver nenhuma CLI, clique para selecionar o modo BYOK e execute via as APIs OpenAI/Anthropic/Azure/Gemini usando sua API Key.

4) Selecione a habilidade de design

A página inicial lista 31 habilidades, agrupadas por cenário:

• Design: web-prototype (padrão), 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 (apresentação): guizang-ppt (padrão), simple-deck, replit-deck, weekly-update

De acordo com sua necessidade, clique na habilidade correspondente. Por exemplo, escolha mobile-app para gerar um protótipo mobile.

5) Selecione o sistema de design

Depois de escolher a habilidade, o painel do sistema de design será exibido. Por padrão, existem dois sistemas iniciais: default (Neutral Modern) e warm-editorial (Warm Editorial).

A biblioteca completa inclui 72 sistemas de design de marca:

• AI & LLM: claude, cohere, mistral-ai, ollama, x-ai…
• Ferramentas de desenvolvimento: cursor, vercel, linear-app, supabase, posthog, sentry…
• Produtos: notion, figma, airtable, intercom, raycast…
• E-commerce: shopify, airbnb, uber, nike, starbucks…
• Carros: tesla, bmw, ferrari, lamborghini…
• Outros: apple, ibm, nvidia, spotify…

Você também pode enviar seu próprio arquivo DESIGN.md, definindo normas de design em 9 dimensões, como cores da marca, fontes, espaçamento etc.

6) Envie instruções de design

No campo de entrada, descreva sua necessidade de design, por exemplo:

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

Depois de preencher o formulário e enviar, o agente fará:

1. Gerar um plano TodoWrite e atualizar em tempo real via streaming
2. Ler os templates de habilidade e o sistema de design
3. Executar uma autoanálise em 5 dimensões (filosofia, hierarquia, execução, especificidade, contenção)
4. Produzir o código <artifact>
5. Renderizar uma prévia em um iframe do sandbox

7) Visualização e exportação

Após renderizar o layout do design, você pode:

• Editar em tempo real: modificar diretamente HTML/CSS no workspace de arquivos à direita
• Baixar: exportar como HTML (recursos embutidos), PDF, PPTX, ZIP ou Markdown
• Salvar no disco: clique em «Save to disk»; os artefatos serão salvos em .od/artifacts/
• Continuar a conversa: diga ao agente «mude o botão para ficar com cantos arredondados» ou «troque a paleta de cores»; ele continuará a modificação com base no layout atual

Outros comandos comuns:

# Ver status de execução
pnpm tools-dev status

# Ver logs
pnpm tools-dev logs

# Parar todos os serviços
pnpm tools-dev stop

# Reiniciar (cenário de troca de portas)
pnpm tools-dev restart --daemon-port 17456 --web-port 17573

# Diagnosticar problemas
pnpm tools-dev check

---

Modificar um projeto existente

Muitas pessoas ao receber o Open Design pensam primeiro: «não é apenas uma ferramenta para gerar uma nova página?». Na verdade, ele também pode ser usado para modificar um projeto existente, e não exige que exista algum DESIGN.md dentro do seu projeto.

A lógica central é bem simples: o agente tem acesso completo ao sistema de arquivos — Read, Write, Bash, WebFetch tudo está disponível. Ao fazer com que ele analise seu código, ele entende sua linguagem de design e então gera um resultado baseado no estilo já existente.

Usar o seletor de direção para estabelecer um baseline visual rapidamente

Se não houver normas de design definidas, no Turn 2 aparecem 5 direções predefinidas, cada uma sendo uma paleta de cores OKLch determinística + um conjunto de fontes:

Depois de escolher uma direção, o agente usa essa paleta para substituir as variáveis :root do template de habilidade; a partir daí, todos os componentes seguirão essas normas.

Enviar capturas para o agente extrair a linguagem de design

Este é um modo mais alinhado com projetos reais. O Open Design vem com um protocolo embutido de extração de ativos de marca:

1. Locate  — localizar os blocos de cor-chave na captura
2. Download — baixar a captura para o diretório do projeto
3. Grep hex — extrair valores hex
4. Codify   — escrever em brand-spec.md
5. Vocalise — o agente gera com base em brand-spec.md, e não chuta a partir de memórias

O uso é simples:

"Here's our current app, I want you to match the styles"
# Depois anexe um screenshot ou cole a URL da página existente

O agente analisa as cores principais/secundárias, características de fontes e espaçamento na captura para gerar brand-spec.md. A partir daí, todas as próximas modificações se baseiam nessa especificação.

Ler diretamente o código, mais preciso do que screenshots

O diretório de trabalho padrão do agente é .od/projects/<id>/, mas você pode colocar seus projetos existentes lá:

# Copie seu projeto para o diretório de trabalho do Open Design
cp -r ~/my-app/.   .od/projects/<PROJETO-ID>/

Ou use um servidor MCP para permitir leitura entre diretórios diretamente (veja a próxima seção).

Depois envie instruções 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"

O agente percorre os arquivos, analisa variáveis CSS / configurações do Tailwind, extrai design tokens e então gera artefatos com estilo consistente com o código existente.

Servidor MCP: leitura de arquivos de design entre projetos

Não quer copiar arquivos? O Open Design oferece um servidor MCP que permite que seu agente de codificação leia diretamente os arquivos do projeto do Open Design.

Na página Open Design Settings → MCP Server, há guias de configuração para diferentes clientes. Após configurar, os agentes Claude Code / Cursor executados em outros projetos (como ~/my-app) podem consultar diretamente no Open Design os arquivos de design do projeto aberto.

Fluxo recomendado para cenários de modificação

1. Abra o Open Design e selecione uma habilidade próxima ao estilo do seu projeto (por exemplo, web-prototype)

2. Turn 1 (formulário):
   - Surface: Web
   - Audience: público-alvo existente
   - Tone: manter consistente com o produto atual

3. Turn 2 (seleção de direção):
   - Quer manter consistente → envie screenshot da página existente para extrair brand-spec.md
   - Permitir redesenho moderado → selecione uma direção como baseline visual

4. Envie instruções:
   "Add a settings page to my existing project at ./src,
    match the color palette and typography from the attached screenshot"

O agente fará:

1. Ler a captura → extrair brand-spec.md (ou ler as variáveis CSS no código)
2. Ler os arquivos existentes do seu projeto
3. Reusar cores principais, cores secundárias e fontes na nova página
4. Gerar HTML executável, com estilo consistente com o projeto atual

---

Solução de problemas comuns

Q1: Versão do Node incorreta, erro Requested version v24.x.x is not currently installed

O Open Design exige Node 24. Instale usando nvm ou fnm:

nvm install 24 && nvm use 24
# ou
fnm install 24 && fnm use 24

Se estiver usando fnm, certifique-se de que o arquivo de configuração do seu shell carregue fnm env (consulte a documentação oficial do fnm）。

Q2: O agente de codificação não foi detectado

O Open Design varre o PATH na primeira inicialização. Verifique se a CLI está instalada e disponível globalmente:

# Verificar um agente específico
which claude     # macOS/Linux
where claude     # Windows

# Se estiver instalado mas ainda não for detectado, tente reiniciar o serviço
pnpm tools-dev stop && pnpm tools-dev start web

Q3: Porta em uso

As portas padrão 17456 (daemon) e 17573 (web) podem já estar ocupadas:

# Trocar para outras portas
pnpm tools-dev run web --daemon-port 17457 --web-port 17574

Q4: Ao alternar o sistema de design, o estilo não muda

O sistema de design do Open Design injeta estilos lendo as variáveis CSS em DESIGN.md. Depois de cada troca de sistema, o agente usa novas variáveis em uma nova conversa; conversas antigas já geradas não atualizam automaticamente. Abra uma nova conversa para aplicar o novo sistema.

Q5: O iframe de prévia carrega em branco

O iframe do sandbox renderiza com srcdoc. Se o conteúdo não aparecer:

1. Verifique se há erros de CSP no console do navegador
2. Confirme que o plugin de bloqueio de anúncios não está bloqueando o carregamento do iframe
3. Clique em «Download HTML», faça o download e abra localmente para validar

Q6: BYOK retorna erro de API Key

Os agentes BYOK ficam em /api/proxy/{anthropic,openai,azure,google}/stream. Confirme:

1. O baseUrl configurado na página Settings está correto (formato compatível com OpenAI)
2. A API Key é válida e tem permissões para o modelo correspondente
3. Se o campo apiKey não for preenchido, o servidor recusará a requisição (proteção contra SSRF)

---

Leitura adicional / caminhos avançados

Adicionar habilidades de design personalizadas

As habilidades existem na forma de pastas com SKILL.md + assets/ + references/, seguindo o padrão de SKILL.md do Claude Code。

Crie uma nova pasta em skills/, adicione SKILL.md e defina o frontmatter od: (mode, scenario, design_system.requires etc.). Depois de reiniciar o serviço, ele aparecerá automaticamente no seletor de habilidades.

Importar pacotes exportados do Claude Design

O Claude Design da Anthropic suporta exportar ZIP. Arraste o ZIP para o quadro de boas-vindas do Open Design e o POST /api/import/claude-design fará a análise e reconstruirá o projeto; o agente pode continuar a edição sem interrupções.

Integrar servidores MCP

O Open Design fornece um servidor MCP stdio. Configure em clientes MCP como Claude Code/Cursor/VS Code; assim, o agente consegue ler diretamente os arquivos e materiais de design do projeto do Open Design, sem precisar exportar ZIP manualmente.

Construir um app para desktop

A versão desktop do Electron oferece suporte a macOS (Apple Silicon) e 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

O App empacotado pode rodar independentemente, com os dados armazenados no diretório AppData do sistema.

Expandir capacidades de geração de mídia

Além dos artefatos de código, o Open Design também integra modelos para geração de imagens (gpt-image-2), vídeo (Seedance 2.0, HyperFrames) e áudio (Suno, Udio). Após configurar a API Key, o fluxo de design pode produzir diretamente arquivos de mídia como .mp4 e .png.

---

Endereço do projeto：nexu-io/open-design