나만의 디자인 시스템, Claude Code로 ‘쉽게 잘’ 적용해보고 싶었다.

들어가는 글

셀프 브랜딩에는 관심이 꽤 있어서, 블로그나 개인 프로젝트에 걸쳐 일관된 톤과 무드를 갖고 싶다는 생각을 오래 해왔다. 그래서 나만의 디자인 시스템을 하나 만들었는데, 만들고 나니 새로운 문제가 생겼다. 디자인 시스템을 정의해두니 여러 프로젝트에서 이걸 '쉽게' 가져다 쓸 수 있는가?에 대한 의문이 피어났다.

이 글은 어떤 방법들을 고민해봤고 그 중 무엇을 채택하고 기각했는지, Skill을 어떤 기준으로 설계했는지, 그리고 실제로 적용해보고 나서 사후 질문들을 정리한 개인적인 실험을 공유하고자 한다.

다음 중 하나에라도 해당하는 독자라면, 이 글이 참고가 되었으면 하는 염원이 있다.

• 개인 프로젝트에 쓸 디자인 시스템을 어떤 구조로 관리할지 고민 중인 사람
• Claude Code Skill을 실제 워크플로우에 적용해본 사례가 궁금한 사람
• 백엔드 개발자가 디자인/프론트엔드 영역에 처음 발을 들이는 과정이 궁금한 사람

디자인 시스템부터 간단히 정의해보기!

평소 백엔드 위주로 일해와서 디자인이나 프론트엔드 작업은 익숙한 영역이 아니었지만 조금씩 알고 있던 아이디어를 모아서 디자인 시스템부터 구축해보고자 시도했다.

만들어둔 디자인 시스템은 아주 거창하진 않다. 색상, 폰트, 톤 같은 정체성 요소들을 한 곳에 정의해두고, 여러 프로젝트에서 재사용하고 싶었을 뿐이다. 토큰 정의를 중심으로 시작했고, 컴포넌트는 card, btn, callout, timeline처럼 자주 쓰는 몇 가지 최소 단위만 다뤘다.

다음은 정의해본 디자인 시스템의 일부다.

css
/* ─── Base palette ─────────────────────────────────────── */

:root {
  --bg:      #f6f2eb;  /* 크림 배경 */
  --surface: #edeae2;  /* 카드/서피스 */
  --border:  #e4ddd0;  /* 구분선 */
  --muted:   #9a9590;  /* 보조 텍스트 */
  --text:    #282420;  /* 본문 오프블랙 */
  --accent:  #3d5a80;  /* 슬레이트블루 */
  --accent2: #b85c38;  /* 테라코타 */
}

.dark {
  --bg:      #0d1117;
  --surface: #161b22;
  --border:  #21262d;
  --muted:   #555e6a;
  --text:    #e8e0d0;
  --accent:  #4a7fa5;
  --accent2: #c9b48a;
}

css
/* ─── Font families ─────────────────────────────────────── */

:root {
  --font-sans:  "Pretendard", sans-serif;
  --font-serif: "Maru Buri", serif;
}

본격적인 컴포넌트 확장까지는 아직 UI나 디자인을 잘 모르기도 하고 여력이 없다고 판단, 다음 과제로 남겨두었다.
그렇게 다소 작고 귀여운(?) 나만의 디자인 시스템이 탄생하였다.

예시 레포: https://github.com/liza0525/design-system

디자인 시스템 적용하는 step by step

정의한 디자인을 내 작업에 어떻게 적용할 것인가

디자인을 정의하는 것과 별개로, 구축한 디자인 시스템을 여러 프로젝트에 쉽게 끌어다 쓰는 것은 다른 문제였다. 이에 몇 가지 방법을 검토하고 기각하는 과정을 거쳤다.

• Storybook급 도구: 기업에서 쓰는 규모의 디자인 시스템 관리 도구는 지금 상황엔 명백한 오버 스킬이라 생각하여 제외했다.
• API 서버: 처음엔 디자인 시스템을 API로 끌어오는 방식도 생각했다. 하지만 결국 토큰이나 스타일 같은 정적인 값을 가져다 쓰는 것뿐인데, 그걸 위해 서버까지 두는 것 또한 오버 엔지니어링이라고 판단했다.
• npm 패키지 배포: 배포 없이 로컬에서만 쓰는 방법(npm link, file: 프로토콜 등)이 있다는 것도 알게 되었다. 하지만 이 방식들은 같은 로컬 머신 안에서만 유효하다.
  블로그는 이미 Next.js + Vercel로 배포되고 있어서, 빌드 시점에 원격에서 디자인 시스템 파일에 접근할 수 있어야 했다. 결국 로컬 편의성보다는 "여러 환경(로컬 + 배포 파이프라인)에서 동일하게 재현 가능해야 한다"는 조건이 더 중요했다.
