Theme switch

미리보기

로컬 미리보기입니다. 실제 계정, 환경, 실행 데이터에는 영향을 주지 않습니다.

사용법

라이트, 다크, 기기 설정을 버튼 하나로 차례로 고르게 하세요. 버튼은 이름과 툴팁에 지금 테마와 다음 테마를 말합니다. 스위치는 페이지의 루트 요소, 또는 범위 테마라면 target에 테마 크로스페이드와 함께 data-theme을 정하고, 선택을 data-theme-mode에 두고, persist 이름으로 기억합니다. 같은 대상의 스위치들은 저마다 대상을 다시 읽어 서로 맞춰지고, onThemeChange는 실제로 적용된 테마를 코드에 알려 줍니다. 시스템은 기기 설정에 따라 라이트나 다크로 정해지고, 설정이 바뀌면 따라갑니다. variant='group'은 설정 화면처럼 셋을 나란히 보여 주고, 이름이 들어가지 않으면 아이콘만 보입니다. AppShell 사이드바 안에서는 링크와 같은 줄("Theme: System" 같은)이 되고 접힌 레일에서는 이름이 툴팁이 되며, 그룹은 사이드바가 펼쳐 있을 때만 셋을 보여 줍니다.

• 기기 설정이 중요한 곳에서 라이트와 다크만 두지 마세요. 기본은 시스템입니다.
• 같은 때에 다른 곳에서 data-theme을 정하지 마세요. 서버가 첫 화면에 읽는 쿠키처럼 직접 가진 상태로 움직이려면 value와 onValueChange를 주세요.

크기: SizeProvider size="small" 포털까지 포함해 구성 전체의 크기를 바꿉니다. 기본 크기는 Default입니다. 크기 안내 및 비교

구성

div → Tooltip → Button(icon, aria-label) | variant='group': div → SegmentedControl(aria-label) → light, dark, system (icon + name)

키보드와 접근성

• 버튼은 지금 테마와 누르면 바뀔 테마를 이름으로 말하고, 툴팁에도 같은 내용을 보여 줍니다. Enter나 Space로 다음 테마로 바꿉니다.
• variant='group'은 segmented control입니다. Tab으로 들어가고, 화살표 키로 라이트, 다크, 시스템 사이를 옮기고, Enter나 Space로 고릅니다. 고른 것이 눌린 상태이고, 자리가 없어 숨긴 이름은 보조 기술에 남습니다.
• 테마는 크로스페이드로 바뀌고, 동작 줄이기에서는 바로 바뀝니다.

각 컨트롤에 목적을 설명하는 이름을 지정하세요. 오류 메시지를 해당 컨트롤에 연결하고, 상태를 색만으로 알리지 마세요. 자동 검사는 수동 키보드 및 보조 기술 테스트를 대신하지 않습니다.

예시 코드

공유 컴포넌트는 디자인 토큰에서 스타일을 가져옵니다. 각 예시는 자체 구성과 접근성 속성을 설정합니다. 호출하는 화면이 콜백, ref, 제품 데이터를 정의합니다.

import { ThemeSwitch, AppShell } from '@surflane/ui'

<ThemeSwitch />
<ThemeSwitch variant='group' />

// In a sidebar: a row like the links, an icon on the collapsed rail.
<AppShell.Footer>
  <ThemeSwitch />
</AppShell.Footer>

주요 API

표는 공통 래퍼의 주요 props를 나열합니다. 전체 타입은 패키지 타입 선언을 참조하세요.

관련 토큰