Communitygithub.com

UX.md 생성기 및 구조 감사 도구 (v1)

UX.md v1 구조적 UI/UX 명세를 생성, 추출, 감사, 미리보기, 비교(diff) 및 검증합니다. DESIGN.md 및 AGENTS.md의 구조적 동반자로서 애플리케이션의 골격을 정의합니다. 프론트엔드/UI 프로젝트 초기화, 참조 제품에서 UX 패턴 추출, 기존 코드베이스의 레이아웃 드리프트 감사, 새로운 라우트/뷰 추가 시 사용합니다.

UX.md 생성기 및 구조 감사 도구 (v1)란 무엇인가요?

이 스킬은 UI/UX의 시각적 토큰(Color, Typography, Radius 등)을 다루는 `DESIGN.md`와 달리, 애플리케이션의 구조적 골격과 상호작용 규칙을 명세하는 `UX.md`를 생성하고 관리하는 포괄적인 도구입니다. 주요 기능으로는 프로젝트 초기화 시 12개 섹션의 `UX.md`를 자동 생성하는 'Synthesize', 기존 제품(Linear, Stripe Dashboard 등)의 UX 패턴을 추출하는 'Extract from reference', 그리고 소스 코드 경로를 스캔하여 기존 `UX.md` 명세와의 차이를 발견하는 'Audit' 모드가 있습니다. 6개의 제로-의존성 Node.js 스크립트(`extract-ux.mjs`, `generate-ux.mjs` 등)로 구성된 3단계 파이프라인을 통해 동작하며, 최종적으로 `validate-ux.mjs`로 16가지 규칙을 검증하여 일관성 없는 레이아웃, 누락된 상태(Empty/Error), 잘못된 z-index 등을 방지합니다. Claude Code, Cursor, Codex 등 모든 AI 코딩 에이전트와 함께 사용할 수 있도록 설계되었습니다.

지원 대상~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/SolidStateNetwork/ux.md/tree/main/skills/ux-md-generator

즐겨 사용하는 AI에게 물어보기

이 에이전트 스킬이 미리 로드된 새 채팅을 엽니다.

문서

UX.md 생성기 및 구조 감사 도구 (v1)은(는) 무엇을 하나요?

개요

DESIGN.md가 색상, 타이포그래피, 반경, 그림자, 스페이싱 스케일과 같은 시각적 토큰을 지정하는 반면, UX.md는 애플리케이션의 구조적 골격과 상호작용 규칙을 지정합니다.

UX.md 없이 AI 코딩 에이전트는 세션 간에 일관성을 잃습니다: 컨테이너 너비가 혼용되고, 주요 CTA가 이동하며, 모달과 드로어 사이에서 임의로 전환되고, 빈 상태나 오류 상태가 누락되며, F5 새로고침 시 필터 상태가 손실되고, 링크가 끊긴 라우트가 발생합니다.

이 스킬은 scripts/ 디렉토리에 있는 6개의 제로-의존성 Node.js 스크립트가 지원하는 3단계 파이프라인을 통해 네 가지 모드로 작동합니다.


번들 CLI 스크립트

스크립트목적사용 예시
scripts/extract-ux.mjspackage.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.mjs16가지 결정론적 구조 규칙 및 --check-code 린터 규칙(라우트 패리티, 프리미티브, 데드 핸들러, rogue z-index) 실행node .agents/skills/ux-md-generator/scripts/validate-ux.mjs UX.md --strict --check-code
scripts/scaffold-ux.mjsUX.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

작동 모드

  1. 합성 (Synthesize / init): extract-ux.mjs + generate-ux.mjs를 실행하여 프로젝트 컨텍스트와 DESIGN.md에서 초기 UX.md를 스캐폴딩한 후, 라우트, 아키타입 및 도메인 규칙을 사용자 정의합니다.
  2. 참조에서 추출 (Extract from reference): 명명된 참조 제품(예: Linear, ChatGPT Canvas, Stripe Dashboard, Shopify, Supabase)에서 공간 셸, 상호작용 규칙, 키보드 단축키 및 페이지 아키타입을 추출합니다.
  3. 감사 및 리버스 엔지니어링 (Audit / existing codebase): extract-ux.mjs를 실행하여 기존 라우트(src/app/**, src/pages/**, src/routes/**)를 발견하고, 구조적 드리프트를 감지하며, 통합된 UX.md를 생성합니다.
  4. 진화 (Evolve / feature addition): 새 페이지나 워크플로우가 추가될 때마다 섹션 3(Page Archetypes)과 섹션 4(Navigation, Route Graph & URL Persistence)를 업데이트하고 validate-ux.mjs UX.md --check-code로 패리티를 확인합니다.

3단계 생성 파이프라인

1단계: 결정론적 추출 및 아키타입 분류

  1. node .agents/skills/ux-md-generator/scripts/extract-ux.mjs .를 실행하거나 (또는 package.json, AGENTS.md, DESIGN.md를 직접 검사하여) 대상 런타임, 인증 경계, 기존 라우트 및 DESIGN.md 중단점을 감지합니다.
  2. resources/archetype-taxonomy.md를 로드하고 다음을 확인합니다:
    • platform_profile: web-app | mobile-native | desktop-app | terminal-tui
    • archetype: b2b-saas-workspace | ai-chat-canvas | analytics-dashboard | ecommerce-storefront | developer-tool
  3. 선택적으로 다음 명령어로 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 (Mermaid flowchart 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단계: 교차 감사 및 기계 검증

  1. 생성된 UX.md를 resources/quality-checklist.md ([UX-01] ~ [UX-16])에 대해 감사합니다.
  2. 자동화된 린터 스크립트를 실행합니다:
    node .agents/skills/ux-md-generator/scripts/validate-ux.mjs UX.md --strict --check-code
    
  3. 보고된 모든 error 또는 warning 사항을 해결하고 검증기가 0 errors로 종료될 때까지 다시 실행합니다.

관련 스킬