08-ui-first UI 자산 우선 원칙

핵심 원칙

핵심 원칙

프론트엔드 페이지/컴포넌트 구현 시작 전, 반드시 프로젝트에 존재하는 HTML 목업 파일을 먼저 탐색하고 확인한다.

INTENT.md context.docs에 명시되지 않아도 능동적으로 탐색한다. 확인 없이 UI 구현을 시작하면 → auto-fail (목업과 다른 UI를 처음부터 다시 구현해야 하는 상황 방지)

---

HTML 목업 탐색 절차 (필수)

프론트엔드 작업 시작 전 아래 명령을 실행한다:

복사find {project_root} -name "*.html" \
  -not -path "*/node_modules/*" \
  -not -path "*/.git/*" \
  -not -path "*/dist/*" \
  -not -path "*/build/*" \
  -not -name "index.html"

• index.html 제외 이유: Vite/CRA entry 파일은 목업이 아님
• 발견된 HTML 파일 수 + 경로를 사용자에게 보고
• 목업 HTML이 있으면 → 반드시 읽고 디자인 토큰 추출 후 구현 시작

---

목업 HTML에서 추출할 것

항목	확인 내용
색상 팔레트	CSS 변수, Tailwind 클래스, 하드코딩 색상값
레이아웃 구조	사이드바/헤더/컨텐츠 영역 배치
타이포그래피	폰트 패밀리, 크기, 굵기
컴포넌트 패턴	카드, 테이블, 폼, 버튼 스타일
인터랙션 힌트	hover, active, disabled 상태

추출한 토큰은 두 형식으로 병행 기록한다:

• docs/design/DESIGN_TOKENS.md — 사람이 읽는 마크다운 문서
• docs/design/design-tokens.json — AI가 재활용하는 구조화 데이터 (Google A2UI 패턴)

design-tokens.json 최소 구조:

복사{
  "colors": { "primary": "#...", "background": "#..." },
  "typography": { "fontFamily": "...", "baseSize": "16px" },
  "spacing": { "unit": "4px" },
  "components": { "button": { "borderRadius": "..." } }
}

---

목업이 없을 때

HTML 목업 파일이 0개인 경우:

• 09-design 섹션 4 절차 실행 — 디자인 시스템 확인 → 없으면 레퍼런스 제안 → 토큰 생성
• 토큰 생성/확인 없이 임의 디자인 결정 금지
• 09-design의 Hard Ban 패턴은 목업 유무와 무관하게 항상 적용

---

적용 범위

• 신규 페이지 컴포넌트 구현 시
• 기존 페이지 대규모 UI 변경 시
• 새 프로젝트 프론트엔드 초기 세팅 시

단순 버그 수정(레이아웃 깨짐, 색상 오류 등) → 탐색 생략 가능