add python scaffold folder and autodevelopment system

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

@@ -0,0 +1,254 @@
+---
+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
+
+## 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. 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 |

.cursor/skills/ui-design/references/anti-patterns.md

@@ -0,0 +1,69 @@
+# Anti-Patterns — AI Slop Prevention
+
+Read this file before generating any HTML/CSS. These are explicit instructions for what NOT to do.
+
+## Typography Anti-Patterns
+
+- **Do NOT default to Inter or Roboto.** These are the #1 signal of AI-generated UI. Choose a font that matches the atmosphere from `design-vocabulary.md`. Only use Inter/Roboto if the user explicitly requests them.
+- **Do NOT use the same font weight everywhere.** Establish a clear weight hierarchy: 600-700 for headings, 400 for body, 500 for UI elements.
+- **Do NOT set body text smaller than 14px (0.875rem).** Prefer 16px (1rem) for body.
+- **Do NOT skip heading levels.** Go h1 → h2 → h3, never h1 → h3.
+- **Do NOT use placeholder-only form fields.** Labels above inputs are mandatory; placeholders are hints only.
+
+## Color Anti-Patterns
+
+- **Do NOT default to purple or indigo accent colors.** Purple/indigo is the second-biggest AI-slop signal. Use the accent color from DESIGN.md tokens.
+- **Do NOT use more than 1 strong accent color** in the same view. Secondary accents should be muted or derived from the primary.
+- **Do NOT use gray text on colored backgrounds** without checking contrast. WCAG AA requires 4.5:1 for normal text, 3:1 for large text.
+- **Do NOT use rainbow color coding** for categories. Limit to 5-6 carefully chosen, distinguishable colors.
+- **Do NOT apply background gradients to text** (gradient text is fragile and often unreadable).
+
+## Layout Anti-Patterns
+
+- **Do NOT create "card soup"** — rows of identical cards with no visual break. Vary layout patterns: full-width sections, split layouts, featured items, asymmetric grids.
+- **Do NOT center everything.** Left-align body text. Center only headings, short captions, and CTAs.
+- **Do NOT use fixed pixel widths** for layout. Use relative units (%, fr, auto, minmax).
+- **Do NOT nest excessive containers.** Avoid "div soup" — use semantic elements (nav, main, section, article, aside, footer).
+- **Do NOT ignore mobile.** Design mobile-first; every component must work at 375px width.
+
+## Component Anti-Patterns
+
+- **Do NOT make all buttons equal weight.** Establish clear hierarchy: one primary (filled), secondary (outline), ghost (text-only) per visible area.
+- **Do NOT use spinners for content with known layout.** Use skeleton loaders that match the shape of the content.
+- **Do NOT put a modal inside a modal.** If you need nested interaction, use a slide-over or expand the current modal.
+- **Do NOT disable buttons without explanation.** Every disabled button needs a title attribute or adjacent text explaining why.
+- **Do NOT use "Click here" as link text.** Links should describe the destination: "View documentation", "Download report".
+- **Do NOT show hamburger menus on desktop.** Hamburgers are for mobile only; use full navigation on desktop.
+- **Do NOT use equal-weight buttons in a pair.** One must be visually primary, the other secondary.
+
+## Interaction Anti-Patterns
+
+- **Do NOT skip hover states on interactive elements.** Every clickable element needs a visible hover change.
+- **Do NOT skip focus states.** Keyboard users need visible focus indicators on every interactive element.
+- **Do NOT omit loading states.** If data loads asynchronously, show a skeleton or progress indicator.
+- **Do NOT omit empty states.** When a list or section has no data, show an illustration + explanation + action CTA.
+- **Do NOT omit error states.** Form validation errors need inline messages below the field with an icon.
+- **Do NOT use bare alert() for messages.** Use toast notifications or inline banners.
+
+## Decoration Anti-Patterns
+
+- **Do NOT over-decorate.** Restraint over decoration. Every visual element must earn its place.
+- **Do NOT apply shadows AND borders AND background fills simultaneously** on the same element. Pick one or two.
+- **Do NOT use generic stock-photo placeholder images.** Use SVG illustrations, solid color blocks with icons, or real content.
+- **Do NOT use decorative backgrounds** that reduce text readability.
+- **Do NOT animate everything.** Use motion sparingly and purposefully: transitions for state changes (200-300ms), not decorative animation.
+
+## Spacing Anti-Patterns
+
+- **Do NOT use inconsistent spacing.** Stick to the spacing scale from DESIGN.md (multiples of 4px or 8px base unit).
+- **Do NOT use zero padding inside containers.** Minimum 12-16px padding for any content container.
+- **Do NOT crowd elements.** When in doubt, add more whitespace, not less.
+- **Do NOT use different spacing systems** in different parts of the same page. One scale for the whole page.
+
+## Accessibility Anti-Patterns
+
+- **Do NOT rely on color alone** to convey information. Add icons, text, or patterns.
+- **Do NOT use thin font weights (100-300) for body text.** Minimum 400 for readability.
+- **Do NOT create custom controls** without proper ARIA attributes. Prefer native HTML elements.
+- **Do NOT trap keyboard focus** outside of modals. Only modals should have focus traps.
+- **Do NOT auto-play media** without user consent and a visible stop/mute control.

