E-4: Tailwind 다크모드 — 중단점 토큰과 dark:

안녕하세요, 홍순구입니다. 지난 시간에 유틸리티 앞에 조건을 붙이는 법을 배웠죠. 잠겼을 때, 마우스를 올렸을 때, 키보드로 왔을 때, 화면이 넓을 때까지 배웠는데, 마지막에 두 가지를 남겨뒀습니다.

첫째, 화면 크기의 기준으로 lg를 썼는데 그 1024px 은 Tailwind가 정해준 숫자였어요. 우리 화면에 맞는 선을 우리가 정하려면 어떻게 할까요.

둘째, 조건들이 출력되는 순서를 그리면서 제가 하나를 비워뒀는데, 모든 조건보다 뒤에 오는 것이 하나 더 있다고요.

오늘 둘 다 채우는데, 두 번째 것이 오늘의 본론입니다. 화면이 어두울 때요.

 오늘의 여정

 Step 1     두 열로 갈리는 폭을 우리가 정한다
    │
 Step 2     그런데 이 토큰만 :root 에 없다
    │
 Step 3     조건이 화면 밖에 있을 때 — dark:
    │
 Step 4     다크 값을 어디에 둘까 ① 유틸리티마다 붙이기
    │
 Step 5     다크 값을 어디에 둘까 ② 이름은 그대로, 값만
    │
 Step 6     다크 값은 눈대중으로 고르지 않는다
    │
 Step 7     값만 갈아끼워서 안 되는 곳
    ▼
 className 을 한 글자도 안 고치고 화면 전체가 어두워진다

💡 오늘 수업의 핵심 — "같은 이름에 다른 값을 담으면, 유틸리티는 그대로 두고 화면 전체가 바뀐다"

bg-surface는 var(--color-surface)를 보고 있습니다. 그러니 그 이름이 가리키는 값만 어두울 때 갈아끼우면, bg-surface라고 적힌 여덟 곳이 한꺼번에 따라옵니다.

🎯 학습 목표

• 중단점을 --breakpoint-* 토큰으로 직접 정하고, 그 숫자가 어디서 나왔는지 설명할 수 있다
• 중단점 토큰만 :root에 안 나타나는 이유를 미디어 쿼리의 성질로 설명할 수 있다
• dark: 유틸리티를 컴포넌트마다 붙이는 방법과 토큰 값을 한 곳에서 재정의하는 방법을 견주어 고를 수 있다
• 다크 값을 대비로 계산해 고르고, 값 교체만으로는 안 되는 곳을 찾아낼 수 있다

Step 1: "두 열로 갈리는 폭을 우리가 정한다"

지난 시간에 피드를 두 열로 만들면서 lg:를 썼는데, 코드를 다시 볼게요.

// apps/web-spa/src/App.tsx
<main className="mx-auto max-w-[470px] py-4 sm:px-4 lg:max-w-[964px]">

lg는 1024px 인데, 왜 하필 1024일까요. 우리 피드가 1024에서 두 열이 되어야 할 이유가 있었나요.

없습니다. Tailwind가 미리 정해둔 다섯 개 중에 우리 상황에 제일 가까운 것을 고른 것뿐이어서, 오늘은 이 숫자를 우리가 계산해서 정해봅시다.

필요한 폭을 거꾸로 계산해봅시다

두 열이 들어가려면 무엇이 필요한지 세어보면 됩니다. 카드 한 장이 470px 이고, 두 장 사이에 24px 간격이 있고, 바깥 통에 좌우 16px 씩 여백이 있어요.

 카드 470  +  간격 24  +  카드 470        = 964   ← 통 안쪽에 필요한 폭
 여백 16   +      964            + 여백 16 = 996   ← 통 전체에 필요한 폭

996px 입니다. lg의 1024보다 28px 이른데, 그만큼은 두 열이 들어갈 수 있는데도 한 열로 버티고 있었던 겁니다.

통의 폭도 함께 손봐야 합니다

여기서 짚고 갈 것이 있어요. 지난 시간에 통의 상한을 964px 로 뒀는데, 그때 카드 폭을 재보니 470이 아니라 454px 이었습니다.

지난 시간에도 이 값을 확인하고 넘어갔죠. 964에서 좌우 여백 32와 간격 24를 빼고 둘로 나눈 값이라고요. 그 계산은 맞지만, 그때는 964라는 숫자를 먼저 두고 카드가 얼마가 되는지 확인하는 방향이었어요. 오늘은 반대로, 카드를 470으로 두고 통이 얼마여야 하는지를 구합니다.

차이가 생기는 이유는 main에 붙은 sm:px-4입니다. Preflight가 모든 요소를 border-box로 만들어 두기 때문에, max-w로 정한 964 안에 좌우 여백 16씩이 포함되니까, 안쪽에 남는 폭은 932이고 카드는 (932 − 24) ÷ 2 = 454가 됩니다.

 max-w-[964px] 일 때
   통 964  =  여백 16 + 안쪽 932 + 여백 16
   안쪽 932 =  카드 454 + 간격 24 + 카드 454     ← 470 이 아니다

 max-w-[996px] 일 때
   통 996  =  여백 16 + 안쪽 964 + 여백 16
   안쪽 964 =  카드 470 + 간격 24 + 카드 470     ← 의도대로

우리가 카드 폭을 470으로 잡아 뒀으니 두 열일 때도 470이어야 자연스럽죠. 통도 996으로 함께 올립니다.

이름을 주고 씁니다

지난 시간에 색에 이름을 줬던 것과 똑같이 합니다. 중단점도 @theme 안에서 이름을 얻어요.

/* apps/web-spa/src/styles/globals.css */
@theme {
  /* 카드 470 두 장 + 사이 24 + 통의 좌우 여백 32 = 996px 부터 두 열이 들어간다 */
  --breakpoint-2col: 62.25rem;
}

