UX.md 생성기 및 구조 감사 도구 (v1)은(는) 무엇을 하나요?
개요
DESIGN.md가 색상, 타이포그래피, 반경, 그림자, 스페이싱 스케일과 같은 시각적 토큰을 지정하는 반면, UX.md는 애플리케이션의 구조적 골격과 상호작용 규칙을 지정합니다.
UX.md 없이 AI 코딩 에이전트는 세션 간에 일관성을 잃습니다: 컨테이너 너비가 혼용되고, 주요 CTA가 이동하며, 모달과 드로어 사이에서 임의로 전환되고, 빈 상태나 오류 상태가 누락되며, F5 새로고침 시 필터 상태가 손실되고, 링크가 끊긴 라우트가 발생합니다.
이 스킬은 scripts/ 디렉토리에 있는 6개의 제로-의존성 Node.js 스크립트가 지원하는 3단계 파이프라인을 통해 네 가지 모드로 작동합니다.
번들 CLI 스크립트
| 스크립트 | 목적 | 사용 예시 |
|---|---|---|
scripts/extract-ux.mjs | package.json, AGENTS.md, DESIGN.md 및 소스 라우트(src/app, src/pages)를 스캔하여 구조화된 JSON 생성 | node .agents/skills/ux-md-generator/scripts/extract-ux.mjs . --output ux-scan.json |
scripts/generate-ux.mjs | 아키타입, 제품 프리셋(--preset linear) 또는 ux-scan.json에서 12개 섹션의 UX.md 스캐폴딩 | node .agents/skills/ux-md-generator/scripts/generate-ux.mjs --preset linear --project "Acme" --output UX.md |
scripts/validate-ux.mjs | 16가지 결정론적 구조 규칙 및 --check-code 린터 규칙(라우트 패리티, 프리미티브, 데드 핸들러, rogue z-index) 실행 | node .agents/skills/ux-md-generator/scripts/validate-ux.mjs UX.md --strict --check-code |
scripts/scaffold-ux.mjs | UX.md에서 ux-contract.css 사용자 정의 속성 및 React/TypeScript 레이아웃 프리미티브(AppShell.tsx, PageHeader.tsx, PageSection.tsx, DataStateBoundary.tsx) 생성 | node .agents/skills/ux-md-generator/scripts/scaffold-ux.mjs UX.md --out-dir src/components/ux |
scripts/preview-ux.mjs | 독립적이고 반응형인 ux-preview.html 대화형 와이어프레임 시뮬레이터 생성 | node .agents/skills/ux-md-generator/scripts/preview-ux.mjs UX.md --output ux-preview.html |
scripts/diff-ux.mjs | 두 UX.md 파일을 비교하여 라우트, 아키타입, 예산 또는 임계값 회귀 탐지 | node .agents/skills/ux-md-generator/scripts/diff-ux.mjs UX.old.md UX.md --json |
작동 모드
- 합성 (Synthesize /
init):extract-ux.mjs+generate-ux.mjs를 실행하여 프로젝트 컨텍스트와DESIGN.md에서 초기UX.md를 스캐폴딩한 후, 라우트, 아키타입 및 도메인 규칙을 사용자 정의합니다. - 참조에서 추출 (Extract from reference): 명명된 참조 제품(예: Linear, ChatGPT Canvas, Stripe Dashboard, Shopify, Supabase)에서 공간 셸, 상호작용 규칙, 키보드 단축키 및 페이지 아키타입을 추출합니다.
- 감사 및 리버스 엔지니어링 (Audit / existing codebase):
extract-ux.mjs를 실행하여 기존 라우트(src/app/**,src/pages/**,src/routes/**)를 발견하고, 구조적 드리프트를 감지하며, 통합된UX.md를 생성합니다. - 진화 (Evolve / feature addition):
새 페이지나 워크플로우가 추가될 때마다 섹션 3(Page Archetypes)과 섹션 4(Navigation, Route Graph & URL Persistence)를 업데이트하고
validate-ux.mjs UX.md --check-code로 패리티를 확인합니다.
3단계 생성 파이프라인
1단계: 결정론적 추출 및 아키타입 분류
node .agents/skills/ux-md-generator/scripts/extract-ux.mjs .를 실행하거나 (또는package.json,AGENTS.md,DESIGN.md를 직접 검사하여) 대상 런타임, 인증 경계, 기존 라우트 및DESIGN.md중단점을 감지합니다.- resources/archetype-taxonomy.md를 로드하고 다음을 확인합니다:
platform_profile:web-app|mobile-native|desktop-app|terminal-tuiarchetype:b2b-saas-workspace|ai-chat-canvas|analytics-dashboard|ecommerce-storefront|developer-tool
- 선택적으로 다음 명령어로
UX.md를 시드(seed)합니다:node .agents/skills/ux-md-generator/scripts/generate-ux.mjs --archetype <archetype> --project "<Project Name>" --output UX.md
2단계: 도메인별 12개 섹션 합성
resources/ux-md-format.md, resources/layout-primitives.md 및 resources/writing-style-guide.md를 로드합니다. 저장소 루트에 있는 UX.md를 다음 내용으로 맞춤설정합니다:
- YAML 머리말 (Frontmatter): 완전한 구성 (
spec_version: "1.0",shell_budget,z_index_scale,thresholds,layout_primitives). - 섹션
0부터11까지 순서대로:## 0. Product & Domain Topology## 1. Spatial Architecture & App Shell(ASCII 와이어프레임 및 뷰포트 예산 표)## 2. Scroll, Viewport & Z-Index Contract## 3. Core Page Archetypes (Blueprints)(### Archetype: <ArchetypeID>제목 사용)## 4. Navigation, Route Graph & URL Persistence(Mermaidflowchart LR, 라우트 도달성 표 및 상태 지속성 매트릭스)## 5. Overlay & Feedback Decision Matrix(필드 수 및px임계값)## 6. Mandatory View States (4-State Matrix)(Loading,Empty,Error,Populated)## 7. Mutation, Form & Permission Ergonomics(isDirty가드, 2계층 파괴 규칙, 3방향 권한 게이트)## 8. Real-Data Stress, Density & Truncation(단일 리스트 스케일링 모드,min-w-0 truncate,-빈 셀 플레이스홀더 토큰,tabular-nums)## 9. Responsive Reflow & Input Choreography(축소 순서,>= 44x44px터치 대상 및>= 8px간격, 호버 상호작용에 대한 탭 대안, safe-area 스크롤 패딩)## 10. Mandatory Layout Primitives (Code Contract)(<AppShell>,<PageHeader>,<PageSection>,<DataStateBoundary>)## 11. Project Do's, Don'ts & Agent Prompt Guide
작성 제약 조건:
- 모호한 형용사 사용 금지: 명확한 숫자 없이 "작은 폼", "깔끔한 레이아웃", "느린 요청", "직관적인 내비게이션" 과 같은 표현을 사용하지 마십시오 (대신
<= 4 fields,1280px,>= 150ms사용). resources/anti-patterns.md를 참조하십시오. - 데드 엔드 금지: 섹션 4의 모든 라우트는 섹션 3의 유효한
<ArchetypeID>를 참조하고Entry Trigger와Exit / Cancel Fallback을 모두 정의해야 합니다. - 레이아웃 프리미티브 적용: 모든 라우트가 섹션 10에 정의된 4가지 필수 레이아웃 프리미티브(
<AppShell>,<PageHeader>,<PageSection>,<DataStateBoundary>)를 구성하도록 보장합니다.
3단계: 교차 감사 및 기계 검증
- 생성된
UX.md를 resources/quality-checklist.md ([UX-01]~[UX-16])에 대해 감사합니다. - 자동화된 린터 스크립트를 실행합니다:
node .agents/skills/ux-md-generator/scripts/validate-ux.mjs UX.md --strict --check-code - 보고된 모든
error또는warning사항을 해결하고 검증기가0 errors로 종료될 때까지 다시 실행합니다.