Temas

Ajuste a aparência com alguns tokens de configuração, sobrescreva qualquer variável CSS em theme.css ou recorra aos utilitários do Tailwind para componentes personalizados.

O tema do Blume é orientado a tokens e funciona nos modos claro e escuro por padrão. Use tão pouco ou tanto quanto precisar: alguns tokens de configuração para os casos comuns, um theme.css para sobrescrever qualquer token de design ou utilitários do Tailwind para componentes personalizados.

Tokens de configuração

Os controles do dia a dia ficam em theme na sua configuração:

theme: {
  accent: "teal",   // a named preset or any CSS color
  radius: "md",     // none | sm | md | lg
  mode: "system",   // system | light | dark
  toggle: true,     // show the light/dark toggle
  fonts: {          // self-hosted Google Fonts
    display: "inter",
    body: "inter",
    mono: "ibm-plex-mono",
  },
}

Cor de destaque

A cor de destaque tinge elementos interativos e realçados — marcadores de etapa, abas ativas, selos, hovers de cartões e mais. Use uma predefinição nomeada ou qualquer cor CSS:

theme: {
  accent: "#ff0066", // hex, oklch(), rgb()… anything CSS understands
}

Predefinições nomeadas: blue (padrão), green, orange, pink, purple, red e teal. Cada predefinição tem um tom mais escuro para o modo claro e um tom mais claro para o modo escuro, para que o texto de destaque e os rótulos de botões atinjam o contraste WCAG AA (4,5:1) em ambos os modos.

Uma string se aplica a ambos os modos de cor; passe um objeto para uma cor de destaque diferente por modo.

Um valor que não é nem uma predefinição nem uma cor CSS, como "deep purple" ou um valor hex sem o #, gera o aviso BLUME_THEME_COLOR_INVALID na linha do blume.config.ts que o define, já que os navegadores ignoram os estilos que o usam. A mesma verificação cobre action, background e o seo.og.palette do cartão Open Graph. Propriedades personalizadas (var(--brand)), color-mix() e as demais funções de cor passam como estão escritas.

O texto sobre um preenchimento de destaque ou de ação, como o rótulo de um botão ou o número de uma etapa, é branco enquanto o branco atingir AA sobre essa cor, e escuro caso contrário. Uma cor de destaque clara recebe rótulos escuros sem nenhuma configuração extra. O blume audit verifica uma cor de destaque, de ação ou de fundo personalizada com o mesmo critério.

Raio

radius define o arredondamento dos cantos compartilhado por cartões, blocos de código, avisos e campos de entrada — none, sm, md (padrão) ou lg.

Modo de cor

mode define o esquema de cores inicial:

• system (padrão) — segue a preferência do sistema operacional do leitor
• light / dark — usa um esquema como padrão

Um alternador no cabeçalho permite que os leitores mudem, e a escolha deles é lembrada entre as visitas. O modo escuro é aplicado com um atributo data-theme="dark" no elemento <html>.

Para entregar um único esquema, defina toggle: false. O cabeçalho deixa de exibir o alternador, e todas as páginas são renderizadas no mode, mesmo para os leitores que escolheram o outro esquema antes de o alternador ser removido:

theme: {
  mode: "dark",
  toggle: false,
}

Com mode: "system", toggle: false segue a configuração do sistema operacional de cada leitor e não oferece nenhuma forma de sobrescrevê-la.

Fontes

fonts define os tipos de letra para três funções:

• display — títulos (h1–h6)
• body — texto do corpo, interface e prosa
• mono — blocos de código e código em linha

Os títulos recebem letter-spacing de display (-0.05em) do próprio tema, então o que você escolher para display — incluindo fontes de texto como o padrão Inter — fica correto nos tamanhos de título, sem depender do tracking embutido na fonte.

Cada uma tem como padrão uma Google Font selecionada, para que o Blume pareça intencional desde o início:

theme: {
  fonts: {
    display: "inter",         // default
    body: "inter",            // default
    mono: "ibm-plex-mono",    // default
  },
}

Defina apenas as funções que você quer alterar — as demais mantêm seus padrões:

theme: {
  fonts: { display: "geist" }, // body + mono stay Inter / IBM Plex Mono
}

As fontes são auto-hospedadas: o Blume as baixa no momento da build e as serve a partir do seu próprio site, então não há requisição em tempo de execução ao Google nem deslocamento de layout (o Astro gera automaticamente faces com métricas de fallback).

Uma string simples é um slug do Google Fonts do conjunto selecionado abaixo:

Qualquer família de qualquer provedor

Precisa de uma família que não está no conjunto selecionado — digamos, uma que cubra um sistema de escrita não latino? Passe um objeto com o nome exato da família. Ela é auto-hospedada e otimizada da mesma forma:

theme: {
  fonts: {
    display: { name: "Noto Sans JP", weights: [400, 700] },
    body: { name: "Noto Sans JP", weights: [400, 500, 700] },
  },
}

• name — o nome da família exatamente como o provedor o lista.
• provider — de onde vem a família: google (padrão), fontsource, bunny ou fontshare.
• weights — os pesos a carregar, como números ou um intervalo variável como "100..900". O padrão é [400, 500, 600, 700].
• subsets — os subconjuntos de caracteres a carregar, pelos nomes do provedor (latin, latin-ext, vietnamese, cyrillic, greek, …). O padrão é latin mais o que os idiomas configurados precisarem — veja abaixo.
• fallback — a pilha de fontes do sistema exibida enquanto a fonte carrega e para glifos ausentes: sans, serif ou mono. O padrão é mono para a função mono e sans nos demais casos.