--breakpoint- 뒤에 붙인 이름이 그대로 변형 이름이 되고, 이제 2col:을 쓸 수 있어요.

// apps/web-spa/src/App.tsx
<main className="mx-auto max-w-[470px] py-4 sm:px-4 2col:max-w-[996px]">

// apps/web-spa/src/components/Feed.tsx
<List
  className="2col:grid 2col:grid-cols-2 2col:gap-6"

// apps/web-spa/src/components/PostCard.tsx
className="mb-6 overflow-hidden rounded-lg border border-line bg-surface 2col:mb-0"

// apps/web-spa/src/components/SignUpForm.tsx
className="flex flex-col gap-3 rounded-lg border border-line bg-surface p-4 2col:max-w-[470px]"

62.25rem은 996 ÷ 16입니다. 중단점은 rem으로 적는 게 기본인데, 사용자가 브라우저 기본 글자 크기를 키웠을 때 함께 따라가야 하기 때문이에요.

경계를 확인해봅시다

창 폭을 바꿔가며 재보면 996에서 정확히 갈립니다.

995 까지는 한 열이고 996부터 두 열인데, 그 순간 카드가 정확히 470이 됩니다. 우리가 계산한 숫자가 화면에 그대로 나온 겁니다.

500과 640 사이에서 카드가 470에서 438로 줄어드는 것도 보이실 텐데, 640부터 sm:px-4가 걸리면서 통 안쪽을 좌우 16씩 먹기 때문입니다. 방금 이야기한 그 border-box예요.

💡 한 줄 정리

중단점도 @theme 안에서 이름을 얻는 토큰입니다. 이름을 준다는 것보다 중요한 것은 그 숫자의 근거가 생긴다는 점이에요. 996은 우리 카드 폭과 간격에서 나온 값이라 누가 물어도 설명할 수 있습니다.

Step 2: "그런데 이 토큰만 :root에 없다"

지난 시간에 우리가 만든 토큰이 어디로 갔는지 확인했던 것 기억하시죠. 개발자 도구에서 html을 선택하면 :root에 우리 색이 전부 들어 있었는데, 오늘은 방금 만든 토큰으로 같은 자리를 다시 확인해봅니다.

:root, :host {
  --color-brand: oklch(65.46% 0.177 248.2);
  --color-surface: oklch(100% 0 none);
  ...
}

방금 만든 --breakpoint-2col도 여기 있어야겠죠. 그럼 찾아봅시다.

없습니다

:root를 아무리 훑어도 --breakpoint-2col이 없는데, 우리가 안 만든 것도 아니고 2col:은 화면에서 멀쩡히 동작하는데도요.

빌드된 CSS 파일 전체에서 --breakpoint라는 글자를 찾아도 한 건도 안 나오는데, 색 토큰은 아홉 개가 전부 그대로 있는데 말이죠.

대신 이런 것이 있습니다.

@media (width>=62.25rem) {
  .\32 col\:mb-0 { margin-bottom: 0; }
}

값이 변수로 남지 않고 62.25rem 이라는 숫자 그대로 미디어 조건 안에 들어가 있어요.

왜 이것만 다를까요

색 토큰과 견줘보면 차이가 뚜렷합니다.

 색 토큰      .bg-surface { background-color: var(--color-surface) }
                                              └─ 변수로 남는다

 중단점 토큰  @media (width>=62.25rem) { ... }
                            └─ 값이 그대로 박힌다

이유는 CSS 자체의 성질인데, 미디어 쿼리의 조건에는 var()를 쓸 수 없기 때문이에요.

/* 이건 동작하지 않습니다 */
@media (width >= var(--breakpoint-2col)) { ... }

변수는 요소에 스타일을 적용할 때 값이 정해지지만, 미디어 쿼리는 어떤 요소를 그리기 훨씬 전에 이 규칙 뭉치를 쓸지 말지부터 정해야 해요. 그 시점에는 아직 참조할 요소가 없으니 변수를 읽을 방법이 없고, 그래서 Tailwind는 선택의 여지가 없어요. 빌드할 때 --breakpoint-2col의 값을 꺼내서 조건 안에 직접 써넣습니다. 변수를 내보내 봐야 미디어 쿼리가 쓸 수 없으니 내보내지 않는 거고요.

⚠️ 그래서 중단점 토큰은 런타임에 바꿀 수 없습니다. 색은 자바스크립트로 --color-brand를 바꾸면 화면이 즉시 따라오지만, 중단점은 이미 숫자로 굳어 있어서 바꿀 대상이 없어요.

조건들이 출력되는 순서를 다시 봅시다

지난 시간에 조건들이 파일 안에서 정해진 순서로 늘어선다고 했는데, 우리가 만든 중단점이 그 줄의 어디에 들어가는지 오늘 확인해봅시다.

 출력 순서 (앞 → 뒤)

 (hover:hover)          ← 상태 변형
 (width>=900px)         ← min-[900px]:  임의로 적은 값
 (width>=40rem)         ← sm    640
 (width>=62.25rem)      ← 2col  996   우리가 만든 이름
 (width>=64rem)         ← lg   1024

우리가 만든 2col이 sm과 lg 사이에 들어갔습니다. 이름이 무엇인지는 상관없고 값의 크기순으로 자리를 찾아가서, 이름을 붙인 중단점끼리는 크기 순서대로 예측할 수 있습니다.

⚠️ 그런데 min-[900px]:처럼 임의로 적은 값은 다릅니다. 900px 인데도 640px 인 sm보다 앞에 나와서, 이름 붙은 중단점 무리보다 통째로 앞에 몰립니다.

