거버넌스 & 협업

디자인 시스템의 지속적인 성공은 거버넌스에 달려 있습니다. 명확한 소유권, 변경 프로세스, 품질 기준이 없으면 시스템은 점차 일관성을 잃게 됩니다.

거버넌스 구조

팀 구조

역할 정의

역할	책임	권한
DS Lead	전략, 로드맵, 의사결정	모든 변경 승인
DS Engineer	코어 개발, 리뷰	컴포넌트 머지
DS Designer	비주얼, 토큰, UX	디자인 변경 승인
Contributor	기능 기여, 버그 수정	PR 생성
Consumer	시스템 사용	이슈 생성

RACI 매트릭스

| 활동            | DS Lead | DS Engineer | DS Designer | Contributor |
| --------------- | ------- | ----------- | ----------- | ----------- |
| 토큰 변경       | A       | C           | R           | I           |
| 컴포넌트 추가   | A       | R           | C           | C           |
| 문서 업데이트   | I       | R           | C           | R           |
| 브레이킹 체인지 | R/A     | C           | C           | I           |
| 버그 수정       | I       | A           | I           | R           |

R: Responsible (수행)
A: Accountable (책임)
C: Consulted (자문)
I: Informed (통보)

변경 관리

변경 유형

변경 요청 프로세스

RFC 템플릿 (Major 변경용)

# RFC: [변경 제목]

## 요약

한 문단으로 변경 내용 설명

## 동기

왜 이 변경이 필요한가?

## 상세 설계

### 현재 상태

현재 어떻게 작동하는가?

### 제안 변경

어떻게 변경할 것인가?

### 마이그레이션 경로

기존 사용자는 어떻게 마이그레이션하는가?

## 대안

고려한 다른 방법들

## 영향

### Breaking Changes

- [ ] Props 변경
- [ ] API 변경
- [ ] 스타일 변경

### 영향받는 컴포넌트

- Component A
- Component B

## 체크리스트

- [ ] 타입 정의 업데이트
- [ ] 문서 업데이트
- [ ] 마이그레이션 가이드
- [ ] Changelog 업데이트

품질 게이트

자동화된 체크

품질 기준

// quality-gates.config.ts

export const qualityGates = {
  // 타입 검사
  typeCheck: {
    required: true,
    strict: true,
  },

  // 린트
  lint: {
    required: true,
    rules: {
      'design-system/no-hardcoded-values': 'error',
      'design-system/component-docs': 'error',
      'design-system/prop-types': 'error',
    },
  },

  // 테스트 커버리지
  coverage: {
    required: true,
    thresholds: {
      statements: 80,
      branches: 75,
      functions: 80,
      lines: 80,
    },
  },

  // 접근성
  accessibility: {
    required: true,
    level: 'AA', // WCAG 2.1 AA
    allowedViolations: 0,
  },

  // 시각적 회귀
  visualRegression: {
    required: true,
    threshold: 0.1, // 0.1% 미만 차이 허용
    requireApproval: true, // 차이 있으면 수동 승인
  },

  // 번들 크기
  bundleSize: {
    required: true,
    maxIncrease: '5kb', // 단일 PR당 최대 증가
    absoluteMax: '50kb', // 컴포넌트당 절대 최대
  },

  // 문서
  documentation: {
    required: true,
    requiredSections: ['summary', 'props', 'examples', 'accessibility'],
  },
}

AI 생성물 평가 (Golden Prompt Suite)

디자인 시스템을 “AI가 잘 쓰는지”는 감으로만 관리하면 금방 무너집니다. LLM을 컴파일러처럼 보고 **대표 프롬프트 세트(golden prompts)**로 지속적으로 회귀 테스트하는 게 현실적인 해법입니다.

핵심은 두 가지입니다.

케이스를 데이터로 관리: “어떤 UI를 만들게 할지”를 시나리오로 고정
검증을 코드로 관리: “무엇이 통과 조건인지”를 룰로 고정 (토큰/컴포넌트/접근성/일관성)

케이스 포맷 (예시)

# ai-evals/cases/user-invite-form.yml
id: user-invite-form
intent: '관리자 페이지에서 사용자 초대 폼을 만든다'
prompt: |
  사용자 초대 폼을 만들어줘.
  - 이메일 필수
  - 역할 선택(단일)
  - 초대 버튼은 제출 로딩 상태 지원
constraints:
  mustUseComponents:
    - FormField
    - Input
    - Select
    - Button
  forbidden:
    - 'style={{'
    - 'text-red-500' # 토큰 우회
assertions:
  - type: no-hardcoded-colors
  - type: no-arbitrary-spacing
  - type: a11y-no-violations
  - type: only-allowed-components

Record/Replay 전략

CI에서 매번 LLM을 호출하면 비용/변동성 때문에 신뢰도가 떨어집니다. 대신 “기록(record) → 재생(replay) + 검증”을 기본으로 둡니다.

record: (수동 또는 nightly) LLM 출력(코드/스크린샷)을 fixtures/로 저장
replay: PR마다 fixtures를 검증 (린트, 타입, a11y, 시각적 회귀, 일관성 룰)

ai-evals/
├── cases/          # 입력 시나리오 (YAML)
├── fixtures/       # 기록된 출력 (code, screenshots)
├── assertions/     # 검증 로직 (TS)
└── runner.ts       # 실행기 (record/replay)

품질 스코어(선택)

Pass/Fail만으로는 미묘한 퇴행을 놓치기 쉽습니다. “위반 개수/중요도” 기반의 점수도 함께 기록하면 추세를 볼 수 있습니다.

예: 100 - (a11y_violation*20 + hardcoded*10 + layout*5 + warnings*1)

PR 체크 워크플로우

# .github/workflows/pr-check.yml

name: PR Quality Check

on:
  pull_request:
    paths:
      - 'packages/ui/**'

jobs:
  quality-gate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Setup
        uses: ./.github/actions/setup

      - name: Type Check
        run: yarn tsc --noEmit

      - name: Lint
        run: yarn lint

      - name: Test
        run: yarn test --coverage

      - name: Check Coverage
        uses: codecov/codecov-action@v4
        with:
          fail_ci_if_error: true

      - name: A11y Audit
        run: yarn test:a11y

      - name: Visual Regression
        run: yarn test:visual
        env:
          CHROMATIC_PROJECT_TOKEN: ${{ secrets.CHROMATIC_TOKEN }}

      - name: Bundle Size
        uses: preactjs/compressed-size-action@v2
        with:
          repo-token: ${{ secrets.GITHUB_TOKEN }}

      - name: Documentation Check
        run: yarn docs:check

버저닝 전략

Semantic Versioning

MAJOR.MINOR.PATCH

MAJOR: Breaking changes
MINOR: 새 기능 (하위 호환)
PATCH: 버그 수정

Changelog 자동화

// scripts/generate-changelog.ts

import { getCommitsSinceLastTag, parseConventionalCommit } from './git'

const commitTypes = {
  feat: '✨ Features',
  fix: '🐛 Bug Fixes',
  docs: '📚 Documentation',
  style: '💅 Styles',
  refactor: '♻️ Refactoring',
  perf: '⚡ Performance',
  test: '✅ Tests',
  chore: '🔧 Chores',
  breaking: '💥 Breaking Changes',
}

async function generateChangelog(): Promise<string> {
  const commits = await getCommitsSinceLastTag()
  const parsed = commits.map(parseConventionalCommit)

  const grouped = groupBy(parsed, 'type')

  let changelog = `# Changelog\n\n`

  for (const [type, commits] of Object.entries(grouped)) {
    const title = commitTypes[type as keyof typeof commitTypes]
    changelog += `## ${title}\n\n`

    for (const commit of commits) {
      changelog += `- ${commit.description}`
      if (commit.scope) {
        changelog += ` (${commit.scope})`
      }
      changelog += ` ([${commit.hash.slice(0, 7)}](...))\n`
    }

    changelog += '\n'
  }

  return changelog
}

디자이너-개발자 워크플로우

Figma-GitHub 연동

