툴체인 — 툴을 옮겨 다닐 때 에러 막기

작성일 2026-08-21 · 대상: Google Stitch로 레이아웃 → Antigravity로 개발하는 팀 필요 파일: jt-tokens.css jt-utilities.css + (Tailwind v4) jt-tailwind-v4.css / (v3) tailwind.config.js

0. 왜 사고가 나는가 — 원인은 하나입니다

Stitch는 자기만의 디자인 값을 만들어냅니다. 색·간격·타입 스케일을 스스로 정해서 DESIGN.md와 Tailwind 클래스로 뱉습니다. 그 결과 값의 정본이 두 개가 됩니다.

jt-tokens.css  ←  회사 정본
DESIGN.md      ←  Stitch가 방금 지어낸 값     ← 충돌

Antigravity의 AI는 프로젝트 안에 있는 문서를 읽고 코드를 짭니다. DESIGN.md가 그대로 있으면 AI가 그걸 따릅니다. 우리 토큰이 아니라요. 툴을 옮길 때 생기는 문제 대부분이 여기서 출발합니다.

해결 원칙: Stitch 출력은 “레이아웃 초안”으로만 받고, 값은 전부 JT 토큰으로 갈아끼운 뒤 개발을 시작합니다. Stitch 스스로도 결과물을 “스타터 코드”라고 부릅니다 — 프로덕션 코드가 아닙니다.

1. Stitch 단계 — 만들 때부터 줄여두기

① 프롬프트에 값 제약을 넣습니다. Stitch는 지시하지 않으면 자기 팔레트를 씁니다.

다음 제약을 지켜서 화면을 만들어줘.
- 주 색상은 #1F2328 (charcoal), 강조·링크는 #305CDE (blue)만 사용
- 그 외 색은 회색 계열만. 초록·주황·보라 등 임의 색 금지
- 본문 16px 기준, 간격은 4의 배수만 (4/8/12/16/24/32)
- 모서리 8px, 그림자는 아주 옅게 한 단계만
- 버튼은 charcoal 배경 + 흰 글자. 파란 버튼 만들지 말 것
- 한국어 UI. 버튼 라벨은 길어질 수 있으니 고정 폭 쓰지 말 것

② 내보내기는 HTML/CSS 또는 Tailwind 중 하나로 통일합니다. 화면마다 다른 형식으로 받으면 병합할 때 깨집니다.

③ 받은 뒤 반드시 확인할 것 — Stitch 출력은 영어 기준으로 만들어집니다. 한국어를 넣으면 글자 길이가 달라져 레이아웃이 흔들립니다. 실제 한국어 문구로 바꿔서 한 번 보세요.

2. 이관 단계 — Antigravity에 넣기 전 5분 정리

이 5개만 하면 사고의 90%가 사라집니다.

⛔ ① DESIGN.md는 프로젝트에 넣지 않습니다

가장 중요합니다. 넣더라도 _reference/stitch-design.md처럼 AI가 규칙으로 오해하지 않을 위치·이름으로 옮기고, 파일 맨 위에 이렇게 적습니다.

> ⚠️ 참고용 초안입니다. 이 문서의 색·간격 값은 사용하지 마세요.
> 값의 정본은 jt-tokens.css 입니다.

대신 jt-core.md(신규 앱 규칙)를 프로젝트 규칙 파일로 등록합니다. AI가 따라야 할 문서는 이것 하나입니다.

⛔ ② 하드코딩된 색·크기를 전부 찾아 바꿉니다