앞에 있다는 것은 뒤에 있는 것에게 진다는 뜻이라서, 두 조건이 모두 참일 때 sm:이 min-[900px]:을 이깁니다. 900이 640보다 큰데도요.

💡 한 줄 정리

중단점 토큰은 :root에 안 나옵니다. 미디어 쿼리 조건이 var()를 못 쓰기 때문에 빌드할 때 값이 숫자로 굳어서, 색과 달리 런타임에 바꿀 수 없습니다.

@theme {
  --breakpoint-2col: 62.25rem;
}

:root {
  --bp-2col: 62.25rem;
}

Step 3: "조건이 화면 밖에 있을 때 — dark:"

지금까지 배운 조건들을 보면 공통점이 있습니다.

disabled:는 요소가 잠겼는지를 봤고, hover:는 마우스가 그 위에 있는지를 봤고요. sm:과 2col:은 창이 얼마나 넓은지를 봤는데, 전부 우리 화면 안에서 일어나는 일이죠.

오늘 만날 조건은 화면 밖에 있는데, 사용자가 자기 운영체제를 어두운 모드로 쓰고 있는지 여부요.

설정이 필요 없습니다

dark:를 그냥 쓰면 되는데, globals.css에 아무것도 안 적었는데도 동작해요.

<span className="dark:text-brand">어두울 때만 파랑</span>

빌드된 CSS를 열어보면 이렇게 나옵니다.

@media (prefers-color-scheme: dark) {
  .dark\:text-brand { color: var(--color-brand); }
}

prefers-color-scheme은 브라우저가 운영체제 설정을 그대로 전해주는 값입니다. 사용자가 macOS 나 Windows 나 안드로이드에서 어두운 모드를 켜두면 dark가 되고, 아니면 light가 돼요.

즉 우리가 아무것도 안 해도 사용자의 취향이 이미 브라우저까지 와 있어서, 우리는 그 값을 조건으로 쓰기만 하면 되고요.

비워뒀던 마지막 순서

지난 시간 순서 그림에서 제가 하나를 비워뒀는데, 이제 채웁니다.

 출력 순서 (앞 → 뒤)

 조건 없음
 상태 변형 (disabled:  hover:  focus-visible:)
 max-* 방향
 임의 중단점 (min-[900px]:)
 이름 붙은 중단점 (sm:  2col:  lg:  …)
 (prefers-color-scheme: dark)      ← 여기였습니다

dark:가 가장 뒤라서, 다른 조건과 같은 속성을 다투면 dark:가 이겨요. sm:text-ink dark:text-brand를 함께 쓰면 넓은 화면이면서 어두운 모드일 때 파랑이 됩니다.

⚠️ 여기서 한 번 크게 헷갈립니다

dark:를 배우면 자연스럽게 이렇게 써보게 됩니다.

<article className="bg-surface dark:bg-surface">

"평소엔 surface, 어두울 땐 surface"라고 읽혀서 뭔가 이상하지만, 그럼 이건 어떨까요.

<article className="bg-surface dark:bg-canvas">

어두울 때는 canvas가 되는데, canvas는 지금 거의 흰색이라 어두운 화면에서 흰 카드가 나옵니다.

문제의 뿌리를 보려면 생성된 규칙을 봐야 합니다.

.bg-canvas      { background-color: var(--color-canvas); }
.dark\:bg-canvas{ background-color: var(--color-canvas); }

같은 변수를 가리키는데, dark:는 "언제 걸릴지"만 정할 뿐 색을 어둡게 만들어 주지는 않아요. 우리 팔레트에는 아직 어두운 값이 하나도 없으니, 어떤 이름을 골라 붙여도 밝은 색만 나옵니다.

🌟 그러니 다크모드의 진짜 질문은 "어디에 dark:를 붙일까"가 아닙니다. "어두운 값을 어디에 둘까"예요. 다음 두 Step에서 두 가지 답을 각각 만들어 보고 견주겠습니다.

💡 한 줄 정리

dark:는 설정 없이 바로 쓸 수 있고 운영체제 설정을 따라가지만, 조건만 만들어 줄 뿐 값은 안 만들어요. 어두운 값을 어디엔가 두는 것은 우리 몫입니다.

/* dark:hover:text-brand */
@media (prefers-color-scheme: dark) {
  @media (hover: hover) { ... }
}

/* hover:dark:text-danger */
@media (hover: hover) {
  @media (prefers-color-scheme: dark) { ... }
}

Step 4: "다크 값을 어디에 둘까 ① 유틸리티마다 붙이기"

첫 번째 방법부터 해보는데, 배운 대로 dark:를 붙이는 겁니다.

먼저 어두운 값에 이름이 필요합니다

방금 확인했듯이 dark:bg-canvas는 원래 canvas를 그대로 가리켜서, 어두운 값을 담을 새 이름부터 만들어야 합니다.

/* apps/web-spa/src/styles/globals.css */
@theme {
  --color-canvas-dark: oklch(0% 0 none);
  --color-surface-dark: oklch(18.2% 0 none);
  --color-ink-dark: oklch(97% 0 none);
  --color-muted-dark: oklch(73.2% 0 none);
  --color-subtle-dark: oklch(83% 0 none);
  --color-line-dark: oklch(33.3% 0 none);
  --color-line-soft-dark: oklch(26.9% 0 none);
}

일곱 개가 늘었는데, 값을 어떻게 골랐는지는 Step 6에서 다루고 지금은 방법 자체에 집중할게요.

그다음 색을 쓰는 곳마다 짝을 붙입니다

// apps/web-spa/src/components/PostCard.tsx
className="mb-6 overflow-hidden rounded-lg border border-line dark:border-line-dark bg-surface dark:bg-surface-dark 2col:mb-0"

