Design System Domain Knowledge Base

이 문서가 답하는 질문: 디자인 시스템을 다룬다는 것은 정확히 무엇을 다룬다는 뜻인가? 그리고 Panda CSS와 Tailwind를 동시에 쓰는 것이 가능한가? 작성: 2026-05-19 / 스타일: Minto Pyramid + /explain (Why → How → What → What-if)

한 문장 답 (Pyramid Top)

디자인 시스템은 **“디자인 결정을 코드로 직렬화하는 5개 레이어”**다 — ① Foundations(원칙) ② Tokens(값) ③ Recipes·Variants(규칙) ④ Theming(컨텍스트) ⑤ Distribution(전달). 이 도메인은 그 5개 레이어를 W3C DTCG, Tailwind, Panda CSS 같은 사실상 표준 위에서 정리하며, “한 번 정의한 토큰을 Panda recipe와 Tailwind utility 양쪽에서 동시에 소비” 하는 호환 전략을 핵심 케이스로 다룬다.

Why — 왜 이 도메인이 필요한가

디자인 시스템은 “같은 색을 두 번 정의하지 마라” 라는 단순한 원칙에서 시작하지만, 실제로는 다음과 같은 충돌들을 동시에 해결해야 한다.

충돌	예시	누가 푸는가
디자이너 vs 개발자	Figma의 `Primary/500` ↔ 코드의 `--color-primary-500`	Tokens (W3C DTCG)
런타임 vs 빌드타임	다크모드 즉시 전환 ↔ Tailwind JIT의 정적 클래스	Theming + Build pipeline
유틸리티 vs 컴포넌트	`className="bg-blue-500 px-4"` ↔ `<Button variant="primary">`	Recipes·Variants
두 라이브러리의 공존	신규는 Panda, 레거시는 Tailwind	Interop (7장 핵심)
버전·브레이킹 체인지	`color.primary` 이름이 바뀌면 100개 컴포넌트가 깨짐	Governance + Versioning

특히 Panda CSS와 Tailwind의 공존은 2025년 현재 가장 첨예한 실무 이슈다:

Tailwind는 마크업에 의미 있는 유틸리티를, Panda는 타입 안전한 recipe + zero-runtime을 약속한다.
두 진영 모두 자기만의 토큰 시스템(tailwind.config.{js,ts} vs panda.config.ts)을 갖는다.
“한쪽으로 통일”이 정치적·기술적으로 어려운 조직은 토큰을 단일 출처로 두고 두 빌드 시스템에 동시 주입하는 길을 택한다.

이 레포는 그 전 과정을 원리 → 토큰 → 규칙 → 컨텍스트 → 배포의 순서로 따라간다.

How — 어떻게 정리했나

1) 책장 구조 (3층)

층	폴더	다루는 것	비고
L1 기초	`00-foundations`	디자인 시스템 정의·역사·5-레이어	모든 결정의 토대
L2 값	`01-tokens`, `02-color-system`, `03-typography-spacing`	DTCG·계층·스케일	”어떤 값을 둘 것인가”
L3 규칙	`04-recipes-variants`, `05-composition`	recipe·variant·slot·polymorphism	”그 값을 어떻게 조합할 것인가”
L4 컨텍스트	`06-theming`	다크모드·멀티 브랜드·RTL	”언제 어느 값을 쓸 것인가”
L5 전달	`07-panda-tailwind-interop`, `08-pipeline-distribution`	호환·빌드·docs·governance	”어떻게 모두에게 같은 값을 줄 것인가”
사전	`99-glossary`	100~150개 용어	빠른 참조

2) 문서 형식 (모든 챕터 공통)

각 문서는 다음 7-블록을 따른다 — /explain + Minto 합성:

1. 한 줄 답 (Pyramid Top)
2. Why  — 왜 존재하는가, 어떤 문제를 푸는가
3. How  — 어떻게 동작하는가, 핵심 메커니즘
4. What — 구체 사양·수치·필드·옵션
5. What-if — 잘못 쓰면 어떻게 깨지는가
6. Insight — 흥미로운 이야기·역사·반전
7. 요약 + Mermaid (필수)

3) 챕터 인덱스 (10개)

챕터	다루는 것	핵심 키워드
`00-foundations`	디자인 시스템 정의·역사·5-레이어 모델	atomic design, design tokens, 단일 출처, contract
`01-tokens`	토큰 계층(primitive/semantic/component)·DTCG	DTCG, alias, $value,$ type, $extensions
`02-color-system`	OKLCH·contrast·dark mode·color scale 12-step	OKLCH, P3, APCA, Radix Colors, color-mix
`03-typography-spacing`	타이포 스케일·spacing scale·radius·shadow	modular scale, 4/8 grid, fluid type, clamp
`04-recipes-variants`	Panda recipe·CVA·tv·compound variants	recipe, variant, compoundVariants, defaultVariants
`05-composition`	슬롯·polymorphism·compound components	slot recipe, asChild, polymorphic, headless
`06-theming`	테마 전환·다크모드·브랜드·CSS variables	data-theme, prefers-color-scheme, multi-brand, RTL
`07-panda-tailwind-interop`	두 라이브러리 철학 비교 + 호환 전략	preset, codegen, Style Dictionary, 토큰 브리지
`08-pipeline-distribution`	패키징·릴리스·docs·governance	npm, changeset, semver, RFC, Storybook
`99-glossary`	디자인 시스템 용어 사전	100~150개 항목

What-if — 이 도메인의 한계

“디자인 시스템 = 컴포넌트 라이브러리”가 아니다. 이 레포는 값의 약속에 중점을 두고, 컴포넌트 카탈로그(예: shadcn/ui, Radix Primitives 전체) 자체는 다루지 않는다.
CSS-in-JS의 모든 갈래를 다루지 않는다. Panda CSS(zero-runtime, Stitches 계보)와 Tailwind(utility-first) 두 진영만 깊게 본다. Emotion·styled-components·vanilla-extract는 7장의 비교 표에서만 언급.
Figma 측 워크플로는 토큰 export 지점까지만 다룬다. Tokens Studio 같은 도구의 UI 사용법은 다루지 않는다.

Insight — 왜 지금 “호환”인가

2023~2024년의 흐름은 **Tailwind v4(CSS-first config) + Panda CSS v0.x(타입 안전 recipe)**의 동시 성숙이다.

Tailwind v4는 @theme directive로 CSS variables를 1급 시민으로 끌어올렸다.
Panda CSS는 처음부터 CSS variables 기반 토큰 + 타입 안전 recipe를 표방했다.

두 시스템의 교집합이 바로 CSS variables + W3C DTCG다. 즉, 토큰을 표준 포맷(DTCG JSON)으로 정의하고 → tailwind.config와 panda.config 양쪽에 주입하면 한 컴포넌트가 두 마크업 스타일을 동시에 만족할 수 있다.

이 레포의 7장이 그 길을 안내한다.

요약

디자인 시스템은 **값(토큰) → 규칙(recipe) → 컨텍스트(theme) → 전달(pipeline)**의 5-레이어다.
Panda CSS와 Tailwind는 철학이 다른 두 컴파일러지만, CSS variables + DTCG 토큰을 공통 출처로 두면 공존 가능하다.
이 도메인은 그 공존 전략을 원리·표준·코드·사례로 9 챕터 + 1 사전으로 정리한다.

📖 개요 📖 개요