ui-ux-pro-max

ui-ux-pro-max

Comprehensive design intelligence for web, mobile, and desktop applications. Contains a searchable database with 84 styles, 192 color palettes, 74 font pairings, 192 product types, 98 UX guidelines, 104 icon entries, 16 GSAP motion presets, and 25 chart types across 22 technology stacks. Priority-based recommendations with reasoning.

Prerequisites

The bundled scripts require Python 3 (standard library only — no third-party packages, no network access). Check if it is available:

python3 --version || python --version

If Python is not installed, skip the CLI searches and rely on the Quick Reference sections below.

---

How to Use This Skill

Use this skill when the task involves UI structure, visual design decisions, interaction patterns, or user experience quality control:

Scenario	Trigger Examples	Start From
New project / page	"Build a landing page", "Create a dashboard"	Step 1 → Step 2 (design system)
New component	"Create a pricing card", "Add a modal"	Step 3 (domain search: style, ux)
Choose style / color / font	"What style fits a fintech app?"	Step 2 (design system)
Review existing UI	"Review this page for UX issues"	Quick Reference checklist below
Fix a UI bug	"Button hover is broken", "Layout shifts on load"	Quick Reference → relevant section
Improve / optimize	"Make this faster", "Improve mobile experience"	Step 3 (domain search: ux, react)
Implement dark mode	"Add dark mode support"	Step 3 (domain: style "dark mode")
Add charts / data viz	"Add an analytics dashboard chart"	Step 3 (domain: chart)
Stack best practices	"React performance tips", "Astro navigation"	Step 4 (stack search)

Decision rule: if the task changes how something looks, feels, moves, or is interacted with, use this skill.

Step 1: Analyze User Requirements

Extract key information from the request:

• Product type: Entertainment (social, video, music, gaming), Tool (scanner, editor, converter), Productivity (task manager, notes, calendar), or hybrid
• Target audience: C-end consumer users; consider age group, usage context (commute, leisure, work)
• Style keywords: playful, vibrant, minimal, dark mode, content-first, immersive, brutalist, editorial, etc.
• Stack: whatever the project actually builds with — infer from package.json, existing files, or explicit request. Then load its rules with --stack <name>. Do not assume React.
• Platform: web or native app. Several sections below are scoped to App UI (iOS/Android/React Native/Flutter) and do not apply to desktop-web work — safe areas, haptics, bottom nav and Dynamic Type are mobile-only concerns.

Step 2: Generate Design System (REQUIRED)

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

python3 .jcode/skills/ui-ux-pro-max/scripts/search.py "<product_type> <industry> <keywords>" --design-system [-p "Project Name"]

This command:

1. Searches 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 .jcode/skills/ui-ux-pro-max/scripts/search.py "editorial brutalist dark" --design-system -p "My Project"

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

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

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

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 .jcode/skills/ui-ux-pro-max/scripts/search.py "<query>" --design-system --persist -p "Project Name" --output-dir "." --page "dashboard"

Step 2c: Design Dials (optional)

Three optional 1-10 sliders that tune --design-system output without changing your query:

python3 .jcode/skills/ui-ux-pro-max/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 .jcode/skills/ui-ux-pro-max/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)

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

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

When to use detailed searches:

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"
Chart recommendations	chart	--domain chart "real-time dashboard"
UX best practices	ux	--domain ux "animation accessibility"
Landing structure	landing	--domain landing "hero social-proof"
React/Next.js perf	react	--domain react "rerender memo list"
App interface a11y	web	--domain web "accessibilityLabel touch safe-areas"
Icon suggestions	icons	--domain icons "navigation arrows"
Individual Google Fonts	google-fonts	--domain google-fonts "variable sans serif"
GSAP animation snippets	gsap	--domain gsap "scroll reveal stagger"

Step 4: Stack Guidelines

Get implementation-specific best practices for the project's stack:

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

Available stacks: react, nextjs, vue, svelte, astro, swiftui, react-native, flutter, nuxtjs, nuxt-ui, html-tailwind, shadcn, jetpack-compose, threejs, angular, laravel, javafx, wpf, winui, avalonia, uno, uwp

