Saltar al contenido principal

Tokens

@zuccadev-labs/zuix-tokens es la fuente única de los valores de diseño. Iconos, componentes, layouts y documentación leen de aquí. Cambiar de marca es añadir o editar un archivo en tokens/brands/.

Tres niveles​

NivelQué contieneVariable CSSQuién lo edita
PrimitivoPaleta en bruto de la marca--zp-red-500La marca
SemánticoPropósito--z-accent, --z-surface, --z-fgLa marca, al asignar primitivos
ComponenteUso concreto--z-card-bg, --z-button-radiusEl sistema; rara vez la marca

Los componentes solo leen tokens semánticos y de componente. Nunca primitivos; la auditoría de estilo lo comprueba.

Familias​

FamiliaTokens
Textofg, fg-muted, fg-subtle, fg-on-accent, canvas-fg, canvas-fg-muted
Superficiesurface, surface-2, surface-3, surface-solid, overlay, inset, line, line-strong, row-hover
Acentoaccent, accent-hover, accent-soft, accent-text, accent-solid, accent-solid-hover, accent-ring
Estadosuccess, warning, danger, info, cada uno con -soft, -text y -solid
Materialglass-bg, glass-border, glass-highlight, glass-specular, glass-shadow, glass-blur, glass-saturate, canvas, canvas-gradient
Tipografíafont-display, font-sans, font-mono, text-*, weight-*, leading-*, tracking-*
Espaciadospace-0 a space-20, con los intermedios space-1-5 (6 px) y space-2-5 (10 px)
Formaradius-xs, sm, md, lg, xl, panel, full
Elevaciónshadow-sm, md, lg
Movimientoduration-fast, normal, slow; ease-standard, out, spring
Capaslayer-sticky, overlay, menu, dialog, popover, tooltip, toast, top; y layer-below y layer-raised para el apilamiento dentro de un componente
Layoutrail-width, sidebar-width, inspector-width, header-height, shell-gap, stage-pad-x, stage-pad-y, content-max, prose-max, touch-target
Componentefocus-ring, scrim, control-height-sm, md, lg, control-radius, control-bg, control-border, control-border-hover, button-*, card-*, panel-radius, popup-*, tooltip-bg, reading-bg, code-bg

La lista completa, con su valor por marca y tema, está en tokens.json y en la página Tokens.

Qué token de color va en cada sitio​

El color de marca y los de estado tienen tres usos y un token para cada uno. Mezclarlos es la forma más frecuente de perder contraste.

UsoTokenContraste que garantiza
Relleno, borde, icono, indicadoraccent, success, warning, danger, info3:1 contra la superficie que lo rodea
Texto de color y enlacesaccent-text, success-text, warning-text, danger-text, info-text4.5:1 sobre todas las superficies y sobre su propio fondo -soft
Fondo con texto encima (botón primario, insignia sólida)accent-solid, success-solid, warning-solid, danger-solid, info-solid4.5:1 con fg-on-accent en los dos temas
Fondo tenue de un aviso o una insigniaaccent-soft, success-soft…El texto que va encima es el -text correspondiente

Los -text son el color original mezclado con fg hasta llegar al mínimo; los -solid, mezclado con negro. El anillo de foco (accent-ring, y con él focus-ring) usa accent-text, opaco: llega a 3:1 sobre cualquier superficie.

Objetivo táctil​

touch-target es el objetivo táctil mínimo. Vale 0px y pasa a 40px cuando el puntero principal es el dedo (@media (pointer: coarse)). control-height-sm y control-height-md se definen como max(30px, touch-target) y max(36px, touch-target): con ratón miden 30 y 36 px; en un teléfono, 40. Para conservar los tamaños de ratón en táctil: :root { --z-touch-target: 0px } después de tokens.css.

Marcas incluidas​

MarcaAcentoFuentesOrigen
dazlabs (por defecto)#E74327Poppins, DM Sans, JetBrains MonoManual de marca DAZLABS, sobre el material de zutool
zutool#FF6118Plus Jakarta SansTokens de zutool
zenithÍndigoInter, JetBrains MonoLa creé para el piloto local de zudocs sobre Zenith

