# Design

> >-

- **Type:** Skill
- **Install:** `agentstack add skill-wyattowalsh-agents-design`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [wyattowalsh](https://agentstack.voostack.com/s/wyattowalsh)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [wyattowalsh](https://github.com/wyattowalsh)
- **Source:** https://github.com/wyattowalsh/agents/tree/main/skills/design
- **Website:** https://agents.w4w.dev

## Install

```sh
agentstack add skill-wyattowalsh-agents-design
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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.
2. Attach secondary modules for AI trust, accessibility, motion, 3D/canvas,
   shadcn/Radix, Tailwind, rendered proof, or parallel design-team work.
3. Treat an explicit first word like `audit`, `polish`, `refactor`, or `system`
   as the primary hint, then adjust with evidence from the target.
4. 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.
2. **Mode gate:** choose one primary mode from Dispatch, then attach only the
   secondary modules required by evidence in the target.
3. **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.
4. **Proof gate:** rendered UI, badge rows, and visual status indicators need
   browser/preview/screenshot proof when feasible; otherwise state the blocker.
5. **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.
3. Use the scanner for deterministic static signals, not as a replacement for
   design judgment or browser proof.
4. Use current official docs only when project versions or API behavior are
   uncertain.
5. 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.
3. **Never copy** third-party brand trade dress, screenshots, layouts, or identity systems.
4. **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.
5. **Preserve** accessibility: visible focus, labels, keyboard paths, semantic
   HTML, contrast, and reduced-motion behavior.
6. **Match** the domain: operational tools stay dense and scannable; brand and
   editorial surfaces may be more expressive when the brief supports it.
7. **Require** rendered proof for rendered UI, or state the exact blocker.
8. **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.
9. **Keep** audits read-only until the user asks for implementation.
10. **Keep** badge/status work truthful: prefer dynamic endpoints, link badges
   to their source, preserve marker boundaries, and skip private-incompatible
   public API badges.
11. **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:

```text
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](https://github.com/wyattowalsh)
- **Source:** [wyattowalsh/agents](https://github.com/wyattowalsh/agents)
- **License:** MIT
- **Homepage:** https://agents.w4w.dev

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

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-wyattowalsh-agents-design
- Seller: https://agentstack.voostack.com/s/wyattowalsh
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.