Theming

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

개요

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

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

전역 설정 적용

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

import { root } from "@lynx-js/react";
import { useSeedClassName } from "@seed-design/lynx-react";

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

root.render(<Root />);

useSeedClassName()은 colorMode 옵션에 따라 seed-user-color-scheme-light 또는 seed-user-color-scheme-dark 클래스를 반환합니다. lynx.__globalProps.theme 변경을 구독하므로, 시스템 테마가 바뀌면 자동으로 리렌더되어 클래스가 갱신됩니다.

getSeedClassName()은 동일한 클래스를 반환하는 순수 함수 버전입니다. 테마 변경에 반응할 필요가 없는 정적 컨텍스트에서 사용하세요. 자세한 내용은 useSeedClassName을 참고하세요.

`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 Design의 Lynx 테마 시스템은 두 종류의 클래스 이름을 사용합니다.

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

useSeedClassName()이 <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는 클래스 이름의 조합을 통해 적절한 색상 토큰을 적용합니다:

/* 라이트 모드가 적용되는 경우 */
: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 클래스로 매핑합니다.

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

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

Lynx는 현재 Tailwind CSS v3만 지원합니다. Tailwind v4는 Rsbuild에서 아직 미지원입니다. 자세한 설정은 @seed-design/tailwind3-plugin을 참고하세요.

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

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

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>` 주입	`useSeedClassName()` 훅으로 className 설정

Theming

On this page