Theming

SEED Design의 테마 시스템을 이해하고 활용하는 방법을 알아봅니다.

개요

SEED Design은 라이트 모드와 다크 모드를 지원하는 테마 시스템을 제공합니다. 테마는 HTML 요소의 data-seed-color-mode와 data-seed-user-color-scheme 속성을 통해 제어됩니다.

두 속성의 역할과 차이점을 이해하고, 전역 테마 설정 방법과 특정 영역에만 테마를 오버라이딩하는 방법을 알아봅니다.

테마 속성 이해하기

SEED Design의 테마 시스템은 두 가지 data-* 속성을 사용합니다.

`data-seed-color-mode`

애플리케이션의 테마 정책을 설정하는 속성입니다. 세 가지 값을 가질 수 있습니다.

system: 사용자의 시스템 설정에 따라 자동으로 라이트/다크 모드를 전환합니다.
light-only: 항상 라이트 모드로 고정합니다.
dark-only: 항상 다크 모드로 고정합니다.

<!-- 시스템 설정 따르기 -->
<html data-seed-color-mode="system">

<!-- 라이트 모드로 고정 -->
<html data-seed-color-mode="light-only">

<!-- 다크 모드로 고정 -->
<html data-seed-color-mode="dark-only">

`data-seed-user-color-scheme`

사용자 기기의 실제 컬러 스킴을 나타내는 속성입니다. 두 가지 값을 가집니다.

light: 사용자의 시스템이 라이트 모드로 설정되어 있음
dark: 사용자의 시스템이 다크 모드로 설정되어 있음

이 값은 data-seed-color-mode="system"일 때만 의미를 가지며, prefers-color-scheme 미디어 쿼리를 통해 자동으로 업데이트됩니다.

<!-- 시스템 설정을 따르도록 설정했으며, 현재 사용자는 라이트 모드를 사용 중 -->
<html
  data-seed-color-mode="system"
  data-seed-user-color-scheme="light"
>

작동 원리

SEED CSS는 두 속성의 조합을 통해 적절한 색상 토큰을 적용합니다:

/* 라이트 모드가 적용되는 경우 */
:root,
:root[data-seed-color-mode="system"][data-seed-user-color-scheme="light"],
:root[data-seed-color-mode="light-only"],
:root [data-seed-color-mode="light-only"] {
  /* 라이트 모드 색상 토큰 */
}

/* 다크 모드가 적용되는 경우 */
:root[data-seed-color-mode="system"][data-seed-user-color-scheme="dark"],
:root[data-seed-color-mode="dark-only"],
:root [data-seed-color-mode="dark-only"] {
  /* 다크 모드 색상 토큰 */
}

전역 테마 적용하기

애플리케이션 전체에 테마를 적용하는 방법은 Installation 문서를 참고하세요.

번들러 플러그인을 사용하거나, HTML에 직접 속성과 스크립트를 추가하는 방법을 확인할 수 있습니다.

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

특정 영역이나 컴포넌트에만 다른 테마를 적용하고 싶을 때는 해당 요소에 data-seed-color-mode에 light-only, dark-only 또는 system 값을 설정합니다.

라이트 모드

다크 모드

import { ActionButton } from "seed-design/ui/action-button";
import { actionButtonVariantMap } from "@seed-design/css/recipes/action-button";
import { Text, VStack } from "@seed-design/react";

function Demo() {
  return (
    <>
      {actionButtonVariantMap.variant.map((variant) => (
        <ActionButton key={variant} variant={variant}>
          {variant}
        </ActionButton>
      ))}
    </>
  );
}

export default function ThemingColorModeOverride() {
  return (
    <div className="grid grid-cols-2 size-full">
      <VStack
        data-seed-color-mode="light-only"
        bg="bg.layerDefault"
        alignItems="center"
        justify="center"
        gap="spacingY.componentDefault"
        p="x6"
      >
        <Text color="fg.neutral" textStyle="t4Bold">
          라이트 모드
        </Text>
        <Demo />
      </VStack>
      <VStack
        data-seed-color-mode="dark-only"
        bg="bg.layerDefault"
        alignItems="center"
        justify="center"
        gap="spacingY.componentDefault"
        p="x6"
      >
        <Text color="fg.neutral" textStyle="t4Bold">
          다크 모드
        </Text>
        <Demo />
      </VStack>
    </div>
  );
}