# 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를 따른다.