Design system

A linguagem de design com que o ranui é feito, e o catálogo completo dos tokens que a expressam: toda propriedade personalizada --ran-* global que a biblioteca declara, com o valor dela nos dois temas. Os componentes leem esses tokens em vez de escrever valores na mão, então sobrescrever um deles reestiliza tudo que o consome.

Quatro páginas respondem a quatro perguntas diferentes, e são separadas de propósito:

Use quando precisar do nome ou do valor de um token (um papel de cor, um passo de espaço, um tamanho de ícone, um nível de sombra, uma curva de aceleração) ou quiser entender por que as escalas têm o formato que têm.

A linguagem: Geist

Os tokens do ranui se baseiam no Geist, o design system de código aberto da Vercel. Toda escala de cor é uma escada de funções fixas, uma por degrau, não um conjunto de tons para escolher: o degrau 200 não é "um cinza um pouco mais escuro", é "o fundo do hover". Fixada a função de um degrau, escolher a cor de um estado de interação vira uma consulta, não um julgamento.

O ranui adota essa escada como as escalas --ran-* dele, põe tokens semânticos por cima e traz Geist Sans / Geist Mono como tipografias padrão.

Duas camadas

Camada 1: a paleta base. As escalas cruas abaixo. Raramente consumidas direto.

Camada 2: os tokens semânticos. --ran-color-* e companhia, mapeados sobre a camada 1. Consuma esta camada. O modo escuro redefine só a camada 1, então todo token semântico vira pelo var() sem nenhuma sobrescrita escura por componente em lugar algum da biblioteca.

--ran-gray-1000        →  #171717 (claro)  /  #ededed (escuro)   ← camada 1, vira
--ran-color-text       →  var(--ran-gray-1000)                    ← camada 2, acompanha
--ran-btn-color        →  var(--ran-color-text, …)                ← token de componente

Essa corrente é a arquitetura inteira: mude um degrau base e ele se propaga por toda parte; mude um token semântico e muda um papel; mude um token de componente e muda um elemento.

Cor

A escada

Toda escala de matiz vai de 100 a 1000, e cada degrau tem uma função fixa:

Fundos

Cinza — --ran-gray-100..1000

A escala que está por trás do texto, das bordas e das superfícies.

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

Translúcida, então se sobrepõe a qualquer superfície: a escolha certa para um véu, uma lavagem de hover ou um separador que precisa pousar sobre conteúdo desconhecido.

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

Reservado para os links e o anel de foco.

Vermelho — --ran-red-100..1000

Perigo e erros.

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

Avisos.

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

Sucesso.

Tokens semânticos de cor

A camada que os componentes de fato leem. Tudo aqui se resolve pelas escalas de cima, então vira com o tema sozinho.

--ran-color-primary-hover / -active são os dois literais da camada semântica: eles caminham em direção ao fundo da página em vez de ao longo de uma escala, então o modo escuro os redefine direto.

O que cada acento significa

• O primário é monocromático: preto no branco no claro, branco no preto no escuro (o tom de marca do Geist, <r-button type="primary">). O texto e os ícones em cima usam --ran-color-primary-text, que vira junto. Não há um token de "contraste" separado: o primário é a ação de maior contraste.
• O azul é reservado para os links (--ran-color-link) e o anel de foco. Não é um primário alternativo.
• Verde = sucesso · âmbar = aviso · vermelho = perigo. Um significado para cada.

Não existe --ran-color-error; o token é --ran-color-danger. Um var() que nomeia uma propriedade nunca declarada não resolve em nada e a declaração inteira é descartada em silêncio — por isso o nome errado merece ser conferido nesta tabela em vez de adivinhado.

Espaço

Os vãos entre as coisas: padding, margin, gap. Uma unidade base de 4px com nove valores, nem um a mais:

O número é o múltiplo de 4px, então a escala pula: não existe --ran-space-5. É esse o ponto: um conjunto limitado é o que produz o ritmo de uma página.

Tamanhos

As dimensões do próprio elemento: tamanhos de ícone, alturas de controle, controles pequenos quadrados ou retangulares.

Esta é uma escala separada da de espaço de propósito, e misturá-las é um erro conferido por máquina (sizing-scale). As duas têm faixas e progressões diferentes (uma escala de espaço que dobra a partir de 4px produz valores esquisitos para ícones e controles), e quem usa precisa poder reajustar uma sem perturbar a outra: um ícone ficar maior não deveria também alargar todo vão que por acaso divida o mesmo valor em pixels. Quando um degrau coincide numericamente com um de espaço (--ran-size-4 e --ran-space-6 são ambos 24px), é coincidência, não apelido.

Uma dimensão genuinamente única que nenhum outro componente compartilha (o min-width de um menu, digamos) continua sendo um token de componente comum, com o próprio valor reserva literal, em vez de ser forçada num degrau.

