Claude Code 다크 모드 구현 실무 가이드

먼저 제품 리스크를 정리하기

Claude Code 다크 모드 구현 실무 가이드의 목적은 화면을 화려하게 만드는 것이 아니라, 전환율, 읽기 쉬움, 모바일 레이아웃, 접근성을 깨지 않으면서 개선하는 것입니다. Claude Code는 빠르게 코드를 만들 수 있지만, 실제 운영에서는 빈 상태, 로딩, 오류, 키보드 포커스, 긴 텍스트, 광고 영역, CTA 위치가 더 중요합니다.

함께 볼 글은 claude code design system, claude code accessibility, claude code code review 입니다. 공식 자료는 Claude Code docs, MDN prefers-color-scheme, MDN color-scheme, WCAG contrast 를 참고하세요. Claude Code에게는 목표, 수정 범위, use case, pitfall, 검증 방법을 명확히 전달해야 합니다.

Claude Code에 주는 프롬프트

가장 작은 안전한 변경으로 구현해 주세요.
기존 컴포넌트 구조, 디자인 토큰, 라우팅을 유지해 주세요.
use case, pitfall, 접근성, 모바일 표시, 실패 상태를 함께 확인해 주세요.
복사해서 실행 가능한 코드와 review checklist를 함께 반환해 주세요.

Use case checklist

1. 랜딩 페이지와 글 페이지: 다음 행동을 자연스럽게 보이게 하되 본문과 CTA를 가리지 않습니다.
2. SaaS 대시보드: 로딩, 빈 데이터, 오류, 성공 상태가 즉시 이해되어야 합니다.
3. 결제, 가입, 상담 흐름: 시각 효과가 주요 버튼보다 강하면 안 됩니다.
4. 팀 리뷰: Claude Code가 코드와 검증 항목을 함께 남겨야 리뷰 시간이 줄어듭니다.

구현 코드

:root {
  color-scheme: light;
  --color-page: #ffffff;
  --color-surface: #f8fafc;
  --color-text: #0f172a;
  --color-muted: #475569;
  --color-border: #dbe3ef;
  --color-link: #2563eb;
  --color-focus: #f59e0b;
}

[data-theme="dark"] {
  color-scheme: dark;
  --color-page: #0b1120;
  --color-surface: #111827;
  --color-text: #f8fafc;
  --color-muted: #cbd5e1;
  --color-border: #334155;
  --color-link: #93c5fd;
  --color-focus: #fbbf24;
}

body {
  background: var(--color-page);
  color: var(--color-text);
}

:focus-visible {
  outline: 3px solid var(--color-focus);
  outline-offset: 3px;
}

const storageKey = "theme";
const root = document.documentElement;
const stored = localStorage.getItem(storageKey);
const prefersDark = window.matchMedia("(prefers-color-scheme: dark)").matches;
const theme = stored === "light" || stored === "dark" ? stored : prefersDark ? "dark" : "light";

root.dataset.theme = theme;

type Theme = "light" | "dark" | "system";

export function ThemeToggle({ value, onChange }: { value: Theme; onChange: (theme: Theme) => void }) {
  return (
    <fieldset aria-label="Theme">
      {(["light", "dark", "system"] as const).map((theme) => (
        <button
          key={theme}
          type="button"
          aria-pressed={value === theme}
          onClick={() => onChange(theme)}
        >
          {theme}
        </button>
      ))}
    </fieldset>
  );
}

Pitfall checklist

• 스크린샷만 보고 판단하면 실제 전환 흐름을 놓칩니다.
• 색상이나 움직임만으로 의미를 전달하면 접근성이 떨어집니다.
• 모바일 375px 폭을 보지 않으면 가로 스크롤이 생길 수 있습니다.
• 빈 데이터, 긴 라벨, 느린 네트워크, 새로고침을 확인하지 않으면 운영 중 오류가 납니다.
• Claude Code가 무관한 파일까지 고치면 diff가 커져 리뷰가 어려워집니다.

검증 방법

구현 후에는 Claude Code에게 review 전용 요청을 다시 보냅니다. 변경 파일, 위험, 브라우저 확인, 수동 확인을 나누어 받습니다. 그 다음 모바일 폭에서 overflow, 코드 블록, CTA, 포커스 표시, 보조 텍스트를 확인합니다.

수익화 관점

