🌱 Fundamentos

Lançamento da Anthropic em 17/04/2026 que provou que LLMs podem entregar artefatos de design HTML rodáveis, não só prosa.

É o ponto de virada que motivou o OD. Entender o que ele provou (e o que travou) explica o porquê de cada decisão do OD.

Closed-source · cloud-only · pago · Anthropic-only · Opus 4.7 · split-screen artifacts panel

O hábito de jogar um brief grande no LLM e esperar que ele "se vire" — gera resultado caótico, com decisões visuais aleatórias.

Mostra o problema que o OD resolve: estruturar o brief, travar decisões antes do pixel, restringir o espaço de improvisação do modelo.

Brief mal estruturado · variância visual · retrabalho caro · falta de critério · sem checklist

Lista explícita de padrões "AI freestyle" proibidos no prompt do OD: gradientes roxos, ícones emoji genéricos, métricas inventadas.

Sem essa blacklist, qualquer LLM vai cair nos mesmos clichês. Codificar o "não" é mais barato que tentar acertar o "sim".

Gradiente roxo · Inter como display · invented metrics · placeholders honestos > fake stats

Daemon local em Node, SQLite local, BYOK em todas as camadas, sem login obrigatório, sem telemetria.

Diferencial estrutural vs Claude Design (cloud-only). Permite uso offline, dados sensíveis, controle total.

Daemon · BYOK · SQLite local · 3 topologias de deploy · sem account

OD escaneia seu PATH e detecta CLIs de agente (Claude Code, Codex, Cursor, Gemini, etc.) — uma delas vira o motor.

Não tem dependência de modelo único. Se você muda de Claude pra Codex amanhã, OD pega sem mudança.

PATH scan · 11 CLIs suportados · adapter por CLI · BYOK proxy fallback

Os 4 projetos que o OD canibalizou: huashu-design (filosofia), guizang-ppt (deck), open-codesign (UX), multica (daemon).

Saber a linhagem evita reinventar a roda e ajuda a entender por que cada peça tem o formato que tem.

huashu-design · guizang-ppt-skill · open-codesign · multica-ai · awesome-design-md

Tabela comparativa nos eixos: licença, deploy, runtime de agente, skills, design system, BYOK.

Saber posicionar o OD em uma conversa de stakeholder, em 30 segundos, sem dúvida.

Apache-2.0 vs Closed · Web+daemon vs Web · 11 CLIs vs 1 modelo · 31 skills vs proprietárias

Chat (input) + Skill (workflow) + Design System (vocabulário) + Agent CLI (motor) + Iframe preview (output).

Saber qual peça resolver quando algo dá errado. Output ruim? Skill ou Design System. Agente lento? CLI.

Composição · responsabilidade clara · pontos de troca

A: Local total · B: Vercel + tunnel para daemon · C: Browser-only com API direta (degradado).

Saber qual escolher: dev solo (A), time distribuído (B), demonstração rápida (C).

Topologia A · cloudflared tunnel · IndexedDB fallback · trade-offs

Daemon = único processo privilegiado · Web = Next.js UI · Desktop = Electron shell que descobre Web via IPC.

Cada um tem responsabilidade clara. Saber onde editar para mudar comportamento sem quebrar outro.

apps/daemon · apps/web · apps/desktop · sidecar IPC

O agente emite um único bloco <artifact> com HTML; um parser do OD extrai e renderiza em iframe sandboxed.

É a fronteira de segurança. Tudo que o agente gera passa por sandbox antes de mostrar.

srcdoc iframe · sandboxing · streaming parse · React 18 + Babel vendorizados

Tabelas: projects, conversations, messages, tabs, templates. Tudo persiste entre sessões.

Reabrir projeto amanhã = exatamente onde você parou. Card de todo, abas abertas, tudo.

better-sqlite3 · 5 tabelas · OD_DATA_DIR · gitignored

POST /api/import/claude-design — descompacta um export do Claude Design e abre como projeto OD.

Migração sem dor. Continua editando onde a Anthropic parou.

ZIP parsing · projeto auto-criado · prompt de continuidade

discovery + identity charter + DESIGN.md ativo + SKILL.md ativo + project metadata + skill side-files (+ deck framework).

Cada camada é editável. Saber em qual camada modificar evita quebrar as outras.

composeSystemPrompt · ordem de prioridade · injeção dinâmica

Cada camada é um arquivo TS ou Markdown. Pode ser editado, versionado, revertido individualmente.

Mudanças cirúrgicas em vez de prompt-engineering bagunçado num único string gigante.

Single-responsibility por camada · git-friendly · review-friendly

Turn 1 = question form. Turn 2 = branch de marca. Turn 3+ = TodoWrite com plan.

Esse é o "coração" do OD. Sem essas regras, vira AI freestyle.

discovery.ts (263L) · question form · branch A/B/C · live todos

Camada fixa com a identidade do agente: anti-slop blacklist + junior-pass + design philosophy.

Define o "caráter" do agente independente de skill ou DS escolhidos.

official-system.ts · identidade fixa · contrastes com discovery

