UI Master: AI 같지 않은 인터페이스 만들기은(는) 무엇을 하나요?

경로 규칙: 이 파일은 저장소의 ui/ 디렉토리에 있으며, catalog/ 및 prompts/는 같은 레벨에 위치하여 Skill과 함께 이동합니다.

전체 저장소에서 (또는 setup.sh --link-skills로 심볼릭 링크 설치한 경우): 먼저 realpath로 저장소 루트를 찾은 후, python3 <저장소 루트>/scripts/find.py <키워드>로 모든 모듈을 검색할 수 있습니다.

단독 설치 시 (npx skills add Horace-Maxwell/ai-master-prompt, ui/ 폴더만 있는 경우): 검색 스크립트가 없으므로 catalog/*.md를 직접 grep 합니다. 스캐폴딩, Skills, 도구 등 다른 모듈은 https://github.com/Horace-Maxwell/ai-master-prompt를 참조하세요.

AI가 만든 UI가 어색한 이유는 보통 능력 부족이 아니라, ① 기성 컴포넌트 라이브러리를 제대로 활용하지 못하고, ② 원하는 효과의 이름을 정확히 말하지 못하기 때문입니다. 이 Skill은 이 두 가지 문제를 해결합니다.

작업 흐름

1. 먼저 네 가지를 파악하세요

플랫폼 및 기술 스택: Web (React/Next? Vue? 순수 HTML?) 또는 React Native/Expo? 기존 프로젝트인가요, 신규인가요?
페이지 유형: 랜딩 페이지 / 대시보드 / SaaS 애플리케이션 / AI 채팅 제품 / 모바일 앱 / 포트폴리오…
스타일: 사용자가 특정 스타일이나 참고 사이트를 지정했나요?
애니메이션 강도: 절제됨 / 적당함 / 화려함

언제 질문하고 언제 바로 할까: 플랫폼과 페이지 유형이 명확하지 않을 때만 질문합니다 (최대 한 번). 나머지는 기본값을 사용하고 응답에 선택한 내용을 명시하세요:

언급되지 않은 항목	기본값
기술 스택	기존 프로젝트는 해당 프로젝트를 따름; 신규 Web은 Next.js + Tailwind + shadcn/ui
스타일	사용자에게 2~3가지 방향 제시 (prompts/style-recipes.md 참고); 사용자가 '알아서 해줘'라고 하면 페이지 유형에 가장 적합한 것을 선택
애니메이션 강도	제품 UI는 절제됨; 랜딩 페이지는 적당함; 포트폴리오/이벤트 페이지는 화려함 가능

사용자가 효과를 정확히 설명하지 못할 때는 prompts/effect-vocabulary.md에 있는 이름을 사용하여 확인하세요 ("혹시 Text Scramble처럼 글자가 흩어졌다가 정확한 텍스트로 고정되는 효과를 말씀하시는 건가요?").

2. 결정표에 따라 베이스 선택

사용자가 스타일을 지정한 경우, 스타일 행을 우선합니다: 손그림 스타일 랜딩 페이지는 손그림 라이브러리를 사용하고, Aceternity 같은 어두운 화려함 컴포넌트를 추가로 쌓지 마세요.

상황	베이스	추가할 것
React/Next 신규 프로젝트 (기본)	`npx create-next-app@latest`, 그 다음 `npx shadcn@latest init`	필요에 따라 네임스페이스 레지스트리에서 컴포넌트 추가
스타일 적용 (손그림/레트로/브루탈리즘/글라스/터미널)	해당 스타일 라이브러리 (style-recipes 참고)	대부분 shadcn 레지스트리이므로 설치 후 동일 이름 컴포넌트를 바로 교체 가능
랜딩 페이지 / Hero / 마케팅 페이지 (스타일 미지정)	shadcn + Magic UI / Aceternity / React Bits	부드러운 스크롤 Lenis; 스크롤 애니메이션 GSAP ScrollTrigger 또는 Motion
대시보드 / 백오피스	shadcn + Tremor 또는 shadcn charts	Kibo UI로 고급 컴포넌트 보강
AI 채팅 / Agent 제품	shadcn + AI Elements 또는 assistant-ui	affectUI로 Agent 가시성 패널; 데이터는 Langfuse / Phoenix에서 가져옴; Python 백엔드는 AG-UI 프로토콜로 프론트엔드와 연결
React Native / Expo	`npx create-expo-app@latest` + React Native Reusables 또는 ExpoKit	리퀴드 글라스는 `expo-glass-effect`, 모서리 블러는 `expo-blur`; beUI로 애니메이션
Vue / Nuxt	Nuxt UI 또는 shadcn-vue	Inspira UI로 특수 효과; goopUI (리퀴드 효과, pre-alpha)
순수 HTML / 프레임워크 없음	daisyUI 또는 Tailwind + 네이티브 CSS	Animate.css, Hover.css, GSAP

전체 후보 목록:

컴포넌트 라이브러리: catalog/02 기본, 03 애니메이션, 04 스타일, 05 모바일, 06 특수효과/3D, 07 AI 제품
찾을 수 없을 때는 종합 사이트로: catalog/01 (21st.dev, shadcn 공식 디렉토리, registry.directory)

3. 컴포넌트 설치: shadcn 네임스페이스 사용법

공식 인덱스에 등록된 네임스페이스 (548개)는 별도 설정 없이 사용 가능합니다:

npx shadcn@latest add @magicui/marquee
npx shadcn@latest add @aceternity/spotlight
npx shadcn@latest search @aceternity --query "card"     # 항목 이름을 모를 때: 먼저 검색
npx shadcn@latest list @magicui                    # 또는 해당 네임스페이스의 모든 항목 나열
npx shadcn@latest view @magicui/border-beam        # 설치 전 코드 확인

세 가지 흔한 함정:

항목 이름을 추측하지 마세요. 카탈로그의 <item>은 자리 표시자이며, 각 라이브러리의 이름이 다릅니다. 먼저 search 또는 list를 사용하세요.
React Bits의 항목 이름에는 변형 접미사가 붙습니다: <컴포넌트명>-<TS|JS>-<TW|CSS>, 예: npx shadcn@latest add @react-bits/DecryptedText-TS-TW. 접미사 없이 사용하면 404 오류가 발생합니다.
공식 인덱스에 없는 라이브러리 (Looseleaf, Rare UI 등)는 두 가지 방법으로 설치할 수 있습니다:
- 전체 URL 또는 GitHub 경로를 직접 제공, 설정 불필요: npx shadcn@latest add https://kevintngo.github.io/looseleaf/r/button.json, npx shadcn@latest add swamimalode07/rare-ui/fluid-orb
- 또는 components.json에 한 번 등록하면 이후 @looseleaf/button처럼 사용 가능:
```
{ "registries": { "@looseleaf": "https://kevintngo.github.io/looseleaf/r/{name}.json" } }
```

자주 사용하는 네임스페이스 빠른 검색 (모두 공식 인덱스 내): @magicui @aceternity @react-bits @animate-ui @motion-primitives @cult-ui @kokonutui @coss @shadcnblocks @tailark @kibo-ui @8bitcn @neobrutalism @retroui @glasscn @glassyui @ai-elements @assistant-ui @prompt-kit @affectui @beui @shaderscn @threecn @lucide-animated @svgl

4. Agent에 도구 설치 (사용자 동의 후)

최소 조합 (Claude Code 기준; 다른 Agent는 -- 뒤의 동일한 npx … 명령을 자신의 MCP 설정에 작성하세요. 대조표는 저장소 루트의 AGENTS.md 참고):

npx shadcn@latest mcp init --client claude                    # 수백 개 레지스트리 컴포넌트 탐색/설치 (--client cursor / vscode도 지원)
claude mcp add context7 -- npx -y @upstash/context7-mcp        # 모든 라이브러리의 최신 문서
npx skills add anthropics/skills --skill frontend-design       # 미적 기준선, AI 느낌 제거

필요에 따라 추가: Magic UI MCP, 21st MCP, Figma MCP (디자인 시안이 있을 때), Motion AI Kit (npx motion-ai), GSAP skills, 참고 스크린샷을 찾는 Mobbin / Refero / Lazyweb MCP (모두 계정 필요). 전체 목록은 catalog/12 참고.

5. 디자인 시스템을 먼저 정한 후 페이지 작성

스타일 토큰 설정: 색상 (Realtime Colors / tweakcn으로 생성), 폰트 (기본 Inter 사용 금지: Fontshare, Google Fonts에서 개성 있는 한 쌍 선택), 모서리 둥글기, 그림자, 간격. 사용자가 참고 브랜드를 제공했다면 awesome-design-md에서 해당 DESIGN.md를 찾아 프로젝트 루트에 넣으세요.
페이지 구조: 영감 사이트 (catalog/10)에서 유사한 페이지의 블록 순서를 참고하세요.
컴포넌트 우선 재사용: npx shadcn@latest add로 설치할 수 있으면 직접 작성하지 마세요.
목적 있는 애니메이션: 진입 시 한 번, 호버 피드백, 스크롤 내러티브. prefers-reduced-motion을 존중하세요.

6. 자체 점검 (건너뛰지 마세요)

브라우저 (Playwright / Chrome DevTools MCP / 내장 브라우저)로 페이지를 열고 스크린샷을 찍어 아래 'AI 느낌' 체크리스트와 비교하세요.
모바일 너비 (375px)에서 한 번 확인하세요.
콘솔에 오류가 없고, 애니메이션이 끊기지 않는지 확인하세요 (transform/opacity만 애니메이션).

흔한 AI 느낌 (피해야 할 것): 보라-파랑 그라데이션 + Inter + 가운데 정렬 큰 제목의 삼종세트; 모든 카드가 동일한 모서리 둥글기와 그림자; 이모지를 아이콘으로 사용; 화면 가득 glassmorphism; 계층이 없는 회색 텍스트; 모든 섹션이 '페이드 인 + 위로 이동'.

애니메이션/스타일 용어가 필요할 때

빠른 참조표: prompts/effect-vocabulary.md (바로 설치 가능한 항목 이름 포함)
스타일 레시피: prompts/style-recipes.md
요구사항 설명 템플릿 (사용자 또는 다른 AI용): prompts/request-template.md
데모가 있는 갤러리: motion-prompt (192개 효과, npx skills add showheyohtaki/motion-prompt), Motion Library (510개 효과), aimotions (195개 텍스트 애니메이션), catalog/09 참고

UI Master: AI 같지 않은 인터페이스 만들기