트랙 B — 이미 쓰고 있는 앱에 입히기

되돌릴 수 있습니다. 한 번에 다 바꾸지 않고, 화면 하나씩 시험합니다.

먼저 알아두세요 — 겁먹을 일이 아닙니다

지금 쓰는 앱을 멈추지 않습니다. 사본에서 작업합니다.
문제가 생기면 1분 안에 원래대로 되돌립니다 (STEP 1에서 준비합니다).
전부 다 할 필요 없습니다. 색만 바꿔도(L1) 목적의 80%가 달성됩니다.
순서는 반드시 색 → 글꼴 → 부품 → 간격. 간격이 화면을 가장 크게 흔들기 때문에 맨 마지막입니다.

되돌릴 수 있게 만들기★

3분

무엇을 하나요

이 단계를 건너뛰면, 문제가 생겼을 때 어디서부터 잘못됐는지 찾을 수 없습니다. 3분이면 끝나고, 이 3분이 트랙 B 전체의 안전망입니다.

AI 대화창에 그대로 붙여넣기

지금 코드를 안전하게 보관하고 싶어. 작업용 사본을 만들어줘.

1. 지금 상태를 그대로 저장(커밋)해줘.
2. "jds-v5" 라는 이름의 작업용 가지(브랜치)를 새로 만들고 거기로 옮겨줘.
3. 나중에 내가 "원래대로 되돌려줘" 라고 하면 어떻게 되돌리는지,
   그 명령을 미리 알려줘. 메모해 둘게.

✅ 이렇게 나오면 성공

AI가 되돌리는 명령 한 줄을 알려줬고, 그것을 메모해 뒀다.

Git을 안 쓰는 프로젝트라면 이걸로 충분합니다 — 폴더 전체를 복사해서 앱이름_백업_2026-09-13 같은 이름으로 저장.

진단은 AI에게 시키기★

5분

무엇을 하나요

“Tailwind가 v3인지 v4인지” 같은 질문은 본인이 답할 수 없는 게 정상입니다. 사람이 답하지 말고 AI가 코드를 열어보고 답하게 합니다.

AI 대화창에 그대로 붙여넣기

이 프로젝트에 제니트리 디자인 시스템 v5.0을 입히려고 해.
먼저 지금 상태를 진단해줘. 아래 6가지를 확인해서 표로 정리하고,
각 항목마다 "쉬움 / 주의 / 위험" 으로 표시해줘. 아직 아무것도 고치지 마.

1. 본문 글자 크기가 몇 px 인가? (16px 이 아니면 주의)
2. Tailwind 를 쓰나? 쓴다면 v3 인가 v4 인가?
   (v4 라면 tailwind.config.js 가 무시된다는 점을 알려줘)
3. --color-text 같은 CSS 변수 이름을 이미 쓰고 있나? (있으면 이름 충돌 위험)
4. 전역 리셋(* { box-sizing: border-box })이 있나?
5. 다크 모드가 이미 있나? 있다면 어떤 방식인가?
6. 화면이 총 몇 개인가? 파일 목록으로 보여줘.

마지막에 "이 앱은 L1(색만) 부터 시작하면 됩니다" 처럼
어디서 시작할지 한 줄로 추천해줘.

✅ 이렇게 나오면 성공

6줄짜리 표와 추천 한 줄을 받았다. 이 표를 캡처해 두세요. 이후 모든 대화에서 근거가 됩니다.

어디까지 할지 정하기

2분

무엇을 하나요

전부 할 필요가 없습니다. 채택 레벨을 정하고, 거기서 멈추면 됩니다.

레벨	쉬운 말	효과	위험	권장
L1 색	색만 회사 색으로	“같은 회사 앱”으로 보임	거의 없음	⭐ 여기까지만 해도 성공
L2 글꼴	글꼴을 회사 글꼴로	완성도 상승, 숫자 정렬 정돈	낮음	권장
L3 부품	버튼·입력칸·표를 회사 부품으로	화면이 진짜 통일됨	중간	여유 있으면
L4 간격	여백·글자 크기까지	완전 통일	높음 — 레이아웃이 흔들림	시간이 충분할 때만

→ 채택 레벨 상세

L1 색 — 화면 하나만 먼저★

20분

무엇을 하나요

가장 안전하고 효과가 큽니다. 앱 전체가 아니라 화면 딱 하나에서만 시험합니다. 가장 단순한 화면(목록 하나짜리 같은)을 고르세요.

AI 대화창에 그대로 붙여넣기

[대괄호] 부분은 지우고 본인 내용을 넣으세요.

"[가장 단순한 화면 이름]" 이 화면 하나에서만 색을 우리 토큰으로 바꿔줘.

토큰 파일은 아래 두 줄을 head 에 넣어서 연결해줘.
<link rel="stylesheet" href="https://ds.janytree.app/v5/jt-tokens.css">
<link rel="stylesheet" href="https://ds.janytree.app/v5/jt-utilities.css">

