Claude Code로 디자인 시스템 사양을 강제해 UI 품질 높이기

디자인 토큰을 Claude의 헌법으로 등록하기

주니어 개발자가 만든 UI가 투박한 이유는 디자인 결정이 그때그때 다르기 때문입니다. Claude Code 같은 AI 에이전트는 기준점이 없으면 대충 평균적인 스타일을 내뱉습니다. 프로젝트 초기에 AI가 반드시 지켜야 할 규칙, 즉 디자인 토큰을 시스템에 박아넣어야 합니다. METR의 2025년 생산성 보고서에 따르면, 토큰 기반 자동화 워크플로우를 도입한 팀은 디자인 시스템 구축 시간을 80% 줄였습니다.

먼저 .claudecode/context/theme.json 파일을 만드십시오. 여기에 OKLCH 색상 체계와 4px 단위의 간격 스케일을 정의합니다. 그다음 CLAUDE.md 파일에 "Inter 같은 흔한 폰트 대신 브랜드 전용 폰트를 사용하고, 시각적 대비를 강하게 주라"는 지침을 추가합니다. Tailwind CSS 설정과 이 토큰을 연동하면 AI가 컴포넌트를 만들 때마다 정의된 변수만 꺼내 쓰게 됩니다. 이렇게 기본값만 잘 잡아둬도 매주 CSS 수정에 쏟는 시간을 5시간 이상 아낄 수 있습니다.

검증된 서비스의 레이아웃 구조를 이식하는 프롬프트 체인

디자인 감각이 없다면 이미 잘 만든 서비스를 해체해서 내 것으로 만드는 게 가장 빠릅니다. 단순히 코드를 복사하는 게 아니라, Shadcn UI 같은 검증된 라이브러리 구조 위에 레이아웃만 얹는 방식입니다. 이 기법을 쓰면 신규 페이지 프로토타이핑 속도가 이전보다 3배 이상 빨라집니다.

브라우저 개발자 도구 콘솔에서 getComputedStyle()을 실행하거나 Firecrawl로 목표 사이트의 간격과 그리드 값을 추출하십시오. 추출한 데이터를 Claude Code에게 던지며 "이 구조를 Shadcn UI 프리미티브를 사용해 Tailwind v4 기반 React 컴포넌트로 재구성하라"고 명령합니다. 사양서는 docs/research/components/ 폴더에 넣어두고, 하위 에이전트들이 이를 참고해 페이지를 조립하게 만듭니다. 이렇게 하면 겉모양은 세련된 레퍼런스를 닮으면서도 내부 코드는 Next.js 16 서버 컴포넌트에 최적화된 결과물이 나옵니다.

린트 규칙에 디자인 휴리스틱 검수 통합하기

AI는 겉보기에 화려한 UI를 순식간에 찍어내지만, 접근성이나 세밀한 UX는 자주 놓칩니다. AI 생성 코드의 66%가 전문적인 검토 없이는 결함을 포함한다는 통계도 있습니다. 시각적 결함으로 인한 QA 수정 요청을 40% 이상 줄이려면 검수 과정을 자동화해야 합니다.

.claude/skills 폴더에 닐슨 노먼의 10가지 휴리스틱을 반영한 SKILL.md 파일을 만드십시오. 여기에 /audit-ux라는 커스텀 명령어를 등록합니다. 이 명령어가 실행될 때 모달의 포커스 트랩이 작동하는지, 텍스트 대비가 4.5:1을 넘는지, ARIA 레이블이 적절한지 훑게 만듭니다. 검수를 통과하지 못한 코드는 프리커밋 훅에서 커밋 자체가 안 되도록 막으십시오. 사람이 일일이 눈으로 확인하는 것보다 훨씬 확실합니다.

시각적 회귀 테스트로 디자인 부채 관리하기

프로젝트가 커지면 여기저기서 튀어나오는 중복 CSS와 일관성 없는 패턴이 발목을 잡습니다. 디자인이 바뀔 때마다 전체 코드를 갈아엎는 건 미련한 짓입니다. 변경된 부분만 골라 반영하는 증분 업데이트 전략이 필요합니다.

Playwright나 Chromatic을 Claude Code와 연결해 UI 스냅샷을 픽셀 단위로 비교하는 환경을 만드십시오. 디자인 수정이 필요할 때 AI에게 "기존 디자인 토큰은 유지하되 테두리 반경 값만 전역적으로 업데이트하고, 영향받는 컴포넌트를 리팩토링하라"고 시킵니다. AI가 코드 리뷰 과정에서 정의되지 않은 색상을 사용한 코드를 찾아내도록 설정하면 디자인 원칙이 무너지는 걸 막을 수 있습니다. 레이아웃이 깨질까 봐 걱정하며 코드를 고치던 스트레스에서 벗어나는 게 핵심입니다.