--- type: knowledge domain: design status: active last-reviewed: 2026-07-12 --- # 디자인 시스템 > 한 줄 정의 > 화면 하나를 넘어 재사용되는 디자인 결정의 체계 — 토큰 → 컴포넌트 → 패턴 3층. 원칙은 [[TECHNOLOGY-DECISION-GUIDE]]와 같다: **승격 근거 없으면 최소 층만.** > [!IMPORTANT] 제공 디자인 우선 > 디자인 시스템을 선택했으면 공식 컴포넌트·기본 테마·variant·패턴·예제를 먼저 사용한다. 임의 CSS로 외형을 재설계하지 않는다. 브랜드 조정이 명시적으로 필요할 때만 해당 시스템의 공식 token·theme API 안에서 최소 변경한다. ## 3층 구조 | 층 | 내용 | 예 | |----|------|----| | 토큰 | 원시값과 의미의 분리 | `blue.600` → `color.action.primary` | | 컴포넌트 | 상태·변형을 가진 UI 단위 | Button(variant, size) | | 패턴 | 컴포넌트 조합 규칙 | 폼 레이아웃, 빈 상태, 테이블+필터 | ## 도입 시점 — 승격 조건 | 단계 | 승격 조건 | |------|----------| | 토큰만 (기본값) | 프로젝트 시작 즉시 — 화면 1개여도 토큰은 선언한다 | | + 컴포넌트 라이브러리 | 같은 패턴이 화면 3곳+ 반복, 또는 구현자 2인+ | | + 문서화된 시스템 | 팀 외부가 사용, 브랜드 일관성이 계약 요구 | - 첫날부터 풀 디자인 시스템은 [[아키텍처 스타일 선택]]의 "첫날 마이크로서비스"와 같은 실수 — 제품 전에 시스템부터 만들면 둘 다 죽는다. ## 토큰 규칙 - **2단계 고정**: 원시 토큰(palette) → 의미 토큰(semantic). 컴포넌트가 원시 토큰을 직접 참조하면 테마 교체가 불가능해진다. - 다크 모드·브랜드 테마는 의미 토큰 레이어에서 스왑한다 — 컴포넌트 코드는 불변. - 토큰 범위: 색 · 타이포 스케일 · 간격 · radius · 그림자 · 모션 duration/easing. 하드코딩 값이 코드에 산재하면 체계가 없다는 뜻이다 ([[UI 시각 체계]]). ## 컴포넌트 API - 변형 축 분리: `variant`(의미) × `size`(크기). boolean prop 증식(isPrimary, isLarge, isOutline…)은 조합 폭발 신호. - 상태는 기본 5종을 설계한다: default / hover / focus / active / disabled — 데이터 컴포넌트는 + loading / error / empty. - 복잡한 위젯은 합성(compound) 우선: `…` — 설정 prop 뭉치보다 유연하고 읽기 쉽다. ## 운영 — 시스템은 제품이다 - 버전·변경 로그·마이그레이션 안내 없는 디자인 시스템은 두 릴리즈 안에 우회당한다. - one-off(시스템 우회 스타일)는 금지가 아니라 **추적** 대상 — 3회 반복되면 시스템으로 승격, 아니면 정리. - AI에게 화면을 맡길 때 토큰·컴포넌트 목록을 컨텍스트로 준다. 주지 않으면 매번 새 스타일을 발명한다 ([[AI 페어 개발 원리]]). ## 무료 구현체 카탈로그 구현체는 [[DESIGN-SYSTEM-ROUTER|디자인 시스템 라우터]]에서 기존 스택과 제외 조건을 먼저 검사해 선택한다. 후보가 둘 이상 남으면 [[무료 React 디자인 시스템 비교]]에서 배포 방식, 컴포넌트 범위, AI 도구, 채팅 UI, 라이선스를 비교한다. | 우선 조건 | 구현체 | |---|---| | Astryx와 가까운 관리형 시스템 + MCP | [[Chakra UI 디자인 시스템]], [[HeroUI 디자인 시스템]] | | AI 채팅·에이전트 UI | [[Ant Design X 디자인 시스템]], [[shadcn-ui 디자인 시스템]] | | 넓은 범용 컴포넌트·업무 앱 | [[Mantine 디자인 시스템]] | | 소스를 직접 소유하는 자체 시스템 | [[Park UI 디자인 시스템]], [[shadcn-ui 디자인 시스템]] | ## 안티패턴 - **제품보다 시스템 먼저** — 사용처 없는 컴포넌트 40개. - **원시 토큰 직접 참조** — 테마·다크모드 도입 시 전면 수정 비용. - **문서 없는 시스템** — 셀프서브로 훑어볼 수 있는 뷰(스토리북류)가 없으면 물어봐야 쓰는 시스템이 된다. - **동결된 시스템** — 기여 경로가 없으면 우회가 표준이 된다. ## 관련 문서 - [[DESIGN-SYSTEM-ROUTER|디자인 시스템 라우터]] - [[무료 React 디자인 시스템 비교]] · [[Astryx 디자인 시스템]] - [[UI 시각 체계]] · [[디자인 프로세스와 평가]] · [[프론트엔드 원리]] · [[프론트엔드-체크리스트]]