Tokens y distribución

Todo el lenguaje visual vive en un solo archivo: theme/tokens.ts. De ahí se generan los artefactos que consumen la app, otros proyectos y los LLMs. Nunca se editan a mano los archivos generados.

Artefactos generados

Archivo	Para qué	Consumidor
/tokens.json	Tokens en crudo (color, radios, tipografía, sombras)	Herramientas, LLMs, scripts
/tokens.css	Variables CSS --lg-* (claro y oscuro)	Cualquier proyecto web
/llms.txt · /llms-full.txt	Documentación legible por máquinas	Agentes / LLMs

Cómo usarlo hoy (Fase 1)

En cualquier proyecto de Legalty, importa las variables y úsalas directamente:

@import "https://<host>/tokens.css";

.boton-primario {
  background: var(--lg-accent-solid);
  border-radius: var(--lg-radius-md);
  font-family: var(--lg-font-sans);
}

Cómo lo consume el dashboard: archivo generado, no paquete

El dashboard no copia los tokens a mano —lo hizo durante meses y divergieron: el gris terciario decía una cosa aquí y otra allí—. Tiene un script que trae tokens.css y tokens.json y escribe dos artefactos versionados en su repo:

npm run tokens:sync     # trae y escribe
npm run tokens:check    # falla si lo escrito no coincide con el origen

• src/styles/tokens.generated.css — copia literal, importada desde globals.css.
• src/theme/nextui-theme.generated.js — el tema de NextUI v2 resuelto en modo operativo.

Por qué no un paquete npm

Es la respuesta evidente y hoy no funciona: este repo es private, no hay registro privado ni CI que publique, y el dashboard construye en Docker sin el repo hermano al lado. Un archivo generado y committeado funciona en los tres sitios y —lo que de verdad importa en producción— hace que un cambio de token aparezca como un diff revisable en un PR. La sincronización no es automática a propósito: nadie quiere que el color de un botón cambie en producción porque alguien tocó tokens.ts un viernes.

Un detalle que hay que respetar: los nombres de las fuentes

Las familias se declaran como var(--font-sans, "Inter"), con el fallback dentro del var(). Sin él, un consumidor que no defina esa variable exacta no cae a Inter: un var() sin fallback y sin definir invalida la propiedad entera al calcular el valor, y el texto sale en la fuente del navegador. El contrato para quien carga las fuentes con next/font es nombrarlas --font-display, --font-sans y --font-mono.

Grupos de tokens

• Color — neutros, acento de marca y semánticos, en claro y oscuro.
• Radios — escala rounded expresivo (--lg-radius-xs … --lg-radius-pill).
• Espaciado — base 4px (--lg-sp-1 … --lg-sp-16).
• Tipografía — familias brand / display / sans / mono y escala.
• Modos — alias de rol y deltas de marketing y app (ver Modos).
• Densidad — --lg-density-*, con su variante compacta.
• Sombras — --lg-shadow-sm|md|lg.