UI/UX Pro Max - Design Intelligence

Comprehensive design guide for web and mobile applications. Contains 50+ styles, 97 color palettes, 57 font pairings, 99 UX guidelines, and 25 chart types across 9 technology stacks. Searchable database with priority-based recommendations.

When to Apply

Reference these guidelines when:

• •Designing new UI components or pages
• •Choosing color palettes and typography
• •Reviewing code for UX issues
• •Building landing pages or dashboards
• •Implementing accessibility requirements

Rule Categories by Priority

Quick Reference

1. 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

2. 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
• •error-feedback - Clear error messages near problem
• •cursor-pointer - Add cursor-pointer to clickable elements

3. Performance (HIGH)

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

4. 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)

5. Typography & Color (MEDIUM)

• •line-height - Use 1.5-1.75 for body text
• •line-length - Limit to 65-75 characters per line
• •font-pairing - Match heading/body font personalities

6. Animation (MEDIUM)

• •duration-timing - Use 150-300ms for micro-interactions
• •transform-performance - Use transform/opacity, not width/height
• •loading-states - Skeleton screens or spinners

7. Style Selection (MEDIUM)

• •style-match - Match style to product type
• •consistency - Use same style across all pages
• •no-emoji-icons - Use SVG icons, not emojis

8. Charts & Data (LOW)

• •chart-type - Match chart type to data type
• •color-guidance - Use accessible color palettes
• •data-table - Provide table alternative for accessibility

How to Use

Search specific domains using the CLI tool below.

Prerequisites

Check if Python is installed:

python3 --version || python --version

If Python is not installed, install it based on user's OS:

macOS:

brew install python3

Ubuntu/Debian:

sudo apt update && sudo apt install python3

Windows:

winget install Python.Python.3.12

How to Use This Skill

When user requests UI/UX work (design, build, create, implement, review, fix, improve), follow this workflow:

Step 1: Analyze User Requirements

Extract key information from user request:

• •Product type: SaaS, e-commerce, portfolio, dashboard, landing page, etc.
• •Style keywords: minimal, playful, professional, elegant, dark mode, etc.
• •Industry: healthcare, fintech, gaming, education, etc.
• •Stack: React, Vue, Next.js, or default to html-tailwind

Step 2: Generate Design System (REQUIRED)

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

python3 skills/ui-ux-pro-max/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-pro-max/scripts/search.py "beauty spa wellness service" --design-system -p "Serenity Spa"

Step 2b: Persist Design System (Master + Overrides Pattern)

To save the design system for hierarchical retrieval across sessions, add --persist:

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

This creates:

• •design-system/MASTER.md — Global Source of Truth with all design rules
• •design-system/pages/ — Folder for page-specific overrides

With page-specific override:

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

This also creates:

• •design-system/pages/dashboard.md — Page-specific deviations from Master

How hierarchical retrieval works:

1. •When building a specific page (e.g., "Checkout"), first check design-system/pages/checkout.md
2. •If the page file exists, its rules override the Master file
3. •If not, use design-system/MASTER.md exclusively

Context-aware retrieval prompt:

I am building the [Page Name] page. Please read design-system/MASTER.md.
Also check if design-system/pages/[page-name].md exists.
If the page file exists, prioritize its rules.
If not, use the Master rules exclusively.
Now, generate the code...

Step 3: Supplement with Detailed Searches (as needed)

After getting the design system, use domain searches to get additional details:

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

When to use detailed searches:

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

Get implementation-specific best practices. If user doesn't specify a stack, default to html-tailwind.

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

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

Search Reference

Available Domains

Available Stacks

Example Workflow

User request: "Làm landing page cho dịch vụ chăm sóc da chuyên nghiệp"

Step 1: Analyze Requirements

• •Product type: Beauty/Spa service
• •Style keywords: elegant, professional, soft
• •Industry: Beauty/Wellness
• •Stack: html-tailwind (default)

Step 2: Generate Design System (REQUIRED)

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

Output: Complete design system with pattern, style, colors, typography, effects, and anti-patterns.

Step 3: Supplement with Detailed Searches (as needed)

# Get UX guidelines for animation and accessibility
python3 skills/ui-ux-pro-max/scripts/search.py "animation accessibility" --domain ux

# Get alternative typography options if needed
python3 skills/ui-ux-pro-max/scripts/search.py "elegant luxury serif" --domain typography

Step 4: Stack Guidelines

python3 skills/ui-ux-pro-max/scripts/search.py "layout responsive form" --stack html-tailwind

Then: Synthesize design system + detailed searches and implement the design.

Output Formats

The --design-system flag supports two output formats:

# ASCII box (default) - best for terminal display
python3 skills/ui-ux-pro-max/scripts/search.py "fintech crypto" --design-system

# Markdown - best for documentation
python3 skills/ui-ux-pro-max/scripts/search.py "fintech crypto" --design-system -f markdown

Tips for Better Results

1. •Be specific with keywords - "healthcare SaaS dashboard" > "app"
2. •Search multiple times - Different keywords reveal different insights
3. •Combine domains - Style + Typography + Color = Complete design system
4. •Always check UX - Search "animation", "z-index", "accessibility" for common issues
5. •Use stack flag - Get implementation-specific best practices
6. •Iterate - If first search doesn't match, try different keywords

Common Rules for Professional UI

These are frequently overlooked issues that make UI look unprofessional:

Icons & Visual Elements

Interaction & Cursor

Light/Dark Mode Contrast

Layout & Spacing

Pre-Delivery Checklist

Before delivering UI code, verify these items:

Visual Quality

• • No emojis used as icons (use SVG instead)
• • All icons from consistent icon set (Heroicons/Lucide)
• • Brand logos are correct (verified from Simple Icons)
• • Hover states don't cause layout shift
• • Use theme colors directly (bg-primary) not var() wrapper

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
• • Test both modes before delivery

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

Architecture Overview

NOT traditional RAG (vector embeddings) — Uses BM25 keyword search with CSV databases:

CSV Databases (7 domains) → BM25 Search Engine → JSON Results
├── products.csv (100 product types with reasoning rules)
├── styles.csv (67 UI styles)
├── colors.csv (96 color palettes)
├── typography.csv (56 font pairings)
├── landing-pages.csv (24 page patterns)
├── charts.csv (25 chart types)
└── ux-guidelines.csv (98 best practices)

Search Method: Python script with BM25 ranking + regex matching

Core Design Principles

Typography

• •NEVER: Inter, Roboto, Arial, system fonts
• •ALWAYS: Distinctive fonts (e.g., Cormorant Garamond, Montserrat, Crimson Pro, Public Sans, Space Grotesk)
• •Pair display + body fonts with purpose
• •Client-facing: 16px+ body text
• •Internal ops: 14px+ body text

Color & Theme

• •Commit to cohesive aesthetic (not random colors)
• •Dominant colors with sharp accents
• •Use CSS variables for consistency
• •Industry-appropriate palettes
• •Sufficient contrast (WCAG AA: 4.5:1 minimum)

Motion

• •High-impact moments: staggered reveals, scroll-triggered animations
• •CSS-only for HTML, Motion library for React
• •150-300ms transitions for hover states
• •Respect prefers-reduced-motion

Spatial Composition

• •Unexpected layouts, asymmetry, overlap, diagonal flow
• •Generous negative space OR controlled density (audience-dependent)
• •Break grids intentionally

Backgrounds & Visual Details

• •Gradient meshes, noise textures, layered transparencies
• •Contextual effects (not random decoration)
• •Depth via shadows, gradients, layering

Capabilities

Design System Generation

• •Design Tokens: Generate comprehensive design token systems (colors, typography, spacing, shadows, etc.)
• •Component Libraries: Create reusable UI components with multiple variants and states
• •Brand Systems: Develop complete brand identity systems with logos, color palettes, and visual guidelines
• •Accessibility: WCAG 2.1 AA compliant design patterns and accessibility audits
• •BM25 Search Integration: Industry-specific recommendations from 7 design domains

Framework Support

• •React: Design system components for React with TypeScript support
• •Vue.js: Vue 3 composition API compatible design system
• •Angular: Angular Material compatible design system extensions
• •CSS/Tailwind: Pure CSS and Tailwind CSS design system utilities
• •Figma: Design system files and component libraries for Figma

Advanced Features

• •Responsive Design: Mobile-first responsive design patterns
• •Dark/Light Themes: Complete theme system with automatic switching
• •Motion Design: Animation and transition libraries
• •Design Ops: Design system documentation, versioning, and distribution
• •Performance: Optimized components and bundle size optimization

Search Integration

The 7 Searchable Domains

See references/search-domains.md for complete domain documentation.

Search Command Patterns

Design System Generator (Phase 3 — Always run first):

python3 /path/to/search.py "{platformType} {audience} {outcome}" --design-system -p "{ProjectName}"

Example:

python3 search.py "vapi call center client-facing dashboard" --design-system -p "Acme Corp"

Domain-Specific Searches (Phase 3, 5 — For refinement):

python3 search.py "{keywords}" --domain {style|color|typography|landing|chart|ux}

Examples:

# Style alternatives
python3 search.py "glassmorphism dark mode" --domain style

# Color palette refinement
python3 search.py "fintech blue professional" --domain color

# Typography variations
python3 search.py "elegant luxury serif" --domain typography

# Chart recommendations
python3 search.py "real-time metrics gauge" --domain chart

# UX validation
python3 search.py "contrast wcag accessibility" --domain ux

Platform-Specific Patterns

Vapi (Call Centers)

Tone: Professional, reliable, real-time
Colors: Blues, teals, neutrals (trust, communication)
Emphasis: Live status, call volume trends, success rates
Avoid: Overly playful, slow animations, tiny text

n8n (Workflow Automation)

Tone: Technical, efficient, modular
Colors: Purples (brand), oranges (energy), grays
Emphasis: Flow diagrams, execution timelines, error tracking
Avoid: Cluttered layouts, too much text

Make (Automation Scenarios)

Tone: Clean, systematic, operational
Colors: Greens, blues, whites (productivity, growth)
Emphasis: Scenario summaries, operation counts, data flow
Avoid: Abstract visualizations (keep concrete)

Retell (Voice AI)

Tone: Conversational, human-centric, warm
Colors: Warm neutrals, accent colors (approachable)
Emphasis: Conversation quality, sentiment, transcripts
Avoid: Cold/clinical aesthetics

Usage Examples

Generate a Complete Design System

Create a modern design system for a SaaS platform with:
- Primary color: #6366f1 (indigo)
- Typography: Inter font family
- Component library: buttons, forms, navigation, data tables
- Responsive breakpoints: mobile (320px+), tablet (768px+), desktop (1024px+)
- Dark mode support
- WCAG AA accessibility

Create Component Variants

Generate button component variations:
- Primary, secondary, tertiary buttons
- Multiple sizes: small, medium, large
- Full states: default, hover, active, disabled, loading
- Icon support and text/icon combinations

Design System Audit

Audit existing design system for:
- Color contrast ratios
- Typography hierarchy consistency
- Component naming conventions
- Accessibility compliance
- Performance optimization opportunities

Script Files

The skill includes three Python scripts in the scripts/ directory:

search.py

BM25-powered search engine for design recommendations:

• •Searches 7 domains (product, style, color, typography, landing, chart, ux)
• •Returns JSON results with priority-based rankings
• •Supports design system generation with --design-system flag
• •Includes hierarchical persistence with Master + page-specific overrides

design_system.py

Design system generation engine:

• •Creates comprehensive design systems from search results
• •Handles style, color, typography recommendations
• •Integrates with industry-specific patterns
• •Outputs both ASCII and Markdown formats

core.py

Core utilities for data processing:

• •CSV parsing and data validation
• •Text processing and fuzzy matching
• •Cross-domain reasoning integration
• •Performance optimization utilities

Data Structure

Design Tokens Schema

{
  "colors": {
    "primary": "#6366f1",
    "secondary": "#8b5cf6",
    "success": "#10b981",
    "warning": "#f59e0b",
    "error": "#ef4444"
  },
  "typography": {
    "fontFamily": "Inter, system-ui, sans-serif",
    "scale": [12, 14, 16, 18, 20, 24, 30, 36, 48, 64]
  },
  "spacing": {
    "scale": [4, 8, 12, 16, 20, 24, 32, 40, 48, 64]
  }
}

