Ui Ux

Quick Reference

Accessibility (CRITICAL)

• color-contrast — Minimum 4.5:1 ratio for normal text
• focus-states — Visible focus rings on interactive elements
• alt-text — Descriptive alt text for meaningful images
• aria-labels — aria-label for icon-only buttons
• keyboard-nav — Tab order matches visual order
• form-labels — Use label with for attribute

Touch & Interaction (CRITICAL)

• touch-target-size — Minimum 44x44px touch targets
• hover-vs-tap — Use click/tap for primary interactions
• loading-buttons — Disable button during async operations
• cursor-pointer — Add cursor-pointer to clickable elements

Performance (HIGH)

• image-optimization — Use WebP, srcset, lazy loading
• reduced-motion — Check prefers-reduced-motion
• content-jumping — Reserve space for async content

Layout & Responsive (HIGH)

• viewport-meta — width=device-width initial-scale=1
• readable-font-size — Minimum 16px body text on mobile
• horizontal-scroll — Ensure content fits viewport width
• z-index-management — Define z-index scale (10, 20, 30, 50)

Prerequisites

python3 --version || python --version

If not installed — Windows: winget install Python.Python.3.12 | macOS: brew install python3 | Linux: sudo apt install python3

Workflow

Progress

• Analyzed user requirements (product type, style, industry, stack)
• Generated design system via --design-system
• Supplemented with domain searches (if needed)
• Applied stack guidelines
• Implemented UI with design system values
• Ran Pre-Delivery Checklist
• Delivered Changes Made summary

Step 1: Analyze User Requirements

Extract from the user's request:

Step 2: Generate Design System (REQUIRED)

Always start with --design-system to get comprehensive recommendations with reasoning:

python3 skills/ui-ux/scripts/search.py "<product_type> <industry> <keywords>" --design-system [-p "Project Name"]

This command:

1. Searches 5 domains in parallel (product, style, color, landing, typography)
2. Applies reasoning rules from ui-reasoning.csv to select best matches
3. Returns complete design system: pattern, style, colors, typography, effects
4. Includes anti-patterns to avoid

Example:

python3 skills/ui-ux/scripts/search.py "beauty spa wellness service" --design-system -p "Serenity Spa"

Step 2b: Persist Design System (Optional)

Save for hierarchical retrieval across sessions with --persist:

python3 skills/ui-ux/scripts/search.py "<query>" --design-system --persist -p "Project Name"

Creates design-system/MASTER.md (source of truth) and design-system/pages/ for overrides.

With page override: Add --page "dashboard" to create page-specific deviations.

Retrieval rule: Check pages/<page>.md first → if exists, overrides Master → otherwise use Master exclusively.

Step 3: Supplement with Detailed Searches

After the design system, use domain searches for additional detail:

python3 skills/ui-ux/scripts/search.py "<keyword>" --domain <domain> [-n <max_results>]

Step 4: Stack Guidelines (Default: html-tailwind)

python3 skills/ui-ux/scripts/search.py "<keyword>" --stack html-tailwind

Available: html-tailwind, react, nextjs, vue, svelte, swiftui, react-native, flutter, shadcn, jetpack-compose

Search Reference

Domains

Output Formats

# ASCII box (default)
python3 skills/ui-ux/scripts/search.py "fintech crypto" --design-system

# Markdown
python3 skills/ui-ux/scripts/search.py "fintech crypto" --design-system -f markdown

Constraints

• Do not use emoji as UI icons — always use SVG icons (Heroicons, Lucide, Simple Icons)
• Do not skip Step 2 (design system generation) — it's required before implementing any UI
• Do not use scale transforms for hover states — they cause layout shift; use color/opacity instead
• Do not hardcode colors — always derive from the generated design system palette
• Do not leave interactive elements without cursor-pointer
• Do not ignore prefers-reduced-motion for animations

Example

Input: "Build a landing page for a luxury spa brand" Workflow:

python3 skills/ui-ux/scripts/search.py "luxury spa wellness service" --design-system -p "Serenity Spa"

Output: Design system with elegant/organic style, warm muted palette (sage, cream, rose gold), Cormorant Garamond + Montserrat typography, subtle fade animations, and anti-patterns to avoid (no neon colors, no aggressive CTAs).

Common Rules for Professional UI

Icons & Visual Elements

Interaction & Cursor

Light/Dark Mode Contrast

Layout & Spacing

Error Handling

If the search script fails:

1. Verify Python is installed: python3 --version || python --version
2. Check the script path is correct: ls skills/ui-ux/scripts/
3. Run with help: python3 skills/ui-ux/scripts/search.py --help
4. Verify data files exist: ls skills/ui-ux/data/
5. If on Windows, try python instead of python3
6. Re-read the relevant section of this SKILL.md

Pre-Delivery Checklist

Visual Quality

• No emojis used as icons (use SVG instead)
• All icons from consistent icon set (Heroicons/Lucide)
• Brand logos correct (verified from Simple Icons)
• Hover states don't cause layout shift

Interaction

• All clickable elements have cursor-pointer
• Hover states provide clear visual feedback
• Transitions are smooth (150-300ms)
• Focus states visible for keyboard navigation

Light/Dark Mode

• Light mode text has sufficient contrast (4.5:1 minimum)
• Glass/transparent elements visible in light mode
• Borders visible in both modes

Layout

• Floating elements have proper spacing from edges
• No content hidden behind fixed navbars
• Responsive at 375px, 768px, 1024px, 1440px
• No horizontal scroll on mobile

Accessibility

• All images have alt text
• Form inputs have labels
• Color is not the only indicator
• prefers-reduced-motion respected

Changes Made Summary

• Changes Made summary delivered to user (see below)

Changes Made (MANDATORY)

[!CAUTION] This is NON-NEGOTIABLE. Every single UI/UX task MUST end with a "Changes Made" summary. This is the LAST thing you do — present it before any other closing remarks. Never skip this step, even for small changes.

After completing any UI/UX work, present the user with a structured summary:

## ✅ Changes Made

| # | File | Action | Detail |
|---|------|--------|--------|
| 1 | `index.html` | Created / Modified | <what was done> |
| 2 | `styles.css` | Created / Modified | <what was done> |
| 3 | `components/nav.html` | Created | <what was done> |

**Summary:** <1-2 sentence recap of the overall change>

Rules:

• List every file created, modified, or deleted
• Action column: Created, Modified, Deleted, Moved, or Renamed
• Detail column must be specific — not "updated file" but "added responsive navbar with dark mode toggle"
• End with a 1-2 sentence Summary of the overall impact

Worked example:

## ✅ Changes Made

| # | File | Action | Detail |
|---|------|--------|--------|
| 1 | `index.html` | Modified | Added floating navbar with glassmorphism effect, hero section with gradient overlay, testimonials grid |
| 2 | `styles.css` | Modified | Implemented design system tokens (--primary, --accent), added dark mode media query, responsive breakpoints at 375/768/1024px |
| 3 | `assets/hero-bg.webp` | Created | Generated hero background image with WebP format |

**Summary:** Built a luxury spa landing page using the Serenity Spa design system with dark mode support and responsive layout.