# [UI UX Pro Max](https://uupm.cc)

<p align="center">
  <a href="https://github.com/nextlevelbuilder/ui-ux-pro-max-skill/blob/main/README.id.md">🇮🇩 Bahasa Indonesia</a> |
  <a href="https://github.com/nextlevelbuilder/ui-ux-pro-max-skill/blob/main/README.ko.md">🇰🇷 한국어</a> |
  <a href="https://github.com/nextlevelbuilder/ui-ux-pro-max-skill/blob/main/README.vi.md">🇻🇳 Tiếng Việt</a> |
  <a href="https://github.com/nextlevelbuilder/ui-ux-pro-max-skill/blob/main/README.zh.md">🇨🇳 简体中文</a> |
  <a href="https://github.com/nextlevelbuilder/ui-ux-pro-max-skill/blob/main/README.md">🇺🇸 English</a>
</p>

<p align="center">
  <a href="https://github.com/nextlevelbuilder/ui-ux-pro-max-skill/releases"><img src="https://img.shields.io/github/v/release/nextlevelbuilder/ui-ux-pro-max-skill?style=for-the-badge&color=blue" alt="GitHub 릴리스"></a>
  <img src="https://img.shields.io/badge/reasoning_rules-192-green?style=for-the-badge" alt="추론 규칙 192개">
  <img src="https://img.shields.io/badge/UI_styles-79_searchable-purple?style=for-the-badge" alt="검색 가능한 UI 스타일 79개">
  <img src="https://img.shields.io/badge/python-3.x-yellow?style=for-the-badge&logo=python&logoColor=white" alt="Python 3.x">
  <a href="https://github.com/nextlevelbuilder/ui-ux-pro-max-skill/blob/main/LICENSE"><img src="https://img.shields.io/github/license/nextlevelbuilder/ui-ux-pro-max-skill?style=for-the-badge&color=green" alt="라이선스"></a>
</p>

<p align="center">
  <a href="https://www.npmjs.com/package/ui-ux-pro-max-cli"><img src="https://img.shields.io/npm/v/ui-ux-pro-max-cli?style=flat-square&logo=npm&label=CLI" alt="npm"></a>
  <a href="https://www.npmjs.com/package/ui-ux-pro-max-cli"><img src="https://img.shields.io/npm/dm/ui-ux-pro-max-cli?style=flat-square&label=downloads" alt="npm 다운로드 수"></a>
  <a href="https://github.com/nextlevelbuilder/ui-ux-pro-max-skill/stargazers"><img src="https://img.shields.io/github/stars/nextlevelbuilder/ui-ux-pro-max-skill?style=flat-square&logo=github" alt="GitHub 스타 수"></a>
  <a href="https://paypal.me/uiuxpromax"><img src="https://img.shields.io/badge/PayPal-Support%20Development-00457C?style=flat-square&logo=paypal&logoColor=white" alt="PayPal"></a>
</p>

여러 플랫폼과 프레임워크에서 전문적인 UI/UX를 구축할 수 있도록 디자인 인텔리전스를 제공하는 AI 스킬입니다.

<p align="center">
  <a href="https://uupm.cc">
    <img src="screenshots/website.png" alt="UI UX Pro Max" width="800">
  </a>
</p>

<p align="center">
  <b>이 프로젝트가 유용하다면 후원을 고려해 주세요:</b><br><br>
  <a href="https://paypal.me/uiuxpromax"><img src="https://img.shields.io/badge/PayPal-Donate-00457C?style=for-the-badge&logo=paypal&logoColor=white" alt="PayPal 후원"></a>
</p>

<p align="center">
  <i>다른 프로젝트</i><br>
  <a href="https://nextlevelbuilder.io">NextLevelBuilder.io</a> | <a href="https://goclaw.sh">GoClaw.sh</a> | <a href="https://claudekit.cc">ClaudeKit.cc</a> | <a href="https://tose.sh">TOSE.sh</a>
</p>

## v2.0의 새로운 기능

### 지능형 디자인 시스템 생성

v2.0의 핵심 기능은 **디자인 시스템 생성기**입니다. AI 기반 추론 엔진이 프로젝트 요구 사항을 분석하고 몇 초 만에 완전한 맞춤형 디자인 시스템을 생성합니다.

