# Design > [Design] Use when creating or describing a UI design. Flags: --mode={fast|good|describe|screenshot|video} (default fast), --lane={product|marketing} (default product). - Skill: `duc01226/design-2` (Agent Skill, multi-file: 29 files) - Install (CLI): `npx skillmds@latest add duc01226/design-2` - Raw SKILL.md: https://api.skillmd.com/api/skills/duc01226/design-2/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Marketing & Growth - Author: duc01226 (https://skillmd.com/u/duc01226) - Updated: 2026-09-21 - Page: https://skillmd.com/skills/duc01226/design-2 --- ## Quick Summary **Goal:** Create (or describe) a UI design using design-intelligence databases and subagents, dispatched by `--mode` (input carrier) × `--lane` (design lane). > **Renamed:** folds the former `/design-fast`, `/design-good`, `/design-describe`, `/design-screenshot`, `/design-video` skills into `--mode={fast|good|describe|screenshot|video}` — those names no longer resolve as slash commands; use `/design --mode=…`. > > **Absorbed lanes:** the former `frontend-design` (marketing/creative) and `interface-design` (product-UI) skills now fold into `--lane={marketing|product}` — those names no longer resolve as slash commands; use `/design --lane=…`. Each lane's full body lives under `references/lane-{marketing,product}/lane-guide.md`. **Mode dispatch:** `--mode={fast|good|describe|screenshot|video}` — default `fast` when omitted. **Lane dispatch:** `--lane={product|marketing}` — default `product` when omitted. Lane (the design tradition) is orthogonal to mode (the input carrier); any mode combines with any lane. | Lane | Use for | Full body | | --------------------- | ----------------------------------------------------------------------- | --------- | | `product` (default) | dashboards, admin panels, SaaS apps, tools, settings, data interfaces | `references/lane-product/lane-guide.md` | | `marketing` | landing pages, marketing sites, campaigns, distinctive creative pieces | `references/lane-marketing/lane-guide.md` | | Mode | Input carrier | Output | | --------------------- | --------------------------- | ----------------------------------------------------------- | | `fast` (default) | text brief | quick prototype implementation | | `good` | text brief | immersive, researched, higher-quality implementation | | `describe` | screenshot / video | super-detailed written description + implementation plan (NO code) | | `screenshot` | screenshot | design recreated from the image as functional code | | `video` | video | design + interactions recreated from the video as functional code | **Shared workflow (5-stage spine):** 1. **Research** — Run `ui-ux-pro-max` searches for design intelligence (ALWAYS FIRST) 2. **Ingest** — For visual modes (`describe`/`screenshot`/`video`), use `visual analysis tooling` to analyze the screenshot/video in super-detail 3. **Design** — Use `ui-ux-designer` subagent to create the design (or, for `describe`, an implementation plan), applying the selected lane's craft body 4. **Implement** — Build as code following the selected lane guide: `references/lane-product/lane-guide.md` (product UIs) or `references/lane-marketing/lane-guide.md` (marketing/creative). Skipped in `describe` mode. 5. **Document** — Present to user for approval; update `./docs/design-guidelines.md` if needed **Key Rules:** - Always activate `ui-ux-pro-max` FIRST for design intelligence - Default to pure HTML/CSS/JS if the user doesn't specify a framework - Use `visual analysis tooling` for generating AND reviewing real visual assets - Use media processing tooling (RMBG) to remove backgrounds from generated assets when needed **Be skeptical. Apply critical thinking, sequential thinking. Every claim needs traced proof, confidence percentages (Idea should be more than 80%).** ## Arguments & Mode Dispatch `/design --mode={fast|good|describe|screenshot|video} --lane={product|marketing} ` - When `--mode` is omitted, default to `--mode=fast`. - When `--lane` is omitted, default to `--lane=product` (the dominant PBI/app use). Pick `marketing` for landing pages, campaigns, and distinctive creative pieces. - `--mode` (input carrier) and `--lane` (design tradition) are orthogonal — e.g. `--mode=screenshot --lane=product` recreates a dashboard screenshot in the product-UI craft tradition. - `$ARGUMENTS` carries the full input after the command. Interpret it per mode: `fast`/`good` → a text design brief; `describe`/`screenshot` → a screenshot reference (path/URL/attachment); `video` → a video reference. ### Lane selection (apply the chosen lane's craft body at stages 3-4) - **`--lane=product` (default)** — product UIs: dashboards, admin panels, SaaS apps, tools. Domain-driven craft (intent → domain exploration → signature → layered surfaces/tokens). Full body: `references/lane-product/lane-guide.md`. - **`--lane=marketing`** — marketing/creative: landing pages, campaigns, screenshot replication. Bold aesthetic direction (distinctive type, cohesive palette, atmosphere, motion). Full body: `references/lane-marketing/lane-guide.md`. Do NOT inline the lane bodies here — read the matching `lane-guide.md` when the lane is selected. ## Required Skills (Priority Order) 1. **`ui-ux-pro-max`** — Design intelligence database (ALWAYS ACTIVATE FIRST) 2. **In-skill lane references** — `references/lane-{product|marketing}/lane-guide.md` (+ their reference files) own implementation, screenshot/video analysis, and design replication for the selected lane. **Ensure token efficiency while maintaining high quality.** ## Shared First Step (ALL modes) > **[BLOCKING] Step 0 — Understand the existing UI first** (per the `SYNC:existing-ui-research` protocol carried by this skill). Before designing or updating any screen/component, inventory the existing related UI (screens, pages, components already serving this feature/domain) and map every connected feature flow that links to / embeds / navigates to-or-from it, so the design faithfully matches the current UI system. Skip only for non-UI work (state it explicitly). **FIRST**, run `ui-ux-pro-max` searches to gather design intelligence: ```bash python $HOME/.claude/skills/ui-ux-pro-max/scripts/search.py "" --domain product python $HOME/.claude/skills/ui-ux-pro-max/scripts/search.py "" --domain style python $HOME/.claude/skills/ui-ux-pro-max/scripts/search.py "" --domain typography python $HOME/.claude/skills/ui-ux-pro-max/scripts/search.py "" --domain color ``` ## Design Principles Contract (all modes) The 40 UI/UX Design Principles (`UI-1.1`–`UI-9.4`) carried as the `SYNC:ui-ux-design-principles` block below bind EVERY mode of this skill. Project design-system docs OUTRANK them — surface a genuine conflict to the user with both sides, NEVER resolve it silently. **Generative modes (`fast`, `good`) — APPLY the clauses as an output contract on the design you produce:** 1. **States first.** Design and build the empty, loading and error state BEFORE the populated state (`UI-1.5`), and reserve space for anything that loads so nothing shifts in (`UI-9.3`). 2. **All 5 interaction states per interactive element** — default, hover, focus, active, disabled — plus loading where it applies (`UI-5.2`); keep a visible focus ring, restyled if it clashes but NEVER removed (`UI-5.5`). 3. **Declare the scales, never improvise them.** State the type scale as 6 named steps with no one-off sizes (`UI-2.5`), body 16px web / 17px mobile and never below 14px (`UI-2.2`), measure 45–75 characters (`UI-2.3`); and declare ONE spacing unit — 4px or 8px base, every gap a multiple of it (`UI-4.1`). Both declarations belong in the summary you report back at stage 5; an undeclared scale is an incomplete design, not a style choice. 4. **Contrast is measured, not eyeballed** — state the target AND the measured value: 4.5:1 text, 3:1 UI edges (`UI-3.1`); colour NEVER carries meaning alone — pair it with an icon, label or position (`UI-3.3`). 5. **Touch surfaces.** When the design covers a mobile/touch surface, hit targets are ≥44×44pt and 8px apart (`UI-8.1`) and primary actions sit in the bottom third where the thumb lives (`UI-8.2`). When it does not, state that explicitly so the §8 skip is auditable. **Reporting modes (`describe`, and the analysis pass of `screenshot` / `video`) — REPORT against the clauses:** the super-detailed description MUST name which clauses the OBSERVED design SATISFIES and which it VIOLATES, cited by ID — e.g. type-scale drift (`UI-2.5`), contrast failure with the measured ratio (`UI-3.1`), undersized touch targets (`UI-8.1`), missing empty/loading/error states (`UI-1.5`), a removed focus ring (`UI-5.5`). A violation is RECORDED, never silently reproduced: `describe` carries it into the implementation plan as a correction; `screenshot` / `video` then apply the five generative obligations above so the recreation FIXES the violation rather than inheriting it — flag any correction that changes the visual match and confirm it with the user before shipping it. ## Mode Branches ### `--mode=fast` (default) — quick design 1. Run the shared `ui-ux-pro-max` searches above. 2. Use `ui-ux-designer` subagent to start the design process. 3. If the user doesn't specify, create the design in pure HTML/CSS/JS. 4. Report back with a brief summary of the changes; ask the user to review and approve. 5. On approval, update `./docs/design-guidelines.md` if needed. ### `--mode=good` — immersive, high-quality design Same spine as `fast`, raised to a higher quality bar (iterate on details): 1. Run comprehensive `ui-ux-pro-max` searches across all domains. 2. Use `researcher` subagent to research design style, trends, fonts, colors, borders, spacing, elements' positions, etc. 3. Use `ui-ux-designer` subagent to implement the design step by step based on the research. 4. If the user doesn't specify, create the design in pure HTML/CSS/JS. 5. Report back with a summary; ask the user to review and approve. 6. On approval, update `./docs/design-guidelines.md` if needed. - **ALWAYS REMEMBER you have the skills of a top-tier UI/UX Designer who won many awards on Dribbble, Behance, Awwwards, Mobbin, TheFWA.** - Create storytelling designs, immersive 3D experiences, micro-interactions, and interactive interfaces. ### `--mode=describe` — describe only (NO implementation) Treat `$ARGUMENTS` as the screenshot/video to describe. 1. Use `visual analysis tooling` to describe super-details of the screenshot/video so a developer can implement it easily. - Be specific about design style, every element, elements' positions, every interaction, every animation, every transition, every color, every border, every icon, every font style/size/weight, every spacing/padding/margin, every size/shape/texture/material/light/shadow/reflection/refraction/blur/glow/image, background transparency, etc. - **IMPORTANT:** Predict the font name (Google Fonts) and font size — don't just use Inter or Poppins. 2. Use `ui-ux-designer` subagent to create a design implementation **plan** following the progressive-disclosure structure so the result matches the screenshot/video: - Create a directory using the naming pattern from the `## Naming` section. - Save the overview access point at `plan.md`, keep it generic, under 80 lines, listing each phase with status/progress and links. - For each phase, add `phase-XX-phase-name.md` with sections (Context links, Overview with date/priority/statuses, Key Insights, Requirements, Architecture, Related code files, Implementation Steps, Todo list, Success Criteria, Risk Assessment, Security Considerations, Next steps). 3. Report back with a summary of the plan. **Do NOT implement.** ### `--mode=screenshot` — recreate from image as code Treat `$ARGUMENTS` as the screenshot to recreate exactly. 1. Use `visual analysis tooling` to describe super-details of the screenshot (design style, trends, fonts, colors, border, spacing, elements' positions, size, shape, texture, material, light, shadow, reflection, refraction, blur, glow, image, background transparency, transition, etc.). - **IMPORTANT:** Predict the font name (Google Fonts) and font size — don't just use Inter or Poppins. 2. Use `ui-ux-designer` subagent to create a design plan following the progressive-disclosure structure (as in `describe`) so the final result matches the screenshot. Keep every research markdown report concise (≤150 lines). 3. Implement the plan step by step. 4. If the user doesn't specify, create the design in pure HTML/CSS/JS. 5. Report back with a summary; ask the user to review and approve. 6. On approval, update `./docs/design-guidelines.md` if needed. - **ALWAYS REMEMBER you have the skills of a top-tier UI/UX Designer who won many awards on Dribbble, Behance, Awwwards, Mobbin, TheFWA.** - Create storytelling designs, immersive 3D experiences, micro-interactions, and interactive interfaces. ### `--mode=video` — recreate from video as code Treat `$ARGUMENTS` as the video to recreate exactly. Same as `--mode=screenshot`, but ingest a VIDEO and capture BOTH static layout AND interaction/animation/transition patterns. 1. Use `visual analysis tooling` to describe super-details of the video: every element, every interaction, every animation, every transition, every color, every font, every border, every spacing, every size/shape/texture/material/light/shadow/reflection/refraction/blur/glow/image, background transparency, etc. - **IMPORTANT:** Predict the font name (Google Fonts) and font size — don't just use Inter or Poppins. 2. Use `ui-ux-designer` subagent to create a design plan following the progressive-disclosure structure so the final result matches the video. Keep every research markdown report concise (≤150 lines). 3. Implement the plan step by step. 4. If the user doesn't specify, create the design in pure HTML/CSS/JS. 5. Report back with a summary; ask the user to review and approve. 6. On approval, update `./docs/design-guidelines.md` if needed. - **ALWAYS REMEMBER you have the skills of a top-tier UI/UX Designer who won many awards on Dribbble, Behance, Awwwards, Mobbin, TheFWA.** - Create storytelling designs, immersive 3D experiences, micro-interactions, and interactive interfaces. ## Notes (all modes) - **Design system (canonical):** When implementing UI — HTML, CSS, or SCSS — read the project canonical design-system doc `docs/project-reference/design-system/design-system-canonical.md` first for design tokens, component patterns, and BEM conventions. Prefer `designSystem.canonicalDoc` + `tokenFiles` (resolved from `docs/project-config.json`) over per-app docs for new design work. - Remember you have the capability to generate images, videos, edit images, etc. with `visual analysis tooling` skills. Use them to create the design and real assets. - Always review, analyze, and double-check generated assets with `visual analysis tooling` skills to verify quality. - Use media processing tooling (RMBG) to remove background from generated assets if needed (`good`/`screenshot`/`video`). - Maintain and update `./docs/design-guidelines.md` docs if needed. --- > **[IMPORTANT]** Use `TaskCreate` to break ALL work into small tasks BEFORE starting — including tasks for each file read. This prevents context loss from long files. For simple tasks, AI MUST ATTENTION ask user whether to skip. Think hard to plan & start working on these tasks follow the Orchestration Protocol, Core Responsibilities, Subagents Team and Development Rules. Parse `--mode` from the input (default `fast`) and route to the matching branch above: $ARGUMENTS > **[BLOCKING] Understand the existing UI before you design or spec a new/updated screen.** Before producing any wireframe, mockup, screen design, or UI spec: > > 1. **Inventory existing related UI** — search the project for screens, pages, and components already serving this feature or its domain (consult design-system docs + the real component inventory). > 2. **Map connected flows** — identify every feature that links to, embeds, includes, or navigates to/from the new screen; trace its entry and exit flows so the new screen fits them. > 3. **Reuse before invent** — prefer existing components, patterns, and layout conventions; justify any new component against what already exists. > 4. **Record findings** — note the matched existing screens/components + connected flows in the artifact so downstream design faithfully matches the current UI system. > > **Skip ONLY** when the feature is backend-only (no UI) — state that explicitly. > **UI/UX Design Principles (Rev 1.0 — 40 clauses, web + mobile)** — the working rule set for ANY task that designs, plans, implements, or reviews a user interface. Applies to BOTH platforms unless a clause names one (§8 is mobile/touch). Cite clauses by ID: `UI-3.1`, `UI-8.2`. > > **Precedence:** project design-system / SCSS / frontend-pattern docs OUTRANK these clauses; these clauses outrank generic taste. A genuine conflict is SURFACED to the user with both sides — NEVER resolved silently. — why: the project's own recorded decision is the authority; these clauses are the default when it is silent. > > **1.0 Visual Hierarchy & Layout** > > - `UI-1.1` One focal point per screen. Two elements competing for first read → demote one. > - `UI-1.2` Signal order: size → weight → colour → position. Use the cheapest signal that works before adding another. > - `UI-1.3` Group by proximity, NEVER by border. Whitespace separates cleanly; boxes inside boxes do not. > - `UI-1.4` Align to a shared edge. Every unexplained indent reads as an accident. > - `UI-1.5` Design the empty, loading and error state FIRST. The full state is the easy one. > > **2.0 Typography** > > - `UI-2.1` Max 2 families, 3 weights each. More variety reads as inconsistency, not range. > - `UI-2.2` Body text 16px web, 17px mobile. NEVER below 14px for anything a user must read. > - `UI-2.3` Line length 45–75 characters. Constrain the measure, not the container. > - `UI-2.4` Leading scales inversely with size: 1.5 body, 1.1–1.2 display. > - `UI-2.5` Fixed type scale — 6 named steps shared with engineering. NEVER one-off sizes. > > **3.0 Colour & Contrast** > > - `UI-3.1` Contrast 4.5:1 text, 3:1 UI edges. Measure it — NEVER judge by eye on a bright screen. > - `UI-3.2` One accent, one job. An accent that is everywhere points at nothing. > - `UI-3.3` Colour NEVER carries meaning alone — pair it with an icon, label or position. > - `UI-3.4` Dark mode is NOT inverted light mode. Lift surfaces to signal elevation; soften pure-white text. > > **4.0 Spacing & Grid** > > - `UI-4.1` One spacing unit, multiplied — 4px or 8px base; every gap a multiple of it. > - `UI-4.2` Space belongs to the container, not the child. Use `gap`; reserve margins for exceptions. > - `UI-4.3` Tighter inside, looser between — inner padding always smaller than the gap to the next group. > - `UI-4.4` Breakpoints follow content, not devices. Break where the layout stops working. > > **5.0 Interaction & Feedback** > > - `UI-5.1` Every action gets a response under 100ms, even when the result takes longer. > - `UI-5.2` Specify all 5 states — default, hover, focus, active, disabled — plus loading where it applies. > - `UI-5.3` Prefer undo over confirmation. Confirm ONLY what cannot be reversed. > - `UI-5.4` Motion clarifies cause and effect: 150–250ms, ease-out, honours reduced-motion. > - `UI-5.5` Keep the visible focus ring. Restyle it if it clashes; NEVER remove it. > > **6.0 Navigation & IA** > > - `UI-6.1` Every screen answers: where am I, what's here, where next. > - `UI-6.2` Max 5 top-level destinations. Depth beats a crowded first level. > - `UI-6.3` Label by the user's word, not the internal one. Team vocabulary is not a taxonomy. > - `UI-6.4` Every state deserves a URL or a back path. Deep links and hardware back must land somewhere sensible. > > **7.0 Forms & Input** > > - `UI-7.1` Ask for less. Every field needs a reason it exists today. > - `UI-7.2` Labels stay visible. Placeholders are hints, NEVER labels. > - `UI-7.3` Validate on blur, not on keystroke. Errors sit next to the field and say how to fix it. > - `UI-7.4` Match keyboard to data type — correct input type, autocomplete and autocapitalise on every field. > - `UI-7.5` NEVER lose entered data. Preserve input across errors, navigation and refresh. > > **8.0 Mobile & Touch** _(mobile/touch surfaces)_ > > - `UI-8.1` Hit target ≥44×44pt, 8px apart. The target may exceed the visible icon. > - `UI-8.2` Primary actions in the bottom third — that is where the thumb lives. > - `UI-8.3` Gestures are shortcuts, NEVER the only route. Anything swipeable is also tappable. > - `UI-8.4` Respect safe areas and the keyboard. Notch, home indicator and on-screen keyboard all steal space. > > **9.0 Speed & Perceived Speed** > > - `UI-9.1` Show structure before data — skeletons for known layouts, spinners only for unknown waits. > - `UI-9.2` Assume success optimistically. Update UI first, reconcile after, roll back visibly on failure. > - `UI-9.3` Reserve space for anything that loads. Images, ads and fonts must NEVER shift the layout. > - `UI-9.4` Design for the slow connection. Offline, timeout and retry are states, NOT edge cases. > > **Apply by role** — the clauses are one set; what you DO with them depends on the task: > > | Role | Obligation | > | ----------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | > | DESIGN / PLAN a surface | Clauses shape the artifact: empty/loading/error specified first (`UI-1.5`), all 5 states enumerated (`UI-5.2`), type scale + spacing unit declared (`UI-2.5`, `UI-4.1`) | > | IMPLEMENT a component | Pre-completion gate: states · tokens · contrast · focus ring · touch target · reserved space (`UI-5.2`, `UI-2.5`/`UI-4.1`, `UI-3.1`, `UI-5.5`, `UI-8.1`, `UI-9.3`) | > | REVIEW UI code or a design artifact | Each clause is a fail-condition; every finding cites `UI-` + `file:line` + severity. NEVER a tick-box sweep — one focused pass per section | > | SCAN / document a UI system | Record where the PROJECT deliberately deviates, so the overriding doc becomes the recorded authority | > > **Skip ONLY** when the change has no user-facing surface (backend-only, tooling, docs) — state that explicitly so the skip is auditable, not an omission. > **AI Mistake Prevention** — Failure modes to avoid on every task: > > **Re-read files after context changes.** Context compaction, resume, or long-running work can make memory stale; verify current files before acting. > **Verify generated content against source evidence.** AI hallucinates APIs, names, claims, and document facts. Check the relevant source before documenting or referencing. > **Check downstream references before deleting or renaming.** Removing an artifact can stale docs, generated mirrors, configs, and callers; map references first. > **Trace the full impact chain after edits.** Changing a definition can miss derived outputs and consumers. Follow the affected chain before declaring done. > **Verify ALL affected outputs, not just the first.** One green check is not all green checks; validate every output surface the change can affect. > **Assume existing values are intentional — ask WHY before changing OR flagging one as a defect.** Before changing or reporting a constant, limit, flag, cutoff, wording, or pattern, read nearby context and history, the CALLER's ordering, and 2+ sibling call sites of the same convention. A doc stating WHAT without WHY is missing rationale, not proof of a missing guard. > **Surface ambiguity before acting — don't pick silently.** Multiple valid interpretations require an explicit question or stated assumption with risk. > **Assert the outcome your system owns, not the intermediate state your infrastructure owns.** When verifying async work, assert the final business state — never the delivery/retry bookkeeping held in shared infrastructure that any co-running process can write. Such a check passes when run alone and flakes the moment anything else shares that infrastructure. > **Keep shared guidance role-relevant.** Universal guidance must help every receiving skill or agent; code-specific obligations belong only in code-specific protocols. > **Critical Thinking Mindset** — Apply critical thinking, sequential thinking. Every claim needs traced proof, confidence >80% to act. > **Anti-hallucination:** Never present guess as fact — cite sources for every claim, admit uncertainty freely, self-check output for errors, cross-reference independently, stay skeptical of own confidence — certainty without evidence root of all hallucination. > **[BLOCKING] Design distinctiveness gate (`DD-1`–`DD-8`) — binds on ANY task that designs, plans, mocks up, implements, or reviews a user-facing visual surface.** Deep catalog: `.claude/docs/design-knowledge.md`. Cite findings as `DD-` + `file:line`. > > **Precedence (resolve in this order, never silently):** the **brief's own stated visual direction WINS outright** — including when it asks for one of the `DD-4` tells. Then the **project's design-system / SCSS / frontend-pattern docs and accepted ADRs** — a house style IS an intentional identity, and re-deciding it per feature is the incoherence this gate prevents. Then these clauses. A genuine conflict is SURFACED to the user with both sides, NEVER resolved silently. > > **Relationship to `UI-1.1`–`UI-9.4`:** a different question, no overlap — the 40 clauses ask _"is this usable, accessible, consistent?"_ (a measurable floor); this gate asks _"is this THIS product's interface, or the one any generator would emit for any brief?"_. A surface can pass all 40 clauses and still be a template. BOTH bind; where they touch (type scale, colour, motion timing) the clause sets the floor and this gate picks the value. > > - `DD-1` **Ground it in the subject matter.** Before designing, name the concrete subject, the audience, and the design's primary job — and CONFIRM with the user when the brief is silent. Distinctive choices come FROM the subject's industry, materials and vernacular; they are never taste applied on top. **Test: if the palette, type and layout would fit a different product unchanged, there is no identity yet.** > - `DD-2` **Every choice carries a WHY.** "It's common", "it's clean", "users expect it" are not reasons. A decision with no articulable reason is a default that arrived unnoticed. Defaults hide in what feels like infrastructure — typography, navigation, data display, and TOKEN NAMES. **Token-name test: someone reading only your CSS variables should be able to guess what product this is** (`--ink`/`--parchment` evoke a world; `--gray-700`/`--surface-2` evoke a template). > - `DD-3` **Two passes, and the review pass is mandatory.** (1a) Write a compact **design plan** — Colour (4–6 named hex values) · Type (families + roles + scale) · Layout (one-sentence prose + ASCII wireframes to compare alternatives, including alignment: left/centre/justified) · Principles (what makes THIS page unique). (1b) **BLOCKING generic test — before any code:** work through a similar prompt and see whether you arrive somewhere similar; **any part that reads like the generic default for any comparable page rather than a choice for THIS brief gets REVISED, and you state what you changed and why.** Then (2a) build the REVISED plan, (2b) critique. — why: writing a plan and going straight to code reproduces the default, because the plan came from the same patterns the code will. > - `DD-4` **Audit every FREE axis against the generated-design tell catalog** (`[model-knowledge]`, calibration not prohibition — each trait is legitimate for SOME brief): **T1** cream `#F4F1EA` + high-contrast serif + terracotta near `#D97757` (Anthropic's own interaction accent — on a user's brief it reads specifically as a tell) · **T2** near-black + one acid-green/vermilion accent · **T3** broadsheet hairline-rule pastiche, zero radius, dense columns · **T4** the SaaS-card kit: identical rounded cards, ONE radius regardless of hierarchy, the same `rgba(0,0,0,.1)` shadow under each, gradient washes as decoration · **T5** template chrome whatever the subject: tracked-out ALL-CAPS eyebrow above every heading, meta strings joined with middle dots (`A · B · C`), `WORD — fragment` labels with a spaced em dash, tinted near-black (`#0B0B0B`/`#111`) standing in for black, monospace for small data labels, `→` appended to link/button text. **A match is a HYPOTHESIS about a missed decision, never a defect** — promote it only by naming the axis, that the brief left it free, and what the subject suggested instead. > - `DD-5` **Typography carries the personality.** One family, or two CLEARLY distinct ones — you do NOT need separate display and body faces. Choose deliberately, not the default you would reach for on any project. Set a real scale with intentional weights, widths and spacing. When type is a headline it is an ACTIVE part of the design, not a neutral delivery vehicle. Measure under ~80 characters; serifs tolerate slightly longer lines and want slightly more line-height than sans at the same size. Hierarchy needs weight/tracking/opacity, not size alone. **Avoid the three commonest tells: accenting a single word in a headline (italic/bold/colour) · ALL CAPS labels · an eyebrow label that names the section the heading already names.** > - `DD-6` **Structure is information, not decoration.** Outlines, borders, numbering, eyebrows, dividers and labels must encode something about the content. **Before adding numbered markers (`01 / 02 / 03`), check the content really IS a sequence** — a stepped process, timeline or ranking. For every device ask: what does this tell the reader that whitespace would not? Nothing → cut it. **Hero:** open with the most characteristic thing in the subject's world, in whatever form fits (headline, image, animation, live demo, interactive moment) — big-number-plus-small-label-plus-gradient is the DEFAULT treatment, so use it only when it is genuinely best here. **Composition:** rhythm over monotone (same card size, same gap, same density everywhere is the sound of no one deciding); proportions must say something you can articulate; one dominant focal point. > - `DD-7` **Motion sparingly and deliberately.** Non-user-triggered motion draws attention ONLY. One orchestrated moment — a single page-load sequence or one reveal — lands better than scattered effects; **fade-and-slide-up entrances on each section and hover transitions on every card are the generic default and read as generated.** Motion that ANSWERS a person's action (opening, expanding, confirming) is welcome when it shows what changed. Honour `prefers-reduced-motion`. > - `DD-8` **Spend boldness once, then remove one accessory.** Let ONE element be the memorable thing and keep everything around it quiet and disciplined; cut any decoration that does not serve the brief. **Critique the BUILT page, not just the plan** — composition, craft (density is a decision, not a constant), content coherence, and CSS honesty (negative margins undoing a parent's padding, `calc()` values that exist only as workarounds, absolute positioning to escape layout flow are lies; the correct answer is always simpler than the hack). Take screenshots to review where the environment supports it — a picture is worth 1000 tokens. Then ask "if they said this lacks craft, what would they point to?" and fix that. **Build the quality floor in silently** — responsive, visible keyboard focus, reduced-motion respected, measured contrast, tokens never raw hex or magic numbers — and watch CSS selector specificity, where a type-based selector (`.section`) and an element-based one (`.cta`) most often cancel each other's padding/margin. > > **Memory:** vary between briefs — light and dark, families, direction. NEVER converge on the same choice across generations (Space Grotesk, for example). Where the project already has a design system, tokens, or an `interface-system.md`, ADOPT and record it rather than re-deciding; write back any pattern used 2+ times with measurements worth remembering. > > **Skip ONLY** when the change has NO user-facing visual surface (backend-only, tooling, docs) — state that reason explicitly so the skip is auditable, not an omission. > **Words are design content, not decoration** — binds whenever a task authors, changes, or reviews user-visible strings (labels, CTAs, headings, empty/error/loading text, toasts, placeholder content). Deep detail: `.claude/docs/design-knowledge.md` §8. Copy makes a design feel as templated as the visuals do. > > Before writing anything, ask what the design needs to SAY and how it can best be said to help the person navigate the experience. Then: > > 1. **Write from the end user's perspective.** Name things by what users will understand in simple language, not by how the system is built — a user manages **notifications**, not **webhook config**. Describe what something is or does in plain terms rather than selling it. Being specific and legible to a new user ALWAYS beats being clever. > 2. **Active voice by default.** A CTA says exactly what happens when it is used: **"Save changes"**, NEVER "Submit". > 3. **One name per action, across the whole flow.** The button that says **Publish** produces a toast that says **Published**. The vocabulary of an interface is the signposting for someone navigating the product — cohesion and consistency are how people learn their way around. > 4. **Failure and emptiness give DIRECTION, not mood.** Explain what went wrong and how to fix it, in the interface's voice rather than a person's. **Errors do NOT apologize, and are NEVER vague about what happened.** An empty screen is an invitation to act. > 5. **Conversational tone, one job per element.** Plain verbs, sentence case, no filler, tone matched to the brand and the audience; let each written element do exactly one job. > 6. **Real content, never lorem.** When the brief supplies no copy, write plausible strings for the ACTUAL subject. **Coherence check — read every visible string as a user would, checking for truth, not typos:** could a real person at a real company be looking at exactly this data right now, or does the page title belong to one product, the body to another, and the sidebar metrics to a third? A beautifully designed interface with nonsensical content is a movie set with no script. > > **Skip ONLY** when the change surfaces no user-visible text — state that explicitly. > **Front-End Design Review Checklist** — the EXECUTABLE review protocol for any artifact carrying a user-facing front-end surface. Full catalog (`A1`…`Q`, ~130 checks with failure signals and default severities): **`.claude/docs/design-review-checklist.md`**. This gate carries the protocol and the triage pass; the file carries the checks. > > **Applies when — and ONLY when — the change, plan, or artifact carries a user-facing front-end surface.** A back-end-only diff, a doc edit, or a config change is `N/A`: state that once and move on. NEVER run a UI review on a non-UI change to manufacture coverage. When it DOES apply, **MUST ATTENTION READ `.claude/docs/design-review-checklist.md` and work its sections** — a review that cites a check ID without opening the catalog is asserting, not checking. > > **`CL-1` Context before checks (§0.1).** Establish platform · primary user & expertise · primary task · success metric · constraints · review scope · available artifacts. Fewer than four known → state the gap at the top of the report and mark affected findings **low confidence** — why: a check judged against an unknown task is a guess wearing an ID. > > **`CL-2` Evidence or nothing (§0.2).** Every finding cites a specific location (screen · element · `file:line`). NEVER invent a measurement — contrast, tap-target size, and load time that cannot be measured from the given artifact are `NOT VERIFIABLE`, never a guessed number. Tag every finding `MEASURED` · `OBSERVED` · `HEURISTIC`. Status values: `PASS` · `FAIL` · `PARTIAL` · `N/A` · `NOT VERIFIABLE`. > > **`CL-3` Severity, then a cap (§0.3).** `P0` blocks task completion / loses data / excludes a protected group (ship blocker) · `P1` significant friction or a legal accessibility floor (fix before release) · `P2` measurable inefficiency (next iteration) · `P3` polish (backlog) · `P4` note. Cap the report at the top 10 by severity unless a full audit was requested. A clean section reports "no issues found" — NEVER pad. Every `P0`/`P1` carries a concrete fix. > > **`CL-4` Section sweep, in order.** §A core usability heuristics · §B cognitive load & decision design · §C visual design & hierarchy · §D interaction + **the eight screen states** (ideal, empty, first-run, loading, partial, error, offline, maximum-data) · §E information architecture · **§F web / §G mobile / §H desktop — conditional on platform** · §I accessibility (WCAG 2.2 AA; every item `P1` minimum, `P0` when it blocks the task) · §J content & UX writing · §K trust, ethics & privacy (dark patterns are `P0`) · **§L AI & agentic patterns — conditional on the product having AI features** · §M cross-cutting consistency · §N edge-case probes. One focused pass per section — why: a section skipped in the long middle silently becomes an unreported defect class. > > **`CL-5` Quick Triage Pass (§P)** when a full sweep is not possible — these 10 catch the majority of serious defects: (1) can a new user complete the primary task unaided · (2) does every action give visible feedback within 400ms · (3) do empty/loading/error states exist AND offer a forward path · (4) is the primary action obvious, singular, reachable · (5) text ≥4.5:1 contrast and focus visible · (6) whole flow completable by keyboard · (7) touch targets ≥44/48px · (8) destructive actions reversible · (9) holds at 320px and 200% zoom · (10) any dark patterns. > > **`CL-6` Report shape (§O).** Context (+ known gaps) → Verdict (Ship / Ship with fixes / Do not ship) → What works (2–4 specific strengths, cited) → Findings grouped `P0`→`P3`, each with Location · Evidence + tag · Impact · Principle (checklist ID) · Fix → Open questions → Coverage table. Any `P0` caps the grade at Fail regardless of score; report a score only ALONGSIDE findings, never instead of them. > > **Precedence and no-double-counting.** The project's design-system / SCSS / frontend-pattern docs and accepted ADRs OUTRANK this checklist; the brief's stated direction outranks aesthetic judgment. A deliberate, documented convention is NEVER a defect — check intent before flagging, and surface a genuine conflict to the user with both sides, NEVER resolve it silently. This checklist is the review PROCEDURE, not a third set of taste rules: `UI-1.1`–`UI-9.4` ask "does it meet the usability floor?", `DD-1`–`DD-8` ask "is this THIS product's interface?", and these checks ask "did the review actually look, with evidence, and rank it?". Where a check restates a `UI-*` or `DD-*` clause, report the defect ONCE under whichever ID the consuming skill already uses. > > **For a PLAN or a PLAN REVIEW.** When the plan contains front-end work, the checklist b …(truncated)