Better UI UX

Better-UI-UX Skill

1. What This Skill Provides

Six MCP tools for production UI development: suggest_design_system returns 3 complete design system candidates with fonts, colors, icons, and type scale. search_palettes queries 172 curated palettes via BM25 scoring with synonym expansion. transform_component applies glassmorphism, neumorphism, brutalist, or minimal-animated styles to any HTML/JSX. generate_logo creates minimal SVG logos in three styles. generate_icon produces 114 parametric SVG icons from shape primitives with animation support. inject_animations injects GSAP + ScrollTrigger scroll-reveal, stagger, pin-scrub, hover-lift, or combination patterns. Curated database, smart typography pairing, and production-ready animation patterns included.

2. When to Apply — Activation Table

Decision rule: If the task changes how something looks, feels, moves, or is interacted with visually, activate this skill.

3. Mandatory Elicitation Protocol

THIS SECTION IS MANDATORY. Before generating any design system, palette, icon, animation, or component transformation, the agent MUST gather requirements. Do not skip. Do not guess. Do not proceed with partial information without explicit user confirmation.

Required Questions (Must Ask Before ANY Generation)

Optional but Recommended

Inference Rules (When User Provides Partial Info)

Apply these inference rules automatically. State what you inferred and ask for confirmation before proceeding.

Enforcement Rules

1. The agent MUST include at least one elicitation question in its first response.
2. If the user has already provided enough context (project type + industry + mood), the agent should state what it inferred and ask for confirmation — do NOT ask every question verbatim.
3. If the user says "use your judgment" or "you decide", document your assumptions and proceed.
4. Never generate a design system without knowing at least: project type + one of (industry or mood).
5. If only project type is known, infer industry from name/description and state the inference.

4. MCP Tool Reference

Tool 1: suggest_design_system

When to call: Initial setup of any UI project. Returns 3 complete design system candidates with typography (heading + body fonts), color palette (primary/secondary/accent/background/text), icon library recommendation, type scale, and reasoning for each choice.

Required params:

• projectName (string) — Name of the project

Optional params:

• description (string) — Brief description of the project
• mood (string) — One of: corporate, playful, minimal, modern, elegant, brutalist, saas, creative, luxury, tech, health, education, gaming, fintech
• customColors (object) — Exact colors to use instead of suggested palette. Properties: primary, secondary, accent, background, text (each a hex string)

Returns: Object with 3 DesignSystemCandidate entries, each containing: name, description, headingFont (family, weights, googleFontsURL), bodyFont (family, weights, googleFontsURL), colorPalette (primary, secondary, accent, background, text), iconSet (set name + reason), typeScale (modular scale tokens), paletteId, wcagAA (boolean), wcagAAA (boolean).

Example:

{
  "tool": "suggest_design_system",
  "params": {
    "projectName": "PayFlow",
    "description": "Payment processing for small businesses",
    "mood": "corporate",
    "customColors": { "primary": "#1a73e8" }
  }
}

Anti-patterns:

• Do not call without completing elicitation first
• Do not ignore customColors when user provides brand colors
• Do not present all 3 candidates as equal — recommend one with reasoning

Tool 2: search_palettes

When to call: When user needs color palettes for a specific mood/industry, or when suggest_design_system candidates need refinement. Searches 172 curated palettes via BM25 scoring with synonym expansion, IDF weighting, and category boosting.

Required params:

• query (string) — 2-5 keywords for palette search. Use format: [industry] [mood] [style modifier]

Optional params:

• limit (number) — Number of results to return. Default: 10

Returns: Object with query, results array (each entry has palette name, hex values, mood tags, industry tags, contrast data, BM25 score), and totalFound count.

Example:

{
  "tool": "search_palettes",
  "params": {
    "query": "fintech dark",
    "limit": 5
  }
}

Anti-patterns:

• Do not use vague queries like "nice colors" or "pretty" — always include industry + mood
• Do not fabricate results when 0 matches return — broaden the query
• Do not call when user provides exact hex colors — use suggest_design_system with customColors instead

Tool 3: transform_component

When to call: When user wants one of 4 preset visual styles applied via class injection (cheerio). Not a full design rewrite — only adds style classes + CSS template. For fully custom styling, use design tokens.

Required params:

• sourceCode (string) — The HTML/JSX source code to transform
• targetStyle (string) — One of: glassmorphism, neumorphism, brutalist, minimal animated

Optional params: None

Returns: Object with transformedHTML (modified markup with style classes added), css (complete CSS for the applied style), js (initialization JavaScript if needed), requiredLibraries (array of dependencies like gsap).

Example:

{
  "tool": "transform_component",
  "params": {
    "sourceCode": "<div class='card'><h3>Title</h3><p>Content</p></div>",
    "targetStyle": "glassmorphism"
  }
}

Anti-patterns:

• Do not apply glassmorphism to data-heavy tables (reduces readability of dense numbers)
• Do not use brutalist style for healthcare or finance (too aggressive for trust-critical contexts)
• Do not apply to already-styled components without checking existing CSS conflicts
• Do not expect more than 4 styles — this tool only injects preset classes + CSS; it does not generate new design systems