---

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
gsap	GSAP animation skeletons by intensity tier	scroll reveal, stagger, magnetic cursor, page transition
react	React/Next.js performance	waterfall, bundle, suspense, memo, rerender, cache
web	App interface guidelines (iOS/Android/React Native)	accessibilityLabel, touch targets, safe areas, Dynamic Type
icons	Icon recommendations with import code	arrow, navigation, lucide, phosphor
google-fonts	Individual Google Fonts lookup	sans serif, monospace, japanese, variable font, popular

---

Example Workflow

User request: "Make an AI search homepage."

Step 1: Analyze Requirements

• Product type: Tool (AI search engine)
• Target audience: C-end users looking for fast, intelligent search
• Style keywords: modern, minimal, content-first, dark mode
• Stack: Astro (inferred from project)

Step 2: Generate Design System (REQUIRED)

python3 .jcode/skills/ui-ux-pro-max/scripts/search.py "AI search tool modern minimal" --design-system -p "AI Search"

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

Step 3: Supplement with Detailed Searches (as needed)

# Get style options for a modern tool product
python3 .jcode/skills/ui-ux-pro-max/scripts/search.py "minimalism dark mode" --domain style

# Get UX best practices for search interaction and loading
python3 .jcode/skills/ui-ux-pro-max/scripts/search.py "search loading animation" --domain ux

Step 4: Stack Guidelines

python3 .jcode/skills/ui-ux-pro-max/scripts/search.py "list performance navigation" --stack astro

Then: Synthesize design system + detailed searches and implement the design. Always cross-reference with the project's DESIGN.md charter — the charter overrides any generic recommendation from this skill.

---

Output Formats

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

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

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

---

Tips for Better Results

Query Strategy

• Use multi-dimensional keywords — combine product + industry + tone + density: "entertainment social vibrant content-dense" not just "app"
• Try different keywords 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
• Add --stack <stack> for implementation-specific guidance when the target stack is known

Common Sticking Points

Problem	What to Do
Can't decide on style/color	Re-run --design-system with different keywords
Dark mode contrast issues	Quick Reference §6: color-dark-mode + color-accessible-pairs
Animations feel unnatural	Quick Reference §7: spring-physics + easing + exit-faster-than-enter
Form UX is poor	Quick Reference §8: inline-validation + error-clarity + focus-management
Navigation feels confusing	Quick Reference §9: nav-hierarchy + bottom-nav-limit + back-behavior
Layout breaks on small screens	Quick Reference §5: mobile-first + breakpoint-consistency
Performance / jank	Quick Reference §3: virtualize-lists + main-thread-budget + debounce-throttle

---

Pre-Delivery Checklist

Before delivering UI code, verify these items:

Visual Quality

• [ ] No emojis used as icons (use SVG instead)
• [ ] All icons come from a consistent icon family and style
• [ ] Official brand assets are used with correct proportions and clear space
• [ ] Pressed-state visuals do not shift layout bounds or cause jitter
• [ ] Semantic theme tokens are used consistently (no ad-hoc per-screen hardcoded colors)

Interaction

• [ ] All tappable elements provide clear pressed feedback (ripple/opacity/elevation)
• [ ] Touch targets meet minimum size (>=44x44pt iOS, >=48x48dp Android)
• [ ] Micro-interaction timing stays in the 150-300ms range with native-feeling easing
• [ ] Disabled states are visually clear and non-interactive
• [ ] Screen reader focus order matches visual order, and interactive labels are descriptive
• [ ] Gesture regions avoid nested/conflicting interactions (tap/drag/back-swipe conflicts)

Light/Dark Mode

• [ ] Primary text contrast >=4.5:1 in both light and dark mode
• [ ] Secondary text contrast >=3:1 in both light and dark mode
• [ ] Dividers/borders and interaction states are distinguishable in both modes
• [ ] Modal/drawer scrim opacity is strong enough to preserve foreground legibility (typically 40-60% black)
• [ ] Both themes are tested before delivery (not inferred from a single theme)

