Fundamentos y Tokens — WebBlocks UI

Tokens de diseño

Todos los valores (colores, tamaños, radios, sombras, espaciado) son propiedades personalizadas CSS definidas en tokens.css. Los componentes nunca usan valores fijos — siempre referencian un token. Reemplaza cualquier token para adaptar WebBlocks UI a tu marca.

Regla: Usa tokens también en tus propios componentes. Nunca fijes un color, tamaño o radio que pueda cambiar con un cambio de tema.

Superficies & texto

Token	Por defecto (claro)	Uso
--wb-bg	#f4f6fb	Fondo de página
--wb-surface	#ffffff	Tarjetas, paneles, modales
--wb-surface-2	#edf1f7	Fondos sutiles, filas de tabla
--wb-surface-3	#e2e8f2	Estados hover, divisores
--wb-text	#18212f	Texto principal
--wb-muted	#5a6a84	Texto secundario, etiquetas, marcadores
--wb-border	#d6e0ee	Todos los bordes y divisores

Colores semánticos

Token	Variantes	Uso
--wb-success	-dark · -soft	Alertas de éxito, badges, iconos
--wb-warning	-dark · -soft	Alertas de advertencia, estados de precaución
--wb-danger	-dark · -soft	Estados de error, acciones destructivas
--wb-info	-dark · -soft	Alertas informativas, sugerencias

Escala de espaciado (base 4px)

Token	Valor	Token	Valor
--wb-s1	4px	--wb-s8	32px
--wb-s2	8px	--wb-s10	40px
--wb-s3	12px	--wb-s12	48px
--wb-s4	16px	--wb-s16	64px
--wb-s5	20px	--wb-s20	80px
--wb-s6	24px	—	—

Radio de borde

Token	Valor
--wb-r-sm	5px
--wb-r-md	9px
--wb-r-lg	14px
--wb-r-xl	20px
--wb-r-full	9999px (pastilla/círculo)

Tipografía

Token	Descripción
--wb-font	Pila de fuente de cuerpo (Inter, fallbacks del sistema)
--wb-font-heading	Pila de fuente para encabezados (igual al cuerpo por defecto)
--wb-font-mono	Pila monoespaciada (Cascadia Code, Menlo, Consolas)
--wb-font-size-xs/sm/md/lg/xl	0.75 / 0.875 / 1 / 1.125 / 1.25 rem

Sombras

Token	Uso
--wb-shadow-sm	Elevación sutil (tarjetas, entradas)
--wb-shadow-md	Menús desplegables, popovers
--wb-shadow-lg	Modales, drawers
--wb-shadow-xl	Paleta de comandos, overlays elevados

Escala de z-index

Token	Valor	Uso
--wb-z-dropdown	100	Menús desplegables, popovers, tooltips
--wb-z-modal	200	Modales, drawers, diálogos de confirmación
--wb-z-toast	300	Notificaciones toast

Sobreescribir tokens

Sobreescribe cualquier token en tu propio CSS apuntando a :root o a un selector acotado:

/* Sobreescritura global */
:root {
  --wb-font: 'Geist', sans-serif;
  --wb-r-md: 12px;
}

/* Sobreescritura acotada — solo afecta a una sección */
.my-hero {
  --wb-accent: #8b5cf6;
}

Colores de acento

Establece data-accent en el elemento <html> para cambiar toda la interfaz a un esquema de color diferente. Cada acento define 12 tokens.

ocean

forest

sunset

royal

mint

amber

rose

slate-fire

Haz clic en una muestra arriba para ver el acento en esta página.

Conjunto de tokens de acento (12 tokens por acento)

Token	Uso
--wb-accent	Acento principal — fondos de botones, estados activos
--wb-accent-hover	Estado hover para elementos con color de acento
--wb-accent-active	Estado activo / presionado
--wb-accent-soft	Fondo con tinte (badges, chips)
--wb-accent-softer	Tinte muy claro (secciones de página, callouts)
--wb-accent-border	Borde con tinte de acento
--wb-accent-text	Texto de acento sobre fondo claro
--wb-accent-on	Color de texto sobre fondo de acento (siempre blanco o casi blanco)
--wb-accent-ring	Color del anillo de foco
--wb-accent-ring-rgb	Valores RGB para anillo de foco con opacidad rgba()
--wb-accent-selection	Fondo de selección de texto
--wb-accent-glow-rgb	Valores RGB para efectos de brillo

Compatibilidad con versiones anteriores: --wb-primary, --wb-primary-dark y --wb-primary-soft son alias que apuntan a sus equivalentes --wb-accent*. En código nuevo, usa siempre --wb-accent*.

Modo oscuro

El modo oscuro se controla mediante el atributo data-mode en <html>. Se admiten tres valores.