Component Schema

{
  "name": "Button",
  "variants": ["primary", "secondary", "outline", "ghost"],
  "sizes": ["sm", "md", "lg", "xl"],
  "states": ["default", "hover", "active", "disabled", "loading"],
  "accessibility": {
    "aria-label": true,
    "keyboard-navigation": true,
    "screen-reader": true
  }
}

Integration Points

Development Workflows

• •Storybook: Component documentation and testing
• •Design Tokens: Style dictionary integration
• •CI/CD: Automated design system testing and deployment
• •Version Control: Semantic versioning for design system updates

Design Tools

• •Figma: Design system files and component libraries
• •Sketch: Design system templates and symbols
• •Adobe XD: Component libraries and design specs
• •Zeplin: Design delivery and handoff

Quality Assurance

Testing

• •Visual Regression: Automated visual testing
• •Accessibility Testing: Screen reader and keyboard navigation testing
• •Cross-browser Testing: Compatibility across browsers
• •Performance Testing: Component rendering and bundle size analysis

Standards Compliance

• •WCAG 2.1 AA: Accessibility compliance
• •Section 508: Government accessibility standards
• •ES6/TypeScript: Modern JavaScript standards
• •Responsive Design: Mobile-first design principles

Metrics & Analytics

Usage Metrics

• •Component usage tracking
• •Design token adoption rates
• •Performance impact measurements
• •User satisfaction scores

Design Ops Metrics

• •Design system ROI
• •Development velocity improvements
• •Consistency scores
• •Maintenance overhead

Documentation

Auto-generated Documentation

• •Component API documentation
• •Design token reference
• •Usage guidelines and best practices
• •Accessibility guide

Developer Resources

• •Getting started guides
• •Migration documentation
• •Troubleshooting guides
• •Contribution guidelines

Dependencies

Core Dependencies

• •Design token management system
• •Component framework (React/Vue/Angular)
• •Build tools and bundlers
• •Testing framework

Optional Dependencies

• •Storybook for component documentation
• •Style dictionary for design tokens
• •ESLint/Prettier for code quality
• •Chromatic for visual testing

Configuration

Environment Variables

DESIGN_SYSTEM_VERSION=1.0.0
THEME_DEFAULT=light
ACCESSIBILITY_LEVEL=AA
PERFORMANCE_TARGET=90

Build Configuration

{
  "output": {
    "components": "./dist/components",
    "tokens": "./dist/tokens",
    "docs": "./dist/docs"
  },
  "optimization": {
    "treeshaking": true,
    "compression": true,
    "bundleAnalysis": true
  }
}

Supported Frameworks

Frontend Frameworks

• •React 16.8+ (Hooks)
• •Vue 3 (Composition API)
• •Angular 12+
• •Svelte 3+
• •Next.js 12+
• •Nuxt 3+

CSS Frameworks

• •Tailwind CSS 3+
• •Bootstrap 5+
• •Material Design
• •Ant Design
• •Chakra UI

Build Tools

• •Vite
• •Webpack
• •Rollup
• •ESBuild
• •Parcel

Security Considerations

Content Security Policy

• •Design system security policies
• •Safe component practices
• •Data handling guidelines
• •Third-party dependency security

Privacy Compliance

• •GDPR compliance components
• •Cookie consent designs
• •Privacy-first design patterns
• •User data protection UI

Performance Optimization

Bundle Optimization

• •Tree shaking for unused components
• •Code splitting strategies
• •Lazy loading patterns
• •Asset optimization

Runtime Performance

• •Component rendering optimization
• •Memory usage patterns
• •Animation performance
• •Accessibility performance impact

Roadmap

Version 2.0 Features

• •AI-powered design token suggestions
• •Automatic accessibility improvements
• •Performance monitoring integration
• •Advanced theming capabilities

Future Enhancements

• •Voice interface design systems
• •AR/VR component libraries
• •Design system marketplace
• •Collaborative design tools