Imported from ankaboot-source/boucle (.jcode/skills/ui-ux-pro-max/SKILL.md). Install upstream with npx skills add ankaboot-source/boucle --skill ui-ux-pro-max. Copyright stays with the author.

name: ui-ux-pro-max description: UI/UX design intelligence with searchable database — 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 stacks. Use when designing, building, or reviewing UI: pages, components, color schemes, typography, layout, accessibility, animation, or data visualization.

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:

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 "humanitarian NGO editorial brutalist dark" --design-system -p "Urgence Palestine"

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>

• --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:

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

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

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

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