design-kit — 디자인 시스템 부트스트랩 + 안티슬롭 게이트

북극성 (styleseed §C0): AI UI가 어색한 건 컴포넌트가 못생겨서가 아니라 부분들이 서로 안 맞아서다. 미학(팔레트·폰트)은 프로젝트마다 다르지만, 일관성을 만드는 방법·판단·완료 판정은 공통 → 그걸 재사용한다.

coherence-as-lint (제1 원칙): 각 디자인 축(radius·shadow·accent·spacing·icon·type·motion·border·상태색·control-height)마다 값 하나만 골라 토큰화하고 어디서나 그것만 쓴다. 섞인 축 = 스타일 선택이 아니라 lint 에러. 애매하면 새로 만들지 말고 이미 내린 결정을 복사한다.

퀄리티는 두 층이다 (둘 다 필요, 다른 작업):

• ⑴ coherence(안 깨짐) — 축 일치·위계·상태. 측정가능, 분산 제거로 고침(=이 lint). 필요조건이지 충분조건 아님 — 완벽히 일관돼도 forgettable할 수 있다.
• ⑵ aesthetic(좋음·distinctive) — 관점이 있나 vs on-distribution 기본값인가. 취향이라 눈으로 판단, 레퍼런스 기반, 여러 렌더 라운드로 수렴 = 시간이 가장 많이 드는 곳(6라운드 비주얼 검증이 정상이다). 인터뷰 한 번으로 안 끝난다 → directions.md. 밋밋함은 분산 제거로 안 고쳐진다 — 관점을 넣어야 한다.

언제 무엇을

• 디자인 시스템 없음 / 새 프로젝트 → A. 부트스트랩 (인터뷰 → 방향 → DESIGN.md+토큰 emit).
• DESIGN.md 있음 / UI 추가·수정·폴리싱 → B. 게이트 (토큰 위 빌드 → 점수제 자가비평).
• 이미 만든 UI인데 퀄이 안 잡힘 / "싸구려·제네릭·off한 느낌" → C. 진단→교정 (라이브 추출 → 점수 → 분산 제거). 세 흐름 다 아래 3개 레퍼런스를 쓴다. 작업 전 항상 프로젝트의 DESIGN.md를 다시 읽고(매 프롬프트), 충돌하면 그걸 따르거나 물어본다 — 결정이 채팅 기억이 아니라 파일에 살아야 "매번 달라 보임"이 사라진다.

레퍼런스 (필요할 때 연다)

A. 부트스트랩 — 0 → 프로덕션급 시스템

1. 인터뷰(짧게, 모르면 기본값): 제품 한 줄+도메인 · 청중+톤 형용사 23 · 좋아하는 레퍼런스 제품 12개+피하고 싶은 느낌 · 라이트/다크 · 지킬 브랜드색. → directions.md의 3질문 picker로 좁힌다.
2. 방향 제안: directions.md의 9 패밀리에서 2~3개를 근거와 함께(SAFE 2~3 + RISK 최소 2). 반수렴 테스트: 두 방향의 헤드라인을 바꿔 껴도 티가 안 나면 하나는 실패 — "세 스튜디오처럼" 달라야 한다. 한 방향만 밀지 말 것. 가능하면 히어로를 실제 렌더/생성해 비교. AVOID 방향 1개를 이유와 함께 못박으면 옳은 방향이 선명해진다.
3. emit (토큰 위에서만): templates/를 확정 방향으로 채워 DESIGN.md(9섹션 + Agent Prompt Guide: 다음 빌드가 읽을 Bias:/Reject: 줄) + 토큰 파일. 컴포넌트에 색 직접 박기 금지.
4. 검증: 대표 화면 1개 렌더 → B 게이트 ≥80 통과해야 시스템 확정.

B. 게이트 — UI 추가/수정 (빌드루프 = 완료 판정)

1. Step 0: DESIGN.md 읽기 → 같은 화면 기존 섹션 1개를 레퍼런스로 열어 복제·연장(새 비주얼 언어 도입 금지) → 색·radius·shadow는 토큰/유틸로만.
2. judgment.md의 축별 룰 위에서 빌드 → 타입체크 통과.
3. 렌더 → 스크린샷 자가비평 + gate.md로 점수화(≥80 목표, ≤3회 고쳐 재캡처, 점수이득 순으로 수정). curl/유닛만으로 완료 판정 금지. 통과 후 사용자에게 점수를 말한다.
4. /design-review가 있으면 호출(라이브 80항목 감사·Trunk Test·commit-per-fix). 없으면 3번이 게이트.
5. 새 섹션 = DESIGN.md 매크로구조 로그 한 줄 갱신.

C. 진단 → 교정 (이미 있는 UI, 퀄이 안 잡힐 때)

