---
trigger: always_on
description: 제니트리 디자인 시스템 v5.0 — 이미 운영 중인 기존 앱에 안전하게 입히는 규칙
---

# JT 디자인 시스템 v5.0 — 기존 앱 규칙 (jt-legacy)

> 이 파일은 **이미 운영 중인 앱** 프로젝트에만 넣는다. 신규 앱에는 `jt-core`를 넣는다.
>
> 개정 2026-10-11 — §3 조사 항목 추가 · §5 변수명 충돌 해법 교체 · §8 멈춤 신호 추가 (결정로그 #88)

이 프로젝트는 사람이 실제로 쓰고 있는 앱이다. **겉모습만 바꾸고 기능은 손대지 않는다.**
집으로 치면 구조는 그대로 두고 페인트와 조명만 바꾸는 리모델링이다.

## 1. 절대 금지

- 기능 · 화면 구조 · 데이터 처리 로직 변경
- 클래스명 · 컴포넌트 이름 변경
- 여러 화면을 한 번에 변경
- 전역 리셋(`* { }`)이나 목업의 `body { }` 전역 스타일을 복사해 오는 것 — **CSS 파일 두 개를 링크**하고 필요한 값만 참조한다
- 요청받지 않은 파일 수정

## 2. v5.0에서 달라진 점 (기존 앱에 직접 영향)

- **본문 기준이 16px이다** (v4.0은 14px이었다). 대부분의 기존 앱이 이미 16px 기준이므로 **크기 충돌이 사라졌다.**
- 14px 기준으로 만든 앱이라면 `body`에 전역 적용 시 **글자와 여백이 함께 커진다.** 이는 정상 동작이다. 전역으로 되돌리지 말고, 데이터 밀집 화면만 `[data-density="compact"]`(14px)를 **그 영역에만** 건다.
- 이름은 같고 값만 바뀐 토큰이 많다 → **찾아 바꾸기가 아니라 파일 교체 + 화면 확인**이 방법이다.

## 3. 진행 순서 (건너뛰지 않는다)

한 번에 한 단계, 한 화면씩. 각 단계가 끝날 때마다 **멈추고 보고**한다.

1. **조사만** — 아래 두 가지를 파일명·줄번호와 함께 **목록으로만** 만든다.
   **이 단계에서는 아무것도 수정하지 않는다.**
   - 하드코딩된 색·글자크기·간격
   - **JT 토큰과 이름이 같은 변수** (§5 판별법). JT 파일을 링크하기 **전에** 확인한다.
2. **L1 색만** — 화면 **하나**에서 색만 교체. 간격·크기·레이아웃·구조는 건드리지 않는다.
3. **L2 글꼴** — `jt-tokens.css`를 링크한 것만으로 웹폰트는 이미 실려 있다. 적용만 한다.
4. **L3 컴포넌트** — 새로 만드는 화면부터 `.jt-*` 클래스로. 기존 화면은 하나씩.
5. **L4 간격·크기 (선택)** — 급하지 않으면 생략한다. 레이아웃이 조금이라도 틀어지면 즉시 중단.

## 4. 색 대응표

| 기존 용도 | JT 토큰 |
|---|---|
| 주버튼 배경 · 헤더 · 본문 글자 | `--color-primary` / `--color-text` |
| 링크 · 포커스 · 활성 탭 | `--color-accent` |
| 카드 · 패널 배경 | `--color-bg-container` |
| 페이지 배경 | `--color-bg-layout` |
| 테두리 | `--color-border` (**입력칸은 `--color-border-strong`**) |
| 구분선 | `--color-split` |
| 보조 글자 | `--color-text-secondary` |
| 성공 / 경고 / 오류 | `--color-success` / `--color-warning` / `--color-error` |
| 시험·규격 판정 | `--color-pass` / `-fail` / `-hold` / `-oos` |

**주버튼이 파란색이었다면 먹색(`--color-primary`)으로 바뀐다.** 이는 의도된 것이다(2톤 규칙).

## 5. 변수명 충돌 — JT 파일을 링크하기 전에 반드시 확인

### 왜 문제인가

기존 앱에 `--color-primary`·`--color-text` 같은 **JT와 같은 이름의 변수**가 있으면, 둘 중 하나가 다른 쪽을 덮어쓴다. **어느 쪽이 이기든 결과가 나쁘다.**

- **JT가 이기면** → 앱 전체 색이 **한꺼번에** 바뀐다 ("한 화면씩" 원칙이 깨진다)
- **앱이 이기면** → `.jt-*` 부품이 앱의 값으로 그려져 **틀린 모양**이 된다
- Tailwind v4의 `@theme` 변수는 레이어 안에 들어가므로 **링크 순서와 상관없이 JT가 이긴다**

⚠️ `.jt-scope`는 이 문제를 막지 못한다. `.jt-scope`는 "이 영역 안에서 JT 글꼴·색을 적용하라"는 표시일 뿐, 같은 이름의 덮어쓰기와는 무관하다.

### 판별 — 겹치는 이름을 찾으면 먼저 출처를 본다

| 출처 | 판정 | 조치 |
|---|---|---|
| 예전에 복사해 둔 **JT 토큰 파일**(v4.0 등, `--jt-ds-version`이 있거나 JT 주석이 붙은 파일) | 충돌 아님 — 업그레이드 대상 | 그 파일을 지우고 v5.0 링크로 교체 |
| **앱이 스스로 만든** 같은 이름 (`:root`, `@theme`, 컴포넌트 CSS 등) | **충돌** | 아래 "이름표 바꿔 달기" |
| 이름이 비슷하기만 함 (`--primary`, `--background`, `--radius` 등) | 충돌 아님 | 그대로 둔다 |

### 해결 — 앱 쪽 이름표 바꿔 달기

JT 파일은 절대 수정하지 않는다. **앱 쪽 변수 이름에 `app-`을 붙인다.**

- 일반 변수: `--color-primary` → `--app-color-primary`
- Tailwind v4 `@theme` 변수: 앞부분(`--color-`)을 유지해야 하므로 `--color-primary` → `--color-app-primary`

이 개명은 §1 "이름 변경 금지"의 **유일한 예외**다. **값은 그대로, 이름만** 바꾼다. 화면이 1px도 달라지면 안 된다.

**순서 (건너뛰지 않는다)**

1. 겹치는 이름 목록과 출처를 표로 보고하고 **승인을 기다린다**
2. 정의부와 **모든 사용처**를 한꺼번에 바꾼다 — CSS의 `var()`, `@theme`, JS의 `setProperty`·`getPropertyValue`, 인라인 `style`, Tailwind 설정
3. 옛 이름이 **정의·사용 모두 0건**인지 검색해 확인하고 결과를 보고한다 (사용처가 하나라도 남으면, JT를 링크하는 순간 그 자리만 JT 값으로 바뀐다)
4. 화면이 개명 전과 **똑같은지** 확인한다
5. 그다음에야 JT 파일 두 개를 링크한다

이렇게 하면 앱은 원래 모습 그대로 `--app-*` 이름으로 돌아가고, 이후 화면 하나씩 `var(--app-color-primary)` → `var(--color-primary)`로 옮기면 된다(§3의 2단계).

## 6. Tailwind를 쓰는 앱이라면

**버전을 먼저 확인한다.**

- **v4**: `tailwind.config.js`가 **에러 없이 조용히 무시된다.** `jt-tailwind-v4.css`(`@theme inline`)를 쓴다.
- **v3**: `tailwind.config.js` 브리지를 쓴다.
- `content` / `@source` 경로가 빠지면 **개발서버는 멀쩡하고 프로덕션 빌드에서만** 스타일이 사라진다. 배포 전 프로덕션 빌드로 확인한다.

## 7. 작업 후 보고 형식

수정한 내용을 반드시 **표로** 보고한다.

| 파일 | 줄 | 이전 값 | 바꾼 토큰 |
|---|---|---|---|
| `Header.jsx` | 12 | `#3B82F6` | `var(--color-accent)` |

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

- 레이아웃이 조금이라도 틀어졌을 때
- 기존 색과 딱 맞는 토큰이 없을 때 — **비슷한 색을 임의로 고르지 않는다**
- 기능이 바뀔 것 같은 수정이 필요할 때
- 이 앱에만 있는 특별한 색(차트 전용색 등)을 만났을 때 — 유지할지 물어본다
- 구조·클래스명을 바꿔야 할 것 같을 때
- **Tailwind v4 `@theme` 변수를 개명해야 할 때** — 개명하면 유틸리티 클래스 이름도 함께 바뀐다(`bg-primary` → `bg-app-primary`). 바뀌는 클래스 수를 세어 보고하고 승인을 받는다
- 개명 후 옛 이름이 남아 있거나 화면이 달라졌을 때