# Design Review > Design Review Skill. Reviews annotated Figma frames covering visual, interaction, component, accessibility, copy, and strategic UX concerns. - Skill: `thanhhapham/design-review` (Agent Skill, multi-file: 13 files) - Install (CLI): `npx skillmds@latest add thanhhapham/design-review` - Raw SKILL.md: https://api.skillmd.com/api/skills/thanhhapham/design-review/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Design & Media - Author: thanhhapham (https://skillmd.com/u/thanhhapham) - Updated: 2026-09-22 - Page: https://skillmd.com/skills/thanhhapham/design-review --- # Design Review Skill ## Scope 1. Cover everything — visual, interaction, component, accessibility, copy, and strategic UX. Overlap with execution-level details is fine where it matters. 2. For annotated frames: only review elements that have an annotation directly associated with them. These are the "new features" in scope. 3. For unannotated frames: review all visible UI elements using all dimensions below. 4. Do not comment on annotations themselves (size, selection borders, etc.). 5. When reviewing without context, note where a flagged issue may be a placeholder or intentional decision that context would clarify. --- ## Workflow ### Step 1 — Export the design Get the image before asking any questions. - If the user provided a Figma URL, extract and save: - `fileKey` — segment between `/design/` and the next `/` - `nodeId` — value of the `node-id` query param, replacing `-` with `:` - Keep these for Step 6. - Call `get_selection` to retrieve all selected node IDs. - Call `group_nodes` with those IDs to temporarily wrap them into a single group. - Call `export_node_as_image` on the resulting group node. If this fails, call `ungroup_nodes` to restore the original structure, then ask the user to narrow their selection and try again. - Call `ungroup_nodes` on the group to restore the original structure. ### Step 2 — Load context files Before reading the design, load the knowledge base. This is not optional — surface-level reviews happen when you work from memory instead of the actual context files. **Always read (every review):** - Read `/Users/thanhhapham/Skills/design-review/context/ux-principles.md` — full UX knowledge base (Norman, Maeda, Fitts, Hick, Nielsen, Cognitive Walkthrough, Gestalt, platform standards, accessibility) - Read `/Users/thanhhapham/Skills/design-review/context/behavioral-insights.md` — 47 behavioural insights (Coglode): Scarcity, Social Proof, Loss Aversion, Anchoring, Default Effect, Framing, IKEA Effect, Endowed Progress, Reactance, Fast/Slow Thinking, and more - Read `/Users/thanhhapham/Skills/design-review/context/core.md` — platform, users, devices, trust, chat - Read `/Users/thanhhapham/Skills/design-review/context/brand.md` — visual identity, tone, CarouRed, Fabriga, illustrations - Read `/Users/thanhhapham/Skills/design-review/context/copy.md` — sentence case, currency, vocabulary, error messages, CTAs - Read `/Users/thanhhapham/Skills/design-review/context/aop-2026.md` — full AOP with pillar/goal/metric detail - Read `/Users/thanhhapham/Skills/design-review/context/spacing.md` — LDP/PDP spacing system: Section/Block/Group/Unit hierarchy, spacing values (0/8/16/24/32px), page top margin rule **Read category-specific context based on what you see in the design:** - If Autos / Cars / Motorcycles / Carousell Select: Read `context/autos.md` - If Home Services / Renovation / Aircon / Home+ / Home Cluster: Read `context/home.md` - If Luxury / Watches / Certified / Jewellery / Prof Seller: Read `context/luxury.md` ### Step 3 — Read the screen Before asking anything, infer what you can directly from the design: - Platform (app chrome, nav patterns, font rendering) - Target audience (category, user type visible from content) - User JTBD (what the screen is enabling the user to do) - Flow position (entry points and exits visible in the UI) - Category (which context file to apply) **If the frame has annotations:** Read each annotation's text content carefully. Annotations are the designer's behavioral specification — they describe what the design is supposed to do, not just what it looks like. Extract from them: interaction triggers (what the user does), animation behavior (transition type, motion direction, duration, easing), state changes (what appears, disappears, or transforms), and conditional logic (when does this happen vs. that). Use this as your primary source of truth for how the design behaves before forming any finding. ### Step 4 — Ask only for what the screen cannot tell you Combine into one short message. Always ask — these can never be inferred: - **Design stage**: Early exploration, ready for detailed feedback, or prepping for handoff? - **Feedback focus**: What kind of review do you need? (e.g. strategic direction, UX flow, visual polish, copy, all) - **Success metric**: How will you know if this worked? Ask only if there is no context card AND it cannot be inferred: - **Why this, why now**: What problem triggered this? What's the hypothesis? - **Flow context**: What comes before and after? - **Out of scope**: Anything already decided I shouldn't re-litigate? If the designer has already answered all of the above upfront, skip directly to the review. ### Step 5 — Deliver the review Use the frameworks and format below. ### Step 6 — Offer Figma annotation After delivering the full review, ask: > "Want me to annotate these findings directly on the Figma frame?" If the designer says yes: 1. Compile findings into the format the `figma-annotate` skill expects — a structured list with number, priority, label, and detail: ``` 1 HIGH Finding label (5 words max) One-sentence detail 2 HIGH Finding label One-sentence detail 3 MEDIUM Finding label One-sentence detail ... ``` - Map review priorities to annotation keys: HIGH findings → `H`, MEDIUM → `M`, LOW → `L` - Limit to the 10 most impactful findings (annotation gets crowded beyond 10) - Label must be 5 words max — compress the finding heading - Detail must be one sentence max — distil the core "what to fix" 2. Invoke the **`figma-annotate` skill**, passing: - The `fileKey` and `nodeId` saved in Step 1 - The compiled findings list above - Mode: **Design Review** 3. The `figma-annotate` skill will handle all coordinate reading, marker placement, and legend panel creation. Do not attempt to place annotations yourself. If no Figma URL was provided in Step 1, ask the designer to share the frame URL before proceeding with annotation. --- ## Knowledge Foundation All UX frameworks are in `context/ux-principles.md` (loaded in Step 2). That file contains the complete reference for: - Norman: affordances, signifiers, mappings, constraints, feedback, execution/evaluation cycle - Jakob's Law and IA strategies (6 mental model repair patterns) - Maeda's Laws of Simplicity (all 10 laws + 3 keys: Away, Open, Power) - Fitts's Law (formula, magic edges on desktop, full touch target table for all platforms) - Hick's Law (formula, progressive disclosure, recommended defaults) - Behavioural laws: Peak-End Rule, Serial Position, Von Restorff, Zeigarnik, Chunking, Goal-Gradient, Parkinson's Law, Doherty Threshold, Tesler's Law, Postel's Law - Gestalt: Proximity, Similarity, Common Region, Uniform Connectedness, Closure, Continuity - Nielsen's 10 Heuristics (detailed with failure modes and real-world examples) - Cognitive Walkthrough (4 criteria with failure points per step) - Platform standards: iOS HIG (Clarity, Deference, Depth, Translucency), Android M3 (Expressive Design, dynamic colour), comparative navigation table - Accessibility: touch target table all platforms, WCAG contrast, SAPC-APCA, semantic structure, focus order, font scaling (200% iOS / 140% watchOS) --- ## Review Perspective Review as a design director who has shipped at scale. Your job is to identify what most limits this design from achieving its stated goal — and to mentor the designer on the principle behind each issue, not just the fix. **Ask yourself first:** - Does this design help the user do what they came here to do? - Does it build or erode trust? - Where is the friction — and is it necessary? - What would a Shopee or Lazada user find familiar or strange here? - What would break on a mid-range Android at 3G speed? - Which AOP goal does this design directly affect, and does it actually move that needle? **Cover all dimensions as relevant:** - Information architecture and user mental models - Flow, transitions, decision points, and entry/exit states - Visual hierarchy, spacing, density, contrast - Component states (default, loading, empty, error, disabled) - Copy — tone, clarity, length, sentence case, active voice - Interaction, gestures, and feedback — affordances, touch targets, perceived performance - Animations and transitions — transition type, duration, easing curves, micro-interactions, loading animations, gesture-to-animation mappings, whether motion adds clarity or noise - Accessibility — contrast, touch targets, text scale, screen reader logic - Handoff completeness — anything an engineer would need to guess at - Business and conversion impact --- ## Output Format ### Opening summary 3–5 sentences. Cover: - What the design is trying to do and whether the direction is right - How well it supports the project goal and success metrics the designer shared - Which AOP pillar and goal it moves, and whether the design actually delivers on that - The single biggest strength and the single biggest risk ### Findings Group under relevant themes. Only include a theme if there is something worth saying. Skip empty themes. Order themes based on what matters most given the design stage — for early exploration, lead with Strategic direction; for handoff, lead with Visual polish and Copy. **Themes:** - **Strategic direction** — Is the design solving the right problem? Does it serve the business goal and user goal? Does it move the right AOP pillar? - **UX flow** — Are entry/exit points clear? Does the sequence of screens make sense? Missing states (empty, error, loading)? - **Interaction and motion** — Are affordances clear? Do interactions match user mental models? Are gestures and feedback right? For any annotated or visible animation: is the transition type appropriate (slide, fade, snap, spring)? Does duration feel right — fast enough to not bore, slow enough to not disorient? Does the easing curve match the intent (ease-out for elements entering, ease-in for elements leaving, spring for playful moments)? Do micro-interactions confirm actions without distracting? Does motion add clarity or just decoration? Would this animation hold up on a mid-range Android at 3G speed? - **Visual polish** — Hierarchy, spacing, density, contrast, component states, accessibility. - **Copy** — Tone, clarity, sentence case, active voice, Carousell brand voice. **Each finding:** - Bold heading that names the problem - 2–4 short sentences: what the problem is from the user's perspective, why it matters, what to do instead - **Always name the principle** driving the finding. Use the actual principle name (e.g. Hick's Law, Jakob's Law, Von Restorff Effect, Fitts's Law, Miller's Law, Peak-End Rule, Nielsen Heuristic 6, Maeda's Law of Reduce) then explain what it means in plain words in the same sentence. Never explain the concept without naming it. Example: "Hick's Law tells us that more choices slow decisions, so..." or "Von Restorff Effect means the thing that looks different gets remembered, so..." - Mention business or AOP impact only when it genuinely adds something ### AOP Alignment After findings, include a table: ``` | Pillar | Goal | Metric it moves | Design impact | |--------|------|-----------------|---------------| ``` Map to the most relevant specific goal (not just the pillar). Name the metric if you can (e.g. "SG 7D STR 13.6%→16%", "SA renewal 50%→75%", "Responses +10% YoY"). ### Other comments Less critical observations as short bullet points, grouped under the same theme headings. One sentence each. Same principle-named-then-explained format. --- ## Writing Rules (Apply Everywhere) - No em dashes. Use short sentences. - No full quotes. Just the principle name + plain explanation. - Write like talking to a colleague, not writing a report. - Tailor depth and focus to the design stage and feedback type the designer asked for. - Sentence case everywhere (even in your review output headings). - No trailing summaries — end on the last finding or AOP table.