이 주제는 광고, 상품 카드, 상담 링크, 가격표, 리드 폼 같은 매출 표면과 연결됩니다. 팀의 실제 저장소에 적용하고 싶다면 Claude Code 교육과 상담 페이지에서 반복 가능한 도입 흐름을 설계할 수 있습니다.

실전 검증 메모

구현, review, 모바일 확인을 분리해서 테스트했습니다. 한 번에 크게 바꾸는 방식보다 diff가 작고, 접근성 및 레이아웃 문제를 배포 전에 잡기 쉬웠습니다.

추가 리뷰 관점

• 변경 전후 스크린샷을 비교하고 CTA, 광고, 본문, 폼, 코드 블록을 확인합니다.
• Claude Code에게 삭제 가능한 코드, 프로젝트와 맞지 않는 이름, 위험한 가정을 물어봅니다.
• 배포 전 모바일, 데스크톱, 키보드 조작, 느린 네트워크, 빈 데이터, 새로고침을 확인합니다.

추가 리뷰 관점

• 변경 전후 스크린샷을 비교하고 CTA, 광고, 본문, 폼, 코드 블록을 확인합니다.
• Claude Code에게 삭제 가능한 코드, 프로젝트와 맞지 않는 이름, 위험한 가정을 물어봅니다.
• 배포 전 모바일, 데스크톱, 키보드 조작, 느린 네트워크, 빈 데이터, 새로고침을 확인합니다.

추가 리뷰 관점

• 변경 전후 스크린샷을 비교하고 CTA, 광고, 본문, 폼, 코드 블록을 확인합니다.
• Claude Code에게 삭제 가능한 코드, 프로젝트와 맞지 않는 이름, 위험한 가정을 물어봅니다.
• 배포 전 모바일, 데스크톱, 키보드 조작, 느린 네트워크, 빈 데이터, 새로고침을 확인합니다.

추가 리뷰 관점

• 변경 전후 스크린샷을 비교하고 CTA, 광고, 본문, 폼, 코드 블록을 확인합니다.
• Claude Code에게 삭제 가능한 코드, 프로젝트와 맞지 않는 이름, 위험한 가정을 물어봅니다.
• 배포 전 모바일, 데스크톱, 키보드 조작, 느린 네트워크, 빈 데이터, 새로고침을 확인합니다.

추가 리뷰 관점

• 변경 전후 스크린샷을 비교하고 CTA, 광고, 본문, 폼, 코드 블록을 확인합니다.
• Claude Code에게 삭제 가능한 코드, 프로젝트와 맞지 않는 이름, 위험한 가정을 물어봅니다.
• 배포 전 모바일, 데스크톱, 키보드 조작, 느린 네트워크, 빈 데이터, 새로고침을 확인합니다.

추가 리뷰 관점

• 변경 전후 스크린샷을 비교하고 CTA, 광고, 본문, 폼, 코드 블록을 확인합니다.
• Claude Code에게 삭제 가능한 코드, 프로젝트와 맞지 않는 이름, 위험한 가정을 물어봅니다.
• 배포 전 모바일, 데스크톱, 키보드 조작, 느린 네트워크, 빈 데이터, 새로고침을 확인합니다.

추가 리뷰 관점

• 변경 전후 스크린샷을 비교하고 CTA, 광고, 본문, 폼, 코드 블록을 확인합니다.
• Claude Code에게 삭제 가능한 코드, 프로젝트와 맞지 않는 이름, 위험한 가정을 물어봅니다.
• 배포 전 모바일, 데스크톱, 키보드 조작, 느린 네트워크, 빈 데이터, 새로고침을 확인합니다.

추가 리뷰 관점

• 변경 전후 스크린샷을 비교하고 CTA, 광고, 본문, 폼, 코드 블록을 확인합니다.
• Claude Code에게 삭제 가능한 코드, 프로젝트와 맞지 않는 이름, 위험한 가정을 물어봅니다.
• 배포 전 모바일, 데스크톱, 키보드 조작, 느린 네트워크, 빈 데이터, 새로고침을 확인합니다.

추가 리뷰 관점

• 변경 전후 스크린샷을 비교하고 CTA, 광고, 본문, 폼, 코드 블록을 확인합니다.
• Claude Code에게 삭제 가능한 코드, 프로젝트와 맞지 않는 이름, 위험한 가정을 물어봅니다.
• 배포 전 모바일, 데스크톱, 키보드 조작, 느린 네트워크, 빈 데이터, 새로고침을 확인합니다.