```
대상: Serenity Spa - 권장 디자인 시스템

패턴: 히어로 중심 + 사회적 증거
  전환: 신뢰 요소를 활용한 감성 중심 설계
  CTA: 첫 화면에 배치하고 후기 다음에 반복
  섹션:
    1. 히어로
    2. 서비스
    3. 고객 후기
    4. 예약
    5. 연락처

스타일: Soft UI Evolution
  키워드: 부드러운 그림자, 은은한 깊이, 편안함, 고급스러움, 유기적 형태
  추천 대상: 웰니스, 뷰티, 라이프스타일 브랜드, 프리미엄 서비스
  성능: cost:low | 접근성: risk:conditional; 요구 사항 확인 필요

색상:
  기본:   #E8B4B8 (연한 분홍색)
  보조:   #A8D5BA (세이지 그린)
  CTA:    #D4AF37 (금색)
  배경:   #FFF5F5 (따뜻한 흰색)
  텍스트: #2D3436 (차콜)
  참고: 차분한 팔레트에 금색 포인트를 더해 고급스러운 분위기 연출

타이포그래피: Cormorant Garamond / Montserrat
  분위기: 우아함, 차분함, 세련됨
  추천 대상: 명품 브랜드, 웰니스, 뷰티, 에디토리얼
  Google Fonts: https://fonts.google.com/share?selection.family=...

핵심 효과:
  부드러운 그림자 + 맥락에 맞는 전환 + 은은한 호버 상태

피해야 할 요소(안티패턴):
  밝은 네온 색상 + 과한 애니메이션 + 다크 모드 + AI 스타일 보라/분홍 그라디언트

전달 전 체크리스트:
  [ ] 이모지를 아이콘으로 사용하지 않음(SVG: Heroicons/Lucide 사용)
  [ ] 클릭 가능한 모든 요소에 cursor-pointer 적용
  [ ] 플랫폼, 컴포넌트, 사용자 환경설정에 맞는 상호작용 타이밍 적용
  [ ] 라이트 모드: 텍스트 명암비 최소 4.5:1
  [ ] 키보드 탐색 시 포커스 상태 표시
  [ ] prefers-reduced-motion 준수
  [ ] 텍스트, 칩, 배지가 잘리거나 깨지지 않고 재배치
  [ ] 반응형: 375px, 768px, 1024px, 1440px
```

### 디자인 시스템 생성 방식

```
1. 사용자 요청
   "내 뷰티 스파의 랜딩 페이지를 만들어 줘"

   ↓

2. 다중 도메인 검색(5개 병렬 검색)
   • 제품 유형 매칭(192개 분야)
   • 스타일 추천(검색 가능 79개, 활성 50개)
   • 색상 팔레트 선택(192개 팔레트)
   • 랜딩 페이지 패턴(34개 패턴)
   • 타이포그래피 조합(74개 글꼴 조합)

   ↓

3. 추론 엔진
   • 제품 → UI 분야 규칙 매칭
   • 스타일 우선순위 적용(BM25 순위)
   • 산업별 안티패턴 필터링
   • 의사결정 규칙 처리(JSON 조건)

   ↓

4. 완전한 디자인 시스템 출력
   패턴 + 스타일 + 색상 + 타이포그래피 + 효과
   + 피해야 할 안티패턴 + 전달 전 체크리스트
```

### 192개의 산업별 추론 규칙

추론 엔진에는 다음 분야에 특화된 규칙이 포함되어 있습니다.

| 분야 | 예시 |
|------|------|
| **기술 및 SaaS** | SaaS, 마이크로 SaaS, B2B 서비스, 개발자 도구/IDE, AI/챗봇 플랫폼, 사이버 보안 플랫폼 |
| **금융** | 핀테크/암호화폐, 은행, 보험, 개인 재무 추적기, 청구서 및 결제 도구 |
| **헬스케어** | 병원, 약국, 치과, 동물병원, 정신 건강, 복약 알림 |
| **전자상거래** | 일반, 명품, 마켓플레이스(P2P), 구독 상자, 음식 배달 |
| **서비스** | 뷰티/스파, 레스토랑, 호텔, 법률, 홈 서비스, 예약 및 일정 관리 |
| **크리에이티브** | 포트폴리오, 에이전시, 사진, 게임, 음악 스트리밍, 사진/동영상 편집기 |
| **라이프스타일** | 습관 추적기, 요리 및 레시피, 명상, 날씨, 일기, 기분 추적기 |
| **신기술** | Web3/NFT, 공간 컴퓨팅, 양자 컴퓨팅, 자율 드론 함대 |

각 규칙에는 다음 항목이 포함됩니다.
- **권장 패턴** - 랜딩 페이지 구조
- **스타일 우선순위** - 가장 적합한 UI 스타일
- **색상 분위기** - 산업에 적합한 색상 팔레트
- **타이포그래피 분위기** - 글꼴의 개성 조합
- **핵심 효과** - 애니메이션 및 상호작용
- **안티패턴** - 피해야 할 요소(예: 은행 서비스의 "AI 스타일 보라색/분홍색 그라디언트")

## 기능