바꿀 때 지킬 것:
- 구조, 클래스 이름, 레이아웃은 절대 건드리지 마. 색 값만 바꿔.
- 직접 박아 넣은 hex 색을 var(--color-*) 로만 교체해.
- 주버튼은 먹색(--color-primary)이야. 파랑으로 만들지 마.
  파랑(--color-link)은 "누를 수 있다"는 신호로만 써.
- 어느 토큰으로 바꿔야 할지 애매하면 임의로 정하지 말고 나에게 물어봐.
- 다 바꾼 뒤 "바꾸기 전 색 → 바꾼 후 토큰 이름 → 어디에 쓰였는지"를
  표로 보여줘.

다른 화면은 아직 건드리지 마.

✅ 이렇게 나오면 성공

그 화면만 색이 바뀌었고 레이아웃이 그대로다
주버튼이 먹색이다 — 파랑이면 가장 흔한 일탈이니 즉시 다시 시키세요
변환표를 받았다

이상해졌다 — 되돌리는 문장

AI 대화창에 그대로 붙여넣기

방금 바꾼 것을 전부 되돌려줘. 바꾸기 직전 상태로 돌아가야 해.
되돌린 뒤 어떤 파일이 원래대로 돌아왔는지 알려줘.

화면 넓히기 — 하나씩 반복

화면당 10분

무엇을 하나요

화면 하나 → 눈으로 확인 → 다음. 한꺼번에 시키지 않습니다. 직전 화면에서 받은 변환표가 기준입니다.

AI 대화창에 그대로 붙여넣기

[대괄호] 부분은 지우고 본인 내용을 넣으세요.

"[다음 화면 이름]" 에도 같은 방식으로 색만 바꿔줘.
직전 화면에서 썼던 변환표와 똑같은 기준을 써. 새 토큰을 임의로 고르지 마.
다른 기준을 써야 하는 곳이 나오면 먼저 물어봐.

L2 글꼴

10분

무엇을 하나요

토큰 파일을 연결한 것만으로 회사 웹폰트가 이미 실려 있습니다. 적용만 하면 됩니다. 폰트 링크를 따로 넣지 마세요 — 중복 로딩으로 느려집니다.

AI 대화창에 그대로 붙여넣기

글꼴을 우리 것으로 바꿔줘.
- 본문 전체 : var(--font-base)
- 숫자가 들어가는 곳(가격, 수량, LOT번호, 표의 숫자 칸) : var(--font-num)
  그리고 font-variant-numeric: tabular-nums 도 같이 넣어줘.
  표에서 자릿수가 흔들리지 않게 하려는 거야.
- 폰트 링크를 새로 추가하지 마. jt-tokens.css 에 이미 들어 있어.
- 글꼴만 바꾸고 크기·간격은 건드리지 마.

✅ 이렇게 나오면 성공

글꼴이 바뀌었고, 표의 숫자 자릿수가 아래위로 딱 맞는다.

L3 부품 교체 — 화면 하나씩 (선택)

화면당 30분

무엇을 하나요

기존 버튼·입력칸·표를 회사 부품(.jt-*)으로 바꿉니다. 새로 만드는 화면부터 하는 것이 가장 안전합니다.

.jt-scope = 울타리. 이 울타리 안쪽에만 디자인 시스템이 적용됩니다. 좁게 시작해서 넓혀가세요.

AI 대화창에 그대로 붙여넣기

[대괄호] 부분은 지우고 본인 내용을 넣으세요.

"[화면 이름]" 의 버튼·입력칸·표를 우리 컴포넌트로 바꿔줘.

- 먼저 그 화면의 바깥을 <div class="jt-scope"> 로 감싸줘.
  이 울타리 안쪽만 시스템이 적용되게 하려는 거야.
- 그 안의 버튼 → .jt-btn (보조 버튼은 .jt-btn-ghost)
  입력칸 → .jt-input, 표 → .jt-table, 상태 표시 → .jt-badge-*
  전체 목록: https://ds.janytree.app/components
- 기능(클릭하면 뭐가 되는지)은 절대 바꾸지 마. 모양만 교체.
- 바꾼 뒤 직접 눌러볼 수 있게 해주고, 바꾼 목록을 표로 알려줘.

✅ 이렇게 나오면 성공

눌렀을 때 원래 하던 일이 그대로 된다. 모양만 달라졌다.

L4 간격 · 크기 — 마지막 (선택)

여유 있을 때만

🚫

레이아웃을 가장 크게 흔듭니다. 본문이 14px였던 앱이라면 16px로 바뀌면서 모든 여백이 함께 커집니다. 화면마다 눈으로 확인해야 합니다.

AI 대화창에 그대로 붙여넣기

간격과 글자 크기를 토큰으로 바꾸려고 해. 다만 위험하니까 순서대로 해줘.

