Tema e personalização

O tema de Tailwind é um conjunto plano de variáveis CSS. Você pode estendê-lo ou substituí-lo com um bloco @theme { … } na entrada CSS, referenciar esses valores dentro de CSS por meio das funções de tema e consultar os valores resolvidos em PHP. Não há arquivo de configuração JavaScript — o tema fica inteiramente em CSS.

O bloco @theme

Um bloco @theme declara tokens de design como propriedades personalizadas CSS. O prefixo de namespace de cada variável (--color-*, --font-*, --breakpoint-*, --spacing-*, …) indica a Tailwind quais utilidades e variantes esse token alimenta.

use TailwindPHP\tw;

$css = tw::generate('<div class="bg-brand text-brand xs:flex">', '
    @import "tailwindcss";

    @theme {
        --color-brand: #3b82f6;
        --font-heading: "Inter", sans-serif;
        --breakpoint-xs: 20rem;
        --spacing-huge: 10rem;
    }
');

Cada token registra utilidades em seu namespace. O exemplo acima disponibiliza bg-brand, text-brand, border-brand, a família font-heading, uma variante responsiva xs: e o espaçamento p-huge/m-huge — gerados apenas quando a classe aparece no seu conteúdo.

/* bg-brand resolves to the theme variable */
:root, :host {
  --color-brand: #3b82f6;
}
.bg-brand {
  background-color: var(--color-brand);
}

O token --breakpoint-xs registra diretamente a variante xs::

@media (min-width: 20rem) {
  .xs\:flex {
    display: flex;
  }
}

Namespaces comuns

Limpando um namespace

Definir um curinga de namespace como initial remove os padrões de Tailwind para esse namespace antes de adicionar seus próprios tokens. Isso permite começar com uma paleta limpa:

@theme {
    /* Drop every default color, then define only what you need */
    --color-*: initial;
    --color-brand: #3b82f6;
    --color-ink: #111827;
}

--*: initial; limpa todo o tema. Um único valor initial em uma chave sem curinga (--color-red-500: initial;) remove apenas esse token. Apenas initial é aceito como valor para um curinga -* — qualquer outro valor gera um erro.

Lendo valores do tema em CSS

theme()

A função legada theme() lê um valor usando a notação de ponto nos namespaces no estilo v3. Ela resolve o valor do token durante a compilação, então pode ser usada em qualquer lugar onde um valor é esperado — inclusive em regras personalizadas e outras declarações.

$css = tw::generate('<div class="callout">', '
    @import "tailwindcss";
    .callout { color: theme(colors.red.500); }
');

.callout {
  color: oklch(63.7% .237 25.331);
}

Os caminhos pontilhados apontam para as variáveis subjacentes (colors.red.500 → --color-red-500, fontFamily.sans → a família sem serifa). Há suporte para um modificador de opacidade: theme(colors.red.500 / 50%). É possível passar um valor alternativo como segundo argumento: theme(colors.brand, #000). Se não for possível resolver um caminho e nenhum valor alternativo for informado, a opção que o usa será descartada.

--theme()

--theme() lê uma variável do tema pelo nome da propriedade personalizada CSS e, por padrão, retorna uma referência var(), para que o valor possa ser sobrescrito em tempo de execução:

.btn { color: --theme(--color-brand); }
/* → color: var(--color-brand); */

Adicione inline para substituir a referência var() pelo valor resolvido: --theme(--color-brand inline). O segundo argumento é um valor alternativo (--theme(--color-brand, #000)), e um valor alternativo initial recebe tratamento especial — ele é inserido em referências var() aninhadas que também são resolvidas para initial. Dentro de uma regra at (@media, @container), --theme() sempre é resolvido em linha, pois var() não é válido nesses preâmbulos.

--spacing()

--spacing(n) multiplica a unidade base de espaçamento do tema (--spacing) por n:

@utility my-gap { gap: --spacing(4); }
/* → gap: calc(var(--spacing) * 4); */

Um multiplicador de 1 é resolvido para a própria variável base (--spacing(1) → var(--spacing), que também é o que p-1 emite), e 0 para um comprimento zero simples.

Esse é o mesmo cálculo usado pelos utilitários de espaçamento integrados, por isso os valores personalizados permanecem consistentes com p-4, m-4 e similares.

--alpha()

--alpha(color / opacity) aplica opacidade a uma cor usando um color-mix() no espaço de cores oklab:

@utility tint { color: --alpha(var(--color-red-500) / 50%); }

.tint {
  color: #fb2c3680;
}
@supports (color: color-mix(in lab, red, red)) {
  .tint {
    color: color-mix(in oklab, var(--color-red-500) 50%, transparent);
  }
}

O formato color-mix() continua podendo ser sobrescrito em tempo de execução; o valor alternativo estático anterior a ele, calculado a partir do valor do tema, atende aos navegadores sem suporte a color-mix(). Desative o valor alternativo com a opção polyfills de tw::compile().

Composição de opacidade e color-mix() → oklab()

Os modificadores de opacidade se combinam. Aplicar 50% a um valor que já tem 50% resulta em 25%, calculados em oklab. Quando um modificador de opacidade é resolvido com base em uma cor estática, TailwindPHP reduz a expressão color-mix(in oklab, …) a um valor oklab() concreto — a mesma conversão que lightningcss executa na cadeia de ferramentas upstream Tailwind — enquanto cores dinâmicas (aquelas que ainda estão envolvidas em var()) mantêm o formato color-mix() para que continuem podendo ser sobrescritas em tempo de execução.

Leitura de valores do tema em PHP

Três acessores retornam valores resolvidos do tema como arrays PHP. Cada um aceita uma string CSS de entrada opcional (padrão @import "tailwindcss";) e também está disponível em uma instância do compilador.

use TailwindPHP\tw;

tw::colors();
// ['red-500' => 'oklch(63.7% .237 25.331)', 'blue-500' => 'oklch(62.3% .214 259.815)', ...]

tw::breakpoints();
// ['sm' => '40rem', 'md' => '48rem', 'lg' => '64rem', 'xl' => '80rem', '2xl' => '96rem']

tw::spacing('@import "tailwindcss"; @theme { --spacing-huge: 10rem; }');
// ['huge' => '10rem']

Passe uma string CSS para consultar um tema personalizado:

tw::colors('@import "tailwindcss"; @theme { --color-brand: #3b82f6; }');
// [..., 'brand' => '#3b82f6']

tw::breakpoints('@import "tailwindcss"; @theme { --breakpoint-xs: 20rem; }');
// ['sm' => '40rem', ..., '2xl' => '96rem', 'xs' => '20rem']

TailwindCSS 4 usa um único valor base --spacing em vez de uma escala --spacing-*, então tw::spacing() retorna apenas os tokens --spacing-* personalizados que você definir. Os mesmos métodos também estão disponíveis em uma instância do compilador: $compiler->colors(), $compiler->breakpoints(), $compiler->spacing(). Consulte API para ver as assinaturas completas.

Próximas etapas

• Diretivas — @apply, @utility, @custom-variant, @layer.
• Importações — @import, módulos virtuais e Preflight.
• API — todos os acessores e métodos de inspeção.