azaion/annotations

Fork 0

mirror of https://github.com/azaion/annotations.git synced 2026-04-22 22:06:30 +00:00

Files

T

Oleksandr Bezdieniezhnykh e9c42e4888 Sync .cursor from suite (autodev orchestrator + monorepo skills)

2026-04-18 22:03:57 +03:00

13 KiB

Raw Permalink Blame History

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

name

description

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

Check for existing project documentation: PRD, design specs, README with design notes
Check for existing MOCKUPS_DIR/DESIGN.md
Check for existing mockups in MOCKUPS_DIR/
If DESIGN.md exists → announce "Using existing design system" → skip to Phase 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:

Visual Atmosphere — descriptive mood (never "clean and modern")
Color System — three-layer CSS custom properties (primitives → semantic → component)
Typography — specific font family, weight hierarchy, size scale with rem values
Spacing & Layout — base unit, spacing scale, grid, breakpoints
Component Styling Defaults — buttons, cards, inputs, navigation with all states
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:

Read MOCKUPS_DIR/DESIGN.md for the design system
Read references/components.md for component best practices relevant to the page type
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):

Open the generated HTML file using the browser tool
Take screenshots at desktop (1440px) width
Examine the screenshot for: spacing consistency, alignment, color rendering, typography hierarchy, overall visual balance
Compare against DESIGN.md's intended atmosphere
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

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)
Present assessment summary: structural check results, visual observations, compliance scores if available
Ask: "How does this look? What would you like me to change?"

Phase 8: Iteration

Parse user feedback into specific changes
Apply targeted edits via StrReplace (not full regeneration unless user requests a fundamentally different direction)
Re-run visual verification (Phase 6)
Present changes to user
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/.

Read the HTML file
Run structural checklist from references/quality-checklist.md
If browser tool available: take screenshot and visual check
If AccessLint MCP available: WCAG audit
Report findings with severity levels

/design-polish

Final refinement pass on an existing mockup.

Read the HTML file and DESIGN.md
Check token usage (no hardcoded values that should be tokens)
Verify all interaction states are present
Refine spacing consistency, typography hierarchy
Apply micro-improvements (subtle shadows, transitions, hover states)

/design-critique

UX review with specific feedback.

Read the HTML file
Evaluate: information hierarchy, call-to-action clarity, cognitive load, navigation flow
Check against anti-patterns from references/anti-patterns.md
Provide a structured critique with specific improvement suggestions

/design-regen

Regenerate mockup with a different design direction.

Keep the existing page structure and content
Ask user what direction to change (atmosphere, colors, layout, typography)
Update DESIGN.md tokens accordingly
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

13 KiB Raw Permalink Blame History