Valor	Comportamiento
light	Siempre modo claro
dark	Siempre modo oscuro
auto	Sigue la configuración del sistema `prefers-color-scheme`

Cómo funciona el modo oscuro

El modo oscuro reemplaza los tokens de superficie, texto y borde mediante un selector [data-mode="dark"] en dark.css. Todos los estilos de componentes heredan automáticamente los nuevos valores — no se necesitan variantes separadas de clase para modo oscuro.

<!-- Estático -->
<html data-mode="dark">

<!-- Cambiado por el usuario -->
<button data-wb-mode-cycle>Cambiar modo</button>

<!-- Establecido por programación -->
<script>WBTheme.setMode('dark');</script>

Persistencia en localStorage: WBTheme guarda la preferencia de modo del usuario en localStorage bajo la clave wb-mode y la restaura en la siguiente carga de página. Establece el data-mode inicial en el HTML para evitar un flash del modo incorrecto.

Presets

Los presets son paquetes con nombre que establecen múltiples ejes a la vez — radio, sombra, densidad, fuente y borde. Úsalos como punto de partida para un aspecto coherente; los ejes individuales aún pueden sobreescribir cualquier valor del preset.

Preset	Radio	Sombra	Densidad	Fuente	Borde
modern	default	default	default	modern	subtle
minimal	sharp	flat	compact	system	subtle
rounded	soft	soft	comfortable	modern	none
bold	sharp	default	default	modern	bold
editorial	sharp	flat	comfortable	editorial	medium

<!-- Aplicar preset "rounded", sobreescribir solo el acento -->
<html data-preset="rounded" data-accent="rose">

<!-- Aplicar "minimal", sobreescribir radio a soft -->
<html data-preset="minimal" data-radius="soft">

Los presets se aplican en el orden de cascada CSS antes que los atributos de eje individuales, por lo que los ejes individuales siempre tienen prioridad.

Ejes de tema

Más allá del modo oscuro y el acento, cinco ejes adicionales permiten ajustar la personalidad visual de tu interfaz.

Radio — `data-radius`

Valor	Efecto
sharp	Reduce todos los radios de borde — aspecto más estructurado y empresarial
soft	Aumenta todos los radios de borde — aspecto amigable y orientado al consumidor

Densidad — `data-density`

Valor	Efecto
compact	Reduce el relleno en botones, entradas, filas de tabla — más contenido por pantalla
comfortable	Aumenta el relleno — más espacio para respirar, mejor para táctil

Sombra — `data-shadow`

Valor	Efecto
flat	Elimina sombras — profundidad basada en bordes, limpio y minimalista
soft	Aumenta el desenfoque y opacidad de sombra — aspecto más elevado y premium

Fuente — `data-font`

Valor	Pila de fuente
system	Pila de fuente nativa del SO — no se carga ninguna fuente web
modern	Inter (CDN) — limpia y muy legible
editorial	Playfair Display (CDN) + Inter — aspecto editorial y de publicación

Borde — `data-border`

Valor	Efecto
none	Elimina bordes — superficies definidas solo por sombras
subtle	Bordes ligeros (por defecto)
medium	Bordes de peso medio
bold	Bordes gruesos — estructura visual fuerte
dashed	Bordes discontinuos — aspecto distintivo y técnico

Combinando todos los ejes

<!-- Máxima personalización sin una sola línea de CSS propio -->
<html
  data-mode="dark"
  data-accent="royal"
  data-preset="rounded"
  data-density="comfortable"
  data-font="modern"
>

Sobreescrituras de token personalizadas

Para personalizaciones específicas de marca que van más allá de los ejes incorporados, sobreescribe tokens directamente en tu propio CSS.

/* ── Fuente de marca ─────────────────────────────── */
:root {
  --wb-font:         'DM Sans', sans-serif;
  --wb-font-heading: 'DM Serif Display', serif;
}

/* ── Acento personalizado (fuera de los 8 predefinidos) ── */
:root {
  --wb-accent:           #0f766e;
  --wb-accent-hover:     #0d6e66;
  --wb-accent-active:    #0b605a;
  --wb-accent-soft:      #ccfbf1;
  --wb-accent-softer:    #f0fdf4;
  --wb-accent-border:    #5eead4;
  --wb-accent-text:      #0d6e66;
  --wb-accent-on:        #ffffff;
  --wb-accent-ring:      rgb(15 118 110);
  --wb-accent-ring-rgb:  15 118 110;
  --wb-accent-selection: #ccfbf1;
  --wb-accent-glow-rgb:  15 118 110;
}

/* ── Espaciado más ajustado para una tabla de datos densa ── */
.my-data-table {
  --wb-s3: 0.5rem;
  --wb-s4: 0.75rem;
}

Fundamentos & Tokens