Saltar a contenido

ADR-021 · Tipografía + design system governance

Fecha: 2026-04-29 Source: /srv/projects/cis/cis-plan/DECISIONS.md (do not edit here — re-split desde la fuente)

Contexto

El ecosistema CIS tiene 16+ frontends consumidores de core-style. La tipografía hasta 2026-04 era ambigua: VISION.md mencionaba "Inter" en algunos puntos, otros componentes usaban Helvetica fallback, el wordmark del navbar usa IBM Plex 800. La incoherencia se notaba en sub-brands (cochid, periodismo2, isometrico) donde cada uno definía su propio fallback.

CLAUDE.md del workspace y CONSTITUTION.md (§2.1) ya fijaron IBM Plex Sans + JetBrains Mono como estándar. ADR-013 (cis-admin stack) lo asume. core-style/v6/cis.min.css ya tiene los @font-face apuntando a archivos locales. Pero falta el ADR explícito que:

  1. Fije los pesos canónicos.
  2. Prohíba Google Fonts CDN (privacy + offline).
  3. Formalice la governance de v6 (frozen, deprecation 90d, sub-brands).
  4. Documente la regla "nuevos sub-brands en core-style/v6/brands/<slug>/tokens.css".

Alternativas consideradas

  1. (a) Google Fonts CDN (fonts.googleapis.com)
  2. Pro: cero hosting, lazy load auto, cache compartido entre sites.

  3. Contra: cada visitante envía request a Google → leak de IP y User-Agent. Falla si Google se cae o el user bloquea third-party. Privacy issue para CIS (procesamos datos chilenos).

  4. (b) Self-host en core-style/v6/fonts/ ← propuesta

  5. Pro: zero dependency externa. Privacy-respectful. Cache HTTP de Caddy. Versiones fijas y reproducibles.

  6. Contra: ~600KB extra en core-style repo (5 weights × IBM Plex × WOFF2 + 4 weights × JetBrains Mono). Mitigado por preload selectivo en <head>.

  7. (c) System fonts (-apple-system, BlinkMacSystemFont, ...)

  8. Pro: zero KB. Native look.
  9. Contra: cada OS renderiza distinto. Marca CIS pierde identidad. Ya descartado por VISION.md.

Decisión

Familia primaria: IBM Plex Sans, weights 400, 500, 600, 700, 800. Fallbacks: system-ui, sans-serif.

Familia mono: JetBrains Mono, weights 400, 500, 700. Fallbacks: ui-monospace, monospace.

Hosting: self-hosted en /srv/projects/core/core-style/v6/fonts/, servido por style.innovacionsantiago.cl con Cache-Control: public, max-age=31536000, immutable (los nombres incluyen hash). Cero requests a Google Fonts ni CDN externo. Privacy-respectful por convicción CIS.

Preload obligatorio en <head> de cada frontend:

<link rel="preload" href="https://style.innovacionsantiago.cl/v6/fonts/plex-sans-600.woff2" as="font" type="font/woff2" crossorigin>
<link rel="preload" href="https://style.innovacionsantiago.cl/v6/fonts/plex-sans-400.woff2" as="font" type="font/woff2" crossorigin>

Governance v6 (frozen + deprecation):

  • v6 está frozen desde 2026-04-XX (date stamp en core-style/v6/CHANGELOG.md). No breaking changes hasta v7. Ajustes minor (nuevos tokens, nuevos brands) van con bump v6.X.
  • v5 está frozen y servido inmutable hasta 90 días post-deploy de v6 (deprecation policy). Path: style.innovacionsantiago.cl/v5/*.
  • v6 → v7: cuando el ADR de v7 se acepte, regla idéntica — 90 días de gracia en v6.

Sub-brands: cada producto con identidad propia (cochid, periodismo2, situación, isometrico, librospa, usaia, firmas, indieweb, admin, claudia, portal, mando, infra) tiene un archivo dedicado:

core-style/v6/brands/<slug>/tokens.css

con sus accent colors, hero gradients, opcional fuente secundaria. Importado vía <link rel="stylesheet" href="/v6/brands/<slug>/tokens.css">. Default: hereda IBM Plex Sans + JetBrains Mono. Una sub-marca solo override fuentes si hay justificación documentada (ej. periodismo2 podría usar serif para body en artículos largos — caso a evaluar).

Logos monogram: SVG 64×64 en core-style/brand/<slug>/logo.svg, con IBM Plex 800 sobre accent color del brand. Fila 16 brands ya productiva (CONTRACTS.md). Nuevo brand requiere crear logo + tokens.css en mismo PR.

Consecuencias

  • Positivo: identidad visual coherente cross-ecosystem. Privacy-respectful. Reproducible (si Google Fonts cambia su CDN o ToS, no nos afecta). Sub-brands declarativos en un solo lugar.
  • Negativo: ~600KB extra hosted. Mitigado por immutable cache + preload selectivo (solo se preload los 2-3 weights críticos por frontend).
  • Riesgo: licencia IBM Plex (SIL OFL) y JetBrains Mono (Apache 2.0) son ambas open source y permiten redistribución. Verificación legal hecha 2026-04-22. Si en el futuro ambas cambian licencia (improbable), el ADR se reverte.
  • Migración: frontends en v5 migran cuando consumen v6. Frontends nuevos arrancan en v6. v5 sigue servido 90d post-deploy v6 (cumplido por design).
  • Compatibilidad: cualquier frontend que ya consume style.innovacionsantiago.cl/v6/cis.min.css ya está alineado. Frontends que importan Google Fonts directamente (legacy cis-www/index.html revisado 2026-04-15) deben migrar — ticket abierto en BACKLOG flujo 10.
  • Brand new: la creación de un nuevo sub-brand requiere PR a core-style con (a) brands/<slug>/tokens.css, (b) brand/<slug>/logo.svg 64×64 monogram, (c) entry en CHANGELOG core-style. Sin esos 3, el brand no se considera registrado.
  • Dependencia de Caddy: style.innovacionsantiago.cl es Caddy file_server puro con immutable headers. Configuración en /etc/caddy/sites.d/style.caddy. Cambios al cache policy requieren CHANNEL announcement.