• git submodule: 같이 일했던 프론트엔드 개발자 동료가 "이런 거 써본 적 있어요?"라고 지나가듯 물어봐준 게 생각이 났다. 한 번도 써본 적 없는 git 명령어였지만, 디자인 시스템 코드도 결국 코드의 일부고 레포 단위로 묶여있어야 한다는 점에서 submodule이 맞다고 판단했다.

반복 작업을 Claude Code Skill로

git submodule를 사용하기로 결정하니 새로운 고민이 생겼다. 프로젝트에 디자인 시스템을 반영하려면 매번 명령어로 쳐야 해서, 번거롭게 느껴졌다. 이 정도의 자동화는 필요하다는 생각에 좀 더 세부적인 고민을 했었다.(귀찮음은 어쩔 수 없다!)

가장 중요하다고 생각한 것

자동화하는 과정에서 설계하면서 한 가지 원칙을 세웠다. ‘디자인 시스템을 적용하는 결정 자체’는 자동화하지 않는다는 것. 이건 프로젝트마다 디자인 시스템 적용 여부를 고민해야 하는 ‘인간의 판단’이 들어가야 하기 때문이라고 생각했다.

고려했던 세 가지 방법

git submodule 명령어를 실행하는 일종의 entrypoint를 고려해야 했다. 이때 고민 했던 것은 README.md에 작성할 지 CLAUDE.md에 작성할 지, Claude Code Skill로 정의할 지에 대한 판단이었다.

• README.md는 사람이 읽는 문서다. 여러 프로젝트에 반복 적용하려면 결국 매번 사람이 복사하거나 실행해야 해서 자동화 효과가 없다.
• CLAUDE.md는 Claude Code가 "이 프로젝트가 어떻게 생겼는지"를 상시로 파악하기 위한 컨텍스트다. 여기에 "이럴 땐 이 명령어나 Skill을 써라" 같은 절차를 적는 건 목적에 맞지 않다고 판단했다.
• Claude Code Skill로 디자인 시스템 적용 방안을 정의하면, git submodule 실행부터 디자인 시스템 가이드라인 파악, CSS 토큰 적용까지 이어지는 과정 자체는 자동화할 수 있다. 다만 이 흐름을 지금 이 프로젝트에 실제로 실행할지는 자동화 영역이 아니라고 판단했다. 그 실행 여부는 사람이 그때그때 직접 판단하고 직접 트리거하도록 하고 싶었기 때문이다.

Claude Code Skill 정의

이 과정을 Claude Code Skill로 만들었다. 필자의 컴퓨터 세팅이었고, 프로젝트마다 Skill을 새로 설정하는 게 비효율적이라고 생각해서 ~/.claude/skills/ 아래 글로벌로 설치했다.

실제 Skill 정의는 다음과 같다.

markdown
---
name: lizzie-design
description: Add Lizzie's personal design system to a project as a git submodule and load its context. Trigger this whenever the user wants to apply, install, integrate, or set up the design system in a new or existing project, mentions "디자인 시스템 적용", "design system submodule", or asks to bring in design-system.md context. Make sure to use this skill even if the user just says something like "이 프로젝트에 디자인 시스템 추가해줘" without explicitly mentioning git or submodule.
---

# Design System Submodule Setup
Lizzie의 개인 디자인 시스템 레포를 프로젝트에 git submodule로 추가하고, 컨텍스트 파일(design-system.md)을 읽어 요약하는 스킬입니다.

## Repo
https://github.com/liza0525/design-system.git

## Steps
1. 프로젝트 루트에서 submodule 추가:
git submodule add https://github.com/liza0525/design-system.git design-system
git submodule update --init --recursive

2. `design-system/design-system.md`(또는 유사한 컨텍스트 파일)가 존재하는지 확인하고,
   있다면 읽어서 다음을 요약해 사용자에게 보여줄 것:
   - 폰트(제목용/본문용) 및 사용 용도
   - 컬러 팔레트
   - 톤 & 보이스 가이드라인
   - 기타 컴포넌트/레이아웃 규칙

3. 요약 후, 이후 작업(컴포넌트 생성, 스타일링 등)에서
   이 컨텍스트를 기준으로 일관된 톤을 유지할 것.

## Notes
- design-system.md 파일이 없으면 사용자에게 어떤 파일을 컨텍스트로 쓸지 물어볼 것.
- submodule 경로는 항상 프로젝트 루트의 `design-system/`로 고정.
- 이미 `design-system/` 디렉토리가 존재하면 덮어쓰지 말고 사용자에게 확인할 것.

