# ipai-ui-ux-pro-max

> Design intelligence for UI/UX generation and critique; use for layouts, typography, color palettes, tokens, and UX best practices. 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.

**Version:** 1.0.0
**Tags:** design, ui, ux, tokens, accessibility, typography, color

---

_This file is generated by `scripts/skills/build_skills.py`. Do not edit by hand._

## references/01-styles.md

# Styles Catalog

## Purpose

Choose a visual style that matches product positioning, audience expectations, and platform constraints.

## 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` |

## Styles (Selection Guide)

- **Minimal / Editorial** — best for premium, clarity-first products
- **Glassmorphism** — best for modern, playful UIs; avoid for data-dense screens
- **Neumorphism** — use sparingly; accessibility risk (low contrast)
- **Brutalism** — niche; brand-forward; high risk for mainstream audiences
- **Corporate SaaS** — safe default; fastest to ship; widest audience
- **Claymorphism** — soft 3D aesthetic; suitable for playful products
- **Bento Grid** — grid-based cards; good for feature showcases and dashboards
- **Dark Mode** — reduce eye strain; test contrast carefully in both modes
- **Skeuomorphism** — realistic textures; rarely appropriate in modern web
- **Flat Design** — simple and clean; pairs well with strong typography

## Selection Heuristic

Pick based on:
1. **Trust requirement** (high → corporate/editorial)
2. **Information density** (high → minimal/corporate)
3. **Device primary** (mobile-first → minimal)
4. **Brand tone** (playful → glass/gradients; serious → editorial)

## Style-Specific Rules

| Rule | Do | Don't |
|------|----|----- |
| `style-match` | Match style to product type and audience | Pick trendy style without justification |
| `consistency` | Use the same style across all pages | Mix multiple visual languages |
| `no-emoji-icons` | Use SVG icons (Heroicons, Lucide, Simple Icons) | Use emojis like 🎨 🚀 as UI icons |
| `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 |

## references/02-color-palettes.md

# Color Palettes

## Token Roles (Semantic-First)

Design systems should use semantic color roles, not raw hex values:

| Role | Purpose | Example |
|------|---------|---------|
| `bg` | Page background | `#FFFFFF` / `#0F172A` |
| `surface` | Card/panel background | `#F8FAFC` / `#1E293B` |
| `surface-2` | Nested surface | `#F1F5F9` / `#334155` |
| `text` | Primary text | `#0F172A` (slate-900) |
| `text-muted` | Secondary text | `#475569` (slate-600) minimum |
| `primary` | Brand action color | Varies by brand |
| `primary-hover` | Hover state | 10-15% darker |
| `secondary` | Secondary actions | Neutral or complementary |
| `success` | Positive states | Green family |
| `warning` | Caution states | Amber/yellow family |
| `danger` | Error/destructive | Red family |
| `border` | Default borders | `border-gray-200` light / `border-gray-700` dark |
| `divider` | Section separators | Lighter than border |

## Contrast Rules