Tool 4: generate_logo

When to call: Only when the user has no existing logo and explicitly needs a placeholder. Generates 3 fixed minimal templates (minimal = initial in circle, geometric = rotated square + circle, abstract = curve + circle) — not AI generation. If the user already provided a logo file, URL, or brand mark, do NOT call this tool; preserve their asset.

Required params:

• companyName (string) — Brand or project name

Optional params:

• style (string) — One of: minimal, geometric, abstract. Default: minimal

Returns: Object with companyName, style, and svg (complete SVG markup string).

Example:

{
  "tool": "generate_logo",
  "params": {
    "companyName": "PayFlow",
    "style": "geometric"
  }
}

Anti-patterns:

• Do not call if the user already has a logo — ask first (see elicitation Q8)
• Do not use for complex illustrations — this generates minimal mark/logotype only
• Do not generate multiple logos without user selecting a style preference
• Do not use abstract style for enterprise/finance audiences (lacks recognizability)

Tool 5: generate_icon

When to call: When user needs a custom parametric SVG icon not available in standard libraries (Lucide, Phosphor, Tabler). Builds icons from shape primitives, not template lookup.

Required params:

• iconName (string) — One of 114 icons: home, search, user, heart, star, settings, mail, bell, check, plus, minus, arrow_right, arrow_left, close, menu, globe, lock, unlock, calendar, clock, camera, download, upload, trash, edit, eye, zap, cloud, code, bookmark, layers, terminal, database, chevron_up, chevron_down, play, pause, stop, volume, mic, image, film, music, phone, message_circle, send, inbox, link, file, folder, copy, shield, filter, refresh_cw, bar_chart, pie_chart, trending_up, monitor, smartphone, gift, award, flag, sun, moon, fire, wind, key, scissors, and more (see availableIcons in response)

Optional params:

• size (number) — Icon size in pixels. Default: 24
• color (string) — Hex color. Default: #111827
• strokeWidth (number) — Stroke width. Default: 2
• fill (boolean) — Fill icon shapes. Default: false
• animated (boolean) — Adds CSS animation keyframes. Default: false
• animationType (string) — One of: spin, bounce, draw, pulse

Returns: Object with svg (complete SVG markup), name, animated, css (if animated), shapeCount, availableIcons (full list).

Example:

{
  "tool": "generate_icon",
  "params": {
    "iconName": "home",
    "size": 24,
    "color": "#2563EB",
    "animated": true,
    "animationType": "bounce"
  }
}

Anti-patterns:

• Do not use for complex multi-path illustrations — keep to single-concept icons
• Do not mix icon styles (filled + outline) at the same hierarchy level
• Do not generate animated icons for every element — reserve for key interactions

Tool 6: inject_animations

When to call: When user wants GSAP + ScrollTrigger animations added to their project. Supports scroll-reveal, stagger, pin-scrub, hover-lift, and combination patterns. Returns JavaScript code with GSAP setup, ScrollTrigger configuration, and cleanup guidance.

Required params:

• htmlCode (string) — HTML code to add animations to
• type (string) — One of: scroll-reveal, stagger, pin-scrub, hover-lift, combination

Optional params:

• duration (number) — Animation duration in seconds (default: 0.8)
• ease (string) — GSAP ease function name (default: "power3.out")
• yOffset (number) — Y offset for reveal animations in pixels (default: 40)
• staggerDelay (number) — Stagger delay between elements in seconds (default: 0.1)

Returns: Object with javascript (complete GSAP initialization code), html (modified HTML with animation classes), css (required CSS for animations), cleanup (function reference for ScrollTrigger cleanup).

Example:

{
  "tool": "inject_animations",
  "params": {
    "htmlCode": "<section><h2>Title</h2><div class='card'>Content</div></section>",
    "type": "combination",
    "duration": 0.8,
    "yOffset": 40
  }
}

Anti-patterns:

• Do not animate layout properties (width, height, top, left) — use transform and opacity only
• Do not add animations to every element on the page — animate 1-2 key elements per view
• Do not skip prefers-reduced-motion — always provide fallback for users who disable animations
• Do not use for dashboard data tables (analysts need fast data access, not decorative motion)

5. Search Query Contract

Rules for constructing search queries for search_palettes:

Query construction formula: [industry] [mood] [style modifier]

Examples by context:

• Fintech dashboard: "fintech dark modern" — industry + mood
• Healthcare app: "healthcare professional minimal" — industry + mood + style
• Gaming site: "gaming vibrant neon" — industry + mood + color hint
• Luxury brand: "luxury elegant dark" — industry + mood + tone
• Creative portfolio: "creative bold expressive" — industry + mood + personality
• Education platform: "education friendly warm" — industry + mood + tone

Fallback strategy: If exact query returns 0 results, try: (1) remove style modifier, (2) use broader industry term, (3) search by mood only. Report what you tried.