동작합니다. 어두운 모드에서 카드가 제대로 어두워져서, 방법 자체는 옳습니다.

문제는 여기가 한 곳이 아니라는 점이죠.

세어보면 이렇습니다

색을 쓰는 곳을 전부 세어보면 29곳, 14개 파일입니다.

 index.html          2      LikeButton          2
 App                 1      MiniPostCard        4
 ClickCounter        2      PostBody            2
 CommentForm         1      PostCard            2
 CommentList         2      Section             1
 KeyDemo             4      SignUpForm          2
 StaticPostCard      2      TextField           2

29곳에 짝을 붙이고 나면 화면은 완성되는데, 그 대가를 한번 봅시다.

더 큰 문제는 끝나지 않는다는 것인데, 다음 주에 새 컴포넌트를 만들면 거기서도 bg-surface 옆에 dark:bg-surface-dark를 또 적어야 해요. 한 번이라도 빠뜨리면 그 요소만 어두운 화면에서 하얗게 남습니다.

⚠️ 빠뜨린 것을 알아차리기도 어려운데, 개발할 때 밝은 모드로 보고 있으면 아무 문제가 없거든요. 지난 시간에 포커스 표시를 한 곳 빠뜨렸던 것과 똑같은 종류의 사각지대입니다.

이름도 두 배로 늘었죠. surface와 surface-dark는 결국 같은 것을 뜻하는데 이름이 둘이고, 세 번째 테마가 생기면 셋이 되고요.

💡 한 줄 정리

dark: 유틸리티를 컴포넌트마다 붙이는 방법은 동작합니다. 다만 색을 쓰는 모든 곳을 찾아다녀야 하고, 새 컴포넌트를 만들 때마다 다시 해야 해요. 빠뜨려도 밝은 모드에서는 안 보입니다.

Step 5: "다크 값을 어디에 둘까 ② 이름은 그대로, 값만"

다시 생각해보면, bg-surface가 하는 일이 뭐죠.

.bg-surface { background-color: var(--color-surface); }

--color-surface를 보고 있을 뿐이라서, 그 변수에 뭐가 들어 있는지는 bg-surface가 정하지 않아요.

그렇다면 컴포넌트를 하나도 안 건드리고, 저 변수의 값만 어두울 때 바꿔치면 어떨까요. bg-surface라고 적힌 여덟 곳이 전부 따라올 텐데요.

방금 지운 것을 되돌리고, 대신 이렇게 씁니다

Step 4에서 붙인 29곳을 전부 원래대로 돌리고, 새로 만든 이름 일곱 개도 지웁니다. 대신 globals.css에 일곱 줄을 더합니다.

/* apps/web-spa/src/styles/globals.css */
@media (prefers-color-scheme: dark) {
  :root {
    --color-canvas: oklch(0% 0 none);
    --color-surface: oklch(18.2% 0 none);
    --color-ink: oklch(97% 0 none);
  }
}

이게 전부인데, 어두운 모드로 바꿔보면 페이지 바닥이 검어지고 카드가 그보다 살짝 밝은 회색이 되고 글자가 하얘집니다.

컴포넌트는 한 글자도 안 고쳤습니다. PostCard는 여전히 bg-surface 라고만 적혀 있어요.

왜 우리가 쓴 값이 이기나요

@theme도 :root에 값을 넣었고, 우리도 :root에 값을 넣었습니다. 같은 변수를 두고 둘이 다투는 셈이죠.

지난 시간에 배운 것을 떠올려 보면 "나중에 쓴 것이 이긴다"라고 답하고 싶어지지만, 그게 아니에요. 먼저 써도 이깁니다.

확인해보죠. 순서를 뒤집어서 우리 것을 먼저, @theme 쪽을 나중에 두고 재봤습니다.

/* 먼저 쓴 쪽 — layer 밖 */
#probe { --c: rgb(10, 10, 10); }

