SKILL.md
$2b
Tone Options (Pick an Extreme)
Choose a clear aesthetic direction and execute with precision:
- Brutally minimal - stripped to essence, bold typography, vast whitespace
- Maximalist chaos - layered, dense, visually rich, controlled disorder
- Retro-futuristic - vintage meets sci-fi, nostalgic tech aesthetics
- Organic/natural - soft edges, earthy colors, nature-inspired textures
- Luxury/refined - elegant spacing, premium typography, subtle details
- Playful/toy-like - bright colors, rounded shapes, delightful interactions
- Editorial/magazine - strong typography hierarchy, asymmetric layouts
- Brutalist/raw - exposed structure, harsh contrasts, intentionally rough
- Art deco/geometric - bold patterns, metallic accents, symmetric elegance
- Soft/pastel - gentle gradients, muted tones, calming atmosphere
- Industrial/utilitarian - functional, no-nonsense, mechanical precision
After Getting Context
- Commit fully to the chosen direction - no half measures
- Present 2-3 alternative approaches with trade-offs
- Then implement with precision: production-grade, visually striking, memorable
Foundational Design Principles
Stand Out From Generic Patterns
NEVER Use These AI-Generated Aesthetics:
- Fonts: Inter, Roboto, Arial, system fonts as primary choice, Space Grotesk (overused by AI)
- Colors: Generic SaaS blue (#3B82F6), purple gradients on white backgrounds
- Patterns: Cookie-cutter layouts, predictable component arrangements
- Effects: Glass morphism, Apple design mimicry, liquid/blob backgrounds
- Overall: Anything that looks "Claude-generated" or machine-made
Instead, Create Atmosphere:
- Suggest photography, patterns, textures over flat solid colors
- Apply gradient meshes, noise textures, geometric patterns
- Use layered transparencies, dramatic shadows, decorative borders
- Consider custom cursors, grain overlays, contextual effects
- Think beyond typical patterns - you can step off the written path
Draw Inspiration From:
- Modern landing pages (Perplexity, Comet Browser, Dia Browser)
- Framer templates and their innovative approaches
- Leading brand design studios
- Historical design movements (Bauhaus, Otl Aicher, Braun) - but as inspiration, not imitation
- Beautiful background animations (CSS, SVG) - slow, looping, subtle
Visual Interest Strategies:
- Unique color pairs that aren't typical
- Animation effects that feel fresh
- Background patterns that add depth without distraction
- Typography combinations that create contrast
- Visual assets that tell a story
Core Design Philosophy
-
Simplicity Through Reduction
- Identify the essential purpose and eliminate distractions
- Begin with complexity, then deliberately remove until reaching the simplest effective solution
- Every element must justify its existence
-
Material Honesty
- Digital materials have unique properties - embrace them
- Buttons communicate affordance through color, spacing, typography, AND shadows when intentional
- Cards can use borders, background differentiation, OR dramatic shadows for depth
- Animations follow real-world physics principles adapted to digital responsiveness
Examples:
- Clickable: Use distinct colors, hover state changes, cursor feedback, subtle lift effects
- Containers: Use borders, background shifts, generous padding, OR shadow depth
- Hierarchy: Use scale, weight, spacing, AND elevation when it serves the aesthetic
-
Functional Layering
- Create hierarchy through typography scale, color contrast, and spatial relationships
- Layer information conceptually (primary → secondary → tertiary)
- Use shadows and gradients INTENTIONALLY when they serve the aesthetic direction
- Embrace functional depth: modals over content, dropdowns over UI
- Avoid: glass morphism, Apple mimicry (but shadows/gradients are tools, not enemies)
-
Obsessive Detail
- Consider every pixel, interaction, and transition
- Excellence emerges from hundreds of small, intentional decisions
- Balance: Details should serve simplicity, not complexity
- When detail conflicts with clarity, clarity wins
-
Coherent Design Language
- Every element should visually communicate its function
- Elements should feel part of a unified system
- Nothing should feel arbitrary
-
Invisibility of Technology
- The best technology disappears
- Users should focus on content and goals, not on understanding the interface
What This Means in Practice
Color Usage:
- Base palette: 4-5 neutral shades (backgrounds, borders, text)
- Accent palette: 1-3 bold colors (CTAs, status, emphasis)
- Neutrals are slightly desaturated, warm or cool based on brand intent
- Accents are saturated enough to create clear contrast
Typography:
- Headlines: Emotional, attention-grabbing, UNEXPECTED (personality over pure legibility)
- Body/UI: Functional, highly legible (clarity over expression)
- 2-3 typefaces maximum, but make them CHARACTERFUL and distinctive
- Clear mathematical scale (e.g., 1.25x between sizes)
- NEVER default to Inter, Roboto, or Space Grotesk - find unique fonts
Animation:
- Purposeful: Guides attention, establishes relationships, provides feedback
- Subtle: Felt rather than seen (100-300ms for most interactions)
- Physics-informed: Natural easing, appropriate mass/momentum
Spacing:
- Generous negative space creates clarity and breathing room
- Mathematical relationships (e.g., 4px base, 8/16/24/32/48px scale)
- Consistent application creates visual rhythm
Design Decision Checklist
Before presenting any design, verify:
- Purpose: Does every element serve a clear function?
- Hierarchy: Is visual importance aligned with content importance?
- Consistency: Do similar elements look and behave similarly?
- Accessibility: Does it meet WCAG AA standards? (contrast, touch targets, keyboard nav)
- Responsiveness: Does it work on mobile, tablet, desktop?
- Uniqueness: Does this break from generic SaaS patterns?
- Approval: Have I asked before implementing colors, fonts, sizes, layouts?
Design System Framework:
For understanding what's fixed (universal rules), project-specific (brand personality), and adaptable (context-dependent) in your design system, think of a design system.
Visual Design Standards
Color & Contrast
Color System Architecture:
Every interface needs two color roles:
-
Base/Neutral Palette (4-5 colors):
- Backgrounds (lightest)
- Surface colors (cards, inputs)
- Borders and dividers
- Text (darkest)
- Use slightly desaturated, warm or cool greys based on brand
-
Accent Palette (1-3 colors):
- Primary action (CTA buttons)
- Status indicators (success, warning, error, info)
- Focus/hover states
- Use saturated colors for clear contrast against neutrals
Palette Structure Example:
Neutrals: slate-50, slate-100, slate-300, slate-700, slate-900
Accents: teal-500 (primary), amber-500 (warning), red-500 (error)
Color Application Rules:
- Backgrounds: Lightest neutral (slate-50 or white)
- Text: Darkest neutral for primary text (slate-900), mid-tone for secondary (slate-600)
- Buttons (primary): Accent color with white text
- Buttons (secondary): Neutral with border and dark text
- Status indicators: Specific accent (green=success, red=error, amber=warning, blue=info)
- Interactive states:
- Hover: Darken by 10-15% or shift hue slightly
- Focus: Use ring/outline in accent color
- Disabled: Reduce opacity to 40-50% and remove hover effects
Color Relationships:
Choose warm or cool intentionally based on brand:
- Warm greys (beige/brown undertones): Organic, approachable, trustworthy
- Cool greys (blue undertones): Modern, tech-forward, professional
Accent colors should have clear contrast with both:
- Light backgrounds (for buttons on white)
- Dark text (if used as backgrounds for white text)
Intentional Color Usage:
- Every color must serve a purpose (hierarchy, function, status, or action)
- Avoid decorative colors that don't communicate meaning
- Maintain consistency: same color = same meaning throughout
Accessibility:
- Ensure sufficient contrast for color-blind users
- Follow WCAG 2.1 AA: minimum 4.5:1 for normal text, 3:1 for large text
- Don't rely on color alone to convey information (add icons or labels)
Unique Color Strategy:
To stand out from generic patterns:
- NEVER use default SaaS blue (#3B82F6) or purple gradients on white
- Use unexpected neutrals: warm greys, soft off-whites, deep charcoals, rich blacks
- Pair neutrals with distinctive accents: terracotta + charcoal, sage + navy, coral + slate
- Dominant colors with SHARP accents outperform timid, evenly-distributed palettes
- Test combinations against "does this look AI-generated?" filter
- Vary between light and dark themes - no design should look the same
Create Atmosphere with Color:
- Gradient meshes for depth and visual interest
- Noise textures and grain overlays for tactile feel
- Layered transparencies for dimension
- Dramatic shadows for emphasis and drama
Typography Excellence
Typography Philosophy:
Typography is a primary design element that conveys personality and hierarchy.
Functional vs Emotional Typography:
- Headlines/Display: Prioritize emotion, personality, attention (legibility secondary)
- Body Text: Prioritize legibility, reading comfort, accessibility
- UI/Labels: Prioritize clarity, scannability, consistency
Font Selection:
- Use 2-3 typefaces maximum, but make them UNEXPECTED and characterful
- Limit to 3 weights per typeface (e.g., Regular 400, Medium 500, Bold 700)
- Prefer variable fonts for fine-tuned control and performance
NEVER Use These Fonts as Primary:
- Inter (overused by AI and generic SaaS)
- Roboto (too generic)
- Arial/Helvetica (default fallback vibes)
- Space Grotesk (AI generation favorite)
- System fonts as primary choice (only as fallback)
Font Version Usage:
- Display version: Headlines and hero text only - BE BOLD
- Text version: Paragraphs and long-form content - legibility matters
- Caption/Micro: Small UI labels (1-2 lines, non-critical info)
Find Distinctive Fonts:
- Google Fonts for web - but dig deeper than page 1
- Type foundries for unique options
- Choose fonts that serve your CHOSEN AESTHETIC DIRECTION
- Pair distinctive display font with refined body font
Typographic Scale:
Use mathematical relationships for size hierarchy:
- Ratio: Major third (1.25x) for moderate contrast, Perfect fourth (1.333x) for dramatic
- Base size: 16px (1rem) for body text
- Example scale (1.25x):
xs: 0.64rem (10px)
sm: 0.8rem (13px)
base: 1rem (16px)
lg: 1.25rem (20px)
xl: 1.563rem (25px)
2xl: 1.953rem (31px)
3xl: 2.441rem (39px)
4xl: 3.052rem (49px)
5xl: 3.815rem (61px)
Typographic Hierarchy:
- Create clear visual distinction between levels
- Headlines, subheadings, body, captions should each have distinct size/weight
- Use combination of size, weight, and color for hierarchy
Spacing & Readability:
- Line height: 1.5x font size for body text (e.g., 16px text = 24px line-height)
- Line length: 45-75 characters optimal for readability (60-70 ideal)
- Paragraph spacing: 1-1.5em between paragraphs
- Letter spacing (tracking):
- Larger text (headlines): Slightly tighter (-0.02em to -0.05em)
- Normal text (body): Default (0)
- Small text (captions): Slightly looser (+0.01em to +0.03em)
- General rule: As size increases, reduce tracking; as size decreases, increase tracking
Font Pairing Logic:
When using multiple typefaces, create contrast through:
- Category contrast: Serif + Sans-serif (classic, clear distinction)
- Weight contrast: Light + Bold (dynamic, energetic)
- Personality contrast: Geometric + Humanist (modern + warm)
Examples:
- Serif headlines + Sans body (editorial, trustworthy)
- Display headlines + System body (distinctive + efficient)
- Bold sans headlines + Light sans body (modern, clean)
UI Typography:
Specific guidance for interface elements:
- Button text: Semi-Bold (600), 14-16px, consistent casing (all-caps OR title case)
- Form labels: Regular (400), 14px, positioned above input
- Form input text: Regular (400), 16px minimum (prevents iOS zoom on focus)
- Placeholder text: Light (300) or desaturated color, same size as input
- Error messages: Regular (400), 12-14px, color-coded (red-ish)
Responsive Typography:
Scale type sizes across breakpoints:
// Example with Tailwind
<h1 className="text-3xl md:text-4xl lg:text-5xl">
Responsive Headline
</h1>
// Or with CSS clamp (fluid)
h1 {
font-size: clamp(2rem, 5vw, 4rem);
}
Reduce sizes on mobile (20-30% smaller than desktop)
Reduce hierarchy levels on small screens (fewer distinct sizes)
Layout & Spatial Design
Compositional Balance:
- Every screen should feel balanced
- Pay attention to visual weight and negative space
- Use generous negative space to focus attention
- Add sufficient margins and paddings for professional, spacious look
Grid Discipline:
- Maintain consistent underlying grid system
- Create sense of order while allowing meaningful exceptions
- Use grid/flex wrappers with
gapfor spacing
- Prioritize wrappers over direct margins/padding on children
Spatial Relationships:
- Group related elements through proximity, alignment, and shared attributes
- Use size, color, and spacing to highlight important elements
- Guide user focus through visual hierarchy
Attention Guidance:
- Design interfaces that guide user attention effectively
- Avoid cluttered interfaces where elements compete
- Create clear paths through the content
Interaction Design
Motion Specification:
For detailed motion specs, see MOTION-SPEC.md (easing curves, duration tables, state-specific animations, implementation patterns).
User Experience Patterns
Core UX Principles:
-
Direct Manipulation
- Users interact directly with content, not through abstract controls
- Examples:
- Drag & drop to reorder items (not up/down buttons)
- Inline editing (click to edit, not separate form)
- Sliders for ranges (not numeric input with +/-)
- Pinch/zoom gestures on mobile (not +/- buttons)
-
Immediate Feedback
- Every interaction provides instantaneous visual feedback (within 100ms)
- Types of feedback:
- Visual: Button pressed state, hover effects, color changes
- Haptic: Vibration on mobile (submit, error, success)
- Audio: Subtle sounds for critical actions (optional, user-controlled)
- Loading: Skeleton screens, spinners for >300ms operations
- Success: Checkmarks, green highlights, toast notifications
- Error: Red highlights, inline error messages, shake animations
-
Consistent Behavior
- Similar-looking elements behave similarly
- Examples:
- Visual consistency: All primary buttons have same colors, sizes, hover states
- Behavioral consistency: All modals close via X button, ESC key, and outside click
- Interaction consistency: All drag targets have same hover state and drop feedback
- Pattern consistency: All forms validate on blur and submit
-
Forgiveness
- Make errors difficult, but recovery easy
- Prevention strategies:
- Disable invalid actions (grey out unavailable buttons)
- Validate inputs inline (before submission)
- Confirm destructive actions (delete, overwrite)
- Auto-save in background (drafts, progress)
- Recovery strategies:
- Undo/redo for all state changes
- Soft deletes (trash/archive before permanent delete)
- Clear error messages with actionable fixes
- Preserve user input on errors (don't clear forms)
-
Progressive Disclosure
- Reveal details as needed rather than overwhelming users
- Levels of disclosure:
- Summary: Show essential info by default (card title, price, rating)
- Details: Expand to show more info (description, specs, reviews)
- Advanced: Hide complex options behind "Advanced settings" toggle
- Examples:
- Accordion: Start collapsed, expand on click
- Search filters: Show 3-5 common filters, hide rest behind "More filters"
- Settings: Basic settings visible, advanced behind "Show advanced"
Modern UX Patterns:
-
Conversational Interfaces
Prioritize natural language interaction where appropriate:
Four types:
- Pure chat: Full conversation (AI assistants, support bots)
- Command palette: Text-based shortcuts (Cmd+K, search everywhere)
- Smart search: Natural language queries (search "meetings next week" vs filtering)
- Form alternatives: Conversational data collection ("What's your name?" vs form fields)
When to use:
- Complex searches with multiple variables
- Task guidance (wizards, onboarding)
- Contextual help
- Quick actions (command palette)
When NOT to use:
- Simple forms (just use inputs)
- Precise control interfaces (design tools, dashboards)
- High-frequency repetitive tasks
-
Adaptive Layouts
Respond to user context automatically:
- Time-based: Dark mode at night, light during day
- Device-based: Simplified UI on mobile, full features on desktop
- Connection-based: Reduce images/video on slow connections
- Usage-based: Prioritize frequent actions, hide rarely-used features
Examples:
- Auto dark/light mode based on time or system preference
- Simplified mobile navigation (hamburger menu) vs full desktop nav
- Collapsed sidebar on small screens, expanded on large
-
Bold Visual Expression
Aesthetic flexibility based on chosen direction:
- Shadows ALLOWED and encouraged when intentional (dramatic shadows, soft elevation)
- Gradients ALLOWED for depth, accents, backgrounds, and atmosphere
- NO glass morphism effects (this is the one banned technique)
- NO Apple design mimicry (find your own voice)
- Focus on typography, color, spacing, AND visual effects to create hierarchy
- Create atmosphere: gradient meshes, noise textures, grain overlays, dramatic lighting
Navigation:
- Clear structure with intuitive navigation menus
- Implement breadcrumbs for deep hierarchies (more than 2 levels)
- Use standard UI patterns to reduce learning curve (hamburger menu, tab bars)
- Ensure predictable behavior (back button works, links look clickable)
- Maintain navigation context (highlight current page, preserve scroll position)
Styling Implementation
Component Library & Tools
Component Library:
- Strongly prefer shadcn components (v4, pre-installed in
@/components/ui)
- Import individually:
import { Button } from "@/components/ui/button";
- Use over plain HTML elements (
<Button>over<button>)
- Avoid creating custom components with names that clash with shadcn
Styling Engine:
- Use Tailwind utility classes exclusively
- Adhere to theme variables in
index.cssvia CSS custom properties
- Map variables in
@theme(seetailwind.config.js)
- Use inline styles or CSS modules only when absolutely necessary
Icons:
- Use
@phosphor-icons/reactfor buttons and inputs
- Example:
import { Plus } from "@phosphor-icons/react"; <Plus />
- Use color for plain icon buttons
- Don't override default
sizeorweightunless requested
Notifications:
- Use
sonnerfor toasts
- Example:
import { toast } from 'sonner'
Loading States:
- Always add loading states, spinners, placeholder animations
- Use skeletons until content renders
Layout Implementation
Spacing Strategy:
- Use grid/flex wrappers with
gapfor spacing
- Prioritize wrappers over direct margins/padding on children
- Nest wrappers as needed for complex layouts
Conditional Styling:
- Use ternary operators or clsx/classnames utilities
- Example:
className={clsx('base-class', { 'active-class': isActive })}
Responsive Design
Fluid Layouts:
- Use relative units (%, em, rem) instead of fixed pixels
- Implement CSS Grid and Flexbox for flexible layouts
- Design mobile-first, then scale up
Media Queries:
- Use breakpoints based on content needs, not specific devices
- Test across range of devices and orientations
Touch Targets:
- Minimum 44x44 pixels for interactive elements
- Provide adequate spacing between touch targets
- Consider hover states for desktop, focus states for touch/keyboard
Performance:
- Optimize assets for mobile networks
- Use CSS animations over JavaScript
- Implement lazy loading for images and videos
Accessibility Standards
Core Requirements:
- Follow WCAG 2.1 AA guidelines
- Ensure keyboard navigability for all interactive elements
- Minimum touch target size: 44×44px
- Use semantic HTML for screen reader compatibility
- Provide alternative text for images and non-text content
Implementation Details:
- Use descriptive variable and function names
- Event functions: prefix with "handle" (handleClick, handleKeyDown)
- Add accessibility attributes:
tabindex="0"for custom interactive elements
aria-labelfor buttons without text
roleattributes when semantic HTML isn't sufficient
- Ensure logical tab order
- Provide visible focus states
Design Process & Testing
Design Workflow
-
Understand Context:
- What problem are we solving?
- Who are the users and when will they use this?
- What are the success criteria?
-
Explore Options:
- Present 2-3 alternative approaches
- Explain trade-offs of each option
- Ask which direction resonates
-
Implement Iteratively:
- Start with structure and hierarchy
- Add visual polish progressively
- Test at each stage
-
Validate:
- Use playwright MCP to test visual changes
- Check across different screen sizes
- Verify accessibility
Testing Checklist
Visual Testing:
- Use playwright MCP when available for automated testing
- Check responsive behavior at common breakpoints
- Verify touch targets on mobile
- Test with different content lengths (short, long, edge cases)
Accessibility Testing:
- Test keyboard navigation
- Verify screen reader compatibility
- Check color contrast ratios
- Ensure focus states are visible
Cross-Device Testing:
- Test on actual devices, not just emulators
- Check different browsers (Chrome, Firefox, Safari)
- Verify touch interactions on mobile
- Test landscape and portrait orientations
Examples
Example 1: Designing a Button
Initial Question to Ask:
Before I implement this button, I have a few design questions:
1. What's the primary action you want to emphasize?
2. Do you have brand colors in mind, or should I suggest options?
3. What emotion should this button convey? (urgent, calm, playful, professional)
After Getting Approval, Implementation:
import { Button } from "@/components/ui/button";
import { ArrowRight } from "@phosphor-icons/react";
<Button
className="bg-slate-800 hover:bg-slate-700 text-white px-6 py-3 rounded-lg transition-colors duration-200"
>
Get Started
<ArrowRight className="ml-2" />
</Button>
Example 2: Typography Hierarchy
Question First:
For this content hierarchy, I'm thinking:
- Headline: Large, bold, attention-grabbing
- Subheading: Medium, regular weight
- Body: Smaller, optimized for reading
Should we go bold and contemporary, or subtle and refined?
Implementation After Approval:
<div className="space-y-4">
<h1 className="text-5xl font-bold tracking-tight text-slate-900">
Headline Here
</h1>
<h2 className="text-2xl text-slate-600">
Supporting subheading
</h2>
<p className="text-base leading-relaxed text-slate-700">
Body text optimized for readability with proper line height.
</p>
</div>
Example 3: Unique Color Palette Suggestion
Presenting Options:
I'd like to suggest three color directions that break from typical SaaS patterns:
1. **Warm Earth Tones**
- Base: Warm grey (#E8E2DC)
- Accent: Terracotta (#C86E4B)
- For: Organic, trustworthy feel
2. **Cool Midnight**
- Base: Deep navy (#1A2332)
- Accent: Cyan (#4ECDC4)
- For: Modern, tech-forward feel
3. **Soft Pastels**
- Base: Soft pink (#FFE5E5)
- Accent: Sage green (#9DB5A4)
- For: Calm, approachable feel
Which direction feels right for your brand?
Common Patterns to Avoid
❌ NEVER:
- Use Inter, Roboto, Arial, Space Grotesk as primary fonts
- Use generic SaaS blue (#3B82F6) or purple gradients on white
- Copy Apple's design language or use glass morphism
- Create cookie-cutter layouts that look AI-generated
- Skip asking about context before designing
- Converge on common choices across generations (vary everything!)
- Use animations that delay user actions
- Create cluttered interfaces where elements compete
✅ ALWAYS:
- Ask about purpose, tone, constraints, differentiation FIRST
- Then commit BOLDLY to a distinctive aesthetic direction
- Use unexpected, characterful typography choices
- Create atmosphere: shadows, gradients, textures, grain (when intentional)
- Dominant colors with sharp accents (not timid, evenly-distributed palettes)
- Provide immediate feedback for interactions
- Test with real devices
- Validate accessibility (it enables creativity, not limits it)
- Remember: Claude is capable of extraordinary creative work - don't hold back!
Version History
- v2.0.0 (2025-11-22): Creative liberation update - bold aesthetics, shadows/gradients allowed, Design Thinking protocol
- v1.0.0 (2025-10-18): Initial release with comprehensive UI/UX design guidance
References
For additional context, see:
- Anthropic Frontend Aesthetics Cookbook: https://github.com/anthropics/claude-cookbooks/blob/main/coding/prompting_for_frontend_aesthetics.ipynb
- WCAG 2.1 Guidelines: https://www.w3.org/WAI/WCAG21/quickref/
- Google Fonts: https://fonts.google.com/
- Tailwind CSS Docs: https://tailwindcss.com/docs
- Shadcn UI Components: https://ui.shadcn.com/
Progressive Disclosure Files:
- ACCESSIBILITY.md - Accessibility essentials (WCAG AA baseline)
- MOTION-SPEC.md - Animation timing and easing
- RESPONSIVE-DESIGN.md - Mobile-first breakpoints and patterns