--- name: ui-ux-pro-max description: "UI/UX design intelligence. 50 styles, 21 palettes, 50 font pairings, 20 charts, 9 stacks (React, Next.js, Vue, Svelte, SwiftUI, React Native, Flutter, Tailwind, shadcn/ui). Actions: plan, build, create, design, implement, review, fix, improve, optimize, enhance, refactor, check UI/UX code. Projects: website, landing page, dashboard, admin panel, e-commerce, SaaS, portfolio, blog, mobile app, .html, .tsx, .vue, .svelte. Elements: button, modal, navbar, sidebar, card, table, form, chart. Styles: glassmorphism, claymorphism, minimalism, brutalism, neumorphism, bento grid, dark mode, responsive, skeuomorphism, flat design. Topics: color palette, accessibility, animation, layout, typography, font pairing, spacing, hover, shadow, gradient. Integrations: shadcn/ui MCP for component search and examples." --- # 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 | Priority | Category | Impact | Domain | |----------|----------|--------|--------| | 1 | Accessibility | CRITICAL | `ux` | | 2 | Touch & Interaction | CRITICAL | `ux` | | 3 | Performance | HIGH | `ux` | | 4 | Layout & Responsive | HIGH | `ux` | | 5 | Typography & Color | MEDIUM | `typography`, `color` | | 6 | Animation | MEDIUM | `ux` | | 7 | Style Selection | MEDIUM | `style`, `product` | | 8 | Charts & Data | LOW | `chart` | ## 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 ## Node.js Tool Access (Vercel-safe) This skill is available via Mastra tools that read CSV data from: `.agent/skills/ui-ux-pro-max/data/` ### Tools - `uiux.getProductRecommendations` — industry/product patterns - `uiux.getStyleRecommendations` — style direction recommendations - `uiux.getTypographyRecommendations` — font pairing recommendations - `uiux.getChartRecommendations` — chart type recommendations - `uiux.getUXGuidelines` — UX/accessibility guidelines ### Recommended Workflow When user requests UI/UX work (design, build, create, implement, review, fix, improve), follow this workflow: 1) Call `uiux.getProductRecommendations` to ground industry assumptions 2) Call `uiux.getStyleRecommendations` to propose style directions 3) Call `uiux.getTypographyRecommendations` for font pairing (if needed) 4) Call `uiux.getUXGuidelines` to check accessibility/layout issues 5) Call `uiux.getChartRecommendations` for dashboard chart choices ### 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) **Use UIUX Mastra tools** to get comprehensive recommendations: ```javascript // Industry context const productRecs = await uiux.getProductRecommendations({ productType: "beauty spa", keywords: ["wellness", "service"], limit: 3 }); // Style directions const styleRecs = await uiux.getStyleRecommendations({ productType: "beauty spa", keywords: ["wellness", "service", "professional"], limit: 3 }); // Typography const typographyRecs = await uiux.getTypographyRecommendations({ moodKeywords: ["elegant", "professional"], category: "beauty", limit: 3 }); ``` This provides: 1. Industry-specific product patterns and style mappings 2. Style recommendations with colors and effects 3. Font pairings and CSS imports 4. Accessibility and performance considerations ### Step 2b: Document Design System Store the generated design system in project documentation: ```markdown # Project Design System ## Industry Context [productRecs results...] ## Style Directions [styleRecs results...] ## Typography [typographyRecs results...] ## UX Guidelines [uxGuidelines results...] ``` This creates a consistent reference that can be: - Saved to project docs or wiki - Referenced during implementation reviews - Used for new team member onboarding - Updated as the design evolves ### Step 3: Supplement with Detailed Recommendations After getting the initial design system, use specific UIUX tools for additional details: ```javascript // More style options const moreStyles = await uiux.getStyleRecommendations({ productType: "dashboard", keywords: ["glassmorphism", "dark"], limit: 5 }); // Chart recommendations const chartRecs = await uiux.getChartRecommendations({ dataType: "real-time metrics", keywords: ["dashboard"], accessibility: true, limit: 3 }); // UX best practices const uxGuide = await uiux.getUXGuidelines({ category: "animation", issue: "accessibility", limit: 5 }); // Alternative fonts const altTypography = await uiux.getTypographyRecommendations({ moodKeywords: ["elegant", "luxury"], category: "serif", limit: 3 }); ``` ### Step 4: Implementation Context Use the recommendations based on your implementation stack: - **HTML/Tailwind**: Follow CSS utility guidelines from recommendations - **React/Next.js**: Apply component patterns and performance considerations - **Vue**: Use composition-friendly patterns from style guides - **Mobile Apps**: Adapt typography and spacing for mobile contexts --- ## Search Reference ### Available Domains | Domain | Use For | Example Keywords | |--------|---------|------------------| | `product` | Product type recommendations | SaaS, e-commerce, portfolio, healthcare, beauty, service | | `style` | UI styles, colors, effects | glassmorphism, minimalism, dark mode, brutalism | | `typography` | Font pairings, Google Fonts | elegant, playful, professional, modern | | `color` | Color palettes by product type | saas, ecommerce, healthcare, beauty, fintech, service | | `landing` | Page structure, CTA strategies | hero, hero-centric, testimonial, pricing, social-proof | | `chart` | Chart types, library recommendations | trend, comparison, timeline, funnel, pie | | `ux` | Best practices, anti-patterns | animation, accessibility, z-index, loading | | `react` | React/Next.js performance | waterfall, bundle, suspense, memo, rerender, cache | | `web` | Web interface guidelines | aria, focus, keyboard, semantic, virtualize | | `prompt` | AI prompts, CSS keywords | (style name) | ### Available Stacks | Stack | Focus | |-------|-------| | `html-tailwind` | Tailwind utilities, responsive, a11y (DEFAULT) | | `react` | State, hooks, performance, patterns | | `nextjs` | SSR, routing, images, API routes | | `vue` | Composition API, Pinia, Vue Router | | `svelte` | Runes, stores, SvelteKit | | `swiftui` | Views, State, Navigation, Animation | | `react-native` | Components, Navigation, Lists | | `flutter` | Widgets, State, Layout, Theming | | `shadcn` | shadcn/ui components, theming, forms, patterns | | `jetpack-compose` | Composables, Modifiers, State Hoisting, Recomposition | --- ## 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) ```bash 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) ```bash # 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 ```bash 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: ```bash # 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 | Rule | Do | Don't | |------|----|----- | | **No emoji icons** | Use SVG icons (Heroicons, Lucide, Simple Icons) | Use emojis like 🎨 🚀 ⚙️ as UI icons | | **Stable hover states** | Use color/opacity transitions on hover | Use scale transforms that shift layout | | **Correct brand logos** | Research official SVG from Simple Icons | Guess or use incorrect logo paths | | **Consistent icon sizing** | Use fixed viewBox (24x24) with w-6 h-6 | Mix different icon sizes randomly | ### Interaction & Cursor | Rule | Do | Don't | |------|----|----- | | **Cursor pointer** | Add `cursor-pointer` to all clickable/hoverable cards | Leave default cursor on interactive elements | | **Hover feedback** | Provide visual feedback (color, shadow, border) | No indication element is interactive | | **Smooth transitions** | Use `transition-colors duration-200` | Instant state changes or too slow (>500ms) | ### Light/Dark Mode Contrast | Rule | Do | Don't | |------|----|----- | | **Glass card light mode** | Use `bg-white/80` or higher opacity | Use `bg-white/10` (too transparent) | | **Text contrast light** | Use `#0F172A` (slate-900) for text | Use `#94A3B8` (slate-400) for body text | | **Muted text light** | Use `#475569` (slate-600) minimum | Use gray-400 or lighter | | **Border visibility** | Use `border-gray-200` in light mode | Use `border-white/10` (invisible) | ### Layout & Spacing | Rule | Do | Don't | |------|----|----- | | **Floating navbar** | Add `top-4 left-4 right-4` spacing | Stick navbar to `top-0 left-0 right-0` | | **Content padding** | Account for fixed navbar height | Let content hide behind fixed elements | | **Consistent max-width** | Use same `max-w-6xl` or `max-w-7xl` | Mix different container widths | --- ## 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. | Domain | What It Contains | When to Use | |--------|------------------|-------------| | **product** | 100 product categories with industry rules | Initial design system generation | | **style** | 67 UI styles | Style bundle generation, refinement | | **color** | 96 industry palettes | Color mood selection | | **typography** | 56 font pairings | Typography selection | | **landing** | 24 page patterns | Page structure guidance | | **chart** | 25 chart types | Dashboard data visualization | | **ux** | 98 UX guidelines | Accessibility, best practices | ### Search Command Patterns **Design System Generator (Phase 3 — Always run first):** ```bash python3 /path/to/search.py "{platformType} {audience} {outcome}" --design-system -p "{ProjectName}" ``` Example: ```bash python3 search.py "vapi call center client-facing dashboard" --design-system -p "Acme Corp" ``` **Domain-Specific Searches (Phase 3, 5 — For refinement):** ```bash python3 search.py "{keywords}" --domain {style|color|typography|landing|chart|ux} ``` Examples: ```bash # 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 ```json { "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 ```json { "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 ```json { "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