- **검색 가능한 UI 스타일 79개(활성 50개)** - 글래스모피즘, 클레이모피즘, 미니멀리즘, 브루탈리즘, 뉴모피즘, 벤토 그리드, 다크 모드, AI 네이티브 UI 등
- **색상 팔레트 192개** - 192개 제품 유형과 1:1로 정렬된 산업별 팔레트
- **글꼴 조합 74개** - Google Fonts 가져오기 코드가 포함된 엄선된 타이포그래피 조합
- **차트 유형 25개** - 대시보드 및 분석 화면을 위한 권장 사항
- **기술 스택 22개** - React, Next.js, Astro, Vue, Nuxt.js, Nuxt UI, Svelte, SwiftUI, React Native, Flutter, HTML+Tailwind, shadcn/ui, Jetpack Compose, Angular, Laravel, Three.js, JavaFX, WPF, WinUI 3, UWP, Avalonia, Uno Platform
- **UX 가이드라인 119개** - 모범 사례, 안티패턴, 접근성 규칙, 유연한 텍스트 레이아웃, 간결한 레이블, 취소 가능한 상호작용
- **추론 규칙 192개** - 산업별 디자인 시스템 생성(v2.0의 새로운 기능)

### 유연한 텍스트와 컴팩트 UI

이 가이드는 제목, 긴 토큰, 칩, 배지, 중단된 마이크로 인터랙션에서 흔히 발생하는 실제 서비스 문제를 다룹니다.

- 제목의 균형 잡힌 줄바꿈은 점진적 향상 기능일 뿐, 특정 단어가 마지막 줄에 남는다는 보장은 아닙니다. 너비, 글꼴, 로케일에 따른 자연스러운 줄바꿈에서도 디자인이 정상적으로 작동해야 합니다.
- 필수 텍스트는 좁은 화면, 브라우저 확대, 텍스트 크기 조정, 사용자 간격 설정에서도 잘리지 않고 재배치되어야 합니다. 긴 URL과 식별자는 안전하게 줄바꿈할 수 있어야 합니다.
- 칩과 태그 모음은 줄바꿈되거나 조작 가능한 `+n` 펼치기 기능을 사용해야 합니다. 간결한 레이블은 가능한 한 온전하게 유지하고, 불가피하게 잘라야 한다면 키보드·포인터·터치 사용자가 전체 값을 확인할 수 있는 접근 가능한 경로를 제공해야 합니다.
- 배지의 의미를 색상에만 의존해서는 안 됩니다. 상호작용 가능한 칩에는 네이티브 시맨틱, 명확한 포커스, 프로그래밍 방식의 상태가 필요하며 실시간 개수에는 의미 있는 맥락이 필요합니다.
- 빠른 상호작용은 애니메이션을 취소할 수 있지만, 최종 시맨틱 상태·포커스·콘텐츠는 정확해야 합니다. 타이밍은 플랫폼과 컴포넌트에 맞게 선택하고 모션 감소 환경설정을 존중해야 합니다.

### 스타일 분류 체계

카탈로그에는 안정적인 ID와 별칭으로 뒷받침되는 **검색 가능한 스타일 79개**가 포함됩니다.

| 상태 | 개수 | 검색 동작 |
|------|-----:|-----------|
| 활성 | 50 | 일반 추천에 포함되며 갤러리에 기본 표시 |
| 보조 | 29 | 정확하거나 명시적인 변형/시스템 의도일 때 반환되며 갤러리 상태 필터에서 사용 가능 |
| 사용 중단 | 9 | 일반 순위에서 제외되며 기존 이름은 표준 스타일 또는 랜딩 패턴으로 연결 |

활성 세트는 일반 시각 스타일군 43개, 모바일 전용 스타일 2개, 공식 플랫폼/디자인 시스템 3개, 플랫폼 소재 1개, 핵심 분석 스타일 1개를 포함합니다. 현재 공식 시스템에는 Fluent 2, Shopify Polaris, Adobe Spectrum이 포함됩니다. Liquid Glass는 Apple 플랫폼 소재로 한정되고, Material 3 Expressive는 모바일 Material 변형으로 유지되며, Spectrum 2는 보조 스타일입니다. 랜딩 페이지 구조는 BM25 순위에서 시각 스타일과 경쟁하지 않고 별도의 34개 패턴 랜딩 데이터셋에 포함됩니다.

전체 분류 체계와 출처 인식 메타데이터는 [`styles.csv`](src/ui-ux-pro-max/data/styles.csv)를 참고하세요.

## 💎 기본 버전과 프리미엄 버전 비교

많은 사용자가 오픈 소스 버전과 프리미엄 버전의 차이를 묻습니다. 워크플로에 적합한 버전을 선택할 수 있도록 자세히 비교했습니다.

### 🟢 기본 버전(이 저장소)
* **완전한 오픈 소스:** 개인 개발자, 취미 개발자, 일반 프로젝트에 적합합니다.
* **핵심 UI/UX 인텔리전스:** 검색 가능한 UI 스타일 79개(활성 50개), 제품 유형 192개, 색상 팔레트, 엄선된 글꼴 조합을 모두 사용할 수 있습니다.
* **스마트 추천:** 내장 BM25 검색 엔진으로 정확도 높은 디자인 매칭을 제공합니다.
* **크로스 플랫폼 지원:** 22개 주요 프레임워크(React, Vue, Tailwind, iOS, Android 등)를 위한 스택별 가이드라인을 제공합니다.
* **디자인 시스템 생성:** CLI를 통해 맞춤형 UI 규칙, 패턴, 로직을 즉시 생성합니다.

