# Better UI UX

> UI/UX design system generation, palette search, component transformation, icon generation, and GSAP animation injection. Use when building or styling web UIs, choosing color palettes, generating icons, adding animations, or transforming component styles. Skip for non-UI tasks.

- Skill: `mert-byt/better-ui-ux-2` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add mert-byt/better-ui-ux-2`
- Raw SKILL.md: https://api.skillmd.com/api/skills/mert-byt/better-ui-ux-2/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Design & Media
- Author: Mert-byt (https://skillmd.com/u/mert-byt)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/mert-byt/better-ui-ux-2

---


# 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

| Use when | Skip when |
|----------|-----------|
| User asks for design system, colors, palette, icons, animations, component styling, UI transformation | User is debugging logic, writing tests, configuring CI, working on non-UI code |
| "Make it beautiful", "improve the design", "looks boring", "needs polish" | Backend API development or database schema work |
| Building or styling web UIs — landing pages, dashboards, SaaS, portfolios, e-commerce | DevOps, infrastructure, or deployment configuration |
| Choosing color palettes, typography pairings, or icon sets | Unit testing, integration testing, or test coverage |
| Generating SVG logos or parametric icons not in standard libraries | Performance tuning unrelated to visual interface |
| Adding GSAP/ScrollTrigger scroll animations or micro-interactions | Non-visual automation scripts, CLI tools, data processing |
| Transforming component visual styles (glassmorphism, neumorphism, brutalist) | Accessibility audit unrelated to visual design (semantic HTML, ARIA roles) |
| User says "this UI feels off" or "needs more personality" | Build system configuration, bundler settings, dependency management |

**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)

| # | Question | Why It Matters | Example Answers |
|---|----------|----------------|-----------------|
| 1 | **Project type** — What are you building? | Determines layout patterns, component density, interaction models | SaaS, portfolio, e-commerce, blog, dashboard, mobile app, landing page, admin panel |
| 2 | **Industry/domain** — What space is this in? | Constrains palette (no neon green in healthcare), icon choices, trust signals | Finance, healthcare, gaming, education, food, travel, real estate, tech, creative, legal |
| 3 | **Mood/tone** — How should it feel? | Drives typography personality, color saturation, animation intensity, spacing rhythm | Professional, playful, elegant, minimal, bold, brutalist, luxury, warm, cool, futuristic |
| 4 | **Target audience** — Who uses this? | Affects information density, jargon tolerance, visual complexity, accessibility needs | Developers, consumers, enterprise, creatives, kids, elderly, mixed audience |
| 5 | **Frontend stack** — What tech? | Determines CSS approach (Tailwind vs CSS modules vs inline), component patterns, animation library | React, Vue, Svelte, vanilla, Next.js, Nuxt, Astro, HTML/CSS only |
| 6 | **Colors to avoid** — Any exclusions? | Prevents clash with existing brand, cultural sensitivities, accessibility requirements | "No red", "avoid yellow", "nothing too saturated" |

### Optional but Recommended

| # | Question | Why It Helps |
|---|----------|--------------|
| 7 | **Existing brand colors** — Hex values? | Uses `customColors` parameter to honor brand constraints in design system |
| 8 | **Existing logo** — Do you already have a logo file/URL? | If yes, **do NOT call `generate_logo`** — preserve the user's brand asset |
| 9 | **Competitor designs** — What to differentiate from? | Avoids accidental similarity, helps find unique positioning |
| 10 | **Accessibility requirements** — WCAG level? | Constrains contrast ratios, font sizes, animation intensity (AAA vs AA) |

### Inference Rules (When User Provides Partial Info)

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

| If user mentions... | Infer project type | Infer mood |
|---------------------|-------------------|------------|
| Project name contains "tech", "start.io", "app", "dev" | Tech startup, SaaS | Modern, minimal, clean |
| Description mentions "finance", "pay", "bank", "invest" | Fintech, financial dashboard | Professional, trustworthy, stable |
| Description mentions "kids", "young", "play", "learn" | EdTech, children's app | Playful, colorful, friendly |
| Description mentions "luxury", "premium", "exclusive", "boutique" | Luxury brand, premium service | Elegant, dark/gold, restrained |
| Description mentions "health", "med", "clinic", "well" | Healthcare, wellness | Calm, clean, trustworthy, blue/green |
| Description mentions "game", "esport", "stream" | Gaming, entertainment | Bold, vibrant, high-contrast, neon accents |
| Description mentions "food", "restaurant", "recipe", "menu" | Food industry, restaurant | Warm, appetizing, rich colors |
| Description mentions "travel", "hotel", "booking" | Travel, hospitality | Inviting, airy, aspirational |
| Description mentions "photo", "design", "art", "creative" | Portfolio, creative agency | Expressive, unconventional, strong typography |
| Description mentions "data", "analytics", "metrics", "monitor" | Dashboard, analytics tool | Functional, data-dense, neutral with accent |

### 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**:
```json
{
  "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**:
```json
{
  "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**:
```json
{
  "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**:
```json
{
  "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**:
```json
{
  "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**:
```json
{
  "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`:

| Rule | Correct Example | Incorrect Example |
|------|-----------------|-------------------|
| Use 2-5 keywords per query | `"fintech dark modern"` | `"colors"` |
| One dominant intent per query | `"healthcare professional"` | `"healthcare dark playful minimal bold"` |
| Prefer specific over generic | `"fintech dark"` | `"nice colors for my finance app"` |
| Include industry keyword | `"gaming vibrant neon"` | `"vibrant neon"` |
| Include mood keyword | `"elegant luxury dark"` | `"dark"` |
| If 0 results, broaden query | `"dark modern"` | Repeat same query |
| Never fabricate results | Report "no matches found" | Invent palette data |

**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.

| Anti-Pattern | Why It's Wrong | Better Approach |
|--------------|----------------|-----------------|
| Generic blue/gray palette without context | Feels corporate and forgettable | Choose palette from industry + mood data via `search_palettes` |
| Animating every element on the page | Overwhelms users, hurts performance, causes motion sickness | Animate 1-2 key elements per view maximum |
| Ignoring WCAG contrast ratios | Excludes users with visual impairments, potential legal liability | Verify 4.5:1 for body text, 3:1 for large text minimum |
| Font sizes below 14px for body text | Unreadable on mobile, triggers iOS auto-zoom | Use 16px minimum for body text, 14px absolute floor |
| Using more than 3 font families | Visual chaos, slow loading, inconsistent personality | Maximum 2 font families: 1 heading + 1 body |
| Skipping elicitation and guessing | Misses user needs, wastes iterations, produces wrong design | Always complete Section 3 requirements gathering first |
| Fabricating palette search results | Misleads user, produces colors that don't exist in database | Report "no matches" and broaden query, never invent data |
| Overriding user-specified colors | Breaks brand identity, ignores client constraints | Use `customColors` parameter, never replace user hex values |
| Using linear gradients as text backgrounds | Reduces readability, fails accessibility, looks dated | Use solid colors for text, gradients for decorative backgrounds only |
| Using `backdrop-filter: blur()` without fallback | Breaks in Firefox < 103, performance cost on mobile | Provide solid background fallback, test in Firefox |
| Animating `width`, `height`, `top`, `left` | Triggers layout reflow, causes jank, drops frames | Use `transform` and `opacity` only for animation |
| Hardcoding hex values in components | Breaks theming, makes dark mode impossible,维护 nightmare | Use CSS custom properties or design tokens |
| Using emoji as icons | Inconsistent rendering across platforms, no scalability, no accessibility | Use SVG icons from Lucide, Phosphor, or Tabler |
| Adding glassmorphism to data tables | Reduces readability of dense numbers, hurts data comprehension | Use glassmorphism sparingly — cards, overlays, hero sections only |
| Ignoring `prefers-reduced-motion` | Excludes users with vestibular disorders, accessibility violation | Always wrap animations in reduced-motion media query |

## 8. Color Theory Rules

These rules govern all palette recommendations and color system generation.

| Rule | Specification |
|------|---------------|
| **60-30-10 rule** | 60% dominant (background/surface), 30% secondary (cards, sections), 10% accent (CTAs, highlights) |
| **Complementary colors** | Use for high contrast — opposite on color wheel. Best for CTAs against neutral backgrounds. |
| **Analogous colors** | Use for harmonious, calm feel — adjacent on color wheel. Best for wellness, healthcare, luxury. |
| **Triadic colors** | Use for vibrant, balanced — three equidistant on wheel. Best for creative, gaming, youth brands. |
| **Warm vs cool** | Warm colors (red, orange, yellow) advance visually. Cool colors (blue, green, purple) recede. Use warm for emphasis, cool for background. |
| **Contrast ratio minimum** | Body text: 4.5:1 against background (WCAG AA). Large text (18px+ bold or 24px+): 3:1 minimum. UI components: 3:1 against adjacent colors. |
| **Dark mode strategy** | Do NOT just invert colors. Use desaturated dark backgrounds (#121212 to #1E1E1E range). Reduce accent saturation by 10-20%. Use elevated surfaces (lighter) for cards, not darker. Text: #E0E0E0 for body, #FFFFFF for headings. |
| **Semantic color tokens** | Define `--color-primary`, `--color-secondary`, `--color-accent`, `--color-error`, `--color-success`, `--color-warning`, `--color-surface`, `--color-background`, `--color-text`. Never use raw hex in components. |
| **Color accessibility** | Never convey information by color alone — add icons, text labels, or patterns. Test with colorblindness simulators (deuteranopia, protanopia, tritanopia). |

## 9. Typography Rules

| Rule | Specification |
|------|---------------|
| **Maximum 2 font families** | 1 heading font + 1 body font. Monospace acceptable as 3rd only for code/technical content. |
| **Type scale** | Use modular scale: Major Third (1.25) for compact UIs, Perfect Fourth (1.333) for standard web, Augmented Fourth (1.414) for large displays. |
| **Base font size** | 16px minimum for body text. 14px absolute minimum for secondary labels only. |
| **Line height** | Body text: 1.5 (150%). Headings: 1.2 (120%). Small text (12-14px): 1.6 for readability. |
| **Measure (line length)** | 45-75 characters per line. Optimal: 66 characters. Mobile: 35-50 characters. |
| **Font weight hierarchy** | Headings: 600-700 (SemiBold to Bold). Body: 400 (Regular). Labels: 500 (Medium). Captions: 400. |
| **Font loading** | Use `font-display: swap` to prevent invisible text (FOIT). Preload only critical fonts. |
| **Number alignment** | Use tabular figures (`font-variant-numeric: tabular-nums`) for data columns, prices, timers. |
| **Letter spacing** | Headings: -0.02em to -0.01em (tighter). Body: normal (0). Small caps/labels: 0.05em to 0.1em (wider). |

## 10. Animation Rules

| Rule | Specification |
|------|---------------|
| **Duration** | Micro-interactions (hover, focus, toggle): 200-300ms. Page transitions: 600-1200ms. Stagger entrance: 30-50ms delay between items. |
| **Easing** | Entering elements: `ease-out` or `power3.out`. Exiting elements: `ease-in` or `power3.in`. Movement: `power2.inOut`. Springs: `elastic.out(1, 0.3)` for playful feel. |
| **ScrollTrigger cleanup** | Always provide cleanup function. `ScrollTrigger.getAll().forEach(t => t.kill())` on unmount. React: return cleanup in `useEffect`. |
| **Never animate layout** | Never animate `width`, `height`, `top`, `left`, `margin`, `padding`. Use `transform: translate()`, `scale()`, `rotate()` and `opacity` only. |
| **Compositor properties only** | Animate only `transform` and `opacity` — these run on GPU compositor thread, not main thread. |
| **Respect prefers-reduced-motion** | Wrap all animations in `@media (prefers-reduced-motion: no-preference)` or check `window.matchMedia`. Provide instant alternative. |
| **Maximum 3 animation types per page** | Choose max 3 from: scroll-reveal, stagger, pin-scrub, hover-lift. More than 3 causes visual chaos. |
| **Exit faster than enter** | Exit animations: 60-70% of enter duration. Enter: 400ms → Exit: 250-280ms. |
| **Interruptible** | Animations must be interruptible. User interaction should cancel in-progress animation immediately. |
| **No blocking animation** | Never block user input during animation. UI must stay interactive throughout. |

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

| Rule | Value |
|------|-------|
| Elicitation | MANDATORY before any generation |
| Max font families | 2 (heading + body) |
| Base font size | 16px minimum |
| Body line-height | 1.5 |
| Heading line-height | 1.2 |
| Characters per line | 45-75 (optimal: 66) |
| Type scale ratio | 1.25 (Major Third) or 1.333 (Perfect Fourth) |
| Color distribution | 60% dominant / 30% secondary / 10% accent |
| Body text contrast | 4.5:1 minimum (WCAG AA) |
| Large text contrast | 3:1 minimum |
| Micro-interaction duration | 200-300ms |
| Page transition duration | 600-1200ms |
| Stagger delay | 30-50ms per item |
| Exit duration | 60-70% of enter duration |
| Max animation types per page | 3 |
| Animate only | `transform` and `opacity` |
| Palette query format | `[industry] [mood] [style]` |
| Palette query keywords | 2-5 keywords |
| Custom colors | Always pass to `suggest_design_system`, never to `search_palettes` |
| Dark mode background | #121212 to #1E1E1E (desaturated, not inverted) |
| Touch target minimum | 44×44px (web) |
| Reduced motion | Always provide fallback |
| Emoji as icons | Never — use SVG from Lucide/Phosphor/Tabler |