디자인 폴리싱 스킬 v2.0

디자인 지식 기반(서비스 유형별 규칙, 컴포넌트 체크리스트, UX 규칙) + 실시간 시각 비교(Puppeteer 스크린샷) + WCAG 자동 검사(axe-core) + 트렌드 검색(WebSearch) 통합 폴리싱.

지식 기반 리소스

• knowledge/: 서비스 유형별 UI 규칙, 컴포넌트 체크리스트, UX 규칙 (마크다운 직접 Read)

• data/: 66개 디자인 스타일, 96개 색상 팔레트, 57개 타이포그래피, 13개 기술 스택 가이드 (JSON + BM25 검색)

• scripts/search.cjs: Node.js BM25 검색 엔진

인수

• --apply : (옵션) 개선안을 코드에 직접 적용

• --wcag-only : (옵션) WCAG 접근성 체크만 수행

• --no-wcag : (옵션) WCAG 체크 생략

• $1: (옵션) 레퍼런스 사이트 (미지정시 프로젝트 유형에 맞게 자동 선택)

• $2: (옵션) 기능 키워드 (미지정시 전체 디자인 폴리싱)

사용 예시

/design-polish # 전체 자동 폴리싱 + WCAG 체크 /design-polish --apply # 폴리싱 + 코드 적용 /design-polish --wcag-only # WCAG 접근성 체크만 /design-polish mobbin # Mobbin에서 검색 /design-polish godly hero # Godly에서 hero 검색 /design-polish --apply godly hero # hero 폴리싱 + 코드 적용

실행 플로우 개요

전제조건 확인 ↓ 0단계: 프로젝트 분석 + 서비스 유형 감지 + 스크린샷 캡처 [Glob, Read, Bash] ↓ 1단계: WCAG 접근성 체크 (axe-core) [Bash, Read] ↓ 1.5단계: 디자인 지식 로딩 [Read, Bash] ↓ 2단계: 레퍼런스 사이트 선택 ↓ 3단계: 트렌드 검색 → 레퍼런스 캡처 [WebSearch, Bash] ↓ 4단계: Gap 분석 (시각 비교 + 지식 기반) [Read] ↓ 5단계: 개선안 도출 (8단계 우선순위) ↓ 6단계: 결과 출력 ↓ 7단계: 코드 적용 (--apply 시) [Edit, Bash] ↓ Pre-delivery 체크리스트

전제조건 확인

실행 전 다음 조건을 확인합니다:

1. 개발 서버 실행 확인

Mac/Linux - 서버 상태 확인

curl -s -o /dev/null -w "%{http_code}" http://localhost:3000

Windows PowerShell - 서버 상태 확인