# .github/workflows/figma-sync.yml

name: Figma Sync

on:
  repository_dispatch:
    types: [figma-update]

jobs:
  sync:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Fetch Figma Tokens
        run: |
          npx figma-tokens-sync \
            --token ${{ secrets.FIGMA_TOKEN }} \
            --file ${{ github.event.client_payload.file_key }} \
            --output ./tokens/

      - name: Create PR
        uses: peter-evans/create-pull-request@v6
        with:
          title: 'sync: Update design tokens from Figma'
          body: |
            자동 동기화된 토큰 변경사항입니다.

            Figma File: ${{ github.event.client_payload.file_url }}

디자인 QA 체크리스트

## 디자인 QA 체크리스트

### 시각적 일치

- [ ] 색상이 Figma와 일치
- [ ] 간격이 8px 그리드 준수
- [ ] 타이포그래피 일치
- [ ] 아이콘 크기/정렬

### 인터랙션

- [ ] Hover 상태
- [ ] Focus 상태
- [ ] Active 상태
- [ ] Disabled 상태
- [ ] Loading 상태

### 반응형

- [ ] 모바일 (< 640px)
- [ ] 태블릿 (640px ~ 1024px)
- [ ] 데스크톱 (> 1024px)

### 접근성

- [ ] 색상 대비
- [ ] 포커스 표시자
- [ ] 키보드 내비게이션

커뮤니케이션

채널 정의

채널	용도	응답 기대
GitHub Issues	버그, 기능 요청	1-2 영업일
Slack #design-system	빠른 질문, 논의	당일
RFC PR	주요 변경 제안	1주일
Office Hours	심층 논의, 페어링	주 1회

정기 미팅

## Design System Sync (주간)

- 일시: 매주 목요일 14:00
- 참석: DS Team, 관심 있는 Contributor
- 어젠다:
  - 지난주 변경사항 리뷰
  - 이번주 계획
  - Open PR/Issue 논의
  - Q&A

## Design-Dev Sync (격주)

- 일시: 격주 화요일 15:00
- 참석: DS Team, Product Designer, Tech Lead
- 어젠다:
  - 디자인 시스템 로드맵 동기화
  - 새 컴포넌트 니즈 논의
  - 피드백 공유

체크리스트

참고 자료

거버넌스 구조

팀 구조

역할 정의

역할	책임	권한
DS Lead	전략, 로드맵, 의사결정	모든 변경 승인
DS Engineer	코어 개발, 리뷰	컴포넌트 머지
DS Designer	비주얼, 토큰, UX	디자인 변경 승인
Contributor	기능 기여, 버그 수정	PR 생성
Consumer	시스템 사용	이슈 생성

RACI 매트릭스

| 활동            | DS Lead | DS Engineer | DS Designer | Contributor |
| --------------- | ------- | ----------- | ----------- | ----------- |
| 토큰 변경       | A       | C           | R           | I           |
| 컴포넌트 추가   | A       | R           | C           | C           |
| 문서 업데이트   | I       | R           | C           | R           |
| 브레이킹 체인지 | R/A     | C           | C           | I           |
| 버그 수정       | I       | A           | I           | R           |

R: Responsible (수행)
A: Accountable (책임)
C: Consulted (자문)
I: Informed (통보)

변경 관리

변경 유형

변경 요청 프로세스

RFC 템플릿 (Major 변경용)

# RFC: [변경 제목]

## 요약

한 문단으로 변경 내용 설명

## 동기

왜 이 변경이 필요한가?

## 상세 설계

### 현재 상태

현재 어떻게 작동하는가?

### 제안 변경

어떻게 변경할 것인가?

### 마이그레이션 경로

기존 사용자는 어떻게 마이그레이션하는가?

## 대안

고려한 다른 방법들

## 영향

### Breaking Changes

- [ ] Props 변경
- [ ] API 변경
- [ ] 스타일 변경

### 영향받는 컴포넌트

- Component A
- Component B

## 체크리스트

- [ ] 타입 정의 업데이트
- [ ] 문서 업데이트
- [ ] 마이그레이션 가이드
- [ ] Changelog 업데이트

