Aesthetic

Aesthetic

Create aesthetically beautiful interfaces by following proven design principles and systematic workflows. This skill combines design thinking, frontend implementation patterns, and comprehensive analysis techniques.

When to Use This Skill

Use when:

• Building or designing user interfaces
• Analyzing designs from inspiration websites (Dribbble, Mobbin, Behance)
• Generating design images and evaluating aesthetic quality
• Implementing visual hierarchy, typography, color theory
• Adding micro-interactions and animations
• Creating design documentation and style guides
• Need guidance on accessibility and design systems
• Building production-grade frontend interfaces with distinctive aesthetics

Core Philosophy

Design Thinking First: Before coding, understand context and commit to a BOLD aesthetic direction. Choose a clear conceptual direction and execute it with precision. Bold maximalism and refined minimalism both work - the key is intentionality, not intensity.

Evidence-Based Aesthetics: AI lacks aesthetic sense - standards must come from analyzing high-quality examples and aligning with market tastes. Study existing designs, identify patterns, extract principles.

Progressive Excellence: Start with BEAUTIFUL (aesthetics), ensure RIGHT (functionality/accessibility), add SATISFYING (micro-interactions), elevate with PEAK (storytelling).

Quick Reference Framework

1. BEAUTIFUL: Understanding Aesthetics

Study existing designs, identify patterns, extract principles.

Reference: references/design-principles.md - Load for visual hierarchy, typography, color theory, white space principles.

2. RIGHT: Ensuring Functionality

Beautiful designs lacking usability are worthless. Study design systems, component architecture, accessibility requirements.

Reference: references/design-principles.md - Load for design systems, component libraries, WCAG accessibility standards.

3. SATISFYING: Micro-Interactions

Incorporate subtle animations with appropriate timing (150-300ms), easing curves (ease-out for entry, ease-in for exit), sequential delays.

Reference: references/micro-interactions.md - Load for duration guidelines, easing curves, performance optimization.

4. PEAK: Storytelling Through Design

Elevate with narrative elements - parallax effects, particle systems, thematic consistency. Use restraint: "too much of anything isn't good."

Reference: references/storytelling-design.md - Load for narrative elements, scroll-based storytelling, interactive techniques.

Frontend Implementation Guidelines

Typography

Choose fonts that are beautiful, unique, and interesting. Avoid generic fonts like Arial and Inter. Pair a distinctive display font with a refined body font.

Color & Theme

Commit to a cohesive aesthetic. Use CSS variables for consistency. Dominant colors with sharp accents outperform timid, evenly-distributed palettes.

Motion & Animation

Use animations for effects and micro-interactions. Prioritize CSS-only solutions. Use anime.js for complex animations.

Reference: references/animejs.md - Load when implementing anime.js v4 animations.

Spatial Composition

Unexpected layouts. Asymmetry. Overlap. Diagonal flow. Grid-breaking elements. Generous negative space OR controlled density.

Backgrounds & Visual Details

Create atmosphere and depth. Add contextual effects and textures: gradient meshes, noise textures, geometric patterns, layered transparencies, dramatic shadows, decorative borders, custom cursors, grain overlays.

Reference: references/implementation-guide.md - Load for detailed frontend design execution patterns.

Workflows

Workflow 1: Capture & Analyze Inspiration

Extract design guidelines from inspiration websites: 1. Browse inspiration sites (Dribbble, Mobbin, Behance, Awwwards) 2. Use chrome-devtools skill to capture full-screen screenshots 3. Use ai-multimodal skill to analyze and extract design patterns 4. Document findings in project design guidelines

Reference: references/workflows.md - Load for complete workflow steps and analysis checklist.

Workflow 2: Generate & Iterate Design Images

Create aesthetically pleasing designs through iteration: 1. Define design prompt with style, colors, typography, audience 2. Use ai-multimodal skill to generate design images 3. Evaluate aesthetic quality (must score >= 7/10) 4. Iterate until professional standards met 5. Document final design decisions

Reference: references/workflows.md - Load for complete iteration process and quality standards.

Design Documentation

Create Design Guidelines

Use assets/design-guideline-template.md to document:

• Color patterns & psychology
• Typography system & hierarchy
• Layout principles & spacing
• Component styling standards
• Accessibility considerations
• Design highlights & rationale

Save in project ./docs/design-guideline.md.

Create Design Story

Use assets/design-story-template.md to document:

• Narrative elements & themes
• Emotional journey
• User journey & peak moments
• Design decision rationale

Save in project ./docs/design-story.md.

Anti-Patterns: Avoid Generic AI Aesthetics

NEVER use:

• Overused font families (Inter, Roboto, Arial, system fonts)
• Cliched color schemes (particularly purple gradients on white backgrounds)
• Predictable layouts and component patterns
• Cookie-cutter design that lacks context-specific character

Variation Principle: No design should be the same. Vary between light and dark themes, different fonts, different aesthetics. NEVER converge on common choices (Space Grotesk, for example) across generations.

Implementation Complexity Matching

Match implementation complexity to the aesthetic vision:

• Maximalist designs: Need elaborate code with extensive animations and effects
• Minimalist/refined designs: Need restraint, precision, careful attention to spacing, typography, and subtle details
• Elegance: Comes from executing the vision well

Related Skills Integration

• ai-multimodal: Analyze documents, screenshots & videos, generate design images, evaluate aesthetic quality using Gemini API
• chrome-devtools: Capture screenshots from inspiration websites, navigate pages, interact with elements
• media-processing: Refine generated images (FFmpeg for video, ImageMagick for images)
• ui-styling: Implement designs with shadcn/ui components + Tailwind CSS
• web-frameworks: Build with Next.js, React, Vue

Reference: references/design-resources.md - Load for inspiration platforms, design systems, AI tools, MCP integrations.

Key Principles

1. Aesthetic standards come from humans, not AI - study quality examples 2. Choose a BOLD aesthetic direction and execute with precision 3. Iterate based on analysis - never settle for first output (minimum 7/10 quality) 4. Balance beauty with functionality and accessibility 5. Document decisions for consistency across development 6. Use progressive disclosure in design - reveal complexity gradually 7. Match implementation complexity to aesthetic vision 8. Avoid generic AI aesthetics - create context-specific character

Code Quality Standards

Implement working code that is:

• Production-grade and functional
• Visually striking and memorable
• Cohesive with a clear aesthetic point-of-view
• Meticulously refined in every detail

Remember: Claude is capable of extraordinary creative work. Don't hold back, show what can truly be created when thinking outside the box and committing fully to a distinctive vision.

Design Guidelines: [Project Name]

_Generated: [Date]_

Design Style

[Specify: Minimalism, Glassmorphism, Neo-brutalism, Modern, Memphis, Flat Design, etc.]

Color Palette

Primary Colors

• Primary: #000000 - [Description/Usage]
• Secondary: #000000 - [Description/Usage]

Accent Colors

• Accent: #000000 - [Description/Usage]
• Success: #000000 - [Description/Usage]
• Warning: #000000 - [Description/Usage]
• Error: #000000 - [Description/Usage]

Neutral Colors

• Background: #000000 - [Description/Usage]
• Surface: #000000 - [Description/Usage]
• Border: #000000 - [Description/Usage]

Color Psychology

[Explain mood and emotions evoked by color choices]

Typography System

Font Families

• Primary Font: [Font Name] - Body text, paragraphs
• Secondary Font: [Font Name] - Headings, emphasis
• Monospace Font: [Font Name] - Code, technical content

Font Hierarchy

• H1: [Size]px / [Weight] / [Line Height] - [Usage]
• H2: [Size]px / [Weight] / [Line Height] - [Usage]
• H3: [Size]px / [Weight] / [Line Height] - [Usage]
• Body: [Size]px / [Weight] / [Line Height] - [Usage]
• Small: [Size]px / [Weight] / [Line Height] - [Usage]

Typography Guidelines

• Line length: [Character count] characters max
• Paragraph spacing: [Value]
• Letter spacing: [Value]

Layout Principles

Grid System

• Columns: [Number]
• Gutter: [Size]px
• Margin: [Size]px
• Max width: [Size]px

Spacing Scale

• xs: [Size]px
• sm: [Size]px
• md: [Size]px
• lg: [Size]px
• xl: [Size]px
• 2xl: [Size]px

Responsive Breakpoints

• Mobile: [Width]px
• Tablet: [Width]px
• Desktop: [Width]px
• Wide: [Width]px

Component Styling

Buttons

• Primary: [Description of style]
• Secondary: [Description of style]
• Ghost: [Description of style]
• Sizes: [List sizes]
• States: Default, Hover, Active, Disabled

Cards

• Border radius: [Value]
• Shadow: [Value]
• Padding: [Value]
• Background: [Color]

Forms

• Input height: [Value]
• Border radius: [Value]
• Focus state: [Description]
• Error state: [Description]

Navigation

• [Description of nav patterns]

Visual Hierarchy

Emphasis Techniques

• [List how to draw attention: size, color, placement, etc.]

Content Flow

• [Describe reading patterns: F-pattern, Z-pattern, etc.]

Micro-Interactions

Animation Timing

• Fast: 150ms - [Usage]
• Normal: 250ms - [Usage]
• Slow: 350ms - [Usage]

Easing Curves

