# 테마 및 사용자 지정

Tailwind의 테마는 CSS 변수의 평면 집합입니다. 입력 CSS의 `@theme { … }` 블록으로 확장하거나 대체하고, 테마 함수를 사용해 CSS 내부에서 값을 참조한 다음 PHP에서 확인된 값을 읽을 수 있습니다. JavaScript 구성 파일은 없으며 테마는 전부 CSS에 정의됩니다.

## `@theme` 블록

`@theme` 블록은 디자인 토큰을 CSS 사용자 지정 속성으로 선언합니다. 각 변수의 네임스페이스 접두사(`--color-*`, `--font-*`, `--breakpoint-*`, `--spacing-*`, …)가 해당 토큰을 사용하는 유틸리티와 변형을 Tailwind에 알려줍니다.

```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;
    }
');
```

각 토큰은 네임스페이스에 따라 유틸리티를 등록합니다. 위 예시에서는 `bg-brand`, `text-brand`, `border-brand`, `font-heading` 계열, 반응형 변형 `xs:`, `p-huge`/`m-huge` 간격을 사용할 수 있습니다. 해당 클래스가 콘텐츠에 나타날 때만 생성됩니다.

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

`--breakpoint-xs` 토큰은 `xs:` 변형을 직접 등록합니다:

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

### 일반적인 네임스페이스

| 네임스페이스 | 제공 항목 |
|-----------|-------|
| `--color-*` | `bg-*`, `text-*`, `border-*`, `fill-*`, `stroke-*`, … |
| `--font-*` | `font-*` 계열 유틸리티 |
| `--text-*` | `text-*` 글꼴 크기 유틸리티 |
| `--breakpoint-*` | 반응형 변형(`sm:`, `md:`, 사용자 지정 `xs:`) |
| `--spacing-*` | 이름이 지정된 간격 값(`p-huge`, `m-huge`) |
| `--radius-*` | `rounded-*` 유틸리티 |
| `--shadow-*` | `shadow-*` 유틸리티 |

### 네임스페이스 초기화

네임스페이스 와일드카드를 `initial`로 설정하면 사용자 토큰을 추가하기 전에 해당 네임스페이스의 Tailwind 기본값이 제거됩니다. 이를 통해 팔레트를 초기 상태에서 구성할 수 있습니다:

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

`--*: initial;`는 테마 전체를 초기화합니다. 와일드카드가 아닌 키(`--color-red-500: initial;`)에 `initial` 값을 하나 지정하면 해당 토큰만 제거됩니다. `-*` 와일드카드의 값으로는 `initial`만 허용되며, 다른 값은 오류를 발생시킵니다.

## CSS에서 테마 값 읽기

### `theme()`

이전 버전의 `theme()` 함수는 v3 스타일 네임스페이스에서 점 표기법으로 값을 읽습니다. 컴파일 시점에 토큰 값으로 확인되므로 사용자 지정 규칙이나 다른 선언을 포함해 값이 필요한 모든 곳에서 사용할 수 있습니다.

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

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

점 경로는 내부 변수에 대응합니다(`colors.red.500` → `--color-red-500`, `fontFamily.sans` → sans 계열). 불투명도 수정자도 지원합니다: `theme(colors.red.500 / 50%)`. 두 번째 인수로 대체 값을 전달할 수 있습니다: `theme(colors.brand, #000)`. 경로를 확인할 수 없고 대체 값도 지정하지 않으면 해당 경로를 사용하는 후보가 제외됩니다.

### `--theme()`

`--theme()`는 사용자 지정 속성 이름인 CSS으로 테마 변수를 읽고 기본적으로 `var()` 참조를 반환하므로 런타임에 값을 재정의할 수 있습니다:

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

`inline`를 추가하면 `var()` 참조 대신 확인된 값으로 대체합니다: `--theme(--color-brand inline)`. 두 번째 인수는 대체 값(`--theme(--color-brand, #000)`)이며, `initial` 대체 값은 특별히 처리됩니다. `initial`로 확인되는 중첩 `var()` 참조에 삽입됩니다. 앳 규칙(`@media`, `@container`) 내부에서는 해당 전치부에서 `var()`이 유효하지 않으므로 `--theme()`가 항상 인라인으로 확인됩니다.

### `--spacing()`

`--spacing(n)`는 테마의 기본 간격 단위(`--spacing`)에 `n`를 곱합니다:

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

`1` 배수는 기본 변수 자체로 확인됩니다(`--spacing(1)` → `var(--spacing)`이며, `p-1`가 출력하는 값과 같습니다). `0`는 단위가 없는 0 길이로 확인됩니다.

내장 간격 유틸리티에서 사용하는 계산과 같으므로 사용자 지정 값도 `p-4`, `m-4` 등과 일관성을 유지합니다.

### `--alpha()`

`--alpha(color / opacity)`는 oklab 색 공간에서 `color-mix()`을 사용해 색상에 불투명도를 적용합니다:

```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);
  }
}
```

`color-mix()` 형식은 런타임에 재정의할 수 있으며, 앞에 배치되는 테마 값 기반 정적 대체 값은 `color-mix()`을 지원하지 않는 브라우저를 위한 것입니다. [`tw::compile()`](https://tailwindphp.inline0.dev/ko/docs/api#twcompile)의 `polyfills` 옵션으로 대체 값을 비활성화하세요.

### 불투명도와 `color-mix()` → `oklab()` 조합

불투명도 수정자는 함께 계산됩니다. 이미 50%가 적용된 값에 50%를 적용하면 oklab에서 계산된 25%가 됩니다. 정적 색상에 불투명도 수정자를 적용하면 TailwindPHP는 `color-mix(in oklab, …)` 표현식을 구체적인 `oklab()` 값으로 변환합니다. 이는 상위 Tailwind 도구 체인에서 lightningcss가 수행하는 변환과 같습니다. `var()`로 감싼 동적 색상은 런타임에 재정의할 수 있도록 `color-mix()` 형식을 유지합니다.

## PHP에서 테마 값 읽기

세 가지 접근자는 확인된 테마 값을 PHP 배열로 반환합니다. 각 접근자는 선택적 입력 CSS 문자열(기본값 `@import "tailwindcss";`)을 받으며 [컴파일러 인스턴스](https://tailwindphp.inline0.dev/ko/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']
```

사용자 지정 테마의 값을 읽으려면 CSS 문자열을 전달하세요:

```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는 `--spacing-*` 척도가 아닌 단일 `--spacing` 기본값을 사용하므로 `tw::spacing()`는 정의한 사용자 지정 `--spacing-*` 토큰만 반환합니다. 컴파일러 인스턴스에서도 같은 메서드인 `$compiler->colors()`, `$compiler->breakpoints()`, `$compiler->spacing()`를 사용할 수 있습니다. 전체 시그니처는 [API문서](https://tailwindphp.inline0.dev/ko/docs/api)를 참고하세요.

## 다음 단계

- [지시문](https://tailwindphp.inline0.dev/ko/docs/usage/directives) — `@apply`, `@utility`, `@custom-variant`, `@layer`.
- [가져오기](https://tailwindphp.inline0.dev/ko/docs/usage/imports) — `@import`, 가상 모듈 및 Preflight.
- [API문서](https://tailwindphp.inline0.dev/ko/docs/api) — 모든 접근자 및 검사 메서드.