Subconjuntos e idiomas

Google, Bunny e Fontsource dividem cada família em subconjuntos por sistema de escrita, e apenas os subconjuntos que você carrega recebem um @font-face. O Blume deriva a lista a partir do seu i18n.locales: um site com idiomas vietnamita, polonês, russo ou grego carrega vietnamese, latin-ext, cyrillic ou greek junto com latin, para que diacríticos e letras não latinas sejam renderizados na fonte escolhida em vez do fallback do sistema. Sites sem um bloco i18n, ou apenas com idiomas Latin-1, carregam somente latin. Os navegadores baixam um subconjunto apenas quando uma página usa seus caracteres, e os preloads seguem a mesma lista.

Defina subsets em uma família para sobrescrever a lista derivada — digamos, para um site de um único idioma cujo conteúdo ainda precisa de um sistema de escrita que o idioma não implica:

theme: {
  fonts: {
    body: { name: "Be Vietnam Pro", subsets: ["latin", "vietnamese"] },
  },
}

Slugs selecionados como inter seguem a lista derivada dos idiomas; use a forma de objeto para fixar subconjuntos nessas famílias também.

Arquivos de fonte locais

Para uma fonte que você possui (ou que nenhum provedor serve), aponte uma função para arquivos de fonte no seu projeto. Cada variante se torna um @font-face:

theme: {
  fonts: {
    display: {
      name: "Berkeley Mono",
      variants: [
        { src: "./fonts/BerkeleyMono-Regular.woff2", weight: 400 },
        { src: "./fonts/BerkeleyMono-Bold.woff2", weight: 700 },
      ],
    },
  },
}

Os caminhos são resolvidos a partir da raiz do projeto. weight e style (normal, italic, oblique) são opcionais — o Astro os lê do arquivo de fonte quando omitidos.

Quer voltar para a pilha de fontes do sistema? Sobrescreva os tokens --blume-font-* diretamente em theme.css.

Cores do modo escuro

accent e background seguem uma regra: uma string se aplica a ambos os modos de cor, e um objeto { light, dark } define cada modo individualmente:

theme: {
  accent: { light: "blue", dark: "teal" },
  background: {
    light: "#ffffff",
    dark: "#0a0a0a",
  },
}

Cada cor aceita uma predefinição nomeada ou qualquer cor CSS. Para background (e backgroundImage), qualquer uma das chaves pode ser omitida para sobrescrever apenas um modo — background: { dark: "#0a0a0a" } mantém o fundo claro padrão.

Cor de ação

action é uma cor de destaque secundária para chamadas para ação principais e para os utilitários action do Tailwind (bg-action, text-action). Seu padrão é o seu accent:

theme: {
  action: "#ff0066",
}

Imagem de fundo

Defina uma imagem de fundo atrás do seu conteúdo com backgroundImage — uma URL ou um caminho dentro de public/. Assim como nas cores, uma string se aplica a ambos os modos e um objeto { light, dark } define a imagem de cada modo:

theme: {
  backgroundImage: {
    light: "/bg-light.svg",
    dark: "/bg-dark.svg",
  },
}

theme.css

Coloque um theme.css na raiz do seu projeto para sobrescrever qualquer token de design. É a última camada da cascata, então ela prevalece sobre os padrões e sobre os tokens de configuração:

:root {
  --blume-accent: oklch(0.68 0.14 180);
  --blume-radius: 0.5rem;
}

:root[data-theme="dark"] {
  --blume-background: oklch(0.16 0 0);
}

Defina um token em :root para o modo claro e em :root[data-theme="dark"] para o modo escuro. Os tokens de cor têm valores escuros embutidos distintos, declarados na especificidade mais alta do seletor escuro, então uma sobrescrita apenas em :root de --blume-accent, --blume-background e companhia se aplica somente ao modo claro — declare também o bloco escuro quando ambos os modos devem mudar.

O theme.css é embutido no ponto de entrada do Tailwind do site, então diretivas do Tailwind também funcionam nele. A que vale conhecer para um monorepo é @source: o Blume analisa seu projeto em busca de classes utilitárias, e uma página que importa componentes de um pacote irmão do workspace precisa que esse pacote também seja analisado. Aponte para ele de forma relativa ao theme.css — a regra padrão do Tailwind — e o Blume leva o caminho para a folha de estilos gerada:

@source "../../packages/ui/src";

Tokens de design

Defina um token --blume-font-* com qualquer pilha de fontes para usar uma fonte fora da lista selecionada, ou para recorrer à pilha do sistema:

:root {
  --blume-font-body: ui-sans-serif, system-ui, sans-serif;
}

Utilitários do Tailwind

O tema do Blume é construído internamente com o Tailwind v4, e os arquivos .astro, .jsx, .mdx, .ts e .tsx do seu projeto também são analisados — assim você pode estilizar componentes e páginas personalizados com classes utilitárias, sem precisar configurar o Tailwind. Cada token é exposto como um utilitário, então seus componentes acompanham o tema automaticamente:

Ordem da cascata

Os estilos são resolvidos em três camadas, cada uma sobrescrevendo a anterior: