UI 디자인 시스템은(는) 무엇을 하나요?

디자인 토큰 생성, 컬러 팔레트 제작, 타이포그래피 스케일 계산, 컴포넌트 시스템 구축 및 개발자 인수인계 문서 준비를 수행합니다.

트리거 용어

다음과 같은 경우에 이 스킬을 사용하세요:

"디자인 토큰 생성"
"컬러 팔레트 만들기"
"타이포그래피 스케일 구축"
"간격 시스템 계산"
"디자인 시스템 만들기"
"CSS 변수 생성"
"SCSS 토큰 내보내기"
"컴포넌트 아키텍처 설정"
"컴포넌트 라이브러리 문서화"
"반응형 브레이크포인트 계산"
"개발자 인수인계 준비"
"브랜드 색상을 팔레트로 변환"
"WCAG 대비 확인"
"8pt 그리드 시스템 구축"

먼저 명확히 하기

토큰이나 시스템을 생성하기 전에 아래 입력 사항을 확인하세요. 누락되거나 모호하여 결과가 달라질 경우 질문하고, 그렇지 않으면 합리적인 기본값을 사용하고 사용한 기본값을 알려주세요.

브랜드 기본 색상(hex): 전체 팔레트의 시드(색상 스케일 및 WCAG 대비 검사에 사용)
스타일 프리셋: modern, classic, 또는 playful(글꼴, 테두리 반경, 그림자 스타일 결정)
출력 형식 및 프레임워크: CSS, SCSS, 또는 Tailwind/styled-components/Figma용 JSON(내보내기 및 개발자 인수인계에 영향)

전체 목록이 아니라 이 요청에 가장 중요한 두세 가지 입력 사항에 대해 질문하세요. 사용자가 즉시 결과를 원한다면 결과를 생성하고 상단에 가정한 내용을 명시하세요.

워크플로우

워크플로우 1: 디자인 토큰 생성

상황: 브랜드 색상이 있고 완전한 디자인 토큰 시스템이 필요합니다.

단계:

브랜드 색상 및 스타일 식별
- 브랜드 기본 색상(hex 형식)
- 스타일 선호도: modern | classic | playful

스크립트를 사용하여 토큰 생성

python scripts/design_token_generator.py "#0066CC" modern json

생성된 카테고리 검토
- 색상: primary, secondary, neutral, semantic, surface
- 타이포그래피: fontFamily, fontSize, fontWeight, lineHeight
- 간격: 8pt 그리드 기반 스케일(0-64)
- 테두리: radius, width
- 그림자: none부터 2xl까지
- 애니메이션: duration, easing
- 브레이크포인트: xs부터 2xl까지

대상 형식으로 내보내기

# CSS 사용자 정의 속성
python scripts/design_token_generator.py "#0066CC" modern css > design-tokens.css

# SCSS 변수
python scripts/design_token_generator.py "#0066CC" modern scss > _design-tokens.scss

# Figma/도구용 JSON
python scripts/design_token_generator.py "#0066CC" modern json > design-tokens.json

접근성 검증
- 색상 대비가 WCAG AA(일반 텍스트 4.5:1, 큰 텍스트 3:1)를 충족하는지 확인
- 시맨틱 색상에 대비 색상이 정의되어 있는지 확인

워크플로우 2: 컴포넌트 시스템 생성

상황: 디자인 토큰을 사용하여 컴포넌트 라이브러리를 구조화해야 합니다.

단계:

컴포넌트 계층 구조 정의
- Atoms: Button, Input, Icon, Label, Badge
- Molecules: FormField, SearchBar, Card, ListItem
- Organisms: Header, Footer, DataTable, Modal
- Templates: DashboardLayout, AuthLayout

토큰을 컴포넌트에 매핑

컴포넌트	사용된 토큰
Button	colors, sizing, borders, shadows, typography
Input	colors, sizing, borders, spacing
Card	colors, borders, shadows, spacing
Modal	colors, shadows, spacing, z-index, animation

변형 패턴 정의

크기 변형:

sm: height 32px, paddingX 12px, fontSize 14px
md: height 40px, paddingX 16px, fontSize 16px
lg: height 48px, paddingX 20px, fontSize 18px

색상 변형:

primary: background primary-500, text white
secondary: background neutral-100, text neutral-900
ghost: background transparent, text neutral-700

컴포넌트 API 문서화
- 유형이 있는 Props 인터페이스
- 변형 옵션
- 상태 처리(hover, active, focus, disabled)
- 접근성 요구 사항
참조: references/component-architecture.md 참조

워크플로우 3: 반응형 디자인

상황: 브레이크포인트, 유동형 타이포그래피 또는 반응형 간격이 필요합니다.

단계:

브레이크포인트 정의

이름 너비 대상
xs 0 작은 휴대폰
sm 480px 큰 휴대폰
md 640px 태블릿
lg 768px 작은 노트북
xl 1024px 데스크탑
2xl 1280px 대형 화면

유동형 타이포그래피 계산

공식: clamp(min, preferred, max)

/* 320px ~ 1200px 뷰포트에서 16px ~ 24px */
font-size: clamp(1rem, 0.5rem + 2vw, 1.5rem);

미리 계산된 스케일:

--fluid-h1: clamp(2rem, 1rem + 3.6vw, 4rem);
--fluid-h2: clamp(1.75rem, 1rem + 2.3vw, 3rem);
--fluid-h3: clamp(1.5rem, 1rem + 1.4vw, 2.25rem);
--fluid-body: clamp(1rem, 0.95rem + 0.2vw, 1.125rem);

반응형 간격 설정

토큰 모바일 태블릿 데스크탑
--space-md 12px 16px 16px
--space-lg 16px 24px 32px
--space-xl 24px 32px 48px
--space-section 48px 80px 120px
참조: references/responsive-calculations.md 참조

워크플로우 4: 개발자 인수인계

상황: 디자인 토큰을 개발 팀에 인수인계해야 합니다.

단계:

필요한 형식으로 토큰 내보내기

# CSS 프로젝트용
python scripts/design_token_generator.py "#0066CC" modern css

# SCSS 프로젝트용
python scripts/design_token_generator.py "#0066CC" modern scss

# JavaScript/TypeScript용
python scripts/design_token_generator.py "#0066CC" modern json

프레임워크 통합 준비

React + CSS 변수:

import './design-tokens.css';

<button className="btn btn-primary">Click</button>

Tailwind 설정:

const tokens = require('./design-tokens.json');

module.exports = {
  theme: {
    colors: tokens.colors,
    fontFamily: tokens.typography.fontFamily
  }
};

styled-components:

import tokens from './design-tokens.json';

const Button = styled.button`
  background: ${tokens.colors.primary['500']};
  padding: ${tokens.spacing['2']} ${tokens.spacing['4']};
`;

Figma와 동기화
- Tokens Studio 플러그인 설치
- design-tokens.json 가져오기
- 토큰이 Figma 스타일과 자동으로 동기화됨
인수인계 체크리스트
- 토큰 파일이 프로젝트에 추가됨
- 빌드 파이프라인이 구성됨
- 테마/CSS 변수가 임포트됨
- 컴포넌트 라이브러리가 정렬됨
- 문서가 생성됨
참조: references/developer-handoff.md 참조

도구 참조

design_token_generator.py

브랜드 색상으로 완전한 디자인 토큰 시스템을 생성합니다.

인수	값	기본값	설명
brand_color	Hex 색상	#0066CC	기본 브랜드 색상
style	modern, classic, playful	modern	디자인 스타일 프리셋
format	json, css, scss, summary	json	출력 형식

예시:

# JSON 토큰 생성 (기본값)
python scripts/design_token_generator.py "#0066CC"

# 클래식 스타일 CSS 출력
python scripts/design_token_generator.py "#8B4513" classic css

# 플레이풀 스타일 요약 보기
python scripts/design_token_generator.py "#FF6B6B" playful summary

출력 카테고리:

카테고리	설명	주요 값
colors	컬러 팔레트	primary, secondary, neutral, semantic, surface
typography	글꼴 시스템	fontFamily, fontSize, fontWeight, lineHeight
spacing	8pt 그리드	0-64 스케일, 시맨틱(xs-3xl)
sizing	컴포넌트 크기	container, button, input, icon
borders	테두리 값	radius (스타일별), width
shadows	그림자 스타일	none부터 2xl, inner
animation	모션 토큰	duration, easing, keyframes
breakpoints	반응형	xs, sm, md, lg, xl, 2xl
z-index	레이어 시스템	base부터 notification까지

빠른 참조 표

색상 스케일 생성

단계	밝기	채도	사용 사례
50	95% 고정	30%	미묘한 배경
100	95% 고정	38%	밝은 배경
200	95% 고정	46%	호버 상태
300	95% 고정	54%	테두리
400	95% 고정	62%	비활성화 상태
500	원본	70%	기본/기본 색상
600	원본 × 0.8	78%	호버 (어두움)
700	원본 × 0.6	86%	활성 상태
800	원본 × 0.4	94%	텍스트
900	원본 × 0.2	100%	제목

타이포그래피 스케일 (1.25x 비율)

크기	값	계산
xs	10px	16 ÷ 1.25²
sm	13px	16 ÷ 1.25¹
base	16px	기본
lg	20px	16 × 1.25¹
xl	25px	16 × 1.25²
2xl	31px	16 × 1.25³
3xl	39px	16 × 1.25⁴
4xl	49px	16 × 1.25⁵
5xl	61px	16 × 1.25⁶

WCAG 대비 요구 사항

수준	일반 텍스트	큰 텍스트
AA	4.5:1	3:1
AAA	7:1	4.5:1

큰 텍스트: ≥18pt 일반 또는 ≥14pt 굵게

스타일 프리셋

측면	Modern	Classic	Playful
Sans 글꼴	Inter	Helvetica	Poppins
Mono 글꼴	Fira Code	Courier	Source Code Pro
기본 반경	8px	4px	16px
그림자	계층적, 미묘함	단일 레이어	부드럽고 강조됨

