다크 모드를 지원하려면 보통 라이트용 커스텀 프로퍼티 세트를 `:root`에, 다크용을 `:root.dark`나 `@media (prefers-color-scheme: dark)`에 각각 정의하고, 값을 쓸 때는 `var(--bg)` 하나로 참조하는 간접 구조를 만들어야 했습니다. 토큰이 많아지면 이 이중 정의가 꽤 번거로워집니다.
`light-dark(#fff, #111)`은 그 자리에서 바로 "라이트일 땐 이 값, 다크일 땐 저 값"을 적습니다. 단, 요소(또는 조상)에 `color-scheme: light dark`가 선언돼 있어야 브라우저가 어느 값을 쓸지 압니다 — 이 선언이 빠지면 항상 첫 번째(라이트) 값만 씁니다.
기본 지원은 caniuse/MDN baseline을 확인하세요. 미지원 브라우저에서는 지금까지 해오던 대로 `:root`/`.dark` 커스텀 프로퍼티 이중 정의가 대안입니다.
언제 쓰나
다크 모드 색 토큰을 선언 하나로 줄이고 싶을 때. 토큰이 적은 컴포넌트 라이브러리에 특히 잘 맞습니다.