| name | ui-ux-pro-max |
| description | Search a bundled UI/UX database for product-specific styles, palettes, typography, accessibility, motion, charts, and stack guidance. Use only when explicitly requested or when a concrete design-system lookup is needed for web or mobile UI. |
UI/UX Pro Max - Design Intelligence
Searchable database of UI/UX design rules with priority-based recommendations: 84 styles, 192 color palettes, 74 font pairings, 192 product types with reasoning rules, 98 UX guidelines, 104 icon entries, 16 GSAP motion presets, and 25 chart types across 22 technology stacks.
When to Apply
Use this Skill when the task involves UI structure, visual design decisions, interaction patterns, or user experience quality control: designing new pages, creating/refactoring UI components, choosing color/typography/spacing/layout systems, reviewing UI for UX/accessibility/consistency, implementing navigation/animation/responsive behavior, or improving perceived quality and usability.
Skip it for pure backend logic, API/database design, non-visual performance work, infrastructure/DevOps, or non-visual scripts — unless the task changes how something looks, feels, moves, or is interacted with.
Rule Categories by Priority
Follow priority 1→10 to decide which category to focus on first; use --domain <Domain> to query full details. The full rule text for every category lives in references/quick-reference.md — read it on demand rather than loading it every time.
| Priority | Category | Impact | Domain | Key Checks (Must Have) | Anti-Patterns (Avoid) |
|---|
| 1 | Accessibility | CRITICAL | ux | Contrast 4.5:1, Alt text, Keyboard nav, Aria-labels | Removing focus rings, Icon-only buttons without labels |
| 2 | Touch & Interaction | CRITICAL | ux | Min size 44×44px, 8px+ spacing, Loading feedback | Reliance on hover only, Instant state changes (0ms) |
| 3 | Performance | HIGH | ux | WebP/AVIF, Lazy loading, Reserve space (CLS < 0.1) | Layout thrashing, Cumulative Layout Shift |
| 4 | Style Selection | HIGH | style, product | Match product type, Consistency, SVG icons (no emoji) | Mixing flat & skeuomorphic randomly, Emoji as icons |
| 5 | Layout & Responsive | HIGH | ux | Mobile-first breakpoints, Viewport meta, No horizontal scroll | Horizontal scroll, Fixed px container widths, Disable zoom |
| 6 | Typography & Color | MEDIUM | typography, color | Base 16px, Line-height 1.5, Semantic color tokens | Text < 12px body, Gray-on-gray, Raw hex in components |
| 7 | Animation | MEDIUM | ux, gsap | Duration 150–300ms, Motion conveys meaning, Spatial continuity | Decorative-only animation, Animating width/height, No reduced-motion |
| 8 | Forms & Feedback | MEDIUM | ux | Visible labels, Error near field, Helper text, Progressive disclosure | Placeholder-only label, Errors only at top, Overwhelm upfront |
| 9 | Navigation Patterns | HIGH | ux | Predictable back, Bottom nav ≤5, Deep linking | Overloaded nav, Broken back behavior, No deep links |
| 10 | Charts & Data | LOW | chart | Legends, Tooltips, Accessible colors | Relying on color alone to convey meaning |
For the full rule list per category (all ~98 UX guidelines with rationale), read references/quick-reference.md. For app-specific polish rules (icons, touch feedback, dark mode contrast, safe areas) and the canonical pre-delivery checklist, read references/pro-rules.md.
Running the search tool
The search script lives inside this skill's own directory, not the project directory. Resolve UI_UX_SKILL_DIR to the directory containing this SKILL.md, then invoke it by full path:
python3 "$UI_UX_SKILL_DIR/scripts/search.py" "<query>" --domain <domain>
If python3 is not found, try python, then py -3. Requires Python 3.x and no external dependencies.
Workflow
Step 1: Analyze User Requirements
Extract from the user request:
- Product type: SaaS, e-commerce, portfolio, dashboard, entertainment, tool, productivity, or hybrid
- Target audience & context: age group, usage context (commute, leisure, work)
- Style keywords: playful, vibrant, minimal, dark mode, content-first, immersive, etc.
- Stack: detect from the project — check
package.json deps (react/next/vue/svelte/nuxt/@angular), pubspec.yaml (Flutter), *.xcodeproj/Package.swift (SwiftUI), composer.json (Laravel), or React Native markers (app.json + react-native dep). If nothing is detectable, ask the user or default to html-tailwind. Never assume a stack — a hardcoded default silently misroutes every recommendation.
Step 2: Generate Design System (REQUIRED for new pages/projects)
Always start with --design-system to get comprehensive recommendations with reasoning:
python3 "$UI_UX_SKILL_DIR/scripts/search.py" "<product_type> <industry> <keywords>" --design-system [-p "Project Name"]
This searches product/style/color/landing/typography domains in parallel, applies reasoning rules from ui-reasoning.csv, and returns pattern, style, colors, typography, effects, and anti-patterns to avoid.
Example:
python3 "$UI_UX_SKILL_DIR/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 retrieval across sessions, add --persist and always pass --output-dir pointed at the project root — without it, files are written relative to whatever directory the tool happens to run from:
python3 "$UI_UX_SKILL_DIR/scripts/search.py" "<query>" --design-system --persist -p "Project Name" --output-dir "<project-root>"
This creates:
design-system/<project-slug>/MASTER.md — Global Source of Truthdesign-system/<project-slug>/pages/ — Folder for page-specific overrides
With a page-specific override, add --page "dashboard" to also create design-system/<project-slug>/pages/dashboard.md.
If design-system/<project-slug>/MASTER.md already exists, --persist skips writing and leaves it untouched unless you also pass --force — check whether it exists first (and read it) before regenerating, so you don't silently discard prior decisions the user or a teammate made.
Retrieval when building a specific page:
- Read
design-system/<project-slug>/MASTER.md
- Check if
design-system/<project-slug>/pages/<page-name>.md exists — if so, its rules override Master
- Otherwise use Master rules exclusively
Step 2c: Design Dials (optional)
Three optional 1-10 sliders that tune --design-system output without changing your query. Add any combination of them to the same command:
python3 "$UI_UX_SKILL_DIR/scripts/search.py" "<query>" --design-system --variance <1-10> --motion <1-10> --density <1-10>
| Dial | Low (1-3) | Mid (4-7) | High (8-10) |
|---|
--variance | Centered / minimal (biases toward Minimalism-style categories) | Balanced / modern | Bold / asymmetric (biases toward Brutalism, Bento Grids) |
--motion | Subtle micro-interactions | Standard scroll/stagger motion | Complex choreography (pin, Flip, SplitText) |
--density | Spacious (24-96px spacing scale) | Standard (16-64px, current default) | Dense/dashboard (8-32px spacing scale) |
--motion attaches a ready-to-use GSAP snippet (with framework notes, Do/Don't, and performance notes) pulled from --domain gsap, matched to the resolved tier (Subtle/Standard/Complex).--density overrides the --space-* CSS variable table in the ASCII/markdown/MASTER.md output — use it for dashboards (high) vs. marketing pages (low) without hand-editing tokens.- Leaving a dial unset keeps that part of the output exactly as it was before (no behavior change).
Example:
python3 "$UI_UX_SKILL_DIR/scripts/search.py" "internal analytics dashboard" --design-system --variance 8 --motion 7 --density 8 -p "Ops Console"
Step 3: Supplement with Detailed Searches (as needed)
python3 "$UI_UX_SKILL_DIR/scripts/search.py" "<keyword>" --domain <domain> [-n <max_results>]
| Need | Domain | Example |
|---|
| Product type patterns | product | --domain product "entertainment social" |
| More style options | style | --domain style "glassmorphism dark" |
| Color palettes | color | --domain color "entertainment vibrant" |
| Font pairings | typography | --domain typography "playful modern" |
| Individual Google Fonts | google-fonts | --domain google-fonts "sans serif popular variable" |
| Chart recommendations | chart | --domain chart "real-time dashboard" |
| UX best practices | ux | --domain ux "animation accessibility" |
| Landing page structure | landing | --domain landing "hero social-proof" |
| Icon recommendations | icons | --domain icons "navigation outline" |
| GSAP animation presets | gsap | --domain gsap "scroll reveal stagger" |
| React/Next.js performance | react | --domain react "rerender memo list" |
| App/native interface guidelines | web | --domain web "accessibilityLabel touch safe-areas" |
Domain is auto-detected from the query if --domain is omitted — but auto-detection can misroute overlapping terms (e.g. "font" matches both typography and google-fonts). If results look off-topic, pass --domain explicitly.
Step 4: Stack Guidelines
python3 "$UI_UX_SKILL_DIR/scripts/search.py" "<keyword>" --stack <stack>
Available stacks: react, nextjs, vue, svelte, astro, nuxtjs, nuxt-ui, angular, laravel, swiftui, react-native, flutter, jetpack-compose, html-tailwind, shadcn, threejs, javafx, wpf, winui, avalonia, uno, uwp. Use the stack detected in Step 1.
If a search returns 0 results
Do not fabricate output. Instead:
- Retry once with broader or differently-worded keywords (try product + style separately rather than combined).
- If still empty, fall back to the priority table above and say explicitly to the user that this recommendation came from the built-in defaults, not a database match (e.g. "no palette match for X, using general SaaS defaults").
- Never present a 0-result search as if it returned data.
Example Workflow
User request: "Make an AI search homepage." (stack detected as Next.js from package.json)
python3 "$UI_UX_SKILL_DIR/scripts/search.py" "AI search tool modern minimal" --design-system -p "AI Search"
python3 "$UI_UX_SKILL_DIR/scripts/search.py" "search loading animation" --domain ux
python3 "$UI_UX_SKILL_DIR/scripts/search.py" "suspense streaming bundle" --stack nextjs
Then synthesize the design system + detailed searches and implement.
Output Formats
--design-system supports -f ascii (default, terminal display), -f markdown (documentation), and --json (machine-readable, includes the raw design system dict plus persistence status).
Tips for Better Results
- Use multi-dimensional keywords — combine product + industry + tone + density:
"entertainment social vibrant content-dense", not just "app"
- Try different phrasings for the same need:
"playful neon" → "vibrant dark" → "content-first minimal"
- Use
--design-system first for full recommendations, then --domain to deep-dive any dimension you're unsure about
- Pass the detected stack explicitly for implementation-specific guidance
| Problem | What to Do |
|---|
| Can't decide on style/color | Re-run --design-system with different keywords |
| Dark mode contrast issues | references/quick-reference.md §6: color-dark-mode + color-accessible-pairs |
| Animations feel unnatural | references/quick-reference.md §7: spring-physics + easing + exit-faster-than-enter |
| Form UX is poor | references/quick-reference.md §8: inline-validation + error-clarity + focus-management |
| Navigation feels confusing | references/quick-reference.md §9: nav-hierarchy + bottom-nav-limit + back-behavior |
| Layout breaks on small screens | references/quick-reference.md §5: mobile-first + breakpoint-consistency |
| Performance / jank | references/quick-reference.md §3: virtualize-lists + main-thread-budget + debounce-throttle |
Before Delivering App UI
Read references/pro-rules.md and run through its canonical Pre-Delivery Checklist. It covers icon/visual-element discipline, interaction feedback, light/dark contrast, safe-area layout, and accessibility — scoped to native/mobile app UI (iOS/Android/React Native/Flutter).
