🎨 11. CSS 변수: '유지보수 가능한 디자인 시스템의 심장'

📌 이 문서를 읽기 전에

⏱️ 예상 읽기 시간: 9분(전체) / 핵심 파트만: 5분

🗺️ 이 문서의 흐름
[CSS 변수의 문법] → [Scoped 변수와 테마 전환] → [JS와 CSS의 다리 놓기]

🎯 이 문서를 다 읽으면 할 수 있는 것

• :root를 넘어 특정 컴포넌트 단위로 변수를 정의하고 활용합니다.
• 다크 모드와 브랜드 컬러 전환을 단 몇 줄의 CSS로 구현합니다.
• 자바스크립트에서 CSS 변수를 실시간으로 조작해 동적인 효과를 만듭니다.

🗺️ 이 문서의 배경 세계관: '영수네 커뮤니티'

• 🐣 영철 (후반부 실무자): "영호 님! 영숙 디자이너 님이 브랜드 블루 컬러를 살짝 연하게 바꿔달라고 하셨어요. 그런데 프로젝트 전체에 같은 색상값이 여러 곳에 직접 들어가 있어서 변경 범위를 확인하기 어렵습니다."
• 🦁 영호 (리드): "이제 토큰으로 관리할 시점이에요. 색상을 이름표(변수)로 관리했다면, 그 이름표의 값 하나만 바꿔도 관련 컴포넌트가 함께 바뀝니다. 디자인 시스템의 첫걸음인 CSS 변수를 배워봅시다."

🤔 왜 알아야 하는가

CSS 변수(Custom Properties)는 단순한 편의 기능이 아니라 '시스템' 을 구축하는 도구입니다. 예전에는 SASS 같은 전처리기를 써야만 변수를 쓸 수 있었지만, 이제 CSS 표준 변수는 그보다 훨씬 강력한 기능을 제공합니다.

가장 큰 차별점은 런타임성 입니다. SASS 변수는 빌드하고 나면 사라지지만, CSS 변수는 브라우저에서 실시간으로 값을 바꿀 수 있죠. 5년차 이상의 시니어는 이를 활용해 다크 모드 처럼 복잡한 스타일 전환을 조건부 클래스 없이 우아하게 해결합니다.

🏗️ 1. CSS 변수의 기본과 스코프(Scope)

다음 코드는 전역 토큰과 컴포넌트 토큰의 차이를 보여줍니다. 같은 버튼 코드라도 부모가 어떤 변수 값을 제공하느냐에 따라 색상이 달라집니다.

/* 1. 최상단(Global) 선언 */
:root {
  --primary-color: #3b82f6;
}
 
/* 2. 컴포넌트(Local) 선언 - 오버라이드 가능 */
.card--featured {
  --primary-color: #f59e0b; /* 이 카드 내부에서만 primary 의미를 재정의합니다. */
}
 
