컴포넌트 계약 — 앱이 지켜야 할 4가지 약속

겁먹을 이름이지만 내용은 간단합니다. “부품을 뜯어고치지 말고, 부품에 달린 조절 손잡이만 돌려라” — 이 한 문장이 전부입니다.

왜 있나요

앞으로 더 복잡한 앱이 개발됩니다. 복잡한 앱은 반드시 “이 시스템으로는 안 되는 것”을 만나고, 그때 시스템 파일을 복사해서 고칩니다. 한 번 그러면 통일은 끝납니다. 계약은 그 순간에 복사 대신 쓸 수 있는 정식 통로입니다.

4가지 약속

#	약속	쉬운 말	어기면 이렇게 됩니다
1	컴포넌트는 Alias 토큰만 참조한다	`--blue-500` 같은 원시 색을 부품에 직접 쓰지 않습니다	다크 모드로 바꿨을 때 그 부품만 색이 안 뒤집힙니다
2	`jt-utilities.css`를 수정하지 않는다. 대신 `--jt-{부품}-*` 손잡이를 덮어쓴다	시스템 파일은 통째로 갈아 끼울 수 있어야 합니다	v5.1을 받는 순간 고쳐 둔 것이 전부 사라집니다
3	z-index에 숫자를 쓰지 않는다 — `--z-*` 토큰만	무엇이 위에 뜨는지는 시스템이 정합니다	모달 위에 툴팁이 안 뜨거나, 드롭다운이 헤더 뒤로 숨습니다
4	토큰을 먼저 추가하고 부품을 쓴다 (역순 금지)	없는 값이 필요하면 먼저 물어보세요	앱마다 다른 회색이 생기고, 나중에 한꺼번에 못 바꿉니다

실제 사용 예 — “이 앱만 버튼을 크게”

/* ✅ 올바름 — 손잡이만 덮어쓰기 */
.checkout-page .jt-btn{ --jt-btn-min-w:120px; --jt-btn-bg:var(--color-accent); }
 
/* 🚫 금지 — 시스템 파일 수정 */
/* jt-utilities.css 를 열어서 .jt-btn 을 고치는 것 */

⚠️

AI에게 시킬 때는 이렇게 말하세요 — “jt-utilities.css는 수정하지 마. 모양을 바꿔야 하면 --jt-* 값만 덮어써.” 이 한 줄이 계약 2조를 지켜줍니다. → 프롬프트 지갑 · 규칙 심기

주요 손잡이 (노브)

--jt-btn-*(bg / fg / border / hover / active / min-w) · --jt-badge-h · --jt-check-size · --jt-topbar-h · --jt-tabbar-h · --jt-grid-min · --jt-toast-max · --jt-tooltip-max

전체 목록은 각 컴포넌트 페이지 하단에 있습니다.

용어

사이트 용어	쉬운 말
토큰	회사가 정한 색·크기·간격의 값 이름표. #305CDE 대신 --color-link 라고 부르는 것.
컴포넌트	미리 만들어 둔 부품. 버튼, 입력칸, 표, 배지 같은 것.
노브	부품에 달린 조절 손잡이(--jt-* 값). 부품을 뜯어고치지 말고 이것만 돌립니다.
컴포넌트 계약	부품을 쓸 때 앱이 지켜야 할 4가지 약속. 이것만 지키면 버전이 올라가도 안 깨집니다.

개발 패턴이란