# 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.

```php
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.

```css
/* 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:`:

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

### Namespaces comuns

| Namespace | Gera |
|-----------|-------|
| `--color-*` | `bg-*`, `text-*`, `border-*`, `fill-*`, `stroke-*`, … |
| `--font-*` | Utilidades da família `font-*` |
| `--text-*` | Utilidades de tamanho da fonte `text-*` |
| `--breakpoint-*` | Variantes responsivas (`sm:`, `md:`, personalizada `xs:`) |
| `--spacing-*` | Valores de espaçamento nomeados (`p-huge`, `m-huge`) |
| `--radius-*` | Utilidades `rounded-*` |
| `--shadow-*` | Utilidades `shadow-*` |

### 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:

```css
@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.

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

```css
.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:

```css
.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`:

```css
@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:

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

```css
.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()`](https://tailwindphp.inline0.dev/pt/docs/api#twcompile).

### 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](https://tailwindphp.inline0.dev/pt/docs/api).

```php
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:

```php
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](https://tailwindphp.inline0.dev/pt/docs/api) para ver as assinaturas completas.

## Próximas etapas

- [Diretivas](https://tailwindphp.inline0.dev/pt/docs/usage/directives) — `@apply`, `@utility`, `@custom-variant`, `@layer`.
- [Importações](https://tailwindphp.inline0.dev/pt/docs/usage/imports) — `@import`, módulos virtuais e Preflight.
- [API](https://tailwindphp.inline0.dev/pt/docs/api) — todos os acessores e métodos de inspeção.