## Local CLAUDE.md 업데이트
submodule 추가 및 design-system.md 요약이 끝나면, 현재 프로젝트 루트에
`CLAUDE.md`가 있는지 확인할 것.
- 있다면: 아래 섹션이 이미 있는지 확인 후, 없으면 추가
- 없다면: 새로 생성하고 아래 섹션 추가

  ## Design System
  이 프로젝트는 `design-system/` 디렉토리에 디자인 시스템을 git submodule로 포함하고 있다.
  UI/스타일 관련 작업을 할 때는 항상 `design-system/design-system.md`를 먼저 읽고
  그 안의 폰트, 컬러 팔레트, 톤 가이드를 따를 것.

기존 프로젝트 CLAUDE.md에 다른 내용이 이미 있다면 덮어쓰지 말고 해당 섹션만 추가/병합할

여기서 핵심은 단순히 git submodule add 명령을 대신 쳐주는 게 아니라는 점이다. design-system.md를 읽어 요약까지 해주고, 그 결과를 CLAUDE.md에 기록해서 세션이 끝나도 지속되는 컨텍스트를 만든다.

이미 존재하는 디렉토리는 덮어쓰지 않고 확인하게 하거나, design-system.md가 없을 때는 사람에게 물어보게 한 것도 의도적이다. 한 번 쓰고 버리는 스크립트가 아니라, 반복 실행해도 안전하고 판단이 필요한 지점은 사람에게 넘기는 도구를 만들고 싶었다. 즉 이 Skill이 하는 일은 "명령어를 아껴주는 것"이 아니라, "디자인 시스템을 파악하는 과정 자체"를 자동화하는 것에 가까워졌다.

이렇게 Skill을 정의하고 나니, /lizzie-design 이라는 슬래시 명령어로 나만의 디자인 시스템을 받아와서 디자인 가이드를 확인하고 토큰을 적용하기까지 자동으로 되는 것을 확인하였다.

실제로 써보니

좋았던 점은 크게 세 가지다.

• 디자인 시스템을 바꾸면, 이후 Claude Code로 블로그를 개발할 때 스타일 관련 판단에 인간이 직접 개입하는 일이 줄었다.
• 그리고 디자인 및 스타일 관련 코드가 블로그 코드베이스와 분리되어 독립적으로 관리 가능해졌다.
• 귀찮을 거라 예상하는 명령어 치는 과정과 디자인 맥락 파악 과정을 명령어 하나(Skill)로 통합할 수 있었다. (편-안)

Skill에서 정의했던 디자인 시스템 요약의 정확도나 CLAUDE.md 병합도 기대한 대로 잘 동작했다. 원하는 동작과 함께 다음과 같이 블로그 디자인에도 변화가 생겼다는 것을 체감했다.

사후에 스스로에게 던져본 네 가지 질문

여기까지의 판단들이 그럴듯해 보이긴 하지만, 이게 정말 괜찮은 방법인지 평가할 기준은 딱히 없었다. 개인적인 실험에 가까운 이 선택들을 검증해보려면, 더 다양한 관점에서의 질문들이 필요하다고 생각했다. 이에 따라 Claude에게 역질문을 요청하고 함께 질의응답을 해보았다.

굳이 git submodule과 Skill까지 써야 했을까? 그냥 파일을 복붙하면 안 됐을까?

파일 복붙도 고려했지만, 앞으로 다른 레포에도 적용할 걸 생각하면 매번 반복하는 게 귀찮아질 거라 예상했다. 그래서 이 정도의 자동화는 필요하다고 판단했다.

또한 디자인 시스템을 업데이트 할 때마다 관리를 할 수 있어야 했다. 아무래도 깃허브로 하는 형상 관리가 가장 쉬웠기 때문에 채택한 이유도 있다.

다만 지금 실제로 적용된 프로젝트는 블로그 하나뿐이다. 이 판단이 맞는지는 반복이 실제로 여러 번 일어나야 확인할 수 있는데, 지금은 아직 그 지점까지 가보지 못했다. 그래서 이 자동화가 YAGNI에 기반한 오버엔지니어링일 가능성도 열어두고 있다. (그만큼 스스로 현재의 시스템을 더 많이 쓰려고 노력해야겠다.)

md에 적용 가이드라인으로 명령어들을 적어두고 터미널에서 커맨드를 직접 치면 안 됐을까?

md 중에서도 CLAUDE.md에 적는 것 또한 고민했었다. 하지만 CLAUDE.md는 Claude Code가 프로젝트 구조를 파악하기 위한 상시 컨텍스트일 뿐, 어떤 Skill이나 명령어를 써야 하는지 매번 보여줄 이유는 없다고 봤다. Skill을 실행할지 말지는 결국 사람이 그때그때 판단하는 문제이기 때문이다. 어떤 프로젝트는 애초에 이 디자인 시스템을 적용하지 않을 수도 있기 때문이다.