try { (Invoke-WebRequest -Uri http://localhost:3000 -UseBasicParsing -TimeoutSec 5).StatusCode } catch { 0 }

자동 포트 감지 (서버가 3000이 아닐 수 있음):

Mac/Linux - 실행 중인 개발 서버 포트 탐지

lsof -i -P | grep LISTEN | grep -E ':(3000|5173|8080|4200)'

Windows PowerShell - 실행 중인 개발 서버 포트 탐지

Get-NetTCPConnection -State Listen | Where-Object { $_.LocalPort -in 3000,5173,8080,4200 }

서버가 실행 중이 아니면 사용자에게 안내:

"개발 서버를 먼저 실행해주세요. (예: npm run dev)"

2. 플러그인 의존성 확인

플러그인 디렉토리에서 npm install 실행 여부 확인

ls ~/.claude/plugins/marketplaces/design-polish/node_modules/puppeteer

없으면 안내:

"플러그인 의존성을 설치해주세요: cd ~/.claude/plugins/marketplaces/design-polish && npm install"

3. Node.js 확인

node --version

0단계: 프로젝트 분석 + 서비스 유형 감지

사용 도구: Glob , Read , Bash

프로젝트 유형 감지

• 디렉토리 구조: src/ , components/ , pages/ , app/ 등

• 프레임워크: React, Vue, Flutter, Next.js, Nuxt 등

• 스타일링: CSS, Tailwind, styled-components, CSS Modules, SCSS 등

서비스 유형 감지

프로젝트 코드에서 서비스 유형 신호를 자동 감지합니다:

감지 신호 서비스 유형

결제/장바구니/상품/checkout 코드 Online Shop

인증+대시보드+subscription SaaS Platform

의료 용어, HIPAA, patient Healthcare Service

차트+거래+지갑+crypto Finance & Trading

학습+퀴즈+진도+course Education & Learning

포트폴리오+작품+projects Portfolio

.gov, 접근성 중심 Government Service

chat+AI+prompt+stream AI & Chatbot

메뉴+예약+food Food & Restaurant

booking+destination+travel Travel & Booking

property+listing+map Real Estate

game+score+level+player Gaming

article+news+breaking News & Media

feed+like+share+follow Social Media

workout+fitness+health Fitness & Gym

럭셔리+프리미엄+브랜드+high-end Luxury Brand

에이전시+케이스스터디+creative+팀 Creative Agency

웰니스+명상+마음챙김+calm Wellness & Health

admin+대시보드+analytics+지표 Admin Dashboard

IDE+터미널+코드에디터+syntax+CLI Developer Tool

감지 방법: Grep 으로 주요 코드 파일에서 키워드 빈도 분석, 가장 높은 점수의 서비스 유형을 선택합니다.

디자인 파일 탐지

유형 패턴

컴포넌트 **/.tsx , **/.jsx , **/.js , **/.vue , **/.svelte , **/.dart

스타일 **/.css , **/.scss , */tailwind.config.

레이아웃 */layout. , */App. , */page. , */_app.

현재 디자인 스크린샷 캡처

Bash로 캡처 스크립트 실행:

캡처 스크립트 실행 (${CLAUDE_PLUGIN_ROOT}는 플러그인 설치 경로로 자동 치환됨)

node "${CLAUDE_PLUGIN_ROOT}/scripts/capture.cjs" / /about /pricing

포트 변경시

BASE_URL=http://localhost:5173 node "${CLAUDE_PLUGIN_ROOT}/scripts/capture.cjs" /

저장 위치: .design-polish/screenshots/current-*.png

캡처 후 Read로 이미지 분석

Read(".design-polish/screenshots/current-main.png")

분석 항목:

• 레이아웃 구조

• 색상 팔레트

• 타이포그래피

• 컴포넌트 스타일

1단계: WCAG 접근성 체크

사용 도구: Bash , Read

체크 실행

WCAG 체크 포함 캡처

node "${CLAUDE_PLUGIN_ROOT}/scripts/capture.cjs" --wcag /

체크 항목 (axe-core 기반)

카테고리 체크 항목 WCAG 기준

색상 대비 텍스트-배경 대비 4.5:1 (AA)

색상 대비 대형 텍스트 대비 3:1 (AA)

색상 대비 UI 컴포넌트 대비 3:1

텍스트 크기 최소 텍스트 크기 12px 이상 권장

터치 타겟 최소 타겟 크기 44x44px (모바일)

링크 링크 구분 밑줄 또는 3:1 대비

결과 저장

.design-polish/ ├── screenshots/ │ └── current-main.png └── accessibility/ └── wcag-report.json

결과 확인

Read(".design-polish/accessibility/wcag-report.json")

1.5단계: 디자인 지식 로딩

사용 도구: Read , Bash

0단계에서 감지된 서비스 유형/기술 스택 정보를 기반으로 디자인 지식을 로딩합니다.

마크다운 직접 로딩 (필수 — 매 실행시)

Read("${CLAUDE_PLUGIN_ROOT}/knowledge/industry-rules.md") Read("${CLAUDE_PLUGIN_ROOT}/knowledge/component-checklist.md") Read("${CLAUDE_PLUGIN_ROOT}/knowledge/ux-rules.md")

스크립트 검색 (감지된 서비스 유형/키워드 기반)

0단계에서 감지된 서비스 유형 키워드를 사용

예: SaaS Platform 감지 시

node "${CLAUDE_PLUGIN_ROOT}/scripts/search.cjs" --domain style "saas dashboard minimal"

예: Online Shop 감지 시

node "${CLAUDE_PLUGIN_ROOT}/scripts/search.cjs" --domain color "ecommerce shopping"

예: Healthcare Service 감지 시

node "${CLAUDE_PLUGIN_ROOT}/scripts/search.cjs" --domain typography "medical clean accessible"

기술 스택 가이드 (코드 적용 시에만)

예: React 프로젝트 감지 시

node "${CLAUDE_PLUGIN_ROOT}/scripts/search.cjs" --domain stack --stack react "accessibility aria"

검색 예시

감지된 서비스 유형 스타일 검색 색상 검색 타이포 검색

SaaS Platform "saas dashboard minimal" "saas professional trust" "modern professional clean"

Online Shop "ecommerce vibrant card" "ecommerce shopping" "ecommerce clean shopping"

Healthcare Service "healthcare accessible calm" "healthcare calm" "medical clean accessible"

Finance & Trading "fintech dark glass" "fintech crypto" "financial trust"

Education & Learning "education playful friendly" "education playful" "playful friendly"

Wellness & Health "wellness organic biophilic" "wellness nature calm" "calming soft rounded"

2단계: 레퍼런스 사이트 선택

사용 도구: 판단 로직

$1 미지정시 자동 선택

프로젝트 유형 판단 기준 우선 사이트 대체 사이트

앱 UI/UX Flutter, React Native, 모바일 우선 Mobbin Page Flows, Refero

모던 웹/SaaS Next.js, Nuxt, 대시보드 Godly Dark Mode Design, Awwwards

감각적/예술적 포트폴리오, 갤러리, 아트 키워드 SiteInspire Savee, Behance

랜딩페이지 단일 페이지, 마케팅 중심 Lapa Ninja Httpster

UI 디테일 컴포넌트 중심, 버튼/카드 등 Dribbble

3단계: 트렌드 검색

사용 도구: WebSearch , Bash

3-1. WebSearch로 레퍼런스 검색

기능 단위 검색 (업종별 X)

올바른 검색:

• site:mobbin.com onboarding flow
• site:godly.website hero section
• site:dribbble.com dashboard UI 2024

잘못된 검색:

• "금융 앱 디자인"
• "게임 앱 UI"

3-2. 검색 결과에서 URL 추출

WebSearch 결과에서 유용한 레퍼런스 URL을 2-3개 선정.

3-3. Bash로 레퍼런스 캡처

단일 레퍼런스 캡처

node "${CLAUDE_PLUGIN_ROOT}/scripts/capture.cjs" ref "https://dribbble.com/shots/..." hero

여러 개 캡처 (브라우저 재사용으로 효율적)

node "${CLAUDE_PLUGIN_ROOT}/scripts/capture.cjs" ref "https://site1.com" ref1 "https://site2.com" ref2

저장 위치: .design-polish/screenshots/reference-*.png

검색 실패시 (자동 처리)

• 대체 사이트로 재시도: 위 표의 대체 사이트 순서대로

• site: 제거: 일반 웹 검색으로 전환

• 키워드 일반화: 예) "checkout" → "ecommerce flow"

4단계: Gap 분석 (시각 비교 + 지식 기반)

사용 도구: Read

Read로 이미지 비교 분석

Read(".design-polish/screenshots/current-main.png") Read(".design-polish/screenshots/reference-hero.png")

분석 영역

영역 분석 항목 지식 기반 참조

레이아웃 그리드, 여백, 정보 계층, CTA 위치 ux-rules.md → Layout

타이포그래피 폰트, 크기, 행간, 웨이트 search.cjs typography 검색 결과

색상 팔레트, 대비, 다크모드 지원 search.cjs color 검색 결과

인터랙션 호버, 전환, 애니메이션, 로딩 ux-rules.md → Animation

컴포넌트 버튼, 카드, 입력, 모달, 토스트 component-checklist.md

상태 로딩/성공/실패/빈 상태 처리 ux-rules.md → Loading & Error

접근성 WCAG 위반 항목, 터치 타겟, 포커스 표시 ux-rules.md → Accessibility

서비스 유형 적합성 industry-rules.md 기준 스타일/색상 일치 여부 industry-rules.md

스타일 매칭 search.cjs 검색 결과와 현재 디자인 비교 search.cjs style 검색 결과

지식 기반 분석 (추가)

• 서비스 유형 적합성: industry-rules.md에서 해당 서비스 유형의 추천 스타일/색상과 현재 디자인 비교

• 컴포넌트 품질: component-checklist.md의 Do/Don't 체크 — 사용 중인 컴포넌트별 위반 확인

• UX 규칙 준수: ux-rules.md의 각 카테고리별 패턴 체크

• 스타일 매칭: search.cjs 검색 결과의 추천 스타일과 현재 디자인 비교

• 색상/타이포 매칭: 검색된 팔레트/폰트 페어링 vs 현재 사용 중인 값 비교

플랫폼별 추가 기준

플랫폼 핵심 기준

웹 스캔 가능성, 정보 밀도, 반응형

앱 엄지 도달 범위, 제스처, 네이티브 패턴

5단계: 개선안 도출 (8단계 우선순위)

우선순위 분류

우선순위 카테고리 영향 예시

P1 접근성 (WCAG 위반) CRITICAL 대비 부족, 터치 타겟 미달, 포커스 미표시

P2 터치/인터랙션 CRITICAL cursor 미지정, 타겟 크기 미달, hover 없음

P3 성능 HIGH 이미지 미최적화, reduced-motion 미지원

P4 레이아웃/반응형 HIGH CLS, 모바일 깨짐, 뷰포트 이슈

P5 타이포/색상 MEDIUM 행간 부족, 서비스 유형 부적합 색상, 폰트 미매칭

P6 애니메이션 MEDIUM 트랜지션 누락, 과도한 모션, 타이밍 이슈

P7 스타일 적합성 MEDIUM 서비스 유형별 추천 스타일과 불일치

P8 차트/데이터 LOW 차트 접근성, 데이터 시각화 개선

각 개선안에는 다음 정보를 포함합니다:

• 대상 파일 경로

• 구체적인 변경 내용

• 참조 근거 (knowledge 파일, search.cjs 결과, WCAG 기준 등)

6단계: 결과 출력

출력 형식

프로젝트 요약

[프레임워크], [스타일링 방식] 기반 [프로젝트 유형] 감지된 서비스 유형: [서비스 유형명]

WCAG 접근성 체크

서비스 유형별 적합성

컴포넌트 체크 결과

트렌드 요약

• [핵심 트렌드 1]
• [핵심 트렌드 2]
• [핵심 트렌드 3]

Gap 분석

추천 리소스 (search.cjs 결과)

• 추천 스타일: [스타일명] — [cssHints]
• 추천 색상: Primary [HEX], Secondary [HEX], CTA [HEX], BG [HEX]
• 추천 폰트: [Heading Font] + [Body Font] — [Google Fonts URL]

개선안 (8단계 우선순위)

P1: 접근성 (CRITICAL)

• btn-primary 색상 대비 수정 (src/components/Button.tsx)

P2: 터치/인터랙션 (CRITICAL)

• [개선안 + 대상 파일]

P3: 성능 (HIGH)

• [개선안 + 대상 파일]

P4: 레이아웃/반응형 (HIGH)

• [개선안 + 대상 파일]

P5: 타이포/색상 (MEDIUM)

• [개선안 + 대상 파일]

P6: 애니메이션 (MEDIUM)

• [개선안 + 대상 파일]

P7: 스타일 적합성 (MEDIUM)

• [개선안 + 대상 파일]

P8: 차트/데이터 (LOW)

• [개선안 + 대상 파일]

7단계: 코드 적용 (--apply 옵션시만)

사용 도구: Edit , Bash

스택 가이드 참조

코드 적용 전, 감지된 기술 스택의 가이드라인을 참조합니다:

기술 스택 가이드 검색 (적용할 영역 키워드로)

예: React 프로젝트 감지 시

node "${CLAUDE_PLUGIN_ROOT}/scripts/search.cjs" --domain stack --stack react "accessibility aria"

적용 순서

• P1 (접근성 CRITICAL) 우선순위부터 순차 적용

• P2~P4 (CRITICAL/HIGH) 적용

• P5~P7 (MEDIUM) — 사용자 확인 후 적용

• 각 수정 후 파일 저장

• 적용 결과 요약 출력

적용하지 않는 것

• 새 라이브러리 설치 필요한 변경

• 대규모 구조 변경 (리팩토링 수준)

• 브레이킹 체인지

적용 결과 출력

적용 완료

미적용 (수동 필요)

• Framer Motion 설치 필요 (애니메이션)

레퍼런스 사이트 목록

실제 서비스 UX 흐름

사이트 URL 특징

Mobbin mobbin.com 실 서비스 스크린샷, 플로우별 정리

Page Flows pageflows.com 영상 기반 플로우, 인터랙션 참고

Refero refero.design 실제 서비스 UI 요소 모음

모던 웹 트렌드 (Tech & SaaS)

사이트 URL 특징

Godly godly.website 다크 모드, 마이크로 인터랙션

Dark Mode Design darkmodedesign.com 다크 모드 UI 큐레이션

Awwwards awwwards.com 창의적/기술적 웹사이트

감각적 & 예술적 영감

사이트 URL 특징

SiteInspire siteinspire.com 레이아웃, 색감, 분위기

Savee savee.it 무드보드용 시각적 자극

Behance behance.net 브랜딩, Case Study

랜딩 페이지 & 마케팅

사이트 URL 특징

Lapa Ninja lapa.ninja 랜딩 페이지 레퍼런스 최다

Httpster httpster.net 심플한 타이포그래피

UI 디테일

사이트 URL 특징

Dribbble dribbble.com 버튼, 카드 등 디테일

Pre-delivery 체크리스트

코드 적용 후 (--apply 시) 또는 최종 결과 보고 전에 다음을 확인합니다:

시각 품질

• 색상 대비 4.5:1 이상 (WCAG AA)

• 일관된 border-radius (8px/12px/16px 중 택일)

• 일관된 spacing scale (예: 4/8/12/16/24/32px)

• 폰트 계층 명확 (h1 > h2 > h3 > body > caption)

인터랙션

• 모든 클릭 가능 요소에 cursor: pointer

• 호버 상태 (150-200ms transition)

• 포커스 링 (2-3px, 키보드 사용자)

• 로딩 상태 (스켈레톤 또는 스피너)

• 에러 상태 (인라인 메시지 + 아이콘)

라이트/다크 모드

• 다크 모드 전환시 깨지는 요소 없음

• 다크 모드 색상 대비 유지

레이아웃

• 모바일 (320px~) 깨지지 않음

• 태블릿 (768px) 적절한 배치

• 데스크톱 (1024px+) 최대 너비 제한

접근성 최종 점검

• axe-core 위반 0건 (또는 justified)

• 키보드 네비게이션 가능

• 스크린 리더 호환 (ARIA 레이블)

• prefers-reduced-motion 지원