1. 먼저 바꿨을 때 레이아웃이 깨질 가능성이 큰 곳을 예측해서 목록으로 보여줘.
   (고정 폭·고정 높이를 쓴 곳, 글자 크기에 맞춰 계산된 곳)
2. 내가 확인한 뒤에, 화면 하나씩만 바꿔줘.
3. 고정 width/height 는 min-width/min-height 로 바꿔줘.

지금은 1번만 해줘.

기록 남기기

2분

✅ 여기까지 하면 끝입니다

홈의 적용 현황 표에 어느 앱을 어느 레벨까지 올렸는지 적습니다. 예: JT-Estimate — L2 — v5.0

효과가 좋은 지시 방식

같은 일을 시켜도 문장에 따라 결과가 크게 달라집니다.

이렇게 ✅	이러지 마세요 🚫	왜
“이 파일에서 색상 값만 바꿔줘”	“디자인 시스템 적용해줘”	범위가 없으면 AI가 구조까지 바꿉니다
“한 번에 파일 하나”	“전체 프로젝트 한 번에”	깨졌을 때 원인을 못 찾습니다
“바꾼 내용을 표로 보고해줘”	(보고 요청 없음)	검증할 수 없습니다
“토큰에 없으면 물어봐”	(알아서 하게 둠)	AI는 없으면 지어냅니다
“구조·클래스명·레이아웃은 절대 건드리지 마”	(안 씀)	기존 앱 1순위 규칙입니다

→ 기존 앱 규칙 파일 jt-legacy · 자주 깨지는 곳 10가지

막혔을 때

뭘 하고 있는지 모르겠다

AI 대화창에 그대로 붙여넣기

지금 무엇을 하고 있는지, 어떤 파일을 고칠 계획인지
코딩을 모르는 사람이 이해할 수 있게 한국어로 설명해줘.
설명을 듣고 내가 진행 여부를 정할게.

색을 바꿨는데 아무 변화가 없다

AI 대화창에 그대로 붙여넣기

jt-tokens.css 와 jt-utilities.css 링크가 제대로 들어가 있는지 확인해주고,
개발자도구에서 실제로 불러와졌는지 검사하는 방법을 알려줘.
기존 CSS가 더 강한 우선순위로 덮어쓰고 있는지도 확인해줘.

개발할 땐 되는데 배포하면 깨진다

AI 대화창에 그대로 붙여넣기

Tailwind 를 쓰고 있다면 content 경로 설정 때문에 클래스가 빠졌을 수 있어.
설정 파일을 확인하고 문제를 알려줘.

화면이 뒤틀렸다 / 그 밖의 증상

레이아웃이 흔들렸다 → 안전 적용 규칙
자주 나오는 함정 → 자주 깨지는 곳 10가지
에러 문구가 뜬다 → 도움말 · 에러 사전

이 페이지의 모든 프롬프트를 한곳에서

→ 프롬프트 지갑 — 트랙 A·B의 프롬프트를 카드 11장으로 모아 둔 곳

용어 사전

사이트 용어	쉬운 말
토큰	회사가 정한 색·크기·간격의 값 이름표. #305CDE 대신 --color-link 라고 부르는 것.
컴포넌트	미리 만들어 둔 부품. 버튼, 입력칸, 표, 배지 같은 것.
하드코딩	값을 코드에 직접 박아 넣는 것. 나중에 한꺼번에 못 바꿔서 문제가 됩니다.
노브	부품에 달린 조절 손잡이(--jt-* 값). 부품을 뜯어고치지 말고 이것만 돌립니다.
스코프	시스템이 적용되는 울타리 범위(.jt-scope). 좁게 시작해 넓혀갑니다.
채택 레벨	어디까지 입혔는지 나타내는 단계. L1 색 → L2 글꼴 → L3 부품 → L4 간격.
Productive	업무형 조판. 일을 처리하는 앱에 씁니다. (기본값)
Expressive	홍보형 조판. 읽고 구경하는 페이지에 씁니다.
컨테이너	본문이 차지하는 최대 가로 폭. 720 / 1200 / 1440 중에 고릅니다.
텍스트 팽창	번역하면 글자가 길어지는 현상. 한글 3자가 영어 12자가 됩니다.
뷰포트 메타	휴대폰에서 화면이 축소돼 보이지 않게 하는 <head> 안의 한 줄 설정.
전역 리셋	브라우저가 기본으로 넣는 여백을 0으로 초기화해 두는 것.
MCP	AI가 다른 프로그램(스티치 등)을 직접 읽어오게 해주는 연결 통로.
스타터 킷	세팅이 이미 끝난 빈 프로젝트. 받아서 열기만 하면 됩니다.
컴포넌트 계약	부품을 쓸 때 앱이 지켜야 할 4가지 약속. 이것만 지키면 버전이 올라가도 안 깨집니다.
AGENTS.md	프로젝트 루트에 두는 AI용 규칙 파일. AI가 대화 시작 때 읽습니다.

⭐ 트랙 A — 새 앱을 만든다 프롬프트 지갑