Sistema de diseño

El lenguaje de diseño con el que está hecho ranui, y el catálogo completo de los tokens que lo expresan: todas las propiedades personalizadas --ran-* globales que declara la biblioteca, con su valor en ambos temas. Los componentes leen estos tokens en vez de escribir valores a mano, así que sobrescribir uno reestiliza todo lo que lo consume.

Tres páginas responden a tres preguntas distintas, y están separadas a propósito:

Úsala cuando necesites el nombre o el valor de un token (un rol de color, un paso de espacio, un tamaño de icono, un nivel de sombra, una curva de aceleración) o quieras entender por qué las escalas tienen la forma que tienen.

El lenguaje: Geist

Los tokens de ranui se basan en Geist, el sistema de diseño de código abierto de Vercel. Cada escala de color es una escalera de trabajos fijos, uno por peldaño, no un conjunto de tonos entre los que elegir: el peldaño 200 no es «un gris un poco más oscuro», es «el fondo del hover». Una vez fijado el trabajo de un peldaño, elegir un color para un estado de interacción es una consulta, no un juicio.

ranui adopta esa escalera como sus escalas --ran-*, superpone tokens semánticos encima y trae Geist Sans / Geist Mono como tipografías por defecto.

Dos capas

Capa 1: la paleta base. Las escalas crudas de abajo. Rara vez se consumen directamente.

Capa 2: los tokens semánticos. --ran-color-* y compañía, mapeados sobre la capa 1. Consume esta capa. El modo oscuro redefine solo la capa 1, así que cada token semántico cambia a través de var() sin una sola sobreescritura oscura por componente en toda la biblioteca.

--ran-gray-1000        →  #171717 (claro)  /  #ededed (oscuro)   ← capa 1, cambia
--ran-color-text       →  var(--ran-gray-1000)                    ← capa 2, sigue
--ran-btn-color        →  var(--ran-color-text, …)                ← token de componente

Esa cadena es toda la arquitectura: cambia un peldaño base y se propaga a todas partes; cambia un token semántico y cambia un rol; cambia un token de componente y cambia un elemento.

Color

La escalera

Cada escala de tono va de 100 a 1000, y cada peldaño tiene un trabajo fijo:

Fondos

Gris — --ran-gray-100..1000

La escala que hay detrás del texto, los bordes y las superficies.

Gris alfa — --ran-gray-alpha-100..1000

Translúcida, así que se superpone a cualquier superficie: la elección correcta para un velo, un lavado de hover o un separador que debe posarse sobre contenido desconocido.

Azul — --ran-blue-100..1000

Reservado para los enlaces y el anillo de foco.

Rojo — --ran-red-100..1000

Peligro y errores.

Ámbar — --ran-amber-100..1000

Advertencias.

Verde — --ran-green-100..1000

Éxito.

Tokens semánticos de color

La capa que los componentes leen de verdad. Todo lo de aquí se resuelve a través de las escalas de arriba, así que cambia con el tema por sí solo.

--ran-color-primary-hover / -active son los dos literales de la capa semántica: avanzan hacia el fondo de la página en lugar de a lo largo de una escala, así que el modo oscuro los redefine directamente.

Qué significa cada acento

• El primario es monocromo: negro sobre blanco en claro, blanco sobre negro en oscuro (el tono de marca de Geist, <r-button type="primary">). El texto y los iconos encima usan --ran-color-primary-text, que cambia con él. No hay un token de «contraste» aparte: el primario es la acción de mayor contraste.
• El azul está reservado para los enlaces (--ran-color-link) y el anillo de foco. No es un primario alternativo.
• Verde = éxito · ámbar = advertencia · rojo = peligro. Un significado cada uno.

No existe --ran-color-error; el token es --ran-color-danger. Un var() que nombra una propiedad nunca declarada se resuelve en nada y la declaración entera se descarta en silencio, y por eso el nombre equivocado merece comprobarse contra esta tabla en vez de adivinarse.

Espacio

Los huecos entre las cosas: padding, margin, gap. Una unidad base de 4px con nueve valores, ni uno más:

El número es el múltiplo de 4px, así que la escala salta: no existe --ran-space-5. Ese es el punto: un conjunto limitado es lo que produce el ritmo de una página.

Tamaños

Las dimensiones propias de un elemento: tamaños de icono, alturas de control, controles pequeños cuadrados o rectangulares.

Es una escala aparte de la de espacio a propósito, y mezclarlas es un error que comprueba una máquina (sizing-scale). Las dos tienen rangos y progresiones distintos (una escala de espacio que dobla desde 4px produce valores incómodos para iconos y controles), y quien la use debe poder reajustar una sin perturbar la otra: que un icono crezca no debería ensanchar además cada hueco que casualmente comparta su valor en píxeles. Cuando un peldaño coincide numéricamente con uno de espacio (--ran-size-4 y --ran-space-6 son ambos 24px) es coincidencia, no un alias.

Una dimensión genuinamente irrepetible que ningún otro componente comparte (el min-width de un menú, por ejemplo) se queda como token de componente con su propio valor literal de respaldo, en vez de forzarse a un peldaño.

Tipografía

El texto se organiza por rol, y el rol fija a la vez la fuente, el tamaño, el grosor y la altura de línea:

