---
trigger: always_on
description: 제니트리 디자인 시스템 v5.0 — 새로 만드는 앱의 화면 제작 규칙
---

# JT 디자인 시스템 v5.0 — 신규 앱 규칙 (jt-core)

이 파일을 프로젝트 루트에 `AGENTS.md` · `CLAUDE.md` · `GEMINI.md` 중 쓰는 도구가 읽는 이름으로 저장하세요. (Cursor는 `.cursor/rules/` 폴더 또는 `AGENTS.md`)
전체 스펙이 필요하면 https://ds.janytree.app/llms.txt 를 첫 대화에 붙여넣습니다.

## 1. 앱 정보 (프로젝트 시작 시 채울 것)

- 앱 이름: [ ]
- 분야: [ ]
- 기술 스택: [ ]
- 디자인 시스템 버전: **v5.0**
- 채택 레벨: **L4 (신규 앱은 처음부터 전면 적용)**
- 조판: [ Productive (업무용·기본) / Expressive (브랜드·랜딩) ]
- 컨테이너: [ narrow 720 / max 1200 / wide 1440 / full ]

## 2. 설치 — 이 두 줄이 전부다

```html
<link rel="stylesheet" href="https://ds.janytree.app/v5/jt-tokens.css">
<link rel="stylesheet" href="https://ds.janytree.app/v5/jt-utilities.css">
```

- **웹폰트를 따로 넣지 않는다.** `jt-tokens.css`에 Pretendard·Figtree 로드가 내장돼 있다.
- 값의 정본은 **`jt-tokens.css` 하나**다. 문서와 값이 다르면 파일이 맞다.
- **이 두 파일을 편집하지 않는다.** 값을 바꿔야 하면 디렉터에게 요청한다.

## 3. 절대 규칙 (어기면 결과물을 폐기한다)

1. **색·크기·간격에 리터럴 값을 쓰지 않는다.** `#hex` · `rgb()` · 임의 `px` 전부 금지. 반드시 `var(--토큰)`.
2. **Tailwind 임의값 대괄호 표기 금지** — `bg-[#305CDE]` `text-[13px]` `p-[7px]` 등.
3. **z-index 숫자 금지.** `--z-base/raised/sticky/drawer/dropdown/overlay/modal/toast/tooltip` 만.
4. **원시 팔레트를 컴포넌트에서 직접 쓰지 않는다.** `--blue-500` 아니라 `--color-accent`. 그래야 다크·밀도 전환이 자동으로 된다.
5. **시스템 CSS를 수정하지 않는다.** 모양을 바꿔야 하면 `--jt-{컴포넌트}-*` 노브만 덮어쓴다.
   ```css
   .checkout .jt-btn { --jt-btn-min-w: 120px; }   /* ✅ */
   .jt-btn { min-width: 120px; }                  /* 🚫 */
   ```
6. **고정 `width`/`height` 금지.** `min-width` / `min-height`를 쓴다 (번역 시 글자가 최대 7배까지 길어진다).
7. **판정·상태를 색만으로 전달하지 않는다.** 반드시 글자를 병기한다 — 흑백으로 인쇄되는 COA·시험성적서에서 색은 사라진다.
8. **`--color-text-tertiary`를 글자에 쓰지 않는다.** 대비 3.04:1로 기준 미달. placeholder·도움말도 텍스트이므로 `--color-text-secondary`를 쓴다.
9. **`word-break: keep-all`을 전역이나 중국어·일본어·태국어에 적용하지 않는다.** 토큰 파일이 `:lang(ko)` 한정으로 이미 처리한다.
10. **필요한 값이 토큰에 없으면 지어내지 말고 "토큰에 없다"고 보고한다.**

## 4. 브랜드 규칙 — 2톤 모델

| 색 | 의미 | 쓰는 곳 |
|---|---|---|
| Charcoal `--color-primary` | "이것이 제니트리다" | 솔리드 주버튼 · 헤더 · 본문 글자 |
| Blue `--color-accent` | "여기를 누를 수 있다" | 링크 · 포커스 · 활성 탭 · 선택된 행 |

**주버튼을 파랑으로 만들지 않는다.** 가장 흔한 일탈이며 브랜드가 즉시 흐려진다.
뉴트럴이 화면의 90%, 색은 의미가 있을 때만 쓴다.

## 5. 컴포넌트

`.jt-*` 클래스 47종을 쓴다. 목록과 코드는 https://ds.janytree.app/components

자주 쓰는 것:

```html
<button class="jt-btn">저장</button>            <!-- ghost / danger / sm / lg -->
<input class="jt-input">                        <!-- textarea / date 는 .jt-textarea / .jt-date -->
<span class="jt-badge jt-badge-pass">적합</span> <!-- fail / hold / oos -->
<div class="jt-table-wrap"><table class="jt-table">…</table></div>
<dl class="jt-desc"><dt>LOT</dt><dd class="jt-num">26H21-03</dd></dl>
```

- 표의 숫자열은 **우측 정렬 + `class="jt-num"`** (Figtree + 자릿수 정렬).
- 표는 반드시 `.jt-table-wrap`으로 감싼다. 없으면 가로 스크롤이 페이지 전체로 번진다.
- 모바일 도움말은 `.jt-tooltip`(hover)이 아니라 **`.jt-toggletip`(클릭)** 을 쓴다.
- 모바일 주요 메뉴는 상단이 아니라 **하단 탭바 `.jt-tabbar`** (5개 이하).

## 6. 화면 완성 시 자가 점검 (매번 실행)

점검하고, 위반이 있으면 고친 뒤 **무엇을 고쳤는지 보고**한다.

- [ ] `#hex` · `rgb()` · 임의 `px` 직접 사용 0건
- [ ] Tailwind 임의값 대괄호 표기 0건
- [ ] z-index 숫자 직접 사용 0건
- [ ] 주버튼이 먹색 `--color-primary`인가 (파랑 아님)
- [ ] `--color-accent`(파랑)가 링크·포커스·활성에만 쓰였는가
- [ ] warning이 노란 배경 + 어두운 글자인가 (흰 글자 아님)
- [ ] `--color-text-tertiary`를 글자에 쓴 곳 없음
- [ ] 판정·상태에 글자가 병기되어 있음
- [ ] 12px 미만 글자 없음 (캡션 11px 예외)
- [ ] 간격 값이 모두 4px 배수
- [ ] 고정 width/height 없음 (min-* 사용)
- [ ] 모바일 폭(≤639px)에서 가로 스크롤·글자 잘림 없음
- [ ] 다크(`data-theme="dark"`)에서도 글자·테두리가 전부 보임
- [ ] 아이콘만 있는 버튼에 `aria-label` 있음
- [ ] 표가 `.jt-table-wrap`으로 감싸여 있음
- [ ] 토큰에 없는 값을 임의로 만든 곳 없음

## 7. 멈춤 신호 — 진행하지 말고 즉시 질문

- 필요한 색·크기가 토큰에 없을 때
- `jt-tokens.css` 또는 `jt-utilities.css`를 수정해야 할 것 같을 때
- 요청받지 않은 파일을 고쳐야 할 것 같을 때
- 구조(무엇을 화면에 넣을지)를 임의로 정해야 할 때