/* 나중에 쓴 쪽 — layer 안 */
@layer theme { #probe { --c: rgb(200, 200, 200); } }

결과는 rgb(10, 10, 10)입니다. 먼저 쓴 쪽이 이겼어요.

이유는 지지난 시간에 우리를 괴롭혔던 그 규칙입니다. cascade layer밖에 있는 스타일은 layer 안에 있는 것을 이깁니다. 순서를 따지기 전에 이미 결판이 나요.

 @layer theme {  :root, :host { --color-surface: 흰색 }  }   ← layer 안
 @media (...) {  :root        { --color-surface: 어두움 } }   ← layer 밖  이김

@theme이 내보내는 값은 theme이라는 layer 안에 들어갑니다. 우리가 globals.css에 그냥 쓴 :root는 어느 layer에도 안 들어가고요.

🌟 지지난 시간에는 이 규칙 때문에 손으로 쓴 CSS가 유틸리티를 이겨서 골치였죠. 같은 규칙이 이번에는 우리 편으로 일합니다. 기본값 위에 우리 값을 얹기가 쉬워지니까요.

두 방법을 나란히 놓고 봅시다

마지막 줄이 가장 중요합니다. 앞으로 만들 컴포넌트가 bg-surface를 쓰기만 하면 다크모드는 이미 되어 있어요. 아무도 잊어버릴 수 없습니다.

canvas와 surface가 드디어 갈라집니다

지지난 시간에 이름만 지어두고 안 갈라놓은 두 가지가 있었는데, canvas는 페이지 바닥이고 surface는 그 위에 얹히는 카드 배경이라 둘 다 거의 흰색이었고 나눌 이유가 없어 보였습니다.

이제 확실히 갈립니다.

 밝을 때   canvas #fafafa  ─  surface #ffffff     거의 안 갈림
 어두울 때 canvas #000000  ─  surface #121212     카드가 바닥에서 떠 보임

어두운 화면에서는 테두리보다 밝기 차이가 카드를 구분해 줘서, 두 이름을 나눠둔 것이 이제야 값을 합니다. 만약 지지난 시간에 둘을 --color-white 하나로 합쳤다면, 지금 이 두 곳을 다시 갈라내야 했을 거예요.

💡 한 줄 정리

유틸리티는 변수를 보고 있으니, 변수 값만 갈아끼우면 그 이름을 쓰는 모든 곳이 한꺼번에 따라옵니다. @theme 값을 이기는 이유는 순서가 아니라 cascade layer예요. 우리가 쓴 :root는 layer 밖이라 먼저 써도 이깁니다.

@theme {
  --color-surface: oklch(100% 0 none);

  @media (prefers-color-scheme: dark) {
    --color-surface: oklch(18.2% 0 none);
  }
}

 @theme    어떤 이름들이 있는가          (유틸리티가 여기서 만들어진다)
 :root     그 이름이 지금 무슨 값인가    (조건에 따라 바뀔 수 있다)

Step 6: "다크 값은 눈대중으로 고르지 않는다"

이제 나머지 네 개를 채우는데, muted, subtle, line, line-soft요.

여기서 흔한 실수가 하나 있는데, "어두우니까 대충 밝게 하면 되겠지" 하고 눈으로 골라버리는 거예요. 지지난 시간에 색에 이름을 줄 때도 눈대중을 금지했었죠. 같은 이유가 여기서도 적용됩니다.

옮겨야 하는 것은 밝기가 아니라 대비입니다

밝은 화면에서 각 회색이 카드 위에서 어느 정도로 읽혔는지 재보면 이렇습니다.

ink는 본문 글자라 아주 진하고, line은 테두리라 있는 듯 없는 듯합니다. 이 관계가 어두운 화면에서도 유지돼야, 사용자가 느끼는 위계가 같습니다.

그래서 값을 고를 때 "얼마나 밝게 할까"가 아니라 "이 대비를 어떻게 다시 만들까"로 물어야 합니다.

⚠️ 밝기 순서가 뒤집힙니다

여기서 한 번 헷갈리는데, 밝은 화면에서는 어두울수록 또렷하고 어두운 화면에서는 밝을수록 또렷하죠.

그래서 값을 그대로 밝게만 옮기면 위계가 조용히 뒤집히는데, 예를 들어 볼게요.

 밝을 때   subtle #737373  (어둡다 = 또렷)
           muted  #8e8e8e  (밝다   = 흐림)
           → subtle 이 muted 보다 또렷하다

 값을 그대로 뒤집으면
           subtle 이 muted 보다 어두워진다
           → 어두운 화면에서는 subtle 이 더 흐려진다   뒤집혔다

subtle은 폼 라벨에 쓰고 muted는 보조 문구에 씁니다. 라벨이 보조 문구보다 흐려지면 폼이 읽기 어려워져서, 어두운 화면에서는 subtle을 muted보다 밝게 잡아야 원래 관계가 지켜집니다.

정한 값

/* apps/web-spa/src/styles/globals.css */
@media (prefers-color-scheme: dark) {
  :root {
    --color-canvas: oklch(0% 0 none);
    --color-surface: oklch(18.2% 0 none);
    --color-ink: oklch(97% 0 none);

    /* 회색 넷은 밝기를 뒤집되 서열은 그대로 둔다.
       라이트에서 subtle 이 muted 보다 어두워 더 또렷했으므로
       다크에서는 subtle 이 muted 보다 밝아야 한다. */
    --color-muted: oklch(73.2% 0 none);
    --color-subtle: oklch(83% 0 none);
    --color-line: oklch(33.3% 0 none);
    --color-line-soft: oklch(26.9% 0 none);
  }
  /* brand·danger 는 안 바꾼다 — 브랜드색은 양쪽 화면에서 같아야 한다 */
}

재본 결과입니다.

진한 순서가 양쪽에서 똑같은데, ink → subtle → muted → line이에요. 값은 반대편으로 갔는데 서열은 그대로죠.

안 바꾼 것도 있습니다

brand와 danger는 그대로 뒀습니다. 어두운 모드에서도 인스타그램 파랑은 같은 파랑이어야 하니까요. 브랜드 색이 화면 설정에 따라 달라지면 그건 다른 브랜드입니다.

실제로 확인해보면 어두운 화면에서도 가입하기 버튼은 0,149,246 그대로예요. 다크모드를 만든다고 해서 모든 값을 바꿀 필요는 없습니다.

⚠️ 그런데 표에서 눈에 걸리는 것이 하나 있죠. muted가 밝을 때 3.28입니다. 본문 글자에 권장되는 4.5에 못 미쳐요. 어두울 때는 7.88로 넉넉한데 말이죠.

이건 오늘 만든 문제가 아닙니다. 원래부터 그랬는데, 어두운 값을 계산하면서 나란히 놓고 보니까 드러난 겁니다. 다크모드를 만들다가 밝은 화면의 약점을 발견한 셈이죠. 이 문제를 어떻게 다룰지는 오늘 생각해볼 주제로 남기겠습니다.

💡 한 줄 정리

다크 값은 밝기를 짐작해서 정하는 게 아니라 밝은 화면에서 재둔 대비를 다시 만드는 겁니다. 밝기 방향이 뒤집히므로 회색끼리의 서열이 유지되는지 반드시 확인해야 해요.

Step 7: "값만 갈아끼워서 안 되는 곳"

여기까지 하면 화면 대부분이 어두워지는데, 전부는 아니에요.

토큰 값을 바꾸는 방식은 그 토큰을 쓰고 있는 것만 움직입니다. 토큰을 안 쓰는 곳은 그대로 남아요. 어두운 모드로 화면을 훑으면서 남은 것들을 찾아봅시다.

알림 상자가 사라집니다

좋아요를 누르면 아래쪽에 알림이 뜨는데, 그 코드를 봅시다.

// apps/web-spa/src/components/Toast.tsx
className="fixed bottom-8 left-1/2 -translate-x-1/2 rounded-[20px] bg-black/82 px-4.5 py-2.5 text-sm text-white"

bg-black/82는 우리 토큰이 아닙니다. Tailwind가 원래 갖고 있는 검정이에요. 그러니 우리가 --color-*를 아무리 갈아끼워도 여기는 안 움직입니다.

밝은 화면에서는 문제가 없었습니다. 흰 페이지 위에 검은 상자가 뜨니 잘 보였죠. 그런데 어두운 화면에서는 페이지가 검정이 됩니다.

 밝을 때    페이지 250,250,250   상자 45,45,45    잘 보인다
 어두울 때  페이지   0,  0,  0   상자  0, 0, 0    상자와 배경이 같은 색

상자와 배경의 대비가 1.00입니다. 완전히 같은 색이에요. 글자는 흰색이라 읽히지만 상자의 윤곽이 통째로 사라져서, 알림이 아니라 글자가 허공에 떠 있는 것처럼 보입니다.

서로 뒤집히는 이름으로 고칩니다

어두운 값 하나를 더 만들어서 dark:로 붙이는 방법도 있지만, 더 나은 방법이 있어요.

이 상자가 원하는 것은 "페이지와 반대"입니다. 밝은 화면에서는 어둡고, 어두운 화면에서는 밝아야 해요.

우리 팔레트에 이미 서로 뒤집히는 짝이 있죠. ink와 canvas입니다. ink는 밝을 때 어둡고 어두울 때 밝아요. canvas는 정확히 그 반대고요.

// apps/web-spa/src/components/Toast.tsx
className="fixed bottom-8 left-1/2 -translate-x-1/2 rounded-[20px] bg-ink/90 px-4.5 py-2.5 text-sm text-canvas"

이제 상자가 저절로 반전됩니다.

새 이름을 안 만들고 dark:도 안 붙였는데 양쪽에서 잘 보여요. 이미 있는 두 이름의 관계를 이용한 겁니다.

⚠️ 정직하게 짚을 것이 하나 있습니다. 밝은 화면에서 상자가 45,45,45에서 59,59,59로 아주 조금 밝아졌어요. 검정 대신 ink를 깔았으니까요. 대비는 13.19에서 10.73으로 내려갔지만 여전히 넉넉합니다. 이 정도 변화를 받아들일지는 디자이너와 함께 정할 일이에요.

반쪽만 따라와서 부딪히는 곳

더 고약한 것이 있습니다. 회원가입 폼 맨 위의 프로필 사진 고르기 버튼이에요. 지지난 시간 과제로 남겨둔 것이라 아직 손으로 쓴 CSS를 쓰고 있습니다.

/* apps/web-spa/src/styles/globals.css */
.profile-picker-button {
  border: 1px solid #dbdbdb;
  border-radius: 6px;
  background: #fafafa;
  padding: 6px 12px;
  font-size: 13px;
  cursor: pointer;
}

여기엔 글자색이 없어서, 글자색은 body에 걸린 text-ink를 물려받습니다.

어두운 모드에서 무슨 일이 일어나는지 보세요.

 배경    #fafafa   손으로 적은 값    안 움직인다   → 250,250,250
 테두리  #dbdbdb   손으로 적은 값    안 움직인다   → 219,219,219
 글자    (없음)    ink 를 물려받음   따라 움직인다 → 245,245,245

한 요소 안에서 반쪽만 따라온 겁니다. 배경은 흰색으로 남고 글자만 밝아져서, 흰 버튼 위에 흰 글씨가 됐어요. 글자와 배경의 대비가 1.04입니다. 밝은 화면에서는 14.50 이었는데요.

이게 손으로 쓴 값을 남겨두면 생기는 진짜 위험입니다. 그냥 안 바뀌는 것보다 나빠요. 안 바뀌기만 하면 어색할 뿐인데, 반쪽만 바뀌면 읽을 수 없게 됩니다.

이 버튼은 오늘 고치지 않고 과제로 남기겠습니다. 지금 화면에서 직접 확인해보시라고요.

반대로 저절로 잘 따라오는 것도 있습니다

지난 시간에 잠긴 게시 버튼 색을 disabled:text-brand/30으로 옮기면서, 어두운 배경 위에서는 값이 갈린다고 하고 미뤄뒀죠. 이제 확인합니다.

 밝을 때    카드 배경 255,255,255  →  잠긴 글자 179,223,252   흐린 하늘색
 어두울 때  카드 배경  18, 18, 18  →  잠긴 글자  13, 57, 86   흐린 남색

알파로 적은 색은 뒤에 무엇이 오든 그것에 섞입니다. 그래서 배경이 바뀌면 저절로 따라와요. 우리가 아무것도 안 했는데 양쪽에서 자연스럽게 흐려집니다.

만약 지난 시간에 이걸 #b2dffc라는 값으로 그냥 적었다면 어땠을까요. 어두운 화면에서도 밝은 하늘색이 그대로 떠서 잠긴 버튼이 오히려 더 눈에 띄었을 겁니다.

🌟 그러니 알파는 다크모드에서 손해가 아니라 이득이에요. "값을 못 바꾸는 것"이 아니라 "배경을 따라가는 것"입니다.

그리고 아예 못 바꾸는 것

사진은 어떻게 할 수 없습니다. 사용자가 올린 밝은 사진은 어두운 화면에서도 밝아요.

이건 고칠 대상이 아닙니다. 인스타그램 실제 앱도 사진을 어둡게 하지 않아요. 사진은 콘텐츠 그 자체라, 우리가 색을 건드리면 그건 다른 사진이 되니까요. 다크모드가 손댈 수 없는 영역이 있다는 것을 알아두시면 됩니다.

💡 한 줄 정리

토큰 값을 바꾸는 방식은 그 토큰을 쓰는 것만 움직입니다. 손으로 적은 값은 안 따라오고, 상속받는 속성만 따라와서 한 요소 안에서 부딪히기도 해요. 다크모드를 켜본다는 것은 곧 토큰을 안 쓰는 곳을 찾아내는 일입니다.

/* @media (prefers-color-scheme: dark) { */
  :root { --color-canvas: oklch(0% 0 none); ... }
/* } */

마무리

오늘 한 일을 한 줄로 줄이면 이렇습니다. 이름은 그대로 두고 값을 갈아끼웠습니다.

지난 시간까지는 유틸리티에 조건을 붙여서 "언제 걸릴지"를 말했죠. 오늘은 조건에 따라 "무슨 값일지"가 달라지게 만들었습니다.

오늘 배운 핵심 세 가지

💡 하나 — 모든 토큰이 같은 방식으로 나오지는 않습니다. 색 토큰은 :root에 변수로 남아 런타임에 바꿀 수 있지만, 중단점 토큰은 값이 숫자로 굳어 사라집니다. 미디어 쿼리 조건이 변수를 못 읽기 때문이에요.

💡 둘 — 같은 목적지에 두 가지 길이 있고, 고르는 기준은 범위입니다. 앱 전체에 걸리는 규칙은 토큰 값을 한 곳에서 바꾸고, 한 요소만의 예외는 dark: 유틸리티로 붙입니다. 전체 규칙을 29곳에 나눠 적으면 새 컴포넌트를 만들 때마다 잊어버릴 수 있어요.

💡 셋 — 다크모드를 켜보는 것은 토큰을 안 쓰는 곳을 찾는 일입니다. 손으로 적은 값은 따라오지 않고, 그중에서도 반쪽만 따라오는 것이 가장 위험해요. 흰 버튼 위의 흰 글씨는 밝은 화면에서 아무리 봐도 안 보입니다.

시작할 때 남아 있던 두 가지

오프닝에서 지난 시간이 남긴 두 가지를 이야기했죠. 어떻게 닫혔는지 봅시다.

그리고 지지난 시간에 이름만 지어두고 안 갈라놨던 canvas와 surface도 오늘 갈라졌습니다.

다음 시간 예고

오늘 우리 다크모드는 운영체제 설정을 그대로 따릅니다. 사용자가 시스템을 밝게 쓰면 우리 화면도 밝아요.

그런데 실제 서비스에는 대개 해와 달 모양의 버튼이 있죠. 시스템 설정과 상관없이 이 사이트만 어둡게 보고 싶은 사람이 있으니까요.

그러려면 조건이 달라져야 합니다. prefers-color-scheme은 우리가 읽을 수만 있고 바꿀 수는 없는 값이거든요.

대신 dark:라는 변형이 무슨 뜻인지를 우리가 다시 정할 수 있습니다. 지난 시간에 hover: 이야기를 하면서 변형을 손수 만드는 문법이 있다고 했죠. 그게 이겁니다.

@custom-variant dark (&:where(.dark, .dark *));

이 한 줄은 dark:라는 변형의 뜻을 "운영체제가 어두울 때"에서 "그 요소나 위쪽 어딘가에 dark라는 표시가 붙어 있을 때"로 바꾸는데, 이 줄만 넣으면 우리 화면은 꿈쩍도 안 해요. 우리는 Step 5에서 토큰 방식을 골라서 dark: 유틸리티를 한 개도 안 쓰고 있거든요. 실제로 옮겨야 하는 것은 오늘 쓴 그 @media (prefers-color-scheme: dark) 블록입니다. 그 조건을 표시 쪽으로 바꾸면 토글이 화면을 움직이게 돼요.

바꾸는 것은 조건뿐입니다. 오늘 고른 색 값은 한 개도 안 버려요. 값과 조건을 갈라 둔 덕분에 조건만 바꿔 끼울 수 있는 겁니다.

다음 시간에 이 한 줄을 실제로 쓰고, 표시를 붙였다 떼는 버튼까지 만듭니다.

그다음 시간엔 이미 만들어진 컴포넌트를 가져다 쓰는 방법도 배웁니다. 대화 상자나 드롭다운처럼 직접 만들면 접근성까지 챙기기 까다로운 것들이 있어요. 그런 것을 복사해서 내 것으로 만드는 방식이 요즘 표준인데, 우리가 오늘 만든 토큰 위에 그대로 얹힙니다.

마지막으로 오늘 우리가 쓴 조건은 전부 창이나 운영체제를 봤습니다. 지난 시간 마무리에서 이름을 소개했던 컨테이너 쿼리는 담긴 칸을 보죠. 그건 비주얼을 마감하는 시간에 실제로 써봅니다.

과제

[구현] 어두운 화면에서 사라진 버튼 되살리기

Step 7에서 프로필 사진 고르기 버튼이 흰 배경에 흰 글씨가 된다고 했죠. 직접 확인하고 고쳐 주세요.

• 먼저 어두운 모드를 켜고 그 버튼을 눈으로 확인하세요. 글자가 보이나요?
• 개발자 도구로 그 버튼의 background-color와 color를 각각 읽고 두 값을 적어 주세요. 왜 하나만 바뀌었는지 한 줄로 설명하고요.
• globals.css에서 profile-picker로 시작하는 규칙 네 개를 전부 유틸리티로 옮기세요. 우리 토큰만 써야 합니다.
• 옮기고 나면 어두운 모드에서 저절로 따라오는지 확인하세요. dark:를 한 번도 안 쓰고 해결되면 제대로 옮긴 겁니다.
• 밝은 모드에서 원래 생김새가 유지되는지도 확인해 주세요.

다 하고 나면 npm run typecheck -w web-spa와 npm run lint -w web-spa를 돌려 둘 다 통과하는지 확인해 주세요.

[구현] 우리 중단점 하나 더 만들기

지금 화면은 996px 에서 한 열과 두 열이 갈립니다. 아주 넓은 화면에서는 세 열이 들어갈 텐데요.

• 세 열이 들어가려면 뷰포트가 몇 px이어야 하는지 Step 1처럼 계산해 주세요. 카드 470, 간격 24, 통의 좌우 여백 32를 그대로 씁니다.
• 계산한 값으로 --breakpoint-3col을 만드세요. rem으로 적어야 합니다.
• 통의 최대 폭과 피드의 열 수를 그 중단점에서 바꾸세요.
• 계산한 폭보다 1px 좁을 때와 정확히 그 폭일 때를 각각 확인하고, 카드 폭이 470으로 나오는지 재 주세요.
• 빌드된 CSS에서 --breakpoint-3col을 찾아보세요. 있나요? 없다면 그 값이 어디로 갔는지 적어 주세요.

[탐구] 경계를 건드려 보기

각 실험 결과를 한두 줄씩 적어 주세요. 확인이 끝나면 전부 되돌립니다.

• 아무 요소에 2col:text-danger dark:text-brand를 함께 붙이고, 넓은 화면에서 어두운 모드를 켜 보세요. 어느 쪽이 이기나요? Step 3의 순서 그림과 맞는지 견줘 보세요.
• 같은 요소에 min-[900px]:text-danger sm:text-brand를 붙이고 창을 1000px 쯤으로 맞춰 보세요. 두 조건이 모두 참인데 어느 쪽이 이기나요? 크기 순서대로 나오나요?
• globals.css의 다크 블록을 @theme 안으로 옮겨 보세요. 화면이 어떻게 되나요? 빌드가 실패하나요, 아니면 조용히 아무 일도 안 일어나나요?
• 다크 블록의 :root를 @layer theme { :root { ... } }로 감싸 보세요. 여전히 이기나요? 이기거나 지는 이유를 Step 5의 실험과 연결해 설명해 주세요.

생각해볼 주제

1. 새 화면을 만들다가 원래 화면의 문제를 발견했을 때

Step 6에서 muted의 대비를 재보니 밝은 화면에서 3.28 이었습니다. 본문 글자에 권장되는 4.5에 못 미치는 값이에요. 어두운 화면에서는 7.88로 넉넉하고요.

이건 오늘 만든 문제가 아닙니다. 처음부터 그랬는데 아무도 재보지 않았을 뿐이죠. 다크 값을 계산하려고 밝은 값을 나란히 놓고 나서야 드러났습니다.

여기서 판단이 갈립니다. 지금 고치면 이미 쓰고 있는 화면의 색이 바뀌고, 디자이너가 정한 값을 개발자가 임의로 바꾸는 셈이 됩니다. 안 고치면 접근성 문제를 알면서 두는 것이 되고요.

여러분이라면 어떻게 하시겠어요. 그리고 이런 발견을 팀에 어떻게 전달해야 "나중에 보자"로 묻히지 않을지도 함께 생각해 보세요.

2. 사용자의 설정을 따를 것인가, 우리가 고르게 할 것인가

오늘 우리 다크모드는 운영체제 설정을 그대로 따릅니다. 코드를 한 줄도 안 쓰고 얻은 결과라 값이 싼데, 실제 서비스 대부분은 사이트 안에 별도의 토글을 둡니다. 시스템은 밝게 쓰면서 특정 사이트만 어둡게 보고 싶은 사람이 있으니까요. 반대로 시스템을 어둡게 쓰지만 사진이 많은 사이트는 밝게 보고 싶은 사람도 있고요.

토글을 두면 결정할 것이 늘어납니다. 사용자가 고른 값을 어디에 저장할지, 다음에 방문했을 때 언제 읽을지, 그리고 시스템 설정이 바뀌면 저장해둔 선택을 따를지 시스템을 따를지요.

시스템 설정만 따르는 것으로 충분한 서비스와 토글이 꼭 필요한 서비스는 무엇이 다를까요. 그리고 토글을 둔다면 "시스템 따르기"라는 선택지도 함께 줘야 할지 생각해 보세요.

3. 규칙을 한 곳에 모으는 것과 흩어 놓는 것

오늘 우리는 다크 값을 한 곳에 모았습니다. globals.css의 블록 하나를 고치면 화면 전체가 바뀌죠.

편해 보이지만 반대편도 있습니다. PostCard.tsx만 열어본 사람은 이 카드가 어두운 모드에서 어떻게 보이는지 알 수 없어요. bg-surface 라고만 적혀 있으니까요. 알려면 다른 파일을 열어야 합니다.

Step 4의 방법은 반대였죠. dark:bg-surface-dark가 그 자리에 적혀 있으니 파일 하나만 봐도 다 보입니다. 대신 29곳에 흩어져서 전체를 바꾸기가 어렵고요.

이 맞바꿈은 다크모드만의 이야기가 아닙니다. 앞으로 여러분이 만들 거의 모든 공통 규칙에서 같은 선택을 하게 돼요.

한 곳에 모으는 편이 나은 것과 각자의 자리에 적어두는 편이 나은 것을 가르는 기준이 무엇일지, 그리고 모아둔 규칙을 나중에 읽을 사람이 찾을 수 있게 하려면 무엇을 해두어야 할지도 정리해 보세요.