loader/.cursor/skills/ui-design/SKILL.md

---
name: ui-design
description: |
  End-to-end UI design workflow: requirements gathering → design system synthesis → HTML+CSS mockup generation → visual verification → iterative refinement.
  Zero external dependencies. Optional MCP enhancements (RenderLens, AccessLint).
  Two modes:
  - Full workflow: phases 0-8 for complex design tasks
  - Quick mode: skip to code generation for simple requests
  Command entry points:
  - /design-audit — quality checks on existing mockup
  - /design-polish — final refinement pass
  - /design-critique — UX review with feedback
  - /design-regen — regenerate with different direction
  Trigger phrases:
  - "design a UI", "create a mockup", "build a page"
  - "make a landing page", "design a dashboard"
  - "mockup", "design system", "UI design"
category: create
tags: [ui-design, mockup, html, css, tailwind, design-system, accessibility]
disable-model-invocation: true
---

# UI Design Skill

End-to-end UI design workflow producing production-quality HTML+CSS mockups entirely within Cursor, with zero external tool dependencies.

## Core Principles

- **Design intent over defaults**: never settle for generic AI output; every visual choice must trace to user requirements
- **Verify visually**: AI must see what it generates whenever possible (browser screenshots)
- **Tokens over hardcoded values**: use CSS custom properties with semantic naming, not raw hex
- **Restraint over decoration**: less is more; every visual element must earn its place
- **Ask, don't assume**: when design direction is ambiguous, STOP and ask the user
- **One screen at a time**: generate individual screens, not entire applications at once

## Applicability Check

When invoked directly by a user (`/ui-design ...`), proceed — the user explicitly asked.

When invoked by an orchestrator (e.g. the autodev greenfield flow Step 4), first decide whether the project actually has UI work to do. The project IS a UI project if ANY of the following are true:

- `package.json` exists in the workspace root or any subdirectory
- `*.html`, `*.jsx`, or `*.tsx` files exist in the workspace
- `_docs/02_document/components/` contains a component whose `description.md` mentions UI, frontend, page, screen, dashboard, form, or view
- `_docs/02_document/architecture.md` mentions frontend, UI layer, SPA, or client-side rendering
- `_docs/01_solution/solution.md` mentions frontend, web interface, or user-facing UI

If none of the above match → return `outcome: skipped, reason: not-a-ui-project` to the caller and exit without running any phase.

If at least one matches → present using Choose format:

```
══════════════════════════════════════
 DECISION REQUIRED: UI project detected — generate mockups?
══════════════════════════════════════
 A) Generate UI mockups (recommended before decomposition)
 B) Skip — proceed without mockups
══════════════════════════════════════
 Recommendation: A — mockups before decomposition
 produce better task specs for frontend components
══════════════════════════════════════
```

- If **A** → continue to Context Resolution below and run the workflow.
- If **B** → return `outcome: skipped, reason: user-declined` and exit.

## Context Resolution

Determine the operating mode based on invocation before any other logic runs.

**Project mode** (default — `_docs/` structure exists):
- MOCKUPS_DIR: `_docs/02_document/ui_mockups/`

**Standalone mode** (explicit input file provided, e.g. `/ui-design @some_brief.md`):
- INPUT_FILE: the provided file (treated as design brief)
- MOCKUPS_DIR: `_standalone/ui_mockups/`

Create MOCKUPS_DIR if it does not exist. Announce the detected mode and resolved path to the user.

## Output Directory

All generated artifacts go to `MOCKUPS_DIR`:

```
MOCKUPS_DIR/
├── DESIGN.md              # Generated design system (three-layer tokens)
├── index.html             # Main mockup (or named per page)
└── [page-name].html       # Additional pages if multi-page
```

## Complexity Detection (Phase 0)

Before starting the workflow, classify the request:

**Quick mode** — skip to Phase 5 (Code Generation):
- Request is a single component or screen
- User provides enough style context in their message
- `MOCKUPS_DIR/DESIGN.md` already exists
- Signals: "just make a...", "quick mockup of...", single component name, less than 2 sentences