• Ease-out: [Usage]
• Ease-in: [Usage]
• Spring: [Usage]

Interactive States

• Hover: [Description]
• Active: [Description]
• Focus: [Description]
• Loading: [Description]

Accessibility

Contrast Ratios

• Text: [Ratio] (WCAG AA: 4.5:1 minimum)
• Large text: [Ratio] (WCAG AA: 3:1 minimum)
• UI elements: [Ratio]

Focus Indicators

• [Description of focus styles]

Touch Targets

• Minimum size: 44x44px

Design Highlights

What Works Well

• [List successful design decisions]

Unique Elements

• [List distinctive design features]

Brand Alignment

• [Explain how design supports brand identity]

Implementation Notes

Technologies

• [List frameworks, libraries, tools used]

Performance Considerations

• [List optimization strategies]

Browser Support

• [List supported browsers/versions]

Resources

Design Files

• Figma: [Link]
• Assets: [Link]

Related Documentation

• [Link to design-story.md]
• [Link to component library]

Design Story: [Project Name]

_Generated: [Date]_

Project Context

Purpose

[What problem does this design solve?]

Target Audience

[Who is this design for?]

Key Objectives

1. [Objective 1] 2. [Objective 2] 3. [Objective 3]

Design Narrative

Core Message

[What story does this design tell?]

Emotional Journey

[What should users feel as they interact?]

Visual Metaphor

[What metaphor or theme unifies the design?]

User Journey

Entry Point

First Impression: [What users see first] Goal: [What should users understand immediately] Design Choices: [How design supports this]

Exploration Phase

User Actions: [What users do next] Design Response: [How interface responds] Micro-Interactions: [Subtle feedback provided]

Engagement Phase

Key Interactions: [Main user activities] Visual Feedback: [How design reinforces actions] Storytelling Elements: [Narrative reinforcement]

Peak Moment

