ADR-0002 — Design system internalizado, não é mais pacote externo¶

Contexto¶

Até a spec 0017, o design system era o pacote @garantora/design-system, num repositório Git separado (Garantora/garantora_design_system). Havia duas fontes editáveis para a mesma verdade, e elas divergiram: o MuiSelect nasceu 13px mais baixo que os demais campos e a correção ficou só no app (spec 0016); o token surfacePanelHeader dizia navy enquanto o app pintava teal; a spec 0015 registrou três divergências conscientes. O padrão era sempre o mesmo — corrigir no lugar certo custava commit em outro repo, tag, bump da dependência e rebuild, então a correção acabava ficando só no app.

Isso já era, em si, a reversão de uma decisão anterior: em 2026-08-01, o caminho tinha sido o oposto — internalizar apps/web/design-system/ como pacote próprio.

Decisão¶

Trazer o design system de volta para dentro do apps/web, em apps/web/src/design-system/ — tema MUI em TypeScript, tokens em CSS e os .prompt.md de comportamento por componente. Não existe mais "levar ao design system": o diretório é o design system, e a mudança de tema entra no mesmo commit que o consome.

Alternativas consideradas¶

• Manter o pacote e disciplinar o processo de sincronização (checklist, CI que barra merge sem bump). Descartada: o app consome só o tema (540 linhas em cinco arquivos) e há um único consumidor — o custo do pacote (repo, tag, bump, rebuild, agente SSH no build) não se paga para um caso de uso desse tamanho.

Consequências positivas¶

• Uma correção de design vira um commit só, revisável e testável junto com quem a usa.
• O web.Dockerfile não precisa mais de git, openssh-client nem --mount=type=ssh — o pacote git privado exigia agente SSH carregado no build.

Consequências negativas¶

• Os .jsx de referência do Figma, ui_kits/ e as fichas guidelines/*.card.html do repositório antigo ficaram arquivadas, fora do monorepo — seguem legíveis lá, mas não são mais tocadas nem versionadas junto com o código que implementam.

Riscos¶

Nenhum novo além dos já existentes — o risco que esta decisão elimina (divergência entre duas fontes) era maior que o que ela introduz.

Status¶

aceita — spec 0017, mesclada em 2026-08-04.

Documentos relacionados¶

SPEC-0017 (a implementação completa desta decisão).