Theming

개요

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

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

전역 설정 적용

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

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 옵션

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

/* 라이트 모드가 적용되는 경우 */
: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 토큰은 v3의 @seed-design/tailwind3-plugin 또는 v4의 @seed-design/tailwind4-theme으로 사용할 수 있습니다.

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

v3 클래스는 var(--seed-color-*)를 직접 참조합니다. v4 theme은 루트에 --color-* alias를 선언하고 utility에서 이를 참조합니다. 루트 <page>의 테마와 함께 사용하세요.

기기 모드 전환을 반영하려면 host가 변경된 theme global prop을 전달하고 앱이 루트 클래스를 갱신해야 합니다. 설정 후 실제 host에서 라이트 → 다크 → 라이트 전환을 확인하세요.

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

아래는 직접 SEED 토큰 참조 또는 Tailwind v3에 해당하는 사용법입니다. 위의 v4 제한을 함께 확인하세요.

특정 영역에만 다른 테마를 적용하고 싶을 때는 해당 요소에 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과의 비교