impeccable — o motor de design (fonte única de UI)¶
O que é¶
Fonte única de design do monorepo: o design system vive no código
(DESIGN.md/PRODUCT.md), e é nele que todo trabalho de UI ancora. Substituiu os DS
antigos — to-prototype (canvas no Paper) e o .claude/system/design/ (ORBIT legado) foram
aposentados. Motor de design 3rd-party, vendorizado no repo (não é dependência npm), em três
runtimes (.claude/, .github/, .opencode/). Faz duas coisas: gera/mantém o design
system em código; revisa e afina UI por comando (critique, audit, polish, craft…).
Os dois arquivos¶
Decisão 2026-07-11: o DS é centralizado na raiz porque vários apps seguem o mesmo.
| Arquivo | Onde | Escopo |
|---|---|---|
DESIGN.md |
raiz do monorepo | Único e compartilhado por todos os apps: cores, tipografia, componentes, tokens, regras nomeadas. O "como parece". |
PRODUCT.md |
por app | Register, usuários, propósito, princípios estratégicos. Difere entre apps. |
Cada app que usa o DS aponta um symlink apps/<app>/DESIGN.md → ../../DESIGN.md — editar o
DS é sempre editar o da raiz.
Os comandos¶
Agrupados por intenção: Sistema (init, document, extract, live);
Planejar/construir (shape, craft); Revisar (critique, audit, polish,
harden, onboard, optimize); Ajustar (layout, typeset, colorize, animate,
bolder/quieter, distill/delight, clarify, adapt).
Como se encaixa no harness¶
Princípio: interface não é pra toda feature. Todo passo de design é gated em "tem
tela?" — quem decide o gate é co-create/to-prd (declarativo) e, nos guardians, "o diff
toca apps/*/client/**?" (observável). Modelo completo das duas lanes independentes
(engenharia sempre roda; design só se tem tela) em loop-engineering.
O impeccable não é uma etapa nova — é a fonte que todo mundo consulta + o revisor no guardian:
| Etapa | Papel do impeccable |
|---|---|
co-create/to-prd |
Ancoram UX/UI no DESIGN.md+PRODUCT.md+shadcn MCP. |
| Rascunho (opcional) | Claude Design (/design-sync), não roda automático. |
to-build |
Fan-out front‖back; front cria (build+polish) ou altera (ajuste cirúrgico); auto-review critique/audit antes do PR. |
pr-guardian (4c) |
Revisão de design pré-merge: critique+audit ancorados no DESIGN.md. Quebra de a11y AA ou desvio grande = risco 🚫. |
prod-guardian (3c) |
Mantém o DESIGN.md honesto pós-merge: extract/document se subiu componente/token novo. |
Detalhe dos guardians: comite-de-agentes.
Setup (one-time)¶
npx impeccable install # depois: /impeccable init (escolha "product")
DESIGN.md gerado uma vez na raiz; cada app novo ganha o symlink. PRODUCT.md um por app.
Conectar o shadcn MCP. Detalhe: onboarding §4.
O hook (vigia passivo)¶
.github/hooks/impeccable.json roda em todo edit/create/apply_patch (postToolUse, 5s),
sinalizando anti-padrões inline enquanto se mexe em UI — barato, não bloqueia.
Fronteira com o resto¶
shadcn MCP serve os componentes reais do UI Kit; o DESIGN.md diz como usar. Claude Design
(/design-sync) é canvas de prototipagem opcional — o DS do código é a fonte das duas
pontas. Aposentados: to-prototype e o DS legado ORBIT.
Relacionado¶
loop-engineering · comite-de-agentes · skills · onboarding · visao-geral