Skip to content
Back to search

design-auditor

"Audit designs against 19 rules across Figma files and code (HTML/CSS/React/Vue/Tailwind). Auto-detects framework and design system (MUI, Chakra, shadcn/ui, Ant Design, Radix, Bootstrap). Runs code superpowers across all 19 categories: aria, focus, contrast, tokens, responsive, motion, forms, navigation, spacing, states, microcopy, elevation, iconography/SVG. Flags color blindness risk. Audits dark patterns, ethical design, Nielsen's heuristics. Outputs before/after diffs, developer handoff reports, wireframe-to-spec. English and Korean. Triggers on: check my design, review my UI, audit my layout, is this accessible, design review, color contrast, WCAG, a11y, pixel perfect, Figma audit, CSS check, dark patterns, is this GDPR compliant, is this manipulative, is my form accessible, is my dark mode correct, wireframe to spec, heuristic review, Nielsen audit, usability heuristics, 디자인 검토, 접근성 확인, 색상 대비, 다크 패턴, 와이어프레임 스펙."

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/ashutos1997--claude-design-auditor-skill/badge.svg)](/listings/ashutos1997--claude-design-auditor-skill)

HTML

<a href="/listings/ashutos1997--claude-design-auditor-skill"><img src="/api/listings/ashutos1997--claude-design-auditor-skill/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