.cursor/skills/ui-design/references/components.md

@@ -0,0 +1,307 @@
+# Component Reference
+
+Use this reference when generating UI mockups. Each component includes best practices, required states, and accessibility requirements.
+
+## Navigation
+
+### Top Navigation Bar
+- Fixed or sticky at top; z-index above content
+- Logo/brand left, primary nav center or right, actions (search, profile, CTA) far right
+- Active state: underline, background highlight, or bold — pick one, be consistent
+- Mobile: collapse to hamburger menu at `md` breakpoint; never show hamburger on desktop
+- Height: 56-72px; padding inline 16-24px
+- Aliases: navbar, header nav, app bar, top bar
+
+### Sidebar Navigation
+- Width: 240-280px expanded, 64-72px collapsed
+- Sections with labels; icons + text for each item
+- Active item: background fill + accent color text/icon
+- Collapse/expand toggle; responsive: overlay on mobile
+- Scroll independently from main content if taller than viewport
+- Aliases: side nav, drawer, rail
+
+### Breadcrumbs
+- Show hierarchy path; separator: `/` or `>`
+- Current page is plain text (not a link); parent pages are links
+- Truncate with ellipsis if more than 4-5 levels
+- Aliases: path indicator, navigation trail
+
+### Tabs
+- Use for switching between related content views within the same context
+- Active tab: border-bottom accent or filled background
+- Never nest tabs inside tabs
+- Scrollable when too many to fit; show scroll indicators
+- Aliases: tab bar, segmented control, view switcher
+
+### Pagination
+- Show current page, first, last, and 2-3 surrounding pages
+- Previous/Next buttons always visible; disabled at boundaries
+- Show total count when available: "Showing 1-20 of 342"
+- Aliases: pager, page navigation
+
+## Content Display
+
+### Card
+- Border-radius: 8-12px; subtle shadow or border (not both unless intentional)
+- Padding: 16-24px; consistent within the same card grid
+- Content order: image/visual → title → description → metadata → actions
+- Hover: subtle shadow lift or border-color change (not both)
+- Never stack more than 3 cards vertically without visual break
+- Aliases: tile, panel, content block
+
+### Data Table
+- Header row: sticky, slightly bolder background, sort indicators
+- Row hover: subtle background change
+- Striped rows optional; alternate between base and surface colors
+- Cell padding: 12-16px vertical, 16px horizontal
+- Truncate long text with ellipsis + tooltip on hover
+- Responsive: horizontal scroll with frozen first column, or stack to card layout on mobile
+- Include empty state when no data
+- Aliases: grid, spreadsheet, list view
+
+### List
+- Consistent item height or padding
+- Dividers between items: subtle border or spacing (not both)
+- Interactive lists: hover state on entire row
+- Leading element (icon/avatar) + content (title + subtitle) + trailing element (action/badge)
+- Aliases: item list, feed, timeline
+
+### Stat/Metric Card
+- Large number/value prominently displayed
+- Label above or below the value; comparison/trend indicator optional
+- Color-code trends: green up, red down, gray neutral
+- Aliases: KPI card, metric tile, stat block
+
+### Avatar
+- Circular; sizes: 24/32/40/48/64px
+- Fallback: initials on colored background when no image
+- Status indicator: small circle at bottom-right (green=online, gray=offline)
+- Group: overlap with z-index stacking; show "+N" for overflow
+- Aliases: profile picture, user icon
+
+### Badge/Tag
+- Small, pill-shaped or rounded-rectangle
+- Color indicates category or status; limit to 5-6 distinct colors
+- Text: short (1-3 words); truncate if longer
+- Removable variant: include x button
+- Aliases: chip, label, status indicator
+
+### Hero Section
+- Full-width; height 400-600px or viewport-relative
+- Strong headline (h1) + supporting text + primary CTA
+- Background: gradient, image with overlay, or solid color — not all three
+- Text must have sufficient contrast over any background
+- Aliases: banner, jumbotron, splash
+
+### Empty State
+- Illustration or icon (not a generic placeholder)
+- Explanatory text: what this area will contain
+- Primary action CTA: "Create your first...", "Add...", "Import..."
+- Never show just blank space
+- Aliases: zero state, no data, blank slate
+
+### Skeleton Loader
+- Match the shape and layout of the content being loaded
+- Animate with subtle pulse or shimmer (left-to-right gradient)
+- Show for predictable content; use progress bar for uploads/processes
+- Never use spinning loaders for content that has a known layout
+- Aliases: placeholder, loading state, content loader
+
+## Forms & Input
+
+### Text Input
+- Height: 40-48px; padding inline 12-16px
+- Label above the input (not placeholder-only); placeholder as hint only
+- States: default, hover, focus (accent ring), error (red border + message), disabled (reduced opacity)
+- Error message below the field with icon; don't use red placeholder
+- Aliases: text field, input box, form field
+
+### Textarea
+- Minimum height: 80-120px; resizable vertically
+- Character count when there's a limit
+- Same states as text input
+- Aliases: multiline input, text area, comment box
+
+### Select/Dropdown
+- Match text input height and styling
+- Chevron indicator on the right
+- Options list: max height with scroll; selected item checkmark
+- Search/filter for lists longer than 10 items
+- Aliases: combo box, picker, dropdown menu
+
+### Checkbox
+- Size: 16-20px; rounded corners (2-4px)
+- Label to the right; clickable area includes the label
+- States: unchecked, checked (accent fill + white check), indeterminate (dash), disabled
+- Group: vertical stack with 8-12px gap
+- Aliases: check box, toggle option, multi-select
+
+### Radio Button
+- Size: 16-20px; circular
+- Same interaction patterns as checkbox but single-select
+- Group: vertical stack; minimum 2 options
+- Aliases: radio, option button, single-select
+
+### Toggle/Switch
+- Width: 40-52px; height: 20-28px; thumb is circular
+- Off: gray track; On: accent color track
+- Label to the left or right; describe the "on" state
+- Never use for actions that require a submit; toggles are instant
+- Aliases: switch, on/off toggle
+
+### File Upload
+- Drop zone with dashed border; icon + "Drag & drop or click to upload"
+- Show file type restrictions and size limit
+- Progress indicator during upload
+- File list after upload: name, size, remove button
+- Aliases: file picker, upload area, attachment
+
+### Form Layout
+- Single column for most forms; two columns only for related short fields (first/last name, city/state)
+- Group related fields with section headings
+- Required field indicator: asterisk after label
+- Submit button: right-aligned or full-width; clearly primary
+- Inline validation: show errors on blur, not on every keystroke
+
+## Actions
+
+### Button
+- Primary: filled accent color, white text; one per visible area
+- Secondary: outline or subtle background; supports primary action
+- Ghost/tertiary: text-only with hover background
+- Sizes: sm (32px), md (40px), lg (48px); padding inline 16-24px
+- States: default, hover (darken/lighten 10%), active (darken 15%), focus (ring), disabled (opacity 0.5 + not-allowed cursor)
+- Disabled buttons must have a title attribute explaining why
+- Icon-only buttons: need aria-label; minimum 40px touch target
+- Aliases: action, CTA, submit
+
+### Icon Button
+- Circular or rounded-square; minimum 40px for touch targets
+- Tooltip on hover showing the action name
+- Visually lighter than text buttons
+- Aliases: toolbar button, action icon
+
+### Dropdown Menu
+- Trigger: button or icon button
+- Menu: elevated surface (shadow), rounded corners
+- Items: 36-44px height; icon + label; hover background
+- Dividers between groups; section labels for grouped items
+- Keyboard navigable: arrow keys, enter to select, escape to close
+- Aliases: context menu, action menu, overflow menu
+
+### Floating Action Button (FAB)
+- Circular, 56px; elevated with shadow
+- One per screen maximum; bottom-right placement
+- Primary creation action only
+- Extended variant: pill-shape with icon + label
+- Aliases: FAB, add button, create button
+
+## Feedback
+
+### Toast/Notification
+- Position: top-right or bottom-right; stack vertically
+- Auto-dismiss: 4-6 seconds for info; persist for errors until dismissed
+- Types: success (green), error (red), warning (amber), info (blue)
+- Content: icon + message + optional action link + close button
+- Maximum 3 visible at once; queue the rest
+- Aliases: snackbar, alert toast, flash message
+
+### Alert/Banner
+- Full-width within its container; not floating
+- Types: info, success, warning, error with corresponding colors
+- Icon left, message center, dismiss button right
+- Persistent until user dismisses or condition changes
+- Aliases: notice, inline alert, status banner
+
+### Modal/Dialog
+- Centered; overlay dims background (opacity 0.5 black)
+- Max width: 480-640px for standard, 800px for complex
+- Header (title + close button) + body + footer (actions)
+- Actions: right-aligned; primary right, secondary left
+- Close on overlay click and Escape key
+- Never put a modal inside a modal
+- Focus trap: tab cycles within modal while open
+- Aliases: popup, dialog box, lightbox
+
+### Tooltip
+- Appears on hover after 300-500ms delay; disappears on mouse leave
+- Position: above element by default; flip if near viewport edge
+- Max width: 200-280px; short text only
+- Arrow/caret pointing to trigger element
+- Aliases: hint, info popup, hover text
+
+### Progress Indicator
+- Linear bar: for known duration/percentage; show percentage text
+- Skeleton: for content loading with known layout
+- Spinner: only for indeterminate short waits (< 3 seconds) where layout is unknown
+- Step indicator: for multi-step flows; show completed/current/upcoming
+- Aliases: loading bar, progress bar, stepper
+
+## Layout
+
+### Page Shell
+- Max content width: 1200-1440px; centered with auto margins
+- Sidebar + main content pattern: sidebar fixed, main scrolls
+- Header/footer outside max-width for full-bleed effect
+- Consistent padding: 16px mobile, 24px tablet, 32px desktop
+
+### Grid
+- CSS Grid or Flexbox; 12-column system or auto-fit with minmax
+- Gap: 16-24px between items
+- Responsive: 1 column mobile, 2 columns tablet, 3-4 columns desktop
+- Never rely on fixed pixel widths; use fr units or percentages
+
+### Section Divider
+- Use spacing (48-96px margin) as primary divider; use lines sparingly
+- If using lines: subtle (1px, border color); full-width or indented
+- Alternate section backgrounds (base/surface) for clear separation without lines
+
+### Responsive Breakpoints
+- sm: 640px (large phone landscape)
+- md: 768px (tablet)
+- lg: 1024px (small laptop)
+- xl: 1280px (desktop)
+- Design mobile-first: base styles are mobile, layer up with breakpoints
+
+## Specialized
+
+### Pricing Table
+- 2-4 tiers side by side; highlight recommended tier
+- Feature comparison with checkmarks; group features by category
+- CTA button per tier; recommended tier has primary button, others secondary
+- Monthly/annual toggle if applicable
+- Aliases: pricing cards, plan comparison
+
+### Testimonial
+- Quote text (large, italic or with quotation marks)
+- Attribution: avatar + name + title/company
+- Layout: single featured or carousel/grid of multiple
+- Aliases: review, customer quote, social proof
+
+### Footer
+- Full-width; darker background than body
+- Column layout: links grouped by category; 3-5 columns
+- Bottom row: copyright, legal links, social icons
+- Responsive: columns stack on mobile
+- Aliases: site footer, bottom navigation
+
+### Search
+- Input with search icon; expand on focus or always visible
+- Results: dropdown with highlighted matching text
+- Recent searches and suggestions
+- Keyboard shortcut hint (Cmd+K / Ctrl+K)
+- Aliases: search bar, omnibar, search field
+
+### Date Picker
+- Input that opens a calendar dropdown
+- Navigate months with arrows; today highlighted
+- Range selection: two calendars side by side
+- Presets: "Today", "Last 7 days", "This month"
+- Aliases: calendar picker, date selector
+
+### Chart/Graph Placeholder
+- Container with appropriate aspect ratio (16:9 for line/bar, 1:1 for pie)
+- Include chart title, legend, and axis labels in the mockup
+- Use representative fake data; label as "Sample Data"
+- Tooltip placeholder on hover
+- Aliases: data visualization, graph, analytics chart