Tipografia

O texto é organizado por papel, e o papel fixa de uma vez a fonte, o tamanho, o peso e a altura de linha:

Dois tokens existem só para um papel pousar direito:

O Geist limita o peso em 600 (semibold). A ênfase vem do tamanho e do espaço, não de uma tipografia mais pesada. Não existe --ran-text-copy-3: o degrau de 12px é --ran-text-label-3.

Fontes

O ranui hospeda as duas famílias por conta própria (peso variável 100–900, SIL OFL 1.1), então uma única importação as carrega sem depender de CDN:

import 'ranui/fonts'; // empacotadores

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

Sem ela, os tokens recaem nas pilhas de fontes do sistema; tudo continua funcionando, só que sem as famílias do Geist.

Raio

Elevação

A sombra é um papel, não enfeite. Escolha o nível pelo que o elemento é. O modo escuro substitui os três, porque uma sombra afinada para uma página branca some numa preta.

Camadas sem borda contam só com a sombra para se separar, então os níveis de camada flutuante carregam peso de verdade; uma camada que cai no nível elevado parece plana e pregada à página.

Empilhamento

Camadas flutuantes são portalizadas para o <body>, então precisam de um nível explícito:

A escada começa em 1000 para passar por cima da moldura comum de uma página (barras de navegação e fundos costumam viver nas dezenas). Sobrescreva um nível no :root, ou por componente (--ran-dropdown-host-z-index, --ran-modal-root-z-index, --ran-message-z-index), nunca com !important.

Movimento

A família spring é destilada de molas afinadas do SwiftUI (response/damping reduzidos a uma bézier de uma só ultrapassagem).

Combine-as só com propriedades de movimento: transform, opacity, a geometria da caixa. As propriedades da paleta (background-color, color, border-color, box-shadow, fill, stroke) de propósito não trazem transição padrão, porque o CSS não distingue uma interação de uma troca de tema: qualquer desvanecimento que você acrescente a uma cor também dispara quando o claro vira escuro. Mesmo assim, todo componente expõe um gancho --ran-*-transition caso você queira ligar de volta.

Foco

O anel tem duas camadas: uma interna da cor do fundo e uma externa azul, então ele continua visível sobre qualquer superfície, e continua azul em vez de acompanhar o primário, agora monocromático.

--ran-focus-ring-inverse-color de propósito não é redefinido no modo escuro: ele existe para um componente cuja própria superfície é escura fixa, seja qual for o tema da página (a barra de controle do r-player, sobre um vídeo qualquer), e essa superfície não muda quando a página muda.

Primitivas de pele

Os poucos valores estruturais que os componentes compartilham e que não são cor, tamanho nem tipografia. Mantidos no mínimo de propósito: esta camada já foi bem maior e quase tudo dela saiu junto com os pacotes de tema.

O que o modo escuro redefine

data-ran-theme="dark" no <html> (ou em qualquer subárvore, veja tematização) redefine a paleta base e nada mais, com três exceções que não conseguem se resolver por uma escala:

• a camada 1 inteira: cada degrau de cinza, cinza alfa, azul, vermelho, âmbar e verde, e os dois fundos;
• --ran-color-bg-elevated, que no escuro aponta para --ran-gray-100 para um cartão se levantar de uma página preta em vez de sumir nela;
• --ran-color-primary-hover / -active, que são literais e não referências a uma escala;
• os três níveis de sombra, reafinados para um fundo escuro.

Todo o resto (qualquer outro token semântico, cada tamanho, cada duração) é definido uma única vez.

Tokens de componente

Abaixo da camada semântica, todo componente expõe os próprios ganchos, nomeados assim:

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

por exemplo --ran-btn-hover-background, --ran-select-search-active-border-width. Por padrão eles recaem nos tokens semânticos: var(--ran-btn-background, var(--ran-color-primary, #171717)), então sobrescrever um token semântico alcança todos eles, e sobrescrever um de componente estreita a mudança para um elemento só.

A lista completa, gerada, é o style-tokens-public.md no repositório; a API por elemento está aqui. Para saber como aplicá-los, veja Tematização.

Usar os tokens no seu próprio 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);
}

Três regras mantêm isso seguro no escuro:

1. Nada de hexadecimal cru para algo que deva acompanhar o tema.
2. Um valor reserva precisa nomear um token que vire: var(--ran-color-text, var(--ran-gray-1000)), nunca var(--ran-color-text, #171717).
3. Um valor reserva precisa nomear um token que exista, ou a declaração é descartada e o elemento fica em silêncio com o que herdou.

Todo token global que a biblioteca declara está listado nesta página, e um teste unitário falha se algum for acrescentado sem ser documentado aqui. Os tokens de escopo de componente são gerados à parte, no style-tokens-public.md.