Tema

Cor, raio, espessura de borda, altura de campo, fonte e movimento passam por variável CSS com o prefixo --tuc-, e todas vivem em :root. Trocar o visual é sobrescrever variável, sem recompilar nada: nenhum valor de cor, raio, borda ou altura está escrito à mão no CSS dos componentes.

Nas amostras, cada cor troca --tuc-accent-fg junto, e também --tuc-accent-text, o tom do destaque usado como cor de texto no item de menu ativo e na tag do select. Trocar só o --tuc-accent deixaria texto ilegível no botão primário.

:root {
  --tuc-accent: #4f46e5;
  --tuc-accent-hover: #4338ca;
  --tuc-accent-fg: #ffffff;       /* texto sobre o destaque */
  --tuc-accent-text: #4338ca;     /* destaque como cor de texto, no claro */
  --tuc-radius: 1rem;             /* cantos mais redondos */
  --tuc-control-height: 2.5rem;   /* campos mais altos */
}
.dark {
  --tuc-accent-text: #818cf8;     /* no escuro, um tom mais claro para ter contraste */
}

O destaque e o texto sobre ele

O destaque padrão é neutro: preto no tema claro e quase branco no escuro. A cor é do seu projeto — o pacote não impõe marca, e combina com qualquer uma até você trocar. O laranja que você vê nesta documentação é a cor do site, definida do mesmo jeito que você definiria a sua.

O destaque tem tokens separados para cada papel, porque uma cor viva raramente serve para todos. Sobre o laranja deste site o texto é branco (--tuc-accent-fg), com contraste 2,7 — escolha de marca; quem precisa de 4,5 usa #0a0a0a (7,4). E laranja vivo como cor de texto sobre fundo claro também dá 2,7, então link, item de menu ativo, tag do select, "hoje" no calendário e ícone ativo leem --tuc-accent-text, aqui #B84300 no claro (5,5 sobre branco) e o próprio #FF7501 no escuro (6,7).

/* O laranja deste site */
:root {
  --tuc-accent: #FF7501;
  --tuc-accent-hover: #FF8A2A;
  --tuc-accent-fg: #ffffff;
  --tuc-accent-text: #B84300;
  --tuc-thumb: #ffffff;
}
.dark {
  --tuc-accent: #FF7501;
  --tuc-accent-hover: #FF8A2A;
  --tuc-accent-fg: #ffffff;
  --tuc-accent-text: #FF7501;
  --tuc-thumb: #ffffff;
}

O .dark repete o destaque porque o padrão neutro muda com o tema: sem ele, o escuro voltaria ao quase branco.

Tom semântico nunca lê o destaque. Sucesso, alerta, perigo e informação têm tokens próprios, porque a marca pode ser de qualquer cor e o significado não pode mudar junto. Foi por isso que informação ganhou --tuc-info: lendo o destaque, com laranja o aviso de informação ficava igual ao de alerta, e a etiqueta "Novo" colava em "Em análise".

Tokens

A lista completa, com o valor de cada tema. A fonte da verdade é src/styles/core/tokens.css; o llms.txt traz a mesma lista, gerada do código.

Superfície e texto

Destaque

Tons semânticos

Tom de texto e preenchimento sólido são tokens diferentes de propósito. O --tuc-danger é mais claro no escuro para ter contraste sobre fundo escuro — e um botão pintado com ele ficaria pastel com texto branco em cima. O --tuc-danger-fill é o mesmo nos dois temas.

Forma e tamanho

Profundidade e movimento

Entrada e saída usam curvas diferentes de propósito: usar a mesma curva nos dois faz a saída parecer preguiçosa.

Tema escuro

O escuro segue a classe .dark no <html>, a convenção do Tailwind e do admin moderno do Django. data-theme="dark" também vale.

<html class="dark">
<html data-theme="dark">

Para seguir o sistema operacional, marque a raiz com data-tuc-theme="auto". É opt-in de propósito: seguir o sistema por padrão fazia o componente escurecer sozinho numa página clara. Quem manda no tema é o projeto, e não o sistema operacional.

<html data-tuc-theme="auto">

O escuro também põe color-scheme: dark, que faz o navegador desenhar barra de rolagem e campo nativo em tom escuro — só dentro dos componentes, para não impor o esquema de cores à página inteira.

Escopo por contêiner

Como são variáveis, o escopo é seu: em :root valem para a página inteira, e declaradas num contêiner valem só ali dentro. É o jeito de ter um painel com cor própria, ou uma faixa escura numa página clara.

.panel-green {
  --tuc-accent: #0f766e;
  --tuc-accent-hover: #115e59;
  --tuc-accent-fg: #ffffff;
  --tuc-accent-text: #0f766e;
  --tuc-accent-soft: color-mix(in oklab, var(--tuc-accent) 12%, transparent);
  --tuc-accent-ring: color-mix(in oklab, var(--tuc-accent) 35%, transparent);
}
.dark .panel-green {
  --tuc-accent-text: #2dd4bf;     /* texto de destaque legível sobre fundo escuro */
}

/* .dark num contêiner: os tons mudam, e o fundo suave deles precisa ser refeito ali */
.band.dark {
  background: var(--tuc-bg);
  --tuc-success-soft: color-mix(in oklab, var(--tuc-success) 12%, transparent);
  --tuc-warning-soft: color-mix(in oklab, var(--tuc-warning) 14%, transparent);
  --tuc-danger-soft: color-mix(in oklab, var(--tuc-danger) 12%, transparent);
  --tuc-info-soft: color-mix(in oklab, var(--tuc-info) 12%, transparent);
}

Painel que abre fora do contêiner — calendário, lista do select, menu, toast — é inserido no fim do <body> e não herda as variáveis dele. Para esses, declare o tema em :root, ou use appendTo onde o componente oferece.

Layout compacto

Abaixo de 40rem (640px) o layout fica compacto. O mesmo ponto de corte vale para o CSS e para o JavaScript do date picker, e é por largura — não por pointer: coarse —, porque um notebook com tela de toque não deveria receber comportamento de celular.

Se o seu projeto troca de layout em outro ponto, o compacto da biblioteca não acompanha — ele é fixo em 40rem. Os seus campos devem adotar os mesmos 16px no celular pelo mesmo motivo; é o padrão text-base md:text-sm do shadcn.