[🇬🇧 English version →](./README.md)

# 🎨 Design Auditor — Claude 스킬

**19가지 전문 디자인 카테고리**를 기준으로 디자인을 감사하는 Claude 스킬입니다. 개발자, 비디자이너, 디자인 규칙을 몰라도 전문적인 피드백이 필요한 모든 분을 위해 만들어졌습니다.

**Figma 파일** (Figma MCP), **코드** (HTML/CSS/React/Vue), **스크린샷**, **와이어프레임**, **라이브 URL**, **GitHub 링크** 등 다양한 입력을 지원합니다. **한국어와 영어** 모두 지원합니다.

**Claude**, **Manus**, 그 외 SKILL.md 기반 스킬을 지원하는 에이전트와 호환됩니다.

---

## 무엇을 해주나요?

Figma 링크를 붙여넣거나, CSS를 공유하거나, 스크린샷을 업로드하거나, 와이어프레임을 첨부하면 — Design Auditor가 19가지 디자인 규칙 카테고리에 따라 검토하고 다음을 제공합니다:

- **100점 만점 점수** + 카테고리별 세부 점수 (각 행에 미니 바 차트 포함)
- 별도 **접근성 점수** (WCAG 기준 — Cat 2, 6, 7, 15, 16)
- 별도 **윤리 점수** (다크 패턴 — Cat 18)
- 별도 **사용성 점수** (닐슨 휴리스틱 — Cat 19, H4/H5/H8/H9 교차 참조 포함)
- **🚫 차단** 레벨 — WCAG AA, GDPR, PECR 등 법적 위반 사항 (−12점)
- 심각도별 이슈 분류 (🚫 차단 / 🔴 심각 / 🟡 경고 / 🟢 팁)
- **색맹 컨텍스트** — 실패한 색상 조합마다 영향 받는 색맹 유형 주석 추가
- **SVG 접근성 검사** — 장식/의미 SVG 패턴, aria-hidden, role="img"
- **디자인 시스템 감지** — MUI, Chakra, shadcn/ui, Ant Design, Radix, Bootstrap (시스템별 수정 방법 제시)
- **Figma 오토 레이아웃 스캔** — 오토 레이아웃 대신 수동 배치 사용 중인 프레임 감지
- 각 규칙이 **왜** 중요한지 쉬운 언어로 설명
- **"원리 설명(Teach Me)" 모드** — 수정 방법이 아닌 디자인 원칙 중심의 3레슨 설명
- 이슈를 수정 난이도 vs 개선 효과로 매핑한 **이슈 우선순위 매트릭스**
- HTML/CSS/React/Vue 코드의 **수정 전/후 코드 diff**
- Figma MCP를 통한 **Figma 파일 직접 수정**
- Figma Code Connect — 디자인-코드 간 매핑 갭 감지
- **와이어프레임 → 스펙** 변환 — 개발 즉시 사용 가능한 주석 스펙 생성
- **개발자 전달 보고서** — CSS 스펙 표, 접근성 체크리스트, 핵심 수정사항
- **Canva 시각적 보고서** — 이해관계자와 공유 가능한 시각 요약
- **마크다운 보고서 내보내기** — Notion, GitHub, Linear, Jira 활용 가능

---

## 19가지 감사 카테고리