먼저 어느 층이 문제인지 가른다 (squint/first-impression으로): "지저분·제각각"(→coherence, 분산 제거) vs "깔끔한데 밋밋·제네릭·feel이 틀림"(→aesthetic, 재방향) vs 둘 다. 밋밋함은 분산 제거로 안 고쳐진다. 대개 coherence를 먼저 잡아 바닥을 깔고, 그래도 forgettable하면 aesthetic 재방향으로 간다.

C-1. coherence 경로 ("지저분·제각각")

1. 시스템 확보(잣대): DESIGN.md 있으면 그걸로. 없으면 라이브 렌더에서 실제 값 추출 — 폰트·색·spacing·radius·shadow가 몇 개 값으로 갈렸는지(gstack 있으면 /design-review JS 추출).
2. 점수화(고치기 전): gate.md 7범주 + 이름있는 테스트 → coherence 감점이 대개 최대 → 근거(selector/file:line)+impact×effort 점수이득 순 펀치리스트.
3. 분산 제거 순 교정: 가장 갈린 축부터 토큰 1개로(radius→1·shadow광원→1·accent→1+<5%·폰트≤2·spacing 1스케일·icon 1패밀리) → 위계 → 누락 상태. 한 축씩 재렌더·재채점, atomic commit, ≥80까지.

C-2. aesthetic 경로 ("깔끔한데 밋밋·제네릭·feel이 틀림") — 시간을 써야 하는 곳

1. 밋밋함 진단: directions.md의 anti-generic 체크로 원인을 이름댄다 — signature move 없음 / 기본폰트(Inter·system)가 정체성 / accent 정체성 없는 flat 단색 / stock·centered 히어로 / "모든 [카테고리] 사이트처럼" / RISK 0(전부 안전빵). 현 미학을 9 패밀리 중 하나로 명명하고 왜 안 사는지(밋밋 / 방향이 제품·청중과 안 맞음 / 기본값 표류) 판단.
2. 재방향(렌더-비교 루프, 머릿속 수렴 금지): directions.md로 — 레퍼런스 수집 → genuinely 다른 방향 2~3개를 실제 렌더(/design-shotgun 병렬 변형·$D 히어로 생성) → 눈으로 비교 + distinctiveness 테스트(swap-headline·"동경 브랜드 사이트에 놔도 어울리나"·embarrassment) → 관점 생길 때까지 라운드 반복(6라운드가 정상). 여기서 아끼지 말 것 — 이게 진짜 시간 드는 작업.
3. 확정 후 토큰화 + coherence 패스: 이긴 방향으로 토큰 재작성 → C-1로 일관성 마감.

공통 마무리

• 잠금: DESIGN.md 없었으면 교정된 값으로 지금 emit(templates/) → 재드리프트 방지. 있었으면 매크로구조 로그 갱신.

충돌 해소 순서 (룰이 부딪히면)

접근성 > 금지룰 > 페이지타입 직무 > 핵심 위계 > 도메인 편향 > 로컬 취향. 위가 항상 이긴다. (예: 핀테크 절제 vs 첫 입금 축하 confetti 1회 → 페이지타입 직무가 이겨 confetti 허용.)

gstack 있으면 위임, 없으면 내장으로 (독립 동작)

• 위임(있을 때): /design-review(라이브 감사) · /design-shotgun(병렬 변형 보드) · /design-html(Pretext 정밀 레이아웃) · $D 바이너리(~/.claude/skills/gstack/design/dist/design = gpt-image-2 이미지 생성 + GPT-4o vision 체크; OPENAI_API_KEY 필요).
• 내장(없을 때 폴백): 판단룰·안티슬롭 tells·점수 루브릭·이미지 브리핑 레시피는 여기 레퍼런스에 다 있어 gstack 없이도 "무엇이 좋은가"를 안다. 이미지는 $D 없으면 손으로 짠 HTML 히어로 프리뷰로 폴백.

함정 (반복 방지)

• Tailwind v4 font-size 트랩: 폰트 크기를 --text-* CSS 변수로 토큰화 금지(Tailwind 네임스페이스 충돌 → text-[var(--x)]가 색으로 파싱). 명시적 text-[Npx] + DESIGN.md의 크기 테이블이 곧 토큰.
• Tailwind JIT staleness: dev 서버가 새 토큰 유틸 못 잡으면 재시작.
• Inter/system-ui: 폴백 기본값으로 쓰면 "타이포 포기" 슬롭. 의도적 브랜드 매치면 OK(예: Linear). 기본값으로 흘러가는 것만 금지.
• UI 완료 = 눈으로 본 것. 렌더 자가비평 없이 완료 판정 금지.

한 줄: 축마다 값 하나(섞이면 lint 에러). 방법은 재사용, 미학은 함께 설계. 토큰 위에서만 짓고, 점수로 완료를 판정하고, 새로 만들지 말고 기존을 연장한다.