시스템 색 구성표 감지

prefers-color-scheme CSS 미디어 쿼리는 사용자가 운영 체제에서 어두운 색상 테마 또는 밝은 색상 테마를 사용하도록 설정했는지 감지합니다. dark와 light 두 값을 받습니다. 이 설정은 브라우저가 아니라 OS 수준의 시스템 설정에서 지정됩니다.

@media (prefers-color-scheme: dark) { ... }를 사용하면 CSS만으로 어두운 스타일을 적용할 수 있습니다. 이 블록 안에서 색상, 배경, 테두리를 어두운 팔레트에 맞게 재정의합니다. 이 방식은 JavaScript가 필요하지 않으며 React가 마운트되기 전에도 작동합니다.

JavaScript에서 window.matchMedia('(prefers-color-scheme: dark)')는 MediaQueryList 객체를 반환합니다. 이를 사용하면 React 훅이나 이벤트 핸들러 안에서 현재 시스템 설정을 프로그래밍 방식으로 읽을 수 있습니다. 이는 CSS 미디어 쿼리와 JS 로직을 연결하는 다리입니다.

MediaQueryList 객체에는 불리언을 반환하는 matches 속성이 있습니다. matches가 true이면 시스템이 다크 모드이고, false이면 라이트 모드입니다. 일반적으로 마운트될 때 한 번 읽어 테마 상태를 초기화합니다.

사용자는 언제든지 OS 색상 구성을 변경할 수 있습니다. 동적으로 대응하려면 mediaQuery.addEventListener('change', handler)를 호출하세요. 이때 handler는 업데이트된 MediaQueryListEvent를 받습니다. 이벤트 객체에도 새로운 설정을 나타내는 matches 불리언이 있습니다.

깔끔한 방법은 useSyncExternalStore를 사용하여 사용자 지정 훅을 만드는 것입니다. 이 훅은 mediaQuery.addEventListener를 구독하고 mediaQuery.matches를 반환하는 스냅샷 함수를 제공합니다. 따라서 수동으로 상태를 관리하지 않아도 외부 브라우저 API와 훅의 상태를 동기화할 수 있습니다.

컴포넌트가 마운트 해제될 때 메모리 누수를 방지하려면 이벤트 리스너를 제거해야 합니다. useEffect 정리 함수에서 mediaQuery.removeEventListener('change', handler)를 호출하세요. useSyncExternalStore를 사용할 때는 subscribe 함수가 동일한 작업을 수행하는 구독 해제 함수를 반환해야 합니다.

시스템 설정은 OS가 보고하는 값입니다. 하지만 사용자는 앱 테마를 독립적으로 재정의하려는 경우가 많습니다. 예를 들어 OS가 다크 모드여도 앱은 라이트 모드로 유지할 수 있습니다. 아키텍처에서 시스템 기본값과 localStorage에 저장된 명시적인 사용자 재정의를 구분해야 합니다.

Chrome DevTools를 사용하면 OS 설정을 변경하지 않고도 색상 구성 설정을 에뮬레이션할 수 있습니다. DevTools를 열고 Rendering 탭으로 이동한 다음 "Emulate CSS media feature prefers-color-scheme" 드롭다운을 찾으세요. 개발 중 두 테마를 빠르게 테스트할 때 매우 유용합니다.

훌륭한 다크 모드 구현은 시스템 설정을 기본 시작점으로 읽어 즉시 적용합니다. 이는 사용자의 접근성 설정을 존중한다는 의미입니다. 사용자가 앱에서 명시적으로 테마를 전환한 후에만 다른 재정의 값을 저장하고 사용해야 합니다.

서버에서는 window.matchMedia가 존재하지 않습니다. 서버에서 렌더링하는 경우 matchMedia를 호출하기 전에 typeof window !== 'undefined'로 확인하세요. SSR 앱에서는 하이드레이션 불일치를 방지하기 위해 대신 쿠키나 HTTP 헤더에서 사용자 설정을 읽으세요.

MediaQueryList 객체의 어떤 속성으로 미디어 쿼리가 현재 일치하는지 알 수 있나요?

prefers-color-scheme 미디어 쿼리는 CSS와 JavaScript 모두에서 OS 색상 설정을 제공합니다. window.matchMedia를 사용하여 변경 사항을 읽고 감지하며, 이벤트 리스너는 항상 정리하고 시스템 기본값과 사용자 재정의를 구분하세요. Chrome DevTools 에뮬레이션을 사용하면 두 테마를 더 빠르게 테스트할 수 있습니다.