🎉 디자인 시스템 v5.0 — 본문 16px · 컴포넌트 47종 · 스타터 킷 제공
시작하기⭐ 트랙 A — 새 앱을 만든다

트랙 A — 새 앱을 처음부터 만들기

코딩을 몰라도 됩니다. 문장을 복사해서 AI에게 붙여넣는 것이 전부입니다.

이 페이지 사용법
  1. 위에서부터 순서대로, 한 단계씩만 하세요.
  2. 각 단계의 파란 박스를 [복사] → AI 대화창에 붙여넣기 → 엔터.
  3. 초록 박스(✅ 이렇게 나오면 성공)를 확인한 뒤에 다음 단계로. 확인 안 하고 넘어가면 세 단계 뒤에 원인을 못 찾습니다.
  4. 박스 안 노란 [대괄호] 부분은 지우고 본인 앱에 맞게 바꿔 넣으세요.
준비물 — AI 코딩 도구 1개(어느 도구든 됩니다). 그 외 없음. · 전체 소요 — 처음이면 약 2시간 (화면 1개 기준)
0

이 길이 맞나요?

30초
무엇을 하나요

잘못된 트랙으로 가면 처음부터 다시 해야 합니다. 30초만 확인하고 갑니다.

지금 상황갈 곳
아직 아무것도 없다 / 새로 만든다트랙 A — 이 페이지
이미 돌아가는 앱이 있다트랙 B로 가세요
화면 디자인을 Google Stitch로 먼저 뽑았다트랙 A로 진행하되 STEP 4에서 (B) 선택
1

스타터 킷 받기★

5분
무엇을 하나요

토큰(= 회사 색·글꼴·간격의 값 이름표)이 이미 연결된 빈 프로젝트를 받습니다. 직접 세팅하면 사람마다 조금씩 달라지고, 그 차이가 나중에 전부 문제가 됩니다.

어느 것을 받나언제
순수 HTML 킷잘 모르겠으면 이것. 설치 없이 파일을 더블클릭하면 브라우저에서 열립니다
Next.js 킷나중에 로그인·데이터베이스를 붙일 계획이면

압축을 풀고 폴더 전체를 쓰고 계신 AI 도구에서 열기.

✅ 이렇게 나오면 성공
  • 폴더 안에 index.html(또는 app/)과 AGENTS.md가 보인다
  • HTML 킷이면 index.html을 더블클릭 → 브라우저에 표·버튼이 있는 예제 화면이 뜬다
  • 버튼이 먹색(짙은 회색)이다 — 파란 버튼이면 킷이 잘못 열린 것

킷 안에는 이미 들어 있습니다 — 토큰 링크 2줄, 뷰포트 메타 설정, 예제 화면(표·검색·배지·모바일 탭바·다크 전환), 그리고 AGENTS.md.

2

AI에게 규칙 심기★

3분
무엇을 하나요

AI는 규칙을 안 주면 자기가 아는 색(대부분 파란색)을 씁니다. 그 순간 브랜드 통일은 끝납니다. 이 3분을 아끼면 나중에 며칠을 씁니다.

AI 도구 첫 대화에 붙여넣기
프로젝트 루트에 규칙 파일(AGENTS.md · CLAUDE.md · GEMINI.md 중 이 도구가 읽는 것)이 있어.
이게 우리 회사 디자인 규칙 문서야. 이 파일은 절대 고치지 마.
(폴더를 읽을 수 없는 대화형 도구라면, 이 메시지 맨 아래에 규칙 문서 전체를 붙여넣을게.)

지금부터 아래를 지켜줘.
1. 먼저 그 규칙 문서를 읽고, 규칙을 몇 조 읽었는지 나에게 말해줘.
   읽지 못했다면 읽지 못했다고 말해. 읽은 척하지 마.
2. https://ds.janytree.app/llms.txt 도 읽어줘. 우리가 쓸 수 있는
   토큰과 컴포넌트 목록이 전부 들어 있어.