### 🟡 프리미엄 버전
* **확장된 브랜드 디자인 스킬:** UI/UX를 넘어 브랜드 아이덴티티 생성, 로고 디자인, 기업 아이덴티티 프로그램(CIP), 배너, 프레젠테이션 슬라이드, 맞춤형 아이콘 제작을 포함합니다.
* **고급 에셋 생성:** AI 기반 이미지 생성과 긴밀하게 통합되어 플레이스홀더가 아닌 실제 시각 에셋을 만듭니다.
* **엔터프라이즈 아키텍처:** 대규모 팀 배포를 위한 더 포괄적이고 확장 가능한 디자인 토큰 아키텍처를 제공합니다.
* **우선 지원:** 중단 없는 전체 디자인 워크플로가 필요한 팀과 전문가에게 전용 기술 지원을 제공합니다.

👉 *프리미엄 등급 업그레이드에 관한 자세한 내용은 [uupm.cc](https://uupm.cc)를 참고하세요.*

## 설치

### Claude Marketplace 사용(Claude Code)

Claude Code에서 다음 두 명령어로 바로 설치할 수 있습니다.

```
/plugin marketplace add nextlevelbuilder/ui-ux-pro-max-skill
/plugin install ui-ux-pro-max@ui-ux-pro-max-skill
```

### CLI 사용(권장)

```bash
# CLI 전역 설치
npm install -g ui-ux-pro-max-cli

# 프로젝트로 이동
cd /path/to/your/project

# 사용하는 AI 어시스턴트용으로 설치
uipro init --ai claude      # Claude Code
uipro init --ai cursor      # Cursor
uipro init --ai windsurf    # Windsurf
uipro init --ai antigravity # Antigravity
uipro init --ai copilot     # GitHub Copilot
uipro init --ai kiro        # Kiro
uipro init --ai codex       # Codex CLI
uipro init --ai qoder       # Qoder
uipro init --ai roocode     # Roo Code
uipro init --ai gemini      # Gemini CLI
uipro init --ai trae        # Trae
uipro init --ai opencode    # OpenCode
uipro init --ai continue    # Continue
uipro init --ai codebuddy   # CodeBuddy
uipro init --ai droid       # Droid (Factory)
uipro init --ai kilocode    # KiloCode
uipro init --ai warp        # Warp
uipro init --ai augment     # Augment
uipro init --ai codewhale   # CodeWhale
uipro init --ai openclaw    # OpenClaw
uipro init --ai universal   # Universal / Agent Standard (.agents/skills/)
uipro init --ai all         # All assistants
```

npm 패키지명은 `ui-ux-pro-max-cli`이며, 설치되는 명령어는 `uipro`입니다. 이전 `uipro-cli` 릴리스는 오래되었으므로 현재 에셋과 함께 사용하지 마세요.

### 전역 설치(모든 프로젝트에서 사용)

```bash
uipro init --ai claude --global   # Install to ~/.claude/skills/
uipro init --ai cursor --global   # Install to ~/.cursor/skills/
uipro init --ai universal --global # Install to ~/.agents/skills/
```

### 기타 CLI 명령어

```bash
uipro versions              # List available versions
uipro update                # Refresh skill files from installed CLI package
uipro update --global       # Refresh global skill files from installed CLI package
uipro init --offline        # Compatibility flag; installs bundled templates
uipro uninstall             # Remove skill (auto-detect platform)
uipro uninstall --ai claude # Remove specific platform
uipro uninstall --global    # Remove from global install
```

## 사전 요구 사항

검색 스크립트를 실행하려면 Python 3.x가 필요합니다. 표준 라이브러리만 사용하며, 스크립트는 아무것도 설치하지 않고 네트워크 요청도 보내지 않습니다.

Python 설치 여부를 확인하세요.

```bash
python3 --version
```

설치되어 있지 않다면 [python.org](https://www.python.org/downloads/) 또는 운영체제의 패키지 관리자(Homebrew, apt, winget)를 사용해 직접 설치하세요. 이 설치 단계는 **사람인 사용자**가 수행해야 합니다. 이 스킬을 사용하는 AI 에이전트는 사용자 컴퓨터에 소프트웨어를 직접 설치하지 않고, 사용자에게 설치를 요청하도록 지시되어 있습니다.

## 사용법

### 스킬 모드(자동 활성화)

**지원:** Claude Code, Cursor, Windsurf, Antigravity, Codex CLI, Continue, Gemini CLI, OpenCode, Qoder, CodeBuddy, Droid (Factory), KiloCode, Warp, Augment, CodeWhale

UI/UX 작업을 요청하면 스킬이 자동으로 활성화됩니다. 자연스럽게 요청하세요.

```
내 SaaS 제품의 랜딩 페이지를 만들어 줘
```

> **Trae**: 먼저 **SOLO** 모드로 전환하세요. UI/UX 요청 시 스킬이 활성화됩니다.

### 워크플로 모드(슬래시 명령어)

**지원:** Kiro, GitHub Copilot, Roo Code, KiloCode

슬래시 명령어로 스킬을 실행하세요.

```
/ui-ux-pro-max 내 SaaS 제품의 랜딩 페이지를 만들어 줘
```

### 프롬프트 예시

```
내 SaaS 제품의 랜딩 페이지를 만들어 줘

헬스케어 분석 대시보드를 만들어 줘

다크 모드 포트폴리오 웹사이트를 디자인해 줘

전자상거래 모바일 앱 UI를 만들어 줘

어두운 테마의 핀테크 뱅킹 앱을 만들어 줘
```

### 작동 방식

1. **요청** - UI/UX 작업을 요청합니다(구축, 디자인, 생성, 구현, 검토, 수정, 개선).
2. **디자인 시스템 생성** - AI가 추론 엔진을 사용해 완전한 디자인 시스템을 자동으로 생성합니다.
3. **스마트 추천** - 제품 유형과 요구 사항에 따라 가장 적합한 스타일, 색상, 타이포그래피를 찾습니다.
4. **코드 생성** - 적절한 색상, 글꼴, 간격, 모범 사례를 적용해 UI를 구현합니다.
5. **전달 전 검사** - 일반적인 UI/UX 안티패턴을 기준으로 검증합니다.

### 지원 스택

이 스킬은 다음 스택별 가이드라인을 제공합니다.

| 분야 | 스택 |
|------|------|
| **웹(HTML)** | HTML + Tailwind(기본값) |
| **React 생태계** | React, Next.js, shadcn/ui |
| **Vue 생태계** | Vue, Nuxt.js, Nuxt UI |
| **Angular** | Angular |
| **PHP** | Laravel(Blade, Livewire, Inertia.js) |
| **기타 웹** | Svelte, Astro, Three.js |
| **데스크톱** | JavaFX, WPF, WinUI 3, Avalonia, Uno Platform, UWP |
| **iOS** | SwiftUI |
| **Android** | Jetpack Compose |
| **크로스 플랫폼** | React Native, Flutter |

프롬프트에서 원하는 스택을 언급하거나 기본값인 HTML + Tailwind를 사용하세요.

## 디자인 시스템 명령어(고급)

디자인 시스템 생성기에 직접 접근하려면 다음 명령어를 사용하세요.

> 참고: Continue로 설치했다면 아래 명령어의 `.claude/skills/`를 `.continue/skills/`로 바꾸세요. Droid(Factory)는 `.factory/skills/`를 사용합니다.

```bash
# ASCII 출력으로 디자인 시스템 생성
python3 .claude/skills/ui-ux-pro-max/scripts/search.py "beauty spa wellness" --design-system -p "Serenity Spa"

# Markdown 출력으로 생성
python3 .claude/skills/ui-ux-pro-max/scripts/search.py "fintech banking" --design-system -f markdown

# 도메인별 검색
python3 .claude/skills/ui-ux-pro-max/scripts/search.py "glassmorphism" --domain style
python3 .claude/skills/ui-ux-pro-max/scripts/search.py "elegant serif" --domain typography
python3 .claude/skills/ui-ux-pro-max/scripts/search.py "dashboard" --domain chart
python3 .claude/skills/ui-ux-pro-max/scripts/search.py "error summary validation" --domain ux
python3 .claude/skills/ui-ux-pro-max/scripts/search.py "decorative icon aria hidden" --domain icons
python3 .claude/skills/ui-ux-pro-max/scripts/search.py "icon button accessible label" --domain icons
python3 .claude/skills/ui-ux-pro-max/scripts/search.py "orphan heading line balance" --domain ux
python3 .claude/skills/ui-ux-pro-max/scripts/search.py "badge chip label wraps to second line" --domain ux
python3 .claude/skills/ui-ux-pro-max/scripts/search.py "rapid chip animation interrupted" --domain ux

# 스택별 가이드라인
python3 .claude/skills/ui-ux-pro-max/scripts/search.py "form validation" --stack react
python3 .claude/skills/ui-ux-pro-max/scripts/search.py "responsive layout" --stack html-tailwind
python3 .claude/skills/ui-ux-pro-max/scripts/search.py "chip badge overflow nowrap" --stack html-tailwind
python3 .claude/skills/ui-ux-pro-max/scripts/search.py "tableview binding" --stack javafx
python3 .claude/skills/ui-ux-pro-max/scripts/search.py "atlantafx primer enterprise theme" --stack javafx
python3 .claude/skills/ui-ux-pro-max/scripts/search.py "enterprise tableview density permission" --stack javafx
```

웹 스택 검색은 버전을 인식합니다. 이전 메이저 버전을 지정하지 않은 쿼리는 현재 활성 가이드라인을 반환합니다. 명시적인 레거시 용어나 이전 메이저 버전(예: `Svelte 4`, `Next.js 15`)을 지정하면 `Status`와 `Applies To`가 표시된 엄선된 레거시 행만 반환합니다. 일치하는 레거시 가이드라인이 없다면 프레임워크 세대를 섞지 않고 결과를 반환하지 않습니다.

### 디자인 시스템 저장(마스터 + 오버라이드 패턴)

세션 간 **계층적 검색**을 위해 디자인 시스템을 파일로 저장하세요.

```bash
# 디자인 시스템을 생성하여 design-system/myapp/MASTER.md에 저장
python3 .claude/skills/ui-ux-pro-max/scripts/search.py "SaaS dashboard" --design-system --persist -p "MyApp"

# 페이지별 오버라이드 파일도 생성
python3 .claude/skills/ui-ux-pro-max/scripts/search.py "SaaS dashboard" --design-system --persist -p "MyApp" --page "dashboard"
```

다음과 같은 `design-system/` 폴더 구조가 생성됩니다.

```
design-system/
└── myapp/                  # 프로젝트마다 폴더 하나(-p "MyApp"의 슬러그)
    ├── MASTER.md           # 전역 단일 정보 출처(색상, 타이포그래피, 간격, 컴포넌트)
    └── pages/
        └── dashboard.md    # 페이지별 오버라이드(마스터와 다른 내용만 기록)
```

**계층적 검색 방식:**
1. 특정 페이지(예: "결제")를 만들 때 먼저 `design-system/[project-slug]/pages/checkout.md`를 확인합니다.
2. 페이지 파일이 있으면 해당 규칙이 마스터 파일을 **재정의**합니다.
3. 없으면 `design-system/[project-slug]/MASTER.md`만 사용합니다.

**컨텍스트 인식 검색 프롬프트:**
```
[페이지 이름] 페이지를 만들고 있습니다. design-system/[project-slug]/MASTER.md를 읽어 주세요.
design-system/[project-slug]/pages/[page-name].md 파일이 있는지도 확인해 주세요.
페이지 파일이 있으면 해당 규칙을 우선 적용하세요.
없으면 마스터 규칙만 사용하세요.
이제 코드를 생성해 주세요...
```

## 아키텍처 및 기여

### 사용자 안내

코드베이스는 **템플릿 기반 생성 시스템**을 사용하도록 재구성되었습니다. 모든 플랫폼별 파일(`.cursor/`, `.windsurf/`, `.kiro/`, `.factory/` 등)은 이제 CLI에서 동적으로 생성됩니다.

**항상 CLI를 사용해 설치하세요.**

```bash
npm install -g ui-ux-pro-max-cli
uipro init --ai <platform>
```

이 방법을 사용하면 설치된 CLI 패키지에 포함된 최신 템플릿과 AI 어시스턴트에 맞는 올바른 파일 구조를 받을 수 있습니다. 새 릴리스가 배포되면 먼저 npm 패키지를 업데이트하세요.

### 기여자 안내

이 프로젝트에 기여하려면 다음 절차를 따르세요.

```bash
# 1. 저장소 복제
git clone https://github.com/nextlevelbuilder/ui-ux-pro-max-skill.git
cd ui-ux-pro-max-skill

# 2. 구조 이해
src/ui-ux-pro-max/           # 단일 정보 출처(데이터, 스크립트, 템플릿)
cli/                         # CLI 설치 도구(템플릿에서 파일 생성)
.claude/                     # Claude Code 스킬 로컬 개발/테스트
.factory/                    # Droid(Factory) 스킬 로컬 개발/테스트

# 3. src/ui-ux-pro-max/에서 변경
# - data/*.csv              → 데이터베이스 파일
# - scripts/*.py            → 검색 엔진 및 디자인 시스템
# - templates/              → 플랫폼별 템플릿

# 4. CLI에 동기화하고 로컬 테스트
cd cli
npm run sync:assets
npm run check:assets
npm run verify:data
npm run typecheck

# 5. CLI 빌드 및 테스트
# `npm run build`는 Bun이 있으면 사용하고, 없으면 `npm ci` 후 TypeScript 컴파일러 출력을 사용합니다.
npm run build
node dist/index.js init --ai claude --offline  # Test in a temp folder

# 6. PR 생성(main에 직접 푸시하지 않음)
git checkout -b feat/your-feature
git commit -m "feat: description"
git push -u origin feat/your-feature
gh pr create
```

자세한 개발 가이드라인은 [CLAUDE.md](CLAUDE.md)를 참고하세요.

### 카탈로그 출처 및 갱신

커밋된 카탈로그 요약에는 현재 **승인된 Google Fonts 1,934개**와 공식 라이선스 메타데이터가 일치하지 않아 반영되지 않은 **검토 제외 항목 8개**가 기록되어 있습니다. 아이콘 가이드는 **엄선된 105개 행**(Phosphor 웹 직접 가져오기 100개와 React Native/대체 가이드)으로 유지됩니다. 별도의 **1,512개 아이콘이 포함된 업스트림 Phosphor 매니페스트**는 검색 결과를 업스트림 패키지 전체로 채우지 않으면서 이름, 두께, React/SSR 가져오기를 검증합니다.

일반 개발 및 풀 리퀘스트 CI는 네트워크에 의존하지 않습니다. 스냅샷 해시와 생성 개수 검증을 포함한 전체 오프라인 게이트를 실행하려면 다음 명령어를 사용하세요.

```bash
npm --prefix cli run verify:data
# 또는 생성된 카탈로그 요약만 검사:
npm --prefix cli run validate:catalog-summary
```

갱신 정규화도 커밋된 픽스처를 사용해 완전히 오프라인으로 실행할 수 있습니다. 출력은 임시 후보 디렉터리에 저장되며 표준 데이터를 대체하지 않습니다.

```bash
candidate_dir="$(mktemp -d)"
python3 scripts/refresh-google-fonts.py \
  --api-input src/ui-ux-pro-max/scripts/tests/fixtures/catalogs/google-api.json \
  --metadata-input src/ui-ux-pro-max/scripts/tests/fixtures/catalogs/google-metadata.json \
  --existing-csv src/ui-ux-pro-max/scripts/tests/fixtures/catalogs/google-existing.csv \
  --overrides src/ui-ux-pro-max/scripts/tests/fixtures/catalogs/google-overrides.json \
  --output-csv "$candidate_dir/google-fonts.csv" \
  --license-output "$candidate_dir/google-font-licenses.json" \
  --metadata-revision fixture-catalogs-v1 \
  --verified-at 2026-08-13 --expected-count 2 --approve-changes
python3 scripts/refresh-icon-catalog.py \
  --input src/ui-ux-pro-max/scripts/tests/fixtures/catalogs/phosphor-core.json \
  --package-json src/ui-ux-pro-max/scripts/tests/fixtures/catalogs/phosphor-package.json \
  --react-package-json src/ui-ux-pro-max/scripts/tests/fixtures/catalogs/phosphor-react-package.json \
  --react-exports-input src/ui-ux-pro-max/scripts/tests/fixtures/catalogs/phosphor-react-exports.json \
  --curated-csv src/ui-ux-pro-max/scripts/tests/fixtures/catalogs/icons-curated.csv \
  --output "$candidate_dir/phosphor-icons-upstream.json" \
  --verified-at 2026-08-13 --expected-count 2
```

실시간 업스트림 갱신은 의도적으로 `refresh-catalogs.yml` 워크플로에 격리되어 있으며, 매주 월요일 03:17 UTC에 실행되거나 필요할 때 수동으로 실행할 수 있습니다. `GOOGLE_FONTS_API_KEY`를 GitHub Actions 시크릿으로 설정한 다음 워크플로를 실행하고 검토용 아티팩트를 다운로드하세요.

```bash
gh workflow run refresh-catalogs.yml
run_id="$(gh run list --workflow refresh-catalogs.yml --limit 1 --json databaseId --jq '.[0].databaseId')"
gh run watch "$run_id"
gh run download "$run_id" --name "catalog-refresh-review-$run_id"
```

이 워크플로는 Google Fonts Developer API와 버전이 고정된 공식 Phosphor 패키지를 읽고, 후보 파일과 통합 diff를 아티팩트에 기록하며, 저장소 읽기 전용 권한만 가집니다. 커밋, 푸시, PR 생성, 병합은 수행하지 않습니다. 후보 파일을 `src/ui-ux-pro-max/data/`에 수동으로 반영하기 전에 변경 보고서, 제외 항목, 라이선스, 관련성 지표, 오프라인 게이트를 검토하세요.


## 자동 릴리스

이 저장소는 Conventional Commits와 semantic-release를 사용해 GitHub 릴리스를 자동으로 생성합니다.

- `dev` 브랜치는 `2.6.0-beta.1`과 같은 베타 GitHub 프리릴리스를 생성합니다.
- `main` 브랜치는 `2.6.0`과 같은 공식 안정 릴리스를 생성합니다.

릴리스 노트와 `CHANGELOG.md`는 Conventional Commit 메시지에서 생성됩니다. 릴리스 준비 중 `skill.json`, `.claude-plugin/plugin.json`, `.claude-plugin/marketplace.json`, `cli/package.json`, `cli/package-lock.json`의 버전 번호가 동기화됩니다.

올바른 버전 증가를 위해 다음 커밋 유형을 사용하세요.

- `fix:` -> 패치 릴리스
- `feat:` -> 마이너 릴리스
- `feat!:` 또는 `BREAKING CHANGE:` -> 메이저 릴리스

릴리스 워크플로는 GitHub 릴리스에 기본 `GITHUB_TOKEN`을 사용하고, `ui-ux-pro-max-cli`를 npm에 배포할 때 저장소의 `NPM_TOKEN` 시크릿을 사용합니다.

## 문제 해결

### `uipro: unknown command 'uninstall'` 또는 `unknown command 'update'`

설치된 `ui-ux-pro-max-cli` 버전이 오래되었습니다. 업데이트한 후 다시 시도하세요.

```bash
npm install -g ui-ux-pro-max-cli@latest
uipro uninstall
```

### `uipro uninstall` 실행 시 "No installed AI skill directories detected"가 표시되는 경우

명령어를 실행한 디렉터리가 스킬을 설치한 디렉터리와 다릅니다. 다음 중 하나를 수행하세요.

```bash
# 방법 A — 처음 설치한 프로젝트 루트에서 실행
cd /path/to/your/project
uipro uninstall

# 방법 B — 전역 설치 제거
uipro uninstall --global

# 방법 C — 수동 제거
rm -rf .claude/skills/ui-ux-pro-max   # Claude Code
rm -rf .cursor/skills/ui-ux-pro-max   # Cursor
rm -rf .windsurf/skills/ui-ux-pro-max # Windsurf
rm -rf .agents/skills/ui-ux-pro-max   # Antigravity / Codex
```

### Claude.ai의 "Upload a skill" 대화상자에서 "Zip contains too many files (maximum 200)"가 표시되는 경우

GitHub 저장소 전체 ZIP을 업로드하지 마세요. 이 ZIP은 소스 코드, CLI 에셋, 문서, 미리보기, 여러 번들 스킬을 포함한 개발용 체크아웃이므로 Claude의 파일 200개 업로드 제한을 초과합니다. Claude 스킬 업로드용 아티팩트가 아니며, 이 프로젝트는 현재 Claude.ai 수동 업로드용 ZIP을 별도로 배포하지 않습니다.

Claude Code에서는 Marketplace를 통해 설치하세요.

```bash
/plugin marketplace add nextlevelbuilder/ui-ux-pro-max-skill
/plugin install ui-ux-pro-max@ui-ux-pro-max-skill
```

또는 CLI 설치 도구를 사용하세요.

```bash
npx ui-ux-pro-max-cli init --ai claude
```

### Claude Marketplace 설치가 "Zip file contains a symbolic link" 오류로 실패하는 경우

v2.5.1 이전 버전에서 알려진 문제입니다. 저장소 내부에서 일부 설치 도구가 처리할 수 없는 심볼릭 링크를 사용했습니다. **해결 방법:** CLI 설치 도구를 사용하세요.

```bash
npm install -g ui-ux-pro-max-cli
uipro init --ai claude
```

또는 이 문제가 해결된 다음 릴리스를 기다리세요.

### `npm install -g ui-ux-pro-max-cli` 명령이 권한 오류로 실패하는 경우

Node 버전 관리자를 사용하거나(권장) 전역 설치를 생략하세요.

```bash
# 전역 설치 없이 npx 사용
npx ui-ux-pro-max-cli init --ai claude
```

### 디자인 시스템 명령어 실행 시 Python을 찾을 수 없는 경우

검색 스크립트에는 Python 3.x가 필요합니다. [python.org](https://www.python.org/downloads/) 또는 운영체제의 패키지 관리자(Homebrew, apt, winget)를 사용해 직접 설치하세요. AI 에이전트는 대신 설치하지 않으며 사용자에게 설치를 요청하도록 지시되어 있습니다.

### 디자인 시스템 출력 또는 필드가 잘리는 경우

사람이 읽기 쉬운 출력에서는 긴 필드가 300자로 잘립니다. 잘리지 않은 전체 데이터를 받으려면 `--json`을 사용하세요.

```bash
python3 .claude/skills/ui-ux-pro-max/scripts/search.py "SaaS" --domain style --json
```

---

## 스타 기록

[![스타 기록 차트](https://star-history.dera.page/svg?repos=nextlevelbuilder/ui-ux-pro-max-skill&type=Date)](https://star-history.dera.page/#nextlevelbuilder/ui-ux-pro-max-skill&Date)

## 라이선스

이 프로젝트는 [MIT 라이선스](LICENSE)에 따라 배포됩니다.

## 호환 에이전트

이 스킬은 다음 에이전트에서 사용할 수 있습니다.
- [Claude Code](https://claude.com/product/claude-code)
- [AdaL](https://sylph.ai/) - 스스로 진화하는 AI 코딩 에이전트([문서](https://docs.sylph.ai/) | [GitHub](https://github.com/SylphAI-Inc/adal-cli))