Dark Mode
SPI 디자인 시스템의 다크 모드 구현 및 사용 가이드입니다.
Dark Mode
SPI는 설계 단계부터 다크 모드를 네이티브로 지원합니다. .dark 클래스 기반의 테마 전환 방식을 사용하며,
프레임워크에 의존하지 않는 순수 React 기반의 ThemeProvider를 제공합니다.
ThemeProvider 설정
애플리케이션 최상단에서 ThemeProvider를 래핑하여 다크 모드 컨텍스트를 활성화합니다.
import { ThemeProvider } from "@seoulpi/ui";
function App({ children }) {
return (
<ThemeProvider defaultTheme="system" storageKey="spi-theme">
{children}
</ThemeProvider>
);
}ThemeToggle 사용
사용자가 테마를 직접 변경할 수 있도록 애니메이션이 적용된 토글 버튼을 제공합니다.
import { ThemeToggle } from "@seoulpi/ui";
function Header() {
return (
<header>
<Logo />
<ThemeToggle />
</header>
);
}시스템 연동 (System Preference)
defaultTheme="system" 설정을 통해 사용자의 OS 설정(라이트/다크)을 자동으로 감지하고 반영합니다.
OS 설정이 변경되면 실시간으로 테마가 업데이트됩니다.
커스텀 스타일 적용 시 유의사항
커스텀 컴포넌트를 개발할 때는 항상 @seoulpi/tokens에서 제공하는 시맨틱 변수를 사용하세요.
/* 추천하지 않음: 하드코딩된 색상 */
.my-card {
background-color: white;
}
/* 추천: 시맨틱 토큰 사용 */
.my-card {
background-color: var(--color-background-neutral);
color: var(--color-foreground-strong);
}