Layout

• [ ] Safe areas are respected for headers, tab bars, and bottom CTA bars (mobile only)
• [ ] Scroll content is not hidden behind fixed/sticky bars
• [ ] Verified on small phone, large phone, and tablet (portrait + landscape)
• [ ] Horizontal insets/gutters adapt correctly by device size and orientation
• [ ] 4/8dp spacing rhythm is maintained across component, section, and page levels
• [ ] Long-form text measure remains readable on larger devices (no edge-to-edge paragraphs)

Accessibility

• [ ] All meaningful images/icons have accessibility labels
• [ ] Form fields have labels, hints, and clear error messages
• [ ] Color is not the only indicator
• [ ] Reduced motion and dynamic text size are supported without layout breakage
• [ ] Accessibility traits/roles/states (selected, disabled, expanded) are announced correctly

---

Rule Categories by Priority

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 44x44px, 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	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

---

Quick Reference

1. Accessibility (CRITICAL)

• color-contrast - Minimum 4.5:1 ratio for normal text (large text 3:1)
• focus-states - Visible focus rings on interactive elements (2-4px)
• alt-text - Descriptive alt text for meaningful images
• aria-labels - aria-label for icon-only buttons
• keyboard-nav - Tab order matches visual order; full keyboard support
• form-labels - Use label with for attribute
• skip-links - Skip to main content for keyboard users
• heading-hierarchy - Sequential h1→h6, no level skip
• color-not-only - Don't convey info by color alone (add icon/text)
• reduced-motion - Respect prefers-reduced-motion; reduce/disable animations when requested
• escape-routes - Provide cancel/back in modals and multi-step flows

2. Touch & Interaction (CRITICAL)

• touch-target-size - Min 44x44pt (iOS) / 48x48dp (Android); extend hit area beyond visual bounds if needed
• touch-spacing - Minimum 8px/8dp gap between touch targets
• hover-vs-tap - Use click/tap for primary interactions; don't rely on hover alone

3. Performance (HIGH)

• virtualize-lists - Virtualize long lists (react-window, FlashList)
• main-thread-budget - Keep main thread work <16ms per frame (60fps)
• debounce-throttle - Debounce search input, throttle scroll/resize handlers
• lazy-loading - Lazy load images and below-the-fold content
• reserve-space - Reserve space for async content to prevent CLS

4. Style Selection (HIGH)

• match-product-type - Style should match product type and audience
• consistency - One style language across the app
• svg-icons - Use SVG icons, never emojis as structural icons
• stroke-consistency - Consistent stroke width within the same visual layer

5. Layout & Responsive (HIGH)

• mobile-first - Start with mobile styles, add breakpoints for larger screens
• breakpoint-consistency - Use consistent breakpoints across the app
• no-horizontal-scroll - Prevent horizontal scroll on any device
• viewport-meta - Always include viewport meta tag

6. Typography & Color (MEDIUM)

• base-16px - Base font size 16px, never below 12px for body
• line-height-1.5 - Line-height 1.5 for body text
• semantic-tokens - Use semantic color tokens, not raw hex in components
• color-dark-mode - Test dark mode contrast independently

7. Animation (MEDIUM)

• duration-150-300ms - Micro-interactions 150-300ms
• motion-conveys-meaning - Animation should communicate state change or spatial relationship
• exit-faster-than-enter - Exit animations should be faster than enter
• reduced-motion - Always provide reduced-motion fallback

8. Forms & Feedback (MEDIUM)

• visible-labels - Always use visible labels, not placeholder-only
• error-near-field - Show errors near the field, not at the top
• inline-validation - Validate inline as user types/blurs, not only on submit
• helper-text - Provide helper text for complex fields

9. Navigation Patterns (HIGH)

• predictable-back - Back button always goes to the logical parent
• bottom-nav-limit - Bottom navigation max 5 items
• deep-linking - Support deep linking into app content

10. Charts & Data (LOW)

• legends - Always include legends
• tooltips - Provide tooltips for data points
• accessible-colors - Don't rely on color alone to convey meaning in charts