3. 앞으로 색·크기·간격에 숫자나 hex(#305CDE 같은 것)를 직접 쓰지 마.
   반드시 var(--color-...) 같은 토큰 이름을 써.
4. 버튼·입력칸·표 같은 부품은 새로 만들지 말고 .jt-btn, .jt-input,
   .jt-table 같은 기존 클래스를 써.
5. jt-tokens.css 와 jt-utilities.css 파일은 수정 금지.
   모양을 바꿔야 하면 --jt-* 값만 덮어써.
6. 토큰에 없는 값이 필요하면 지어내지 말고 나에게 물어봐.

다 읽었으면 "규칙 확인 완료"라고 말하고, 규칙 중 가장 중요한 3개를
네 말로 요약해줘. 아직 코드는 만들지 마.
✅ 이렇게 나오면 성공
  • AI가 규칙 확인 완료라고 답한다
  • 요약 3개 안에 hex를 직접 쓰지 않기와 .jt-* 클래스 쓰기가 들어 있다
  • 아직 파일을 만들지 않았다 — 만들었으면 규칙을 안 읽은 것이니 다시 시키세요
AGENTS.md 를 못 찾는다고 할 때
이어서 붙여넣기
AGENTS.md 파일을 못 찾겠으면, 프로젝트 루트에 어떤 파일들이 있는지 목록으로 보여줘.

그래도 없으면 → jt-core 규칙 페이지의 원본 파일을 내려받아 프로젝트 루트에 AGENTS.md로 저장하세요.

⚠️

AI 도구의 「프로젝트 규칙(Rules)」 기능에 등록해 두세요. 매번 붙여넣지 않아도 됩니다. 등록 방법 → AI 규칙 · 프롬프트

3

앱의 성격 3가지 정하기

3분
무엇을 하나요

나중에 바꾸면 화면을 다시 그려야 하는 3가지입니다. 용어는 몰라도 됩니다. 가운데 질문에만 답하세요.

정할 것쉬운 질문답이 이러면고를 것
글자 분위기이 앱에서 사용자가 “일을 처리”하나요, “읽고 구경”하나요?일을 처리Productive (업무형·기본)
읽고 구경Expressive (홍보형)
본문 폭화면에 표·데이터가 많나요?글 위주 문서narrow 720
보통 업무 앱max 1200 (기본)
표가 아주 넓음wide 1440
휴대폰공장·창고에서 폰으로 볼 일이 있나요?있다주요 메뉴 5개 이하 → 하단 탭바
없다PC만
정하기 어려우면 AI에게 물어보세요

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

내가 만들 앱은 [예: 원료 입고 검사 결과를 기록하고 판정하는 앱]이야.
주 사용자는 [예: 공장 품질팀 3명]이고, 주로 [예: PC, 가끔 휴대폰]으로 봐.

이 앱에 맞는 조판(Productive/Expressive), 컨테이너 폭(720/1200/1440),
모바일 하단탭 필요 여부를 추천해주고, 왜 그런지 한 줄씩 이유를 알려줘.
아직 코드는 만들지 마.
✅ 이렇게 나오면 성공
3가지가 메모에 적혔다. (다음 단계에서 그대로 씁니다)
4

뼈대 만들기

15분
무엇을 하나요

상단바·왼쪽 메뉴·본문이 있는 집의 골조를 세웁니다. 내용은 아직 가짜 데이터입니다.

(A) 스티치를 안 쓴 경우 — 대부분 이쪽입니다

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

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

이제 앱의 기본 뼈대를 만들어 줘.

- 앱 이름 : [앱 이름]
- 하는 일 : [한 줄 설명]
- 조판 : [Productive / Expressive]
- 본문 폭 : [720 / 1200 / 1440]
- 모바일 : [하단 탭바 있음 / PC만]
- 왼쪽 메뉴에 들어갈 것 : [메뉴1], [메뉴2], [메뉴3]

지킬 것:
- 화면 골격은 처음부터 그리지 말고
  https://ds.janytree.app/develop/patterns 의 패턴과
  https://ds.janytree.app/develop/templates 의 템플릿에서 골라서 써.
  어떤 것을 골랐는지 이유와 함께 알려줘.
- 클래스는 .jt-shell / .jt-sidebar / .jt-topbar / .jt-main 을 쓴다.
- 색·간격에 직접 값을 쓰지 않는다. 토큰 이름만 쓴다.
- 지금은 뼈대만. 개별 화면과 기능은 다음 단계에서 한다.

끝나면 (1) 만든 파일 목록 (2) 고른 패턴 이름과 이유를 알려줘.

(B) Google Stitch로 디자인을 먼저 뽑은 경우

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

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

스티치 MCP에서 공통 뼈대(상단바, 왼쪽 메뉴, 본문 영역)를 읽어와서 구현해 줘.

중요 — 스티치가 준 코드를 그대로 붙이지 말고 반드시 아래를 정리한 뒤 넣어 줘.
- 임의 색(#305CDE 같은 hex)은 var(--color-*) 토큰으로 바꾼다.
- 임의 크기(p-[13px], text-[15px] 같은 대괄호 표기)는 토큰으로 바꾼다.
- Tailwind 기본 색(bg-blue-500, text-gray-600 등)은 뜻이 같은 우리 이름으로 바꾼다.
- 어느 이름으로 바꿔야 할지 애매하면 임의로 정하지 말고 먼저 나에게 물어봐.

끝나면 바꾼 것을 표로 보여 줘. (바꾸기 전 → 바꾼 후 → 이유)
✅ 이렇게 나오면 성공
  • 브라우저에 상단바 + 왼쪽 메뉴 + 본문이 보인다
  • 버튼이 먹색이다 — 파란 버튼이면 STEP 2로 돌아가세요
  • (B의 경우) 변환표가 출력됐다. 표가 없으면 정리를 안 한 것입니다
5

화면 하나씩 만들기 — 화면 개수만큼 반복★

화면당 20~40분
🚫

한 번에 화면 여러 개를 요청하지 마세요. 하나 만들고 → 실제로 눌러 보고 → 다음. 이것이 가장 흔한 실패 원인입니다.

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

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

"[화면 이름]" 화면을 만들어 줘.

[이 화면이 하는 일]
[한두 줄 설명]

[화면에 들어가는 것]
1. [항목] — [예: 표, 검색창, 등록 버튼]
2. [항목] — [입력 방식]

지킬 것:
- 버튼·입력칸·표·배지는 새로 만들지 말고 .jt-* 기존 컴포넌트를 가져다 쓴다.
  목록: https://ds.janytree.app/components
- 색·크기·간격에 직접 값을 쓰지 않는다. 토큰만 쓴다.
- 빈 상태(데이터가 없을 때)와 로딩 상태도 함께 만든다.
- 지금은 화면(보이는 부분)만. 데이터 연결과 기능은 다음 단계.
  가짜 데이터를 5줄 정도 넣어서 화면이 어떻게 보이는지 볼 수 있게 해줘.

끝나면 어떤 .jt-* 컴포넌트를 썼는지 목록으로 알려줘.
✅ 이렇게 나오면 성공
  • 화면이 보이고, 가짜 데이터가 5줄 들어 있다
  • AI가 쓴 컴포넌트 목록을 보고했다 (새로 만든 부품이 있으면 왜 필요했는지 물어보세요)
  • 데이터를 다 지웠을 때 “내용이 없습니다” 같은 빈 상태가 보인다
6

기능 붙이기 — 화면마다

화면당 30분~
AI 대화창에 그대로 붙여넣기

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

"[화면 이름]" 화면에 기능을 붙여 줘.

[이 화면에서 되어야 하는 일]
- [예: 목록을 데이터베이스에서 불러온다]
- [예: 검색창에 글자를 넣으면 이름으로 걸러진다]
- [예: 추가 버튼을 누르면 입력창이 뜨고, 저장하면 목록에 반영된다]
- [예: 삭제는 확인창을 거친 뒤에만 실행된다]

[주의할 것]
- 화면 모양은 바꾸지 말고, 기능만 붙여줘.
- 확인창은 브라우저 기본 팝업(alert, confirm) 대신 앱 안의 모달로 만들어줘.
- 저장에 실패했을 때 사용자에게 보여줄 문구도 만들어줘.
  문구 원칙: https://ds.janytree.app/develop/ux-writing
- 무엇이 잘못됐는지 나에게도 알려줘.
✅ 이렇게 나오면 성공

직접 눌러봅니다. 저장·삭제·검색이 되고, 브라우저 기본 팝업이 뜨지 않는다.

7

눈으로 확인

10분
AI에게 점검시키기
지금 화면을 아래 4가지로 점검하고, 문제가 있으면 어디인지 알려줘. 아직 고치지는 마.
1. 다크 모드 — document.documentElement.dataset.theme='dark' 로 바꿨을 때
   글자가 안 보이는 곳이 있는지
2. 모바일 — 폭 390px 에서 가로 스크롤이 생기는 곳이 있는지
3. 글자 팽창 — 버튼 글자를 3배 길게 넣었을 때 깨지는 곳이 있는지 (번역 대비)
4. 판정·상태를 색만으로 표시한 곳이 있는지 (글자가 함께 있어야 함)

내 눈으로도 이 3가지만 확인합니다

확인어떻게
다크 모드앱에서 다크로 전환 → 글자가 배경에 묻히지 않는가
휴대폰브라우저 창을 손가락 두 개 폭까지 줄이기 → 좌우로 밀리면 실패
회색 글자아주 연한 회색 글자가 있으면 → 읽을 수 있는가

→ 잘 됐는지 확인하기

8

배포 전 점검 + 기록

10분
AI 대화창에 그대로 붙여넣기
배포 전 점검을 해줘.
https://ds.janytree.app/develop/checklist 의 16항목을 기준으로
프로젝트 전체를 검사하고, 파일 이름과 줄 번호를 표로 보여줘.

특히 이 3개는 실제로 사고가 났던 것이니 반드시 확인해줘.
1. --color-text-tertiary 를 글자 색으로 쓴 곳 (대비 부족)
2. 아이콘 폰트를 display=block 으로 로드했는지
   (swap 이면 아이콘 대신 settings 같은 영어 원문이 보입니다)
3. 판정·상태를 색만으로 전달한 곳

아직 고치지 말고, 무엇부터 고칠지는 내가 정할게.
✅ 기록까지 해야 끝입니다

배포 후 홈의 적용 현황 표에 앱 이름 · 채택 레벨 · DS 버전을 추가하세요. 안 하면 다음 버전업 때 어떤 앱이 뒤처졌는지 아무도 모릅니다.

9

나중에 화면을 추가할 때★

며칠 뒤·몇 주 뒤
무엇을 하나요

AI는 지난주에 정한 규칙을 기억하지 못합니다. 이 문장 없이 새 화면을 시키면 그 화면만 모양이 다릅니다. 가장 흔한 실수입니다.

며칠 뒤 작업은 반드시 이 문장으로 시작

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

새 화면 "[화면 이름]" 을 추가하려고 해.
시작하기 전에 반드시 아래 순서로 확인하고, 확인한 내용을 나에게 요약해줘.

1. 프로젝트 루트의 규칙 파일(AGENTS.md · CLAUDE.md · GEMINI.md)을 읽어서 디자인 규칙 확인
2. 이 프로젝트가 쓰는 토큰 목록 확인 (jt-tokens.css)
3. 이미 만들어 둔 공용 부품이 무엇인지 확인
4. 비슷한 기존 화면 하나를 열어서 구조와 여백 쓰는 법 확인

그다음 기존 화면들과 똑같은 결로 새 화면을 만들어 줘.

[이 화면이 하는 일]
[설명]

[화면에 들어가는 것]
1. [항목] — [입력 방식]
2. [항목] — [입력 방식]

새 버튼 모양이나 새 색을 만들지 마. 기존 것으로 안 되면 먼저 나에게
"이런 게 필요한데 새로 만들어도 될까요?" 라고 물어봐 줘.
10

디자인이 흐트러진 느낌이 들 때

한 달에 한 번
AI 대화창에 그대로 붙여넣기

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

프로젝트 전체를 점검해 줘.

1. 색을 직접 박아 넣은 곳을 전부 찾아줘 (#305CDE 같은 hex, rgb())
2. 크기를 직접 박아 넣은 곳을 찾아줘 (p-[13px], text-[15px] 같은 대괄호 표기)
3. Tailwind 기본 색을 쓴 곳을 찾아줘 (bg-blue-*, text-gray-*, bg-slate-* 등)
4. style={{ }} 로 색이나 간격을 직접 지정한 곳을 찾아줘
5. .jt-* 공용 부품을 안 쓰고 따로 만든 버튼·입력칸이 있는지 찾아줘
6. jt-tokens.css 나 jt-utilities.css 를 수정한 흔적이 있는지 확인해줘

파일 이름과 줄 번호를 표로 보여 주고, 아직 고치지는 마.
무엇부터 고칠지는 내가 정할게.

막혔을 때 — 그대로 붙여넣는 문장

뭘 하고 있는지 모르겠다
AI 대화창에 그대로 붙여넣기
지금 무엇을 하고 있는지, 어떤 파일을 고칠 계획인지
코딩을 모르는 사람이 이해할 수 있게 한국어로 설명해줘.
설명을 듣고 내가 진행 여부를 정할게.
스타일이 아예 안 먹는다 (색도 글꼴도 그대로)
AI 대화창에 그대로 붙여넣기
jt-tokens.css 와 jt-utilities.css 링크가 제대로 들어가 있는지 확인해주고,
개발자도구에서 실제로 불러와졌는지 검사하는 방법을 알려줘.

→ 잘 됐는지 확인하기

개발할 땐 되는데 배포하면 깨진다
AI 대화창에 그대로 붙여넣기
Tailwind 를 쓰고 있다면 content 경로 설정 때문에 클래스가 빠졌을 수 있어.
설정 파일을 확인하고 문제를 알려줘.

→ 툴체인

스티치에서 못 읽어온다
AI 대화창에 그대로 붙여넣기
스티치 MCP가 연결되어 있는지 확인해 주고, 지금 쓸 수 있는 도구 목록을 보여 줘.
만든 화면이 스티치 디자인과 다르다
AI 대화창에 그대로 붙여넣기
지금 만든 화면이 스티치 디자인과 좀 다른 것 같아.
스티치 MCP로 그 화면을 다시 읽어서 어디가 다른지 비교해 주고,
디자인 쪽에 맞춰서 고쳐 줘.
화면이 뒤틀렸다 / 그 밖의 증상

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

며칠 뒤에 “그 문장이 어디 있었지” 하고 찾게 됩니다. 즐겨찾기는 이쪽으로 하세요.

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

용어 사전

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