.cursor/skills/ui-design/references/design-vocabulary.md

@@ -0,0 +1,139 @@
+# Design Vocabulary
+
+Use this reference when writing DESIGN.md files and constructing generation prompts. Replace vague descriptors with specific, actionable terms.
+
+## Atmosphere Descriptors
+
+Use these instead of "clean and modern":
+
+| Atmosphere | Characteristics | Font Direction | Color Direction | Spacing |
+|------------|----------------|---------------|-----------------|---------|
+| **Airy & Spacious** | Generous whitespace, light backgrounds, floating elements, subtle shadows | Thin/light weights, generous letter-spacing | Soft pastels, whites, muted accents | Large margins, open padding |
+| **Dense & Data-Rich** | Compact spacing, information-heavy, efficient use of space | Medium weights, tighter line-heights, smaller sizes | Neutral grays, high-contrast data colors | Tight but consistent padding |
+| **Warm & Approachable** | Rounded corners, friendly illustrations, organic shapes | Rounded/humanist typefaces, comfortable sizes | Earth tones, warm neutrals, amber/coral accents | Medium spacing, generous touch targets |
+| **Sharp & Technical** | Crisp edges, precise alignment, monospace elements, dark themes | Geometric or monospace, precise sizing | Cool grays, electric blues/greens, dark backgrounds | Grid-strict, mathematical spacing |
+| **Luxurious & Premium** | Generous space, refined details, serif accents, subtle animations | Serif or elegant sans-serif, generous sizing | Deep darks, gold/champagne accents, rich jewel tones | Expansive whitespace, dramatic padding |
+| **Playful & Creative** | Asymmetric layouts, bold colors, hand-drawn elements, motion | Display fonts, variable weights, expressive sizing | Bright saturated colors, unexpected combinations | Dynamic, deliberately uneven |
+| **Corporate & Enterprise** | Structured grids, predictable patterns, dense but organized | System fonts or conservative sans-serif | Brand blues/grays, accent for status indicators | Systematic, spec-driven |
+| **Editorial & Content** | Typography-forward, reading-focused, long-form layout | Serif for body text, sans for UI elements | Near-monochrome, sparse accent color | Generous line-height, wide columns |
+
+## Style-Specific Vocabulary
+
+### When user says... → Use these terms in DESIGN.md
+
+| Vague Input | Professional Translation |
+|-------------|------------------------|
+| "clean" | Restrained palette, generous whitespace, consistent alignment grid |
+| "modern" | Current design patterns (2024-2026), subtle depth, micro-interactions |
+| "minimal" | Single accent color, maximum negative space, typography-driven hierarchy |
+| "professional" | Structured grid, conservative palette, system fonts, clear navigation |
+| "fun" | Saturated palette, rounded elements, playful illustrations, motion |
+| "elegant" | Serif typography, muted palette, generous spacing, refined details |
+| "techy" | Dark theme, monospace accents, neon highlights, sharp corners |
+| "bold" | High contrast, large type, strong color blocks, dramatic layout |
+| "friendly" | Rounded corners (12-16px), humanist fonts, warm colors, illustrations |
+| "corporate" | Blue-gray palette, structured grid, conventional layout, data tables |
+
+## Color Mood Palettes
+
+### Cool Blues & Grays
+- Background: #f8fafc → #f1f5f9
+- Surface: #ffffff
+- Text: #0f172a → #475569
+- Accent: #2563eb (blue-600)
+- Pairs well with: Airy, Sharp, Corporate atmospheres
+
+### Warm Earth Tones
+- Background: #faf8f5 → #f5f0eb
+- Surface: #ffffff
+- Text: #292524 → #78716c
+- Accent: #c2410c (orange-700) or #b45309 (amber-700)
+- Pairs well with: Warm, Editorial atmospheres
+
+### Bold & Vibrant
+- Background: #fafafa → #f5f5f5
+- Surface: #ffffff
+- Text: #171717 → #525252
+- Accent: #dc2626 (red-600) or #7c3aed (violet-600) or #059669 (emerald-600)
+- Pairs well with: Playful, Creative atmospheres
+
+### Monochrome
+- Background: #fafafa → #f5f5f5
+- Surface: #ffffff
+- Text: #171717 → #737373
+- Accent: #171717 (black) with #e5e5e5 borders
+- Pairs well with: Minimal, Luxurious, Editorial atmospheres
+
+### Dark Mode
+- Background: #09090b → #18181b
+- Surface: #27272a → #3f3f46
+- Text: #fafafa → #a1a1aa
+- Accent: #3b82f6 (blue-500) or #22d3ee (cyan-400)
+- Pairs well with: Sharp, Technical, Dense atmospheres
+
+## Typography Mood Mapping
+
+### Geometric (Modern, Clean)
+Fonts: DM Sans, Plus Jakarta Sans, Outfit, General Sans, Satoshi
+- Characteristics: even stroke weight, circular letter forms, precise geometry
+- Best for: SaaS, tech products, dashboards, landing pages
+
+### Humanist (Friendly, Readable)
+Fonts: Source Sans 3, Nunito, Lato, Open Sans, Noto Sans
+- Characteristics: organic curves, varying stroke, warm feel
+- Best for: consumer apps, health/wellness, education, community platforms
+
+### Monospace (Technical, Code-Like)
+Fonts: JetBrains Mono, Fira Code, IBM Plex Mono, Space Mono
+- Characteristics: fixed-width, technical aesthetic, raw precision
+- Best for: developer tools, terminals, data displays, documentation
+
+### Serif (Editorial, Premium)
+Fonts: Playfair Display, Lora, Merriweather, Crimson Pro, Libre Baskerville
+- Characteristics: traditional elegance, reading comfort, authority
+- Best for: blogs, magazines, luxury brands, portfolio sites
+
+### Display (Expressive, Bold)
+Fonts: Cabinet Grotesk, Clash Display, Archivo Black, Space Grotesk
+- Characteristics: high impact, personality-driven, attention-grabbing
+- Best for: hero sections, headlines, creative portfolios, marketing pages
+- Use for headings only; pair with a readable body font
+
+## Shape & Depth Vocabulary
+
+### Border Radius Scale
+| Term | Value | Use for |
+|------|-------|---------|
+| Sharp | 0-2px | Technical, enterprise, data-heavy |
+| Subtle | 4-6px | Professional, balanced |
+| Rounded | 8-12px | Friendly, modern SaaS |
+| Pill | 16-24px or full | Playful, badges, tags |
+| Circle | 50% | Avatars, icon buttons |
+
+### Shadow Scale
+| Term | Value | Use for |
+|------|-------|---------|
+| None | none | Flat design, minimal |
+| Whisper | 0 1px 2px rgba(0,0,0,0.05) | Subtle elevation, cards |
+| Soft | 0 4px 6px rgba(0,0,0,0.07) | Standard cards, dropdowns |
+| Medium | 0 10px 15px rgba(0,0,0,0.1) | Elevated elements, modals |
+| Strong | 0 20px 25px rgba(0,0,0,0.15) | Floating elements, popovers |
+
+### Surface Hierarchy
+1. **Background** — deepest layer, covers viewport
+2. **Surface** — content containers (cards, panels) sitting on background
+3. **Elevated** — elements above surface (modals, dropdowns, tooltips)
+4. **Overlay** — dimming layer between surface and elevated elements
+
+## Layout Pattern Names
+
+| Pattern | Description | Best for |
+|---------|-------------|----------|
+| **Holy grail** | Header + sidebar + main + footer | Admin dashboards, apps |
+| **Magazine** | Multi-column with varied widths | Content sites, blogs |
+| **Single column** | Centered narrow content | Landing pages, articles, forms |
+| **Split screen** | Two equal or 60/40 halves | Comparison pages, sign-up flows |
+| **Card grid** | Uniform grid of cards | Product listings, portfolios |
+| **Asymmetric** | Deliberately unequal columns | Creative, editorial layouts |
+| **Full bleed** | Edge-to-edge sections, no max-width | Marketing pages, portfolios |
+| **Dashboard** | Stat cards + charts + tables in grid | Analytics, admin panels |

