# Theming
URL: /lynx/getting-started/theming
Source: https://github.com/daangn/seed-design/blob/dev/docs/content/lynx/getting-started/theming.mdx

Lynx 환경에서 SEED의 테마 시스템을 활용하는 방법을 알아봅니다.

## 개요

SEED는 라이트 모드와 다크 모드를 지원하는 테마 시스템을 제공합니다.

웹 환경에서는 `data-*` 속성 셀렉터를 통해 테마를 제어하지만, Lynx에서는 `data-*` 속성 셀렉터를 지원하지 않기 때문에 CSS 클래스 이름을 사용합니다.
스타일시트에 선언된 CSS 커스텀 프로퍼티(변수)는 Lynx에서도 상속되므로, 루트 요소에 설정된 테마 토큰이 하위 요소에 자연스럽게 적용됩니다.

## 전역 설정 적용

`@seed-design/lynx-react`의 `getSeedClassName()` 함수를 사용하여 `<page>` 요소에 테마 클래스를 설정합니다.

```tsx
import { root } from "@lynx-js/react";
import { getSeedClassName } from "@seed-design/lynx-react";

function Root() {
  return (
    <page className={getSeedClassName({ colorMode: "system" })}>
      <App />
    </page>
  );
}

root.render(<Root />);
```

`getSeedClassName()`은 `colorMode` 옵션에 따라 `seed-user-color-scheme-light` 또는 `seed-user-color-scheme-dark` 클래스를 반환합니다.

### `colorMode` 옵션

| `colorMode` 설정 | 기기 설정  | 적용되는 테마 클래스                    |
| -------------- | ------ | ------------------------------ |
| `system` (기본값) | 라이트 모드 | `seed-user-color-scheme-light` |
| `system`       | 다크 모드  | `seed-user-color-scheme-dark`  |
| `light-only`   | (무관)   | `seed-user-color-scheme-light` |
| `dark-only`    | (무관)   | `seed-user-color-scheme-dark`  |

`system`으로 설정하면 `lynx.__globalProps.theme` 값을 읽어 기기의 다크 모드 설정을 따릅니다.

## 테마 클래스 이해하기

SEED의 Lynx 테마 시스템은 두 종류의 클래스 이름을 사용합니다.

### `seed-user-color-scheme-*` (루트 레벨 테마)

`getSeedClassName()`이 `<page>` 요소에 적용하는 클래스입니다. 현재 해석(resolve)된 테마를 나타냅니다.

- `seed-user-color-scheme-light`: 라이트 모드가 적용됨
- `seed-user-color-scheme-dark`: 다크 모드가 적용됨

### `seed-color-mode-*-only` (자식 레벨 오버라이드)

특정 요소와 그 하위 요소에 테마를 강제 적용할 때 사용하는 클래스입니다.

- `seed-color-mode-light-only`: 해당 영역을 라이트 모드로 강제
- `seed-color-mode-dark-only`: 해당 영역을 다크 모드로 강제

## 작동 원리

SEED CSS는 클래스 이름의 조합을 통해 적절한 색상 토큰을 적용합니다:

```css
/* 라이트 모드가 적용되는 경우 */
:root,
:root.seed-user-color-scheme-light,
:root.seed-color-mode-light-only,
.seed-color-mode-light-only {
  /* 라이트 모드 색상 토큰 */
}

/* 다크 모드가 적용되는 경우 */
:root.seed-user-color-scheme-dark,
:root.seed-color-mode-dark-only,
.seed-color-mode-dark-only {
  /* 다크 모드 색상 토큰 */
}
```

- `:root` 단독 셀렉터는 기본값으로 라이트 모드 토큰을 적용합니다.
- `:root.seed-user-color-scheme-*` 셀렉터는 루트 요소에 설정된 전역 테마를 처리합니다.
- `.seed-color-mode-*-only` 셀렉터는 하위 요소에서의 테마 오버라이드를 처리합니다. `:root` 접두사가 있는 셀렉터와 없는 셀렉터 모두 포함되어 있어, 루트 요소와 자식 요소 모두에서 동작합니다.

## Tailwind CSS와 함께 사용하기

SEED 토큰은 Tailwind CSS v3 유틸리티 클래스로도 사용할 수 있습니다. `@seed-design/tailwind3-plugin`이 SEED 색상 토큰을 Tailwind 클래스로 매핑합니다.

```tsx
// 테마에 따라 자동으로 색상이 변경됩니다
<view className="bg-bg-layer-default">
  <text className="text-fg-neutral">테마에 반응하는 텍스트</text>
</view>
```

Tailwind 클래스는 CSS 커스텀 프로퍼티(`var(--seed-color-*)`)를 사용하므로, 테마 클래스가 변경되면 자동으로 모든 색상이 업데이트됩니다.

<Callout type="warning">
  Lynx는 현재 Tailwind CSS v3만 지원합니다. Tailwind v4는 Rsbuild에서 아직 미지원입니다.
  자세한 설정은 [`@seed-design/tailwind3-plugin`](https://github.com/daangn/seed-design/tree/dev/packages/tailwind3-plugin)을 참고하세요.
</Callout>

## 일부 요소에만 테마 오버라이드하기

특정 영역에만 다른 테마를 적용하고 싶을 때는 해당 요소에 `seed-color-mode-light-only` 또는 `seed-color-mode-dark-only` 클래스를 추가합니다.

```tsx
function MyComponent() {
  return (
    <view>
      {/* 현재 전역 테마를 따르는 영역 */}
      <text>전역 테마가 적용됩니다</text>

      {/* 다크 모드 강제 적용 영역 */}
      <view className="seed-color-mode-dark-only">
        <text>다크 모드가 강제 적용됩니다</text>
      </view>

      {/* 라이트 모드 강제 적용 영역 */}
      <view className="seed-color-mode-light-only">
        <text>라이트 모드가 강제 적용됩니다</text>
      </view>
    </view>
  );
}
```

오버라이드된 영역 내부의 모든 하위 요소는 CSS 커스텀 프로퍼티 상속을 통해 해당 테마의 토큰을 사용하게 됩니다.

## Web과의 비교

|          | Web (React)                                                             | Lynx                                                            |
| -------- | ----------------------------------------------------------------------- | --------------------------------------------------------------- |
| 테마 제어 방식 | `data-*` 속성 셀렉터                                                         | CSS 클래스 이름                                                      |
| 전역 테마 설정 | `data-seed-color-mode` + `data-seed-user-color-scheme` 속성을 `<html>`에 적용 | `seed-user-color-scheme-*` 클래스를 `<page>`에 적용                    |
| 테마 오버라이드 | `data-seed-color-mode="light-only"` 또는 `"dark-only"` 속성                 | `seed-color-mode-light-only` 또는 `seed-color-mode-dark-only` 클래스 |
| 토큰 상속    | CSS 커스텀 프로퍼티 상속                                                         | CSS 커스텀 프로퍼티 상속 (동일)                                            |
| 테마 설정 방법 | 번들러 플러그인이 `<script>` 주입                                                 | `getSeedClassName()` 함수로 className 직접 설정                        |