| # | 카테고리 | 확인 항목 |
|---|---|---|
| 1 | **타이포그래피** | 계층 구조, 폰트 수, 크기, 줄 높이, 대비 |
| 2 | **색상 및 대비** | WCAG 비율, 의미론적 색상 사용, 팔레트 일관성 |
| 3 | **간격 및 레이아웃** | 8포인트 그리드, 근접성, 정렬, 여백 |
| 4 | **시각적 계층** | 주요 동작 명확성, 읽기 패턴, 크기/대비 매핑 |
| 5 | **일관성** | 컴포넌트 재사용, 아이콘 패밀리, 모서리 반경, 상호작용 상태 |
| 6 | **접근성 (A11y / WCAG)** | 터치 타깃, 포커스 상태, 대체 텍스트, 폼 라벨, 읽기 순서 |
| 7 | **폼 및 입력** | 라벨, 크기, 유효성 검사 타이밍, 오류 위치, 제출 상태 |
| 8 | **모션 및 애니메이션** | 목적, 지속 시간, 이징, 모션 감소 지원 |
| 9 | **다크 모드** | 단순 반전 금지, 표면 높낮이, 채도, 아이콘 가독성 |
| 10 | **반응형 및 적응형** | 브레이크포인트, 오버플로우, 터치 타깃, 타입 스케일링 |
| 11 | **로딩·빈 상태·오류 상태** | 스켈레톤, 빈 상태 구성, 오류 레벨, 성공 확인, 피크-엔드 법칙, 목표 경사 진행 표시 검사 |
| 12 | **콘텐츠 및 마이크로카피** | 버튼 라벨, 오류 메시지, 톤 일관성, 용어 |
| 13 | **국제화 및 RTL** | 텍스트 확장, RTL 미러링, 로케일 형식, 폰트 지원 |
| 14 | **엘리베이션 및 그림자** | 그림자 스케일, 높낮이 계층, 다크 모드 깊이 |
| 15 | **아이콘그래피** | 아이콘 패밀리, 광학적 크기, 터치 타깃, 의미 일관성 |
| 16 | **내비게이션 패턴** | 탭, 브레드크럼, 뒤로 가기, 모바일 내비, 활성 상태 |
| 17 | **디자인 토큰 및 변수** | 의미론적 명명, 하드코딩된 값, 다크 모드 토큰 교환 |
| 18 | **윤리적 디자인 및 다크 패턴** | 컨펌셰이밍, 거짓 긴박감, 사전 체크된 동의, CTA 계층 반전, 개인정보 조작, 숨겨진 비용, 디코이 가격 책정, 조작적 앵커링 등 6개 그룹 — 규제 컴플라이언스 기준(쿠키 동의, 구독 고지, 수집 시점 개인정보 고지, 취소 정책, 연령 확인, 접근성 법적 지위) 포함 |
| 19 | **닐슨 사용성 휴리스틱** | H1(시스템 상태 가시성), H2(현실 세계 일치), H3(사용자 제어), H6(기억보다 인식), H7(사용 유연성), H10(도움말 및 문서) |

---

## 누구를 위한 스킬인가요?

- 디자인 배경이 없는 **개발자**
- 빠른 피드백 또는 WCAG 확인이 필요한 **디자이너**
- Figma MCP 또는 VS Code에서 디자인 검증을 원하는 **팀**
- 윤리적이고 접근 가능한 제품을 만들고 싶은 **PM 및 창업자**
- "이거 괜찮아 보여?"가 궁금한 **모든 분**

---

## 설치 방법