.cursor/skills/ui-design/references/quality-checklist.md

@@ -0,0 +1,109 @@
+# Quality Checklist
+
+Run through this checklist after generating or modifying a mockup. Three layers; run all that apply.
+
+## Layer 1: Structural Check (Always Run)
+
+### Semantic HTML
+- [ ] Uses `nav`, `main`, `section`, `article`, `aside`, `footer` — not just `div`
+- [ ] Single `h1` per page
+- [ ] Heading hierarchy follows h1 → h2 → h3 without skipping levels
+- [ ] Lists use `ul`/`ol`/`li`, not styled `div`s
+- [ ] Interactive elements are `button` or `a`, not clickable `div`s
+
+### Design Tokens
+- [ ] CSS custom properties defined in `<style>` block
+- [ ] Colors in HTML reference tokens (e.g., `var(--color-accent)`) not raw hex
+- [ ] Spacing follows the defined scale, not arbitrary pixel values
+- [ ] Font family matches DESIGN.md, not browser default or Inter/Roboto
+
+### Responsive Design
+- [ ] Mobile-first: base styles work at 375px
+- [ ] Content readable without horizontal scroll at all breakpoints
+- [ ] Navigation adapts: full nav on desktop, collapsed on mobile
+- [ ] Images/media have max-width: 100%
+- [ ] Touch targets minimum 44px on mobile
+
+### Interaction States
+- [ ] All buttons have hover, focus, active states
+- [ ] All links have hover and focus states
+- [ ] At least one loading state example (skeleton loader preferred)
+- [ ] At least one empty state with illustration + CTA
+- [ ] Disabled elements have visual indicator + explanation (title attribute)
+- [ ] Form inputs have focus ring using accent color
+
+### Component Quality
+- [ ] Button hierarchy: one primary per visible area, secondary and ghost variants present
+- [ ] Forms: labels above inputs, not placeholder-only
+- [ ] Error states: inline message below field with icon
+- [ ] No hamburger menu on desktop
+- [ ] No modal inside modal
+- [ ] No "Click here" links
+
+### Code Quality
+- [ ] Valid HTML (no unclosed tags, no duplicate IDs)
+- [ ] Tailwind classes are valid (no made-up utilities)
+- [ ] No inline styles that duplicate token values
+- [ ] File is self-contained (single HTML file, no external dependencies except Tailwind CDN)
+- [ ] Total file size under 50KB
+
+## Layer 2: Visual Check (When Browser Tool Available)
+
+Take a screenshot and examine:
+
+### Spacing & Alignment
+- [ ] Consistent margins between sections
+- [ ] Elements within the same row are vertically aligned
+- [ ] Padding within cards/containers is consistent
+- [ ] No orphan text (single word on its own line in headings)
+- [ ] Grid alignment: elements on the same row have matching heights or intentional variation
+
+### Typography
+- [ ] Heading sizes create clear hierarchy (visible difference between h1, h2, h3)
+- [ ] Body text is comfortable reading size (not tiny)
+- [ ] Font rendering looks correct (font loaded or appropriate fallback)
+- [ ] Line length: body text 50-75 characters per line
+
+### Color & Contrast
+- [ ] Primary accent is visible but not overwhelming
+- [ ] Text is readable over all backgrounds
+- [ ] No elements blend into their backgrounds
+- [ ] Status colors (success/error/warning) are distinguishable
+
+### Overall Composition
+- [ ] Visual weight is balanced (not all content on one side)
+- [ ] Clear focal point on the page (hero, headline, or primary CTA)
+- [ ] Appropriate whitespace: not cramped, not excessively empty
+- [ ] Consistent visual language throughout the page
+
+### Atmosphere Match
+- [ ] Overall feel matches the DESIGN.md atmosphere description
+- [ ] Not generic "AI generated" look
+- [ ] Color palette is cohesive (no unexpected color outliers)
+- [ ] Typography choice matches the intended mood
+
+## Layer 3: Compliance Check (When MCP Tools Available)
+
+### AccessLint MCP
+- [ ] Run `audit_html` on the generated file
+- [ ] Fix all violations with fixability "fixable" or "potentially_fixable"
+- [ ] Document any remaining violations that require manual judgment
+- [ ] Re-run `diff_html` to confirm fixes resolved violations
+
+### RenderLens MCP
+- [ ] Render at 1440px and 375px widths
+- [ ] Lighthouse accessibility score ≥ 80
+- [ ] Lighthouse performance score ≥ 70
+- [ ] Lighthouse best practices score ≥ 80
+- [ ] If iterating: run diff between previous and current version
+
+## Severity Classification
+
+When reporting issues found during the checklist:
+
+| Severity | Criteria | Action |
+|----------|----------|--------|
+| **Critical** | Broken layout, invisible content, no mobile support | Fix immediately before showing to user |
+| **High** | Missing interaction states, accessibility violations, token misuse | Fix before showing to user |
+| **Medium** | Minor spacing inconsistency, non-ideal font weight, slight alignment issue | Note in assessment, fix if easy |
+| **Low** | Style preference, minor polish opportunity | Note in assessment, fix during /design-polish |