Highlight: [Most memorable interaction] Implementation: [How it's achieved technically] Purpose: [Why this moment matters]

Thematic Elements

Visual Theme

[Description of consistent visual approach]

Narrative Devices

• Parallax: [How depth is used]
• Transitions: [How sections connect]
• Progressive Disclosure: [How information unfolds]
• Motion: [How animation tells the story]

Symbolism

[Meaning behind design choices]

Design Decisions

Why This Style?

[Rationale for design style choice]

Why These Colors?

[Reasoning behind color palette]

Why This Layout?

[Logic behind structure and flow]

Why These Interactions?

[Purpose of micro-interactions chosen]

Technical Storytelling

Performance Story

[How fast loading enhances narrative]

Responsive Story

[How design adapts across devices]

Accessibility Story

[How inclusive design supports everyone]

Evolution

Initial Concepts

[Early ideas explored]

Key Iterations

[Major changes and why]

Final Direction

[Ultimate design rationale]

Inspiration

Design References

• [Source 1]: [What inspired]
• [Source 2]: [What inspired]
• [Source 3]: [What inspired]

Cultural Context

[Broader design trends considered]

Impact

Intended Effect

[What users should take away]

Success Metrics

[How to measure if story resonates]

Future Chapters

[How design can evolve]

Reflections

What Worked

[Successful narrative elements]

What We Learned

[Insights gained from process]

What's Next

[Future storytelling opportunities]

---

Remember: Every design tells a story. Make it intentional, coherent, and meaningful.

Anime.js v4 Reference Guide for AI Assistants

🚨 CRITICAL: ALWAYS USE ANIME.JS V4 SYNTAX 🚨

This project uses Anime.js v4.x.x - DO NOT use v3 syntax under any circumstances

If you're about to write `import anime from 'animejs'` - STOP! That's v3. This project uses v4. Use the correct import below.

🚀 Quick Start - Essential Setup

1. Correct v4 Import (REQUIRED)

// ✅ CORRECT v4 imports
import { animate, createTimeline, stagger, utils, svg, eases, engine } from 'animejs';

// ❌ WRONG v3 import - NEVER USE THIS
// import anime from 'animejs';

2. Configure Time Units to Seconds (SET ONCE IN APP ENTRY POINT)

// ⚠️ IMPORTANT: Set this ONLY ONCE in your app's main entry point
// For React: App.js/App.tsx or index.js/index.tsx
// For Vue: main.js/main.ts
// For vanilla JS: The main script file that loads first

import { engine } from 'animejs';

// Set ONLY in the app's entry point, NOT in components
engine.timeUnit = 's';

// Now ALL durations use seconds everywhere: 1 = 1 second, 0.5 = 500ms
// DO NOT set this in individual components - it's a global setting!

3. Single-Line Format for Simple Animations (REQUIRED)

// ✅ GOOD - Clean, readable, one line for simple tweens
animate('.element', { x: 250, duration: 1, ease: 'outQuad' });

// ❌ BAD - Unnecessary multi-line for simple tweens
animate('.element', {
  x: 250,
  duration: 1,
  ease: 'outQuad'
});

✅ Quick Validation Checklist

Before generating anime.js code, verify:

• [ ] Using import { animate, ... } from 'animejs' NOT import anime
• [ ] Set engine.timeUnit = 's' ONLY ONCE in app entry point (NOT in components)
• [ ] Using seconds for all durations (1 = 1 second)
• [ ] Simple animations on ONE LINE
• [ ] Using animate() NOT anime()
• [ ] Using createTimeline() NOT anime.timeline()
• [ ] Using ease: NOT easing:
• [ ] Using to: for values, NOT value:
• [ ] Using on prefix for callbacks (onUpdate, onComplete)
• [ ] Using loop and alternate NOT direction
• [ ] Using correct v4 stagger syntax with stagger()
• [ ] Using shorthand properties (x, y, z) when possible

🎯 Core API - Most Common Patterns

Basic Animation (single line for simple tweens)

// Simple tween - ALWAYS one line
animate('.element', { x: 250, rotate: 180, duration: 0.8, ease: 'inOutQuad' });

// Fade in - one line
animate('.element', { opacity: [0, 1], y: [20, 0], duration: 0.6, ease: 'outQuad' });

// Scale bounce - one line
animate('.element', { scale: [0, 1], duration: 0.8, ease: 'outElastic(1, 0.5)' });

// Infinite loop - one line
animate('.element', { rotate: 360, duration: 2, loop: true, ease: 'linear' });

Timeline Creation

const tl = createTimeline({ defaults: { duration: 1, ease: 'outQuad' } });

tl.add('.element1', { x: 250 })
  .add('.element2', { y: 100 }, '+=0.2')  // 0.2s after previous
  .add('.element3', { rotate: 180 }, '<'); // at start of previous

Stagger Animations (single line)

animate('.elements', { x: 250, delay: stagger(0.1) });  // 0.1s between each
animate('.elements', { x: 250, delay: stagger(0.1, { from: 'center' }) });

❌ Common AI Mistakes to Avoid

MISTAKE #1: Using v3 Import Pattern

// ❌ WRONG - This is v3
import anime from 'animejs';
anime({ targets: '.element', translateX: 250 });

// ✅ CORRECT - Always use v4
import { animate } from 'animejs';
animate('.element', { x: 250 });

MISTAKE #2: Using 'targets' Property

// ❌ WRONG - 'targets' is v3
animate({ targets: '.element', translateX: 250 });

// ✅ CORRECT - First parameter is the target
animate('.element', { x: 250 });

MISTAKE #3: Using 'easing' Instead of 'ease'

// ❌ WRONG
animate('.element', { x: 250, easing: 'easeInOutQuad' });

// ✅ CORRECT
animate('.element', { x: 250, ease: 'inOutQuad' });

MISTAKE #4: Using 'value' for Animation Values

// ❌ WRONG - 'value' is v3
animate('.element', { x: { value: 250 } });

// ✅ CORRECT - Use 'to' for values
animate('.element', { x: { to: 250 } });

MISTAKE #5: Wrong Timeline Syntax

// ❌ WRONG - anime.timeline() is v3
const tl = anime.timeline();

// ✅ CORRECT - Use createTimeline
import { createTimeline } from 'animejs';
const tl = createTimeline();

📋 Property Syntax Reference (v3 → v4)

Animation Values

// ✅ v4: Use 'to' for target values
{ opacity: { to: 0.5 } }
{ x: { to: [0, 100] } }

// ❌ v3: DON'T use 'value'
// { opacity: { value: 0.5 } }

Easing Functions

// ✅ v4: Use 'ease' (no 'ease' prefix)
{ ease: 'inOutQuad' }
{ ease: 'outElastic(1, 0.5)' }
{ ease: 'cubicBezier(0.4, 0, 0.2, 1)' }

// ❌ v3: DON'T use 'easing' or 'ease' prefix
// { easing: 'easeInOutQuad' }

Direction & Looping

// ✅ v4
{
  loop: true,        // infinite loop
  loop: 3,          // loop 3 times
  alternate: true,   // alternate direction
  reversed: true     // play in reverse
}

// ❌ v3: DON'T use 'direction'
// { direction: 'alternate' }

Transform Properties (Shorthand Preferred)

// ✅ Both syntaxes work in v4:
animate('.element', { x: 100, y: 50, z: 25 });           // shorthand (preferred)
animate('.element', { translateX: 100, translateY: 50, translateZ: 25 }); // explicit

Callbacks (ALL prefixed with 'on')

// ✅ v4: Simple callback - keep on one line
animate('.element', { x: 250, duration: 1, onComplete: () => console.log('Done!') });

// ✅ v4: Multiple callbacks - use multi-line
animate('.element', {
  x: 250,
  duration: 1,
  onBegin: (anim) => console.log('Started'),
  onUpdate: (anim) => console.log('Progress:', anim.progress),
  onComplete: (anim) => console.log('Finished')
});

// ❌ v3: DON'T use unprefixed callbacks
// { update: () => {}, complete: () => {} }

📝 Code Formatting Guidelines

ALWAYS Use Single-Line Format for Simple Animations

This is mandatory for readability - Use for animations with ≤4 properties:

// ✅ GOOD - Clean, readable, one line
animate('.element', { x: 250, duration: 1, ease: 'outQuad' });
animate('.box', { opacity: 0.5, scale: 0.8, duration: 0.3 });

// ❌ BAD - Unnecessary multi-line for simple tweens
animate('.element', {
  x: 250,
  duration: 1,
  ease: 'outQuad'
});

Multi-Line Format (Only for Complex Animations)

Use for animations with >4 properties or callbacks:

// Complex animation with callbacks - multi-line is appropriate
animate('.element', {
  x: { to: [0, 100, 50], duration: 2 },
  y: { to: [0, -50, 0], duration: 2 },
  scale: [0, 1.2, 1],
  ease: 'outElastic(1, 0.5)',
  onComplete: () => console.log('Done!')
});

🎨 Common Animation Patterns

Hover Animation (single line per animation)

element.addEventListener('mouseenter', () => animate(element, { scale: 1.1, duration: 0.3, ease: 'outQuad' }));
element.addEventListener('mouseleave', () => animate(element, { scale: 1, duration: 0.3, ease: 'outQuad' }));

Sequential Timeline

const tl = createTimeline({ defaults: { duration: 0.5 } });
tl.add('.step1', { x: 100 })
  .add('.step2', { y: 100 })
  .add('.step3', { scale: 2 });

Scroll-triggered Animation

import { createScrollObserver } from 'animejs';

createScrollObserver({
  target: '.scroll-element',
  root: document.querySelector('.scroll-container'),
  play: () => animate('.element', { x: 250, duration: 1 }),
  visibility: 0.5
});

🔧 Advanced Features

SVG Animations

import { animate, svg } from 'animejs';

// Morph path (single line)
animate('#path1', { d: svg.morphTo('#path2'), duration: 1 });

// Draw SVG line
const drawable = svg.createDrawable('.svg-path');
animate(drawable, { draw: '0% 100%', duration: 2 });

// Motion path (single line for simple usage)
const motionPath = svg.createMotionPath('#motion-path');
animate('.element', { x: motionPath.translateX, y: motionPath.translateY, rotate: motionPath.rotate });

Utility Functions

import { utils } from 'animejs';

// DOM selection
const elements = utils.$('.elements');

// Get current value
const currentX = utils.get('.element', 'translateX');

// Set values immediately
utils.set('.element', { x: 100, opacity: 0.5 });

// Remove animations
utils.remove('.element');

// Math utilities
utils.random(0, 100);
utils.shuffle([1, 2, 3, 4]);
utils.lerp(0, 100, 0.5); // 50
utils.clamp(150, 0, 100); // 100

TypeScript Support

import { animate, createTimeline, JSAnimation, Timeline, AnimationParams, TimelineParams } from 'animejs';

// Single line for simple animations
const animation: JSAnimation = animate('.element', { x: 250, duration: 1 } as AnimationParams);

const timeline: Timeline = createTimeline({ defaults: { duration: 0.8 } } as TimelineParams);

⚡ Performance Tips

1. Use transforms over position properties

   // ✅ Good - uses transform
   animate('.element', { x: 100 });
   
   // ❌ Avoid - triggers layout
   animate('.element', { left: 100 });

2. Batch animations in timelines

   // ✅ Good - single timeline
   const tl = createTimeline();
   elements.forEach(el => tl.add(el, { x: 100 }));
   
   // ❌ Avoid - multiple animations
   elements.forEach(el => animate(el, { x: 100 }));

3. Use will-change CSS property for complex animations

   .animated-element {
     will-change: transform, opacity;
   }

🚫 How to Identify V3 Code (DON'T USE)

If you see ANY of these patterns, it's v3 and MUST be updated:

// All of these are V3 - NEVER USE:
anime({ ... })
anime.timeline()
anime.stagger()
anime.random()
anime.remove()
anime.get()
anime.set()
anime.running
{ targets: '...' }
{ easing: '...' }
{ value: ... }
{ direction: 'alternate' }

💡 AI Code Generation Rules

When asked to create animations with anime.js:

1. ONLY set engine.timeUnit = 's' ONCE in the app's main entry point (App.js, main.js, index.js) - NEVER in components 2. ALWAYS use seconds for all durations (1 = 1 second) 3. ALWAYS format simple animations on ONE LINE 4. ALWAYS start with v4 imports 5. NEVER use anime() function 6. ALWAYS use animate() for animations 7. NEVER include targets property 8. ALWAYS use ease not easing 9. NEVER use value, use to instead 10. ALWAYS prefix callbacks with on 11. NEVER use direction, use alternate and reversed 12. ALWAYS use createTimeline() for timelines 13. PREFER shorthand (x) over explicit (translateX) 14. FORMAT short animations on single line (≤4 properties) 15. NEVER generate v3 syntax under any circumstances

NPM Installation

npm install animejs

Version Check

// Current version: 4.x.x
// If you see any code using anime({ targets: ... }), it's v3 and needs updating!

Design Principles: Beautiful & Right

BEAUTIFUL: Understanding Aesthetic Principles

Study Process

Analyze high-quality designs on Dribbble, Mobbin, Behance. Ask AI to identify:

• Design styles (Memphis, Flat Design, Glassmorphism, Neo-brutalism, Minimalism)
• Layout structures & applications
• Typography systems (font pairing, hierarchy, scaling)
• Color systems (palettes, contrasts, psychology)

Visual Hierarchy

Guide users through interfaces effectively:

• Size: Larger elements draw attention first
• Contrast: High contrast (text/background) boosts readability
• Typography: Use weight, size, style for hierarchy
• Placement: F-pattern (web), Z-pattern (landing pages)
• Spacing: White space improves clarity, reduces cognitive load

Typography Best Practices

• Stick to 2-3 typefaces max
• Clear font hierarchy with proper spacing, sizes, alignment
• Appropriate font sizes for readability across devices
• Short, scannable paragraphs

Color Theory Applications

• Blue: Trust, security, calmness
• Red: Urgency, passion, excitement
• Warm colors: Drive urgency
• Cool colors: Create trust
• Use color intentionally to direct attention & evoke emotion
• Ensure WCAG AA contrast ratios (4.5:1 text, 3:1 large text)

White Space

Not empty—essential for clarity. Proper spacing between sections, buttons, text improves readability & gives visual breathing room.

RIGHT: Ensuring Functionality

Design Systems Research

Search "Figma Design System + [style]" to understand:

• Component architecture (atomic design: atoms → molecules → organisms)
• Layout principles (grid systems, responsive breakpoints)
• UX patterns & interactions

Component Library Standards

• Semantic HTML first (button > div with ARIA roles)
• Built-in accessibility, focus handling, keyboard interaction
• Each component tested for accessibility before adding
• Documentation includes structure, focus order, keyboard expectations, screen reader announcements

Accessibility Requirements

• WCAG 2.1 AA minimum (work toward 2.2)
• Color contrast ratios meet/exceed minimums
• Alt text for images
• Color-blind-friendly palettes
• Keyboard navigation support
• Screen reader compatibility

Testing Protocol

• Automated tools catch 30-50% of issues
• Manual testing crucial for comprehensive coverage
• Test with real users when possible

Design Resources & Tools

Inspiration Platforms

Design Galleries

• Dribbble: High-quality UI/UX designs, trending styles
• Mobbin: Mobile app design patterns, real-world examples
• Behance: Creative portfolios, comprehensive projects
• Awwwards: Award-winning web experiences
• 21st.dev: Component animations, micro-interactions
• CSS Design Awards: Cutting-edge web designs

Design Systems

Search pattern: "Figma Design System + [style name]"

• Material Design (Google)
• Human Interface Guidelines (Apple)
• Carbon Design System (IBM)
• Ant Design
• Shadcn UI
• Atlassian Design System

AI Tools for Design

Generation

• Gemini: Image generation via ai-multimodal skill
• Claude: Design variations, component code

Prompt Structure

Include in prompts:

• Task description
• Preferred design style
• Color palette
• Typography preferences
• Target audience/user story
• Animation specifications

MCP Integrations

Available MCPs

• Chrome MCP: Research designs, analyze trends from Dribbble/Mobbin
• Figma MCP: Code based on community designs
• Freepik MCP: Access stock imagery
• ChatGPT-Image MCP: Image resources
• gallery-dl: Download reference images via bash

Usage

Connect MCPs for enhanced capabilities when researching, analyzing, or implementing designs.

Development Approach

Git Worktrees Strategy

Maintain separate branches for different design style variations during development. Allows parallel exploration of Minimalist, Modern, Glassmorphism interpretations.

Parallel Agents

Use multiple agents to generate design style variations simultaneously, compare approaches.

Documentation Standards

Required Files

Create in ./docs/ directory:

• design-guideline.md: Color patterns, typography, layout principles, component styling, design highlights
• design-story.md: Narrative elements, thematic decisions, user journey considerations

Content

Document:

• Rationale for design decisions
• Style guide (colors, fonts, spacing)
• Component patterns & usage
• Responsive breakpoints
• Accessibility considerations
• Brand alignment

Maintenance

Update during development. Use development rules to remind Claude Code to follow guidelines consistently.

Implementation Guide: Frontend Design Execution

Design Thinking Process

Before coding, understand context and commit to a BOLD aesthetic direction:

Context Analysis

• Purpose: What problem does this interface solve? Who uses it?
• Tone: Pick an extreme direction - brutally minimal, maximalist chaos, retro-futuristic, organic/natural, luxury/refined, playful/toy-like, editorial/magazine, brutalist/raw, art deco/geometric, soft/pastel, industrial/utilitarian
• Constraints: Technical requirements (framework, performance, accessibility)
• Differentiation: What makes this UNFORGETTABLE? What's the one thing someone will remember?

CRITICAL: Choose a clear conceptual direction and execute it with precision. Bold maximalism and refined minimalism both work - the key is intentionality, not intensity.

Frontend Aesthetics Guidelines

Typography

• Choose fonts that are beautiful, unique, and interesting
• Avoid generic fonts like Arial and Inter
• Opt for distinctive choices that elevate aesthetics
• Use unexpected, characterful font choices
• Pair a distinctive display font with a refined body font

Color & Theme

• Commit to a cohesive aesthetic
• Use CSS variables for consistency
• Dominant colors with sharp accents outperform timid, evenly-distributed palettes
• Create atmosphere and depth rather than defaulting to solid colors

Motion & Animation

• Use animations for effects and micro-interactions
• Prioritize CSS-only solutions for HTML
• Use Motion library for React when available
• Use anime.js for animations: See references/animejs.md
• Focus on high-impact moments: one well-orchestrated page load with staggered reveals (animation-delay) creates more delight than scattered micro-interactions
• Use scroll-triggering and hover states that surprise

Spatial Composition

• Unexpected layouts
• Asymmetry
• Overlap
• Diagonal flow
• Grid-breaking elements
• Generous negative space OR controlled density

Backgrounds & Visual Details

• Create atmosphere and depth
• Add contextual effects and textures that match the overall aesthetic
• Apply creative forms: gradient meshes, noise textures, geometric patterns, layered transparencies, dramatic shadows, decorative borders, custom cursors, grain overlays

Anti-Patterns: Avoid Generic AI Aesthetics

NEVER use:

• Overused font families (Inter, Roboto, Arial, system fonts)
• Cliched color schemes (particularly purple gradients on white backgrounds)
• Predictable layouts and component patterns
• Cookie-cutter design that lacks context-specific character

Variation Principle: Interpret creatively and make unexpected choices that feel genuinely designed for the context. No design should be the same. Vary between light and dark themes, different fonts, different aesthetics. NEVER converge on common choices (Space Grotesk, for example) across generations.

Implementation Complexity Matching

Match implementation complexity to the aesthetic vision:

• Maximalist designs: Need elaborate code with extensive animations and effects
• Minimalist/refined designs: Need restraint, precision, and careful attention to spacing, typography, and subtle details
• Elegance: Comes from executing the vision well

Code Quality Standards

Implement working code that is:

• Production-grade and functional
• Visually striking and memorable
• Cohesive with a clear aesthetic point-of-view
• Meticulously refined in every detail

Remember: Claude is capable of extraordinary creative work. Don't hold back, show what can truly be created when thinking outside the box and committing fully to a distinctive vision.

Micro-Interactions: Satisfying Experience

SATISFYING: Adding Micro-Interactions

Duration Guidelines

• General micro-interactions: 150-300ms (avoid interrupting flow)
• Button presses: Start within 16ms of click
• Standard animations: 200-500ms
• UI motions: 0.5-2s typically
• Rule: A tenth of a second makes big difference; half second wrong feels jarring

Basic Effects

• Fade: Smooth opacity transitions
• Slide: Directional movement (left/right/up/down)
• Scale: Size changes (grow/shrink)
• Rotate: Angular transformations
• Sequential timing with 0.1s delays between elements

Easing Curves

Linear motion = robotic. Use easing for natural feel:

Ease-out (starts fast, slows down):

• Best for: Elements entering screen
• Makes animation feel responsive
• Allows eye time to focus as element settles
• Most common for UI micro-interactions

Ease-in (starts slow, speeds up):

• Best for: Elements leaving screen
• Natural exit motion

Spring/bounce:

• Playful, energetic feel
• Use sparingly for emphasis

Cubic-bezier:

• Fine-tuned control over motion curves
• Custom easing for specific needs

Motion Characteristics

• Follow real-world physics (objects speed up when starting, slow down when stopping)
• Subtle curves for micro-interactions
• Bolder curves for attention-grabbing transitions
• Always have purpose—guide users or give feedback

Performance

• Aim for smooth 60fps
• Prefer hardware-accelerated properties (transforms, opacity)
• Avoid fancy effects causing frame drops or battery drain
• Provide motion-reduced alternatives for accessibility

Resources

Study 21st.dev for component animations & subtle effects worth emulating.

Storytelling Design: Peak Experience

PEAK: Storytelling Through Design

Narrative Elements

Elevate designs by incorporating story-driven interactions:

• Parallax effects: Different scroll speeds create depth
• Particle systems: Dynamic, living background elements
• Thematic consistency: Every element reinforces the narrative
• Progressive disclosure: Reveal information as user explores

Key Principle

"Too much of anything isn't good"—use restraint. Peak moments should be intentional, not overwhelming.

Implementation Approaches

Scroll-Based Storytelling:

• Reveal content in meaningful sequences
• Use scroll position to trigger animations
• Create depth with parallax layers
• Build anticipation through pacing

Interactive Elements:

• Hover states that reveal additional context
• Click interactions that unfold stories
• Drag interactions that manipulate narrative elements
• Gesture-based reveals on mobile

Visual Narrative:

• Hero sections that set tone
• Consistent visual metaphors throughout
• Imagery that supports the message
• Typography that reinforces brand personality

Technical Considerations

• Ensure storytelling enhances, not hinders, usability
• Maintain performance (60fps) during narrative elements
• Provide accessibility alternatives
• Test across devices & screen sizes
• Graceful degradation for older browsers

Inspiration Sources

Study award-winning sites like:

• Awwwards.com winners
• CSS Design Awards
• FWA (Favourite Website Awards)
• Brand campaign sites

Balance

Strong storytelling + solid functionality = peak experience. Neither should sacrifice the other.

Workflows: Design Analysis & Generation

Workflow 1: Capture & Analyze Inspiration

Purpose: Extract design guidelines from inspiration websites.

Process Steps

1. Browse Inspiration Sites

• Dribbble, Mobbin, Behance, Awwwards
• Focus on high-quality, professionally designed examples

2. Capture Screenshots

• Use chrome-devtools skill to capture full-screen screenshots (not full page)
• Capture multiple examples for pattern recognition

3. Analyze with AI Multimodal

• Use ai-multimodal skill to analyze screenshots
• Extract comprehensive design information:
• Design style (Minimalism, Glassmorphism, Neo-brutalism, etc.)
• Layout structure & grid systems
• Typography system & hierarchy
• IMPORTANT: Predict font name (Google Fonts) and font size - don't default to Inter or Poppins
• Color palette with hex codes
• Visual hierarchy techniques
• Component patterns & styling
• Micro-interactions
• Accessibility considerations
• Overall aesthetic quality rating (1-10)

4. Document Findings

• Use project design guidelines templates
• Create structured documentation for reference

Workflow 2: Generate & Iterate Design Images

Purpose: Create aesthetically pleasing design images through iteration.

Process Steps

1. Define Design Prompt

• Specify style, colors, typography
• Define target audience
• Include animation specifications

2. Generate Initial Design

• Use ai-multimodal skill to generate design images with Gemini API
• Create multiple variations for comparison

3. Evaluate Aesthetic Quality

• Use ai-multimodal skill to analyze output images
• Score aesthetic quality objectively (1-10 scale)
• Identify specific strengths and weaknesses

4. Iterate Until Standards Met

• If score < 7/10 or fails professional standards:
• Identify specific weaknesses (color, typography, layout, spacing, hierarchy)
• Refine prompt with targeted improvements
• Regenerate with ai-multimodal
• Use media-processing skill for refinements (resize, crop, filters, composition)
• Repeat until aesthetic standards met (score >= 7/10)

5. Document Final Design

• Save final design decisions
• Document rationale for key choices
• Create reference documentation using templates

Quality Standards

• Minimum Score: 7/10 for aesthetic quality
• Professional Standards: Must meet industry best practices
• Accessibility: Must pass WCAG AA standards
• Consistency: Must align with overall design system

Related Skills Integration

• chrome-devtools: Browser automation, screenshot capture
• ai-multimodal: Image generation and analysis
• media-processing: Image refinement and optimization