<tool_restrictions>

MANDATORY Tool Restrictions

BANNED TOOLS — calling these is a skill violation:

EnterPlanMode — BANNED. Do NOT call this tool. This skill has its own multi-phase design process. Execute the phases below directly.
ExitPlanMode — BANNED. You are never in plan mode. </tool_restrictions>

Design Workflow

Create distinctive, non-generic UI. Avoids AI slop (purple gradients, cookie-cutter layouts).

Announce at start: "I'm using the design skill to create distinctive, non-generic UI."

<important> **This skill is user-interactive. Do NOT spawn agents to do design work.**

This skill walks through design decisions WITH the user — it's collaborative, not delegated
There is no arc:design:designer agent — design creation happens through this skill
arc:review:designer exists but is for REVIEWING implementations AFTER they're built, not for creating designs
If asked to "design X", follow this skill's phases; don't try to spawn an agent </important>

Agents

This skill works with these agents (reuse, don't duplicate):

Agent	Location	When to Use
`ui-builder`	agents/build/	Build UI from the change spec you create
`figma-builder`	agents/build/	Build UI when Figma URL is provided
`design-specifier`	agents/build/	Quick design decisions during implement (empty states, dropdowns)
`designer`	agents/review/	Review implemented UI for AI slop

Workflow:

/arc:design (this skill)
     ↓ creates change spec
ui-builder or figma-builder (builds it)
     ↓ implements
designer (reviews for AI slop)

Phase 0: Load References & Design Context (MANDATORY)

You MUST read these files before proceeding. Do not skip this step.

<required_reading> Read ALL of these using the Read tool:

references/frontend-design.md — Fonts, anti-patterns, design review checklist. Critical.
references/design-philosophy.md — Timeless principles from Refactoring UI
references/ascii-ui-patterns.md — Wireframe syntax and patterns
references/wiretext.md — When to use WireText vs ASCII vs browser review

Then load interface rules: 5. rules/interface/index.md — Interface rules index

And relevant domain rules based on what you're designing:

rules/interface/design.md — Visual principles
rules/interface/colors.md — Color palettes, OKLCH, tinted neutrals
rules/interface/spacing.md — Spacing system, container queries
rules/interface/typography.md — Typography rules, OpenType features
rules/interface/layout.md — Layout patterns, z-index
rules/interface/responsive.md — Responsive design, input detection
rules/interface/animation.md — If motion is involved
rules/interface/forms.md — If designing forms
rules/interface/interactions.md — Interactive states, popover API
rules/interface/marketing.md — If designing marketing pages
rules/interface/app-ui.md — If designing app UI (dashboards, settings, data views) </required_reading>

Persistent Design Context

Check for docs/design-context.md using the Read tool.

If it exists, load it — this file contains project-wide aesthetic decisions (brand colors, chosen fonts, spacing scale, tone) that all design work should inherit. Do not re-ask questions that are already answered in design-context.md. Skip to Phase 1 for any established decisions.

If it does NOT exist, offer to create one:

Use AskUserQuestion:

Question: "No project-wide design context found. Want to establish one? This saves brand decisions (colors, fonts, tone) so every future design session inherits them."
Header: "Design context"
Options:
  1. "Yes, establish context" (Recommended) — Create docs/design-context.md with persistent aesthetic decisions
  2. "No, one-off design" — Proceed without persistent context

If creating context, gather and save to docs/design-context.md:

# Design Context

Persistent aesthetic decisions for this project. All design work inherits these choices.

## Brand
- **Name**: [project name]
- **Personality**: [e.g., confident and technical, warm and approachable]
- **Tone**: [chosen from tone options]

## Typography
- **Display font**: [specific font]
- **Body font**: [specific font]
- **Mono font**: [specific font, if applicable]

## Color Palette (Tailwind @theme)
```css
@theme {
  --color-brand-500: oklch(... ... ...);
  /* Full shade scale */
  --color-gray-500: oklch(... ... ...);
  /* Tinted neutral scale */
}

Spacing

Base unit: 4px
Scale: Tailwind default (p-1=4px through p-16=64px)

Motion Philosophy

Style: [e.g., snappy and confident, smooth and refined]
Library: [CSS transitions / motion/react]

Memorable Element

[What makes this project's UI distinctive]

Anti-Patterns (Project-Specific)

[Anything specifically to avoid for this project]


After creating, proceed to Phase 1.

<progress_context>
**Use Read tool:** `docs/arc/progress.md` (first 50 lines)

Check for related prior design work and aesthetic decisions.
</progress_context>

---

## Phase 1: Visual Reconnaissance

**Before designing anything, see what exists.**

### If Redesigning Existing UI:

**Prefer Chrome MCP to capture current state. If unavailable, use `agent-browser`. If neither is available, ask for screenshots or review the code directly.**

mcp__claude-in-chrome__tabs_context_mcp (get available tabs)
mcp__claude-in-chrome__tabs_create_mcp (create new tab if needed)
mcp__claude-in-chrome__navigate to the local dev URL
mcp__claude-in-chrome__computer action=screenshot


**Analyze the screenshot against the Design Review Checklist from frontend-design.md:**
- Does it have any Red Flags (AI slop indicators)?
- What's the current aesthetic direction (if any)?
- What's working? What's not?

**Report findings to user:** "Here's what I see in the current UI: [observations]. The main issues are: [problems]."

### If Designing From Scratch:

- Confirm dev server is running (or will be)
- Ask if there's any existing brand/style guide to reference
- Check if there are reference designs or inspiration URLs to screenshot

---

## Phase 1.5: Design Mode

**Before gathering direction, establish what kind of UI you're designing.**

**Use AskUserQuestion:**

Question: "What are you designing?" Header: "Design mode" Options:

"Marketing page" — Landing page, homepage, pricing, about, blog. Goal: persuade and convert.
"App UI" — Dashboard, settings, forms, data views. Goal: enable and orient.


**After selection:**
- **Marketing** → Load `rules/interface/marketing.md` as mandatory reference
- **App UI** → Load `rules/interface/app-ui.md` as mandatory reference

This mode context informs all subsequent phases — questions, research sources, wireframe patterns, and checklist items adapt accordingly.

---

## Phase 2: Gather Direction

### Question 0: Exploration Mode (Conditional)

**Offer this option when circumstances allow:**
- New project with no established design system
- Homepage, landing page, or marketing site design
- User seems uncertain about direction
- Greenfield UI with creative freedom

**Do NOT offer when:**
- Strict brand guidelines exist
- Designing a small component or iteration
- User has already specified a clear direction
- Adding to an existing design system

**If circumstances allow, use AskUserQuestion:**

Question: "Would you like me to create 5 vastly different design directions, each at its own route? This lets you compare radically different approaches before committing." Header: "Exploration" Options:

"Yes, explore 5 directions" — Create /design-1 through /design-5 with completely different aesthetics
"No, single direction" (Recommended) — Focus on one well-crafted design


**If exploration mode is chosen:**
- Each route (/design-1, /design-2, etc.) gets a completely different aesthetic
- Vary: color palette, typography, layout structure, tone, spatial composition
- Don't just tweak—make them *unrecognizable* from each other
- After building all 5, ask user which direction resonates
- Then proceed with full design doc for the chosen direction

---

Ask the remaining questions **one at a time**:

### Question 1: Tone
"What tone fits this UI?"
- Minimal, bold, playful, editorial, luxury, brutalist, retro, organic, industrial, art deco, soft/pastel

### Question 1.5: Mode-Specific Question

**If Marketing mode:**
"How does the page tell its story?"
- Hero → problem → solution → proof → CTA (classic)
- Immersive scroll narrative (one idea per viewport)
- Feature showcase (dense, scannable)
- Minimal single-screen (everything above the fold)
- Editorial long-form (article-like)

**If App UI mode:**
"How information-dense should this be?"
- Sparse — generous whitespace, one focus per screen (e.g., onboarding)
- Balanced — comfortable density, clear hierarchy (e.g., settings)
- Dense — lots of data visible at once (e.g., dashboard, table views)

### Question 2: Memorable Element
"What should be memorable about this?"

**If Marketing:** The animation? Typography drama? Layout surprise? Photography style? Scroll behavior?

**If App UI:** The navigation paradigm? Micro-interactions? Information density approach? Empty state creativity? Data visualization style?

### Question 3: Existing Constraints
"Any existing brand/style to match, or fresh start?"

### Question 4: Inspiration
"Any reference designs or inspiration?"
- If provided, **screenshot them immediately using Chrome MCP** for visual reference

### Question 5: UI Chrome
"Should this have standard website chrome (header, footer, navigation), or feel more like an app?"

Consider:
- **Standard website chrome** — Fixed header with logo/nav, footer with links. Good for content sites, marketing pages, multi-page experiences where users need to navigate.
- **App-like experience** — Minimal or no persistent chrome. Content takes full focus. Good for tools, dashboards, immersive experiences, single-purpose flows.
- **Hybrid** — Minimal header (maybe just a logo), no footer. Common for SaaS apps.

**The default shouldn't always be "header + footer".** If the experience is focused (a tool, a game, a single flow), standard chrome can feel clunky and distract from the core experience. Let the purpose guide the frame.

---

## Phase 3: Research Inspiration (Optional)

**Use WebFetch to explore curated design examples based on the chosen direction.**

This phase is optional but recommended when:
- Starting from scratch with no existing references
- The user wants to see examples matching their chosen tone
- You need concrete visual patterns to inform decisions

### Siteinspire (Website/Homepage Design)

Siteinspire curates high-quality website designs. Use WebFetch to explore based on the chosen tone:

WebFetch URL patterns by tone:

Minimal: https://www.siteinspire.com/websites?style=minimal
Bold: https://www.siteinspire.com/websites?style=bold
Playful: https://www.siteinspire.com/websites?style=playful
Editorial: https://www.siteinspire.com/websites?style=editorial
Luxury: https://www.siteinspire.com/websites?style=luxury
Brutalist: https://www.siteinspire.com/websites?style=brutalist
Retro: https://www.siteinspire.com/websites?style=retro
Organic: https://www.siteinspire.com/websites?style=organic

By page type:

Homepage: https://www.siteinspire.com/websites?page=homepage
Portfolio: https://www.siteinspire.com/websites?page=portfolio
E-commerce: https://www.siteinspire.com/websites?page=e-commerce
Blog: https://www.siteinspire.com/websites?page=blog


**WebFetch prompt:** "List the website names, their URLs, and a brief description of their visual style. Focus on typography choices, color palettes, and layout patterns."

### Mobbin (UI/Mobile Design Patterns)

Mobbin collects UI patterns from real apps. Use for component and interaction inspiration:

WebFetch URL patterns:

iOS apps: https://mobbin.com/browse/ios/apps
Android: https://mobbin.com/browse/android/apps
Web apps: https://mobbin.com/browse/web/apps

By screen type:

Onboarding: https://mobbin.com/browse/ios/screens?screen=onboarding
Dashboard: https://mobbin.com/browse/ios/screens?screen=dashboard
Settings: https://mobbin.com/browse/ios/screens?screen=settings
Profile: https://mobbin.com/browse/ios/screens?screen=profile
Search: https://mobbin.com/browse/ios/screens?screen=search


**WebFetch prompt:** "List the apps shown and describe their UI patterns—navigation style, card layouts, typography hierarchy, and interaction patterns."

### Research Workflow

1. **Based on user's chosen tone**, fetch 1-2 relevant Siteinspire pages
2. **Based on what you're designing** (homepage, dashboard, form), fetch relevant Mobbin screens
3. **Summarize findings** to user: "I found these patterns that match your direction: [observations]"
4. **Ask:** "Any of these resonate? Should I explore a specific site further with Chrome MCP?"

### Deep Dive with Chrome MCP

If a specific example catches interest, use Chrome MCP for detailed inspection:

mcp__claude-in-chrome__navigate to the specific site URL
mcp__claude-in-chrome__computer action=screenshot
Analyze: typography, colors, spacing, layout patterns
Report specific values observed (font names, hex colors, spacing)


**Note:** WebFetch provides quick overview; Chrome MCP provides detailed visual inspection. Use both strategically.

---

## Phase 4: Make Concrete Visual Decisions

**Capture SPECIFIC visual decisions, not conceptual themes.**

<principle>
**Complexity Matching:** Design complexity should align with aesthetic vision. Maximalist designs warrant elaborate code and rich details. Minimalist designs require restraint and precision—every element must earn its place. Don't add flourishes to a minimal design; don't under-build a maximalist one.
</principle>

Apply knowledge from the loaded references to make these decisions:

### Typography Selection
Using the font recommendations from `frontend-design.md`:
- **Display font:** [specific font name]
- **Body font:** [specific font name]
- **Mono font (if needed):** [specific font name]

**Never use:** Roboto, Arial, system-ui defaults, Instrument Serif (AI slop)

### Color Palette
- **Background:** [specific hex, e.g., #0a0a0a]
- **Surface/card:** [specific hex]
- **Text primary:** [specific hex]
- **Text secondary:** [specific hex]
- **Accent:** [specific hex]
- **Accent hover:** [specific hex]

**Never use:** Purple-to-blue gradients (AI cliché)

### Spacing System
Define the scale being used:
- **Base unit:** 4px or 8px
- **Common values:** 4, 8, 12, 16, 24, 32, 48, 64
- **Component padding:** [e.g., 16px default, 24px for cards]
- **Section spacing:** [e.g., 64px between major sections]

### Spatial Composition
Beyond basic layout, make deliberate choices about:
- **Asymmetry:** Not everything needs to be centered or perfectly balanced
- **Overlap:** Elements can break grid boundaries, bleed off edges, layer on top of each other
- **Unexpected layouts:** Break the "header → hero → 3-column features → footer" pattern
- **Negative space:** Generous whitespace creates breathing room and draws focus to what matters

**Ask:** "Where can the layout do something unexpected?"

### Motion Philosophy
- **Where animation is used:** [specific locations]
- **Animation style:** [e.g., ease-out for enters, springs for interactive]
- **Duration range:** [e.g., 150-300ms]

---

## Phase 5: Wireframe

**Create a structural wireframe before any code.**

Prefer WireText MCP when available for low-fidelity wireframes. If WireText is unavailable, create ASCII wireframes using patterns from `ascii-ui-patterns.md`.

If WireText is used:
- save the editable URL in the design doc
- capture the exported wireframe text or a short structural summary
- treat it as the source of layout structure, not visual fidelity

┌─────────────────────────────────────┐ │ Logo [Search...] [Menu] │ ├─────────────────────────────────────┤ │ │ │ [Main Content Area] │ │ │ └─────────────────────────────────────┘


**Include:**
1. Primary layout structure
2. Key interactive elements
3. Mobile version if responsive
4. States: empty, loading, error (where relevant)

**If App UI mode:** You MUST include at least one state variant beyond the populated state (empty, loading, or error). App UI without state design is incomplete.

**Ask:** "Does this structure feel right before I continue?"

---

## Phase 5.5: Create Change Spec

**THIS IS CRITICAL.** Translate aesthetic direction into **specific, measurable changes**:

```markdown
## Change Spec

### Typography
| Element | Before | After | Rule Reference |
|---------|--------|-------|----------------|
| h1 | 24px Inter regular | 48px Instrument Serif bold | typography.md: display hierarchy |
| body | 14px system-ui | 16px/1.6 DM Sans | typography.md: body readability |

### Colors
| Element | Before | After | Rule Reference |
|---------|--------|-------|----------------|
| background | white #fff | warm off-white #faf9f7 | colors.md: warmth |
| accent | none | coral #ff6b4a | colors.md: accent strategy |

### Spacing
| Element | Before | After | Rule Reference |
|---------|--------|-------|----------------|
| section padding | p-4 (16px) | p-12 (48px) | spacing.md: generous whitespace |

### Layout
| Element | Before | After | Rule Reference |
|---------|--------|-------|----------------|
| hero | centered text | asymmetric split with image overlap | layout.md: break the grid |

### Motion (if applicable)
| Element | Before | After | Rule Reference |
|---------|--------|-------|----------------|
| page load | none | staggered fade-up, 50ms delay | animation.md: entrance sequence |

Rules for change specs:

Every change references a rule from the interface rules
Changes must be substantial, not tweaks
Specific values, not vague descriptions

Self-check:

At least 3 typography changes?
Color palette actually different?
Spacing significantly adjusted?
Memorable element clearly identified and designed?

If you're only changing padding values, STOP. That's not a redesign.

Phase 6: Produce Design Document

Create the design direction document at docs/arc/specs/design-[component-name].md:

# Design Direction: [Component/Page Name]

## Aesthetic Direction
- **Tone:** [chosen - e.g., "minimal", "bold", "editorial"]
- **Memorable element:** [specific - e.g., "oversized typography", "micro-interactions on hover"]

## Typography
- **Display:** [font name] — [where used]
- **Body:** [font name] — [where used]
- **Mono:** [font name] — [where used, if applicable]

## Color Palette
| Role | Value | Usage |
|------|-------|-------|
| Background | #0a0a0a | Page background |
| Surface | #1a1a1a | Cards, panels |
| Text primary | #fafafa | Headings, body |
| Text secondary | #a1a1a1 | Labels, hints |
| Accent | #f59e0b | CTAs, links |
| Accent hover | #fbbf24 | Hover states |

## Spacing
- Base unit: 8px
- Component padding: 16px (small), 24px (medium), 32px (large)
- Section gaps: 48px (tight), 64px (normal), 96px (generous)

## Motion
- Page transitions: fade, 200ms ease-out
- Interactive elements: spring (stiffness: 400, damping: 25)
- Hover states: 150ms ease-out

## Layout

### Desktop
[ASCII wireframe]

### Mobile
[ASCII wireframe]

## Implementation Notes
- [Any specific technical considerations]
- [Component library preferences]
- [Animation library: CSS-only vs motion/react]

## Anti-Patterns to Avoid
- [Specific things NOT to do for this design]

Phase 7: Verify Against Checklist

Run the Design Review Checklist from frontend-design.md:

Red Flags (must be zero)

Uses default system fonts
Purple-to-blue gradient present
White background + gray cards throughout
Could be mistaken for generic AI output

Green Flags (should have most)

Clear aesthetic direction documented
Typography is deliberate
At least one memorable element
Layout has unexpected decisions

If Marketing Mode, also check:

Red Flag: Cookie-cutter hero → features → testimonials → CTA layout
Red Flag: No clear narrative structure
Green Flag: Section rhythm creates breathing room
Green Flag: Would pass the "screenshot test" — distinctive in a grid of competitors

If App UI Mode, also check:

Red Flag: No empty state designed
Red Flag: Generic admin template feel
Red Flag: Fails the swap test — choices are defaults, not decisions (see app-ui.md)
Green Flag: Could use this for 8 hours without visual fatigue
Green Flag: All critical states designed (empty, loaded, error)

If any Red Flags are present, revise before proceeding.

Phase 8: Hand Off

Use AskUserQuestion tool:

Question: "Design documented. What's next?"
Header: "Next step"
Options:
  1. "Create detailed plan" (Recommended) — Run /arc:detail for task breakdown
  2. "Save and stop" — Return to this later

IMPORTANT: Do NOT automatically invoke other skills.

If option 1: Tell user: "Design saved. Run /arc:detail to create implementation tasks."
If option 2: Tell user: "Design saved to docs/arc/specs/design-[name].md. Return anytime."

During Implementation (Reference for /arc:implement)

When implementing this design (via /arc:implement), use Chrome MCP continuously when available. Outside Claude Code, prefer agent-browser, then Playwright.

After Every Significant Change

mcp__claude-in-chrome__computer action=screenshot

Check Responsive Behavior

mcp__claude-in-chrome__resize_window width=375 height=812  # Mobile
mcp__claude-in-chrome__computer action=screenshot
mcp__claude-in-chrome__resize_window width=1440 height=900 # Desktop
mcp__claude-in-chrome__computer action=screenshot

Verify Against Design Doc

Does the typography match what was specified?
Are the colors exactly as documented?
Does spacing feel consistent with the system?
Is the memorable element actually memorable?

Never commit UI code without visually verifying it looks correct.

Anti-Patterns (Quick Reference)

From frontend-design.md:

🚫 Never use sparkles/stars to denote AI features. Overused, meaningless, dated.

🚫 Never propose conceptual themes with metaphors. No "Direction: Darkroom / Metaphor: Photo emerging from developer bath". Instead: "Dark background (#0a0a0a) with warm red accents (#dc2626)."

🚫 Never use these:

Roboto/Arial/system-ui defaults
Purple-to-blue gradients
White backgrounds with gray cards
Rounded corners on everything
Mixed icon styles

<arc_log> After completing this skill, append to the activity log. See: references/arc-log.md

Entry: /arc:design — [Component/page] design ([aesthetic direction]) </arc_log>

<success_criteria> Design is complete when:

Interop

Produces design doc consumed by /arc:implement
Reads/creates docs/design-context.md for persistent project-wide aesthetic decisions
Can invoke web-design-guidelines skill for compliance review (if available)
Can invoke vercel-composition-patterns skill for component architecture review (if available)
Uses WireText MCP for low-fidelity wireframes when available
Uses Chrome MCP (mcp__claude-in-chrome__*) as the preferred rendered-page capture path in Claude Code
Uses agent-browser as the preferred browser fallback outside Claude Code
Uses WebFetch to research design inspiration from Siteinspire and Mobbin
References feed into implementation to maintain design fidelity

Related Refinement Skills

After implementation, suggest these for the final mile:

/arc:polish — Pre-ship visual refinement (spacing, states, contrast)
/arc:distill — Strip unnecessary complexity
/arc:animate — Add purposeful motion
/arc:harden — Production resilience (errors, overflow, i18n)

design

Safety Notice

Copy this and send it to your AI assistant to learn