16. 스택별 적용

16-0. 정본 경로는 하나입니다 ★

🚫

사내 PDF(「3. 안티그래비티」)와 이 사이트가 서로 다른 방식을 지시하고 있었습니다. 둘 다 읽으면 반드시 혼란스럽습니다. 정본은 사이트입니다.

	정본 — 사이트 방식 ✅	구 PDF 방식 (더 이상 쓰지 않음)
기준 문서	사이트 `llms.txt` + 프로젝트 루트 `AGENTS.md`	`JANYTREE_DESIGN.md` 를 프로젝트에 넣음
토큰	CDN 링크 2줄 (`/v5/jt-tokens.css`)	프로젝트 안에 `styles/tokens.css` 를 복사 생성
클래스	`.jt-btn` `.jt-table` 같은 *`.jt-` 유틸리티**	Tailwind `@theme` 이름 (`bg-surface`, `text-ink`)
부품	이미 제공되는 47종	`components/ui/` 에 직접 제작

왜 사이트 방식인가 — 스타터 킷이 있어서 세팅이 필요 없고, 우리가 v5.1을 내면 링크를 건 앱은 자동으로 따라옵니다. 파일을 복사해 둔 앱은 영영 옛 값에 머뭅니다.

⚠️

Tailwind 앱이라면 아래 16-2 브리지를 쓰세요. PDF의 bg-surface · text-ink 같은 이름은 브리지 파일이 쓰는 이름과 다릅니다. 이름이 두 벌이면 AI가 둘 다 씁니다 — 브리지 파일(jt-tailwind-v4.css)이 내보내는 이름만 쓰세요.

16-1. 스택별 진입점

스택	방법
순수 HTML/CSS	`jt-tokens.css` + `jt-utilities.css` 링크. 끝
Next.js / React	`globals.css`에서 두 파일 `@import`, `<html data-theme>` 토글
Tailwind	§16-2 브리지 파일 사용
antd / React	ConfigProvider의 `theme.token`에 Alias 값 매핑
AppSheet 등 노코드	앱 테마에 primary·폰트만 수동. 표 서식에 §12 Table 규칙 수동 반영
AI 에이전트(바이브 코딩)	이 문서 + `jt-tokens.css`를 프로젝트에 첨부하고 “이 토큰만 쓰고 임의 색·px 값을 만들지 말 것”으로 지시

16-2. Tailwind 브리지 (선택) 〔v5.0 신설〕

Tailwind를 쓰지 않는 앱은 이 절을 건너뛰세요. 브리지 파일은 Google Stitch 등이 Tailwind 코드를 뱉었거나, 앱이 이미 Tailwind인 경우에만 필요합니다. 링크하지 않으면 용량 0입니다.

Tailwind 버전	파일	방식
v4	`jt-tailwind-v4.css`	`@theme inline` + `@custom-variant dark`
v3	`tailwind.config.js`	`theme.extend` + `darkMode:['selector','[data-theme="dark"]']`

브리지의 Tailwind 노출 이름은 토큰 이름과 일부러 다릅니다 (text-ink, bg-brand, border-line 등). 같은 이름을 쓰면 Tailwind v4의 @theme inline에서 --color-accent: var(--color-accent) 자기 참조가 생겨 색이 사라집니다. (실제 빌드로 재현·확인한 사고입니다.)

⚠️ Tailwind v4에서 tailwind.config.js는 조용히 무시됩니다 — @config를 명시하지 않으면 아무 에러 없이 스타일만 안 먹습니다. 버전을 먼저 확인하세요.

⚠️ content / @source 경로 누락은 개발 서버에서는 멀쩡하고 프로덕션 빌드에서만 스타일이 사라집니다. 배포 전 반드시 프로덕션 빌드로 확인하세요.

16-3. 툴체인 (Stitch → Antigravity 등)

디자인 툴을 옮겨 다니며 개발하는 경우의 에러 방지 절차는 별도 문서 TOOLCHAIN.md 에 있습니다. 핵심 3가지만:

임의 값 검색: \[#[0-9a-fA-F]{3,8}\] (하드코딩 색) · \[\d+px\] (하드코딩 크기) — 잡히면 토큰으로 치환
Tailwind 버전 확인 먼저
프로덕션 빌드로 확인 후 배포

페이지 템플릿 툴체인 (Stitch → Antigravity)