Guia

Tokens

Cores, raios, sombras e tipografia expostos por CSS variables.

CSS variables

Os temas viram variáveis CSS no documentElement. Use esses tokens em CSS próprio quando quiser que extensões do app acompanhem o tema atual.

background: var(--color-background);
color: var(--color-foreground);
border-color: var(--color-border);
border-radius: var(--radius-md);
box-shadow: var(--shadow-md);
font-family: var(--font-family);
padding: var(--space-lg);
z-index: var(--z-dropdown);
transition: opacity var(--motion-duration-fast) var(--motion-ease-standard);

Cores

Cada chave de ThemeConfig.colors vira --color-* em kebab-case. Tokens com Foreground devem ser usados sobre o token base correspondente.

--color-background
--color-foreground
--color-muted
--color-muted-foreground
--color-card
--color-card-foreground
--color-popover
--color-popover-foreground
--color-primary
--color-primary-foreground
--color-secondary
--color-secondary-foreground
--color-accent
--color-accent-foreground
--color-success
--color-success-foreground
--color-warning
--color-warning-foreground
--color-danger
--color-danger-foreground
--color-info
--color-info-foreground
--color-border
--color-input
--color-ring
--color-selection
--color-selection-foreground
--color-overlay

Tipografia, raios e sombras

A tipografia expõe família principal, família monoespaçada, tamanho base e escala. Raios e sombras mantêm a escala já existente.

--font-family
--font-mono
--font-base
--font-scale

--radius-xs
--radius-sm
--radius-md
--radius-lg
--radius-xl
--radius-full

--shadow-xs
--shadow-sm
--shadow-md
--shadow-lg
--shadow-xl

Espaço e breakpoints

A escala de espaço padroniza gaps, paddings e offsets. Breakpoints ficam disponíveis como referência para CSS customizado e documentação de layout.

--space-none
--space-xs
--space-sm
--space-md
--space-lg
--space-xl
--space-2xl
--space-3xl

--breakpoint-sm
--breakpoint-md
--breakpoint-lg
--breakpoint-xl
--breakpoint-2xl

Z-index, motion e camadas

Use z-index para empilhar overlays de forma previsível, motion para durações/easing e layers para superfícies sem amarrar CSS customizado diretamente às cores base. O tema cm-aurora usa esses grupos para criar profundidade tonal e transições mais expressivas.

--z-base
--z-docked
--z-dropdown
--z-sticky
--z-overlay
--z-modal
--z-toast
--z-tooltip

--motion-duration-fast
--motion-duration-base
--motion-duration-slow
--motion-ease-standard
--motion-ease-emphasized

--layer-base
--layer-surface
--layer-elevated
--layer-floating
--layer-overlay

Densidade

A densidade organiza altura de controles, padding, gap e tamanho de ícones para modos compact, default e comfortable. Os componentes continuam usando os padrões atuais, e o app pode adotar esses tokens gradualmente.

--density-compact-control-height
--density-compact-control-padding-x
--density-compact-control-padding-y
--density-compact-gap
--density-compact-icon-size

--density-default-control-height
--density-default-control-padding-x
--density-default-control-padding-y
--density-default-gap
--density-default-icon-size

--density-comfortable-control-height
--density-comfortable-control-padding-x
--density-comfortable-control-padding-y
--density-comfortable-gap
--density-comfortable-icon-size

Relação com tema customizado

Ao criar um ThemeConfig próprio, preencha as chaves obrigatórias e sobrescreva os novos grupos apenas quando fizer sentido. O helper themeToCSSVars completa tokens opcionais com defaults e converte camelCase para kebab-case, então mutedForeground vira --color-muted-foreground.

import { themeToCSSVars, type ThemeConfig } from "cosmemilton-ui";

const vars = themeToCSSVars(myTheme);
// vars["--color-primary"]
// vars["--radius-md"]
// vars["--font-family"]
// vars["--space-lg"]
// vars["--motion-duration-fast"]

Stylesheet público

Importe o CSS distribuído pela biblioteca uma vez no app. A aplicação consumidora não precisa configurar geração de classes para os componentes.

import "cosmemilton-ui/styles.css";