Design

Design

Create and critique user-facing interfaces with strong product judgment, accessible implementation, domain-appropriate taste, and rendered evidence.

Input: $ARGUMENTS - optional mode keyword plus a request, path, URL, or natural-language interface problem. Infer mode by default.

---

Dispatch

Route by intent, not by wording alone. Explicit mode words are primary hints, not hard locks; still attach secondary modules required by the target.

| $ARGUMENTS signal | Mode | Primary references | | --- | --- | --- | | empty | Gallery | this file | | audit, review, broken UI, overlap, visual bug, focus bug | Audit | anti-patterns.md, rendered-proof.md | | polish, improve, make better, redesign, refine | Polish | design-briefs.md, visual-inspiration.md, motion-language.md | | component, create, single UI noun | Component | react-19.md, shadcn-patterns.md, modern-css.md | | page, view, screen, dashboard, landing, settings, checkout, URL | Surface | design-briefs.md, aesthetic-guide.md, laws-of-ux.md | | theme, tokens, palette, typography, design system | System | tailwind-v4.md, typography.md, modern-css.md | | refactor, style , existing .tsx/.jsx/.css path | Refactor | anti-patterns.md, modern-css.md, rendered-proof.md | | AI chat, assistant, agent, generation, trust, provenance, citation | AI Interface | ai-ux-patterns.md, laws-of-ux.md | | badges, shields, README badges, status indicators | Badge Surface | badge-systems.md, visual-inspiration.md | | 3D, WebGL, Three.js, immersive canvas | 3D Interface | threejs-immersive.md, rendered-proof.md | | many subagents, parallel, whole app, redesign system, audit many screens | Parallel Design Team | multi-agent-design.md, rendered-proof.md |

Common compound modes:

• Polish + Surface: improve a page, dashboard, landing page, or flow.
• Audit + AI Interface: review AI/chat/research surfaces for trust,

provenance, controls, and accessibility.

• Refactor + Chrome Proof: edit existing UI code, then verify in the

browser with Chrome DevTools MCP when available.

• Badge Surface + System: add or audit project status badges, README badge

rows, ShieldCN/shields styling, icon slugs, dynamic endpoints, and marker boundaries without rewriting the README.

• Parallel Design Team + System: broad app redesign, design-system cleanup,

or many-screen audit with file ownership and merge gates.

Refuse or redirect backend APIs, database work, test repair, state-management bugs, routing architecture, CI/DevOps, generic architecture diagrams, broad planning, and design-document generation unless the user-facing interface is the primary work.

Keep adjacent skills separate: route non-UI API design to api-designer, general docs-site maintenance and README writing to docs-steward, image-generation-only work to draw-thing, localization-only work to i18n-localization, non-UI performance profiling to performance-profiler, security review to security-scanner, test strategy to test-architect, and code review to review. Badge-only README/status-indicator work stays here.

Inference First

For non-empty arguments:

1. Infer one primary mode from action verbs, target type, path or URL, framework

signals, visual risk, and proof needs.

1. Attach secondary modules for AI trust, accessibility, motion, 3D/canvas,

shadcn/Radix, Tailwind, rendered proof, or parallel design-team work.

1. Treat an explicit first word like audit, polish, refactor, or system

as the primary hint, then adjust with evidence from the target.

1. If two plausible modes remain, choose the one that changes the work plan

most and name the secondary module in the thesis.

---

Classification/Gating Logic

Before loading references or editing files, use this classification-gating pass:

1. Interface gate: the primary target must be a user-facing interface,

badge/status indicator, visual state, interaction, or rendered proof. If the real target is backend, docs prose, architecture, CI setup, tests, or MCP configuration, redirect.

1. Mode gate: choose one primary mode from Dispatch, then attach only the

secondary modules required by evidence in the target.

1. Mutation gate: audits, inspiration, scanner runs, and proof collection

are read-only until the user asks for implementation. Badge insertion still needs approval unless an explicit --yes-style instruction is present.

1. Proof gate: rendered UI, badge rows, and visual status indicators need

browser/preview/screenshot proof when feasible; otherwise state the blocker.

1. Handoff gate: route deep performance, security, test strategy, docs

writing, and non-UI automation to their adjacent skills instead of stretching /design.

Scaling Strategy

Use this scaling-strategy table to scale by verified independence:

| Size | Strategy | | --- | --- | | trivial | Single component, badge row, or narrow CSS file: single-lane inspect, edit, proof | | small | One page or flow: split discovery by structure, copy/content, accessibility, motion, and proof only when files do not overlap | | medium | Generated docs, README badges, shared tokens, or central components: serialize behind a file lock and run a merge gate | | large | Multi-screen app or design-system work: use multi-agent-design.md, one owner per surface or concern, merge captain for shared decisions |