Stitch 출력에는 bg-[#1F2328], text-[10px] 같은 임의값이 섞여 나옵니다. 이게 남아 있으면 다크 모드가 안 먹고, 토큰을 바꿔도 화면이 안 따라옵니다.

찾는 법 — 편집기에서 정규식 검색:

\[#[0-9a-fA-F]{3,8}\]     ← 임의 색   bg-[#1F2328]
\[\d+px\]                  ← 임의 크기 text-[10px]

바꾸는 법 — 아래 대응표대로. AI에게 이렇게 시켜도 됩니다:

“이 파일의 임의값 클래스(대괄호 표기)를 전부 jt-tailwind 브리지의 이름 클래스로 바꿔줘. bg-[#1F2328] → bg-brand 식으로. 값은 절대 새로 만들지 말고 대응표에 없으면 멈추고 물어봐.”

⛔ ③ Tailwind 버전을 먼저 확정합니다

v3와 v4는 설정 방식이 완전히 다릅니다. 섞이면 “빌드는 되는데 스타일이 안 먹는” 최악의 증상이 납니다.

확인 방법: package.json의 tailwindcss 버전을 봅니다.

v4에서 tailwind.config.js는 그냥 무시됩니다. 에러도 안 납니다. 설정을 했는데 아무 일도 안 일어나면 이걸 의심하세요. 굳이 써야 하면 CSS에 @config "./tailwind.config.js";를 명시해야 합니다.

⛔ ④ 스캔 경로(content / @source)를 확인합니다

Tailwind는 소스 파일을 훑어서 실제로 쓰인 클래스만 CSS에 넣습니다. 경로가 빠지면 그 파일의 스타일이 통째로 사라집니다.

증상이 고약합니다 — 개발 서버에선 멀쩡하고 배포 후에만 스타일이 없어집니다. 그리고 Tailwind는 모르는 클래스에 에러를 내지 않습니다. 그냥 아무것도 안 만듭니다.

또 하나: 클래스 이름을 문자열로 조립하면 잡히지 않습니다.

// ❌ 스캔 안 됨 — 화면에 아무 색도 안 나옴
<div className={`text-${status}`}>
// ✅ 전체 이름을 그대로 쓰기
<div className={status === 'pass' ? 'text-qc-pass' : 'text-qc-fail'}>

⛔ ⑤ 폰트·기준 크기를 확인합니다

Stitch는 Inter나 시스템 폰트로 내보냅니다. jt-tokens.css를 링크하면 Pretendard가 자동으로 따라오므로, Stitch가 넣은 폰트 <link>와 font-family 선언은 지웁니다. 남아 있으면 두 폰트가 싸웁니다.

3. 대응표 — Stitch 임의값 → JT 클래스

z-index는 특히 주의 — Stitch·AI는 z-50, z-[9999]를 씁니다. 전부 토큰으로: z-dropdown z-overlay z-modal z-toast z-tooltip (v3), v4는 z-[var(--z-modal)].

4. 설치 — 복사해서 쓰세요

Tailwind v4

/* app/globals.css */
@import "tailwindcss";
@import "./jt-tokens.css";        /* 값의 정본 — 폰트도 여기서 함께 로드됨 */
@import "./jt-tailwind-v4.css";   /* Tailwind 이름 → JT 토큰 연결 */
@import "./jt-utilities.css";     /* 선택: jt-btn 등 컴포넌트 클래스 */
 
@source "./src";                  /* ⚠️ 빠뜨리면 프로덕션에서 스타일 소멸 */
@source "./app";

Tailwind v3

// tailwind.config.js  ← 제공된 파일을 그대로 사용

/* globals.css */
@import "./jt-tokens.css";
@tailwind base;
@tailwind components;
@tailwind utilities;

확인 (설치 후 1분)

<div class="bg-brand text-on-brand p-4 rounded-md">이 박스가 짙은 회색 + 흰 글자면 성공</div>

파란색이거나 스타일이 없으면 → ③ 버전 확인 → ④ 스캔 경로 확인 순으로 점검하세요.

5. Antigravity에 줄 프롬프트 (복사용)

프로젝트 시작할 때 한 번 붙여넣으세요.

이 프로젝트의 디자인 값 정본은 jt-tokens.css 하나다. 다음을 지켜라.

1. 색·간격·글자 크기를 새로 만들지 마라. 임의값 클래스(bg-[#...], text-[10px])
   를 쓰지 마라. jt-tailwind 브리지가 제공하는 이름 클래스만 쓴다.
   (bg-brand, text-action, text-ink, bg-surface, border-line, shadow-e1 …)
2. 주 버튼은 bg-brand(charcoal)다. 파란 주 버튼을 만들지 마라 —
   파랑은 링크·클릭 가능의 신호다.
3. z-index 숫자를 직접 쓰지 마라. z-dropdown / z-overlay / z-modal /
   z-toast / z-tooltip 만 쓴다.
4. 컨트롤에 고정 width·height를 주지 마라. min-width·min-height만 쓴다.
   한국어를 다른 언어로 옮기면 글자가 최대 7배까지 길어진다.
5. 품질 판정(적합/부적합/보류/관리한계)은 색만으로 표시하지 마라.
   반드시 글자를 함께 넣는다. 흑백 인쇄되는 시험성적서에서 색이 사라진다.
6. 대응표에 없는 값이 필요하면 만들지 말고 멈추고 물어봐라.

6. 배포 전 체크리스트

• DESIGN.md가 프로젝트 규칙 위치에 없다 (또는 “참고용” 경고문이 붙어 있다)
• 임의값 검색 \[#[0-9a-fA-F]{3,8}\] · \[\d+px\] → 0건
• z-[ 검색 → 0건
• Tailwind 버전과 브리지 파일이 짝이 맞다 (v3↔config / v4↔css)
• content 또는 @source에 모든 소스 폴더가 들어 있다
• 프로덕션 빌드를 실제로 돌려 화면을 확인했다 (개발 서버만 보면 놓칩니다)
• 다크 모드 전환 확인 — [data-theme="dark"]
• 한국어 실제 문구로 교체 후 버튼·탭 잘림 없음
• Stitch가 넣은 폰트 <link>·font-family 제거됨

부록. 이미 Tailwind로 만들어진 기존 앱

조사 결과 앱마다 자체 테마명을 씁니다(예: Bulk-Track의 text-ink·border-line·shadow-2). 공교롭게 JT 브리지와 이름이 겹치는 것도 있으니, 기존 tailwind.config.js를 지우기 전에 어떤 이름이 정의돼 있는지 먼저 확인하세요. 그대로 지우면 그 클래스들이 조용히 무효가 되어 화면이 밋밋해집니다.

순서는 jt-legacy.md를 따릅니다 — ① 조사만 ② 색·글꼴만 교체(화면 하나씩) ③ 로고 ④ (선택) 간격·크기.