Dos tokens existen solo para que un rol aterrice bien:

Geist limita el grosor a 600 (semibold). El énfasis viene del tamaño y del espacio, no de una tipografía más gruesa. No existe --ran-text-copy-3: el peldaño de 12px es --ran-text-label-3.

Tipografías

ranui aloja por su cuenta ambas familias (peso variable 100–900, SIL OFL 1.1), así que una sola importación las carga sin depender de ningún CDN:

import 'ranui/fonts'; // empaquetadores

<link rel="stylesheet" href="…/ranui/dist/fonts/fonts.css" />

Sin ella, los tokens recurren a las pilas de fuentes del sistema; todo sigue funcionando, solo que sin las familias de Geist.

Radio

Elevación

La sombra es un rol, no un adorno. Elige el nivel por lo que es el elemento. El modo oscuro reemplaza los tres, porque una sombra afinada para una página blanca desaparece sobre una negra.

Las capas sin borde confían solo en la sombra para separarse, así que los niveles de capa flotante llevan peso de verdad; una capa que cae al nivel elevado se ve plana y clavada a la página.

Apilamiento

Las capas flotantes se portalizan a <body>, así que necesitan un nivel explícito:

La escalera empieza en 1000 para superar el marco habitual de una página (las barras de navegación y los fondos suelen vivir en las decenas). Sobrescribe un nivel en :root, o por componente (--ran-dropdown-host-z-index, --ran-modal-root-z-index, --ran-message-z-index), nunca con !important.

Movimiento

La familia spring está destilada de muelles afinados de SwiftUI (response/damping reducidos a una bézier de un solo rebote).

Combínalas solo con propiedades de movimiento: transform, opacity, la geometría de la caja. Las propiedades de la paleta (background-color, color, border-color, box-shadow, fill, stroke) no llevan transición por defecto a propósito, porque el CSS no puede distinguir una interacción de un cambio de tema: cualquier fundido que añadas a un color se dispara también al pasar de claro a oscuro. Aun así, cada componente expone un gancho --ran-*-transition por si quieres volver a activarlo.

Foco

El anillo tiene dos capas: una interior del color del fondo y otra exterior azul, así que sigue viéndose sobre cualquier superficie, y se queda azul en vez de seguir al primario, ahora monocromo.

--ran-focus-ring-inverse-color no se redefine en modo oscuro a propósito: existe para un componente cuya propia superficie es oscura fija, sea cual sea el tema de la página (la barra de control de r-player, sobre un vídeo cualquiera), y esa superficie no cambia cuando cambia la página.

Primitivas de piel

Los pocos valores estructurales que comparten los componentes y que no son color, tamaño ni tipografía. Se mantienen al mínimo a propósito: esta capa era mucho mayor y casi toda se retiró junto con los paquetes de tema.

Qué redefine el modo oscuro

data-ran-theme="dark" en <html> (o en cualquier subárbol, véase tematización) redefine la paleta base y nada más, con tres excepciones que no pueden resolverse a través de una escala:

• toda la capa 1: cada peldaño de gris, gris alfa, azul, rojo, ámbar y verde, y los dos fondos;
• --ran-color-bg-elevated, que en oscuro apunta a --ran-gray-100 para que una tarjeta se levante de una página negra en vez de desaparecer en ella;
• --ran-color-primary-hover / -active, que son literales y no referencias a una escala;
• los tres niveles de sombra, reafinados para un fondo oscuro.

Todo lo demás (cualquier otro token semántico, cada tamaño, cada duración) se define una sola vez.

Tokens de componente

Por debajo de la capa semántica, cada componente expone sus propios ganchos, con este nombre:

--ran-{component}-{element}[-{state}]-{property}

por ejemplo --ran-btn-hover-background, --ran-select-search-active-border-width. Por defecto recurren a los tokens semánticos: var(--ran-btn-background, var(--ran-color-primary, #171717)), así que sobrescribir un token semántico llega a todos ellos, y sobrescribir uno de componente reduce el cambio a un solo elemento.

La lista completa, generada, es style-tokens-public.md en el repositorio; la API por elemento está aquí. Para saber cómo aplicarlos, véase Tematización.

Usar los tokens en tu propio CSS

.panel {
  background: var(--ran-color-bg-elevated);
  color: var(--ran-color-text);
  border: var(--ran-skin-border-width) var(--ran-skin-border-style) var(--ran-color-border);
  border-radius: var(--ran-radius-md);
  padding: var(--ran-space-4);
  box-shadow: var(--ran-shadow-elevated);
}

Tres reglas mantienen eso a salvo en oscuro:

1. Nada de hex crudo para algo que deba seguir al tema.
2. Un respaldo debe nombrar un token que cambie: var(--ran-color-text, var(--ran-gray-1000)), nunca var(--ran-color-text, #171717).
3. Un respaldo debe nombrar un token que exista, o la declaración se descarta y el elemento se queda en silencio con lo que heredó.

Todos los tokens globales que declara la biblioteca están listados en esta página, y una prueba unitaria falla si se añade uno sin documentarlo aquí. Los tokens de ámbito de componente se generan aparte, en style-tokens-public.md.