# ZEST Design System 규칙
이 프로젝트의 UI 는 ZEST Design System(https://ui.zest.im)을 따른다. 전체 계약은 `docs/zest-ui/DESIGN.md`.
## 반드시
- 부품은 `@/components/ui/*`(shadcn 레지스트리 @zest) 를 먼저 쓴다. 없으면 `npx shadcn add @zest/<이름>`.
- 색은 토큰 클래스만: 글자 `text-ink-strong|ink|ink-sub|ink-muted`, 선 `border-line`, 바탕 `bg-app|bg-surface|bg-subtle`, 강조 `bg-brand`·`text-brand-text`·`bg-brand-soft`.
- 상태는 점 + 글자 ``. 진행 중=잉크, 완료=그린, 대기=앰버, 반려=레드, 예정=회색 링.
- 페이지 순서: 큰 제목(PageHeader) → 하위 탭 → 도구 줄(FilterBar·주 버튼) → 본문. 상세는 오른쪽 Drawer.
- 주 버튼(`variant="primary"`)은 화면에 하나. 되돌릴 수 없는 행동은 AlertDialog(첫 포커스 = 취소).
- 카드는 1px 테두리만(`border border-solid border-line`). 그림자는 떠 있는 것(메뉴·드로어·토스트)에만.
- 글자 크기는 `text-caption|small|body|body-lg|lead|title-sm|title|heading|display-sm|display`. 본문·표는 `text-body`.
- 아이콘만 있는 버튼은 `aria-label`. 색만으로 뜻을 전하지 않는다.
## 금지 (AI 슬롭)
- 그라데이션(버튼·배경·카드·텍스트), 글래스모피즘, 네온 글로우
- 인디고·바이올렛·퍼플·블루(`indigo-*`, `violet-*`, `purple-*`, `blue-500/600`, `#3182F6`, `#8B5CF6`) 강조색
- 이모지로 시작하는 제목, "🚀 Supercharge your …" 같은 빈 문구
- 토큰 밖 hex·rgb 색, `shadow-lg` 이상의 카드 그림자, `text-gray-400` 본문
- 같은 모양 카드 3개를 나란히 깐 기능 소개 섹션(내용이 실제로 그렇지 않다면)
## 확인
작업 후 `node scripts/zest-check.mjs src` 를 돌려 0건이어야 한다.
---
# DESIGN.md — ZEST Design System v2
ZEST 전 제품이 공유하는 디자인 계약이다. 사람과 AI 코딩 에이전트 모두 이 문서를 기준으로 화면을 설계하고 구현한다.
구현의 단일 소스는 `@zest-im/ui` v1(1.1.0~, Tailwind v4)이고, 값의 단일 소스는 `src/tokens/tokens.css`다. Tailwind 연결은 `src/tokens/theme.css`(`@theme inline`).
공개 문서: **https://ui.zest.im** · shadcn 레지스트리 `@zest` = `https://ui.zest.im/r/{name}.json`
- 설계 근거: `docs/superpowers/specs/2026-11-16-zest-design-system-v2-design.md`
- 팔레트 완성본: `design/palette.html` (tokens.css 를 직접 읽어 그린다)
- 쇼케이스 문서: `design/showcase/index.html`
- 레퍼런스(flex 공개 화면 수집본): `design/reference/flex/README.md`
- 살아 있는 문서: Storybook `Docs/*` (`pnpm storybook`)
> v1(2026-07, buildchain·토스 계열)은 `@zest-im/ui/legacy`로 동결했다. 새 화면에는 쓰지 않는다.
---
## 1. 성격
사내 HR·운영 도구는 하루에도 몇 번씩 여는 **작업 화면**이다. 그래서 꾸밈보다 정돈을 우선한다.
- **Calm**: 무채색 바탕에 강조색은 그린 하나만 쓴다.
- **Dense, not crowded**: 넓게 쓰고 촘촘하게 채우되, 위계로 숨을 쉬게 한다.
- **Predictable**: 모든 페이지가 같은 순서로 짜여 있어서, 처음 여는 메뉴도 익숙하게 읽힌다.
- **Accessible by default**: 키보드 조작과 스크린리더 연결, 대비 기준은 부품이 보장한다.
레이아웃과 밀도의 문법은 HR SaaS flex의 공개 화면에서 관찰했다. 색·형태·첫인상은 ZEST의 것이다(§10).
---
## 2. 원칙 7
1. **무채색 바탕에 강조색은 그린 하나.** 그린은 주 행동(추가·승인·저장), 선택 상태, 완료에만 쓴다.
2. **위계는 색보다 굵기와 회색 단계로.** 강조는 굵기 600이 기본이고, 700은 큰 제목에만 쓴다.
3. **넓게 쓰고 촘촘하게 채운다.** 목록 화면은 전체 폭을 쓰고, 상세·폼 화면은 최대 1200px로 둔다. 짧은 항목은 한 줄에 4개까지 놓는다.
4. **페이지 문법을 통일한다.** 순서는 큰 제목(같은 레벨 메뉴는 회색 제목으로 나란히) → 하위 탭 → 도구 줄(필터 칩·검색·보기 옵션·주 버튼) → 본문이다.
5. **상세는 오른쪽 드로어로 연다.** 목록 맥락을 유지한다. 승인 단계는 드로어 오른쪽 패널(`aside`)에 둔다.
6. **상태는 점 + 글자로 표시한다.** 배지는 재직·퇴직 예정·NEW 같은 분류 표시에만 쓴다.
7. **기능은 형태와 독립이다.** 부품은 기본 동작(키보드·aria)을 보장하고, 제약은 최소로 둔다.
---
## 3. 색
hex 값은 `tokens.css`에만 둔다. 화면 코드는 프리셋 클래스나 CSS 변수만 쓴다.
### 3.1 중립 — 무채색 11단계
| 토큰 | 값 | 용도 |
|---|---|---|
| `gray-0` | `#FFFFFF` | 카드·표면 |
| `gray-25` | `#FAFAFA` | 표 헤더, 행 hover |
| `gray-50` | `#F5F5F7` | 앱 배경 |
| `gray-100` | `#EFEFF1` | 입력 배경, 보조 버튼 |
| `gray-200` | `#E5E5E8` | 구분선 |
| `gray-300` | `#D1D1D6` | 강한 테두리(입력) |
| `gray-400` | `#B3B3B8` | 비활성 |
| `gray-500` | `#6B6B70` | 보조 글 — 0·50·100 어느 바탕에서도 AA |
| `gray-600` | `#5C5C61` | 라벨 |
| `gray-700` | `#3A3A3C` | 본문 |
| `gray-900` | `#111111` | 제목 |
시맨틱 이름(코드에서는 이쪽을 쓴다):
| 이름 | 연결 |
|---|---|
| `text-ink-strong` | 900 |
| `text-ink` | 700 |
| `text-ink-sub` | 600 |
| `text-ink-muted` | 500 |
| `text-ink-faint` | `#88888D` — **18px 이상 큰 글자 전용**(흐린 형제 제목) |
| `text-ink-disabled` | 400 |
| `border-line` | 200 |
| `border-line-strong` | 300 |
| `bg-app` | 50 |
| `bg-surface` | 0 |
| `bg-subtle` | 25 |
### 3.2 브랜드 그린
| 토큰 | 값 | 용도 |
|---|---|---|
| `green-50` / `bg-brand-soft` | `#E7F7EF` | 선택 행, 성공 배경 |
| `green-100` | `#CAEFDB` | 연한 강조 |
| `green-500` / `bg-brand` | `#03C75A` | **기준색**. 주 버튼 채움, 강조 점 |
| `green-600` / `bg-brand-hover` | `#02A04A` | hover |
| `green-700` / `text-brand-text` | `#037A3A` | 그린 글씨는 항상 이것 |
**그라데이션은 쓰지 않는다**(버튼·커버·배경 모두).
### 3.3 상태 — A안 「모노톤 + 그린」 (대표 확정 2026-11-16)
색은 그린·앰버·레드 세 가지만 쓴다. 나머지 상태는 잉크와 모양으로 구분한다. 토스 블루·바이올렛처럼 흔한 SaaS 색은 쓰지 않는다.
| 상태 | 점 | 배지(배경 / 글자) |
|---|---|---|
| `progress` 진행 중·정보 | `#3A3A3C` 짙은 잉크 | `#EFEFF1` / `#3A3A3C` |
| `done` 완료·성공 | `#03C75A` 그린 | `#E7F7EF` / `#037A3A` |
| `wait` 대기·승인 필요 | `#E0A100` 앰버 | `#FFF7DB` / `#8A6300` |
| `reject` 반려·위험 | `#E5484D` 레드 | `#FDECEC` / `#B4232A` |
| `plan` 예정·비활성 | 회색 **링** `#B3B3B8` | `#F5F5F7` / `#6B6B70` |
- 표·목록의 상태 열은 `StatusDot`(점 + 글자)으로 표시한다.
- `NEW` 배지는 `#B4232A` 바탕에 흰 글자를 쓴다(대비 AA).
### 3.4 아바타 파스텔
이름 해시로 8쌍(`--avatar-1..8-{bg,fg}`) 중 하나를 고른다. 글자 대비는 모두 4.5 이상이다. 이니셜 규칙:
- 한글 이름: 끝 두 글자(`김지나`→`지나`)
- 영문: 단어 첫 글자 둘(`Aaliyah Kim`→`AK`)
- 빈 값: `?`
---
## 4. 타이포그래피
서체는 **Pretendard** 하나만 쓴다.
| 클래스 | px / 행간 | 쓰는 곳 |
|---|---|---|
| `text-display-xl` | 72 / 86 | 홈페이지 히어로 |
| `text-display-lg` | 52 / 66 | 홈페이지 섹션 |
| `text-display` | 32 / 42 | 지표 숫자 |
| `text-display-sm` | 28 / 36 | 페이지 제목 |
| `text-heading` | 24 / 32 | 드로어 제목·프로필 이름 |
| `text-title` | 20 / 28 | 다이얼로그 제목 |
| `text-title-sm` | 18 / 26 | 섹션 제목 |
| `text-lead` | 16 / 24 | 탭·강조 문장 |
| `text-body-lg` | 15 / 22 | 필드 값 |
| `text-body` | 14 / 20 | **본문·표 기본** |
| `text-small` | 13 / 18 | 라벨·표 헤더·칩 |
| `text-caption` | 12 / 16 | 배지·보조 설명 |
- 자간: 18px 이상 -0.02em, 32px 이상 -0.03em(프리셋에 포함돼 있다).
- 굵기:
- 400: 본문
- 500: 라벨
- 600: 강조·버튼·탭(기본 강조)
- 700: 페이지·섹션 제목
---
## 5. 간격 · 모서리 · 그림자 · 레이아웃
- **간격**: 4px 격자(4·8·12·16·20·24·32·40·48·64). Tailwind 기본 간격 클래스를 쓴다.
- **모서리**(값 변수 `--ui-radius-*`): `rounded-xs` 6(배지) · `sm` 8(버튼·입력) · `md` 12(카드·드로어) · `lg` 16(큰 카드·홈페이지) · `xl` 24 · `full`
- **그림자**: 떠 있는 것에만 쓴다 — `shadow-pop`(메뉴·팝오버), `shadow-drawer`, `shadow-toast`. **카드는 1px 테두리만** 둔다.
- **레이아웃**:
- 사이드바: 240(접으면 64)
- 상단바: 56
- 상세 화면: `PageContainer width="detail"`(최대 1200). 목록 화면: `PageContainer`(fluid).
- 좌우 여백: 데스크톱 32, 모바일 16
- 768px 미만에서는 사이드바가 드로어로 바뀐다.
---
## 6. 부품 선택 규칙
| 하려는 것 | 쓸 것 |
|---|---|
| 앱 틀 | `AppShell` |
| 페이지 머리(제목·형제·탭·도구 줄) | `PageHeader` + `PageContainer` |
| 필터 칩 줄 | `FilterBar` |
| 표 열 표시·순서 | `ColumnSettingsPanel` |
| 목록 | `DataTable`(선택·고정 헤더·빈 상태·말줄임) |
| 상세 열기 | `Drawer`(+ `aside`에 `ApprovalSteps`) |
| 확인·경고 | `Dialog` |
| 인사카드 머리 | `ProfileHeader` |
| 라벨-값 묶음(4열) | `FieldGrid` / 세로 목록·변경 전→후는 `KeyValueList` |
| 처리 이력 | `ActivityLog` |
| 지표 | `StatCard`(증감 색은 「좋아졌는지」 기준) |
| 사람 × 날짜 | `ScheduleGrid` |
| 입력 | `Field`로 감싸고 `Input`·`Select`·`Combobox`·`DatePicker`… |
| 보기 전환(주/월) | `SegmentedControl` |
| 탭 | `Tabs`(밑줄형) |
| 알림 | `toast()` + 앱 루트 `` |
버튼:
- 한 화면의 주 버튼(`variant="primary"`)은 **하나**만 둔다.
- 파괴적 행동은 `danger`로 한다. 드로어나 다이얼로그에서 파괴적 버튼이 첫 포커스를 받지 않게 한다.
---
## 7. 접근성
- 모든 스토리는 axe 검사를 거치고, 위반이 있으면 실패시킨다(`.storybook/preview.tsx`, `a11y.test: 'error'`).
- 대비 기준: 본문 4.5:1, 큰 글자(18px+ 또는 14px bold+)와 UI 경계 3:1.
- **유일한 예외 — 주 버튼**:
- `#03C75A` 바탕에 흰 글자로 대비 2.25:1이다. 대표가 브랜드 예외로 확정했다(2026-11-16).
- 대신 글자 굵기 600을 쓴다.
- 예외는 `data-brand-fill`이 붙은 요소(주 버튼)에만 적용된다. 그린 위에 작은 글자를 올리는 다른 용도는 금지다.
- 색만으로 뜻을 전하지 않는다. 상태 점에는 글자를 붙이고, 아이콘만 있는 버튼에는 `aria-label`을 붙인다.
- 오버레이는 열리면 포커스를 가두고, Esc로 닫히며, 닫히면 트리거로 포커스가 돌아간다(Radix).
- 소비 앱이 preflight를 꺼도 같은 모습이어야 한다. 부품은 `box-border`와 기본 스타일 초기화를 스스로 한다.
---
## 8. 금지 목록
- hex·rgb 리터럴 하드코딩(`tokens.css` 밖)
- 그라데이션 버튼·커버·배경
- 토스 블루 `#3182F6`, 바이올렛 `#8B5CF6` 계열
- 카드 그림자
- 배지로 상태 열 채우기(점 + 글자를 쓴다)
- 한 화면에 주 버튼 둘 이상
- flex의 로고·일러스트·홈페이지 히어로·업데이트노트 썸네일 스타일
- 서버 전용 React(`react-server-dom-*`, `"use server"`) — zest-ui는 클라이언트 전용이다
---
## 8.5 다크 모드 · 강조색
- 다크 모드:
- 루트에 `.dark`(또는 `[data-theme="dark"]`)를 붙인다. 회색 램프를 뒤집는 방식이라 부품은 그대로 따라온다.
- 대비 기준은 라이트와 같다(`tokens.test.ts`).
- 주 버튼 글자 `--brand-fg`는 다크에서도 흰색으로 고정한다.
- 강조색:
- **구조(무채색·밀도·상태색)는 고정**하고 강조색만 바꾼다.
- `generateAccent(hex)` → `accentCss()`로 만든 `:root` 블록을 `tokens.css` 뒤에 붙인다.
- 그린 글씨 단계(700)는 흰 바탕과 연한 바탕 모두에서 4.5:1이 되도록 자동으로 보정한다.
## 9. AI 에이전트 작업 순서
1. 이 문서와 Storybook `Docs/원칙`을 읽는다.
2. 화면이 비슷한 쇼케이스(`Showcase/*`)를 찾아 구성을 그대로 따른다.
3. §6 표에서 부품을 고른다. 없으면 primitives를 조합하고, 여러 제품에서 반복되면 zest-ui patterns로 올린다.
4. 색·간격은 프리셋 클래스만 쓴다. 새 토큰이 필요하면 `tokens.css`·`tokens.test.ts`·이 문서를 같이 고친다.
5. 검증: `pnpm typecheck && pnpm test && pnpm build`. 화면 작업이면 1440·390 두 폭으로 캡처해 직접 본다.
6. 제품 레포에서는 `node scripts/zest-check.mjs src` 가 0건이어야 한다(`npx shadcn add @zest/zest-check`).
---
## 10. 레퍼런스와 차용 범위
flex는 디자인 시스템을 공개하지 않았다. 그래서 다음을 근거로 삼았다.
- 공개 홈페이지·헬프센터·업데이트 노트의 화면 약 1,100장 — `design/reference/flex/`
- FEConf 2022 발표
| 가져온 것 | 가져오지 않은 것 |
|---|---|
| Pretendard 단일 서체 | 그린→틸 그라데이션(→ 단색 `#03C75A`) |
| 무채색 회색 체계 | 틸 진행 중 상태(→ 짙은 잉크) |
| 페이지 문법(큰 제목·회색 형제·탭·필터 칩·표) | 파스텔 그라데이션 프로필 커버(→ 단색 연한 그린) |
| 오른쪽 상세 패널 + 승인 단계 | 로고·일러스트·히어로 |
| Radix 기반·기능과 형태 분리 원칙 | |
---
## 11. 제품별 메모
- **PANTE**: 아직 `@zest-im/ui` 0.2(legacy)를 쓴다. 제품 방향은 `design/pante.md`를 따른다. v1로 옮길 때 이 문서의 원칙·토큰을 그대로 적용한다.
- **zestim(사내 HR)**: v1의 첫 소비처다. 옮기는 순서는 스펙 §5.4를 따른다.