디자인 시스템 버저닝, 적용 프로젝트가 하나뿐인데 이것 또한 너무 앞서간 설계 아닐까?

이건 실제로 겪은 작은 경험에서 나온 고민이다. 디자인 시스템을 적용해보고 나니 마음에 안 드는 부분이 있어서 수정하고 다시 적용하는 과정을 거쳤다. 지금은 프로젝트가 하나뿐이라 문제가 안 되지만, 여러 레포가 이 디자인 시스템에 자동으로 의존하게 된다면 디자인 시스템 쪽의 변경 하나가 다른 프로젝트들의 스타일을 예고 없이 깨뜨릴 수 있다. (디자인 시스템에 대한 의존성이 생겼기 때문에 가능한 일이라고 생각한다.)

이런 전파는 자동으로 일어나면 안 된다고 생각했다. 스타일 변경을 다른 프로젝트에 반영할지 말지는 사람이 판단해야 하는 영역이다. 그래서 어느 정도 마음에 드는 스타일이 나온 시점에 첫 태그(0.0.1)를 붙였다. 따라서 이는 앞선 설계가 아닌 일종의 ‘가드레일’이라고 생각한다.

이 구조, 다른 사람이나 팀에도 이식 가능할까?

지금 구조는 필자 개인에게 맞춰진 것이라, 타인이 사용하겠다고 하면 비슷한 플로우로 사용해도 괜찮을 것 같다. 다만 팀이 그대로 가져다 쓰긴 어렵다고 본다. 팀 단위로 이식하려면 다음의 체크리스트에 대한 대답이 선행되어야 한다고 생각한다.

• Skill을 어떻게 관리·공유할지부터 논의가 필요하고, 애초에 디자인 시스템 적용에 Claude Code Skill이 꼭 필요한지도 다시 따져봐야 한다.
• 팀에서는 git 명령어를 직접 쓰는 게 오히려 더 명확할 수도 있다.
• 이미 대규모 디자인 시스템을 운영 중인 조직이라면, 그 조직의 컨벤션을 따라야 하니 이 구조 자체가 애초에 맞지 않을 수도 있다.

앞으로 시도해볼 것

• 디자인 시스템 레포에는 태그를 만들어 업데이트와 롤백을 용이하게 할 계획이고, 첫 태그(0.0.1)는 이미 만들어뒀다. 다만 프로젝트(현재는 블로그 작업 레포지토리) 쪽에서 이 버전을 언제, 어떤 기준으로 추적하고 업데이트할지에 대한 운영 정책 또한 함께 정의해봐야 할 것 같다.
• 작업을 해보는 도중에, 최근엔 디자인 시스템을 md 파일 형태로 손쉽게 제공하는 서비스들도 늘고 있다는 사실도 알게 되었다. 또한 디자인을 직접 도와주는 Claude Code 플러그인도 많이 나온다는 소식도 있었다. 앞으로는 이런 도구들도 참고해볼 생각이다.

마치며

디자인 시스템이라는 개념은 그동안 파편적으로만 알고 있었고 실제 경험을 해보고 싶단 생각도 해봤었다. 이렇게 스스로가 개념만 알고 있던 찰나에 AI가 급격히 발전하여 스스로 직접 만들어보고 설계 해볼 수 있는 기회가 생겼다. 덕분에 참 재미있게 이 실험에 임했었다.

‘셀프 브랜딩을 해보고 싶다’는 생각에서 시작했지만, 결국 시스템을 구축하고 결정 사항들을 고민해보는 시간을 가지며 디자인 시스템을 적용하는 과정 자체는 **‘여전히 시스템적으로 관리가 되어야 한다’**라는 결론에 도달했다. 코드나 Claude Code Skill을 작성하는 건 어느정도 AI에게 맡겼지만, (디자인이더라도) 시스템 구축, 버저닝, 이를 적용하는 운영 방안과 여러 선택의 과정에는 인간의 판단이 개입해야 하는 상황이 필수 불가결이라고 생각한다. 또한 SKILL.md에 어떤 내용을 작성할 지 고민해보는 과정은 확실한 ‘설계’의 영역이며 이 또한 개발자가 주로 하게 되는 일이 되어가는 것을 체감했다.

이번을 통해 무엇을 AI한테 맡기고 무엇을 개발자로서 판단할 수 있을지 더 생각해볼 수 있는 시간이었던 것 같다. 앞으로도 작업을 하는 데 무엇을 AI에게 맡기고 무엇을 인간이 직접 판단할지, 그 경계가 어떻게 변화할지를 스스로 더 벼려보고 싶다.