Claude Code로 CSS variables와 theme token 설계하기

먼저 문제 범위를 정하기

Claude Code로 CSS variables와 theme token 설계하기의 목적은 Claude Code에게 멋진 코드를 한 번에 만들게 하는 것이 아닙니다. 상호작용, 레이아웃, 접근성, 모바일 표시, 매출 동선을 같은 체크리스트에서 확인하는 것입니다. 초보자는 데스크톱 화면만 보고 끝내기 쉽지만, 실제 운영에서는 긴 텍스트, 코드 블록, 광고, CTA, 키보드 조작, 오류 상태가 더 중요합니다.

CSS 변수는 정확히는 CSS 커스텀 프로퍼티라고 부르는 구조입니다. --color-accent처럼 직접 이름을 붙인 값을 정의하고, var(--color-accent)로 다른 선언에서 참조합니다. 초보자용으로 바꿔 말하면, 색, 여백, 모서리 둥글기, 그림자, 폰트 크기에 “이름 붙은 보관소”를 만드는 기능입니다. Claude Code에 UI 구현을 맡길 때 이 보관소를 먼저 정해 두면 생성되는 CSS가 흩어지기 어렵고, 버튼만 파랑, 카드만 미묘하게 다른 그림자, 다크 모드만 글자색이 너무 옅은 사고를 줄일 수 있습니다.

함께 볼 글은 claude code dark mode implementation, claude code design tokens, claude code design system 입니다. 공식 자료는 MDN CSS custom properties, MDN var(), MDN prefers-color-scheme 를 참고하세요. Claude Code에게는 목표, 수정 금지 범위, 유지할 디자인 규칙, use case, pitfall을 명확히 전달해야 합니다.

토큰을 계층으로 나누어 생각하기

개념도로는 다음 순서로 생각하면 무너지지 않습니다.

팔레트 토큰: --blue-600 같은 날것의 색이나 수치
시맨틱 토큰: --color-accent 같은 의미를 가진 값
컴포넌트 토큰: --button-bg 같은 부품 단위의 덮어쓰기
상태 토큰: dark, danger, compact처럼 상황에 따른 교체

이렇게 나누면 나중에 브랜드 색을 바꿔도 --blue-600 한 곳만 고치면 되고, 다크 모드는 시맨틱 토큰만 교체하면 됩니다. Claude Code에게는 “무엇을 토큰화할지”, “어디까지 덮어쓰기를 허용할지”, “fallback을 반드시 넣을지”를 먼저 지정합니다.

Claude Code 프롬프트

가장 작은 안전한 변경으로 이 UI 개선을 구현해 주세요.
기존 라우트, 컴포넌트 구조, design token, 주요 CTA를 유지해 주세요.
복사해서 실행 가능한 코드, use case, pitfall, 모바일 확인, rollback 방법을 주세요.
마지막에 사람이 확인할 review checklist를 작성해 주세요.

Use case checklist

콘텐츠 사이트: 관련 글, 검색, 상담 버튼, 다운로드 링크를 더 쉽게 찾게 합니다.
SaaS 화면: 조작 경로를 줄이되 키보드, 모바일, 오류 상태를 유지합니다.
상품 페이지: 가격, 구매 버튼, 광고, 폼을 가리지 않습니다.
팀 개발: Claude Code가 코드와 review checklist를 함께 남겨야 합니다.

구현 예시

:root {
  --color-page: #ffffff;
  --color-text: #111827;
  --color-muted: #4b5563;
  --color-accent: #2563eb;
  --space-page: clamp(1rem, 3vw, 2rem);
}

[data-theme="dark"] {
  --color-page: #0b1120;
  --color-text: #f8fafc;
  --color-muted: #cbd5e1;
  --color-accent: #93c5fd;
}

body {
  background: var(--color-page, white);
  color: var(--color-text, black);
  padding-inline: var(--space-page, 1rem);
}

a {
  color: var(--color-accent, blue);
}

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

var() fallback을 반드시 넣기

var()의 두 번째 인수는 fallback입니다. 예를 들어 var(--surface, #ffffff)는 --surface가 정의되지 않았거나 사용할 수 없는 값일 때 #ffffff를 씁니다. 토큰을 외부 CSS나 테마 파일에서 주입하는 구조에서는, 어떤 이유로 토큰이 비었을 때 화면이 새하얗게 깨지는 사고를 막아 줍니다. Claude Code에게는 “주요 색과 배경에는 반드시 var() fallback을 넣어 줘”라고 미리 지정하면, 생성 코드의 안정성이 올라갑니다.

다크 모드는 [data-theme="dark"] 같은 명시적 토글과 @media (prefers-color-scheme: dark)의 OS 설정을 함께 다룹니다. 사용자가 직접 고른 테마를 localStorage에 저장하고, 저장된 값이 없을 때만 OS 설정을 따르게 하면 두 방식이 충돌하지 않습니다. 두 모드 모두에서 본문, 보조 텍스트, 링크의 대비가 읽기 쉬운지 반드시 확인합니다.

Pitfall checklist

예쁜 스크린샷만 보고 판단하지 않습니다.
긴 텍스트, 코드 블록, 표가 모바일에서 가로 스크롤을 만들지 확인합니다.
색상만으로 상태를 표현하지 말고 텍스트와 focus 표시를 남깁니다.
커스텀 프로퍼티는 값에만 쓰고, 선택자나 속성 이름에는 쓰지 않습니다.
Claude Code가 관련 없는 파일을 고치지 않게 합니다.
375px 모바일, 키보드 조작, 느린 네트워크, 오류 상태를 확인합니다.

검증 방법

build 후 모바일 폭에서 overflow를 확인합니다. 코드 블록이 스크롤되는지, CTA가 보이는지, 폼과 광고가 가려지지 않는지 봅니다. 라이트 모드와 다크 모드를 전환하며 대비가 충분한지도 함께 봅니다. Claude Code에게 두 번째 review pass를 요청해 변경 파일, 위험, 삭제 가능한 코드, rollback 방법을 받습니다.

수익화 관점

이 주제는 광고 viewability, 상담 버튼, 상품 카드, 가격표, lead form과 연결됩니다. 팀 프로세스로 만들고 싶다면 Claude Code 교육과 상담에서 구현, review, 배포 확인을 반복 가능한 흐름으로 만들 수 있습니다.

추가 확인

배포 전 스크린샷, 키보드 조작, 모바일 폭, 느린 네트워크, 오류 상태, CTA 위치를 같은 checklist에 넣습니다. 이렇게 해야 Claude Code의 결과가 코드뿐 아니라 실제 비즈니스 결과와 연결됩니다. Claude Code가 방금 작성한 코드라도 삭제할 수 있는 복잡도는 삭제하는 편이 좋습니다.

실전 검증 메모

글 페이지와 관리 화면에서 모바일 폭, 코드 블록, CTA, 키보드 조작을 확인했습니다. 토큰을 팔레트, 시맨틱, 컴포넌트로 나누고 var() fallback을 먼저 넣어 두니, 다크 모드를 추가할 때 고칠 곳이 줄었습니다. 구현과 리뷰를 분리해서 Claude Code에 맡기는 방식이 diff가 작고 안정적이었습니다.