Every lane reports owned files, evidence, proposed edits, proof needs, and blockers. Same-file edits, generated surfaces, MCP/browser config, installs, and credentialed tools never run in parallel.

Progressive Disclosure

Load the smallest useful context:

1. Start with this SKILL.md and local project files.
2. Load only references named by the primary mode and required secondary

modules. A badge-only task should not load 3D guidance; a component task should not load the full inspiration stack unless the brief needs it.

1. Use the scanner for deterministic static signals, not as a replacement for

design judgment or browser proof.

1. Use current official docs only when project versions or API behavior are

uncertain.

1. Keep source excerpts and browser artifacts bounded; summarize large traces,

screenshots, heap snapshots, and generated reports instead of reading them wholesale.

State Management

Use these state-management rules to keep /design proof and generated state contained:

• Do not commit .DS_Store, generated skill zips, screenshots, traces, HAR

files, Lighthouse reports, heap snapshots, browser downloads, or Python caches.

• Save large proof artifacts only to explicit temporary or user-approved paths.
• Preserve manual README content outside badge markers.
• There is no /design state-dir; do not read/write persistent state under

~/.{design}/state/ or any other hidden skill state path.

• Do not create, modify, or delete MCP registry/config, browser launch config,

live installed skills, or remote registry state from /design.

• If validation creates cache/package noise, remove it before finalizing.

---

Canonical Vocabulary

These are canonical terms; use them consistently.

| Term | Meaning | | --- | --- | | Interface | A user-facing product, page, component, workflow, or interactive surface. | | Design thesis | The short rationale for audience, job, register, density, motion, and system reuse. | | Register | The domain-appropriate tone: restrained, expressive, technical, playful, premium, civic, clinical, etc. | | Design-system precedence | Existing local components, tokens, typography, and interaction patterns win before new invention. | | Rendered proof | Browser, preview, screenshot, canvas, or equivalent evidence that the UI actually renders correctly. | | Trust affordance | A control or display tied to real provenance, permissions, state, or recovery behavior. | | Chrome proof | Rendered proof gathered through available Chrome DevTools MCP tools: page selection, snapshot, console/network checks, focus interaction, and screenshots. | | Badge surface | README/docs/status badges treated as compact interface elements with truthful data, accessible labels, links, style, and marker boundaries. |

---

Critical Rules

1. Inspect existing UI and design-system conventions before proposing style.
2. Preserve project tokens, components, typography, and icon language unless

there is evidence they are missing or broken.

1. Never copy third-party brand trade dress, screenshots, layouts, or identity systems.
2. Do not run live installs, remote registries, MCP setup/config mutation,

Figma/Stitch flows, or hooks unless the user explicitly asks and the repo trust gate is satisfied.

1. Preserve accessibility: visible focus, labels, keyboard paths, semantic

HTML, contrast, and reduced-motion behavior.

1. Match the domain: operational tools stay dense and scannable; brand and

editorial surfaces may be more expressive when the brief supports it.

1. Require rendered proof for rendered UI, or state the exact blocker.
2. Use Chrome DevTools MCP as the default proof path when a browser-rendered

UI exists and the tools are available; fall back only after naming the blocker.

1. Keep audits read-only until the user asks for implementation.
2. Keep badge/status work truthful: prefer dynamic endpoints, link badges

to their source, preserve marker boundaries, and skip private-incompatible public API badges.

1. Fan out broad interface work into many independent subagents: read-only

exploration first, one owner per surface or concern, same-file edits sequential, and a merge captain for synthesis and proof.

---

Operating Workflow

0. Fan Out Broad Work

When the request covers a whole app, many screens, a design-system overhaul, multi-mode audit, or explicitly asks for many subagents, use references/multi-agent-design.md.

Default to high parallelism for read-only work:

• Split by surface, concern, and proof target: routes, components, tokens,

flows, accessibility, responsive behavior, motion, AI trust, 3D/canvas, copy/content, and rendered QA.

• Give each subagent a narrow contract: inspect, report evidence, propose

changes, and name owned files. Do not let multiple writers edit the same file.

• Keep a merge captain in the main thread to lock scope, resolve conflicts,

preserve the design thesis, and verify final rendered behavior.

• Use sequential edits only for shared tokens, central components, generated

docs, package manifests, and files already being changed by another lane.

1. Discover Before Designing

Before writing UI code or making critique claims:

• Inspect existing screens, components, routes, tokens, CSS, copy, data density,

screenshots, stories, and product context.

• Detect framework and design-system precedence: existing local components,

components.json, Tailwind version, theme tokens, Radix/shadcn primitives, CSS modules, styled systems, and project conventions.

• Identify the user job, audience, frequency of use, risk level, accessibility

constraints, and whether the surface is an operational product, marketing surface, editorial surface, AI workflow, game, or immersive interface.

• When a rendered surface exists, open or run it before final claims whenever

local tooling makes that feasible. Prefer Chrome DevTools MCP for page selection, accessibility snapshot, console/network checks, interactions, and screenshots.

If the project already has a design system, extend it. Do not introduce a new palette, component grammar, font stack, icon style, or motion language without evidence that the current system is missing or broken.

2. State The Design Thesis

For non-trivial design work, briefly state:

• Audience and job: who uses this, why, and how often.
• Mode: product/tool, marketing, editorial, AI interface, data dashboard,

form flow, game, or immersive/3D.

• Register: restrained, expressive, technical, playful, premium, civic,

clinical, educational, or another domain-appropriate tone.

• Dials: density, visual variance, motion level, hierarchy, data prominence,

content length resilience, and accessibility risk.

• System precedence: what existing tokens/components/patterns will be reused.

Use references/design-briefs.md when the thesis is more than a sentence.

3. Build Or Refactor

Follow these rules for all implementation modes:

• Prefer semantic HTML and platform controls before custom ARIA.
• Use shadcn/Radix primitives for interactive dialogs, menus, popovers, tabs,

accordions, selects, tooltips, drawers, and command palettes when the project already uses that stack.

• Keep layouts resilient to long words, translated text, missing media, loading

states, empty states, errors, dense data, and mobile safe areas.

• Use CSS logical properties and container queries when component context is the

responsive boundary.

• Use Tailwind v4 CSS-first tokens when the project is on Tailwind v4; do not

invent tailwind.config.js for new v4 work.

• Keep body text readable, touch targets usable, forms labeled, focus visible,

keyboard paths complete, and contrast at WCAG AA or better.

• Treat animation as interaction design: it needs purpose, origin, duration,

interruptibility, performance headroom, and reduced-motion behavior.

• For AI interfaces, expose state, scope, provenance, uncertainty, controls,

undo/escape paths, and verification affordances tied to real system behavior.

• For badge surfaces, preserve existing style, use dynamic endpoints for live

values, include accessible alt text and meaningful links, and keep edits inside approved badge markers.

• For inspiration, extract traits and constraints. Do not copy brand trade

dress, screenshots, layouts, or distinctive identity systems.

4. Audit And Polish

Audits are read-only unless the user explicitly asks for changes. Lead with findings, file/line references, severity, and proof status.

Use this output shape:

Findings
- [P1] file:line - concrete issue, user impact, recommended fix

Strengths
- Existing pattern worth preserving

Proof
- Commands, browser/screenshot evidence, or why rendered proof was unavailable

For polish passes, include a compact before/after table covering hierarchy, spacing, typography, color, motion, accessibility, and content resilience.

5. Rendered Proof Gate

Do not call a visual surface complete until proof is gathered or explicitly blocked.

• Run the local app, Storybook, preview, screenshot, or component harness when

available.

• Prefer Chrome DevTools MCP for browser-rendered proof: select or create the

page, navigate, wait for a stable marker, take an accessibility snapshot, inspect console and network errors, exercise focus or key interactions, and capture desktop/mobile screenshots when visual proof matters.

• Check at least one desktop and one mobile viewport for real UI work.
• Verify there is no blank canvas, broken asset, overlap, clipped text,

unreadable contrast, hidden focus state, or animation that ignores reduced motion.

• For canvas/Three.js, include a screenshot or pixel/nonblank check and confirm

interaction or motion is framed correctly.

• If proof cannot run, state the blocker and list the exact commands attempted.

---

Reference Index

Load only what the task needs:

| Reference | Use for | | --- | --- | | references/design-briefs.md | Thesis, domain register, design dials | | references/visual-inspiration.md | Inspiration without copying | | references/laws-of-ux.md | Cognitive-load and UX heuristics | | references/ai-ux-patterns.md | AI interface trust and control patterns | | references/badge-systems.md | README/status badges, ShieldCN/shields style, dynamic endpoints, marker safety | | `refe

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: wyattowalsh
• Source: wyattowalsh/agents
• License: MIT
• Homepage: https://agents.w4w.dev

Install and usage instructions live in the source repository linked above.