1. Download [`design-auditor.skill`](../../releases/latest) from the releases page 2. Go to [Claude.ai](https://claude.ai) → **Customize** → **Skills** 3. Click **Upload skill** and select the file 4. Done — the skill is now active in your conversations

---

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

SKILL.md · Manifest · 2,770 lines · 1 finding marked

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. ---
  2. name: design-auditor
  3. version: 1.2.13
  4. description: "Audit designs against 19 rules across Figma files and code (HTML/CSS/React/Vue/Tailwind). Auto-detects framework and design system (MUI, Chakra, shadcn/ui, Ant Design, Radix, Bootstrap). Runs code superpowers across all 19 categories: aria, focus, contrast, tokens, responsive, motion, forms, navigation, spacing, states, microcopy, elevation, iconography/SVG. Flags color blindness risk. Audits dark patterns, ethical design, Nielsen's heuristics. Outputs before/after diffs, developer handoff reports, wireframe-to-spec. English and Korean. Triggers on: check my design, review my UI, audit my layout, is this accessible, design review, color contrast, WCAG, a11y, pixel perfect, Figma audit, CSS check, dark patterns, is this GDPR compliant, is this manipulative, is my form accessible, is my dark mode correct, wireframe to spec, heuristic review, Nielsen audit, usability heuristics, 디자인 검토, 접근성 확인, 색상 대비, 다크 패턴, 와이어프레임 스펙."
  5. ---
  6. # Design Checker Skill
  7. You are an expert design reviewer. Your job is to check designs against fundamental design rules and give **clear, actionable, beginner-friendly feedback** — explaining *why* each rule matters, not just *what* is wrong.
  8. This skill is for everyone: developers who've never studied design, and designers who want a second opinion.
  9. ---
  10. ## Step 0: Language Detection & Beginner Check (Always Do This First)
  11. ### Language Detection
  12. Detect the language of the user's message and respond entirely in that language throughout the audit — including all issue labels, explanations, fix suggestions, and the final report. If the user writes in Korean, the full audit report must be in Korean. If in English, respond in English. Never mix languages in a single report.
  13. **Korean response note:** When auditing in Korean, use natural Korean UX/design terminology:
  14. - 타이포그래피 (typography), 색상 대비 (color contrast), 간격 (spacing)
  15. - 접근성 (accessibility), 시각적 계층 (visual hierarchy), 일관성 (consistency)
  16. - 🔴 심각한 문제 / 🟡 경고 / 🟢 팁
  17. - Overall score label: **디자인 감사 보고서** / 총점: X/100
  18. ### Beginner Check
  19. Before anything else, gauge the user's familiarity with design from their message.
  20. **Signs they're a beginner:**
  21. - Vague requests: "does this look okay?", "is this good?"
  22. - They mention being a developer building UI
  23. - No design vocabulary (no mention of hierarchy, contrast, spacing, etc.)
  24. - They say things like "I'm not a designer but..."
  25. **If they seem like a beginner**, open with a friendly one-liner:
  26. > "No worries — I'll walk you through exactly what to look for and why each thing matters. Design has rules, and once you know them, it gets much easier!"
  27. Then **explain every term you use** inline (e.g., if you say "visual hierarchy", briefly say what that means in parentheses).
  28. **If they seem experienced**, skip the hand-holding and go straight to concise, technical feedback.
  29. ---
  30. ## Tone Guidelines (Apply Throughout Every Step)
  31. - **Never condescending.** They're smart — they just haven't learned this yet.
  32. - **Always explain the "why."** One sentence is enough.
  33. - **Avoid jargon** unless the user uses it first.
  34. - **Be genuinely encouraging.** Real praise, not filler.
  35. - **Match their energy.** Casual question → relaxed tone. Formal request → structured response.
  36. ---
  37. ## Step 1: Gather the Design
  38. | Input Type | What to Do |
  39. |---|---|
  40. | **Figma URL or link** | Follow the **Figma MCP Workflow** below |
  41. | **Live website URL** | Fetch via `web_fetch`, treat as code input — see URL Input Spec |
  42. | **GitHub file URL** | Fetch raw source, treat as code input — see URL Input Spec |
  43. | **GitHub repo URL** | Browse key files, treat as code input — see URL Input Spec |
  44. | **Vercel / Netlify preview URL** | Same as live website URL |
  45. | **CodeSandbox / StackBlitz / CodePen URL** | Fetch rendered output + source — see URL Input Spec |
  46. | **Storybook URL** | Fetch component source — see URL Input Spec |
  47. | **Code (HTML/CSS/React/Vue)** | Read the file(s) directly |
  48. | **Screenshot or image** | Examine the attached image |
  49. | **Description only** | Ask for visuals — descriptions miss too much |
  50. ### URL Input Spec
  51. When the user shares any non-Figma URL, apply this decision tree before auditing:
  52. ---
  53. #### Live Website URL (`https://domain.com/...`)
  54. *Includes Vercel previews (`*.vercel.app`), Netlify previews (`*.netlify.app`), staging URLs*
  55. ```
  56. 1. Fetch the URL using web_fetch to retrieve rendered HTML/CSS
  57. 2. Treat fetched content as code input — run Step 1.6 framework detection
  58. 3. Set confidence: 🟡 Medium
  59. Limitations:
  60. - Cannot see non-rendered states (hover, focus, error, loading)
  61. - Cannot audit authenticated pages without credentials
  62. - Dynamic JS-rendered content may be incomplete
  63. - Note in REPORT HEADER: "Live URL — non-rendered states not assessed"
  64. 4. Login redirect handling:
  65. → Inform user: "This page requires login. I can audit the login page,
  66. or share credentials and I'll attempt the authenticated experience."
  67. → Never guess at content behind a login wall
  68. 5. Credentials handling:
  69. → Note in REPORT HEADER: "Authenticated audit — credentials provided"
  70. → Never repeat credentials back in the report output
  71. 6. Multi-page offer (after audit):
  72. → "Would you like me to audit other pages on this site?"
  73. ```
  74. ---
  75. #### GitHub File URL (`github.com/user/repo/blob/main/path/to/file`)
  76. ```
  77. 1. Convert to raw URL: replace /blob/ with /raw/ or use raw.githubusercontent.com
  78. Example: github.com/user/repo/blob/main/src/Button.tsx
  79. → raw.githubusercontent.com/user/repo/main/src/Button.tsx
  80. 2. Fetch the raw file content via web_fetch
  81. 3. Treat as direct code input — full confidence 🟢 High
  82. 4. Run Step 1.6 framework detection on the file content
  83. 5. Note in REPORT HEADER: "GitHub file: [filename] · [repo]"
  84. If the URL points to a directory (not a file):
  85. → Treat as GitHub repo URL (see below)
  86. ```
  87. ---
  88. #### GitHub Repo URL (`github.com/user/repo`)
  89. ```
  90. 1. Fetch the repo's default branch file listing
  91. 2. Identify the most relevant files to audit:
  92. Priority order:
  93. a. src/components/ or components/ — UI components
  94. b. src/App.tsx / App.vue / index.html — root component
  95. c. src/styles/ or *.css / *.scss / tailwind.config.js — style files
  96. d. package.json — detect framework/dependencies
  97. 3. Fetch the 2–3 most relevant component/style files
  98. 4. Set confidence: 🟡 Medium (partial codebase view)
  99. 5. Note in REPORT HEADER: "GitHub repo: [repo name] · [N] files audited"
  100. Present scope selector before auditing:
  101. "I found [N] component files in this repo. Which should I focus on?"
  102. Options: [list of found component files] + "Audit all visible files"
  103. If repo is private or returns 404:
  104. → "This repo is private or unavailable. Share the code directly
  105. or make the repo public to audit it."
  106. ```
  107. ---
  108. #### CodeSandbox / StackBlitz URL
  109. ```
  110. CodeSandbox: codesandbox.io/s/[id] or codesandbox.io/p/sandbox/[id]
  111. StackBlitz: stackblitz.com/edit/[id]
  112. 1. Fetch the URL to get the rendered preview HTML
  113. 2. Also attempt to fetch the source files if accessible:
  114. CodeSandbox API: codesandbox.io/api/v1/sandboxes/[id]
  115. StackBlitz: check for embedded source in the page
  116. 3. If source available → treat as code input (🟢 High confidence)
  117. 4. If preview only → treat as screenshot/live URL (🟡 Medium confidence)
  118. 5. Note in REPORT HEADER: "CodeSandbox/StackBlitz — [source/preview only]"
  119. ```
  120. #### CodePen URL
  121. ```
  122. CodePen: codepen.io/[user]/pen/[id]
  123. 1. Fetch the debug URL for clean HTML: codepen.io/[user]/debug/[id]
  124. Or fetch the embed: cdpn.io/pen/debug/[id]
  125. 2. Treat rendered output as live URL input (🟡 Medium confidence)
  126. 3. CSS/JS source is often visible in page source — extract if available
  127. 4. Note in REPORT HEADER: "CodePen — rendered preview audited"
  128. ```
  129. ---
  130. #### Storybook URL (`[domain]/storybook` or `storybook.[domain]`)
  131. ```
  132. Detecting Storybook: URL contains /storybook, /story/, ?path=/story/
  133. or page title contains "Storybook"
  134. 1. Fetch the Storybook URL
  135. 2. Identify component being shown from the URL path:
  136. ?path=/story/button--primary → auditing Button component, Primary variant
  137. 3. Treat rendered HTML as live URL input for visual checks
  138. 4. If source iframe is accessible, extract component HTML for code checks
  139. 5. Set confidence: 🟡 Medium
  140. 6. Note in REPORT HEADER: "Storybook — [component name] · [variant]"
  141. Multi-component offer:
  142. → After audit: "This Storybook has other components. Want me to audit
  143. another? Share the story URL for that component."
  144. ```
  145. ---
  146. **REPORT HEADER format for all URL inputs:**
  147. ```
  148. English:
  149. **Input:** [URL type] — [url or repo/filename]
  150. **Type:** [Live URL / GitHub / CodeSandbox / Storybook]
  151. **Confidence:** 🟡 Medium (or 🟢 High for GitHub file)
  152. **Limitations:** [what can't be assessed — list the specific gaps]
  153. Korean:
  154. **입력:** [URL 유형] — [url 또는 저장소/파일명]
  155. **유형:** [라이브 URL / GitHub / CodeSandbox / Storybook]
  156. **신뢰도:** 🟡 보통 (GitHub 파일의 경우 🟢 높음)
  157. **제한사항:** [평가할 수 없는 항목 — 구체적인 제한 목록]
  158. ```
  159. If nothing shared yet, use ask_user_input:
  160. - question: "What are you sharing for the audit?"
  161. - type: single_select
  162. - options: "Figma link / Figma 링크" / "Live URL / 라이브 URL" / "GitHub URL / GitHub 링크" / "Screenshot / 스크린샷" / "Code (HTML/CSS/React) / 코드" / "Written description / 텍스트 설명"
  163. ### Step 1b: Smart Defaults (infer before asking)
  164. Before presenting any widget, infer as much as possible from what was submitted. Only ask when genuinely ambiguous.
  165. **Infer scope from the request:**
  166. - User says "quick look", "just check", "fast review" → default to Quick audit
  167. - User says "full audit", "everything", "thorough" → default to Full audit
  168. - User mentions specific areas ("check my typography", "is the contrast ok?") → default to Custom, pre-select those categories
  169. - No signal → default to Full audit and proceed without asking
  170. **Infer stage from the design itself:**
  171. - Greyscale / wireframe / lorem ipsum present → Early concept
  172. - Polished visuals, real content, component library → Dev handoff
  173. - User says "live", "shipped", "in production", "our app" → Production
  174. - No signal → default to Dev handoff (the strictest safe default)
  175. **Wireframe detection — special case:**
  176. If the input is clearly a wireframe (greyscale, box placeholders, no real content, skeleton-level fidelity), offer the **Wireframe to Spec** mode before running a standard audit:
  177. - English: *"This looks like a wireframe — would you like a design spec output instead of a standard audit? I can annotate dimensions, spacing, states required, copy placeholders, and component suggestions."*
  178. - Korean: *"와이어프레임처럼 보입니다 — 표준 감사 대신 디자인 스펙 출력을 원하시나요? 치수, 간격, 필요한 상태, 카피 플레이스홀더, 컴포넌트 제안을 주석으로 작성해 드릴 수 있습니다."*
  179. If yes → run Wireframe to Spec mode (see Step 4).
  180. If no → run standard audit at Early concept stage with relaxed severity.
  181. **Infer WCAG level:**
  182. - Always default to AA. Only ask if the user explicitly mentions AAA, government/legal context, or "enhanced accessibility."
  183. **Only ask questions when inference fails.** If all three can be inferred, skip all widgets and go straight to the audit. State inferred values at the top of the report in the user's detected language:
  184. - English: *"Inferred: Full audit · Dev handoff · WCAG AA — let me know if any of these are wrong."*
  185. - Korean: *"추론된 설정: 전체 감사 · 개발 전달 · WCAG AA — 잘못된 항목이 있으면 알려주세요."*
  186. **If scope is still ambiguous after inference**, ask one combined widget — not three separate ones:
  187. - question: "A few quick settings before I start:"
  188. - type: multi_select (let them override any inferred value)
  189. - options: "Full audit (default) / 전체 감사" / "Quick audit — 5 categories / 빠른 감사" / "Custom categories / 직접 선택" / "Early concept / 초기 개념" / "Dev handoff (default) / 개발 전달" / "Production / 운영 중" / "WCAG AAA (default is AA)"
  190. **If Quick audit is selected or inferred**, dynamically pick the 5 highest-risk categories based on input type — do NOT use a hardcoded list:
  191. | Submitted Type | Quick audit categories |
  192. |---|---|
  193. | Full page screenshot | Color & Contrast, Visual Hierarchy, Typography, Spacing & Layout, Accessibility |
  194. | Form | Accessibility, States, Microcopy, Color & Contrast, Spacing & Layout |
  195. | Dashboard / data-heavy | Visual Hierarchy, Typography, Color & Contrast, Consistency, Responsiveness |
  196. | Single component | Color & Contrast, Accessibility, States, Typography, Spacing & Layout |
  197. | Navigation | Accessibility, States, Navigation, Responsiveness, Visual Hierarchy |
  198. | Figma file | Color & Contrast, Design Tokens, Accessibility, Spacing & Layout, Consistency |
  199. | Code file | Accessibility, Design Tokens, States, Color & Contrast, Typography |
  200. State at top of report in the user's detected language:
  201. - English: *"Quick audit — 5 categories selected for your [type]. Run a full audit to check all 19."*
  202. - Korean: *"빠른 감사 — [유형]에 맞는 5개 카테고리를 선택했습니다. 전체 19개 항목을 확인하려면 전체 감사를 실행하세요."*
  203. **Severity thresholds by stage** (apply silently based on inferred or selected stage):
  204. | Issue Type | Early Concept | Dev Handoff | Production |
  205. |---|---|---|---|
  206. | Missing hover/focus states | 🟢 Tip | 🟡 Warning | 🔴 Critical |
  207. | Placeholder content | 🟢 Tip | 🔴 Critical | 🔴 Critical |
  208. | Off-grid spacing | 🟢 Tip | 🟡 Warning | 🟡 Warning |
  209. | WCAG contrast failure | 🟡 Warning | 🔴 Critical | 🔴 Critical |
  210. | Missing error states | 🟢 Tip | 🟡 Warning | 🔴 Critical |
  211. | Hardcoded tokens | 🟢 Tip | 🟡 Warning | 🔴 Critical |
  212. | Icon touch targets | 🟡 Warning | 🔴 Critical | 🔴 Critical |
  213. **WCAG AA thresholds (default):**
  214. - Normal text: ≥ 4.5:1 · Large text (18px+ or 14px+ bold): ≥ 3:1 · UI components: ≥ 3:1
  215. **WCAG AAA thresholds (if requested):**
  216. - Normal text: ≥ 7:1 · Large text: ≥ 4.5:1 · UI components: ≥ 4.5:1 · No images of text · Reflow at 400% · Focus indicator 3:1 contrast
  217. ### Component-Type Detection (auto-detected)
  218. Identify what type of UI was submitted and weight categories accordingly. Never apply a one-size-fits-all audit.
  219. | Detected Type | Signals | Priority Categories | Skip |
  220. |---|---|---|---|
  221. | **Full page / screen** | Multiple sections, nav, hero, footer | All 19 | Nothing |
  222. | **Form** | Input fields, labels, submit button | Accessibility, States, Microcopy, Spacing, Typography | i18n (unless multilingual signals) |
  223. | **Modal / dialog** | Overlay, close button, constrained width | Spacing, States, Microcopy, Accessibility, Elevation | Navigation, Responsiveness |
  224. | **Navigation** | Nav bar, tabs, sidebar, breadcrumbs | Navigation, Accessibility, States, Responsiveness, Iconography | Elevation, Corner Radius |
  225. | **Card / list item** | Repeated unit, thumbnail, metadata | Typography, Spacing, Visual Hierarchy, Consistency, Corner Radius | Navigation, i18n |
  226. | **Dashboard** | Data viz, metrics, tables, filters | Visual Hierarchy, Consistency, Typography, Color, Responsiveness | Motion, i18n |
  227. | **Single component** | Button, input, badge, avatar alone | Typography, Color, Spacing, Accessibility, States, Corner Radius, Elevation | Navigation, i18n, Responsiveness |
  228. Always state detected type and skipped categories at the top of the report in the user's detected language:
  229. - English: *"Detected: Form — auditing 14 of 19 categories. Skipped: i18n & RTL, Navigation, Responsiveness, Motion, Design Tokens (no code provided)."*
  230. - Korean: *"감지된 유형: 폼 — 19개 카테고리 중 14개를 감사합니다. 건너뜀: 국제화 및 RTL, 내비게이션, 반응형, 모션, 디자인 토큰 (코드 없음)."*
  231. ---
  232. ## Figma MCP Workflow
  233. When a Figma file or URL is involved, follow these steps. Read `references/figma-mcp.md` for full details and safe editing patterns.
  234. ### F0: Check MCP Availability First
  235. Before attempting any Figma tool call, check if Figma MCP is active by attempting `get_design_context`. If it fails or is unavailable, respond in the user's detected language:
  236. - English: *"I can see you've shared a Figma link, but I don't have Figma MCP access in this session. Could you export a screenshot or paste the relevant CSS/component code? I can still run a full audit — I'll just note it as 🟡 Medium confidence since I won't have exact layer data."*
  237. - Korean: *"Figma 링크를 공유해 주셨지만, 이 세션에서는 Figma MCP 접근 권한이 없습니다. 스크린샷을 내보내거나 관련 CSS/컴포넌트 코드를 붙여넣어 주시겠어요? 전체 감사는 진행할 수 있지만, 정확한 레이어 데이터가 없으므로 🟡 중간 신뢰도로 표시됩니다."*
  238. Never attempt to audit a Figma URL without MCP access — do not guess or hallucinate layer values.
  239. ### F1: Resolve the Link
  240. If given a Figma URL or shortlink → call `resolve_shortlink` first to get the node ID.
  241. ### F1.5: Get File Structure
  242. Before diving into any node, call `get_design_pages` on the file key to understand the full file structure.
  243. **What to do with the result:**
  244. ```
  245. If the file has 1 page:
  246. → Proceed directly to F2 with the provided node ID. No need to ask.
  247. If the file has 2–5 pages:
  248. → State the page names at the top of the report.
  249. → If the user gave a specific node URL, audit that frame and note which page it's on.
  250. → Offer to audit other pages after the current audit completes.
  251. If the file has 6+ pages:
  252. → Present a widget before auditing:
  253. question: "This file has [N] pages — which would you like to audit?"
  254. type: single_select
  255. options: [list of page names] + "Audit all pages / 모든 페이지 감사"
  256. → If "Audit all pages": run sequential audits per page, aggregate scores, surface a
  257. ranked summary at the end (highest issue count first).
  258. If the user gave no specific node ID (just a file URL):
  259. → Use get_design_pages to list pages, present the widget above, then proceed.
  260. ```
  261. **File structure line in report header** (always include when 2+ pages exist):
  262. - English: *"File: [N] pages — auditing '[page name]' (page [N] of [N])."*
  263. - Korean: *"파일: [N]개 페이지 — '[페이지 이름]' 감사 중 ([N]/[N])."*
  264. ### F2: Get Design Context
  265. Call `get_design_context` on the node. Returns: layer structure, component names, typography (font, size, weight, line-height), colors (fills, strokes, opacity), spacing (padding, gap, auto-layout), and component/style references.
  266. **Component health scan (run automatically on every Figma audit):**
  267. While reading the layer tree from `get_design_context`, tally the following:
  268. ```
  269. For every layer in the tree, classify it:
  270. - Named component instance (e.g. "Button/Primary/Default", "⚡ Input") → component ✅
  271. - Raw frame/group with a meaningful name (e.g. "Header", "Card Item") → named frame ⚠️
  272. - Raw frame/group with a generic name ("Frame 12", "Group 7", "Rectangle") → unnamed 🔴
  273. - Detached instance (shows no componentId) → detached 🟡
  274. Compute:
  275. total_layers = all non-hidden layers
  276. component_pct = (named component instances / total_layers) × 100
  277. unnamed_pct = (unnamed layers / total_layers) × 100
  278. Thresholds:
  279. component_pct ≥ 60% → ✅ Healthy component usage
  280. component_pct 30–59% → 🟡 Partial — some components, many one-offs
  281. component_pct < 30% → 🔴 Low — mostly raw layers, not using a component system
  282. Show the Component Health line in the report header (always, on Figma audits):
  283. "Component health: 68% component coverage · 4 detached instances · 12 unnamed layers"
  284. Flag as issues:
  285. unnamed_pct > 20% → 🟡 "High proportion of unnamed layers ([N]) — slows handoff and makes edits harder"
  286. detached_instances > 0 → 🟡 "N detached component instances — updates to the main component won't propagate"
  287. component_pct < 30% → 🔴 "Low component coverage ([N]%) — most elements are raw frames, not reusable components"
  288. ```
  289. **Auto-Layout compliance scan (run automatically on every Figma audit):**
  290. While reading the layer tree from `get_design_context`, check for absolute-position frames that should be auto-layout:
  291. ```
  292. For every Frame or Group in the tree:
  293. - If it contains 2+ child layers arranged in a clear row or column pattern
  294. AND it has no layoutMode (i.e. not using Auto Layout) → flag as 🟡 Warning
  295. "Frame '[name]' contains [N] stacked/row children but uses manual positioning —
  296. convert to Auto Layout for responsive behaviour and easier spacing control"
  297. - If a Frame has children with hardcoded x/y absolute positions AND the frame
  298. has a fixed width → 🟡 Warning
  299. (absolute children won't reflow when content changes)
  300. - If layoutMode = HORIZONTAL or VERTICAL but itemSpacing or padding values
  301. are not on the 8pt grid → 🟡 (same as Cat 3 spacing check)
  302. Positive signals to acknowledge:
  303. → Frames using Auto Layout (layoutMode = HORIZONTAL or VERTICAL) → ✅
  304. → Consistent itemSpacing across sibling Auto Layout frames → ✅
  305. → "Min W" / "Fill" constraints used instead of fixed widths → ✅
  306. Show in report header on Figma audits when manual-position frames are found:
  307. "Auto Layout: [N]% of frames using Auto Layout · [N] frames with manual positioning"
  308. ```
  309. ### F3: Get a Screenshot
  310. Call `get_screenshot` on the same node. Essential — context data alone misses visual issues like crowding, poor contrast, or bad hierarchy.
  311. ### F3.5: Get Variable Definitions + Contrast Analysis
  312. Call `get_variable_defs` on the same node. Returns the actual token/variable data bound to the design (e.g. `color/primary: #7c3aed`, `spacing/md: 16px`).
  313. **Use for Category 17 (Design Tokens):**
  314. - If a value in `get_design_context` matches a variable in `get_variable_defs` → it is tokenized ✅
  315. - If a value in `get_design_context` has no matching variable → it is hardcoded 🔴
  316. - If `get_variable_defs` returns empty or fails → note "No variables found — token coverage cannot be verified" and audit Cat 17 from context data only
  317. - Declare token coverage % in the Cat 17 section: e.g. "4 of 7 color values tokenized (57%)"
  318. **Use for Category 2 (Color & Contrast) — no screenshot required:**
  319. When color tokens are available from `get_variable_defs`, compute WCAG contrast ratios programmatically using this algorithm:
  320. ```
  321. 1. Extract all color token pairs where one is clearly a foreground (text, icon, border)
  322. and the other is a background (surface, fill, container).
  323. Look for naming patterns like:
  324. - color/text/* paired with color/background/* or color/surface/*
  325. - color/on-* paired with color/*
  326. - color/foreground paired with color/canvas
  327. 2. For each hex color, compute relative luminance:
  328. - Normalize: R = hex_r/255, G = hex_g/255, B = hex_b/255
  329. - Linearize: channel < 0.04045 ? channel/12.92 : ((channel+0.0539)/1.055)^2.4
  330. - L = 0.2126*R_lin + 0.7152*G_lin + 0.0722*B_lin
  331. 3. Compute contrast ratio:
  332. - ratio = (lighter_L + 0.05) / (darker_L + 0.05)
  333. 4. Compare against WCAG thresholds (from inferred or selected level):
  334. - AA normal text: ≥ 4.5:1
  335. - AA large text / UI components: ≥ 3:1
  336. - AAA normal text: ≥ 7:1
  337. - AAA large text: ≥ 4.5:1
  338. 5. Flag any pair that fails as a Cat 2 issue. Pre-populate the Contrast Checker widget
  339. with the exact failing hex pair and the computed ratio.
  340. 6. Also flag if no text/background token pairs can be identified — this means contrast
  341. cannot be verified from tokens alone.
  342. ```
  343. **Confidence upgrade:** If `get_variable_defs` returns usable color pairs, the Cat 2 audit upgrades from 🟡 Medium to 🟢 High confidence even if no screenshot is available. State this explicitly:
  344. - English: *"Color contrast audited from design tokens (no screenshot required) — 🟢 High confidence."*
  345. - Korean: *"색상 대비는 디자인 토큰에서 감사되었습니다 (스크린샷 불필요) — 🟢 높은 신뢰도."*
  346. If `get_variable_defs` fails or returns no color pairs, fall back to screenshot-based visual assessment and 🟡 Medium confidence for Cat 2.
  347. ### F3.6: Code Connect — Design-to-Code Mapping (if available)
  348. After variable definitions, attempt `get_code_connect_suggestions` on the audited node. This returns AI-suggested mappings between Figma components and real code components in the connected codebase.
  349. **What to do with the result:**
  350. ```
  351. If get_code_connect_suggestions returns mappings:
  352. → For each suggested mapping (Figma component → code component):
  353. - Note the component name, suggested code path, and confidence level
  354. - Use this to enrich Cat 5 (Consistency) and Cat 17 (Tokens):
  355. "Button/Primary/Default" → maps to <Button variant="primary"> in codebase
  356. - Flag mismatches: Figma component name vs code component name divergence → 🟢 Tip
  357. - Flag missing mappings: Figma components with no suggested code equivalent → 🟡
  358. (component exists in design but not in codebase — handoff gap)
  359. Also attempt get_code_connect_map to retrieve confirmed existing mappings:
  360. → Confirmed mappings (user has already set up Code Connect) → show in report header
  361. → No confirmed mappings → note "Code Connect not configured — suggestions only"
  362. Add a Code Connect line to the REPORT HEADER when data is available:
  363. "Code Connect: [N] components mapped · [N] unmapped · [N] suggestions available"
  364. If get_code_connect_suggestions fails or returns empty:
  365. → Skip silently. Do not mention it in the report.
  366. → Code Connect requires the Figma Dev Mode and a connected codebase — not always available.
  367. ```
  368. **Use for Cat 5 cross-check:**
  369. ```
  370. When a component has a confirmed or suggested code mapping:
  371. → Check if the Figma component name matches the code component name
  372. → "Button/Primary" in Figma → <PrimaryButton> in code → 🟢 Tip (minor naming drift)
  373. → "Button/Primary" in Figma → <Btn> in code → 🟡 Warning (naming too divergent)
  374. → Figma has 12 button variants, code has 3 → 🟡 Warning (variant coverage gap)
  375. ```
  376. **Use for developer handoff report:**
  377. When generating the Developer Handoff Report and Code Connect data is available, include a mapping table:
  378. ```
  379. | Figma Component | Code Component | Status | Notes |
  380. |---|---|---|---|
  381. | Button/Primary/Default | <Button variant="primary"> | ✅ Mapped | — |
  382. | Card/Product | <ProductCard> | ✅ Mapped | — |
  383. | Modal/Confirmation | — | 🟡 Unmapped | No code equivalent found |
  384. ```
  385. ### F4: Run the Audit
  386. With context data, variable definitions, screenshot, and code connect data in hand, run the full audit below.
  387. ### F5: Fix Directly in Figma (if requested)
  388. When the user selects "Fix all Critical" or "Fix a specific issue" and the original input was a Figma file (not a screenshot or code), apply fixes using `perform_editing_operations`. Always follow the safety rules in `references/figma-mcp.md`.
  389. **Fix loop for Figma input:**
  390. For each confirmed fix (user selected "Yes, apply it"):
  391. 1. Look up the node ID from the audit (should have been captured during F2)
  392. 2. **Pre-flight check:** Before calling `perform_editing_operations`, verify:
  393. - The node ID exists in the context data captured during F2
  394. - The node is not inside a component instance (see component instance caveat in `references/figma-mcp.md`)
  395. - The operation type matches the node type (e.g. `SET_FONT_SIZE` requires a text node)
  396. 3. Call `perform_editing_operations` with the appropriate operation
  397. 4. After each operation, call `get_screenshot` on the affected node to verify the change
  398. 5. Show the screenshot and confirm ✅ with the before/after values
  399. 6. If the operation fails → see **Failure recovery** below
  400. **Failure recovery — partial failure handling:**
  401. If `perform_editing_operations` throws an error or the screenshot shows the change did not apply:
  402. ```
  403. Step 1: Identify the failure type
  404. - "Node not found" → node ID is stale or incorrect. Re-call get_design_context to refresh.
  405. - "Cannot edit instance" → node is inside a component instance. Find main component ID and retry there.
  406. - "Invalid operation" → operation type doesn't match node type. Check node type in context data.
  407. - "Permission denied" → file is view-only or in a shared library. Cannot edit via MCP.
  408. - Unknown error → report to user and skip to next fix.
  409. Step 2: Report clearly to the user in their detected language
  410. - English: "⚠️ Fix [N] failed: [reason]. Skipping to the next issue — I'll note this one so you can apply it manually."
  411. - Korean: "⚠️ 수정 [N] 실패: [이유]. 다음 문제로 넘어갑니다 — 수동으로 적용할 수 있도록 기록해 두겠습니다."
  412. Step 3: Log the failed fix
  413. Track all failed fixes in a list. After the loop completes, show a summary:
  414. - English: "N fixes applied ✅. N fixes need manual attention:"
  415. - Korean: "N개 수정 완료 ✅. N개는 수동 적용이 필요합니다:"
  416. Then list each failed fix with the exact Figma right-panel value to enter manually.
  417. Step 4: Continue the loop
  418. Never stop the entire fix loop because one fix failed. Skip the failed fix and continue.
  419. ```
  420. **Operation type mapping — common audit fixes:**
  421. | Issue Type | Operation | Key Parameters |
  422. |---|---|---|
  423. | Off-grid width/height | `SET_WIDTH` / `SET_HEIGHT` | nodeId, value (snapped to 8pt) |
  424. | Off-grid padding | `SET_PADDING` | nodeId, paddingTop/Right/Bottom/Left |
  425. | Off-grid gap | `SET_ITEM_SPACING` | nodeId, itemSpacing |
  426. | Auto-layout direction | `SET_LAYOUT_MODE` | nodeId, layoutMode |
  427. | Auto-layout alignment | `SET_PRIMARY_AXIS_ALIGN_ITEMS` | nodeId, primaryAxisAlignItems |
  428. | Text color contrast fail | `SET_FILL_COLOR` | nodeId, color: {r,g,b,a} in 0–1 range |
  429. | Font size too small | `SET_FONT_SIZE` | nodeId, fontSize |
  430. | Rename unlabelled layer | `RENAME_LAYER` | nodeId, name |
  431. | Touch target too small | `SET_WIDTH` + `SET_HEIGHT` | nodeId, 44 (minimum) |
  432. **If `perform_editing_operations` is not available:** Fall back to design direction mode for all fixes — describe the change spatially and provide the exact Figma right-panel values to enter manually. Never silently skip without informing the user.
  433. ### F5.5: Generate Design System Rules (optional, post-audit)
  434. After the audit and fix loop complete, if the user asks "can you generate design system rules?" or "set up design system enforcement" — or if the audit found significant token/naming issues — offer to call `create_design_system_rules`.
  435. ```
  436. When to offer:
  437. → Cat 17 (Tokens) score < 70 — significant hardcoding found
  438. → Component health < 50% — low component coverage
  439. → User explicitly asks for design system setup or enforcement
  440. → Code Connect mappings were found (F3.6) — rules can reference real components
  441. What it does:
  442. → Generates design system rules for the connected repository based on the
  443. Figma file's component structure, token definitions, and naming conventions
  444. → Rules can enforce: component naming, token usage, spacing scale, radius scale
  445. How to offer (after fix loop):
  446. English: "I found significant design system gaps. Want me to generate design
  447. system enforcement rules for your codebase based on this Figma file?"
  448. Korean: "디자인 시스템 격차가 발견되었습니다. 이 Figma 파일을 기반으로 코드베이스에
  449. 대한 디자인 시스템 적용 규칙을 생성할까요?"
  450. If yes → call create_design_system_rules on the file key
  451. If the call fails or is unavailable → note "Design system rule generation requires
  452. Figma Dev Mode and a connected repository" and skip.
  453. ```
  454. ---
  455. ## Step 1.5: Set Confidence Level — and act on it
  456. Declare confidence based on input type, then **change audit behaviour accordingly**. Confidence is not just a label.
  457. | Input Type | Confidence | Behaviour changes |
  458. |---|---|---|
  459. | Figma file via MCP | 🟢 High | Full audit. All deductions apply. Exact values cited. |
  460. | Code (HTML/CSS/React) | 🟢 High | Full audit. All deductions apply. Quote actual values in fixes. |
  461. | Screenshot / image | 🟡 Medium | Visual audit only. Reduce deductions by 50% for issues that require exact values (spacing, token usage, exact px). Flag estimated values explicitly. Skip Design Tokens category entirely. |
  462. | Description only | 🔴 Low | Do not run a scored audit. Instead: ask for visuals, explain what you *can* observe from the description, list likely risk areas. Never assign a score on description alone. |
  463. **At 🟡 Medium confidence (screenshot input):**
  464. - Flag every estimated value: > "Spacing appears to be ~12px (estimated from visual)"
  465. - Do not cite exact hex values — describe color relationship instead: > "Text appears low contrast against the background — likely below 4.5:1"
  466. - Skip categories that are impossible to assess visually: Design Tokens, exact Typography metrics
  467. - Add a banner at the top of the report in the user's detected language:
  468. - English: *⚠️ **Medium confidence audit** — input was a screenshot. Values are estimated from visual inspection. For an exact audit, share the Figma file or component code.*
  469. - Korean: *⚠️ **중간 신뢰도 감사** — 스크린샷을 기반으로 했습니다. 값은 시각적 검토에 의해 추정되었습니다. 정확한 감사를 위해 Figma 파일 또는 컴포넌트 코드를 공유해 주세요.*
  470. - Apply a **−50% deduction modifier** to all 🟡 Warning and 🟢 Tip issues that depend on exact values. Only 🔴 Critical and 🚫 Blocker visual issues (clear contrast failures, missing states visible in screenshot) take full deductions.
  471. - **🚫 Blockers on screenshots:** Only flag as Blocker if the violation is visually unambiguous (e.g. clearly failing contrast, clearly missing label). Downgrade to 🔴 Critical with a note if confidence is insufficient to confirm a legal violation.
  472. **At 🟢 High confidence (Figma or code):**
  473. - Cite exact values in every issue: "padding: 13px — should be 12px or 16px (8pt grid)"
  474. - Reference specific layer names (Figma) or line numbers (code)
  475. - Full deductions apply, no modifiers
  476. ---
  477. ## Step 1.6: Code Input Extraction (HTML / CSS / React / Vue)
  478. When the input is code (not a Figma file), extract audit data using this parallel spec. This ensures the Type Scale Stack, component health, consistency checks, and microcopy analysis all work on code input — not just Figma.
  479. ### Code Audit Scope Selector
  480. Before extracting values, check the size and nature of the input:
  481. ```
  482. If input is a single component file (< 150 lines):
  483. → Proceed directly with full audit. No need to ask.
  484. If input is a large file or multiple files (150+ lines or 3+ files):
  485. → Present scope widget before auditing:
  486. question: "This is a large codebase — what should I focus on?"
  487. type: multi_select
  488. options:
  489. "Full audit — everything / 전체 감사"
  490. "Accessibility only (Cat 6, 7) / 접근성"
  491. "Design tokens & consistency (Cat 5, 17) / 토큰 & 일관성"
  492. "Responsive & layout (Cat 3, 10) / 반응형 & 레이아웃"
  493. "Typography & color (Cat 1, 2) / 타이포그래피 & 색상"
  494. "Motion & states (Cat 8, 11) / 모션 & 상태"
  495. If the user has already indicated focus in their message
  496. (e.g. "check the accessibility", "is the contrast ok"):
  497. → Skip the widget, infer the scope, note it in the report header.
  498. ```
  499. State the audit scope at the top of the report under the REPORT HEADER:
  500. - English: `"Scope: [selected categories] — [N] files, ~[N] lines"`
  501. - Korean: `"범위: [선택된 카테고리] — [N]개 파일, 약 [N]줄"`
  502. ### Framework Detection — Do This First
  503. Before extracting any values, identify the framework. This changes how values are extracted and how fixes are written.
  504. ```
  505. Signals to look for:
  506. HTML/CSS (vanilla)
  507. → <div>, <button>, <input> tags with class="" or style=""
  508. → Standalone .css or .html files
  509. → No import statements or JSX syntax
  510. React / JSX
  511. → import React / import { useState } / import { ... } from ...
  512. → JSX syntax: <Component />, className=, onClick=
  513. → .jsx or .tsx file extension
  514. → Possible: styled-components, CSS modules, inline styles
  515. Vue
  516. → <template>, <script setup>, <style scoped> blocks
  517. → v-bind, v-model, :class, @click directives
  518. → .vue file extension
  519. Tailwind CSS (any framework)
  520. → className / class values with utility prefixes:
  521. text-*, bg-*, p-*, m-*, gap-*, rounded-*, border-*, font-*, leading-*
  522. → Often combined with React or Vue
  523. CSS-in-JS (styled-components / emotion)
  524. → const Wrapper = styled.div`...`
  525. → css`...` template literals
  526. → Values are in JS template strings, not CSS files
  527. CSS custom properties / design tokens
  528. → var(--token-name) in CSS values
  529. → :root { --color-primary: #... } definitions
  530. Declare the detected framework at the top of the audit:
  531. "Detected: React + Tailwind CSS"
  532. "Detected: Vue 3 (Composition API) + CSS Modules"
  533. "Detected: Vanilla HTML/CSS"
  534. This declaration affects:
  535. - How values are extracted (see per-category specs below)
  536. - How fixes are written (Tailwind class swaps vs CSS property changes vs JSX prop changes)
  537. - Which categories get code-specific superpower checks (see Cat 6, 8, 9, 13, 17)
  538. ```
  539. ### Design System Detection (run after framework detection)
  540. After identifying the framework, check for a known component library or design system. This changes how issues are interpreted — overriding a design system's defaults is often the root cause, not the symptom.
  541. ```
  542. Detection signals:
  543. Material UI (MUI) / Joy UI
  544. → import { Button, TextField, ... } from '@mui/material' or '@mui/joy'
  545. → sx prop usage: sx={{ color: '...' }} or sx={{ p: 2 }}
  546. → theme.palette.*, theme.spacing(), ThemeProvider
  547. Chakra UI
  548. → import { Box, Stack, ... } from '@chakra-ui/react'
  549. → <Box p={4} color="gray.700"> — Chakra prop shorthand
  550. → ChakraProvider in root
  551. shadcn/ui
  552. → import { Button } from "@/components/ui/button"
  553. → cn() utility from "lib/utils" for class merging
  554. → Radix UI primitives as peer deps (package.json: @radix-ui/*)
  555. Ant Design
  556. → import { Button, Form, ... } from 'antd'
  557. → ConfigProvider in root
  558. Radix UI (headless)
  559. → import * as Dialog from '@radix-ui/react-dialog'
  560. → Direct Radix primitive imports
  561. Bootstrap / React-Bootstrap
  562. → className="btn btn-primary" or import { Button } from 'react-bootstrap'
  563. → bootstrap CSS imported
  564. None detected → treat as custom/vanilla (standard audit rules apply)
  565. Declare at the top of the audit:
  566. "Detected: React + MUI v5"
  567. "Detected: Next.js + shadcn/ui + Tailwind CSS"
  568. "Detected: Vue 3 + Ant Design"
  569. ```
  570. **Design system — system-specific issue types (add these to relevant categories when a DS is detected):**
  571. ```
  572. MUI / Joy UI:
  573. Cat 6 — Accessibility:
  574. → button:focus { outline: none } overriding MUI's focus-visible → 🔴 Critical
  575. "Overriding MUI's focus-visible breaks keyboard accessibility — remove the override
  576. or use theme.components.MuiButton.styleOverrides.root with focus-visible targeting"
  577. → Calling .MuiButton-root CSS override without :focus-visible scope → 🟡
  578. Cat 17 — Tokens:
  579. → Hardcoded color values bypassing theme.palette → 🟡 "Use theme.palette.primary.main"
  580. → sx={{ fontSize: '14px' }} instead of sx={{ fontSize: 'body2.fontSize' }} → 🟢 Tip
  581. Chakra UI:
  582. Cat 3 — Spacing:
  583. → <Box p="13px"> instead of <Box p={3}> (Chakra spacing scale: 3 = 12px) → 🟡
  584. → Arbitrary spacing string bypassing Chakra's scale → 🟡
  585. Cat 17 — Tokens:
  586. → Hardcoded color strings bypassing the Chakra color scheme ("gray.700" is correct; "#374151" is not) → 🟡
  587. shadcn/ui:
  588. Cat 5 — Consistency:
  589. → Direct className overrides on shadcn components without using the cn() utility → 🟡
  590. (bypasses variant system — use variant prop or extend via cva())
  591. → Multiple custom button implementations alongside shadcn's Button → 🟡
  592. Ant Design:
  593. Cat 5 — Consistency:
  594. → Direct style prop overrides on antd components instead of ConfigProvider/theme → 🟡
  595. Cat 6 — Accessibility:
  596. → antd Form.Item without name prop → 🟡 (label/input association breaks)
  597. General rule for all design systems:
  598. → If a DS is detected AND a hardcoded value overrides its scale → always flag
  599. with the system-specific fix path, not just the generic CSS fix
  600. → Never flag system defaults as issues — only flag when the defaults are
  601. overridden in a way that breaks the design or accessibility
  602. ```
  603. ### Typography extraction from code
  604. ```
  605. Collect all unique font-size values across the codebase/component:
  606. - CSS: font-size declarations (px, rem, em)
  607. - React/Vue: inline styles, className references to utility classes (e.g. text-sm, text-lg)
  608. - Convert rem to px (base 16px unless overridden): 1rem = 16px, 0.875rem = 14px
  609. Map to roles by relative size and frequency (same logic as Figma):
  610. - Largest → heading, next → subheading, most-frequent → body, smallest → caption
  611. Check against typography.md rules and flag issues.
  612. Trigger Type Scale Stack widget with extracted sizes — same as Figma path.
  613. ```
  614. ### Color extraction from code
  615. ```
  616. Collect all color values:
  617. - CSS: color, background-color, border-color (hex, rgb, hsl, var(--token))
  618. - Tailwind: color utility classes (text-gray-900, bg-white, border-blue-500)
  619. - CSS variables: resolve var(--color-x) to actual hex if defined in the file
  620. For each foreground/background pair visible in context:
  621. - Run WCAG luminance contrast check (same algorithm as F3.5)
  622. - Trigger Contrast Checker widget if any pair fails
  623. Hardcoded values (not var(--token)) → flag for Cat 17 (token coverage)
  624. ```
  625. ### Spacing extraction from code
  626. ```
  627. Collect spacing values:
  628. - CSS: padding, margin, gap, width, height in px
  629. - Tailwind: spacing utility classes (p-4 = 16px, m-3 = 12px, gap-2 = 8px)
  630. Tailwind spacing scale: 1 unit = 4px. So p-4 = 16px ✅, p-3 = 12px ✅, p-[13px] = off-grid 🟡.
  631. Check for off-grid values (not multiples of 4). Trigger 8pt Grid Visualizer widget on first offender.
  632. ```
  633. ### Component health from code
  634. ```
  635. Instead of layer tally, assess structural patterns:
  636. - Are UI elements defined as reusable components/functions? (React: <Button>, Vue: <BaseInput>) → ✅
  637. - Are there inline one-off HTML structures with no component wrapper? → 🟡
  638. - Count unique component definitions vs total render instances
  639. If the input is a single component file (not an app):
  640. - Note "Single component input — cross-file component coverage cannot be assessed"
  641. - Audit the internal structure for prop hygiene, named slots, etc.
  642. ```
  643. ### Microcopy extraction from code
  644. ```
  645. Collect all string literals that appear in the UI:
  646. - Button children: <button>Submit</button>, <Button>OK</Button>
  647. - Input placeholders: placeholder="Enter email"
  648. - Labels: <label>First name</label>
  649. - Error strings: "Invalid input", "Required"
  650. - Empty state text
  651. Apply the same per-role checks as Cat 12. Cite line numbers instead of node IDs:
  652. 🟡 placeholder="eg: 5" (line 47) — informal prefix. Use e.g. 5 or a unit hint.
  653. ```
  654. ### 2-frame comparison from code
  655. ```
  656. If the user shares 2+ component files or code snippets in the same session:
  657. - Extract and compare button border-radius, primary color, body font-size across files
  658. - Flag cross-file inconsistencies the same way as the Figma 2-frame compare
  659. ```
  660. ---
  661. ## Step 1.7: Code Fix Output Format
  662. When the input is code, fixes must be output as actual before/after code diffs — not descriptions. This is the code equivalent of F5 (Figma fix loop).
  663. ### Fix format rules
  664. **Always output diffs in this format for every code fix:**
  665. ```
  666. Issue: [issue description]
  667. File: [filename or "component" if single file] · Line [N] (if known)
  668. Before:
  669. [exact original code — 1–5 lines of context]
  670. After:
  671. [corrected code with the fix applied]
  672. Why: [one-sentence reason referencing the rule]
  673. ```
  674. **Framework-aware fix output:**
  675. ```
  676. Vanilla CSS fix:
  677. Before: padding: 13px;
  678. After: padding: 12px; /* snapped to 4pt grid */
  679. Tailwind fix:
  680. Before: className="p-[13px]"
  681. After: className="p-3" /* 12px — nearest grid value */
  682. React inline style fix:
  683. Before: style={{ padding: 13 }}
  684. After: style={{ padding: 12 }}
  685. CSS custom property fix (prefer this over hardcoded):
  686. Before: color: #8a8a8a;
  687. After: color: var(--color-text-secondary);
  688. Aria fix:
  689. Before: <img src="logo.png" />
  690. After: <img src="logo.png" alt="Company logo" />
  691. Focus style fix:
  692. Before: button:focus { outline: none; }
  693. After: button:focus-visible { outline: 2px solid var(--color-focus); outline-offset: 2px; }
  694. ```
  695. **Fix grouping:** When the same issue repeats across lines, show one representative diff and note the others:
  696. ```
  697. Fix shown for line 23. Apply the same pattern to lines 31, 47, 89.
  698. ```
  699. **When to offer a fix loop:**
  700. After completing the audit report, if there are 🔴 Critical issues, offer:
  701. - English: *"Want me to output corrected code for all critical issues?"*
  702. - Korean: *"모든 중요 문제에 대한 수정된 코드를 출력해 드릴까요?"*
  703. If yes → output diffs for every critical in severity order, then warnings if requested.
  704. ---
  705. ## Step 2: Run the Design Audit
  706. > ⚠️ **OUTPUT FORMAT IS MANDATORY — DO NOT DEVIATE**
  707. > Every audit MUST end with a scored report using the Strict Output Template in Step 3.
  708. > This means: a numeric score out of 100, score arithmetic shown explicitly, issues grouped
  709. > by severity (🚫/🔴/🟡/🟢), an Accessibility Score, and the What Next widget.
  710. > Do NOT produce a generic UX review, bullet-point critique, or free-form feedback instead.
  711. > If you are unsure of any value, estimate it and flag with 🟡 Medium confidence — but always
  712. > produce the scored report. Skipping the score is never acceptable.
  713. Check each category. Skip clearly inapplicable ones. Mark each issue:
  714. - 🔴 **Critical** — Breaks usability or accessibility. Must fix. **(-8 points each)**
  715. - 🟡 **Warning** — Weakens the design. Should fix. **(-4 points each)**
  716. - 🟢 **Tip** — Polish-level improvement. Nice to have. **(-1 point each)**
  717. **Scoring formula (always show this explicitly in every report):**
  718. ```
  719. Score = 100 − (blockers × 12) − (criticals × 8) − (warnings × 4) − (tips × 1)
  720. ```
  721. Show the arithmetic inline so the user can see exactly how the score was reached. Example:
  722. > Score: 100 − (3 × 8) − (5 × 4) − (2 × 1) = 100 − 24 − 20 − 2 = **54/100**
  723. Never just show the final number. The breakdown makes the score feel earned and tells the user exactly what to fix to move the needle. If 🟡 Medium confidence applies a −50% modifier, show that too:
  724. > Score: 100 − (2 × 8) − (3 × 4 × 0.5) − (1 × 1 × 0.5) = 100 − 16 − 6 − 0.5 = **77/100** *(medium confidence modifier applied to warnings/tips)*
  725. ---
  726. ### CATEGORY 1: Typography
  727. *Full rules → `references/typography.md`*
  728. - [ ] **Hierarchy** — Clear visual difference between headings, subheadings, body? (Size, weight, or color should vary meaningfully.)
  729. - [ ] **Font count** — Max 2 font families. More = visual chaos.
  730. - [ ] **Body text size** — Min 14px, 16px preferred. Never below 12px for any visible text.
  731. - [ ] **Line height** — 1.4–1.6× the font size for body text.
  732. - [ ] **Line length** — 60–80 characters per line. Wide lines (100+ chars) tire the eyes.
  733. - [ ] **Text contrast** — WCAG AA: 4.5:1 for normal text, 3:1 for large text (18px+).
  734. - [ ] **Alignment** — Don't randomly mix left-aligned and center-aligned body text.
  735. **→ Widget trigger:** Always attempt to trigger the **Type Scale Stack** widget on Figma or code input — do not wait for a typography issue to be found first. Extract all font sizes from `get_design_context` data directly:
  736. ```
  737. From get_design_context, collect all unique fontSize values across all text nodes.
  738. Map each size to its likely role based on relative size and usage frequency:
  739. - Largest 1–2 sizes → heading (h1, h2)
  740. - Mid-range sizes → subheading / label (h3, h4, label)
  741. - Most frequent size → body
  742. - Smallest sizes → caption / helper
  743. Then check:
  744. - Any body text fontSize < 14 → 🔴 Critical
  745. - Two sizes within 2px of each other → 🟡 Warning (too close to distinguish)
  746. - Same fontSize used for visually different roles → 🟡 Warning (relies on weight alone)
  747. - No size below 12px → ✅
  748. - Scale ratio between adjacent levels (e.g. body→h2) < 1.2 → 🟡 Warning (too flat)
  749. - More than 5 distinct font sizes → 🟡 Warning (scale too complex)
  750. Pass the collected sizes and roles as data to the widget.
  751. If get_design_context returns no text nodes or fontSize data, skip the widget silently.
  752. ```
  753. Introduce with one sentence in the user's detected language:
  754. - English: *"Here's how your type scale stacks up visually."*
  755. - Korean: *"타입 스케일을 시각적으로 확인해 보세요."*
  756. ---
  757. ### CATEGORY 2: Color & Contrast
  758. *Full rules → `references/color.md`*
  759. - [ ] **WCAG contrast** — Normal text ≥ 4.5:1, large text ≥ 3:1, UI components ≥ 3:1.
  760. - [ ] **Color-only meaning** — Never use color as the *only* signal. Pair with icon or text.
  761. - [ ] **Palette size** — 1 primary + 1 accent + neutrals beats many colors.
  762. - [ ] **Color consistency** — Same color = same meaning everywhere.
  763. - [ ] **Low-contrast combos** — Light gray on white, yellow on white, white on light blue all commonly fail.
  764. - [ ] **Color blindness risk** — Red/green pairs (most common — affects ~8% of men), blue/yellow pairs, and low-saturation combinations all pose risk. Never rely on hue alone to convey state.
  765. **→ Widget trigger:** If any contrast issue is found — whether from `get_variable_defs` color token analysis (preferred) or from visual screenshot assessment — use the Visualizer to render the **Contrast Checker** widget. Pre-populate the foreground and background hex values from the failing pair. When contrast was calculated from design tokens, show the exact token names alongside the hex values (e.g. `color/text/secondary #8A8A8A on color/surface/default #FFFFFF — ratio: 3.1:1 ❌`). The widget shows all 5 WCAG pass/fail levels live, a real text preview at heading/body/label sizes, and automatically calculates the nearest passing hex value as a fix suggestion. Introduce with one sentence in the user's detected language:
  766. - English: *"Use this to test fixes — the widget calculates the exact color adjustment needed."*
  767. - Korean: *"이 도구로 수정 사항을 바로 테스트해 보세요 — 통과 가능한 정확한 색상값을 자동으로 계산해 드립니다."*
  768. **Color blindness context — add to every Cat 2 color issue flagged:**
  769. For each failing or risky color pair, append a one-line color blindness note:
  770. ```
  771. Pair type → Color blindness note to append:
  772. Red + Green (e.g. red error on green success, red text on green bg):
  773. → "⚠️ Deuteranopia/Protanopia risk — red and green are indistinguishable for ~8% of men.
  774. Add a non-color signal: icon, pattern, or label."
  775. Red/Orange + background (error states, alerts):
  776. → "⚠️ Protanopia risk — reds appear dark brown/black. Pair with an icon (✕, ⚠) and text."
  777. Blue + Yellow / Blue + Orange:
  778. → "⚠️ Tritanopia risk — blue and yellow are confused. Use contrast + shape cues."
  779. Low saturation pairs (grey on grey, muted tones):
  780. → "⚠️ All types — low-saturation pairs affect all color blindness types. Increase contrast."
  781. High-contrast black/white pairs:
  782. → No color blindness note needed — safe for all types.
  783. Only add the note when the pair is actually present in the design. Never add generic warnings
  784. to every color. One line, appended after the fix suggestion.
  785. ```
  786. ---
  787. ### CATEGORY 3: Spacing & Layout
  788. *Full rules → `references/spacing.md`*
  789. - [ ] **8-point grid** — Spacing/sizing should be multiples of 8 (or 4). Arbitrary values look accidental.
  790. - [ ] **Proximity** — Related items close together, unrelated far apart.
  791. - [ ] **Padding consistency** — Uniform padding inside cards/containers.
  792. - [ ] **Breathing room** — Enough whitespace? Dense UIs overwhelm.
  793. - [ ] **Alignment** — Elements align to a shared edge or center.
  794. - [ ] **Content margins** — Consistent left/right margins, not edge-to-edge.
  795. **→ Widget trigger:** If any off-grid spacing value is found, use the Visualizer to render the **8pt Grid Visualizer** widget. Pre-populate the input with the first offending value found. The widget shows the value on a ruler alongside valid grid neighbours, calculates the snap distance, and pre-colors all common spacing values as on/off-grid. Introduce with one sentence in the user's detected language:
  796. - English: *"Here's where that value sits on the grid and what to snap it to."*
  797. - Korean: *"해당 값이 그리드에서 어디에 위치하는지, 어디로 맞춰야 하는지 확인해 보세요."*
  798. **📋 Code input: direct checks available (run these automatically)**
  799. ```
  800. Off-grid value detection:
  801. → Collect all padding, margin, gap, width, height values in px
  802. → Flag any value not divisible by 4 → 🟡 Warning
  803. → Flag any value not divisible by 8 → 🟢 Tip (4pt is acceptable, 8pt is preferred)
  804. → Tailwind: arbitrary values like p-[13px], gap-[22px] → 🟡
  805. → Tailwind standard classes (p-4, gap-3) are on-grid by definition → ✅
  806. Deduplicate: if the same off-grid value appears 5+ times, report once with count:
  807. 🟡 "padding: 13px — appears in 7 places. Snap to 12px (p-3) or 16px (p-4)."
  808. Padding consistency:
  809. → Cards/panels with mismatched padding sides (paddingTop ≠ paddingLeft etc.) → 🟡
  810. Exception: intentional asymmetric padding (e.g. more horizontal than vertical) is fine
  811. if it appears consistently across all similar components.
  812. → Mixed shorthand: some components use padding: 16px, others padding: 16px 24px → 🟡
  813. z-index escalation:
  814. → z-index values outside expected ranges (see spacing.md z-index table) → 🟡
  815. → z-index: 9999 or z-index: 99999 on non-dev-tool elements → 🟡
  816. → Multiple elements with the same z-index in overlapping contexts → 🟡
  817. Content margin check:
  818. → Body/main container with no max-width → 🟢 Tip (content stretches on wide screens)
  819. → max-width > 1440px on body text containers → 🟢 Tip
  820. → margin: 0 with no padding on outermost container → 🟡 (content touches screen edge)
  821. Logical properties (RTL safety):
  822. → margin-left / margin-right used in layout (not decorative) → 🟢 Tip
  823. (prefer margin-inline-start / margin-inline-end for RTL compatibility)
  824. → padding-left / padding-right on nav or directional containers → 🟢 Tip
  825. ```
  826. ---
  827. ### CATEGORY 4: Visual Hierarchy & Focus
  828. - [ ] **One primary action per screen** — One thing should be obviously most important.
  829. - [ ] **Reading patterns** — Users scan in F or Z patterns. Key info along those paths.
  830. - [ ] **Size = importance** — Bigger = more important. Check it maps correctly.
  831. - [ ] **Contrast = importance** — High contrast = foreground. Check it maps correctly.
  832. **📋 Code input: direct checks available (run these automatically)**
  833. ```
  834. Font-size prominence mapping:
  835. → Collect all font-size values across the file (same as Cat 1 extraction)
  836. → Map: largest = most prominent, most frequent = body, smallest = least prominent
  837. → If the largest font-size element is not the primary CTA or heading → 🟡 Warning
  838. (visual hierarchy may be inverted — the biggest thing should matter most)
  839. → If body copy and a CTA/button share the same font-size → 🟡 Warning
  840. (no size signal to distinguish the action from surrounding text)
  841. z-index stacking ladder:
  842. → Collect all z-index values across the file
  843. → Map relative stacking: base content (0–1) < sticky headers (10–20) < dropdowns (100–200)
  844. < modals (300–400) < tooltips (500+) < dev overlays (9999)
  845. → z-index values not following a logical step ladder → 🟡 Warning
  846. (e.g. modal at z-index 5 when a sticky header is at z-index 10 = modal renders behind header)
  847. → Multiple elements at the same z-index in potentially overlapping contexts → 🟡
  848. → z-index: 9999 / 99999 on non-overlay elements → 🟡 (escalation smell)
  849. Element weight ratios:
  850. → Identify the primary CTA (largest button, most prominent button by class/type)
  851. → Compare its font-weight and font-size against surrounding body text
  852. → Primary CTA font-weight ≤ body font-weight → 🟡 Warning (CTA doesn't feel more important)
  853. → Primary CTA font-size = body font-size with no weight or color differentiation → 🟡
  854. Overchoice check:
  855. → Collect all interactive sibling elements (buttons, links, cards) within the same container
  856. → If 4+ siblings share identical: font-size, font-weight, and background-color (or all lack background)
  857. AND none is visually differentiated as primary → 🟡 Warning
  858. "4+ equal-weight options with no primary action — users experience decision paralysis.
  859. Establish one clear primary action per section."
  860. → If 6+ sibling options share identical visual treatment → 🔴 Critical
  861. (Overchoice Paradox: too many undifferentiated choices measurably reduce decision quality and
  862. completion rates. Demote, group, or hide lower-priority options.)
  863. → Exception: lists (ul/ol), nav menus, and data tables are exempt — overchoice applies to
  864. action-oriented UI (CTAs, product cards, feature choices), not content lists.
  865. → Korean: "4개 이상 동일한 시각적 비중의 선택지 — 결정 마비 위험. 주요 액션을 명확히 구분하세요."
  866. Only run this category if:
  867. → Font-size data was successfully extracted (Cat 1 extraction already done)
  868. Otherwise: note "Visual hierarchy inferred from screenshot — see Cat 1 for typography data"
  869. ```
  870. ---
  871. ### CATEGORY 5: Consistency
  872. *Corner radius full rules → `references/corner-radius.md`*
  873. - [ ] **Component reuse** — Buttons, inputs, cards identical throughout. No one-off styles.
  874. - [ ] **Icon family** — All icons from the same set (same style, same stroke weight).
  875. - [ ] **Corner radius scale** — Radii should come from a fixed set (e.g. 4, 8, 12, 16, 24px, full). Arbitrary values (7px, 11px) look accidental.
  876. - [ ] **Nested radius rule** — When an element sits inside another, outer radius = inner radius + padding. If the inner element has 8px radius and 12px padding, the outer must be ~20px. Mismatched nesting makes corners look "poking out."
  877. - [ ] **Size-proportional radius** — Larger elements need larger radii. A small badge with 12px radius looks right. A large modal with 4px radius looks barely rounded.
  878. - [ ] **Pill shapes are intentional** — border-radius ≥ 50% of height creates a pill. Should be deliberate (tags, toggles, badges) not accidental.
  879. - [ ] **Zero radius is a choice** — Sharp corners (0px) should be a design language decision, not a forgotten default.
  880. - [ ] **Contextual radius** — Modals/sheets anchored to screen edges should have rounded top corners, square bottom. Floating elements fully rounded.
  881. - [ ] **Interaction states** — Hover, active, disabled states all visually distinct.
  882. **2-frame consistency compare mode:**
  883. When the audit session has 2+ frames audited (e.g. file has multiple pages, or the user shares a second frame for comparison), automatically cross-check these values between frames:
  884. ```
  885. Cross-frame checks (run silently, report only mismatches):
  886. - Button corner radius: same value on both frames?
  887. - Primary button fill color: same hex/token?
  888. - Body font size: same value?
  889. - Input field height: same?
  890. - Primary heading font weight: same?
  891. - Icon style: outline vs filled — consistent?
  892. Report cross-frame inconsistencies as:
  893. 🟡 Warning: "[Property] differs between frames: [Frame A] = [value], [Frame B] = [value]"
  894. Example: "Button corner radius: 8px on NTIR form, 4px on Dashboard screen — pick one."
  895. Only run cross-frame checks when you have context data for 2+ frames in the session.
  896. Single-frame audits skip this silently — do not mention it.
  897. ```
  898. **📋 Code input: direct checks available (run these automatically)**
  899. ```
  900. Multiple button implementations:
  901. → Collect all button-like elements: <button>, <a role="button">, elements with onClick
  902. → Group by visual role: primary (filled), secondary (outlined), ghost (text-only)
  903. → If primary buttons have more than 1 unique background-color value → 🔴 Critical
  904. (multiple primary button colors = broken visual language)
  905. → If buttons of the same role have different border-radius values → 🟡 Warning
  906. → If buttons of the same role have different font-size values → 🟡 Warning
  907. Inconsistent border-radius:
  908. → Collect all border-radius values applied to cards, panels, modals, buttons, inputs
  909. → Group by element type (cards together, buttons together, inputs together)
  910. → More than 2 distinct radius values per element type → 🟡 Warning
  911. "Cards use 3 different radius values: 4px, 8px, 12px — pick one."
  912. → Arbitrary radius values (7px, 11px, 13px) not on a defined scale → 🟢 Tip
  913. Colour consistency:
  914. → Collect all background-color / color values used for the same semantic role
  915. (e.g. all primary button backgrounds, all body text colors)
  916. → Same semantic role using 2+ different hex values (without token aliasing) → 🟡
  917. "Primary button uses #7c3aed in one place and #6d28d9 in another"
  918. Duplicate style blocks:
  919. → Scan for CSS rule blocks with identical property sets applied to different selectors → 🟢 Tip
  920. (suggests a component opportunity — these should share a class)
  921. → React/Vue: identical JSX style props repeated across 3+ components → 🟢 Tip
  922. Interaction state coverage:
  923. → For each interactive element type (button, link, input, card), check:
  924. → :hover defined? → ✅
  925. → :focus or :focus-visible defined? → ✅
  926. → :active defined? → 🟢 Tip if missing
  927. → .disabled or [disabled] styled? → 🟡 if missing
  928. → Inconsistency: some buttons have :hover, others don't → 🟡 Warning
  929. ```
  930. ---
  931. ### CATEGORY 6: Accessibility (A11y / WCAG)
  932. - [ ] **Touch targets** — Interactive elements ≥ 44×44px (iOS) or 48×48dp (Material).
  933. - [ ] **Focus states** — Visible focus ring on every keyboard-navigable element.
  934. - [ ] **Alt text readiness** — Meaningful images need alt text. Decorative = `aria-hidden`.
  935. - [ ] **Form labels** — Visible label on every input. Placeholder alone is not a label.
  936. - [ ] **Error messages** — Text description of errors, not just red border/color change.
  937. - [ ] **Reading order** — Visual order matches logical/DOM order for screen readers.
  938. - [ ] **Motion sensitivity** — Animations respect `prefers-reduced-motion`.
  939. - [ ] **Link clarity** — Links distinguishable from text by more than color alone.
  940. **📋 Code input: deeper checks available (run these automatically)**
  941. ```
  942. When auditing HTML/React/Vue code, check directly:
  943. aria-label / aria-labelledby
  944. → Every <button> or <a> without visible text must have aria-label
  945. → Icon buttons: <button aria-label="Close"><Icon /></button> ✅
  946. → Missing: <button><Icon /></button> → 🔴 Critical
  947. alt attributes on <img>
  948. → <img src="..." /> (no alt) → 🔴 Critical
  949. → <img src="..." alt="" /> (decorative, intentional empty) → ✅
  950. → <img src="logo.png" alt="Company logo" /> → ✅
  951. focus styles
  952. → button:focus { outline: none } or *:focus { outline: none } → 🔴 Critical
  953. → :focus-visible with visible outline → ✅
  954. → Search for outline: none / outline: 0 across all CSS
  955. role attributes
  956. → Custom interactive elements (<div onClick=...>) missing role="button" → 🟡
  957. → Landmark roles present: role="main", role="nav", role="complementary" → ✅
  958. tabIndex misuse
  959. → tabIndex > 0 on any element → 🟡 (breaks natural tab order)
  960. → tabIndex="-1" on programmatically focused elements → ✅
  961. input label association
  962. → <input id="email" /> must have <label for="email"> or aria-label → 🔴 if missing
  963. → Placeholder-only inputs → 🔴
  964. Color contrast (code path)
  965. → Extract foreground/background pairs from CSS, run WCAG check programmatically
  966. → More precise than visual estimate — cite exact ratio
  967. SVG accessibility:
  968. → Inline <svg> used decoratively (icon, illustration) without aria-hidden="true" → 🔴 Critical
  969. Correct: <svg aria-hidden="true" focusable="false">...</svg>
  970. Why: Screen readers announce SVG contents as text if not hidden, creating noise
  971. → Inline <svg> used as a meaningful image (logo, chart, diagram) without role="img"
  972. AND a <title> element → 🔴 Critical
  973. Correct: <svg role="img" aria-labelledby="icon-title"><title id="icon-title">Company logo</title>...</svg>
  974. → <svg> with focusable="true" (IE default) in an icon-only button → 🟡 Warning
  975. (creates double tab stop — icon receives focus separately from its button wrapper)
  976. → <use href="..."> or <use xlink:href="..."> referencing a <symbol> — check the <symbol> has a <title> → 🟡
  977. ```
  978. ---
  979. ### CATEGORY 7: Forms & Inputs
  980. - [ ] **Label placement** — Labels above inputs (not beside or inside). Fastest to scan.
  981. - [ ] **Input sizing** — Wide enough to show typical content.
  982. - [ ] **Required field marking** — Asterisk (*) with legend, or label optional fields instead.
  983. - [ ] **Validation timing** — Validate on blur (leaving field), not only on submit.
  984. - [ ] **Error placement** — Error messages directly below the relevant field.
  985. - [ ] **Field grouping** — Related fields visually grouped (less space within, more between groups).
  986. - [ ] **Submit button state** — Loading state while submitting. Disable after first click.
  987. **📋 Code input: direct checks available (run these automatically)**
  988. ```
  989. input type correctness:
  990. → <input type="text"> for email → 🟡 should be type="email"
  991. → <input type="text"> for password → 🔴 should be type="password"
  992. → <input type="text"> for phone → 🟡 should be type="tel"
  993. → <input type="text"> for numbers → 🟡 should be type="number" or inputMode="numeric"
  994. → <input type="text"> for URLs → 🟡 should be type="url"
  995. → <input type="submit"> instead of <button type="submit"> → 🟢 Tip (button is more styleable)
  996. autocomplete attributes:
  997. → Name fields missing autocomplete="name" / autocomplete="given-name" → 🟡
  998. → Email fields missing autocomplete="email" → 🟡
  999. → Password fields missing autocomplete="current-password" or "new-password" → 🟡
  1000. → Credit card fields missing autocomplete="cc-number" etc. → 🟡
  1001. → Cite the field and the missing value
  1002. required + aria-required:
  1003. → <input required> without aria-required="true" → 🟢 Tip (redundant but explicit for AT)
  1004. → Required inputs with no visual indicator (* or "(required)" label) → 🟡
  1005. aria-describedby for error messages:
  1006. → Error message element exists but not linked via aria-describedby on its input → 🟡
  1007. → Correct: <input aria-describedby="email-error"> ... <span id="email-error">...</span>
  1008. fieldset + legend for grouped inputs:
  1009. → Radio groups or checkbox groups without <fieldset><legend> → 🟡
  1010. → Only one radio/checkbox option → skip this check
  1011. inputMode for mobile keyboards:
  1012. → Numeric inputs missing inputMode="numeric" or inputMode="decimal" → 🟢 Tip
  1013. → This triggers the correct soft keyboard on mobile
  1014. novalidate + custom validation:
  1015. → <form> without novalidate when custom validation JS exists → 🟡 (browser + custom = double errors)
  1016. → <form novalidate> with no custom validation JS visible → 🟡 (validation silently disabled)
  1017. disabled vs readonly:
  1018. → <input disabled> when the intent is read-only display → 🟢 Tip
  1019. (disabled excludes from form submission; readonly keeps the value but prevents editing)
  1020. ```
  1021. ---
  1022. ### CATEGORY 8: Motion & Animation
  1023. *Full rules → `references/animation.md`*
  1024. - [ ] **Purpose** — Every animation orients, gives feedback, or shows a relationship. No pure decoration.
  1025. - [ ] **Duration** — UI transitions: 150–300ms. Page transitions: 300–500ms. Longer feels sluggish.
  1026. - [ ] **Easing** — Ease-out for entering elements, ease-in for exiting. Linear feels mechanical.
  1027. - [ ] **Reduced motion** — Non-animated version for `prefers-reduced-motion` users.
  1028. - [ ] **No infinite autoplay loops** — Distract and exhaust users. Pause after 3 loops or on hover.
  1029. **📋 Code input: direct checks available (run these automatically)**
  1030. ```
  1031. prefers-reduced-motion:
  1032. → Search for @media (prefers-reduced-motion: reduce) in all CSS/styled-components
  1033. → If any animation or transition exists and no reduced-motion query found → 🔴 Critical
  1034. → Correct pattern:
  1035. @media (prefers-reduced-motion: reduce) {
  1036. *, *::before, *::after {
  1037. animation-duration: 0.01ms !important;
  1038. transition-duration: 0.01ms !important;
  1039. }
  1040. }
  1041. animation-duration values:
  1042. → Extract all transition: and animation: duration values
  1043. → > 500ms on a UI interaction (not page transition) → 🟡 Warning
  1044. → > 1000ms on anything except intentional loading → 🔴 Critical
  1045. → linear easing on transitions → 🟡 (cite the property and value)
  1046. animation-iteration-count:
  1047. → infinite on any element without a pause/hover mechanism → 🟡 Warning
  1048. → Cite element selector and property
  1049. CSS transition on all properties:
  1050. → transition: all ... → 🟡 Warning (causes jank, prefer specific properties)
  1051. → transition: color 200ms ease-out → ✅
  1052. ```
  1053. ---
  1054. ### CATEGORY 9: Dark Mode (if applicable)
  1055. - [ ] **Not just inverted** — Dark mode requires redesigned colors, not flipped ones.
  1056. - [ ] **Background depth** — Lighter dark grays for elevated surfaces (cards, modals). Not pure black.
  1057. - [ ] **Saturation** — Reduce vivid brand colors in dark mode — they look garish on dark.
  1058. - [ ] **Shadow replacement** — Use lighter surface colors for elevation instead of shadows.
  1059. - [ ] **Icon & image legibility** — Icons/images still readable on dark backgrounds.
  1060. **📋 Code input: direct checks available (run these automatically)**
  1061. ```
  1062. Detect if dark mode is implemented:
  1063. → Search for @media (prefers-color-scheme: dark) in CSS
  1064. → Search for [data-theme="dark"] or .dark selector patterns
  1065. → Search for dark: utility prefix (Tailwind dark mode)
  1066. → If any: audit dark mode implementation. If none: note as 🟢 Tip if product likely needs it.
  1067. If dark mode is found, check:
  1068. Color swap pattern:
  1069. → ✅ Good: CSS custom properties swapped in dark media query
  1070. :root { --bg: #ffffff; --text: #111111; }
  1071. @media (prefers-color-scheme: dark) { :root { --bg: #1a1a1a; --text: #f0f0f0; } }
  1072. → 🔴 Bad: Separate hardcoded hex values in dark selectors (token system is broken)
  1073. .dark .card { background: #1c1c1c; color: #ffffff; } ← hardcoded
  1074. Pure black backgrounds:
  1075. → background: #000000 or bg-black in dark mode → 🟡 Warning
  1076. → Prefer #0f0f0f–#1e1e1e range for depth
  1077. Contrast in dark mode:
  1078. → Run WCAG check on dark mode color pairs too (not just light mode)
  1079. → Dark mode often passes light mode checks but fails its own
  1080. Tailwind dark mode:
  1081. → Check if darkMode: 'class' or 'media' is configured
  1082. → Inconsistent dark: prefix usage across components → 🟡
  1083. color-scheme property:
  1084. → <meta name="color-scheme" content="dark light"> or CSS `color-scheme: dark light`
  1085. absent when dark mode IS implemented → 🟢 Tip
  1086. (without this, browser chrome — scrollbars, form inputs — stays light even in dark mode)
  1087. → color-scheme: dark (only) when the product has a light mode toggle → 🟡 Warning
  1088. (locks browser chrome to dark regardless of user preference)
  1089. ```
  1090. ---
  1091. ### CATEGORY 10: Responsive & Adaptive
  1092. - [ ] **Breakpoints** — Mobile (320–480px), tablet (768px), desktop (1024px+) considered.
  1093. - [ ] **No overflow** — Long words or fixed-width containers don't break on small screens.
  1094. - [ ] **Mobile touch targets** — Bigger targets and more spacing than desktop.
  1095. - [ ] **Image scaling** — Images scale without awkward cropping or overflow.
  1096. - [ ] **Type scaling** — Large desktop headings (48px) scaled down to 28–32px on mobile.
  1097. **📋 Code input: direct checks available (run these automatically)**
  1098. ```
  1099. Breakpoint coverage:
  1100. → Collect all @media queries in CSS/styled-components/Tailwind
  1101. → If only one breakpoint found (or none) → 🟡 Warning
  1102. → If no mobile-first breakpoints (min-width) → 🟡 (desktop-first with max-width is harder to maintain)
  1103. → Tailwind: check for sm:, md:, lg:, xl: prefix usage — missing sm: on any layout element → 🟡
  1104. → Flag the specific elements that have no responsive variant
  1105. Fixed-width traps:
  1106. → width: [value]px on containers (not icons or images) → 🟡 (use max-width or %)
  1107. → Fixed pixel widths > 480px with no responsive override → 🔴 (will overflow on mobile)
  1108. → min-width values that exceed mobile viewport (320px) → 🟡
  1109. Overflow risks:
  1110. → overflow: hidden on a container without a max-width → 🟡 (clips content on small screens)
  1111. → Long unbreakable strings: no word-break or overflow-wrap rule on text containers → 🟡
  1112. → white-space: nowrap on text that could be long → 🟡
  1113. Image responsiveness:
  1114. → <img> without max-width: 100% or w-full → 🟡 (overflows container on small screens)
  1115. → <img> with fixed width/height attributes and no CSS override → 🟡
  1116. → Missing srcset or sizes attributes on large hero images → 🟢 Tip (performance)
  1117. → object-fit missing on images inside fixed-height containers → 🟡
  1118. Viewport meta tag (HTML only):
  1119. → Missing <meta name="viewport" content="width=device-width, initial-scale=1"> → 🔴 Critical
  1120. (without this, mobile browsers render at desktop width)
  1121. Font size on mobile:
  1122. → body font-size < 16px with no responsive override → 🟡
  1123. (iOS Safari auto-zooms on inputs with font-size < 16px)
  1124. → Input font-size < 16px → 🟡 (triggers zoom on focus on iOS)
  1125. Tailwind responsive audit:
  1126. → Elements using fixed Tailwind width classes (w-96, w-80) without sm:/md: override → 🟡
  1127. → Text size classes without responsive scaling (text-5xl with no sm:text-3xl) → 🟡
  1128. → hidden / flex / block classes without responsive context → note if suspicious
  1129. Viewport units:
  1130. → height: 100vh on mobile without dvh fallback → 🟡
  1131. (100vh includes browser chrome on mobile, causing content to be hidden)
  1132. → Correct: height: 100dvh (dynamic viewport height) or min-height: 100svh
  1133. ```
  1134. ---
  1135. ### CATEGORY 11: Loading, Empty & Error States
  1136. *The forgotten 30% — most beginner UIs only design the "happy path." Read `references/states.md` for full guidance.*
  1137. - [ ] **Loading state** — Every data fetch needs a loading indicator. Skeleton screens preferred over spinners for content-heavy layouts. Never show a blank screen.
  1138. - [ ] **Empty state** — What does an empty list, inbox, or dashboard look like? Should include an illustration or icon, a friendly explanation, and a clear next action ("Create your first task →").
  1139. - [ ] **Error state** — Network failures, server errors, and not-found pages need their own designed state. Not just a console error or blank screen.
  1140. - [ ] **Partial failure** — What if only some data loads? Design for partial states, not just all-or-nothing.
  1141. - [ ] **Success state** — After a form submission or action, confirm it worked. A toast, a green banner, or a state change — something must close the loop.
  1142. - [ ] **Disabled state** — Disabled buttons and inputs should look visually distinct (reduced opacity, no pointer cursor) and ideally explain why they're disabled.
  1143. - [ ] **Consistency** — Loading/empty/error states should match the overall visual style — not be plain browser defaults or unstyled fallbacks.
  1144. **→ Widget trigger:** If any missing state is found, always render the **States Coverage Map** widget — even for a single missing state. Pre-populate the grid with the components identified in the audit and mark states as present, missing, or N/A based on what was observed. Mark cells as N/A only when a state genuinely cannot apply to that component (e.g. "Empty" on a Button). Introduce with one sentence in the user's detected language:
  1145. - English: *"Here's the full picture of which states are designed and which are missing."*
  1146. - Korean: *"어떤 상태가 디자인되어 있고 어떤 상태가 빠져 있는지 전체 현황을 확인해 보세요."*
  1147. **📋 Code input: direct checks available (run these automatically)**
  1148. ```
  1149. Loading state detection:
  1150. → Search for conditional renders based on loading/isLoading/isPending/isFetching flags
  1151. → Component fetches data (useEffect + fetch / useQuery / useSWR) with no loading branch → 🔴 Critical
  1152. → Loading branch renders null or nothing → 🔴 Critical
  1153. → Loading branch renders a spinner → ✅ (tip: skeleton preferred for content-heavy layouts)
  1154. → aria-live="polite" or aria-busy="true" absent on dynamically updated regions → 🟡 Warning
  1155. (screen readers won't announce content updates without aria-live)
  1156. → Correct: <div aria-live="polite" aria-busy={isLoading}> ... </div>
  1157. Empty state detection:
  1158. → Conditional render for empty array/null data that renders null or nothing → 🔴 Critical
  1159. "No empty state — users see a blank screen when data is empty"
  1160. → Empty state renders only a text string with no action → 🟡 Warning
  1161. "Empty state has no next action — add a CTA or guidance"
  1162. → Well-formed empty state: icon/illustration + explanation + CTA → ✅
  1163. Error state detection:
  1164. → try/catch or .catch() / isError flag with no error UI branch → 🔴 Critical
  1165. → Error state renders raw error.message string → 🟡 Warning
  1166. (technical error messages are not user-friendly — use a human message)
  1167. → Error state has no retry action → 🟡 Warning
  1168. → Well-formed error state: friendly message + retry or back action → ✅
  1169. Disabled state detection:
  1170. → <button disabled> with no visual distinction beyond default browser style → 🟡
  1171. → Disabled button with no tooltip or explanation of why → 🟢 Tip
  1172. → cursor: not-allowed absent on disabled elements → 🟢 Tip
  1173. Success state detection:
  1174. → Form submit handler with no success feedback (no toast, no banner, no state change) → 🟡
  1175. → Success message auto-dismisses before user can read it (timeout < 3000ms) → 🟡
  1176. Korean report labels for this category:
  1177. → 로딩 상태 누락 / 빈 상태 누락 / 오류 상태 누락 / 비활성화 상태 스타일 없음 / 성공 피드백 없음
  1178. Peak-End Rule:
  1179. Users judge entire flows by two moments: the emotional peak and the final screen.
  1180. This makes success/completion states disproportionately important — they are the "end."
  1181. → Check all success/completion screens (form submitted, purchase complete, onboarding done,
  1182. file uploaded, account created):
  1183. → Success screen displays only a generic "Done" or "Success" with no detail → 🟡 Warning
  1184. "The last screen of a flow shapes the user's memory of the whole experience.
  1185. Add: what was completed, what happens next, and a positive reinforcement signal."
  1186. → Success screen auto-redirects in < 2000ms before user can read it → 🟡 Warning
  1187. → Success screen has no positive visual signal (color, icon, illustration, animation) → 🟡
  1188. → Well-formed success screen: names the completed action + next step + positive visual → ✅
  1189. → Check the "peak" moment — the primary CTA interaction (submit, purchase, confirm):
  1190. → Button shows no pressed/active state during interaction → 🟡 (no tactile feedback)
  1191. → No loading state between tap and result → 🟡 (also caught by Cat 11 loading check)
  1192. Korean: 피크-엔드 법칙 — 완료 화면 미흡 / 성공 화면 즉시 리다이렉트 / 시각적 강화 요소 없음
  1193. Goal Gradient Theory:
  1194. People increase effort and motivation as they get closer to completing a goal.
  1195. Progress indicators that don't communicate proximity to completion miss this effect.
  1196. → Scan for multi-step flows (checkout, onboarding, forms, wizards):
  1197. → 3+ step flow with no visible step counter or progress bar → 🟡 Warning
  1198. "No progress signal — users don't know how close they are to done, reducing completion rates."
  1199. → Progress bar present but always shows the same fill regardless of step → 🔴 Critical
  1200. (static progress bar is misleading — users expect it to advance)
  1201. → Step counter says "Step 3" without a total (e.g. "of 5") → 🟡 Warning
  1202. "Without knowing the total, users can't judge proximity to completion."
  1203. → Step counter shows "Step 3 of 4" — total visible → ✅
  1204. → Progress bar fill increases proportionally per step → ✅
  1205. → Final step visually signals it's the last step (e.g. "Last step", filled bar, changed CTA label) → ✅ strong signal
  1206. → Code checks:
  1207. → Stepper component without aria-valuenow / aria-valuemax → 🟡 (also Cat 6)
  1208. → Progress bar with static width value (width: 50% hardcoded, not dynamic) → 🔴
  1209. → Step counter rendered as plain text with no semantic role (role="status" or aria-live) → 🟡
  1210. Korean: 목표 경사 이론 — 진행 표시 없음 / 정적 진행 바 / 전체 단계 수 미표시
  1211. ```
  1212. ---
  1213. ### CATEGORY 12: Content & Microcopy
  1214. *The words inside a UI are part of the design. Read `references/microcopy.md` for full guidance.*
  1215. **On Figma/code input: read every text node.** `get_design_context` returns all text content. Extract and check each one — do not guess. Group them by role:
  1216. ```
  1217. Text content extraction (Figma + code):
  1218. 1. Collect all text node values from get_design_context
  1219. 2. Classify each by role:
  1220. - CTA buttons: text nodes inside button components
  1221. - Labels: text nodes associated with inputs (above/beside)
  1222. - Placeholders: text nodes with placeholder-style content ("Search", "Enter...", "eg:")
  1223. - Error messages: text nodes near error states or with error styling
  1224. - Empty state messages: text nodes in empty/zero-state frames
  1225. - Section headers / titles: largest text nodes in a section
  1226. 3. Apply checks per role (see below)
  1227. 4. Cite the exact text content and node ID in each issue
  1228. e.g. 🟡 "Placeholder 'eg: 5' (node 68:27994) — informal prefix. Use '0' or unit hint."
  1229. ```
  1230. Per-role checks:
  1231. - [ ] **Button labels are verbs** — "Save Changes", "Send Message" not "OK", "Submit", "Yes"
  1232. - [ ] **Error messages are human** — "Invalid input" → 🔴. "Please enter a valid email" → ✅
  1233. - [ ] **Placeholder ≠ label** — Placeholders hint at format (e.g. "name@example.com"), never replace a label. Flag any placeholder that duplicates its label exactly.
  1234. - [ ] **Placeholder prefix style** — "eg:", "e.g." → 🟡 informal. Use the example value directly or a unit label.
  1235. - [ ] **Destructive actions are explicit** — "Delete" dialogs should name what's being deleted. "Are you sure?" alone → 🟡
  1236. - [ ] **Consistent terminology** — Flag if the same concept uses different words across text nodes (e.g. "workspace" and "project" used interchangeably)
  1237. - [ ] **Tone consistency** — Formal in one section, casual in another → 🟡
  1238. - [ ] **No lorem ipsum** — Any "lorem ipsum" or "placeholder text" string → 🔴 Critical at Dev handoff or later
  1239. - [ ] **Empty states have direction** — "No results found" alone → 🟡. Should include a next action.
  1240. - [ ] **Required field legend** — If * is used for required fields, check for a "* Required fields" legend somewhere in the frame. Missing → 🟢 Tip.
  1241. **📋 Code input: direct checks available (run these automatically)**
  1242. ```
  1243. Button label audit:
  1244. → Collect all <button>, <a role="button">, and submit-type elements and extract their text content
  1245. → Labels that are not verbs or verb phrases → 🟡 Warning
  1246. ❌ "OK", "Yes", "Submit", "Click here", "More"
  1247. ✅ "Save changes", "Send message", "Get started", "Delete account"
  1248. → Icon-only buttons with no aria-label → 🔴 Critical (also caught by Cat 6, flag once)
  1249. → Button text identical to page heading (no specificity) → 🟡
  1250. e.g. two "Submit" buttons on the same page with no differentiating context
  1251. Error message audit:
  1252. → Scan all string literals used in error/validation contexts (near catch blocks, validation fns, error state renders)
  1253. → Strings that are purely technical → 🟡 Warning
  1254. ❌ "Invalid input", "Error 422", "Request failed", "null", "undefined"
  1255. ✅ "Please enter a valid email address", "Something went wrong — try again"
  1256. → Error strings with no guidance on how to fix → 🟡
  1257. → aria-describedby linked error messages (cross-check with Cat 7) → ✅
  1258. Placeholder audit:
  1259. → Collect all placeholder="..." attribute values
  1260. → Placeholder that exactly duplicates its label text → 🟡
  1261. e.g. label="Email" + placeholder="Email" — redundant, adds no value
  1262. → Placeholder starting with "eg:", "e.g.", "ex:" → 🟡 informal prefix
  1263. Prefer: use the example directly — placeholder="name@example.com"
  1264. → Placeholder used as sole label (no visible <label>) → 🔴 (also Cat 7)
  1265. Lorem ipsum / filler content:
  1266. → Any string containing "lorem ipsum", "placeholder text", "TBD", "TODO", "FIXME" in UI-facing strings → 🔴 Critical at Dev handoff stage
  1267. → Flag line number and surrounding component
  1268. Terminology consistency:
  1269. → Collect all nouns used for the same concept across the file
  1270. → If 2+ different terms are used for the same entity → 🟡 Warning
  1271. e.g. "workspace" in one component, "project" in another, "team" in a third — all meaning the same thing
  1272. Destructive action copy:
  1273. → Alert/confirm dialogs or delete modal text that reads only "Are you sure?" → 🟡
  1274. Must name the specific thing being deleted: "Delete 'Project Alpha'? This cannot be undone."
  1275. Korean report labels for this category:
  1276. → 버튼 라벨 동사 누락 / 오류 메시지 비인간적 / 플레이스홀더 = 라벨 중복 /
  1277. 비공식 플레이스홀더 접두사 / 로렘 입숨 발견 / 용어 불일치 / 파괴적 동작 문구 부재
  1278. ``` (if applicable)
  1279. *Only audit this category if the product targets multiple languages or RTL locales (Arabic, Hebrew, Persian, Urdu). Read `references/i18n.md` for full guidance.*
  1280. - [ ] **No hardcoded strings** — All visible text should come from a translation file, not be baked into the component. Check for any hardcoded labels, tooltips, or error messages.
  1281. - [ ] **Text expansion budget** — German and Finnish can be 30–40% longer than English. Buttons, labels, and nav items must accommodate longer text without breaking layout. Test with a long string.
  1282. - [ ] **RTL layout mirroring** — In RTL languages, the entire layout flips: left becomes right. Navigation, icons, progress indicators, and reading direction all reverse. Use `dir="rtl"` and CSS logical properties (`margin-inline-start` instead of `margin-left`).
  1283. - [ ] **RTL-safe icons** — Directional icons (arrows, chevrons, back buttons) must flip in RTL. Non-directional icons (heart, star, trash) stay the same.
  1284. - [ ] **Date, time & number formats** — These vary by locale. Don't hardcode formats like "MM/DD/YYYY" — use locale-aware formatting (e.g., `Intl.DateTimeFormat`).
  1285. - [ ] **Currency & units** — Symbol position and decimal separators differ by locale (€1,234.56 vs 1.234,56 €). Never assume.
  1286. - [ ] **No text in images** — Images with embedded text can't be translated. Use CSS overlays or separate text layers instead.
  1287. - [ ] **Font support** — Does the chosen font support all target scripts? Latin fonts won't render Arabic or CJK characters — a system fallback font will kick in and look inconsistent.
  1288. **📋 Code input: direct checks available (run these automatically)**
  1289. ```
  1290. Hardcoded string detection:
  1291. → Scan all JSX/template content for bare string literals inside UI elements
  1292. → <button>Submit</button> when no i18n wrapper → 🟡 if i18n is likely needed
  1293. → <p>No results found</p> hardcoded → 🟡
  1294. → Compare against: t('key'), i18n.t('key'), $t('key'), <FormattedMessage id="..."/> — these are ✅
  1295. → Only flag as 🔴 if evidence of multi-language intent exists (e.g. i18n library imported but some strings not wrapped)
  1296. RTL CSS properties:
  1297. → margin-left / margin-right / padding-left / padding-right / text-align: left → 🟡 if RTL needed
  1298. → margin-inline-start / padding-inline-end / text-align: start → ✅ logical properties
  1299. → position: absolute with left: / right: without RTL override → 🟡
  1300. Intl API usage:
  1301. → Hardcoded date formats like "MM/DD/YYYY" or toLocaleDateString() without locale → 🟡
  1302. → new Intl.DateTimeFormat(locale, options) → ✅
  1303. → Hardcoded currency symbols ($, €) outside of a locale formatter → 🟡
  1304. dir attribute:
  1305. → Check for dir="rtl" implementation pattern on root or document
  1306. → CSS [dir="rtl"] selectors for flip overrides → ✅
  1307. Only run this category if:
  1308. - An i18n library is imported (react-i18next, vue-i18n, next-intl, etc.), OR
  1309. - The user explicitly asks for i18n review, OR
  1310. - The file contains non-English strings
  1311. Otherwise: skip silently.
  1312. ```
  1313. ---
  1314. ### CATEGORY 14: Elevation & Shadows
  1315. *Full rules → `references/elevation.md`*
  1316. - [ ] **Shadow scale** — Shadows should come from a defined scale (e.g. sm, md, lg, xl) — not arbitrary values. Each level should be used consistently for the same type of element.
  1317. - [ ] **Shadow = elevation** — Shadows communicate how high above the page an element floats. Cards sit low (subtle shadow), modals sit high (strong shadow), tooltips highest. Check the hierarchy makes sense.
  1318. - [ ] **Shadow color** — Shadows should use a dark, slightly saturated color (e.g. `rgba(0,0,0,0.08)`) — never pure black. On colored backgrounds, tint the shadow with the surface color.
  1319. - [ ] **No shadows in dark mode** — Shadows are invisible on dark backgrounds. Use lighter surface colors for elevation instead (e.g. a card is slightly lighter gray than the page background).
  1320. - [ ] **No decorative shadows** — Shadows should only appear on elevated elements. Don't use shadows purely for decoration or emphasis on flat elements.
  1321. - [ ] **Consistent blur & offset** — A consistent offset-to-blur ratio (e.g. offset-y = 1/3 of blur) makes shadows feel physically grounded. Mismatched values look amateur.
  1322. - [ ] **Multiple light sources** — Don't combine a top-shadow and a bottom-shadow on the same element unless intentional. Pick one light source direction and stick to it.
  1323. **📋 Code input: direct checks available (run these automatically)**
  1324. ```
  1325. box-shadow value audit:
  1326. → Collect all box-shadow declarations across CSS/styled-components/Tailwind
  1327. → Arbitrary shadow values not matching a defined scale → 🟡 Warning
  1328. ❌ box-shadow: 0 3px 7px rgba(0,0,0,0.11) — arbitrary, not from a scale
  1329. ✅ box-shadow: var(--shadow-md) or Tailwind shadow-md
  1330. → More than 3 distinct box-shadow values used for the same element type (e.g. cards) → 🟡
  1331. "Cards use 4 different shadow values — establish a shadow scale"
  1332. Shadow color audit:
  1333. → box-shadow using pure black rgba(0,0,0,1) or #000000 → 🟡 Warning
  1334. "Pure black shadows look heavy — use rgba(0,0,0,0.08–0.20) for natural depth"
  1335. → box-shadow using an opaque color (no alpha channel) → 🟡
  1336. → On colored surfaces: shadow color should be tinted with the surface color, not neutral black → 🟢 Tip
  1337. Elevation hierarchy check:
  1338. → Collect elements by type: cards, modals, dropdowns, tooltips, sticky headers
  1339. → Compare their shadow values — higher elements must have stronger shadows
  1340. → Modal shadow ≤ card shadow → 🟡 Warning (elevation hierarchy inverted)
  1341. → Tooltip shadow ≤ modal shadow → 🟡
  1342. Multiple shadows on same element:
  1343. → Element with both a top and bottom box-shadow without clear design intent → 🟡
  1344. → More than 2 box-shadow layers on a single element → 🟡
  1345. Dark mode shadow check:
  1346. → box-shadow retained in dark mode without override → 🟡 Warning
  1347. "Shadows are invisible on dark backgrounds — use a lighter surface color for elevation instead"
  1348. → Correct pattern: @media (prefers-color-scheme: dark) { box-shadow: none; background: [elevated-surface-color]; }
  1349. → Tailwind: dark:shadow-none present → ✅
  1350. Blur-to-offset ratio:
  1351. → Extract offset-y and blur-radius from each box-shadow
  1352. → offset-y > blur-radius (e.g. 0 8px 4px) → 🟢 Tip (offset larger than blur looks unnatural)
  1353. → Recommended ratio: blur = 2–3× offset-y
  1354. Korean report labels for this category:
  1355. → 그림자 스케일 미준수 / 순수 검정 그림자 사용 / 높낮이 계층 역전 /
  1356. 다크 모드에서 그림자 미제거 / 블러-오프셋 비율 부적절
  1357. ```
  1358. ---
  1359. ### CATEGORY 15: Iconography
  1360. *Full rules → `references/iconography.md`*
  1361. - [ ] **Consistent icon family** — All icons from the same set (e.g. all Phosphor, all Lucide, all Material). Never mix outline icons from one library with filled icons from another.
  1362. - [ ] **Consistent style within family** — Stick to one style: all outline, all filled, or all duotone. Mixing styles inside one library looks inconsistent.
  1363. - [ ] **Optical sizing** — Icons should be sized at standard grid-friendly values: 16, 20, 24, 32, 40, 48px. Avoid 18px, 22px, 26px — they fall between optical grid lines.
  1364. - [ ] **Stroke weight consistency** — Outline icons have a stroke weight. Don't use 1px icons next to 2px icons — they feel mismatched even when both are "outline."
  1365. - [ ] **Touch target padding** — Icons used as interactive buttons need padding to reach 44×44px minimum. A 24px icon needs 10px padding on each side.
  1366. - [ ] **Icon meaning consistency** — The same icon should mean the same thing everywhere. Don't use a star for both "favourite" and "rating" in the same product.
  1367. - [ ] **Label pairing** — Icons without labels are ambiguous for non-expert users. Always pair with a visible label or tooltip. Exception: universally understood icons (✕ close, ☰ menu, ⌕ search).
  1368. - [ ] **Optical alignment** — Icons often have invisible padding baked in. When aligning icons with text, align to optical center, not bounding box edge.
  1369. **📋 Code input: direct checks available (run these automatically)**
  1370. ```
  1371. Icon sizing audit:
  1372. → Collect all <svg>, <img>, and icon component width/height values
  1373. → Flag sizes not on optical grid: 16, 20, 24, 32, 40, 48px → 🟢 Tip
  1374. "Icon sized at 18px — optical grid values are 16px or 20px"
  1375. → Inconsistent sizes across icons of the same visual role → 🟡 Warning
  1376. "Nav icons are 20px and 24px — pick one"
  1377. SVG icon accessibility:
  1378. → <svg> inside a <button> or <a> without aria-hidden="true" on the SVG → 🔴 Critical
  1379. (the SVG will be announced by screen readers — use aria-hidden on the SVG,
  1380. and aria-label on the parent button instead)
  1381. → Icon-only <button> with no aria-label and a hidden SVG → 🔴 Critical
  1382. (both the SVG is hidden AND there's no label — completely inaccessible)
  1383. → <img> used as icon without alt="" (decorative) or alt="[description]" (meaningful) → 🔴
  1384. → Icon font (class="fa-...", class="material-icons") with no aria-hidden and no label → 🔴
  1385. Stroke weight:
  1386. → Multiple stroke-width values on <path> / <line> elements across icon SVGs → 🟡 Warning
  1387. "Icons use strokeWidth 1 and 2 — inconsistent weight"
  1388. → Only flag if 2+ different SVG elements are present in the same file
  1389. Touch target:
  1390. → <button> or <a> containing only an icon with width or height < 44px and
  1391. no padding to compensate → 🔴 Critical
  1392. "Icon button is 24×24px with no padding — minimum tappable size is 44×44px"
  1393. ```
  1394. ---
  1395. ### CATEGORY 16: Navigation Patterns
  1396. *Full rules → `references/navigation.md`*
  1397. - [ ] **Clear current location** — Users should always know where they are. Active nav items must be visually distinct (color, weight, indicator bar) — not just slightly different.
  1398. - [ ] **Tabs vs nav** — Tabs switch between views of the same content. Nav moves between different sections. Don't use tabs for top-level navigation or nav for in-page switching.
  1399. - [ ] **Breadcrumbs for depth** — Any page more than 2 levels deep needs breadcrumbs. They should show the full path and every crumb should be clickable (except the current page).
  1400. - [ ] **Back button behavior** — "Back" should always go to the previous screen, not the previous URL. In modals and flows, "Back" should not close the entire flow unexpectedly.
  1401. - [ ] **Mobile navigation** — Bottom navigation bar for 3–5 primary destinations on mobile. Hamburger menu acceptable for secondary items but not primary navigation.
  1402. - [ ] **Active state contrast** — Active/selected nav items must meet 3:1 contrast ratio against inactive items — not just a subtle color shift that's easy to miss.
  1403. - [ ] **Overflow handling** — What happens when there are too many nav items? Tabs should scroll horizontally or collapse into a "More" dropdown. Never let them clip or wrap awkwardly.
  1404. - [ ] **Navigation consistency** — The nav should look and behave identically on every page. Never change which items appear, their order, or their style between sections.
  1405. **📋 Code input: direct checks available (run these automatically)**
  1406. ```
  1407. Semantic nav element:
  1408. → Navigation container uses <nav> element → ✅
  1409. → Navigation built with <div> with no role="navigation" → 🟡 Warning
  1410. → Multiple <nav> elements without aria-label to distinguish them → 🟡
  1411. Correct: <nav aria-label="Primary"> and <nav aria-label="Footer">
  1412. Active state implementation:
  1413. → aria-current="page" on the active nav item → ✅
  1414. → Active state relies only on a CSS class (.active) with no aria-current → 🟡
  1415. (class alone doesn't communicate current page to screen readers)
  1416. → Active state only changes color with no weight/background/indicator → 🟡
  1417. (color alone fails colorblind users — needs a secondary signal)
  1418. Skip navigation link:
  1419. → First focusable element is a skip link targeting #main-content → ✅
  1420. → No skip link found → 🟡 Warning
  1421. → Skip link exists but target ID (#main-content) missing from DOM → 🔴 Critical
  1422. Tab vs nav misuse:
  1423. → <nav> containing elements that switch views of the same page → 🟡
  1424. (should be role="tablist" + role="tab" children)
  1425. → role="tablist" used for top-level navigation between pages → 🟡
  1426. (should be <nav> with <a> links)
  1427. Keyboard navigability:
  1428. → Nav items are <div>/<span> with onClick but no role="button" + tabindex="0" → 🔴
  1429. → Nav items are <a> elements with valid href → ✅
  1430. → Dropdown menus with no keyboard handler (Escape to close, arrow keys) → 🟡
  1431. Breadcrumb implementation:
  1432. → <nav aria-label="Breadcrumb"> wrapping the crumb list → ✅
  1433. → Last breadcrumb item has aria-current="page" → ✅
  1434. → Intermediate breadcrumb items are plain text, not links → 🟡
  1435. → No breadcrumb on routes 3+ levels deep → 🟡
  1436. → Breadcrumb list uses <ol> (ordered) not <ul> → ✅ (order matters for breadcrumbs)
  1437. ```
  1438. ---
  1439. ### CATEGORY 17: Design Tokens & Variables Health (if applicable)
  1440. *Audit this when reviewing Figma files or codebases with a design system. Read `references/tokens.md` for full guidance.*
  1441. - [ ] **Colors are tokenized** — No hardcoded hex values in components. Colors should reference a token (e.g. `color.primary.500`, `--color-brand`), not `#7c3aed` directly.
  1442. - [ ] **Spacing is tokenized** — Spacing values reference a scale token, not arbitrary pixel values.
  1443. - [ ] **Typography is tokenized** — Font size, weight, and line-height come from defined text style tokens, not ad-hoc values per component.
  1444. - [ ] **Radius is tokenized** — Corner radius values reference the radius scale, not hardcoded numbers.
  1445. - [ ] **Shadow is tokenized** — Box shadows reference elevation tokens, not custom values per element.
  1446. - [ ] **Token naming is semantic** — Tokens should describe *purpose*, not appearance. `color.background.danger` is good. `color.red.500` used directly in a component is not — it breaks when you need to change the danger color.
  1447. - [ ] **No magic numbers** — Any value that appears more than twice should be a token. Repeated one-off values are a sign the token system isn't being used.
  1448. - [ ] **Dark mode uses the same tokens** — Dark mode should swap token values, not introduce new hardcoded colors. If dark mode components have their own hex values, the token system is broken.
  1449. **📋 Code input: direct token audit available (run automatically — most precise path)**
  1450. ```
  1451. CSS custom property audit:
  1452. → Find all :root { --token: value } definitions — these are the token system
  1453. → Find all var(--token) usages in component CSS
  1454. → Find all hardcoded values (hex, rgb, px) NOT using var()
  1455. Compute per-category coverage:
  1456. color_coverage = var(--color-*) usages / total color declarations × 100
  1457. spacing_coverage = var(--spacing-*) / total padding/margin/gap × 100
  1458. radius_coverage = var(--radius-*) / total border-radius × 100
  1459. shadow_coverage = var(--shadow-*) / total box-shadow × 100
  1460. Report as: "Token coverage: colors 80% · spacing 60% · radius 40% · shadows 20%"
  1461. Any category < 50% → 🟡 Warning
  1462. Any category < 20% → 🔴 Critical (token system not being used)
  1463. JS/TS theme object audit (styled-components / emotion / MUI):
  1464. → Detect theme.colors.*, theme.spacing(), theme.shadows[] usage
  1465. → Hardcoded values inside styled components: color: '#7c3aed' → 🟡
  1466. → theme.colors.primary → ✅
  1467. Tailwind token audit:
  1468. → Tailwind config colors/spacing/borderRadius/boxShadow → these are the tokens
  1469. → Arbitrary values like bg-[#7c3aed], p-[13px], rounded-[7px] → each is 🟡
  1470. → Standard scale values (bg-purple-600, p-3, rounded-lg) → ✅
  1471. Token naming check:
  1472. → --color-red: #ff0000 (describes appearance) → 🟡 rename to --color-error or --color-danger
  1473. → --color-error: #ff0000 (describes purpose) → ✅
  1474. → Tokens with numeric suffixes only (--color-500) without semantic alias → 🟢 Tip
  1475. ```
  1476. ---
  1477. ### CATEGORY 18: Ethical Design & Dark Patterns
  1478. *Full rules, all pattern definitions, detection signals, and the ethical persuasion reference → `references/ethics.md`*
  1479. This category audits for manipulative or deceptive design patterns — not design mistakes, but intentional choices that may exploit users. Read `references/ethics.md` before running this category.
  1480. **When to run:** Always. Every design can be checked for ethical patterns regardless of input type or stage.
  1481. **Ethics severity model** (different from standard audit severity):
  1482. | Level | Label | Meaning | Score impact |
  1483. |---|---|---|---|
  1484. | 🔴 | Deceptive | Actively misleads or coerces. Violates user trust, often consumer law. | −15 pts |
  1485. | 🟡 | Questionable | Exploitative depending on context. Warrants review. | −7 pts |
  1486. | 🟢 | Noted | Persuasive element present. Ethical in standard use. | 0 pts |
  1487. **Ethics Score** is separate from the Overall Score. Start at 100, apply ethics deductions only.
  1488. Display as: **Ethics Score: X/100** alongside Accessibility Score.
  1489. **Detection confidence:** Always declare confidence per finding (High/Medium/Low) using the detection scope table in `references/ethics.md`. Never flag low-confidence patterns without explicit caveat.
  1490. **Checklist — run all groups:**
  1491. *Group A: Deceptive Interface Patterns*
  1492. - [ ] **Confirmshaming** — Decline/cancel copy does not shame or guilt the user for choosing it
  1493. - [ ] **CTA hierarchy inversion** — Accept and decline actions have equivalent visual weight (especially on consent/cookie screens)
  1494. - [ ] **Trick questions** — All consent copy uses positive, unambiguous language with no double negatives
  1495. - [ ] **Disguised ads** — Sponsored/promoted content is visually distinct from organic content with a clear, readable label
  1496. - [ ] **Bait and switch** — CTA labels accurately describe the immediate next action
  1497. - [ ] **Hidden costs** — All mandatory fees are shown from the first price display
  1498. - [ ] **Visual misdirection** — Cost, commitment, and risk information meets the same visual standards as the CTA it accompanies
  1499. - [ ] **Decoy pricing** — In multi-tier pricing layouts (3+ columns), no tier should be a deliberately inferior option designed only to make another tier look better. Signal: a middle or lower tier that is strictly dominated on every axis (price, features, limits) with no clear use case. Confidence: Medium — flag when detected with caveat. Korean: 디코이 가격 책정 — 의도적으로 열등한 옵션으로 중간 등급을 유도하는 패턴
  1500. *Group B: Coercive Flows*
  1501. - [ ] **Roach motel** — Cancellation/exit path is no harder than the sign-up/entry path
  1502. - [ ] **Obstruction** — Unsubscribe, data deletion, and account closure are self-serve and reachable in ≤ 3 steps
  1503. - [ ] **Forced action** — No non-essential data collection or permission is required to access core functionality
  1504. - [ ] **Nagging** — Dismissed prompts stay dismissed; "don't show again" is permanently respected
  1505. *Group C: Consent & Privacy*
  1506. - [ ] **Privacy zuckering** — All non-essential data sharing defaults to OFF
  1507. - [ ] **Pre-checked consent** — No marketing/data-sharing checkbox is pre-checked by default
  1508. - [ ] **Interface interference** — Privacy controls use consistent interaction patterns with clear state labels
  1509. - [ ] **Drip pricing** — No fees are revealed only at the final checkout step
  1510. *Group D: False Urgency & Scarcity*
  1511. - [ ] **Countdown timers** — Any timer is backed by a real server-side expiry that does not reset
  1512. - [ ] **False scarcity** — Scarcity claims ("Only X left") are backed by real-time inventory data
  1513. - [ ] **False social proof** — Social proof numbers ("X people viewing") reflect real data, not hardcoded or random values
  1514. - [ ] **Manipulative anchoring** — Crossed-out "original" prices, inflated RRP values, or "was/now" displays must reflect a price the product was genuinely sold at. A strikethrough price that was never a real selling price is deceptive anchoring. Code signal: `text-decoration: line-through` or `.original-price` / `.was-price` / `.rrp` adjacent to a current price element. Confidence: Medium — flag for review. Korean: 조작적 앵커링 — 실제로 판매된 적 없는 취소선 가격 또는 부풀린 정가 표시
  1515. *Group E: Emotional Manipulation*
  1516. - [ ] **Guilt-based copy** — Inactivity, cancellation, and decline states are addressed neutrally, not shamefully
  1517. - [ ] **Fear appeals** — Risk language is proportionate to actual risk; no exaggerated consequences for conversion
  1518. - [ ] **Toying with emotion** — No patterns that deliberately engineer anxiety, FOMO, or regret as conversion mechanisms
  1519. *Group F: Regulatory Compliance Baseline*
  1520. These checks apply across most jurisdictions (EU, US, UK, Canada, Brazil, Australia). They are UI-detectable signals — not a legal audit. Flag as 🚫 Blocker when a legal requirement is clearly absent; 🟡 Warning when the implementation is ambiguous or weak. Always append: *"Verify with legal counsel for your specific jurisdiction and industry."*
  1521. Korean caveat: *"이 항목은 법률 감사가 아닌 UI 신호 감사입니다. 관할 지역 및 산업별 요건은 법률 전문가와 확인하세요."*
  1522. - [ ] **Cookie & consent banner** — If cookies beyond strictly necessary are used, a consent banner must be present. Check for: banner presence; "Reject All" / "Decline" option at equal visual prominence to "Accept All" (GDPR, PECR, CCPA requirement — CTA hierarchy inversion here is a 🚫 Blocker); granular consent categories (marketing, analytics, functional) rather than a single all-or-nothing toggle.
  1523. Code signal: absence of any consent-related class names (`cookie-banner`, `consent-`, `gdpr-`, `cmp-`) or `localStorage`/`sessionStorage` consent keys → 🚫 if cookies are clearly being set.
  1524. Korean: 쿠키 동의 배너 — "모두 거부" 버튼이 "모두 수락"과 동등한 시각적 비중을 가져야 함
  1525. - [ ] **Subscription & auto-renewal disclosure** — Before a subscription purchase is confirmed, the following must be visible: renewal frequency, renewal amount, and cancellation method. A "free trial → paid" conversion must disclose the date and amount of the first charge before the user commits.
  1526. Code signal: checkout/payment form with no text matching renewal/billing cycle patterns near the CTA → 🟡 Warning.
  1527. Korean: 구독 자동 갱신 고지 — 결제 확인 전 갱신 주기, 금액, 취소 방법이 명시되어야 함
  1528. - [ ] **Privacy at point of collection** — Forms collecting sensitive personal data (email, phone, DOB, national ID, payment, health, location) must include a visible "why we need this" note or a privacy policy link directly at the collection point — not just in the footer.
  1529. Code signal: `<input type="email/tel/date/number">` inside a form with no adjacent `<a href>` linking to a privacy policy and no inline explanation text → 🟡 Warning.
  1530. Korean: 수집 시점 개인정보 고지 — 민감 데이터 입력 필드 근처에 수집 목적 또는 개인정보처리방침 링크 필요
  1531. - [ ] **Right of withdrawal / cancellation policy** — E-commerce and subscription checkout flows must link to a cancellation or returns policy before the final purchase confirmation. A "Buy Now" or "Confirm Order" CTA with no visible policy link nearby is non-compliant in EU/UK/many US states.
  1532. Code signal: final checkout CTA (`type="submit"`, "pay now", "confirm order" label patterns) with no adjacent link text matching "cancel", "return", "refund", "withdrawal" → 🟡 Warning.
  1533. Korean: 청약 철회 / 취소 정책 — 최종 결제 확인 버튼 근처에 취소·환불 정책 링크 필요
  1534. - [ ] **Age gate for restricted content** — Products that could be accessed by minors but involve age-restricted content (alcohol, gambling, adult content, financial products in some jurisdictions) must present an age verification mechanism before access. A DOB picker or age confirmation checkbox that can be trivially bypassed (no backend verification) is a weak gate — flag as 🟡.
  1535. Code signal: presence of age-gated content indicators in route names / class names (`/adults-only`, `age-verify`, `18+`) without a corresponding gate component → 🔴 Critical.
  1536. Korean: 연령 제한 콘텐츠 연령 확인 — 연령 제한 콘텐츠 접근 전 연령 확인 절차 필요
  1537. - [ ] **Accessibility legal baseline** — WCAG 2.1 AA is a legal requirement under: ADA / Section 508 (US), European Accessibility Act (EU — mandatory from June 2025), PSBAR (UK public sector), DDA (Australia), AODA (Canada). Any WCAG AA failure is therefore potentially a legal liability, not just a UX issue. Cat 6 Blocker-tier issues in this audit carry legal weight — do not treat them as optional fixes.
  1538. Note: if the product is a public-sector website (EU/UK) or a service covered by the EAA, all 🚫 Cat 6 Blockers are legal compliance failures.
  1539. Korean: 접근성 법적 기준 — WCAG 2.1 AA는 미국(ADA), EU(유럽 접근성법), 영국(PSBAR), 호주(DDA), 캐나다(AODA)에서 법적 의무 사항임
  1540. **Before flagging any pattern:** Check the Ethical Persuasion reference in `references/ethics.md`. Do not flag legitimate persuasion techniques (genuine social proof, real urgency, positive progress framing, transparent anchoring).
  1541. ---
  1542. ### CATEGORY 19: Nielsen's Usability Heuristics
  1543. *Full rules, all heuristic definitions, detection signals, and the Usability Score → `references/heuristics.md`*
  1544. **Scope:** Audits the 6 heuristics with genuine gaps not covered by existing categories. H4, H5, H8, H9 are already covered by Cat 5, 7, 4, 11/12 respectively — note this in the report but do not re-audit them here.
  1545. **When to run:**
  1546. - Always on Full audits
  1547. - Skip on Quick audits unless user specifically requests heuristic review
  1548. - Triggers on: "heuristic review", "Nielsen audit", "usability heuristics", "H1/H2/H6..." etc.
  1549. - Korean triggers: "휴리스틱 검토", "닐슨 감사", "사용성 휴리스틱", "H1/H2/H6 확인"
  1550. **Usability Score** is separate from the Overall Score and the Accessibility Score. Start at 100, apply standard deduction tiers. Display as: **Usability Score: X/100**
  1551. Scoring bands:
  1552. - **90–100** → Heuristically sound / 사용성 기준 충족
  1553. - **70–89** → Minor usability gaps / 사소한 사용성 문제
  1554. - **50–69** → Significant usability issues / 심각한 사용성 문제
  1555. - **< 50** → Fundamental failures / 근본적인 사용성 실패
  1556. **Checklist:**
  1557. *H1 — Visibility of System Status (gaps only) / 시스템 상태 가시성*
  1558. - [ ] **Async button feedback / 비동기 버튼 피드백** — Every button triggering an async action has a loading/disabled state during processing
  1559. - [ ] **Form submit confirmation / 폼 제출 확인** — Every form submission confirms success with a toast or confirmation screen
  1560. - [ ] **Multi-step progress / 멀티스텝 진행 표시** — Flows with 3+ steps have a visible progress indicator *(detailed progress bar checks → Cat 11 Goal Gradient Theory)*
  1561. *H2 — Match Between System and Real World / 시스템과 현실 세계의 일치*
  1562. - [ ] **No jargon in UI / UI 내 전문 용어 없음** — No raw error codes, stack traces, or developer terms in user-facing copy
  1563. - [ ] **Icon meaning / 아이콘 의미** — Icons match their conventional real-world meaning in context
  1564. - [ ] **Locale-aware formats / 로케일 형식** — Dates and numbers use `Intl` formatting, not hardcoded patterns
  1565. *H3 — User Control and Freedom (gaps only) / 사용자 제어 및 자유*
  1566. - [ ] **Modal exit / 모달 종료** — All modals have a visible close mechanism and respond to Escape key
  1567. - [ ] **Flow back navigation / 플로우 뒤로 가기** — Multi-step flows have a Back option on every step except the first
  1568. - [ ] **Destructive confirmation / 파괴적 작업 확인** — Permanent destructive actions have confirmation dialogs naming what's being deleted
  1569. *H6 — Recognition Rather Than Recall / 기억보다 인식*
  1570. - [ ] **Nav labels / 내비게이션 라벨** — Primary navigation items have visible text labels alongside icons
  1571. - [ ] **Persistent labels / 지속적인 라벨** — Form labels remain visible during and after input
  1572. - [ ] **Selection visibility / 선택 가시성** — Dropdown triggers show the currently selected value; selected options are visually distinct
  1573. *H7 — Flexibility and Efficiency of Use / 사용의 유연성 및 효율성*
  1574. - [ ] **Keyboard shortcuts / 키보드 단축키** — Power user shortcuts are hinted in tooltips on frequently-used actions (productivity tools)
  1575. - [ ] **Bulk actions / 일괄 작업** — Management-oriented lists support bulk selection where clearly warranted
  1576. - [ ] **Preference persistence / 환경설정 저장** — User preferences are saved across sessions where relevant

Lines 2,001–2,770 are not shown. The link to the file on GitHub has every line.

README.md · README · 504 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. [🇰🇷 한국어 버전 →](./README_KR.md)
  2. # 🎨 Design Auditor — Claude Skill
  3. A Claude skill that audits designs against **19 professional design categories** — built for developers, non-designers, and anyone who wants expert design validation without needing to know the rules themselves.
  4. Works with **Figma files** (via Figma MCP), **code** (HTML/CSS/React/Vue), **screenshots**, **wireframes**, and written descriptions. Supports **English and Korean**.
  5. Compatible with **Claude**, **Manus**, and other agents that support SKILL.md-based skills.
  6. ---
  7. ## What It Does
  8. Drop in a Figma link, paste your CSS, upload a screenshot, or share a wireframe — Design Auditor checks your work against 19 categories of design rules and gives you:
  9. - A **score out of 100** with per-category breakdown (with mini bar chart per row)
  10. - A separate **Accessibility Score** (WCAG coverage across Cat 2, 6, 7, 15, 16)
  11. - A separate **Ethics Score** (dark patterns and manipulative design across Cat 18)
  12. - A separate **Usability Score** (Cat 19 — H1/H2/H3/H6/H7/H10, with Nielsen cross-reference for H4/H5/H8/H9)
  13. - A **🚫 Blocker tier** for legal/compliance violations (WCAG AA, GDPR, PECR) — separate from Critical issues
  14. - Issues ranked by severity (🚫 Blocker / 🔴 Critical / 🟡 Warning / 🟢 Tip)
  15. - **Color blindness context** — every failing color pair annotated with the affected blindness type
  16. - **SVG accessibility checks** — decorative vs. meaningful SVG patterns, aria-hidden, role="img"
  17. - **Design System detection** — MUI, Chakra, shadcn/ui, Ant Design, Radix, Bootstrap (system-specific fixes)
  18. - **Figma Auto Layout scan** — detects frames using manual positioning where Auto Layout should be used
  19. - **Plain-language explanations** of *why* each rule matters
  20. - **"Teach Me" mode** — explains the design principles behind your top 3 issues, not just the fixes
  21. - An **Issue Priority Matrix** — every issue plotted by effort vs. impact
  22. - Before/after code diffs when fixing issues in HTML/CSS/React/Vue
  23. - Direct fixes in your **Figma file** via Figma MCP
  24. - **Figma Code Connect** — detects design-to-code mapping gaps (`get_code_connect_suggestions`)
  25. - **Wireframe to Spec** — converts wireframes into annotated dev-ready specs
  26. - **Visual audit report** exportable to Canva for stakeholder sharing
  27. - **Developer handoff report** — CSS spec table, a11y checklist, critical fixes
  28. - **Export report as Markdown** — ready for Notion, GitHub, Linear, or Jira
  29. ---
  30. ## The 19 Audit Categories
  31. | # | Category | What It Checks |
  32. |---|---|---|
  33. | 1 | **Typography** | Hierarchy, font count, size, line height, contrast |
  34. | 2 | **Color & Contrast** | WCAG ratios, semantic color use, palette consistency |
  35. | 3 | **Spacing & Layout** | 8-point grid, proximity, alignment, whitespace |
  36. | 4 | **Visual Hierarchy** | Primary action clarity, reading patterns, size/contrast mapping |
  37. | 5 | **Consistency** | Component reuse, icon families, corner radius, interaction states |
  38. | 6 | **Accessibility (A11y / WCAG)** | Touch targets, focus states, alt text, form labels, reading order |
  39. | 7 | **Forms & Inputs** | Labels, sizing, validation timing, error placement, submit states |
  40. | 8 | **Motion & Animation** | Purpose, duration, easing, reduced-motion support |
  41. | 9 | **Dark Mode** | Not just inverted, surface elevation, saturation, icon legibility |
  42. | 10 | **Responsive & Adaptive** | Breakpoints, overflow, touch targets, type scaling |
  43. | 11 | **Loading, Empty & Error States** | Skeletons, empty state anatomy, error levels, success confirmation, Peak-End Rule, Goal Gradient progress checks |
  44. | 12 | **Content & Microcopy** | Button labels, error messages, tone consistency, terminology |
  45. | 13 | **Internationalization & RTL** | Text expansion, RTL mirroring, locale-aware formatting, font support |
  46. | 14 | **Elevation & Shadows** | Shadow scale, elevation hierarchy, dark mode depth |
  47. | 15 | **Iconography** | Icon families, optical sizing, touch targets, meaning consistency |
  48. | 16 | **Navigation Patterns** | Tabs, breadcrumbs, back buttons, mobile nav, active states |
  49. | 17 | **Design Tokens & Variables** | Semantic naming, hardcoded values, dark mode token swapping |
  50. | 18 | **Ethical Design & Dark Patterns** | Confirmshaming, false urgency, pre-checked consent, CTA hierarchy inversion, privacy zuckering, hidden costs, decoy pricing, manipulative anchoring, and 17 more manipulative patterns across 6 groups — including a Regulatory Compliance Baseline (cookie consent, subscription disclosure, privacy at collection, cancellation policy, age gates, accessibility legal status) |
  51. | 19 | **Nielsen's 10 Usability Heuristics Rules** | Nielsen's 10 Usability Heuristics are the most widely used framework for evaluating interface usability. They were developed by Jakob Nielsen and are grounded in decades of usability research |
  52. ---
  53. ## Who It's For
  54. - **Developers** building UIs who don't have a design background
  55. - **Designers** who want a fast second opinion or WCAG check
  56. - **Teams** using Figma MCP or VS Code who want design validation in their workflow
  57. - **Product managers and founders** who want to ship ethical, accessible products
  58. - **Anyone** who's ever wondered "does this look right?"
  59. ---
  60. ## How to Install
  61. 1. Download [`design-auditor.skill`](../../releases/latest) from the releases page
  62. 2. Go to [Claude.ai](https://claude.ai) → **Customize** → **Skills**
  63. 3. Click **Upload skill** and select the file
  64. 4. Done — the skill is now active in your conversations
  65. ---
  66. ## How to Use
  67. Once installed, just talk to Claude naturally:
  68. **English:**
  69. ```
  70. "Check my design" → choose scope (full / quick / custom), then audit
  71. "Is this accessible?" → accessibility-focused audit
  72. "Review my form" → partial audit, relevant categories only
  73. "Does this follow WCAG?" → contrast & a11y audit
  74. "Check my Figma file: [link]" → Figma MCP audit
  75. "Any dark patterns here?" → ethics audit
  76. "Wireframe to spec" → annotated dev-ready spec from wireframe
  77. ```
  78. **Korean:**
  79. ```
  80. "디자인 검토해줘" → 전체 감사
  81. "접근성 확인해줘" → 접근성 중심 감사
  82. "내 디자인 괜찮아 보여?" → 전체 감사
  83. "UI 검토해줘" → 전체 감사
  84. "색상 대비 확인해줘" → 색상 및 접근성 감사
  85. "와이어프레임 스펙 출력해줘" → 와이어프레임 스펙 모드
  86. ```
  87. ---
  88. ## Example Output
  89. ```
  90. ## 🔍 Design Audit Report
  91. **Input:** Checkout flow · 3 frames
  92. **Type:** Figma MCP
  93. **Confidence:** 🟢 High
  94. **Component health:** 71% coverage · 2 detached instances · 8 unnamed layers
  95. **Code Connect:** 8 components mapped · 3 unmapped
  96. ### Overall Score: 62/100
  97. 100 − (1 × 🚫 12) − (2 × 🔴 8) − (4 × 🟡 4) − (2 × 🟢 1) = 62/100
  98. A legal compliance failure and contrast issues are the main drag.
  99. ### Accessibility Score: 55/100 — significant gaps ⚠️ Contains legal compliance failures
  100. ### Ethics Score: 85/100 — minor concerns
  101. ### 🚫 Blockers (−12pts each)
  102. - **Text contrast failure** — #aaa on white = 2.3:1 → Fix: use #595959 (7:1)
  103. Legal basis: WCAG 2.1 SC 1.4.3
  104. ### 🔴 Critical Issues (−8pts each)
  105. - **Missing form labels** — placeholder-only inputs lose label on type
  106. → Fix: add <label> above each input.
  107. ### 🟡 Warnings (−4pts each)
  108. - **Off-grid spacing** — padding: 13px → Fix: use 12px or 16px
  109. - **CTA hierarchy inversion** — "Accept all" primary, "Reject all" grey text
  110. → Fix: equivalent visual weight (GDPR requirement)
  111. ```
  112. ---
  113. ## Skill Structure
  114. ```
  115. design-auditor/
  116. ├── SKILL.md — Main skill instructions (19 categories)
  117. └── references/
  118. ├── typography.md — Font rules, sizing, hierarchy, type scale algorithm
  119. ├── color.md — WCAG luminance formula, contrast, palette guidance
  120. ├── spacing.md — 8-point grid, layout, proximity, code checks
  121. ├── corner-radius.md — Nested radius rule, scale, pill shapes, code checks
  122. ├── elevation.md — Shadow scale, elevation hierarchy, code shadow audit
  123. ├── iconography.md — Icon families, sizing, touch targets
  124. ├── navigation.md — Tabs, breadcrumbs, back buttons, mobile nav, code checks
  125. ├── tokens.md — Design tokens, semantic naming, dark mode architecture
  126. ├── figma-mcp.md — Figma MCP workflow, Code Connect, page structure, safe editing
  127. ├── heuristics.md — Nielsen's 10 Usability Heuristics: H1/H2/H3/H6/H7/H10 gap coverage
  128. ├── states.md — Loading, empty, error, success states + code checks
  129. ├── microcopy.md — Button labels, errors, tone, per-role audit guide
  130. ├── animation.md — Easing curves, duration scales, reduced motion, code checks
  131. ├── i18n.md — RTL support, locale formatting, i18n
  132. └── ethics.md — Dark patterns, ethical design, persuasion vs manipulation
  133. ```
  134. ---
  135. ## Changelog
  136. ### v1.2.13
  137. **Regulatory Compliance Baseline added to Cat 18.**
  138. **New: Regulatory Compliance Baseline (Cat 18 Group F)**
  139. 6 cross-jurisdiction UI-detectable compliance checks — applicable across EU, US, UK, Canada, Brazil, Australia. 🚫 Blocker when a legal requirement is clearly absent, 🟡 Warning when ambiguous. Each includes a code signal and a caveat that this is a UI signal layer, not a legal audit. Full Korean translations throughout.
  140. - **Cookie & consent banner** — GDPR, PECR, CCPA: banner presence, Reject All at equal prominence to Accept All, granular consent categories
  141. - **Subscription & auto-renewal disclosure** — FTC, CMA, EU Consumer Rights: renewal frequency, amount, and cancellation method visible before confirmation
  142. - **Privacy at point of collection** — GDPR Art. 13, CCPA, PIPEDA: policy link or "why we need this" near sensitive input fields
  143. - **Right of withdrawal / cancellation policy** — EU CRD, UK CRA, FTC: policy link visible near final checkout CTA
  144. - **Age gate for restricted content** — COPPA, GDPR Art. 8, UK Age-Appropriate Design Code: verification mechanism before restricted content
  145. - **Accessibility legal baseline** — ADA/Section 508 (US), EAA (EU — mandatory June 2025), PSBAR (UK), DDA (Australia), AODA (Canada): Cat 6 Blockers carry legal weight
  146. ------------------------------------------------------------------------------------------------------------------------------------------
  147. ### v1.2.12
  148. **Behavioural patterns from nudges.fyi, bug fixes, and visual report improvements.**
  149. **New: 5 behavioural pattern additions**
  150. - **Overchoice Paradox → Cat 4** — 4+ equal-weight sibling actions with no primary → 🟡; 6+ → 🔴. Exempt: lists, nav menus, data tables
  151. - **Peak-End Rule → Cat 11** — audits success/completion screens for memorability: named action, next step, positive visual signal, auto-redirect timing
  152. - **Goal Gradient Theory → Cat 11** — detects multi-step flows with no progress bar, static fill bars, missing step totals, and `aria-valuenow` gaps
  153. - **Decoy Pricing → Cat 18 Group A** — 3-column pricing with one tier strictly dominated on every axis
  154. - **Manipulative Anchoring → Cat 18 Group D** — `text-decoration: line-through` / `.was-price` / `.rrp` patterns near current price elements
  155. **Bug fixes**
  156. - Cat 18 pattern count updated: 20 → 22 (both READMEs)
  157. - Cat 6 SVG `<use>`: added `xlink:href` legacy check alongside `href`
  158. - Cat 19 H1 "Multi-step progress" cross-references new Cat 11 Goal Gradient checks to avoid double-flagging
  159. - Scores panel: Ethics Score formula caveat added — `🔴 −15 · 🟡 −7 · 🟢 0`, distinct from standard formula
  160. - `heuristics.md` separator in skill structure: `-` → `—`
  161. - README Cat 11 row updated to mention Peak-End Rule and Goal Gradient
  162. **Visual report improvements**
  163. - Radar chart: binary purple/red → three-colour scale — purple (8–10) · amber (6–7) · red (≤ 5)
  164. - Radar chart: fallback to Score by Category table when Visualizer unavailable (EN + KR)
  165. - Issue Priority Matrix: Korean axis labels added — `수정 난이도` (x) · `개선 효과` (y)
  166. - Score by Category table: score band footnote — `≥ 8 ✅ · 5–7 🟡 · ≤ 4 🔴` (EN + KR)
  167. - Re-audit delta: before/after bar pair rendered via Visualizer with colour-coded delta badge
  168. - Teach Me mode: 3-card Visualizer layout after lessons, each card clickable via `sendPrompt()`
  169. ------------------------------------------------------------------------------------------------------------------------------------------
  170. ### v1.2.11
  171. **Code parity, design system detection, accessibility improvements, and bug fixes.**
  172. - **Code superpowers** — added `📋 Code input:` blocks to Cat 4 (Visual Hierarchy), Cat 5 (Consistency), Cat 11 (States), Cat 12 (Microcopy), Cat 14 (Elevation), Cat 15 (Iconography) — completing all 19 categories
  173. - **Design System detection** — auto-detects MUI, Chakra UI, shadcn/ui, Ant Design, Radix, Bootstrap; system-specific issue types and fix paths
  174. - **Color blindness context** — every failing color pair annotated with affected blindness type (Deuteranopia, Protanopia, Tritanopia)
  175. - **SVG accessibility** — decorative `aria-hidden`, meaningful `role="img"` + `<title>`, icon-button label checks across Cat 6 and Cat 15
  176. - **Figma Auto Layout scan** — detects frames using manual positioning where Auto Layout should be used; shown in report header
  177. - **Accessibility Score** — expanded from Cat 2/6/7/16 to Cat 2/6/7/**15**/16 (Cat 15 SVG checks are WCAG legal violations)
  178. - **Nielsen cross-reference** — H4/H5/H8/H9 mapped in scores panel to Cat 5/7/4/11–12
  179. - **"Teach Me" mode** — explains design principles behind top 3 issues (beginner + expert depth, full Korean)
  180. - **Scoring formula** — Blockers now explicit: `100 − (blockers × 12) − (criticals × 8) − (warnings × 4) − (tips × 1)`
  181. - **Dev Handoff Report** — added missing 🟢 Tips section; Korean translation included
  182. - **Output** — mini bar column in Score by Category table; Design System + Auto Layout rows in report header; Cat 9 `color-scheme` meta tag check
  183. - **Bug fixes** — category count "17" → "19" throughout; Cat 18/19 numbering corrected; `i19n.md` → `i18n.md`; Korean README category count corrected
  184. ------------------------------------------------------------------------------------------------------------------------------------------
  185. ### v1.2.10
  186. **Dev Handoff Report, Wireframe to Spec — restructured. Korean coverage for both.**
  187. **Dev Handoff Report restructured:**
  188. - `━━━` dividers between all sections for consistent visual separation
  189. - Blockers separated into their own section (`🚫 BLOCKERS — fix before any other work`) above Critical Fixes — previously grouped together
  190. - All four scores in the metadata table: Overall, A11y, Ethics, Usability (with conditional notes for Ethics and Usability)
  191. - Code Connect mapping table included in template
  192. - Consistent `━━━`-wrapped footer
  193. **Wireframe to Spec restructured:**
  194. - All 8 sections now have `━━━` dividers with emoji headers (📐 📏 🔤 🧩 ✍️ 🖱️ ♿ ❓)
  195. - Context notes moved into section headers directly after each `━━━` block, instead of scattered inline
  196. **Korean support added for both:**
  197. - Dev Handoff Report — Korean note block: title, all 6 field labels, all 7 section headers, all 12 table column headers, footer
  198. - Wireframe to Spec — bilingual footer lines + Korean note block: title, field labels, all 8 section headers with context notes, table column headers
  199. **README:**
  200. - v1.0.0–v1.2.4 changelog entries collapsed into a `<details>` block
  201. ------------------------------------------------------------------------------------------------------------------------------------------
  202. ### v1.2.9
  203. **Korean language coverage — full audit pass**
  204. Audited all changes made since v1.2.4 for missing Korean support and filled every gap found.
  205. **SKILL.md gaps fixed:**
  206. - **Category 19 checklist** — All 19 heuristic checklist items now have bilingual labels (e.g. "Async button feedback / 비동기 버튼 피드백")
  207. - **Category 19 triggers** — Korean trigger phrases added: "휴리스틱 검토", "닐슨 감사", "사용성 휴리스틱", "H1/H2/H6 확인"
  208. - **Usability Score bands** — All four bands now bilingual: "Heuristically sound / 사용성 기준 충족", "Minor gaps / 사소한 사용성 문제", etc.
  209. - **Usability Score note in report** — Korean version: "H4(일관성), H5(오류 예방), H8(미적 디자인), H9(오류 복구)는 각각 Cat 5, 7, 4, 11/12에서 다룹니다."
  210. - **URL report header** — Korean format added for all URL-type audits (라이브 URL, 신뢰도, 제한사항)
  211. - **Wireframe spec fidelity line** — Korean added: "값은 권장사항이며 실측값이 아닙니다"
  212. **`heuristics.md` Korean support added:**
  213. - **Korean terminology table** — 22 key UX terms with Korean equivalents (사용성 휴리스틱, 로딩 상태, 진행 표시기, 온보딩, 일괄 작업, etc.)
  214. - **Korean severity labels** — 🚫 차단 · 🔴 심각 · 🟡 경고 · 🟢 팁
  215. - **Korean heuristic note** — Standard report note translated
  216. - **Usability Score bands** — All four bands bilingual in the ref file
  217. - **Quick Reference Checklist** — All 19 checklist items translated (e.g. "비동기 작업 버튼에 로딩 상태 있음", "파괴적 작업에 확인 대화상자 있음")
  218. ------------------------------------------------------------------------------------------------------------------------------------------
  219. ### v1.2.8
  220. **Heuristics.md coverage — no loose ends.**
  221. - Scope declaration (H4/H5/H8/H9 explicitly excluded with reasons)
  222. - Usability Score model with bands
  223. - H1 gaps — async button loading state, form success confirmation, multi-step progress indicator
  224. - H2 — jargon/error code detection, icon meaning mismatch, locale-aware date/number formats
  225. - H3 gaps — modal close mechanism, flow back navigation, destructive action confirmation
  226. - H6 — icon-only nav, disappearing floating labels, dropdown selection visibility
  227. - H7 — keyboard shortcut hints, bulk action support, preference persistence
  228. - H10 — helper text on complex fields, actionable error messages, contextual tooltips, onboarding guidance
  229. - Quick reference checklist covering all 6 heuristics
  230. Every entry has: definition, why it matters, Figma detection, code detection, severity, fix, and context note.
  231. ------------------------------------------------------------------------------------------------------------------------------------------
  232. ### v1.2.7
  233. **URL inputs — full support added**
  234. The skill now recognises and audits from any URL type, not just Figma links.
  235. | URL Type | Confidence | How it's handled |
  236. |---|---|---|
  237. | Live website (`https://...`) | 🟡 Medium | `web_fetch`, login handling, multi-page offer |
  238. | Vercel / Netlify preview | 🟡 Medium | Same as live website |
  239. | GitHub file URL | 🟢 High | Converts to raw URL, full code audit |
  240. | GitHub repo URL | 🟡 Medium | Browses key files, scope selector widget |
  241. | CodeSandbox / StackBlitz | 🟡–🟢 | Source if accessible, preview fallback |
  242. | CodePen | 🟡 Medium | Debug URL fetch, source extraction |
  243. | Storybook | 🟡 Medium | Component/variant detection from URL path |
  244. Each URL type has a dedicated spec: how to fetch, what confidence to set, what limitations to declare in the report header, how to handle login walls, and what to offer the user after the audit.
  245. GitHub file URLs get full 🟢 High confidence — raw source is treated identically to pasted code. All other URL types get 🟡 Medium with explicit limitation notes in the report header.
  246. **Agent compliance — mandatory output enforcement**
  247. Following reports of third-party agents (e.g. TRAE Solo) producing free-form UX reviews instead of scored reports, two mandatory enforcement notices were added:
  248. - `⚠️ OUTPUT FORMAT IS MANDATORY — DO NOT DEVIATE` at the top of Step 2
  249. - `⚠️ MANDATORY — ALL AGENTS — NO EXCEPTIONS` at the top of the Strict Output Template
  250. Both explicitly prohibit substituting a generic critique for the scored report. Skipping the score is never acceptable — agents must estimate and flag with 🟡 Medium confidence if uncertain.
  251. **Input widget updated** — "Live URL" and "GitHub URL" added as input type options alongside Figma, Screenshot, and Code.
  252. **All version stamps updated** — report footers now correctly show v1.2.7.
  253. ------------------------------------------------------------------------------------------------------------------------------------------
  254. ### v1.2.6
  255. **Wireframe to Spec mode**
  256. New output mode alongside the standard audit. When a wireframe is detected (greyscale, box placeholders, skeleton fidelity), the skill offers Spec mode before running a scored audit.
  257. Produces a structured design specification: Layout & Dimensions, Spacing, Typography, Components Required (with states), Copy Placeholders, Interaction Notes, Accessibility Requirements, and an Open Questions section that surfaces gaps the wireframe doesn't answer.
  258. - No score or severity labels — Spec mode annotates, it doesn't audit
  259. - Estimated values clearly flagged with `~` prefix
  260. - Uses Figma layer data when available; falls back to standard defaults from reference files
  261. - Output as downloadable `.md` file
  262. - Auto-detected from wireframe input; also available in "What next?" widget post-audit
  263. - Triggers on: "wireframe to spec", "annotate my wireframe", "turn this wireframe into a spec", "spec out this design"
  264. **Canva visual audit report**
  265. After any audit, "Export to Canva" generates a visual report card in Canva — score rings, issue summary, top 3 fixes, positives. Stakeholder-friendly format for sharing with non-technical audiences. Separate from the full technical Markdown export.
  266. **Trigger vocabulary expanded**
  267. Wireframe-specific trigger phrases added to YAML description. Stale version stamps in report templates fixed (were showing v1.2.2).
  268. ------------------------------------------------------------------------------------------------------------------------------------------
  269. ### v1.2.5
  270. **Figma MCP — three new tools integrated**
  271. - **`get_code_connect_suggestions`** — AI-suggested Figma→code component mappings. Enriches Cat 5 and Cat 17. Flags unmapped components. Adds Code Connect line to report header.
  272. - **`get_code_connect_map`** — confirmed mappings, powers the handoff table
  273. - **`create_design_system_rules`** — generates enforcement rules for the repo, offered post-audit when token/component health is poor. Always requires explicit confirmation.
  274. **Scoring calibration — Blocker tier**
  275. | Severity | Deduction | Basis |
  276. |---|---|---|
  277. | 🚫 Blocker | −12pts | Legal/compliance — WCAG AA, GDPR, PECR |
  278. | 🔴 Critical | −8pts | Usability failure |
  279. | 🟡 Warning | −4pts | Degrades experience |
  280. | 🟢 Tip | −1pt | Polish |
  281. Blocker examples: contrast below 4.5:1 (SC 1.4.3), keyboard-inaccessible element (SC 2.1.1), missing alt (SC 1.1.1), pre-checked marketing consent (GDPR), skip link missing (SC 2.4.1).
  282. Accessibility Score updated: Blockers use −12. Any Blocker appends "⚠️ Contains legal compliance failures".
  283. **Trigger vocabulary expanded** — 15+ new phrases: "is this GDPR compliant", "check my onboarding", "review my checkout", "is this manipulative", "any dark patterns here", "is my form accessible", and more.
  284. ------------------------------------------------------------------------------------------------------------------------------------------
  285. <details>
  286. <summary><strong>v1.0.0–v1.2.4</strong> — earlier versions</summary>
  287. ### v1.2.4
  288. **New: Category 19 — Ethical Design & Dark Patterns**
  289. 20 manipulative patterns across 5 groups: Deceptive Interface, Coercive Flows, Consent & Privacy, False Urgency & Scarcity, Emotional Manipulation.
  290. Ethics severity model: 🔴 Deceptive (−15pts) · 🟡 Questionable (−7pts) · 🟢 Noted (0pts). Ethics Score shown alongside Accessibility Score.
  291. New `ethics.md` reference file — 877 lines with full pattern taxonomy, detection signals, and Ethical Persuasion reference.
  292. ------------------------------------------------------------------------------------------------------------------------------------------
  293. ### v1.2.3
  294. Code parity complete — all 17 categories now check from source code.
  295. - **Cat 3** — off-grid detection, z-index audit, padding consistency, content margin, logical properties
  296. - **Cat 16** — `<nav>` semantics, `aria-current`, skip link, tab vs nav misuse, keyboard handling, breadcrumb structure
  297. - **`spacing.md`, `navigation.md`, `animation.md`, `corner-radius.md`** — all with full code-specific audit sections
  298. ------------------------------------------------------------------------------------------------------------------------------------------
  299. ### v1.2.2
  300. - `get_design_pages` as mandatory F1.5 step — file structure before auditing
  301. - Type Scale Stack triggers on every audit — extracts font sizes directly from `get_design_context`
  302. - Component health metric in report header — coverage %, detached instances, unnamed layers
  303. - 2-frame cross-check for consistency (Cat 5)
  304. - Microcopy reads every text node, classifies by role, cites exact text + node ID
  305. - Issue deduplication — same root cause → one grouped entry
  306. - Framework detection + before/after code diffs for code input
  307. - Code superpowers added to Cat 6, 7, 8, 9, 10, 13, 17
  308. - Standardised report template with fixed sections
  309. - Re-audit spec, Explain an issue depth, Developer Handoff Report template
  310. ------------------------------------------------------------------------------------------------------------------------------------------
  311. ### v1.2.1
  312. - Scoring formula always shown in every report
  313. - Color contrast via design tokens — `get_variable_defs` drives Cat 2
  314. - `animation.md` added — full Cat 8 reference
  315. - Figma fix loop partial failure recovery
  316. - Auto-layout ops and component instance caveat in `figma-mcp.md`
  317. ------------------------------------------------------------------------------------------------------------------------------------------
  318. ### v1.2.0
  319. - 5 interactive audit widgets: Type Scale Stack, Contrast Checker, 8pt Grid Visualizer, States Coverage Map, Issue Priority Matrix
  320. - Smart defaults — scope, stage, WCAG level inferred from request
  321. - Component-type detection and confidence scoring
  322. - Session progress tracker with sparkline
  323. - Full Korean coverage
  324. ------------------------------------------------------------------------------------------------------------------------------------------
  325. ### v1.1.5
  326. - Figma Variables integration, audit goal context, WCAG level selector
  327. - Separate Accessibility Score, Developer handoff mode
  328. - Fix all Critical loop, bilingual widget labels
  329. ------------------------------------------------------------------------------------------------------------------------------------------
  330. ### v1.1.4
  331. - Audit scope selector: Full / Quick / Custom
  332. - Partial audit mode, severity filter, Markdown export
  333. ------------------------------------------------------------------------------------------------------------------------------------------
  334. ### v1.1.3
  335. - Figma MCP fallback, per-category scores, before/after diffs, re-audit delta
  336. ------------------------------------------------------------------------------------------------------------------------------------------
  337. ### v1.1.2
  338. - Deterministic scoring formula, confidence level, strict output template
  339. ------------------------------------------------------------------------------------------------------------------------------------------
  340. ### v1.1.1
  341. - Korean language support
  342. ------------------------------------------------------------------------------------------------------------------------------------------
  343. ### v1.1.0
  344. - 17 categories: added Corner Radius, Elevation, Iconography, Navigation, Design Tokens
  345. ------------------------------------------------------------------------------------------------------------------------------------------
  346. ### v1.0.0
  347. - Initial release: 13 audit categories, 7 reference files
  348. ------------------------------------------------------------------------------------------------------------------------------------------
  349. </details>
  350. ## Contributing
  351. Found a design rule that should be in here? Open an issue or PR.
  352. Areas that could use expansion:
  353. - UX flow analysis & information architecture
  354. - Data visualization & charts
  355. - Native mobile (iOS/Android) specific patterns
  356. - Print / PDF layout rules
  357. ---
  358. ## License
  359. MIT — use it, fork it, build on it.
  360. ---
  361. *Built with [Claude](https://claude.ai) · Skill format by [Anthropic](https://anthropic.com)*

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.