ADR-031 — Design system

Architecture decision record — status: Accepted.

Source: docs/adr/ADR-031-design-system.md

ADR-031: Design system

Estado

Accepted — 2026-08-23
Amendment 2026-08-24: contrato de tokens IVPrior + chrome admin (SLICE-001-00).

Contexto

Un panel finance usado por agentes y humanos. Sin design system, cada slice inventa botones y tablas. Factory: Tailwind + shadcn + tokens.

Decisión

  1. Design tokens en packages/ui (color, spacing, type). Prohibido hex suelto en apps/web/features.
  2. shadcn/ui como base de átomos; moléculas/organismos en packages/ui cuando se reutilicen 2+ features.
  3. Desktop-first, usable en tablet (ADR-005).
  4. Accesibilidad: labels, foco, contraste; no es un portal consumidor.
  5. Copy de UI en inglés US (ADR-035).
  6. Tono: profesional, no “cobrador”. Sin dun / chase / amenazas (glosario).
  7. Specs S-xxx + wireframe HTML P0 antes de UI de producción (constitution §IX). Chrome admin = patrones y packages de este repo (ADR-062 / DOC-024): AdminPageToolbar, list CRUD, wizard. Tokens: contrato --bg/--ink/--green; valores light IVPrior.

Alternativas

Metronic/tema comprado como sistema: se puede usar de referencia visual (como en IVPrior) pero los tokens viven en repo.

Consecuencias

  • Scaffolding instala shadcn + tokens mínimos. No se piden 40 pantallas diseñadas antes de apps/web.