6. Design Reasoning Workflow

Follow this step-by-step process for every design task:

Step 1: Elicit Requirements (MANDATORY)

Complete the elicitation protocol from Section 3. Do not skip. Do not guess. Document answers.

Step 2: Search Palettes

Call search_palettes with keywords derived from gathered requirements:

search_palettes(query="[industry] [mood]", limit=5)

Review results for contrast data and mood alignment.

Step 3: Get Design System Candidates

Call suggest_design_system with full context:

suggest_design_system(query="[type] [industry] [mood]", projectName="[name]")

If user has custom colors, include the customColors parameter. If user provided brand hex values, ALWAYS pass them.

Step 4: Apply Custom Colors (if provided)

If user specified exact colors, use suggest_design_system with customColors — do NOT use search_palettes for exact color requests.

Step 5: Choose Animation Strategy

Based on project type:

• Landing pages: scroll-reveal for hero/sections, stagger for feature lists, combination for full page
• Dashboards: hover-lift for cards, minimal scroll effects, avoid motion on data views
• Portfolios: pin-scrub for hero parallax, combination for project grid
• Blogs: scroll-reveal for article cards, subtle stagger for related posts
• E-commerce: stagger for product grids, hover-lift for product cards, scroll-reveal for reviews
• SaaS: scroll-reveal for feature sections, hover-lift for pricing cards

Step 6: Explain WHY Each Choice Fits

For every recommendation, provide reasoning:

• "Space Grotesk was chosen because its geometric forms convey technical precision appropriate for a fintech product."
• "The blue-dominant palette works because finance industry users associate blue with trust and stability."
• "Restrained animation fits because dashboard users prioritize speed over delight."

Step 7: List Anti-Patterns for This Context

Always include what to avoid for the specific project type and industry. Reference Section 7.

Step 8: Show Before/After (if Transforming Existing UI)

If the user has existing code, show the transformation. Use transform_component and present diff or side-by-side.

7. Anti-Patterns

Things the agent MUST NOT do. Violating any of these produces unprofessional, inaccessible, or broken UI.

8. Color Theory Rules

These rules govern all palette recommendations and color system generation.

9. Typography Rules

10. Animation Rules

11. Example Workflow

User request: "I'm building a landing page for my fintech startup and it looks boring. Make it beautiful."

Step 1: Elicitation

The agent asks:

Before I generate a design system, I need a few details:

1. What's the project name?
2. What does your fintech product do? (payments, lending, investing, banking, insurance?)
3. How would you describe the mood? Professional and trustworthy, or modern and bold?
4. Who is your target audience? (consumers, small businesses, enterprises?)
5. What's your frontend stack?
6. Any colors to avoid?

User responds: "It's called PayFlow. We do payment processing for small businesses. Professional but modern. React with Tailwind. Avoid red."

Step 2: Inference + Confirmation

The agent states:

Got it. Based on your answers, I'm inferring: fintech landing page, professional-modern mood, small business audience, trust-critical context. I'll avoid red and honor that fintech users associate blue with trust. Proceed?

Step 3: Search Palettes

search_palettes(query="fintech professional modern", limit=5)

Returns: 5 palettes including "Midnight Finance" (deep navy + teal accent), "Clean Ledger" (white + blue), "Trust Gradient" (navy to indigo).

Step 4: Design System

suggest_design_system(query="fintech landing page professional modern", projectName="PayFlow", customColors=["#1a73e8"])

Returns 3 candidates:

1. Candidate A: Inter + JetBrains Mono — Navy/Teal palette — Lucide icons — Major Third scale
2. Candidate B: DM Sans + IBM Plex Mono — Slate/Indigo palette — Phosphor icons — Perfect Fourth scale
3. Candidate C: Plus Jakarta Sans + Fira Code — Dark blue/Amber palette — Tabler icons — Augmented Fourth scale

Step 5: Recommendation

Candidate A recommended because Inter's neutral geometry reads well across all screen sizes. JetBrains Mono provides clear number alignment for pricing tables. Navy/Teal palette conveys trust (navy) with modern differentiation (teal). Red excluded per your request. WCAG AA compliant.

Step 6: Animation Strategy

• Hero section: scroll-reveal with power3.out easing, 0.8s duration — entrance from below
• Feature cards: stagger with 100ms delay between items — clean entrance
• CTA section: scroll-reveal with slight scale animation — draws attention
• Avoid: Heavy scroll animations on pricing (users need to scan quickly)

Step 7: Anti-Patterns for This Context

• Do not animate chart data on pricing page (would cause distraction during comparison)
• Do not use glassmorphism on the hero (fintech needs trust, not trendy visual effects)
• Do not add scroll-triggered animations to the navigation bar (must remain instantly accessible)
• Do not use neon or saturated accent colors (feels gambling-adjacent, not fintech)

Step 8: Implementation

The agent generates the design system CSS, component structure, and GSAP animation code with proper cleanup.

12. Quick Reference Table