Antes de gerar, o agente lê assets/template.html + references/*.md da skill ativa.

É o que faz o agente NÃO escrever CSS do zero — copia o seed e adapta.

Auto-injeção · template.html como seed · references/layouts.md · references/checklist.md

Discovery domina sobre identity. Identity domina sobre DESIGN/SKILL. Metadata só adapta o existente.

Saber onde "vence" cada regra evita debugging aleatório quando algo conflita.

Hierarquia explícita · regra de precedência · debug de conflito

Frontmatter mínimo: name, description, triggers. Body em Markdown livre.

É a base. Sem ela, OD não enxerga sua skill.

YAML frontmatter · triggers · skill discovery

assets/ = arquivos que o agente ESCREVE (template.html, imagens). references/ = arquivos que o agente LÊ (layouts.md, checklist.md).

Convenção clara: o que é seed vs o que é doc.

Write target · Read source · separação de responsabilidades

Campos opcionais: mode, platform, scenario, preview, design_system, default_for, featured.

Desbloqueia UI específica do OD (picker, preview, sliders) sem quebrar Claude Code.

prototype/deck/template/design-system · scenario · preview.type

27 prototype + 4 deck. Agrupadas por scenario: design/marketing/operation/engineering/product/finance/hr/sale/personal.

Saber qual skill aciona qual triger. Evita criar skill duplicada.

web-prototype · saas-landing · dashboard · guizang-ppt · taxonomia

O agente é forçado a ler template.html + layouts.md + checklist.md ANTES de escrever CSS.

É a maior razão pela qual output do OD parece consistente vs caótico.

Step 0 · Read antes de Write · seed driven

Skill OD roda em Claude Code puro. Skill Claude Code roda no OD. Sem fork.

Investimento em skill é portável. Comunidade Claude Code também serve OD.

Bidirecional · graceful degradation · ecossistema unificado

~/.claude/skills/ (global), ./skills/ (repo), ./.claude/skills/ (project local). Escaneadas no boot.

Saber onde colocar skill nova baseado em escopo (global vs repo vs project).

3 locais · FS-watch · merge order · scope

color, typography, spacing, layout, components, motion, voice, brand, anti-patterns.

Padroniza comparação entre sistemas. Pruning seletivo de seções economiza tokens.

awesome-design-md · 9 seções fixas · pruning

Espaço de cor perceptualmente uniforme. L=50% azul e L=50% amarelo têm a MESMA luminosidade percebida.

HSL não é uniforme — gera paletas com contraste imprevisível. OKLch corrige isso.

Lightness · Chroma · Hue · Display P3 · WCAG predictable

Catálogo: AI/LLM, dev tools, productivity, fintech, e-commerce, media, automotive, more.

Não precisa criar do zero — provavelmente o seu cliente já tem aproximação.

Linear · Stripe · Vercel · Apple · Notion · 72 marcas

--bg, --surface, --fg, --muted, --border, --accent. 6 variáveis universais.

Trocar de design system = trocar 6 valores no :root. Toda skill consome esses tokens.

CSS custom properties · 6 tokens canônicos · binding

Cada skill declara design_system.sections em SKILL.md — só essas seções entram no prompt.

Pruning seletivo economiza muito token em DSs grandes (Apple, Stripe).

design_system.sections · injeção parcial · context budget

scripts/sync-design-systems.ts puxa tarball de awesome-design-md, atualiza o catálogo.

Refresh do catálogo sem fork manual de cada sistema.

Sync script · upstream tarball · catalog refresh

Criar do zero quando: cliente sem brand-spec; ou marca não está nos 72; ou identidade muito singular.

Evitar fork desnecessário. Estender é mais barato que criar.

Estender vs criar · brand-spec · custom DESIGN.md

Projeto open-source chinês que destilou o método de "designer júnior simulando sênior batendo perguntas".

Saber a fonte permite ler as decisões originais (em Markdown) quando o prompt do OD parecer arbitrário.

alchaincyf/huashu-design · 5 escolas × 20 filosofias · método junior

Output do turn 1 = uma frase + <question-form id="discovery"> + STOP. Sem ferramentas, sem código.

Trava o brief antes do agente improvisar. 30s de radios > 30min de retrabalho.

Hard rule · time-to-first-byte · radio velocity

A: usuário escolhe direção pré-curada. B: brand-spec extraction de URL/screenshot. C: improvisar.

3 caminhos diferentes para 3 contextos. Saber qual cobra qual nível de info do usuário.

Branch A (direção) · B (brand-spec) · C (improvisar) · gate logic

Editorial Monocle · Modern Minimal · Tech Utility · Brutalist · Soft Warm. Cada uma com paleta OKLch determinística.

Reduz variância: 1 clique no radio = paleta + font stack fixos. Sem improviso do modelo.

5 escolas · paletas determinísticas · DesignDirection interface · directions.ts

Plano de 5-10 itens visível ao usuário, marcando in_progress → completed em tempo real.

Usuário pode redirecionar em pleno voo, sem esperar resultado final.

TodoWrite · live updates · cheap redirect · plan visibility

Cada skill traz references/checklist.md com gates obrigatórios (P0), recomendados (P1), nice-to-have (P2).

P0 falhar = não emitir <artifact>. Garante consistência mínima por skill.

P0 hard gate · P1 fix antes de export · P2 ideal · pre-emit

Antes de emitir, agente pontua silenciosamente: Philosophy / Hierarchy / Execution / Specificity / Restraint (1-5).

Anything < 3/5 = regressão, refazer. 2 passes é normal.

Self-critique · 5 dimensões · gate de regressão · re-score