gps-denied-onboard/.cursor/skills/ui-design/SKILL.md

name, description, category, tags, disable-model-invocation

name	description	category	tags	disable-model-invocation
ui-design	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"	create	ui-design mockup html css tailwind design-system accessibility	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