**Full mode** — run phases 1-8:
- Multi-page request
- Brand-specific requirements
- "design system for...", complex layouts, dashboard/admin panel
- No existing DESIGN.md

Announce the detected mode to the user.

## Phase 1: Context Check

1. Check for existing project documentation: PRD, design specs, README with design notes
2. Check for existing `MOCKUPS_DIR/DESIGN.md`
3. Check for existing mockups in `MOCKUPS_DIR/`
4. If DESIGN.md exists → announce "Using existing design system" → skip to Phase 5
5. If project docs with design info exist → extract requirements from them, skip to Phase 3

## Phase 2: Requirements Gathering

Use the AskQuestion tool for structured input (fall back to plain-text questions if the tool is unavailable). Adapt based on what Phase 1 found — only ask for what's missing.

**Round 1 — Structural:**

Ask using AskQuestion with these questions:
- **Page type**: landing, dashboard, form, settings, profile, admin panel, e-commerce, blog, documentation, other
- **Target audience**: developers, business users, consumers, internal team, general public
- **Platform**: web desktop-first, web mobile-first
- **Key sections**: header, hero, sidebar, main content, cards grid, data table, form, footer (allow multiple)

**Round 2 — Design Intent:**

Ask using AskQuestion with these questions:
- **Visual atmosphere**: Airy & spacious / Dense & data-rich / Warm & approachable / Sharp & technical / Luxurious & premium
- **Color mood**: Cool blues & grays / Warm earth tones / Bold & vibrant / Monochrome / Dark mode / Let AI choose based on atmosphere / Custom (specify brand colors)
- **Typography mood**: Geometric (modern, clean) / Humanist (friendly, readable) / Monospace (technical, code-like) / Serif (editorial, premium)

Then ask in free-form:
- "Name an app or website whose look you admire" (optional, helps anchor style)
- "Any specific content, copy, or data to include?"

## Phase 3: Direction Exploration

Generate 2-3 text-based direction summaries. Each direction is 3-5 sentences describing:
- Visual approach and mood
- Color palette direction (specific hues, not just "blue")
- Layout strategy (grid type, density, whitespace approach)
- Typography choice (specific font suggestions, not just "sans-serif")

Present to user: "Here are 2-3 possible directions. Which resonates? Or describe a blend."

Wait for user to pick before proceeding.

## Phase 4: Design System Synthesis

Generate `MOCKUPS_DIR/DESIGN.md` using the template from `templates/design-system.md`.

The generated DESIGN.md must include all 6 sections:
1. Visual Atmosphere — descriptive mood (never "clean and modern")
2. Color System — three-layer CSS custom properties (primitives → semantic → component)
3. Typography — specific font family, weight hierarchy, size scale with rem values
4. Spacing & Layout — base unit, spacing scale, grid, breakpoints
5. Component Styling Defaults — buttons, cards, inputs, navigation with all states
6. Interaction States — loading, error, empty, hover, focus, disabled patterns

Read `references/design-vocabulary.md` for atmosphere descriptors and style vocabulary to use when writing the DESIGN.md.

## Phase 5: Code Generation

Construct the generation by combining context from multiple sources:

1. Read `MOCKUPS_DIR/DESIGN.md` for the design system
2. Read `references/components.md` for component best practices relevant to the page type
3. Read `references/anti-patterns.md` for explicit avoidance instructions

Generate `MOCKUPS_DIR/[page-name].html` as a single file with:
- `<script src="https://cdn.tailwindcss.com"></script>` for Tailwind
- `<style>` block with all CSS custom properties from DESIGN.md
- Tailwind config override in `<script>` to map tokens to Tailwind theme
- Semantic HTML (nav, main, section, article, footer)
- Mobile-first responsive design
- All interactive elements with hover, focus, active states
- At least one loading skeleton example
- Proper heading hierarchy (single h1)

**Anti-AI-Slop guard clauses** (MANDATORY — read `references/anti-patterns.md` for full list):
- Do NOT use Inter or Roboto unless user explicitly requested them
- Do NOT default to purple/indigo accent color
- Do NOT create "card soup" — vary layout patterns
- Do NOT make all buttons equal weight
- Do NOT over-decorate
- Use the actual tokens from DESIGN.md, not hardcoded values