품질 게이트

자동화된 체크

품질 기준

// quality-gates.config.ts

export const qualityGates = {
  // 타입 검사
  typeCheck: {
    required: true,
    strict: true,
  },

  // 린트
  lint: {
    required: true,
    rules: {
      'design-system/no-hardcoded-values': 'error',
      'design-system/component-docs': 'error',
      'design-system/prop-types': 'error',
    },
  },

  // 테스트 커버리지
  coverage: {
    required: true,
    thresholds: {
      statements: 80,
      branches: 75,
      functions: 80,
      lines: 80,
    },
  },

  // 접근성
  accessibility: {
    required: true,
    level: 'AA', // WCAG 2.1 AA
    allowedViolations: 0,
  },

  // 시각적 회귀
  visualRegression: {
    required: true,
    threshold: 0.1, // 0.1% 미만 차이 허용
    requireApproval: true, // 차이 있으면 수동 승인
  },

  // 번들 크기
  bundleSize: {
    required: true,
    maxIncrease: '5kb', // 단일 PR당 최대 증가
    absoluteMax: '50kb', // 컴포넌트당 절대 최대
  },

  // 문서
  documentation: {
    required: true,
    requiredSections: ['summary', 'props', 'examples', 'accessibility'],
  },
}

AI 생성물 평가 (Golden Prompt Suite)

핵심은 두 가지입니다.

케이스를 데이터로 관리: “어떤 UI를 만들게 할지”를 시나리오로 고정
검증을 코드로 관리: “무엇이 통과 조건인지”를 룰로 고정 (토큰/컴포넌트/접근성/일관성)

케이스 포맷 (예시)

# ai-evals/cases/user-invite-form.yml
id: user-invite-form
intent: '관리자 페이지에서 사용자 초대 폼을 만든다'
prompt: |
  사용자 초대 폼을 만들어줘.
  - 이메일 필수
  - 역할 선택(단일)
  - 초대 버튼은 제출 로딩 상태 지원
constraints:
  mustUseComponents:
    - FormField
    - Input
    - Select
    - Button
  forbidden:
    - 'style={{'
    - 'text-red-500' # 토큰 우회
assertions:
  - type: no-hardcoded-colors
  - type: no-arbitrary-spacing
  - type: a11y-no-violations
  - type: only-allowed-components

Record/Replay 전략

CI에서 매번 LLM을 호출하면 비용/변동성 때문에 신뢰도가 떨어집니다. 대신 “기록(record) → 재생(replay) + 검증”을 기본으로 둡니다.

record: (수동 또는 nightly) LLM 출력(코드/스크린샷)을 fixtures/로 저장
replay: PR마다 fixtures를 검증 (린트, 타입, a11y, 시각적 회귀, 일관성 룰)

ai-evals/
├── cases/          # 입력 시나리오 (YAML)
├── fixtures/       # 기록된 출력 (code, screenshots)
├── assertions/     # 검증 로직 (TS)
└── runner.ts       # 실행기 (record/replay)

품질 스코어(선택)

Pass/Fail만으로는 미묘한 퇴행을 놓치기 쉽습니다. “위반 개수/중요도” 기반의 점수도 함께 기록하면 추세를 볼 수 있습니다.

예: 100 - (a11y_violation*20 + hardcoded*10 + layout*5 + warnings*1)

PR 체크 워크플로우

# .github/workflows/pr-check.yml

name: PR Quality Check

on:
  pull_request:
    paths:
      - 'packages/ui/**'

jobs:
  quality-gate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Setup
        uses: ./.github/actions/setup

      - name: Type Check
        run: yarn tsc --noEmit

      - name: Lint
        run: yarn lint

      - name: Test
        run: yarn test --coverage

      - name: Check Coverage
        uses: codecov/codecov-action@v4
        with:
          fail_ci_if_error: true

      - name: A11y Audit
        run: yarn test:a11y

      - name: Visual Regression
        run: yarn test:visual
        env:
          CHROMATIC_PROJECT_TOKEN: ${{ secrets.CHROMATIC_TOKEN }}

      - name: Bundle Size
        uses: preactjs/compressed-size-action@v2
        with:
          repo-token: ${{ secrets.GITHUB_TOKEN }}

      - name: Documentation Check
        run: yarn docs:check

