zeoel-framework 1.0.0

package/.agents/skills/zeoel/skills/design-auditor/README_KR.md

@@ -0,0 +1,327 @@
+[🇬🇧 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)*

package/.agents/skills/zeoel/skills/design-auditor/SKILL.md

@@ -0,0 +1,8 @@
+---
+name: design-auditor
+description: design auditor — loaded from design-skills plugin
+source: design-skills-plugin
+---
+# Design Auditor
+
+> **Plugin Skill**: This skill is provided by the `design-skills` plugin. When available, read the full skill from the plugin directory. When not available, use the agent's embedded knowledge of design auditor patterns.

package/.agents/skills/zeoel/skills/design-auditor/references/animation.md

@@ -0,0 +1,300 @@
+# Motion & Animation Reference
+
+## Why Animation Rules Exist
+
+Animation has a job. When it does its job it reduces cognitive load, orients the user, and confirms actions. When it doesn't, it distracts, delays, and exhausts. Every animation in a UI should pass the "why is this here?" test.
+
+---
+
+## The Animation Purpose Taxonomy
+
+Every animation falls into one of these categories. If it doesn't, it's decoration — and decoration should be removed.
+
+| Purpose | What It Does | Example |
+|---|---|---|
+| **Orientation** | Shows *where* something came from or is going | Panel slides in from the right = it came from a sub-layer |
+| **Feedback** | Confirms an action was received | Button press → brief scale-down → spring back |
+| **State change** | Communicates a change of status | Toggle switches from off to on |
+| **Relationship** | Shows connection between two things | Shared element transitions (hero card → detail view) |
+| **Attention** | Draws the eye to something important | New notification badge pulses once |
+| **Progress** | Shows work is happening | Loading bar, skeleton shimmer |
+
+❌ Pure decoration: "logo spins on load because it looks cool" — remove.
+
+---
+
+## Duration Scale
+
+UI animation should feel instant but not jarring. These are the standard duration bands:
+
+| Category | Duration | When to Use |
+|---|---|---|
+| **Micro** | 100–150ms | Hover states, color changes, button presses |
+| **Transition** | 150–250ms | Element enter/exit, expanding panels, tooltips |
+| **Page** | 250–400ms | Route transitions, modal open/close |
+| **Emphasis** | 400–600ms | Onboarding, celebration, error shake |
+| **Never** | 600ms+ | Nothing in UI. Feels broken. |
+
+**Common mistakes:**
+- Sidebar slides in at 600ms → user waits, feels sluggish
+- Toast notification exits at 1200ms → user waits for it to leave
+- Staggered list animation total > 500ms → last item feels forgotten
+
+**Rule of thumb:** If you're animating data or content the user is waiting for, err shorter. If you're animating a transition the user triggered, 200ms feels crisp.
+
+---
+
+## Easing Reference
+
+Easing defines the velocity curve. Using the wrong easing makes motion feel physically wrong.
+
+| Easing | Curve | When to Use |
+|---|---|---|
+| `ease-out` | Fast start, slow end | **Entering elements.** Things entering the screen decelerate into place — like an object being placed. |
+| `ease-in` | Slow start, fast end | **Exiting elements.** Things leaving the screen accelerate away — like an object being picked up. |
+| `ease-in-out` | Slow start, slow end | **Elements that move but stay.** Drawers, panels sliding across the screen. |
+| `linear` | Constant speed | **Looping animations only** (spinners, progress). Linear motion for one-off transitions feels mechanical and unnatural. |
+| `spring` | Overshoot + settle | **High-energy feedback.** Button presses, pull-to-refresh, elastic effects. Use sparingly. |
+
+**CSS values for reference:**
+```css
+ease-out:     cubic-bezier(0, 0, 0.58, 1)
+ease-in:      cubic-bezier(0.42, 0, 1, 1)
+ease-in-out:  cubic-bezier(0.42, 0, 0.58, 1)
+spring:       Use spring() in Figma or CSS @spring in motion libraries
+```
+
+**Common mistake**: Using `ease-in` for entering elements — it starts slow, making the UI feel unresponsive.
+
+---
+
+## Figma Smart Animate Naming Conventions
+
+Figma's Smart Animate transitions work by matching layer names across frames. For it to work correctly:
+
+### Naming Rules
+```
+ComponentName/Variant/State
+
+Button/Primary/Default   →   Button/Primary/Hover    ✅ Smart Animate works
+button-default           →   button-hover             ✅ Works (if exact names match)
+Rectangle 12             →   Rectangle 12             ❌ Accidental match possible
+```
+
+**Smart Animate checklist:**
+- [ ] Layer that should animate has the **exact same name** in both source and destination frame
+- [ ] Layer **types match** — text animates to text, frame to frame
+- [ ] Layers are **not inside renamed groups** between variants
+- [ ] Use `Move in`, `Move out` with direction for panel/sheet transitions
+- [ ] Use `Dissolve` for opacity-only changes (tooltips, overlays)
+- [ ] Use `Smart Animate` for property-based transitions (size, position, color)
+
+### What to Audit in Figma
+When reviewing a Figma prototype with animations:
+- Check variant layer names match exactly if Smart Animate is expected
+- Check that Delay is 0ms unless a stagger is intentional and < 50ms per item
+- Check that prototype connections use the right animation type for the context
+- Flag any animation with duration > 400ms as 🟡 Warning, > 600ms as 🔴 Critical
+
+---
+
+## Reduced Motion: Non-Negotiable
+
+The `prefers-reduced-motion` media query is not optional. Some users have vestibular disorders where moving UI can cause nausea, dizziness, or seizures.
+
+### Required behaviour:
+```css
+@media (prefers-reduced-motion: reduce) {
+  /* Remove or reduce all animations */
+  * {
+    animation-duration: 0.01ms !important;
+    animation-iteration-count: 1 !important;
+    transition-duration: 0.01ms !important;
+  }
+}
+```
+
+### In Figma:
+There is no built-in reduced motion support in Figma prototypes. Flag this as a 🟡 Warning on any Figma audit — note that developers must implement it in code. If the file has a `Motion: Reduced` page or variant, mark it ✅.
+
+### What still works at reduced motion:
+- **Opacity changes**: Fading is generally acceptable (not physical movement)
+- **Color transitions**: Fine
+- **Scroll-based changes**: Use `scroll-behavior: auto` instead of `smooth`
+- **State changes with no movement**: Toggle from off→on with color change, no slide
+
+### What must be removed at reduced motion:
+- Parallax effects
+- Scroll-triggered entrance animations
+- Auto-playing video or GIF backgrounds
+- Bouncing/pulsing attention animations
+- Staggered list animations
+
+---
+
+## Autoplay & Loop Rules
+
+| Type | Rule |
+|---|---|
+| Background video | Pause button required. No audio autoplay. |
+| Looping animation | Stop or pause after 3 loops. Never infinite without user control. |
+| Skeleton screens | OK to loop infinitely — they communicate "loading", stop when content arrives |
+| Loading spinners | OK to loop — clear purpose, user understands it will stop |
+| Celebration confetti | Max 3s, then stop. Never infinite. |
+| Marquee / ticker | Only if user can pause it (WCAG 2.2.2) |
+
+**WCAG 2.2.2 (Pause, Stop, Hide):** Any moving, blinking, or scrolling content that (1) starts automatically, (2) lasts more than 5 seconds, and (3) is presented in parallel with other content — must have a mechanism to pause, stop, or hide it.
+
+---
+
+## Stagger Animations
+
+Staggered list item animations (each item enters slightly after the last) can work well if:
+- Total stagger duration < 300ms
+- Per-item delay: 30–50ms
+- Only on first load, not every state change
+
+```
+Item 1: delay 0ms
+Item 2: delay 40ms
+Item 3: delay 80ms
+Item 4: delay 120ms (total: 120ms + duration ≈ fine)
+Item 8: delay 280ms (total: 280ms + duration ≈ borderline)
+Item 15: delay 560ms (total: 560ms + duration ≈ 🔴 too slow)
+```
+
+---
+
+## Animation Anti-Patterns
+
+| Anti-pattern | Problem | Fix |
+|---|---|---|
+| Loading spinner on < 1s operations | Creates perceived slowness | Show spinner only after 300ms delay |
+| Entrance animation on every page load | Gets annoying after first visit | One-time or skip-if-visited |
+| Simultaneous animations on multiple elements | Overwhelming, hard to track | Sequence or stagger with clear hierarchy |
+| Hover animation with no click confirmation | User can't tell if action worked | Add a distinct pressed state |
+| Long exit animation on dismissed content | User waits for content they don't want | Exit animations should be shorter than entrances |
+| Scale > 105% on hover | Feels aggressive | Keep scale hover to 101–103% |
+
+---
+
+## Severity Guide for Cat 8
+
+| Issue | Severity |
+|---|---|
+| No reduced motion support (code) | 🔴 Critical |
+| Animation > 600ms | 🔴 Critical |
+| Infinite autoplay loop with no pause | 🟡 Warning |
+| Wrong easing (ease-in on entrance) | 🟡 Warning |
+| Animation with no purpose (pure decoration) | 🟡 Warning |
+| Total stagger > 400ms | 🟡 Warning |
+| Animation > 300ms (shorter than 600ms) | 🟢 Tip |
+| Spring easing used too liberally | 🟢 Tip |
+| No Smart Animate naming convention | 🟢 Tip (Figma only) |
+
+---
+
+## Code-Specific Animation Checks
+
+When auditing CSS/React/Vue animation code, check these directly.
+
+### prefers-reduced-motion
+```
+This is the single most important code check for Cat 8. Run automatically.
+
+Detection:
+  → Search for @media (prefers-reduced-motion: reduce) in all CSS and styled-components
+  → Search for useReducedMotion() hook (Framer Motion), or equivalent
+
+If any transition: or animation: declaration exists AND no reduced-motion query found:
+  → 🔴 Critical
+
+Correct global pattern:
+  @media (prefers-reduced-motion: reduce) {
+    *, *::before, *::after {
+      animation-duration: 0.01ms !important;
+      animation-iteration-count: 1 !important;
+      transition-duration: 0.01ms !important;
+      scroll-behavior: auto !important;
+    }
+  }
+
+Also acceptable (targeted, not global):
+  @media (prefers-reduced-motion: reduce) {
+    .card { transition: none; }
+    .modal { animation: none; }
+  }
+```
+
+### Duration values
+```
+Collect all transition-duration and animation-duration values in ms.
+
+> 600ms on any UI interaction → 🔴 Critical (feels broken/sluggish)
+300–600ms on UI interaction → 🟡 Warning (check if intentional for page-level)
+150–300ms on UI interaction → ✅ ideal range
+< 100ms on any transition → 🟢 Tip (may be imperceptible — intentional?)
+
+Page transitions (route changes): 300–500ms → ✅
+Loading/progress animations: any duration → ✅ (exempt from UI duration rule)
+```
+
+### Easing
+```
+Collect all transition-timing-function and animation-timing-function values.
+
+linear on any interactive element transition → 🟡
+  (linear feels mechanical — use ease-out for entrances, ease-in for exits)
+
+ease-in on entrance animations → 🟡
+  (starts slow, speeds up — feels like it arrives late)
+
+ease-out on entrance animations → ✅
+ease-in on exit animations → ✅
+ease-in-out on transitions → ✅ (symmetric — fine for hover states)
+
+cubic-bezier values: check if they approximate ease-in or ease-out
+  → cubic-bezier(0, 0, 0.2, 1)  = ease-out → ✅
+  → cubic-bezier(0.4, 0, 1, 1)  = ease-in  → ✅ for exits
+  → cubic-bezier(0, 0, 1, 1)    = linear   → 🟡
+```
+
+### Infinite loops
+```
+animation-iteration-count: infinite:
+  → On a background/decorative element with no user control → 🟡 Warning
+  → On a loading spinner → ✅ (expected)
+  → On a skeleton shimmer → ✅ (expected)
+  → On a marquee/ticker → 🟡 (distraction — should pause on hover/focus)
+
+animation-play-state: paused on :hover / :focus → ✅ (infinite loop with pause = acceptable)
+```
+
+### transition: all
+```
+transition: all [duration] → 🟡 Warning
+  Reason: Animates every CSS property including layout properties (width, height, padding),
+  which causes expensive layout recalculations and jank.
+
+Preferred: specify only the properties you need:
+  transition: color 200ms ease-out, background-color 200ms ease-out;
+  transition: transform 250ms ease-out, opacity 250ms ease-out;
+
+High-performance properties (GPU-composited, no layout cost):
+  transform, opacity → ✅ always prefer these
+  color, background-color, box-shadow, border-color → ✅ acceptable (paint only)
+  width, height, padding, margin, top, left → 🟡 (trigger layout — avoid animating)
+```
+
+### Framer Motion / React Spring specific
+```
+If Framer Motion detected (import { motion } from 'framer-motion'):
+  → Check for useReducedMotion() hook used to conditionally disable animations → ✅
+  → AnimatePresence without reduced motion fallback → 🟡
+  → variants with duration > 0.6s → 🟡 (same threshold in seconds)
+  → staggerChildren > 0.1s × item count > 400ms total → 🟡
+
+If React Spring detected:
+  → config.slow or tension < 100 (slow animations) → 🟡 check intent
+  → No reduced motion handling → 🟡
+```