.cursor/skills/ui-design/templates/design-system.md

@@ -0,0 +1,199 @@
+# Design System: [Project Name]
+
+## 1. Visual Atmosphere
+
+[Describe the mood, density, and aesthetic philosophy in 2-3 sentences. Be specific — never use "clean and modern". Reference the atmosphere type from design-vocabulary.md. Example: "A spacious, light-filled interface with generous whitespace that feels calm and unhurried. Elements float on a near-white canvas with subtle shadows providing depth. The overall impression is sophisticated simplicity — premium without being cold."]
+
+## 2. Color System
+
+### Primitives
+
+```css
+:root {
+  --white: #ffffff;
+  --black: #000000;
+
+  --gray-50: #______;
+  --gray-100: #______;
+  --gray-200: #______;
+  --gray-300: #______;
+  --gray-400: #______;
+  --gray-500: #______;
+  --gray-600: #______;
+  --gray-700: #______;
+  --gray-800: #______;
+  --gray-900: #______;
+  --gray-950: #______;
+
+  --accent-50: #______;
+  --accent-100: #______;
+  --accent-200: #______;
+  --accent-300: #______;
+  --accent-400: #______;
+  --accent-500: #______;
+  --accent-600: #______;
+  --accent-700: #______;
+  --accent-800: #______;
+  --accent-900: #______;
+
+  --red-500: #______;
+  --red-600: #______;
+  --green-500: #______;
+  --green-600: #______;
+  --amber-500: #______;
+  --amber-600: #______;
+}
+```
+
+### Semantic Tokens
+
+```css
+:root {
+  --color-bg-primary: var(--gray-50);
+  --color-bg-secondary: var(--gray-100);
+  --color-bg-surface: var(--white);
+  --color-bg-inverse: var(--gray-900);
+
+  --color-text-primary: var(--gray-900);
+  --color-text-secondary: var(--gray-500);
+  --color-text-tertiary: var(--gray-400);
+  --color-text-inverse: var(--white);
+  --color-text-link: var(--accent-600);
+
+  --color-accent: var(--accent-600);
+  --color-accent-hover: var(--accent-700);
+  --color-accent-light: var(--accent-50);
+
+  --color-border: var(--gray-200);
+  --color-border-strong: var(--gray-300);
+  --color-divider: var(--gray-100);
+
+  --color-error: var(--red-600);
+  --color-error-light: var(--red-500);
+  --color-success: var(--green-600);
+  --color-success-light: var(--green-500);
+  --color-warning: var(--amber-600);
+  --color-warning-light: var(--amber-500);
+}
+```
+
+### Component Tokens
+
+```css
+:root {
+  --button-primary-bg: var(--color-accent);
+  --button-primary-text: var(--color-text-inverse);
+  --button-primary-hover: var(--color-accent-hover);
+  --button-secondary-bg: transparent;
+  --button-secondary-border: var(--color-border-strong);
+  --button-secondary-text: var(--color-text-primary);
+
+  --card-bg: var(--color-bg-surface);
+  --card-border: var(--color-border);
+  --card-shadow: 0 1px 3px rgba(0, 0, 0, 0.08);
+
+  --input-bg: var(--color-bg-surface);
+  --input-border: var(--color-border);
+  --input-border-focus: var(--color-accent);
+  --input-text: var(--color-text-primary);
+  --input-placeholder: var(--color-text-tertiary);
+
+  --nav-bg: var(--color-bg-surface);
+  --nav-active-bg: var(--color-accent-light);
+  --nav-active-text: var(--color-accent);
+}
+```
+
+## 3. Typography
+
+- **Font family**: [Specific font name], [fallback], system-ui, sans-serif
+- **Font source**: Google Fonts link or system font
+
+| Level | Element | Size | Weight | Line Height | Letter Spacing |
+|-------|---------|------|--------|-------------|----------------|
+| Display | Hero headlines | 3rem (48px) | 700 | 1.1 | -0.02em |
+| H1 | Page title | 2.25rem (36px) | 700 | 1.2 | -0.01em |
+| H2 | Section title | 1.5rem (24px) | 600 | 1.3 | 0 |
+| H3 | Subsection | 1.25rem (20px) | 600 | 1.4 | 0 |
+| H4 | Card/group title | 1.125rem (18px) | 600 | 1.4 | 0 |
+| Body | Default text | 1rem (16px) | 400 | 1.5 | 0 |
+| Small | Captions, meta | 0.875rem (14px) | 400 | 1.5 | 0.01em |
+| XS | Labels, badges | 0.75rem (12px) | 500 | 1.4 | 0.02em |
+
+## 4. Spacing & Layout
+
+- **Base unit**: 4px (0.25rem)
+- **Spacing scale**: 1 (4px), 2 (8px), 3 (12px), 4 (16px), 5 (20px), 6 (24px), 8 (32px), 10 (40px), 12 (48px), 16 (64px), 20 (80px), 24 (96px)
+- **Content max-width**: [1200px / 1280px / 1440px]
+- **Grid**: [12-column / auto-fit] with [16px / 24px] gap
+
+| Breakpoint | Name | Min Width | Columns | Padding |
+|------------|------|-----------|---------|---------|
+| Mobile | sm | 0 | 1 | 16px |
+| Tablet | md | 768px | 2 | 24px |
+| Laptop | lg | 1024px | 3-4 | 32px |
+| Desktop | xl | 1280px | 4+ | 32px |
+
+## 5. Component Styling Defaults
+
+### Buttons
+- Border radius: [6px / 8px / full]
+- Padding: 10px 20px (md), 8px 16px (sm), 12px 24px (lg)
+- Font weight: 500
+- Transition: background-color 150ms ease, box-shadow 150ms ease
+- Focus: 2px ring with 2px offset using `--color-accent`
+- Disabled: opacity 0.5, cursor not-allowed
+
+### Cards
+- Border radius: [8px / 12px]
+- Border: 1px solid var(--card-border)
+- Shadow: var(--card-shadow)
+- Padding: 20-24px
+- Hover (if interactive): shadow increase or border-color change
+
+### Inputs
+- Height: 40px (md), 36px (sm), 48px (lg)
+- Border radius: 6px
+- Border: 1px solid var(--input-border)
+- Padding: 0 12px
+- Focus: border-color var(--input-border-focus) + 2px ring
+- Error: border-color var(--color-error) + error message below
+
+### Navigation
+- Item height: 40px
+- Active: background var(--nav-active-bg), text var(--nav-active-text)
+- Hover: background var(--color-bg-secondary)
+- Transition: background-color 150ms ease
+
+## 6. Interaction States (MANDATORY)
+
+### Loading
+- Use skeleton loaders matching content shape
+- Pulse animation: opacity 0.4 → 1.0, duration 1.5s, ease-in-out
+- Background: var(--color-bg-secondary)
+
+### Error
+- Inline message below the element
+- Icon (circle-exclamation) + red text using var(--color-error)
+- Border change on the input/container to var(--color-error)
+
+### Empty
+- Centered illustration or icon (64-96px)
+- Heading: "No [items] yet" or similar
+- Descriptive text: one sentence explaining what will appear
+- Primary CTA button: "Create first...", "Add...", "Import..."
+
+### Hover
+- Interactive elements: subtle background shift or underline
+- Cards: shadow increase or border-color change
+- Transition: 150ms ease
+
+### Focus
+- Visible ring: 2px solid var(--color-accent), 2px offset
+- Applied to all interactive elements (buttons, inputs, links, tabs)
+- Never remove outline without providing alternative focus indicator
+
+### Disabled
+- Opacity: 0.5
+- Cursor: not-allowed
+- Title attribute explaining why the element is disabled