버저닝 전략

Semantic Versioning

MAJOR.MINOR.PATCH

MAJOR: Breaking changes
MINOR: 새 기능 (하위 호환)
PATCH: 버그 수정

Changelog 자동화

// scripts/generate-changelog.ts

import { getCommitsSinceLastTag, parseConventionalCommit } from './git'

const commitTypes = {
  feat: '✨ Features',
  fix: '🐛 Bug Fixes',
  docs: '📚 Documentation',
  style: '💅 Styles',
  refactor: '♻️ Refactoring',
  perf: '⚡ Performance',
  test: '✅ Tests',
  chore: '🔧 Chores',
  breaking: '💥 Breaking Changes',
}

async function generateChangelog(): Promise<string> {
  const commits = await getCommitsSinceLastTag()
  const parsed = commits.map(parseConventionalCommit)

  const grouped = groupBy(parsed, 'type')

  let changelog = `# Changelog\n\n`

  for (const [type, commits] of Object.entries(grouped)) {
    const title = commitTypes[type as keyof typeof commitTypes]
    changelog += `## ${title}\n\n`

    for (const commit of commits) {
      changelog += `- ${commit.description}`
      if (commit.scope) {
        changelog += ` (${commit.scope})`
      }
      changelog += ` ([${commit.hash.slice(0, 7)}](...))\n`
    }

    changelog += '\n'
  }

  return changelog
}

디자이너-개발자 워크플로우

Figma-GitHub 연동

# .github/workflows/figma-sync.yml

name: Figma Sync

on:
  repository_dispatch:
    types: [figma-update]

jobs:
  sync:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Fetch Figma Tokens
        run: |
          npx figma-tokens-sync \
            --token ${{ secrets.FIGMA_TOKEN }} \
            --file ${{ github.event.client_payload.file_key }} \
            --output ./tokens/

      - name: Create PR
        uses: peter-evans/create-pull-request@v6
        with:
          title: 'sync: Update design tokens from Figma'
          body: |
            자동 동기화된 토큰 변경사항입니다.

            Figma File: ${{ github.event.client_payload.file_url }}

디자인 QA 체크리스트

## 디자인 QA 체크리스트

### 시각적 일치

- [ ] 색상이 Figma와 일치
- [ ] 간격이 8px 그리드 준수
- [ ] 타이포그래피 일치
- [ ] 아이콘 크기/정렬

### 인터랙션

- [ ] Hover 상태
- [ ] Focus 상태
- [ ] Active 상태
- [ ] Disabled 상태
- [ ] Loading 상태

### 반응형

- [ ] 모바일 (< 640px)
- [ ] 태블릿 (640px ~ 1024px)
- [ ] 데스크톱 (> 1024px)

### 접근성

- [ ] 색상 대비
- [ ] 포커스 표시자
- [ ] 키보드 내비게이션

커뮤니케이션

채널 정의

채널	용도	응답 기대
GitHub Issues	버그, 기능 요청	1-2 영업일
Slack #design-system	빠른 질문, 논의	당일
RFC PR	주요 변경 제안	1주일
Office Hours	심층 논의, 페어링	주 1회

정기 미팅

## Design System Sync (주간)

- 일시: 매주 목요일 14:00
- 참석: DS Team, 관심 있는 Contributor
- 어젠다:
  - 지난주 변경사항 리뷰
  - 이번주 계획
  - Open PR/Issue 논의
  - Q&A

## Design-Dev Sync (격주)

- 일시: 격주 화요일 15:00
- 참석: DS Team, Product Designer, Tech Lead
- 어젠다:
  - 디자인 시스템 로드맵 동기화
  - 새 컴포넌트 니즈 논의
  - 피드백 공유

거버넌스 & 협업

거버넌스 체크리스트

목차

거버넌스 & 협업

거버넌스 체크리스트

목차