For quick mode without DESIGN.md: use a sensible default design system matching the request context. Still follow all anti-slop rules.

## Phase 6: Visual Verification

Tiered verification — use the best available tool:

**Layer 1 — Structural Check** (always runs):
Read `references/quality-checklist.md` and verify against the structural checklist.

**Layer 2 — Visual Check** (when browser tool is available):
1. Open the generated HTML file using the browser tool
2. Take screenshots at desktop (1440px) width
3. Examine the screenshot for: spacing consistency, alignment, color rendering, typography hierarchy, overall visual balance
4. Compare against DESIGN.md's intended atmosphere
5. Flag issues: cramped areas, orphan text, broken layouts, invisible elements

**Layer 3 — Compliance Check** (when MCP tools are available):
- If AccessLint MCP is configured: audit HTML for WCAG violations, auto-fix flagged issues
- If RenderLens MCP is configured: render + audit (Lighthouse + WCAG scores) + diff

Auto-fix any issues found. Re-verify after fixes.

## Phase 7: User Review

1. Open mockup in browser for the user:
   - Primary: use Cursor browser tool (AI can see and discuss the same view)
   - Fallback: use OS-appropriate command (`open` on macOS, `xdg-open` on Linux, `start` on Windows)
2. Present assessment summary: structural check results, visual observations, compliance scores if available
3. Ask: "How does this look? What would you like me to change?"

## Phase 8: Iteration

1. Parse user feedback into specific changes
2. Apply targeted edits via StrReplace (not full regeneration unless user requests a fundamentally different direction)
3. Re-run visual verification (Phase 6)
4. Present changes to user
5. Repeat until user approves

## Command Entry Points

These commands bypass the full workflow for targeted operations on existing mockups:

### /design-audit
Run quality checks on an existing mockup in `MOCKUPS_DIR/`.
1. Read the HTML file
2. Run structural checklist from `references/quality-checklist.md`
3. If browser tool available: take screenshot and visual check
4. If AccessLint MCP available: WCAG audit
5. Report findings with severity levels

### /design-polish
Final refinement pass on an existing mockup.
1. Read the HTML file and DESIGN.md
2. Check token usage (no hardcoded values that should be tokens)
3. Verify all interaction states are present
4. Refine spacing consistency, typography hierarchy
5. Apply micro-improvements (subtle shadows, transitions, hover states)

### /design-critique
UX review with specific feedback.
1. Read the HTML file
2. Evaluate: information hierarchy, call-to-action clarity, cognitive load, navigation flow
3. Check against anti-patterns from `references/anti-patterns.md`
4. Provide a structured critique with specific improvement suggestions

### /design-regen
Regenerate mockup with a different design direction.
1. Keep the existing page structure and content
2. Ask user what direction to change (atmosphere, colors, layout, typography)
3. Update DESIGN.md tokens accordingly
4. Regenerate the HTML with the new design system

## Optional MCP Enhancements

When configured, these MCP servers enhance the workflow:

| MCP Server | Phase | What It Adds |
|------------|-------|-------------|
| RenderLens | 6 | HTML→screenshot, Lighthouse audit, pixel-level diff |
| AccessLint | 6 | WCAG violation detection + auto-fix (99.5% fix rate) |
| Playwright | 6 | Screenshot at multiple viewports, visual regression |

The skill works fully without any MCP servers. MCPs are enhancements, not requirements.

## Escalation Rules

| Situation | Action |
|-----------|--------|
| Unclear design direction | **ASK user** — present direction options |
| Conflicting requirements (e.g., "minimal but feature-rich") | **ASK user** which to prioritize |
| User asks for a framework-specific output (React, Vue) | **WARN**: this skill generates HTML+CSS mockups; suggest adapting after approval |
| Generated mockup looks wrong in visual verification | Auto-fix if possible; **ASK user** if the issue is subjective |
| User requests multi-page site | Generate one page at a time; maintain DESIGN.md consistency across pages |
| Accessibility audit fails | Auto-fix violations; **WARN user** about remaining manual-check items |