사이트 테마 토큰 도입으로 스타일 중앙화 기반 마련

사이트 테마 토큰을 정비하면서 about, contact 페이지 콘텐츠도 함께 손봤다.

왜 이 작업이 필요했나

스타일 파일과 페이지 콘텐츠가 따로 놀고 있었다. styles.css에는 색상, 간격, 타이포 관련 값들이 리터럴로 박혀 있었고, 페이지 컴포넌트들은 그걸 각자 인라인이나 클래스로 참조하는 구조. 테마 토큰이 제대로 정의되지 않은 상태에서 about.astro와 contact.astro 두 페이지가 스타일 일관성 없이 각자 방식대로 렌더링되고 있었다.

작은 프로젝트라도 이런 상태가 오래되면 나중에 테마 변경 요청 하나에 수십 곳을 뒤져야 한다. 팀원 입장에서도 "이 값 어디서 왔어요?" 질문이 반복되는 상황. 정리해야 할 타이밍이었음.

작업 내용

테마 토큰 정리

styles.css에 CSS 커스텀 프로퍼티 기반 토큰을 정리했다. 사이트 특화(site-specific) 토큰이라는 표현을 커밋 메시지에 쓴 건, 범용 디자인 시스템 수준이 아니라 이 프로젝트에 맞게 조율된 값들이라는 의미다.

:root {
  /* color */
  --color-primary: #2d2d2d;
  --color-accent:  #5c6bc0;
  --color-surface: #f7f7f8;
  --color-border:  #e0e0e0;

  /* spacing */
  --space-section: 4rem;
  --space-block:   2rem;

  /* type */
  --font-heading: 'Inter', sans-serif;
  --font-body:    'Georgia', serif;
  --text-base:    1rem;
  --text-lg:      1.25rem;
}

이렇게 뽑아두면 나중에 다크 모드 대응도 :root[data-theme='dark'] 오버라이드 한 블록으로 처리할 수 있다. 토큰 없이 리터럴 값 뿌려놨으면 다크 모드 추가할 때 전체를 다 뒤집어야 했을 거다.

페이지 콘텐츠 패치

about.astro와 contact.astro 두 파일에 콘텐츠 패치도 함께 들어갔다. 커밋 메시지의 "content patches"가 이 부분. 보통 스타일 토큰 작업과 콘텐츠 수정을 한 커밋에 묶으면 리뷰어 입장에서 컨텍스트 추적이 번거롭다고 할 수 있는데, 이번 경우는 두 페이지의 마크업 구조 자체가 토큰 적용 방식과 맞물려 있었기 때문에 분리하는 게 오히려 어색했다.

예를 들어 about.astro의 섹션 구조가 바뀌면서 --space-section 토큰이 제대로 먹히는 위치가 달라지는 식. 콘텐츠 변경이 스타일 토큰 적용의 전제 조건이었다.

회고

이런 작업은 사실 기능 티켓으로 잘 안 올라온다. "동작은 하는데 코드가 지저분하다"는 상태는 우선순위 경쟁에서 항상 뒤로 밀리기 마련이다. 결국 테크 데트가 쌓여서 나중에 팀 전체가 피보는 구조.

총괄 포지션에서 이런 작업을 언제 치고 들어가느냐가 중요하다. 마일스톤 사이 숨 돌리는 구간, 혹은 다음 기능 개발 전 기반을 다져야 할 타이밍. 이번엔 그 판단이 맞았다고 생각함. 페이지 두 개짜리 정비지만, 이후 페이지 추가나 테마 변경 요청이 들어올 때 토큰 한 줄만 바꾸면 되는 구조를 깔았다는 게 의미 있다.

코드리뷰할 때도 "이 값 왜 여기에 하드코딩했어요?"보다 "토큰 있으면 거기서 가져오면 되지 않나요?"가 훨씬 건설적인 대화다. 그러려면 팀이 공유할 수 있는 토큰 레이어가 먼저 있어야 한다. 그걸 먼저 깔아두는 게 이번 작업의 본질이었음.

끝.

🛒 이 글과 어울리는 추천 상품

• 기계식키보드 쿠팡에서 보기 →
• 모니터암 쿠팡에서 보기 →
• 외장SSD 쿠팡에서 보기 →

*위 링크는 쿠팡파트너스 활동의 일환이며, 일정액의 수수료를 제공받을 수 있습니다.