ui-ux

UI/​UX

Searchable design intelligence database for web and mobile applications. Generates complete design systems with style, color palette, typography, and UX guidelines. BM25 search engine across 13 technology stacks.

When to Activate

• User requests UI/​UX work: design, build, create, implement, review, fix, improve
• User asks for color palettes, font pairings, or style recommendations
• User builds a landing page, dashboard, portfolio, or any web/​mobile interface
• User mentions dark mode, accessibility, responsive design, or layout issues
• User asks to review or audit existing UI for quality issues

---

Rule Categories by Priority

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.