지식 베이스

references/ 디렉토리의 상세 참조 가이드:

파일	내용
`token-generation.md`	색상 알고리즘, HSV 공간, WCAG 대비, 타입 스케일
`component-architecture.md`	아토믹 디자인, 명명 규칙, props 패턴
`responsive-calculations.md`	브레이크포인트, 유동형 타이포그래피, 그리드 시스템
`developer-handoff.md`	내보내기 형식, 프레임워크 설정, Figma 동기화

검증 체크리스트

토큰 생성

브랜드 색상이 hex 형식으로 제공됨
스타일이 프로젝트 요구 사항과 일치함
모든 토큰 카테고리가 생성됨
시맨틱 색상에 대비 값이 포함됨

컴포넌트 시스템

모든 크기가 구현됨 (sm, md, lg)
모든 변형이 구현됨 (primary, secondary, ghost)
모든 상태가 작동함 (hover, active, focus, disabled)
디자인 토큰만 사용함 (하드코딩된 값 없음)

접근성

색상 대비가 WCAG AA를 충족함
포커스 표시기가 보임
터치 대상 ≥ 44×44px
시맨틱 HTML 요소 사용

개발자 인수인계

토큰이 필요한 형식으로 내보내짐
프레임워크 통합이 문서화됨
디자인 도구가 동기화됨
컴포넌트 문서가 완료됨

문제 해결

문제	원인	해결 방법
생성된 색상이 WCAG 대비 실패	브랜드 색상이 너무 밝거나 채도가 높음	밝은 배경에 어두운 음영(600+) 사용; 대비 도구로 확인
토큰 내보내기 값이 올바르지 않음	잘못된 형식 인수 또는 색상 구문	hex 색상을 따옴표로 묶었는지 확인; 형식이 `json`, `css` 또는 `scss`인지 확인
타이포그래피 스케일이 너무 크거나 작음	기본 1.25x 비율이 디자인에 맞지 않음	DesignTokenGenerator 클래스에서 `type_scale_ratio` 수정 (1.125는 더 좁게, 1.333은 더 넓게)
SCSS 변수가 기존 항목과 충돌	토큰 명명 충돌	프로젝트 네임스페이스로 모든 토큰에 접두사 추가 (내보내기 함수 편집)
디자인 도구에서 다른 색상 표시	색상 스케일 생성 시 hex 반올림	JSON 내보내기를 진실 공급원으로 사용; Tokens Studio 플러그인과 동기화
간격 값이 그리드와 정렬되지 않음	사용자 정의 간격이 8pt 그리드와 혼합됨	생성된 간격 시스템의 값만 사용; 임의의 픽셀 값 피하기
그림자 토큰이 다크 모드에서 잘못 보임	밝은 배경용으로 설계된 그림자	더 밝은 불투명도 값으로 별도의 다크 모드 그림자 토큰 생성

성공 기준

기준	목표	측정 방법
토큰 일관성	코드베이스에 하드코딩된 색상/간격 값 0개	린트 규칙 위반 횟수
WCAG AA 준수	모든 텍스트 색상이 4.5:1 대비 비율 충족	자동 대비 검사기 또는 수동 감사
내보내기 형식 범위	CSS, SCSS, JSON이 모두 올바르게 생성됨	각 형식으로 생성기 실행; 출력 검증
디자인-개발 동기화	토큰 업데이트와 코드 배포 간 <24시간	Figma 변경부터 프로덕션까지의 시간
컴포넌트 토큰 범위	100% 컴포넌트가 디자인 토큰 사용	하드코딩된 값에 대한 컴포넌트 스타일 감사
타이포그래피 일관성	모든 텍스트가 디자인 시스템 타입 스케일 사용	모든 페이지에 걸친 시각적 감사
반응형 동작	유동형 타이포그래피가 모든 브레이크포인트에서 작동	xs, sm, md, lg, xl, 2xl 너비에서 테스트

범위 및 제한 사항

범위 내:

브랜드 색상으로 완전한 디자인 토큰 생성
컬러 팔레트 생성 (primary, secondary, neutral, semantic)
모듈형 스케일을 사용한 타이포그래피 시스템
8pt 그리드 기반 간격 시스템
컴포넌트 크기, 테두리, 그림자, 애니메이션 토큰
CSS 사용자 정의 속성, SCSS 변수 및 JSON으로 내보내기
반응형 브레이크포인트 정의
WCAG 대비 참조 표

범위 외:

다크 모드 토큰 생성 (별도 팔레트 매핑 필요)
애니메이션/모션 디자인 라이브러리
아이콘 시스템 생성
런타임 테마 전환 구현
Figma 플러그인 또는 API 통합 (Tokens Studio 사용)
시각적 회귀 테스트
디자인-코드 변환 (Figma Dev Mode 또는 Locofy 사용)

통합 지점

…

[번역을 위해 잘림]

UI 디자인 시스템