- Body text must meet WCAG AA (4.5:1 minimum)
- Use semantic colors only for semantic meaning (don't use `danger` for decoration)
- Avoid saturated colors for large background areas
- Test both light and dark modes before delivery

## Light/Dark Mode Specifics

| Context | Do | Don't |
|---------|----|----- |
| Glass card (light mode) | `bg-white/80` or higher opacity | `bg-white/10` (too transparent) |
| Body text (light mode) | `#0F172A` (slate-900) | `#94A3B8` (slate-400) |
| Muted text (light mode) | `#475569` (slate-600) minimum | gray-400 or lighter |
| Borders (light mode) | `border-gray-200` | `border-white/10` (invisible) |

## references/03-typography.md

# Typography System

## Type Scale (Recommended)

| Level | Size (px) | Line Height | Use |
|-------|-----------|-------------|-----|
| H1 | 32–40 | 1.1 | Page titles |
| H2 | 24–32 | 1.2 | Section headers |
| H3 | 20–24 | 1.25 | Subsection headers |
| Body | 14–16 | 1.5 | Paragraph text |
| Caption | 12–13 | 1.4 | Labels, metadata |

## Font Pairing Rules

- One display + one text family maximum
- Prefer variable fonts when available (smaller payload, more flexibility)
- Avoid ultra-light weights for body text (readability suffers)
- Match heading/body font personalities (don't mix playful heading with corporate body)

## Line Length & Readability

| Rule | Value | Reason |
|------|-------|--------|
| `line-height` | 1.5–1.75 for body | Comfortable reading |
| `line-length` | 65–75 characters | Optimal scan width |
| `readable-font-size` | 16px minimum on mobile | Prevents zoom on iOS |
| `font-pairing` | Match personality | Visual coherence |

## Tips for Better Results

Search typography options using:
```bash
python3 skills/ui-ux-pro-max/scripts/search.py "elegant luxury serif" --domain typography
```

## references/04-layout-spacing.md

# Layout & Spacing

## Grid System

| Breakpoint | Columns | Max Content Width |
|------------|---------|-------------------|
| Desktop (1024px+) | 12-col | 1140–1280px |
| Tablet (768px) | 8-col | Fluid |
| Mobile (< 768px) | 4-col | Fluid |

## Spacing Scale (Token Suggestions)

Use a consistent spacing scale: `4, 8, 12, 16, 24, 32, 48, 64`

All spacing should be multiples of 4px for pixel-perfect alignment.

## Responsive Rules

- Never rely on hover-only interactions (touch devices have no hover)
- Collapse multi-column filters into drawers on mobile
- Test at 375px, 768px, 1024px, 1440px
- Ensure no horizontal scroll on any breakpoint

## Layout-Specific Rules

| Rule | Do | Don't |
|------|----|----- |
| `viewport-meta` | `width=device-width, initial-scale=1` | Omit viewport meta tag |
| `horizontal-scroll` | Ensure content fits viewport width | Allow overflow without scroll affordance |
| `z-index-management` | Define scale (10, 20, 30, 50) | Use arbitrary z-index values |
| `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 |

## references/05-components-patterns.md

# Components & Patterns

## Core Components

Every application needs these baseline components:

- **Navigation** — side nav or top nav + breadcrumbs
- **Cards** — content containers with consistent padding and borders
- **Tables** — data display with sorting, filtering, pagination
- **Forms** — input groups with labels, validation, error states
- **Modals/Drawers** — overlay content for secondary actions
- **Toasts** — non-blocking status notifications
- **Empty States** — meaningful content when no data exists
- **Loading States** — skeleton screens or spinners during async operations

## Interaction Patterns

| Pattern | When to Use |
|---------|-------------|
| Progressive disclosure | Details panels, expandable rows, accordion sections |
| Primary action per screen | One clear CTA; secondary actions visually subordinate |
| Default-safe states | No blank screens; always show helpful content or guidance |
| Optimistic updates | Update UI immediately, reconcile on server response |

## Interaction Rules

| Rule | Do | Don't |
|------|----|----- |
| `cursor-pointer` | Add to all clickable/hoverable elements | 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 changes or too slow (>500ms) |
| `stable-hover-states` | Use color/opacity transitions | Use scale transforms that shift layout |
| `loading-buttons` | Disable button during async operations | Allow double-clicks |
| `error-feedback` | Clear error messages near the problem field | Vague errors at page top |

## Pre-Delivery Component Checklist

- [ ] All clickable elements have `cursor-pointer`
- [ ] Hover states provide clear visual feedback
- [ ] Transitions are smooth (150-300ms)
- [ ] Focus states visible for keyboard navigation
- [ ] Use theme colors directly (bg-primary) not var() wrapper

## references/06-charts-dataviz.md

# Charts & Data Visualization

## Chart Selection Guide

| Data Type | Recommended Chart | Avoid |
|-----------|-------------------|-------|
| Trend over time | Line / Area | Pie chart |
| Category comparison | Bar (horizontal or vertical) | Pie for >5 categories |
| Part-to-whole | Stacked bar, treemap | Pie for many slices |
| Distribution | Histogram / Box plot | Bar chart |
| Correlation | Scatter plot | Line chart |
| Flow / Process | Sankey / Funnel | Bar chart |
| Geospatial | Choropleth / Bubble map | Table |

## Dashboard Layout Rules

1. **KPI row first** — show key metrics at top
2. **Filters left or top** — keep filter count manageable (< 5 visible)
3. **Definitions and tooltips** — provide context for derived metrics
4. **Consistent time ranges** — all charts on a dashboard should share the same time filter
5. **Data table alternative** — provide table view for accessibility

## Color in Charts

- Use accessible color palettes (distinguishable by colorblind users)
- Limit to 5-7 colors per chart; group remaining as "Other"
- Use sequential palettes for ordered data; categorical for unordered
- Avoid red/green as the only differentiator

## Chart-Specific Rules

| Rule | Do | Don't |
|------|----|----- |
| `chart-type` | Match chart type to data relationship | Use pie for everything |
| `color-guidance` | Use accessible, distinguishable palettes | Rely on color alone |
| `data-table` | Provide table alternative | Only show visual chart |
| `axis-labels` | Label axes clearly with units | Omit axis context |

## references/07-ux-guidelines.md

# UX Guidelines (Best Practices)

## P0 — Must Have (CRITICAL)

- **Clear hierarchy** — one primary action per screen; visual weight guides the eye
- **Immediate feedback** — every user action gets a visible response (loading, success, error)
- **Actionable errors** — error messages explain what went wrong AND how to fix it, placed near the field

## P1 — Should Have (HIGH)

- **Consistent spacing and alignment** — use the spacing scale; never eyeball padding
- **Predictable navigation** — users should always know where they are and how to go back
- **Content-first empty states** — guide users to their first action; don't show blank pages
- **Touch target size** — minimum 44x44px for all interactive elements

## P2 — Nice to Have (MEDIUM)

- **Animation timing** — 150-300ms for micro-interactions; never > 500ms
- **Transform performance** — animate `transform` and `opacity`, not `width` or `height`
- **Skeleton loading** — show content shape during async operations; avoid blank flash
- **Reduced motion** — respect `prefers-reduced-motion` media query

## Anti-Patterns (Never Do)

| Anti-Pattern | Problem | Fix |
|---|---|---|
| Mystery-meat navigation | Users can't identify links or actions | Use clear labels, not just icons |
| Placeholder-only labels | Labels disappear on focus; users forget context | Always use persistent `<label>` elements |
| Non-dismissable modals | Users feel trapped | Always provide close/escape mechanism |
| Infinite scroll without position | Users can't bookmark or return to position | Add pagination or "back to top" |
| Auto-playing media | Disrupts user focus; accessibility violation | Let user opt-in to play |
| Color-only indicators | Colorblind users miss the signal | Add text, icon, or pattern |

## Tips for Better Results

Search UX guidance using:
```bash
python3 skills/ui-ux-pro-max/scripts/search.py "animation accessibility z-index" --domain ux
```

## references/08-accessibility.md

# Accessibility Checklist

## Contrast (WCAG AA Minimum)

| Element | Minimum Ratio | Standard |
|---------|--------------|----------|
| Normal text (< 18px) | 4.5:1 | WCAG AA |
| Large text (>= 18px bold or 24px) | 3:1 | WCAG AA |
| UI components and graphics | 3:1 | WCAG 2.1 AA |

## Keyboard Navigation

- **Focus visible** — all interactive elements must show a focus ring
- **Tab order logical** — follows visual reading order (top-left to bottom-right)
- **All controls reachable** — every interactive element accessible without mouse
- **Escape closes modals** — standard dismissal behavior
- **Skip to main content** — link for keyboard users to bypass navigation

## Forms

- **Labels exist** — every input has an associated `<label>` (not placeholder-only)
- **Error messaging linked** — use `aria-describedby` to connect error text to field
- **Required fields indicated** — mark required fields visually and with `aria-required`
- **Group related fields** — use `<fieldset>` and `<legend>` for related inputs

## Images & Media

- **Alt text** — descriptive alt for meaningful images; empty `alt=""` for decorative
- **Video captions** — provide captions or transcripts
- **`prefers-reduced-motion`** — disable/reduce animations for users who request it

## ARIA Usage

| Rule | Do | Don't |
|------|----|----- |
| `aria-labels` | Add `aria-label` to icon-only buttons | Rely on visual icon alone |
| `aria-live` | Use for dynamic content updates (toasts, counters) | Omit for auto-updating regions |
| Semantic HTML | Use `<button>`, `<nav>`, `<main>`, `<header>` | Use `<div>` for everything |
| Roles | Only add roles when no semantic element exists | Override native element semantics |

## Pre-Delivery Accessibility Checklist

- [ ] All images have alt text (descriptive or empty for decorative)
- [ ] Form inputs have `<label>` elements with `for` attribute
- [ ] Color is not the only indicator for any state
- [ ] Focus rings visible on all interactive elements
- [ ] Tab order matches visual reading order
- [ ] `prefers-reduced-motion` respected
- [ ] Minimum 4.5:1 contrast ratio for body text
- [ ] Skip-to-content link present