La marca por defecto se fija en tokens/config.json. Cómo crear una: Cambiar de marca.

Temas y preferencias del sistema​

Claro y oscuro redefinen los tokens semánticos. Se elige con data-theme en <html>; sin ese atributo se sigue prefers-color-scheme.

PreferenciaQué cambia en los tokens
pointer: coarsetouch-target pasa a 40 px
prefers-contrast: morefg-muted pasa a fg, líneas y bordes de control se refuerzan, y el cristal y el degradado del fondo se vuelven opacos
forced-colors: activeSe retiran el degradado del fondo y el destello del cristal, que el sistema no fuerza

prefers-reduced-motion y prefers-reduced-transparency se atienden en las hojas de zui y zout, no en los tokens (Accesibilidad).

Salidas​

pnpm tokens genera tokens/dist/ y valida. Nadie edita dist/ a mano.

ArchivoSe importa comoPara qué
tokens.css@zuccadev-labs/zuix-tokens/tokens.cssTodas las marcas: la de por defecto en :root, las demás con data-brand
brands/<marca>.css…/css/<marca>.cssUna sola marca en :root
tailwind.css…/tailwind.cssPuente a utilidades de Tailwind 4 (@theme inline)
docusaurus.css…/docusaurus.cssMapa a las variables del tema clásico de Docusaurus
tokens.json…/tokens.jsonTodo el contrato, para herramientas y agentes
dtcg/<marca>.<tema>.tokens.json…/dtcg/<archivo>Formato Design Tokens (DTCG 2025.10), un archivo autocontenido por marca y tema
compat/<proyecto>.css…/compat/<proyecto>.cssCapa de compatibilidad: variables antiguas de un proyecto como alias de tokens (Migración)

Tailwind 4​

@import "tailwindcss";
@import "@zuccadev-labs/zuix-tokens/css/dazlabs.css";
@import "@zuccadev-labs/zuix-tokens/tailwind.css";

Cada token queda como utilidad (bg-surface, text-accent-text, bg-success-solid, rounded-panel). La variante dark: sigue al tema de los tokens: data-theme="dark" o, sin atributo, el sistema. zuix no usa Tailwind; el puente está para las aplicaciones que sí. Lo probé con Tailwind 4.3 en un proyecto mínimo, no en una aplicación completa.

Design Tokens (DTCG)​

Los archivos de dtcg/ siguen el formato del Design Tokens Community Group, versión 2025.10. Los colores van con espacio y componentes; lo que el formato no expresa (clamp(), max(), degradados, unidades em y ch) viaja con su valor CSS dentro de $extensions, bajo la clave io.github.zuccadev-labs.zuix. Los validé con @terrazzo/parser 2.10. Sirven para llevar los tokens a Figma o a otra herramienta que lea el formato; no los he importado en ninguna.

Validación​

pnpm tokens falla, con la marca, el tema y el par exactos, si:

  • a una marca le falta un token obligatorio, define uno que solo existe en un tema o tiene una referencia circular; cada marca se comprueba además contra schema/brand.schema.json;
  • un token de texto no llega a 4.5:1 sobre alguna superficie (la matriz completa texto × superficie);
  • un par que usan de verdad las hojas de zui y zout no llega a su mínimo: 4.5:1 en texto, 3:1 en iconos, indicadores y bordes de control. Los pares se leen de las propias hojas;
  • el anillo de foco o el borde de un control no llegan a 3:1 contra lo que los rodea;
  • una capa de compatibilidad deja una variable antigua sin destino.

Las superficies translúcidas se componen sobre el fondo de la aplicación, incluidos los extremos de su degradado: es una cota conservadora. Hoy son 654 comprobaciones entre las tres marcas y los dos temas, y pasan todas. Por qué lo mido así: Accesibilidad medida.

Reglas​

  • Un token que solo usa una aplicación se queda en esa aplicación.
  • No se añade un token si uno existente expresa lo mismo.
  • Texto de color con -text, fondo con texto con -solid. El color sin sufijo no lleva texto.