1. 릴리즈 페이지에서 [`design-auditor.skill`](../../releases/latest) 다운로드
2. [Claude.ai](https://claude.ai) → **커스터마이즈** → **스킬**
3. **스킬 업로드** 클릭 후 파일 선택
4. 완료 — 이제 대화에서 스킬이 활성화됩니다

---

## 사용 방법

설치 후 Claude에게 자연스럽게 말하면 됩니다:

```
"디자인 검토해줘" → 범위 선택 후 전체 감사
"접근성 확인해줘" → 접근성 중심 감사
"이 폼 좀 봐줘" → 관련 카테고리 부분 감사
"WCAG 기준에 맞아?" → 대비 및 접근성 감사
"이 Figma 파일 확인해줘: [링크]" → Figma MCP 감사
"다크 패턴 있어?" → 윤리 감사
"와이어프레임 스펙 출력해줘" → 와이어프레임 → 스펙 모드
"휴리스틱 검토해줘" → 닐슨 사용성 감사
"이거 GDPR 준수해?" → 윤리 및 접근성 감사
"색상 대비 확인해줘" → 색상 및 접근성 감사
```

Figma URL, GitHub 링크, 라이브 사이트 URL, 스크린샷, HTML/CSS 코드를 공유하면 Claude가 자동으로 감사를 실행하고 입력한 언어로 응답합니다.

---

## 지원하는 URL 유형

| URL 유형 | 신뢰도 | 처리 방식 |
|---|---|---|
| 라이브 웹사이트 (`https://...`) | 🟡 보통 | web_fetch, 로그인 처리, 다중 페이지 제안 |
| Vercel / Netlify 프리뷰 | 🟡 보통 | 라이브 웹사이트와 동일 |
| GitHub 파일 URL | 🟢 높음 | 원시 소스 가져와 전체 코드 감사 |
| GitHub 저장소 URL | 🟡 보통 | 주요 파일 탐색, 범위 선택 위젯 |
| CodeSandbox / StackBlitz | 🟡–🟢 | 소스 접근 가능 시 코드 감사, 아니면 미리보기 |
| CodePen | 🟡 보통 | 디버그 URL 가져오기, 소스 추출 시도 |
| Storybook | 🟡 보통 | URL 경로에서 컴포넌트/변형 감지 |

---

## 출력 예시

```
## 🔍 디자인 감사 보고서

**입력:** 체크아웃 플로우 · 3개 프레임
**유형:** Figma MCP
**신뢰도:** 🟢 높음
**컴포넌트 건강도:** 71% 커버리지 · 2개 분리된 인스턴스 · 8개 이름 없는 레이어
**Code Connect:** 8개 컴포넌트 매핑됨 · 3개 미매핑

### 종합 점수: 62/100
100 − (1 × 🚫 12) − (2 × 🔴 8) − (4 × 🟡 4) − (2 × 🟢 1) = 62/100
법적 준수 위반 및 대비 문제가 주요 원인입니다.

### 접근성 점수: 55/100 — 심각한 문제 ⚠️ 법적 준수 위반 포함
### 윤리 점수: 85/100 — 사소한 우려
### 사용성 점수: 78/100 — 사소한 문제

### 🚫 차단 항목 (−12점 각각) — 출시 불가
- **텍스트 대비 미달** — #aaa on white = 2.3:1 → 수정: #595959 사용 (7:1)
  법적 근거: WCAG 2.1 SC 1.4.3

### 🔴 심각한 문제 (−8점 각각)
- **폼 라벨 누락** — 플레이스홀더만 있는 입력 필드
  → 수정: 각 입력 위에 <label> 추가

### 🟡 경고 (−4점 각각)
- **그리드 벗어난 간격** — padding: 13px → 수정: 8의 배수 사용 (8, 16, 24px)
- **CTA 계층 반전** — "모두 수락"이 주요, "모두 거부"가 회색 텍스트
  → 수정: 동등한 시각적 비중 적용 (GDPR 요구사항)

### ✅ 잘 된 부분
- 논리적인 섹션 흐름의 깔끔한 페이지 구조
- 히어로 CTA 버튼의 강한 대비와 적절한 크기
```

---

## 스킬 구조

```
design-auditor/
├── SKILL.md                        — 주요 스킬 지시사항 (19개 카테고리)
└── references/
    ├── typography.md               — 폰트 규칙, 크기, 계층, 타입 스케일 알고리즘
    ├── color.md                    — WCAG 휘도 공식, 대비, 팔레트 가이드
    ├── spacing.md                  — 8포인트 그리드, 레이아웃, 근접성, 코드 확인
    ├── corner-radius.md            — 중첩 반경 규칙, 스케일, 필 셰이프, 코드 확인
    ├── elevation.md                — 그림자 스케일, 높낮이 계층, 코드 그림자 감사
    ├── iconography.md              — 아이콘 패밀리, 크기, 터치 타깃
    ├── navigation.md               — 탭, 브레드크럼, 뒤로 가기, 모바일 내비, 코드 확인
    ├── tokens.md                   — 디자인 토큰, 의미론적 명명, 다크 모드 아키텍처
    ├── figma-mcp.md                — Figma MCP 워크플로우, Code Connect, 페이지 구조
    ├── states.md                   — 로딩, 빈, 오류, 성공 상태 + 코드 확인
    ├── microcopy.md                — 버튼 라벨, 오류, 톤, 역할별 감사 가이드
    ├── animation.md                — 이징 곡선, 지속 시간 스케일, 모션 감소, 코드 확인
    ├── i18n.md                     — RTL 지원, 로케일 형식, 국제화
    ├── ethics.md                   — 다크 패턴, 윤리적 디자인, 설득 vs 조작
    └── heuristics.md               — 닐슨 10가지 사용성 휴리스틱, 탐지 신호, 사용성 점수
```

---

## 변경 이력

### v1.2.13

**Cat 18에 규제 컴플라이언스 기준 추가.**

**신규: 규제 컴플라이언스 기준 (Cat 18 Group F)**
EU, 미국, 영국, 캐나다, 브라질, 호주에 공통 적용되는 UI 감지 가능 컴플라이언스 검사 6종. 법적 요건이 명확히 누락된 경우 🚫 차단, 모호한 경우 🟡 경고. 각 항목에 코드 신호 및 "법률 전문가 확인 필요" 주의 문구 포함. 한국어 전체 지원.
- **쿠키 및 동의 배너** — GDPR, PECR, CCPA: 배너 존재 여부, "모두 거부"와 "모두 수락" 동등한 시각적 비중, 세분화된 동의 카테고리
- **구독 자동 갱신 고지** — FTC, CMA, EU 소비자 권리 지침: 결제 확인 전 갱신 주기·금액·취소 방법 명시
- **수집 시점 개인정보 고지** — GDPR 제13조, CCPA, PIPEDA: 민감 입력 필드 근처 개인정보처리방침 링크 또는 수집 목적 안내
- **청약 철회 / 취소 정책** — EU 소비자 권리 지침, 영국 CRA, FTC: 최종 결제 CTA 근처 취소·환불 정책 링크
- **연령 제한 콘텐츠 연령 확인** — COPPA, GDPR 제8조, 영국 연령적합 디자인 코드: 제한 콘텐츠 접근 전 연령 확인 절차
- **접근성 법적 기준** — ADA/Section 508(미국), 유럽 접근성법(EU — 2025년 6월 의무화), PSBAR(영국), DDA(호주), AODA(캐나다): Cat 6 차단 항목은 법적 책임 수반

------------------------------------------------------------------------------------------------------------------------------------------

### v1.2.12

**nudges.fyi 행동 패턴 추가, 버그 수정, 시각적 보고서 개선.**

**신규: 5가지 행동 패턴 추가**
- **선택 과부하(Overchoice Paradox) → Cat 4** — 주요 액션 구분 없이 4개 이상 동일 비중의 선택지 → 🟡; 6개 이상 → 🔴. 목록·내비·테이블 제외
- **피크-엔드 법칙(Peak-End Rule) → Cat 11** — 성공/완료 화면의 기억 가능성 감사: 완료 내용, 다음 단계, 시각적 강화 요소, 자동 리다이렉트 타이밍
- **목표 경사 이론(Goal Gradient Theory) → Cat 11** — 진행 바 없는 다단계 플로우, 정적 진행 바, 전체 단계 수 미표시, `aria-valuenow` 누락 감지
- **디코이 가격 책정(Decoy Pricing) → Cat 18 Group A** — 3열 가격 표에서 모든 기준에서 열등한 하나의 등급 감지
- **조작적 앵커링(Manipulative Anchoring) → Cat 18 Group D** — `text-decoration: line-through` / `.was-price` / `.rrp` 패턴 감지

**버그 수정**
- Cat 18 패턴 수 업데이트: 20개 → 22개 (두 README 모두)
- Cat 6 SVG `<use>`: `href`와 함께 `xlink:href` 레거시 검사 추가
- Cat 19 H1 "멀티스텝 진행 표시": Cat 11 목표 경사 이론 교차 참조 추가로 중복 플래그 방지
- 점수 패널: 윤리 점수 별도 산식 주의 문구 추가 — `🔴 −15 · 🟡 −7 · 🟢 0`
- `heuristics.md` 구분자: `-` → `—`
- README Cat 11 행: 피크-엔드 법칙 및 목표 경사 이론 명시

**시각적 보고서 개선**
- 레이더 차트: 이진 보라/빨강 → 3색 스케일 — 보라(8–10) · 황색(6–7) · 빨강(≤ 5)
- 레이더 차트: Visualizer 사용 불가 시 카테고리 점수 표로 폴백 (영문 + 한국어)
- 이슈 우선순위 매트릭스: 한국어 축 라벨 추가 — `수정 난이도` (x) · `개선 효과` (y)
- 카테고리별 점수 표: 점수 밴드 각주 추가 — `≥ 8 ✅ · 5–7 🟡 · ≤ 4 🔴` (영문 + 한국어)
- 재감사 델타: Visualizer로 이전/이후 바 쌍 렌더링, 색상 코드 델타 배지 포함
- "원리 설명" 모드: 레슨 후 3카드 Visualizer 레이아웃, 각 카드 `sendPrompt()` 클릭 가능

------------------------------------------------------------------------------------------------------------------------------------------

### v1.2.11

**코드 커버리지 완성, 디자인 시스템 감지, 접근성 개선, 버그 수정.**

- **코드 슈퍼파워 완성** — 19개 전 카테고리에 `📋 Code input:` 블록 추가: Cat 4, 5, 11, 12, 14, 15
- **디자인 시스템 감지** — MUI, Chakra UI, shadcn/ui, Ant Design, Radix, Bootstrap 자동 감지; 시스템별 이슈 유형 및 수정 경로 제공
- **색맹 컨텍스트** — 실패한 색상 조합마다 영향 받는 색맹 유형 주석 추가 (제1/제2/제3 색약)
- **SVG 접근성** — 장식용 `aria-hidden`, 의미 있는 `role="img"` + `<title>`, 아이콘 버튼 라벨 검사 (Cat 6 + Cat 15)
- **Figma 오토 레이아웃 스캔** — 오토 레이아웃 대신 수동 배치 사용 프레임 감지; 보고서 헤더에 표시
- **접근성 점수** — Cat 2/6/7/16에서 Cat 2/6/7/**15**/16으로 확장 (Cat 15 SVG 검사는 WCAG 법적 위반)
- **닐슨 교차 참조** — H4/H5/H8/H9를 점수 패널에서 Cat 5/7/4/11–12로 매핑 표시
- **"원리 설명" 모드** — 상위 3개 이슈의 디자인 원칙 설명 (초보자/숙련자 적응, 한국어 전체 지원)
- **점수 산식** — 블로커 명시 추가: `100 − (blockers × 12) − (criticals × 8) − (warnings × 4) − (tips × 1)`
- **개발자 전달 보고서** — 🟢 팁 섹션 추가; 한국어 번역 포함
- **출력 개선** — 카테고리 점수 표 미니 바; 보고서 헤더 Design System + Auto Layout 행; Cat 9 `color-scheme` 검사
- **버그 수정** — "17" → "19" 전체 수정; Cat 18/19 번호 오류; `i19n.md` → `i18n.md`; README_KR 카테고리 수 수정

------------------------------------------------------------------------------------------------------------------------------------------

### v1.2.10

**개발자 전달 보고서, 와이어프레임 스펙 — 구조 개편. 두 기능 모두 한국어 지원 추가.**

**개발자 전달 보고서 개편:**
- 모든 섹션에 `━━━` 구분선 추가 — 일관된 시각적 구분
- 블로커를 별도 섹션(`🚫 블로커 — 다른 작업보다 먼저 수정`)으로 분리 — 기존에는 치명적 수정과 묶여 있었음
- 메타데이터 표에 4개 점수 모두 포함: 전체, 접근성, 윤리, 사용성 (조건부 표시)
- Code Connect 매핑 표 템플릿에 추가
- `━━━` 구분선으로 감싼 일관된 푸터

**와이어프레임 스펙 개편:**
- 8개 섹션 모두 이모지 헤더와 `━━━` 구분선 적용 (📐 📏 🔤 🧩 ✍️ 🖱️ ♿ ❓)
- 컨텍스트 메모를 각 `━━━` 블록 바로 아래로 이동 — 기존 인라인 분산 배치에서 개선

**신규 기능 한국어 지원 추가:**
- 개발자 전달 보고서 — 한국어 노트: 제목, 6개 필드 라벨, 7개 섹션 헤더, 12개 표 컬럼 헤더, 푸터
- 와이어프레임 스펙 — 이중 언어 푸터 + 한국어 노트: 제목, 필드 라벨, 8개 섹션 헤더(컨텍스트 메모 포함), 표 컬럼 헤더

**README:**
- 영어 README의 v1.0.0–v1.2.4 변경 이력을 `<details>` 블록으로 접기

### v1.2.9
- 한국어 지원 전면 감사 및 보완 — v1.2.4 이후 추가된 모든 기능에 한국어 적용
- Cat 19 체크리스트 19개 항목 모두 한국어 라벨 추가
- 한국어 트리거: "휴리스틱 검토", "닐슨 감사", "사용성 휴리스틱"
- 사용성 점수 밴드 한국어 추가
- URL 감사 보고서 헤더 한국어 형식 추가
- 와이어프레임 스펙 헤더 한국어 추가
- `heuristics.md` 한국어 용어 표, 심각도 라벨, 체크리스트 번역 추가

### v1.2.8
- **Cat 19 닐슨 사용성 휴리스틱** 추가 — H1/H2/H3/H6/H7/H10 감사
- 새 참조 파일 `heuristics.md` (730줄) 추가
- 종합 보고서에 별도 사용성 점수 표시

### v1.2.7
- URL 입력 전면 지원 — 라이브 사이트, GitHub, CodeSandbox, StackBlitz, CodePen, Storybook
- 에이전트 출력 형식 강제 적용 — 자유 형식 UX 리뷰 대신 점수화된 보고서 의무화

### v1.2.6
- **와이어프레임 → 스펙 모드** — 레이아웃, 간격, 타이포그래피, 필요한 컴포넌트, 카피 플레이스홀더, 상호작용 메모, 접근성 요구사항, 미해결 질문 포함
- **Canva 시각적 보고서** 내보내기 — 이해관계자 친화적 형식
- 트리거 어휘 확장 및 버전 스탬프 수정

### v1.2.5
- Figma MCP 새 도구 3개 통합: `get_code_connect_suggestions`, `get_code_connect_map`, `create_design_system_rules`
- **차단(Blocker) 심각도 레벨** 추가 — WCAG AA, GDPR, PECR 법적 위반 시 −12점
- 트리거 어휘 15개 이상 추가

### v1.2.4
- **Cat 18 윤리적 디자인 및 다크 패턴** 추가 — 5개 그룹 20가지 조작 패턴
- 새 참조 파일 `ethics.md` 추가
- 윤리 심각도 모델: 🔴 기만 (−15점) · 🟡 의심스러움 (−7점) · 🟢 참고 (0점)

### v1.2.4 이전
[영어 README의 v1.0.0–v1.2.4 변경 이력을 참고하세요](./README.md) (`<details>` 블록에 접혀 있습니다)

---

## 기여하기

추가해야 할 디자인 규칙이 있나요? 이슈나 PR을 열어주세요.

확장이 필요한 영역:
- UX 플로우 분석 및 정보 구조
- 데이터 시각화 및 차트
- 네이티브 모바일 (iOS/Android) 특화 패턴
- 인쇄 / PDF 레이아웃 규칙

---

## 라이선스

MIT — 사용, 포크, 빌드 모두 자유롭게 가능합니다.

---

*[Claude](https://claude.ai)로 제작 · 스킬 형식: [Anthropic](https://anthropic.com)*
