@gpters-internal/ui - Design System

1. 문제의 본질: 일관성의 붕괴

디자인 시스템의 가치는 일관성에서 나온다. 버튼의 모서리 반경이 4px인지 8px인지, 기본 간격이 16px인지 20px인지—이런 세부사항들이 모여 브랜드의 시각적 정체성을 형성한다.

전통적인 개발 환경에서는 디자이너가 Figma에서 정의한 값을 개발자가 수동으로 옮겼다. 이 과정에서 오류가 발생했고, 코드 리뷰가 그것을 걸러냈다. 느리지만 작동했다.

AI 코드 생성 도구의 등장은 이 균형을 깨뜨렸다. AI는 "적당해 보이는" 값을 즉흥적으로 생성한다.padding: 12px가 시스템에 없는 값이라는 것을, AI는 알지 못한다.

"AI가 생성한 코드의 양이 인간의 리뷰 능력을 초과하는 순간, 시스템적 제약만이 일관성을 보장할 수 있다."

2. 하드코딩 금지: 토큰 시스템의 강제

design-rules.md의 첫 번째 규칙은 단순하다:CSS 변수만 사용하라.

금지

css

/* 하드코딩된 값 */
.button {
  background: #3b82f6;
  padding: 8px 16px;
  border-radius: 6px;
}

허용

css

/* 토큰 참조 */
.button {
  background: var(--color-primary);
  padding: var(--spacing-2) var(--spacing-4);
  border-radius: var(--radius-md);
}

이 규칙이 중요한 이유는 변경 전파 때문이다. 브랜드 색상이 바뀌면 tokens.css의 한 줄만 수정하면 된다.

더 근본적으로, 토큰은 의미적 추상화를 제공한다.#3b82f6는 "파란색"이지만,var(--color-primary)는 "이 요소가 주요 액션임"을 선언한다.

3. Generation Protocol: 4단계 검증 체계

규칙을 정의하는 것과 규칙을 강제하는 것은 다른 문제다. Generation Protocol은 AI가 코드를 생성하기 전에 스스로 검증하도록 설계되었다.

토큰 검사

생성할 코드의 모든 색상, 간격, 폰트, 반경 값이 tokens.css에 정의되어 있는지 확인한다. 하드코딩된 값이 발견되면 생성을 거부한다.

컴포넌트 확인

요청된 UI가 기존 컴포넌트로 구현 가능한지 확인한다. Button, Input 등 이미 존재하는 컴포넌트를 처음부터 다시 만들지 않는다.

표현 검증

"적당히", "예쁘게", "모던하게" 같은 모호한 지시가 있으면 구체적인 사양을 요청한다. 해석의 여지를 남기지 않는다.

생성 또는 거부

모든 검증을 통과하면 코드를 생성한다. 하나라도 실패하면 이유를 설명하고 생성을 거부한다.

이 프로토콜의 핵심은 "거부할 수 있는 AI"를 만드는 것이다. 대부분의 AI 도구는 어떤 요청이든 최선을 다해 응답한다. 그러나 디자인 시스템의 맥락에서, "최선의 추측"은 종종 시스템을 오염시킨다.

4. Claude Code 통합: Skill로서의 규칙

design-rules.md는 단순한 문서가 아니다. Claude Code의 Skill로 등록되어, 특정 조건에서 자동으로 에이전트의 컨텍스트에 주입된다.

┌─────────────────────────────────────────────────────────┐
│                    Claude Code Agent                     │
│                                                          │
│  ┌──────────────┐    ┌──────────────┐    ┌────────────┐ │
│  │ User Prompt  │───▶│ Skill Loader │───▶│  Context   │ │
│  │              │    │              │    │  Window    │ │
│  │ "버튼 만들어" │    │ Trigger:     │    │            │ │
│  └──────────────┘    │ UI/컴포넌트   │    │ + rules   │ │
│                      │ 생성 감지     │    │ + tokens  │ │
│                      └──────────────┘    └────────────┘ │
└─────────────────────────────────────────────────────────┘

Skill 등록 구조

.claude/skills/design-rules.md 파일은 다음과 같은 메타데이터로 시작한다:

yaml

---
description: UI/컴포넌트 생성 시 자동 적용되는 디자인 규칙
triggers:
  - UI
  - 컴포넌트
  - 버튼
  - 폼
  - 레이아웃
---

5. Hook을 통한 사후 검증

Skill이 "사전 주입"이라면, Hook은 "사후 검증"이다.PostToolUse Hook은 에이전트가 파일을 생성한 직후 실행된다.

json

// .claude/settings.json
{
  "hooks": {
    "PostToolUse": [{
      "matcher": "Write",
      "command": "node .claude/scripts/validate-tokens.js $FILE"
    }]
  }
}

이 Hook은 생성된 파일에서 하드코딩된 색상값(#으로 시작하는 hex 코드)이나 토큰에 없는 px 값을 검출한다. 위반이 발견되면 경고를 출력하고, 심각한 경우 커밋을 차단할 수 있다.

6. 제약의 역설: 자유를 위한 규칙

얼핏 보면 design-rules.md는 개발자의 자유를 제한하는 것처럼 보인다. 원하는 색상을 쓸 수 없고, 원하는 간격을 줄 수 없다.

그러나 이 제약은 역설적으로 더 큰 자유를 가능하게 한다:

•
의사결정 피로 감소: "이 버튼의 패딩을 몇 px로 할까?"라는 질문을 할 필요가 없다.
•
리뷰 시간 단축: 토큰만 사용했는지 확인하면 된다. 시각적 일관성은 시스템이 보장한다.
•
안전한 실험: 토큰 값을 변경해서 전체 시스템의 룩앤필을 한 번에 바꿀 수 있다.
•
AI 협업 가능: 명확한 제약이 있어야 AI가 "올바른" 코드를 생성할 수 있다.

결론

AI 코드 생성 도구가 보편화되면서, 디자인 시스템의 역할은 "참고 자료"에서 "강제 규칙"으로 변화하고 있다. design-rules.md는 이 변화의 구체적인 구현이다.

토큰 시스템, Generation Protocol, Skill 통합, Hook 검증—이 모든 요소가 결합되어 "AI가 실수하기 어려운 환경"을 만든다. 인간 개발자의 리뷰 부담을 줄이면서, 동시에 디자인 일관성을 보장한다.

이것이 design-rules.md가 존재하는 이유다.

Why Design Rules Exist