/* 3. 사용 */
.btn {
  background-color: var(--primary-color, #3b82f6);
}

var(--primary-color, #3b82f6)의 두 번째 값은 fallback입니다. 변수가 아직 정의되지 않은 범위에서도 버튼이 읽을 수 있는 색을 유지하게 해줍니다.

🦁 영호의 핵심 레슨:
"변수는 상속됩니다! 부모 요소에서 변수 값을 바꾸면 자식 요소들이 일제히 그 바뀐 값을 쓰게 되죠. 이게 바로 테마 전환의 핵심 원리입니다."

🌙 2. 다크 모드: if문 없는 테마 전환

과거처럼 모든 컴포넌트에 .dark .btn 처럼 서브 클래스를 만들 필요가 없습니다.

:root {
  --bg: #ffffff;
  --text: #000000;
}
 
[data-theme="dark"] {
  --bg: #000000;
  --text: #ffffff;
}
 
body {
  background: var(--bg);
  color: var(--text);
}

🐣 영철: "이제 body의 변수 값만 바꾸면 하위 컴포넌트가 같은 토큰 이름을 유지한 채 테마를 따라가네요. 다크 모드가 조건문보다 설계 문제에 가깝다는 게 보입니다."

🔗 3. JS와의 강력한 콜라보레이션

CSS 변수는 자바스크립트로도 실시간 접근이 가능합니다.

/* 마우스 위치에 따라 변수 값을 실시간으로 변경 */
document.documentElement.style.setProperty('--mouse-x', `${e.clientX}px`);

🦁 영호의 디테일:
"사용자가 입력한 설정값을 CSS에 바로 반영하고 싶을 때 유용하죠. CSS의 선언적인 특성과 JS의 동적인 특성을 연결하는 튼튼한 다리입니다."

📝 마무리 퀴즈

Q1. CSS 변수를 선언할 때 이름 앞에 반드시 붙여야 하는 기호는 무엇인가요?

✅ 정답: -- (이중 하이픈)

💡 상세 해설:

• 원리: CSS 표준 명세에 따라 사용자 정의 속성(Custom Properties)은 반드시 --로 시작해야 합니다. 이를 통해 기존의 표준 CSS 속성과 명확히 구분됩니다.
• 오답 피드백: "영철 님, 달러($) 기호는 SASS 전용이에요! 브라우저가 알아듣게 하려면 하이픈 두 개를 꼭 기억하세요."

Q2. CSS 변수가 SASS 변수보다 뛰어난 결정적인 장점은 무엇인가요?

1. 컴파일 속도가 빠르다.
2. 브라우저에서 런타임에 값을 변경할 수 있다.
3. 모든 브라우저에서 100% 지원된다.
4. 더 복잡한 수학 연산이 가능하다.

✅ 정답: 2. 브라우저에서 런타임에 값을 변경할 수 있다.

💡 상세 해설:

• 원리: SASS 변수는 빌드 시점에 정적인 값으로 치환되지만, CSS 변수는 자바스크립트나 미디어 쿼리 등을 통해 실시간으로 값을 바꿀 수 있습니다.
• 오답 피드백: "영철 님, 동적으로 변하는 다크 모드나 테마 시스템을 만들 때 CSS 변수가 압도적으로 유리한 이유가 바로 이거예요!"

Q3. [영철이의 테스트 타임: 실무 딜레마]
영철이가 버튼 하나에만 다른 색상을 적용하려고 .btn--orange { --color: orange; }를 만들었습니다. 그런데 버튼 안의 텍스트 색상이 바뀌지 않네요. 확인해보니 텍스트 색상은 var(--text-color)를 쓰고 있었습니다. 영철이가 이 버튼 안의 텍스트만 주황색으로 바꾸기 위해 가장 우아하게 할 수 있는 행동은?

✅ 정답: .btn--orange 안에서 --text-color 변수값을 orange로 재정의한다.

💡 상세 해설:

• 원리 설명: 변수는 하위 요소로 상속됩니다. 컴포넌트 레벨에서 변수값을 오버라이드하면, 해당 컴포넌트 내부의 모든 자식들이 그 새로운 값을 참조하게 됩니다.
• 오답 피드백: "영철 님, 새로운 속성을 추가하는 게 아니라 기존 정의된 '시스템 변수'를 덮어쓰는 게 디자인 시스템의 정석입니다."
• 📌 핵심 기억법: "변수를 덮어쓰는 것이 시스템을 바꾸는 것이다!"

🐣 영철이의 퇴근 일기

오늘 변수를 배우고 나니, 그동안 내가 짠 코드가 얼마나 경직되어 있었는지 알게 됐다.
색상 코드 하나 바꾸려고 Ctrl+F로 프로젝트 전체를 뒤지던 방식이 왜 위험한지 이제는 설명할 수 있다.
브랜드 컬러가 바뀌어도 토큰 값 하나를 바꾸면 관련 컴포넌트가 함께 따라오게 만드는 것이 진짜 디자인 시스템의 시작이었다.

💡 "하드코딩은 부채이고, 변수는 투자다. 나중에 고통받지 않으려면 처음부터 이름을 붙여라."

퇴근길에 오늘 만든 다크 모드 스위치를 계속 눌러봤다.
코드 몇 줄로 화면 전체의 분위기가 일관되게 바뀌는 게 인상적이었다.
다음 PR부터는 #3b82f6 같은 값이 컴포넌트 안에 직접 들어오면 "이 색은 어떤 토큰이어야 하지?"라고 먼저 물어볼 생각이다.
내일 CSS 아키텍처를 볼 때도 클래스 이름보다 먼저 팀이 공유할 수 있는 규칙과 변경 비용을 생각해봐야겠다.

🔗 더 알아보기

• MDN: CSS 사용자 정의 속성 사용하기
• Web.dev: CSS Variables 가이드