adapt

name	adhoc_design_build
description	Merged design build skill set: adaptation, layout, color, typography, motion, emphasis, and expressive implementation.

Ad-hoc Design Build

This file is a grouped copy of the source bundle from C:\Users\jan.papousek\Downloads\impeccable-style-universal\.agents\skills, focused on designing and implementing user interfaces.

Vault Integration Notes

• Follow this vault's AGENTS.md, SOUL.md, and MEMORY.md first.
• Inspect relevant local notes before design work, especially project notes under 30_Projects/.
• Where the source bundle says to persist design context in .impeccable.md or other external tool files, persist that context in the relevant vault project note or project snapshot instead.
• Keep outputs and notes Obsidian-friendly, and preserve established design systems when working inside an existing product.

Source Skill: adapt

---

name: adapt description: Adapt designs to work across different screen sizes, devices, contexts, or platforms. Ensures consistent experience across varied environments. user-invokable: true argument-hint: [TARGET=] [CONTEXT=]

Adapt existing designs to work effectively across different contexts - different screen sizes, devices, platforms, or use cases.

MANDATORY PREPARATION

Use the design-foundation skill — it contains design principles, anti-patterns, and the Context Gathering Protocol. Follow the protocol before proceeding — if no design context exists yet, you MUST run teach-impeccable first. Additionally gather: target platforms/devices and usage contexts.

---

Assess Adaptation Challenge

Understand what needs adaptation and why:

1. Identify the source context:

   • What was it designed for originally? (Desktop web? Mobile app?)
   • What assumptions were made? (Large screen? Mouse input? Fast connection?)
   • What works well in current context?

2. Understand target context:

   • Device: Mobile, tablet, desktop, TV, watch, print?
   • Input method: Touch, mouse, keyboard, voice, gamepad?
   • Screen constraints: Size, resolution, orientation?
   • Connection: Fast wifi, slow 3G, offline?
   • Usage context: On-the-go vs desk, quick glance vs focused reading?
   • User expectations: What do users expect on this platform?

3. Identify adaptation challenges:

   • What won't fit? (Content, navigation, features)
   • What won't work? (Hover states on touch, tiny touch targets)
   • What's inappropriate? (Desktop patterns on mobile, mobile patterns on desktop)

CRITICAL: Adaptation is not just scaling - it's rethinking the experience for the new context.

Plan Adaptation Strategy

Create context-appropriate strategy:

Mobile Adaptation (Desktop → Mobile)

Layout Strategy:

• Single column instead of multi-column
• Vertical stacking instead of side-by-side
• Full-width components instead of fixed widths
• Bottom navigation instead of top/side navigation

Interaction Strategy:

• Touch targets 44x44px minimum (not hover-dependent)
• Swipe gestures where appropriate (lists, carousels)
• Bottom sheets instead of dropdowns
• Thumbs-first design (controls within thumb reach)
• Larger tap areas with more spacing

Content Strategy:

• Progressive disclosure (don't show everything at once)
• Prioritize primary content (secondary content in tabs/accordions)
• Shorter text (more concise)
• Larger text (16px minimum)

Navigation Strategy:

• Hamburger menu or bottom navigation
• Reduce navigation complexity
• Sticky headers for context
• Back button in navigation flow

Tablet Adaptation (Hybrid Approach)

Layout Strategy:

• Two-column layouts (not single or three-column)
• Side panels for secondary content
• Master-detail views (list + detail)
• Adaptive based on orientation (portrait vs landscape)

Interaction Strategy:

• Support both touch and pointer
• Touch targets 44x44px but allow denser layouts than phone
• Side navigation drawers
• Multi-column forms where appropriate

Desktop Adaptation (Mobile → Desktop)

Layout Strategy:

• Multi-column layouts (use horizontal space)
• Side navigation always visible
• Multiple information panels simultaneously
• Fixed widths with max-width constraints (don't stretch to 4K)

Interaction Strategy:

• Hover states for additional information
• Keyboard shortcuts
• Right-click context menus
• Drag and drop where helpful
• Multi-select with Shift/Cmd

Content Strategy:

• Show more information upfront (less progressive disclosure)
• Data tables with many columns
• Richer visualizations
• More detailed descriptions

Print Adaptation (Screen → Print)

Layout Strategy:

• Page breaks at logical points
• Remove navigation, footer, interactive elements
• Black and white (or limited color)
• Proper margins for binding

Content Strategy:

• Expand shortened content (show full URLs, hidden sections)
• Add page numbers, headers, footers
• Include metadata (print date, page title)
• Convert charts to print-friendly versions

Email Adaptation (Web → Email)

Layout Strategy:

• Narrow width (600px max)
• Single column only
• Inline CSS (no external stylesheets)
• Table-based layouts (for email client compatibility)

Interaction Strategy:

• Large, obvious CTAs (buttons not text links)
• No hover states (not reliable)
• Deep links to web app for complex interactions

Implement Adaptations

Apply changes systematically:

Responsive Breakpoints

Choose appropriate breakpoints:

• Mobile: 320px-767px
• Tablet: 768px-1023px
• Desktop: 1024px+
• Or content-driven breakpoints (where design breaks)

Layout Adaptation Techniques

• CSS Grid/Flexbox: Reflow layouts automatically
• Container Queries: Adapt based on container, not viewport
• clamp(): Fluid sizing between min and max
• Media queries: Different styles for different contexts
• Display properties: Show/hide elements per context

Touch Adaptation

• Increase touch target sizes (44x44px minimum)
• Add more spacing between interactive elements
• Remove hover-dependent interactions
• Add touch feedback (ripples, highlights)
• Consider thumb zones (easier to reach bottom than top)

Content Adaptation

• Use display: none sparingly (still downloads)
• Progressive enhancement (core content first, enhancements on larger screens)
• Lazy loading for off-screen content
• Responsive images (srcset, picture element)

Navigation Adaptation

• Transform complex nav to hamburger/drawer on mobile
• Bottom nav bar for mobile apps
• Persistent side navigation on desktop
• Breadcrumbs on smaller screens for context

IMPORTANT: Test on real devices, not just browser DevTools. Device emulation is helpful but not perfect.

NEVER:

• Hide core functionality on mobile (if it matters, make it work)
• Assume desktop = powerful device (consider accessibility, older machines)
• Use different information architecture across contexts (confusing)
• Break user expectations for platform (mobile users expect mobile patterns)
• Forget landscape orientation on mobile/tablet
• Use generic breakpoints blindly (use content-driven breakpoints)
• Ignore touch on desktop (many desktop devices have touch)

Verify Adaptations

Test thoroughly across contexts:

• Real devices: Test on actual phones, tablets, desktops
• Different orientations: Portrait and landscape
• Different browsers: Safari, Chrome, Firefox, Edge
• Different OS: iOS, Android, Windows, macOS
• Different input methods: Touch, mouse, keyboard
• Edge cases: Very small screens (320px), very large screens (4K)
• Slow connections: Test on throttled network

Remember: You're a cross-platform design expert. Make experiences that feel native to each context while maintaining brand and functionality consistency. Adapt intentionally, test thoroughly.

Source Skill: animate

---

name: animate description: Review a feature and enhance it with purposeful animations, micro-interactions, and motion effects that improve usability and delight. user-invokable: true argument-hint: [TARGET=]

Analyze a feature and strategically add animations and micro-interactions that enhance understanding, provide feedback, and create delight.

MANDATORY PREPARATION

Use the design-foundation skill — it contains design principles, anti-patterns, and the Context Gathering Protocol. Follow the protocol before proceeding — if no design context exists yet, you MUST run teach-impeccable first. Additionally gather: performance constraints.

---

Assess Animation Opportunities

Analyze where motion would improve the experience:

1. Identify static areas:

   • Missing feedback: Actions without visual acknowledgment (button clicks, form submission, etc.)
   • Jarring transitions: Instant state changes that feel abrupt (show/hide, page loads, route changes)
   • Unclear relationships: Spatial or hierarchical relationships that aren't obvious
   • Lack of delight: Functional but joyless interactions
   • Missed guidance: Opportunities to direct attention or explain behavior

2. Understand the context:

   • What's the personality? (Playful vs serious, energetic vs calm)
   • What's the performance budget? (Mobile-first? Complex page?)
   • Who's the audience? (Motion-sensitive users? Power users who want speed?)
   • What matters most? (One hero animation vs many micro-interactions?)

If any of these are unclear from the codebase, ask the user directly to clarify what you cannot infer.

CRITICAL: Respect prefers-reduced-motion. Always provide non-animated alternatives for users who need them.

Plan Animation Strategy

Create a purposeful animation plan:

• Hero moment: What's the ONE signature animation? (Page load? Hero section? Key interaction?)
• Feedback layer: Which interactions need acknowledgment?
• Transition layer: Which state changes need smoothing?
• Delight layer: Where can we surprise and delight?

IMPORTANT: One well-orchestrated experience beats scattered animations everywhere. Focus on high-impact moments.

Implement Animations

Add motion systematically across these categories:

Entrance Animations

• Page load choreography: Stagger element reveals (100-150ms delays), fade + slide combinations
• Hero section: Dramatic entrance for primary content (scale, parallax, or creative effects)
• Content reveals: Scroll-triggered animations using intersection observer
• Modal/drawer entry: Smooth slide + fade, backdrop fade, focus management

Micro-interactions

• Button feedback:
  • Hover: Subtle scale (1.02-1.05), color shift, shadow increase
  • Click: Quick scale down then up (0.95 → 1), ripple effect
  • Loading: Spinner or pulse state
• Form interactions:
  • Input focus: Border color transition, slight scale or glow
  • Validation: Shake on error, check mark on success, smooth color transitions
• Toggle switches: Smooth slide + color transition (200-300ms)
• Checkboxes/radio: Check mark animation, ripple effect
• Like/favorite: Scale + rotation, particle effects, color transition

State Transitions

• Show/hide: Fade + slide (not instant), appropriate timing (200-300ms)
• Expand/collapse: Height transition with overflow handling, icon rotation
• Loading states: Skeleton screen fades, spinner animations, progress bars
• Success/error: Color transitions, icon animations, gentle scale pulse
• Enable/disable: Opacity transitions, cursor changes

Navigation & Flow

• Page transitions: Crossfade between routes, shared element transitions
• Tab switching: Slide indicator, content fade/slide
• Carousel/slider: Smooth transforms, snap points, momentum
• Scroll effects: Parallax layers, sticky headers with state changes, scroll progress indicators

Feedback & Guidance

• Hover hints: Tooltip fade-ins, cursor changes, element highlights
• Drag & drop: Lift effect (shadow + scale), drop zone highlights, smooth repositioning
• Copy/paste: Brief highlight flash on paste, "copied" confirmation
• Focus flow: Highlight path through form or workflow

Delight Moments

• Empty states: Subtle floating animations on illustrations
• Completed actions: Confetti, check mark flourish, success celebrations
• Easter eggs: Hidden interactions for discovery
• Contextual animation: Weather effects, time-of-day themes, seasonal touches

Technical Implementation

Use appropriate techniques for each animation:

Timing & Easing

Durations by purpose:

• 100-150ms: Instant feedback (button press, toggle)
• 200-300ms: State changes (hover, menu open)
• 300-500ms: Layout changes (accordion, modal)
• 500-800ms: Entrance animations (page load)

Easing curves (use these, not CSS defaults):

/* Recommended - natural deceleration */
--ease-out-quart: cubic-bezier(0.25, 1, 0.5, 1);    /* Smooth, refined */
--ease-out-quint: cubic-bezier(0.22, 1, 0.36, 1);   /* Slightly snappier */
--ease-out-expo: cubic-bezier(0.16, 1, 0.3, 1);     /* Confident, decisive */

/* AVOID - feel dated and tacky */
/* bounce: cubic-bezier(0.34, 1.56, 0.64, 1); */
/* elastic: cubic-bezier(0.68, -0.6, 0.32, 1.6); */

Exit animations are faster than entrances. Use ~75% of enter duration.

CSS Animations

/* Prefer for simple, declarative animations */
- transitions for state changes
- @keyframes for complex sequences
- transform + opacity only (GPU-accelerated)

JavaScript Animation

/* Use for complex, interactive animations */
- Web Animations API for programmatic control
- Framer Motion for React
- GSAP for complex sequences

Performance

• GPU acceleration: Use transform and opacity, avoid layout properties
• will-change: Add sparingly for known expensive animations
• Reduce paint: Minimize repaints, use contain where appropriate
• Monitor FPS: Ensure 60fps on target devices

Accessibility

@media (prefers-reduced-motion: reduce) {
  * {
    animation-duration: 0.01ms !important;
    animation-iteration-count: 1 !important;
    transition-duration: 0.01ms !important;
  }
}

NEVER:

• Use bounce or elastic easing curves—they feel dated and draw attention to the animation itself
• Animate layout properties (width, height, top, left)—use transform instead
• Use durations over 500ms for feedback—it feels laggy
• Animate without purpose—every animation needs a reason
• Ignore prefers-reduced-motion—this is an accessibility violation
• Animate everything—animation fatigue makes interfaces feel exhausting
• Block interaction during animations unless intentional

Verify Quality

Test animations thoroughly:

• Smooth at 60fps: No jank on target devices
• Feels natural: Easing curves feel organic, not robotic
• Appropriate timing: Not too fast (jarring) or too slow (laggy)
• Reduced motion works: Animations disabled or simplified appropriately
• Doesn't block: Users can interact during/after animations
• Adds value: Makes interface clearer or more delightful

Remember: Motion should enhance understanding and provide feedback, not just add decoration. Animate with purpose, respect performance constraints, and always consider accessibility. Great animation is invisible - it just makes everything feel right.

Source Skill: arrange

---

name: arrange description: Improve layout, spacing, and visual rhythm. Fixes monotonous grids, inconsistent spacing, and weak visual hierarchy to create intentional compositions. user-invokable: true argument-hint: [TARGET=]

Assess and improve layout and spacing that feels monotonous, crowded, or structurally weak — turning generic arrangements into intentional, rhythmic compositions.

MANDATORY PREPARATION

Use the design-foundation skill — it contains design principles, anti-patterns, and the Context Gathering Protocol. Follow the protocol before proceeding — if no design context exists yet, you MUST run teach-impeccable first.

---

Assess Current Layout

Analyze what's weak about the current spatial design:

1. Spacing:

   • Is spacing consistent or arbitrary? (Random padding/margin values)
   • Is all spacing the same? (Equal padding everywhere = no rhythm)
   • Are related elements grouped tightly, with generous space between groups?

2. Visual hierarchy:

   • Apply the squint test: blur your (metaphorical) eyes — can you still identify the most important element, second most important, and clear groupings?
   • Is hierarchy achieved effectively? (Space and weight alone can be enough — but is the current approach working?)
   • Does whitespace guide the eye to what matters?

3. Grid & structure:

   • Is there a clear underlying structure, or does the layout feel random?
   • Are identical card grids used everywhere? (Icon + heading + text, repeated endlessly)
   • Is everything centered? (Left-aligned with asymmetric layouts feels more designed, but not a hard and fast rule)

4. Rhythm & variety:

   • Does the layout have visual rhythm? (Alternating tight/generous spacing)
   • Is every section structured the same way? (Monotonous repetition)
   • Are there intentional moments of surprise or emphasis?

5. Density:

   • Is the layout too cramped? (Not enough breathing room)
   • Is the layout too sparse? (Excessive whitespace without purpose)
   • Does density match the content type? (Data-dense UIs need tighter spacing; marketing pages need more air)

CRITICAL: Layout problems are often the root cause of interfaces feeling "off" even when colors and fonts are fine. Space is a design material — use it with intention.

Plan Layout Improvements

Consult the spatial design reference from the design-foundation skill for detailed guidance on grids, rhythm, and container queries.

Create a systematic plan:

• Spacing system: Use a consistent scale — whether that's a framework's built-in scale (e.g., Tailwind), rem-based tokens, or a custom system. The specific values matter less than consistency.
• Hierarchy strategy: How will space communicate importance?
• Layout approach: What structure fits the content? Flex for 1D, Grid for 2D, named areas for complex page layouts.
• Rhythm: Where should spacing be tight vs generous?

Improve Layout Systematically

Establish a Spacing System

• Use a consistent spacing scale — framework scales (Tailwind, etc.), rem-based tokens, or a custom scale all work. What matters is that values come from a defined set, not arbitrary numbers.
• Name tokens semantically if using custom properties: --space-xs through --space-xl, not --spacing-8
• Use gap for sibling spacing instead of margins — eliminates margin collapse hacks
• Apply clamp() for fluid spacing that breathes on larger screens

Create Visual Rhythm

• Tight grouping for related elements (8-12px between siblings)
• Generous separation between distinct sections (48-96px)
• Varied spacing within sections — not every row needs the same gap
• Asymmetric compositions — break the predictable centered-content pattern when it makes sense

Choose the Right Layout Tool

• Use Flexbox for 1D layouts: Rows of items, nav bars, button groups, card contents, most component internals. Flex is simpler and more appropriate for the majority of layout tasks.
• Use Grid for 2D layouts: Page-level structure, dashboards, data-dense interfaces, anything where rows AND columns need coordinated control.
• Don't default to Grid when Flexbox with flex-wrap would be simpler and more flexible.
• Use repeat(auto-fit, minmax(280px, 1fr)) for responsive grids without breakpoints.
• Use named grid areas (grid-template-areas) for complex page layouts — redefine at breakpoints.

Break Card Grid Monotony

• Don't default to card grids for everything — spacing and alignment create visual grouping naturally
• Use cards only when content is truly distinct and actionable — never nest cards inside cards
• Vary card sizes, span columns, or mix cards with non-card content to break repetition

Strengthen Visual Hierarchy

• Use the fewest dimensions needed for clear hierarchy. Space alone can be enough — generous whitespace around an element draws the eye. Some of the most sophisticated designs achieve rhythm with just space and weight. Add color or size contrast only when simpler means aren't sufficient.
• Be aware of reading flow — in LTR languages, the eye naturally scans top-left to bottom-right, but primary action placement depends on context (e.g., bottom-right in dialogs, top in navigation).
• Create clear content groupings through proximity and separation.

Manage Depth & Elevation

• Create a semantic z-index scale (dropdown → sticky → modal-backdrop → modal → toast → tooltip)
• Build a consistent shadow scale (sm → md → lg → xl) — shadows should be subtle
• Use elevation to reinforce hierarchy, not as decoration

Optical Adjustments

• If an icon looks visually off-center despite being geometrically centered, nudge it — but only if you're confident it actually looks wrong. Don't adjust speculatively.

NEVER:

• Use arbitrary spacing values outside your scale
• Make all spacing equal — variety creates hierarchy
• Wrap everything in cards — not everything needs a container
• Nest cards inside cards — use spacing and dividers for hierarchy within
• Use identical card grids everywhere (icon + heading + text, repeated)
• Center everything — left-aligned with asymmetry feels more designed
• Default to the hero metric layout (big number, small label, stats, gradient) as a template. If showing real user data, a prominent metric can work — but it should display actual data, not decorative numbers.
• Default to CSS Grid when Flexbox would be simpler — use the simplest tool for the job
• Use arbitrary z-index values (999, 9999) — build a semantic scale

Verify Layout Improvements

• Squint test: Can you identify primary, secondary, and groupings with blurred vision?
• Rhythm: Does the page have a satisfying beat of tight and generous spacing?
• Hierarchy: Is the most important content obvious within 2 seconds?
• Breathing room: Does the layout feel comfortable, not cramped or wasteful?
• Consistency: Is the spacing system applied uniformly?
• Responsiveness: Does the layout adapt gracefully across screen sizes?

Remember: Space is the most underused design tool. A layout with the right rhythm and hierarchy can make even simple content feel polished and intentional.

Source Skill: bolder

---

name: bolder description: Amplify safe or boring designs to make them more visually interesting and stimulating. Increases impact while maintaining usability. user-invokable: true argument-hint: [TARGET=]

Increase visual impact and personality in designs that are too safe, generic, or visually underwhelming, creating more engaging and memorable experiences.

MANDATORY PREPARATION

Use the design-foundation skill — it contains design principles, anti-patterns, and the Context Gathering Protocol. Follow the protocol before proceeding — if no design context exists yet, you MUST run teach-impeccable first.

---

Assess Current State

Analyze what makes the design feel too safe or boring:

1. Identify weakness sources:

   • Generic choices: System fonts, basic colors, standard layouts
   • Timid scale: Everything is medium-sized with no drama
   • Low contrast: Everything has similar visual weight
   • Static: No motion, no energy, no life
   • Predictable: Standard patterns with no surprises
   • Flat hierarchy: Nothing stands out or commands attention

2. Understand the context:

   • What's the brand personality? (How far can we push?)
   • What's the purpose? (Marketing can be bolder than financial dashboards)
   • Who's the audience? (What will resonate?)
   • What are the constraints? (Brand guidelines, accessibility, performance)

If any of these are unclear from the codebase, ask the user directly to clarify what you cannot infer.

CRITICAL: "Bolder" doesn't mean chaotic or garish. It means distinctive, memorable, and confident. Think intentional drama, not random chaos.

WARNING - AI SLOP TRAP: When making things "bolder," AI defaults to the same tired tricks: cyan/purple gradients, glassmorphism, neon accents on dark backgrounds, gradient text on metrics. These are the OPPOSITE of bold—they're generic. Review ALL the DON'T guidelines in the design-foundation skill before proceeding. Bold means distinctive, not "more effects."

Plan Amplification

Create a strategy to increase impact while maintaining coherence:

• Focal point: What should be the hero moment? (Pick ONE, make it amazing)
• Personality direction: Maximalist chaos? Elegant drama? Playful energy? Dark moody? Choose a lane.
• Risk budget: How experimental can we be? Push boundaries within constraints.
• Hierarchy amplification: Make big things BIGGER, small things smaller (increase contrast)

IMPORTANT: Bold design must still be usable. Impact without function is just decoration.

Amplify the Design

Systematically increase impact across these dimensions:

Typography Amplification

• Replace generic fonts: Swap system fonts for distinctive choices (see design-foundation skill for inspiration)
• Extreme scale: Create dramatic size jumps (3x-5x differences, not 1.5x)
• Weight contrast: Pair 900 weights with 200 weights, not 600 with 400
• Unexpected choices: Variable fonts, display fonts for headlines, condensed/extended widths, monospace as intentional accent (not as lazy "dev tool" default)

Color Intensification

• Increase saturation: Shift to more vibrant, energetic colors (but not neon)
• Bold palette: Introduce unexpected color combinations—avoid the purple-blue gradient AI slop
• Dominant color strategy: Let one bold color own 60% of the design
• Sharp accents: High-contrast accent colors that pop
• Tinted neutrals: Replace pure grays with tinted grays that harmonize with your palette
• Rich gradients: Intentional multi-stop gradients (not generic purple-to-blue)

Spatial Drama

• Extreme scale jumps: Make important elements 3-5x larger than surroundings
• Break the grid: Let hero elements escape containers and cross boundaries
• Asymmetric layouts: Replace centered, balanced layouts with tension-filled asymmetry
• Generous space: Use white space dramatically (100-200px gaps, not 20-40px)
• Overlap: Layer elements intentionally for depth

Visual Effects

• Dramatic shadows: Large, soft shadows for elevation (but not generic drop shadows on rounded rectangles)
• Background treatments: Mesh patterns, noise textures, geometric patterns, intentional gradients (not purple-to-blue)
• Texture & depth: Grain, halftone, duotone, layered elements—NOT glassmorphism (it's overused AI slop)
• Borders & frames: Thick borders, decorative frames, custom shapes (not rounded rectangles with colored border on one side)
• Custom elements: Illustrative elements, custom icons, decorative details that reinforce brand

Motion & Animation

• Entrance choreography: Staggered, dramatic page load animations with 50-100ms delays
• Scroll effects: Parallax, reveal animations, scroll-triggered sequences
• Micro-interactions: Satisfying hover effects, click feedback, state changes
• Transitions: Smooth, noticeable transitions using ease-out-quart/quint/expo (not bounce or elastic—they cheapen the effect)

Composition Boldness

• Hero moments: Create clear focal points with dramatic treatment
• Diagonal flows: Escape horizontal/vertical rigidity with diagonal arrangements
• Full-bleed elements: Use full viewport width/height for impact
• Unexpected proportions: Golden ratio? Throw it out. Try 70/30, 80/20 splits

NEVER:

• Add effects randomly without purpose (chaos ≠ bold)
• Sacrifice readability for aesthetics (body text must be readable)
• Make everything bold (then nothing is bold - need contrast)
• Ignore accessibility (bold design must still meet WCAG standards)
• Overwhelm with motion (animation fatigue is real)
• Copy trendy aesthetics blindly (bold means distinctive, not derivative)

Verify Quality

Ensure amplification maintains usability and coherence:

• NOT AI slop: Does this look like every other AI-generated "bold" design? If yes, start over.
• Still functional: Can users accomplish tasks without distraction?
• Coherent: Does everything feel intentional and unified?
• Memorable: Will users remember this experience?
• Performant: Do all these effects run smoothly?
• Accessible: Does it still meet accessibility standards?

The test: If you showed this to someone and said "AI made this bolder," would they believe you immediately? If yes, you've failed. Bold means distinctive, not "more AI effects."

Remember: Bold design is confident design. It takes risks, makes statements, and creates memorable experiences. But bold without strategy is just loud. Be intentional, be dramatic, be unforgettable.

Source Skill: colorize

---

name: colorize description: Add strategic color to features that are too monochromatic or lack visual interest. Makes interfaces more engaging and expressive. user-invokable: true argument-hint: [TARGET=]

Strategically introduce color to designs that are too monochromatic, gray, or lacking in visual warmth and personality.

MANDATORY PREPARATION

Use the design-foundation skill — it contains design principles, anti-patterns, and the Context Gathering Protocol. Follow the protocol before proceeding — if no design context exists yet, you MUST run teach-impeccable first. Additionally gather: existing brand colors.

---

Assess Color Opportunity

Analyze the current state and identify opportunities:

1. Understand current state:

   • Color absence: Pure grayscale? Limited neutrals? One timid accent?
   • Missed opportunities: Where could color add meaning, hierarchy, or delight?
   • Context: What's appropriate for this domain and audience?
   • Brand: Are there existing brand colors we should use?

2. Identify where color adds value:

   • Semantic meaning: Success (green), error (red), warning (yellow/orange), info (blue)
   • Hierarchy: Drawing attention to important elements
   • Categorization: Different sections, types, or states
   • Emotional tone: Warmth, energy, trust, creativity
   • Wayfinding: Helping users navigate and understand structure
   • Delight: Moments of visual interest and personality

If any of these are unclear from the codebase, ask the user directly to clarify what you cannot infer.

CRITICAL: More color ≠ better. Strategic color beats rainbow vomit every time. Every color should have a purpose.

Plan Color Strategy

Create a purposeful color introduction plan:

• Color palette: What colors match the brand/context? (Choose 2-4 colors max beyond neutrals)
• Dominant color: Which color owns 60% of colored elements?
• Accent colors: Which colors provide contrast and highlights? (30% and 10%)
• Application strategy: Where does each color appear and why?

IMPORTANT: Color should enhance hierarchy and meaning, not create chaos. Less is more when it matters more.

Introduce Color Strategically

Add color systematically across these dimensions:

Semantic Color

• State indicators:

  • Success: Green tones (emerald, forest, mint)
  • Error: Red/pink tones (rose, crimson, coral)
  • Warning: Orange/amber tones
  • Info: Blue tones (sky, ocean, indigo)
  • Neutral: Gray/slate for inactive states

• Status badges: Colored backgrounds or borders for states (active, pending, completed, etc.)

• Progress indicators: Colored bars, rings, or charts showing completion or health

Accent Color Application

• Primary actions: Color the most important buttons/CTAs
• Links: Add color to clickable text (maintain accessibility)
• Icons: Colorize key icons for recognition and personality
• Headers/titles: Add color to section headers or key labels
• Hover states: Introduce color on interaction

Background & Surfaces

• Tinted backgrounds: Replace pure gray (#f5f5f5) with warm neutrals (oklch(97% 0.01 60)) or cool tints (oklch(97% 0.01 250))
• Colored sections: Use subtle background colors to separate areas
• Gradient backgrounds: Add depth with subtle, intentional gradients (not generic purple-blue)
• Cards & surfaces: Tint cards or surfaces slightly for warmth

Use OKLCH for color: It's perceptually uniform, meaning equal steps in lightness look equal. Great for generating harmonious scales.

Data Visualization

• Charts & graphs: Use color to encode categories or values
• Heatmaps: Color intensity shows density or importance
• Comparison: Color coding for different datasets or timeframes

Borders & Accents

• Accent borders: Add colored left/top borders to cards or sections
• Underlines: Color underlines for emphasis or active states
• Dividers: Subtle colored dividers instead of gray lines
• Focus rings: Colored focus indicators matching brand

Typography Color

• Colored headings: Use brand colors for section headings (maintain contrast)
• Highlight text: Color for emphasis or categories
• Labels & tags: Small colored labels for metadata or categories

Decorative Elements

• Illustrations: Add colored illustrations or icons
• Shapes: Geometric shapes in brand colors as background elements
• Gradients: Colorful gradient overlays or mesh backgrounds
• Blobs/organic shapes: Soft colored shapes for visual interest

Balance & Refinement

Ensure color addition improves rather than overwhelms:

Maintain Hierarchy

• Dominant color (60%): Primary brand color or most used accent
• Secondary color (30%): Supporting color for variety
• Accent color (10%): High contrast for key moments
• Neutrals (remaining): Gray/black/white for structure

Accessibility

• Contrast ratios: Ensure WCAG compliance (4.5:1 for text, 3:1 for UI components)
• Don't rely on color alone: Use icons, labels, or patterns alongside color
• Test for color blindness: Verify red/green combinations work for all users

Cohesion

• Consistent palette: Use colors from defined palette, not arbitrary choices
• Systematic application: Same color meanings throughout (green always = success)
• Temperature consistency: Warm palette stays warm, cool stays cool

NEVER:

• Use every color in the rainbow (choose 2-4 colors beyond neutrals)
• Apply color randomly without semantic meaning
• Put gray text on colored backgrounds—it looks washed out; use a darker shade of the background color or transparency instead
• Use pure gray for neutrals—add subtle color tint (warm or cool) for sophistication
• Use pure black (#000) or pure white (#fff) for large areas
• Violate WCAG contrast requirements
• Use color as the only indicator (accessibility issue)
• Make everything colorful (defeats the purpose)
• Default to purple-blue gradients (AI slop aesthetic)

Verify Color Addition

Test that colorization improves the experience:

• Better hierarchy: Does color guide attention appropriately?
• Clearer meaning: Does color help users understand states/categories?
• More engaging: Does the interface feel warmer and more inviting?
• Still accessible: Do all color combinations meet WCAG standards?
• Not overwhelming: Is color balanced and purposeful?

Remember: Color is emotional and powerful. Use it to create warmth, guide attention, communicate meaning, and express personality. But restraint and strategy matter more than saturation and variety. Be colorful, but be intentional.

Source Skill: delight

---

name: delight description: Add moments of joy, personality, and unexpected touches that make interfaces memorable and enjoyable to use. Elevates functional to delightful. user-invokable: true argument-hint: [TARGET=]

Identify opportunities to add moments of joy, personality, and unexpected polish that transform functional interfaces into delightful experiences.

MANDATORY PREPARATION

Use the design-foundation skill — it contains design principles, anti-patterns, and the Context Gathering Protocol. Follow the protocol before proceeding — if no design context exists yet, you MUST run teach-impeccable first. Additionally gather: what's appropriate for the domain (playful vs professional vs quirky vs elegant).

---

Assess Delight Opportunities

Identify where delight would enhance (not distract from) the experience:

1. Find natural delight moments:

   • Success states: Completed actions (save, send, publish)
   • Empty states: First-time experiences, onboarding
   • Loading states: Waiting periods that could be entertaining
   • Achievements: Milestones, streaks, completions
   • Interactions: Hover states, clicks, drags
   • Errors: Softening frustrating moments
   • Easter eggs: Hidden discoveries for curious users

2. Understand the context:

   • What's the brand personality? (Playful? Professional? Quirky? Elegant?)
   • Who's the audience? (Tech-savvy? Creative? Corporate?)
   • What's the emotional context? (Accomplishment? Exploration? Frustration?)
   • What's appropriate? (Banking app ≠ gaming app)

3. Define delight strategy:

   • Subtle sophistication: Refined micro-interactions (luxury brands)
   • Playful personality: Whimsical illustrations and copy (consumer apps)
   • Helpful surprises: Anticipating needs before users ask (productivity tools)
   • Sensory richness: Satisfying sounds, smooth animations (creative tools)

If any of these are unclear from the codebase, ask the user directly to clarify what you cannot infer.

CRITICAL: Delight should enhance usability, never obscure it. If users notice the delight more than accomplishing their goal, you've gone too far.

Delight Principles

Follow these guidelines:

Delight Amplifies, Never Blocks

• Delight moments should be quick (< 1 second)
• Never delay core functionality for delight
• Make delight skippable or subtle
• Respect user's time and task focus

Surprise and Discovery

• Hide delightful details for users to discover
• Reward exploration and curiosity
• Don't announce every delight moment
• Let users share discoveries with others

Appropriate to Context

• Match delight to emotional moment (celebrate success, empathize with errors)
• Respect the user's state (don't be playful during critical errors)
• Match brand personality and audience expectations
• Cultural sensitivity (what's delightful varies by culture)

Compound Over Time

• Delight should remain fresh with repeated use
• Vary responses (not same animation every time)
• Reveal deeper layers with continued use
• Build anticipation through patterns

Delight Techniques

Add personality and joy through these methods:

Micro-interactions & Animation

Button delight:

/* Satisfying button press */
.button {
  transition: transform 0.1s, box-shadow 0.1s;
}
.button:active {
  transform: translateY(2px);
  box-shadow: 0 2px 4px rgba(0,0,0,0.2);
}

/* Ripple effect on click */
/* Smooth lift on hover */
.button:hover {
  transform: translateY(-2px);
  transition: transform 0.2s cubic-bezier(0.25, 1, 0.5, 1); /* ease-out-quart */
}

Loading delight:

• Playful loading animations (not just spinners)
• Personality in loading messages (write product-specific ones, not generic AI filler)
• Progress indication with encouraging messages
• Skeleton screens with subtle animations

Success animations:

• Checkmark draw animation
• Confetti burst for major achievements
• Gentle scale + fade for confirmation
• Satisfying sound effects (subtle)

Hover surprises:

• Icons that animate on hover
• Color shifts or glow effects
• Tooltip reveals with personality
• Cursor changes (custom cursors for branded experiences)

Personality in Copy

Playful error messages:

"Error 404"
"This page is playing hide and seek. (And winning)"

"Connection failed"
"Looks like the internet took a coffee break. Want to retry?"

Encouraging empty states:

"No projects"
"Your canvas awaits. Create something amazing."

"No messages"
"Inbox zero! You're crushing it today."

Playful labels & tooltips:

"Delete"
"Send to void" (for playful brand)

"Help"
"Rescue me" (tooltip)

IMPORTANT: Match copy personality to brand. Banks shouldn't be wacky, but they can be warm.

Illustrations & Visual Personality

Custom illustrations:

• Empty state illustrations (not stock icons)
• Error state illustrations (friendly monsters, quirky characters)
• Loading state illustrations (animated characters)
• Success state illustrations (celebrations)

Icon personality:

• Custom icon set matching brand personality
• Animated icons (subtle motion on hover/click)
• Illustrative icons (more detailed than generic)
• Consistent style across all icons

Background effects:

• Subtle particle effects
• Gradient mesh backgrounds
• Geometric patterns
• Parallax depth
• Time-of-day themes (morning vs night)

Satisfying Interactions

Drag and drop delight:

• Lift effect on drag (shadow, scale)
• Snap animation when dropped
• Satisfying placement sound
• Undo toast ("Dropped in wrong place? [Undo]")

Toggle switches:

• Smooth slide with spring physics
• Color transition
• Haptic feedback on mobile
• Optional sound effect

Progress & achievements:

• Streak counters with celebratory milestones
• Progress bars that "celebrate" at 100%
• Badge unlocks with animation
• Playful stats ("You're on fire! 5 days in a row")

Form interactions:

• Input fields that animate on focus
• Checkboxes with a satisfying scale pulse when checked
• Success state that celebrates valid input
• Auto-grow textareas

Sound Design

Subtle audio cues (when appropriate):

• Notification sounds (distinctive but not annoying)
• Success sounds (satisfying "ding")
• Error sounds (empathetic, not harsh)
• Typing sounds for chat/messaging
• Ambient background audio (very subtle)

IMPORTANT:

• Respect system sound settings
• Provide mute option
• Keep volumes quiet (subtle cues, not alarms)
• Don't play on every interaction (sound fatigue is real)

Easter Eggs & Hidden Delights

Discovery rewards:

• Konami code unlocks special theme
• Hidden keyboard shortcuts (Cmd+K for special features)
• Hover reveals on logos or illustrations
• Alt text jokes on images (for screen reader users too!)
• Console messages for developers ("Like what you see? We're hiring!")

Seasonal touches:

• Holiday themes (subtle, tasteful)
• Seasonal color shifts
• Weather-based variations
• Time-based changes (dark at night, light during day)

Contextual personality:

• Different messages based on time of day
• Responses to specific user actions
• Randomized variations (not same every time)
• Progressive reveals with continued use

Loading & Waiting States

Make waiting engaging:

• Interesting loading messages that rotate
• Progress bars with personality
• Mini-games during long loads
• Fun facts or tips while waiting
• Countdown with encouraging messages

Loading messages — write ones specific to your product, not generic AI filler:
- "Crunching your latest numbers..."
- "Syncing with your team's changes..."
- "Preparing your dashboard..."
- "Checking for updates since yesterday..."

WARNING: Avoid cliched loading messages like "Herding pixels", "Teaching robots to dance", "Consulting the magic 8-ball", "Counting backwards from infinity". These are AI-slop copy — instantly recognizable as machine-generated. Write messages that are specific to what your product actually does.

Celebration Moments

Success celebrations:

• Confetti for major milestones
• Animated checkmarks for completions
• Progress bar celebrations at 100%
• "Achievement unlocked" style notifications
• Personalized messages ("You published your 10th article!")

Milestone recognition:

• First-time actions get special treatment
• Streak tracking and celebration
• Progress toward goals
• Anniversary celebrations

Implementation Patterns

Animation libraries:

• Framer Motion (React)
• GSAP (universal)
• Lottie (After Effects animations)
• Canvas confetti (party effects)

Sound libraries:

• Howler.js (audio management)
• Use-sound (React hook)

Physics libraries:

• React Spring (spring physics)
• Popmotion (animation primitives)

IMPORTANT: File size matters. Compress images, optimize animations, lazy load delight features.

NEVER:

• Delay core functionality for delight
• Force users through delightful moments (make skippable)
• Use delight to hide poor UX
• Overdo it (less is more)
• Ignore accessibility (animate responsibly, provide alternatives)
• Make every interaction delightful (special moments should be special)
• Sacrifice performance for delight
• Be inappropriate for context (read the room)

Verify Delight Quality

Test that delight actually delights:

• User reactions: Do users smile? Share screenshots?
• Doesn't annoy: Still pleasant after 100th time?
• Doesn't block: Can users opt out or skip?
• Performant: No jank, no slowdown
• Appropriate: Matches brand and context
• Accessible: Works with reduced motion, screen readers

Remember: Delight is the difference between a tool and an experience. Add personality, surprise users positively, and create moments worth sharing. But always respect usability - delight should enhance, never obstruct.

Source Skill: overdrive

---

name: overdrive description: Push interfaces past conventional limits with technically ambitious implementations. Whether that's a shader, a 60fps virtual table, spring physics on a dialog, or scroll-driven reveals — make users ask "how did they do that?" user-invokable: true argument-hint: [TARGET=]

Start your response with:

──────────── ⚡ OVERDRIVE ─────────────
》》》 Entering overdrive mode...

Push an interface past conventional limits. This isn't just about visual effects — it's about using the full power of the browser to make any part of an interface feel extraordinary: a table that handles a million rows, a dialog that morphs from its trigger, a form that validates in real-time with streaming feedback, a page transition that feels cinematic.

MANDATORY PREPARATION

Use the design-foundation skill — it contains design principles, anti-patterns, and the Context Gathering Protocol. Follow the protocol before proceeding — if no design context exists yet, you MUST run teach-impeccable first.

EXTRA IMPORTANT FOR THIS SKILL: Context determines what "extraordinary" means. A particle system on a creative portfolio is impressive. The same particle system on a settings page is embarrassing. But a settings page with instant optimistic saves and animated state transitions? That's extraordinary too. Understand the project's personality and goals before deciding what's appropriate.

Propose Before Building

This skill has the highest potential to misfire. Do NOT jump straight into implementation. You MUST:

1. Think through 2-3 different directions — consider different techniques, levels of ambition, and aesthetic approaches. For each direction, briefly describe what the result would look and feel like.
2. ask the user directly to clarify what you cannot infer. to present these directions and get the user's pick before writing any code. Explain trade-offs (browser support, performance cost, complexity).
3. Only proceed with the direction the user confirms.

Skipping this step risks building something embarrassing that needs to be thrown away.

Iterate with Browser Automation

Technically ambitious effects almost never work on the first try. You MUST actively use browser automation tools to preview your work, visually verify the result, and iterate. Do not assume the effect looks right — check it. Expect multiple rounds of refinement. The gap between "technically works" and "looks extraordinary" is closed through visual iteration, not code alone.

---

Assess What "Extraordinary" Means Here

The right kind of technical ambition depends entirely on what you're working with. Before choosing a technique, ask: what would make a user of THIS specific interface say "wow, that's nice"?

For visual/marketing surfaces

Pages, hero sections, landing pages, portfolios — the "wow" is often sensory: a scroll-driven reveal, a shader background, a cinematic page transition, generative art that responds to the cursor.

For functional UI

Tables, forms, dialogs, navigation — the "wow" is in how it FEELS: a dialog that morphs from the button that triggered it via View Transitions, a data table that renders 100k rows at 60fps via virtual scrolling, a form with streaming validation that feels instant, drag-and-drop with spring physics.

For performance-critical UI

The "wow" is invisible but felt: a search that filters 50k items without a flicker, a complex form that never blocks the main thread, an image editor that processes in near-real-time. The interface just never hesitates.

For data-heavy interfaces

Charts and dashboards — the "wow" is in fluidity: GPU-accelerated rendering via Canvas/WebGL for massive datasets, animated transitions between data states, force-directed graph layouts that settle naturally.

The common thread: something about the implementation goes beyond what users expect from a web interface. The technique serves the experience, not the other way around.

The Toolkit

Organized by what you're trying to achieve, not by technology name.

Make transitions feel cinematic

• View Transitions API (same-document: all browsers; cross-document: no Firefox) — shared element morphing between states. A list item expanding into a detail page. A button morphing into a dialog. This is the closest thing to native FLIP animations.
• @starting-style (all browsers) — animate elements from display: none to visible with CSS only, including entry keyframes
• Spring physics — natural motion with mass, tension, and damping instead of cubic-bezier. Libraries: motion (formerly Framer Motion), GSAP, or roll your own spring solver.

Tie animation to scroll position

• Scroll-driven animations (animation-timeline: scroll()) — CSS-only, no JS. Parallax, progress bars, reveal sequences all driven by scroll position. (Chrome/Edge/Safari; Firefox: flag only — always provide a static fallback)

Render beyond CSS

• WebGL (all browsers) — shader effects, post-processing, particle systems. Libraries: Three.js, OGL (lightweight), regl. Use for effects CSS can't express.
• WebGPU (Chrome/Edge; Safari partial; Firefox: flag only) — next-gen GPU compute. More powerful than WebGL but limited browser support. Always fall back to WebGL2.
• Canvas 2D / OffscreenCanvas — custom rendering, pixel manipulation, or moving heavy rendering off the main thread entirely via Web Workers + OffscreenCanvas.
• SVG filter chains — displacement maps, turbulence, morphology for organic distortion effects. CSS-animatable.

Make data feel alive

• Virtual scrolling — render only visible rows for tables/lists with tens of thousands of items. No library required for simple cases; TanStack Virtual for complex ones.
• GPU-accelerated charts — Canvas or WebGL-rendered data visualization for datasets too large for SVG/DOM. Libraries: deck.gl, regl-based custom renderers.
• Animated data transitions — morph between chart states rather than replacing. D3's transition() or View Transitions for DOM-based charts.

Animate complex properties

• @property (all browsers) — register custom CSS properties with types, enabling animation of gradients, colors, and complex values that CSS can't normally interpolate.
• Web Animations API (all browsers) — JavaScript-driven animations with the performance of CSS. Composable, cancellable, reversible. The foundation for complex choreography.

Push performance boundaries

• Web Workers — move computation off the main thread. Heavy data processing, image manipulation, search indexing — anything that would cause jank.
• OffscreenCanvas — render in a Worker thread. The main thread stays free while complex visuals render in the background.
• WASM — near-native performance for computation-heavy features. Image processing, physics simulations, codecs.

Interact with the device

• Web Audio API — spatial audio, audio-reactive visualizations, sonic feedback. Requires user gesture to start.
• Device APIs — orientation, ambient light, geolocation. Use sparingly and always with user permission.

NOTE: This skill is about enhancing how an interface FEELS, not changing what a product DOES. Adding real-time collaboration, offline support, or new backend capabilities are product decisions, not UI enhancements. Focus on making existing features feel extraordinary.

Implement with Discipline

Progressive enhancement is non-negotiable

Every technique must degrade gracefully. The experience without the enhancement must still be good.

@supports (animation-timeline: scroll()) {
  .hero { animation-timeline: scroll(); }
}

if ('gpu' in navigator) { /* WebGPU */ }
else if (canvas.getContext('webgl2')) { /* WebGL2 fallback */ }
/* CSS-only fallback must still look good */

Performance rules

• Target 60fps. If dropping below 50, simplify.
• Respect prefers-reduced-motion — always. Provide a beautiful static alternative.
• Lazy-initialize heavy resources (WebGL contexts, WASM modules) only when near viewport.
• Pause off-screen rendering. Kill what you can't see.
• Test on real mid-range devices, not just your development machine.

Polish is the difference

The gap between "cool" and "extraordinary" is in the last 20% of refinement: the easing curve on a spring animation, the timing offset in a staggered reveal, the subtle secondary motion that makes a transition feel physical. Don't ship the first version that works — ship the version that feels inevitable.

NEVER:

• Ignore prefers-reduced-motion — this is an accessibility requirement, not a suggestion
• Ship effects that cause jank on mid-range devices
• Use bleeding-edge APIs without a functional fallback
• Add sound without explicit user opt-in
• Use technical ambition to mask weak design fundamentals — fix those first with other skills
• Layer multiple competing extraordinary moments — focus creates impact, excess creates noise

Verify the Result

• The wow test: Show it to someone who hasn't seen it. Do they react?
• The removal test: Take it away. Does the experience feel diminished, or does nobody notice?
• The device test: Run it on a phone, a tablet, a Chromebook. Still smooth?
• The accessibility test: Enable reduced motion. Still beautiful?
• The context test: Does this make sense for THIS brand and audience?

Remember: "Technically extraordinary" isn't about using the newest API. It's about making an interface do something users didn't think a website could do.

Source Skill: typeset

---

name: typeset description: Improve typography by fixing font choices, hierarchy, sizing, weight consistency, and readability. Makes text feel intentional and polished. user-invokable: true argument-hint: [TARGET=]

Assess and improve typography that feels generic, inconsistent, or poorly structured — turning default-looking text into intentional, well-crafted type.

MANDATORY PREPARATION

Use the design-foundation skill — it contains design principles, anti-patterns, and the Context Gathering Protocol. Follow the protocol before proceeding — if no design context exists yet, you MUST run teach-impeccable first.

---

Assess Current Typography

Analyze what's weak or generic about the current type:

1. Font choices:

   • Are we using invisible defaults? (Inter, Roboto, Arial, Open Sans, system defaults)
   • Does the font match the brand personality? (A playful brand shouldn't use a corporate typeface)
   • Are there too many font families? (More than 2-3 is almost always a mess)

2. Hierarchy:

   • Can you tell headings from body from captions at a glance?
   • Are font sizes too close together? (14px, 15px, 16px = muddy hierarchy)
   • Are weight contrasts strong enough? (Medium vs Regular is barely visible)

3. Sizing & scale:

   • Is there a consistent type scale, or are sizes arbitrary?
   • Does body text meet minimum readability? (16px+)
   • Is the sizing strategy appropriate for the context? (Fixed rem scales for app UIs; fluid clamp() for marketing/content page headings)

4. Readability:

   • Are line lengths comfortable? (45-75 characters ideal)
   • Is line-height appropriate for the font and context?
   • Is there enough contrast between text and background?

5. Consistency:

   • Are the same elements styled the same way throughout?
   • Are font weights used consistently? (Not bold in one section, semibold in another for the same role)
   • Is letter-spacing intentional or default everywhere?

CRITICAL: The goal isn't to make text "fancier" — it's to make it clearer, more readable, and more intentional. Good typography is invisible; bad typography is distracting.

Plan Typography Improvements

Consult the typography reference from the design-foundation skill for detailed guidance on scales, pairing, and loading strategies.

Create a systematic plan:

• Font selection: Do fonts need replacing? What fits the brand/context?
• Type scale: Establish a modular scale (e.g., 1.25 ratio) with clear hierarchy
• Weight strategy: Which weights serve which roles? (Regular for body, Semibold for labels, Bold for headings — or whatever fits)
• Spacing: Line-heights, letter-spacing, and margins between typographic elements

Improve Typography Systematically

Font Selection

If fonts need replacing:

• Choose fonts that reflect the brand personality
• Pair with genuine contrast (serif + sans, geometric + humanist) — or use a single family in multiple weights
• Ensure web font loading doesn't cause layout shift (font-display: swap, metric-matched fallbacks)

Establish Hierarchy

Build a clear type scale:

• 5 sizes cover most needs: caption, secondary, body, subheading, heading
• Use a consistent ratio between levels (1.25, 1.333, or 1.5)
• Combine dimensions: Size + weight + color + space for strong hierarchy — don't rely on size alone
• App UIs: Use a fixed rem-based type scale, optionally adjusted at 1-2 breakpoints. Fluid sizing undermines the spatial predictability that dense, container-based layouts need
• Marketing / content pages: Use fluid sizing via clamp(min, preferred, max) for headings and display text. Keep body text fixed

Fix Readability

• Set max-width on text containers using ch units (max-width: 65ch)
• Adjust line-height per context: tighter for headings (1.1-1.2), looser for body (1.5-1.7)
• Increase line-height slightly for light-on-dark text
• Ensure body text is at least 16px / 1rem

Refine Details

• Use tabular-nums for data tables and numbers that should align
• Apply proper letter-spacing: slightly open for small caps and uppercase, default or tight for large display text
• Use semantic token names (--text-body, --text-heading), not value names (--font-16)
• Set font-kerning: normal and consider OpenType features where appropriate

Weight Consistency

• Define clear roles for each weight and stick to them
• Don't use more than 3-4 weights (Regular, Medium, Semibold, Bold is plenty)
• Load only the weights you actually use (each weight adds to page load)

NEVER:

• Use more than 2-3 font families
• Pick sizes arbitrarily — commit to a scale
• Set body text below 16px
• Use decorative/display fonts for body text
• Disable browser zoom (user-scalable=no)
• Use px for font sizes — use rem to respect user settings
• Default to Inter/Roboto/Open Sans when personality matters
• Pair fonts that are similar but not identical (two geometric sans-serifs)

Verify Typography Improvements

• Hierarchy: Can you identify heading vs body vs caption instantly?
• Readability: Is body text comfortable to read in long passages?
• Consistency: Are same-role elements styled identically throughout?
• Personality: Does the typography reflect the brand?
• Performance: Are web fonts loading efficiently without layout shift?
• Accessibility: Does text meet WCAG contrast ratios? Is it zoomable to 200%?

Remember: Typography is the foundation of interface design — it carries the majority of information. Getting it right is the highest-leverage improvement you can make.

Shared References

Reference: color-and-contrast.md

Color & Contrast

Color Spaces: Use OKLCH

Stop using HSL. Use OKLCH (or LCH) instead. It's perceptually uniform, meaning equal steps in lightness look equal—unlike HSL where 50% lightness in yellow looks bright while 50% in blue looks dark.

/* OKLCH: lightness (0-100%), chroma (0-0.4+), hue (0-360) */
--color-primary: oklch(60% 0.15 250);      /* Blue */
--color-primary-light: oklch(85% 0.08 250); /* Same hue, lighter */
--color-primary-dark: oklch(35% 0.12 250);  /* Same hue, darker */

Key insight: As you move toward white or black, reduce chroma (saturation). High chroma at extreme lightness looks garish. A light blue at 85% lightness needs ~0.08 chroma, not the 0.15 of your base color.

Building Functional Palettes

The Tinted Neutral Trap

Pure gray is dead. Add a subtle hint of your brand hue to all neutrals:

/* Dead grays */
--gray-100: oklch(95% 0 0);     /* No personality */
--gray-900: oklch(15% 0 0);

/* Warm-tinted grays (add brand warmth) */
--gray-100: oklch(95% 0.01 60);  /* Hint of warmth */
--gray-900: oklch(15% 0.01 60);

/* Cool-tinted grays (tech, professional) */
--gray-100: oklch(95% 0.01 250); /* Hint of blue */
--gray-900: oklch(15% 0.01 250);

The chroma is tiny (0.01) but perceptible. It creates subconscious cohesion between your brand color and your UI.

Palette Structure

A complete system needs:

Role	Purpose	Example
Primary	Brand, CTAs, key actions	1 color, 3-5 shades
Neutral	Text, backgrounds, borders	9-11 shade scale
Semantic	Success, error, warning, info	4 colors, 2-3 shades each
Surface	Cards, modals, overlays	2-3 elevation levels

Skip secondary/tertiary unless you need them. Most apps work fine with one accent color. Adding more creates decision fatigue and visual noise.

The 60-30-10 Rule (Applied Correctly)

This rule is about visual weight, not pixel count:

• 60%: Neutral backgrounds, white space, base surfaces
• 30%: Secondary colors—text, borders, inactive states
• 10%: Accent—CTAs, highlights, focus states

The common mistake: using the accent color everywhere because it's "the brand color." Accent colors work because they're rare. Overuse kills their power.

Contrast & Accessibility

WCAG Requirements

Content Type	AA Minimum	AAA Target
Body text	4.5:1	7:1
Large text (18px+ or 14px bold)	3:1	4.5:1
UI components, icons	3:1	4.5:1
Non-essential decorations	None	None

The gotcha: Placeholder text still needs 4.5:1. That light gray placeholder you see everywhere? Usually fails WCAG.

Dangerous Color Combinations

These commonly fail contrast or cause readability issues:

• Light gray text on white (the #1 accessibility fail)
• Gray text on any colored background—gray looks washed out and dead on color. Use a darker shade of the background color, or transparency
• Red text on green background (or vice versa)—8% of men can't distinguish these
• Blue text on red background (vibrates visually)
• Yellow text on white (almost always fails)
• Thin light text on images (unpredictable contrast)

Never Use Pure Gray or Pure Black

Pure gray (oklch(50% 0 0)) and pure black (#000) don't exist in nature—real shadows and surfaces always have a color cast. Even a chroma of 0.005-0.01 is enough to feel natural without being obviously tinted. (See tinted neutrals example above.)

Testing

Don't trust your eyes. Use tools:

• WebAIM Contrast Checker
• Browser DevTools → Rendering → Emulate vision deficiencies
• Polypane for real-time testing

Theming: Light & Dark Mode

Dark Mode Is Not Inverted Light Mode

You can't just swap colors. Dark mode requires different design decisions:

Light Mode	Dark Mode
Shadows for depth	Lighter surfaces for depth (no shadows)
Dark text on light	Light text on dark (reduce font weight)
Vibrant accents	Desaturate accents slightly
White backgrounds	Never pure black—use dark gray (oklch 12-18%)

/* Dark mode depth via surface color, not shadow */
:root[data-theme="dark"] {
  --surface-1: oklch(15% 0.01 250);
  --surface-2: oklch(20% 0.01 250);  /* "Higher" = lighter */
  --surface-3: oklch(25% 0.01 250);

  /* Reduce text weight slightly */
  --body-weight: 350;  /* Instead of 400 */
}

Token Hierarchy

Use two layers: primitive tokens (--blue-500) and semantic tokens (--color-primary: var(--blue-500)). For dark mode, only redefine the semantic layer—primitives stay the same.

Alpha Is A Design Smell

Heavy use of transparency (rgba, hsla) usually means an incomplete palette. Alpha creates unpredictable contrast, performance overhead, and inconsistency. Define explicit overlay colors for each context instead. Exception: focus rings and interactive states where see-through is needed.

---

Avoid: Relying on color alone to convey information. Creating palettes without clear roles for each color. Using pure black (#000) for large areas. Skipping color blindness testing (8% of men affected).

Reference: motion-design.md

Motion Design

Duration: The 100/300/500 Rule

Timing matters more than easing. These durations feel right for most UI:

Duration	Use Case	Examples
100-150ms	Instant feedback	Button press, toggle, color change
200-300ms	State changes	Menu open, tooltip, hover states
300-500ms	Layout changes	Accordion, modal, drawer
500-800ms	Entrance animations	Page load, hero reveals

Exit animations are faster than entrances—use ~75% of enter duration.

Easing: Pick the Right Curve

Don't use ease. It's a compromise that's rarely optimal. Instead:

Curve	Use For	CSS
ease-out	Elements entering	cubic-bezier(0.16, 1, 0.3, 1)
ease-in	Elements leaving	cubic-bezier(0.7, 0, 0.84, 0)
ease-in-out	State toggles (there → back)	cubic-bezier(0.65, 0, 0.35, 1)

For micro-interactions, use exponential curves—they feel natural because they mimic real physics (friction, deceleration):

/* Quart out - smooth, refined (recommended default) */
--ease-out-quart: cubic-bezier(0.25, 1, 0.5, 1);

/* Quint out - slightly more dramatic */
--ease-out-quint: cubic-bezier(0.22, 1, 0.36, 1);

/* Expo out - snappy, confident */
--ease-out-expo: cubic-bezier(0.16, 1, 0.3, 1);

Avoid bounce and elastic curves. They were trendy in 2015 but now feel tacky and amateurish. Real objects don't bounce when they stop—they decelerate smoothly. Overshoot effects draw attention to the animation itself rather than the content.

The Only Two Properties You Should Animate

transform and opacity only—everything else causes layout recalculation. For height animations (accordions), use grid-template-rows: 0fr → 1fr instead of animating height directly.

Staggered Animations

Use CSS custom properties for cleaner stagger: animation-delay: calc(var(--i, 0) * 50ms) with style="--i: 0" on each item. Cap total stagger time—10 items at 50ms = 500ms total. For many items, reduce per-item delay or cap staggered count.

Reduced Motion

This is not optional. Vestibular disorders affect ~35% of adults over 40.

/* Define animations normally */
.card {
  animation: slide-up 500ms ease-out;
}

/* Provide alternative for reduced motion */
@media (prefers-reduced-motion: reduce) {
  .card {
    animation: fade-in 200ms ease-out;  /* Crossfade instead of motion */
  }
}

/* Or disable entirely */
@media (prefers-reduced-motion: reduce) {
  *, *::before, *::after {
    animation-duration: 0.01ms !important;
    transition-duration: 0.01ms !important;
  }
}

What to preserve: Functional animations like progress bars, loading spinners (slowed down), and focus indicators should still work—just without spatial movement.

Perceived Performance

Nobody cares how fast your site is—just how fast it feels. Perception can be as effective as actual performance.

The 80ms threshold: Our brains buffer sensory input for ~80ms to synchronize perception. Anything under 80ms feels instant and simultaneous. This is your target for micro-interactions.

Active vs passive time: Passive waiting (staring at a spinner) feels longer than active engagement. Strategies to shift the balance:

• Preemptive start: Begin transitions immediately while loading (iOS app zoom, skeleton UI). Users perceive work happening.
• Early completion: Show content progressively—don't wait for everything. Video buffering, progressive images, streaming HTML.
• Optimistic UI: Update the interface immediately, handle failures gracefully. Instagram likes work offline—the UI updates instantly, syncs later. Use for low-stakes actions; avoid for payments or destructive operations.

Easing affects perceived duration: Ease-in (accelerating toward completion) makes tasks feel shorter because the peak-end effect weights final moments heavily. Ease-out feels satisfying for entrances, but ease-in toward a task's end compresses perceived time.

Caution: Too-fast responses can decrease perceived value. Users may distrust instant results for complex operations (search, analysis). Sometimes a brief delay signals "real work" is happening.

Performance

Don't use will-change preemptively—only when animation is imminent (:hover, .animating). For scroll-triggered animations, use Intersection Observer instead of scroll events; unobserve after animating once. Create motion tokens for consistency (durations, easings, common transitions).

---

Avoid: Animating everything (animation fatigue is real). Using >500ms for UI feedback. Ignoring prefers-reduced-motion. Using animation to hide slow loading.

Reference: responsive-design.md

Responsive Design

Mobile-First: Write It Right

Start with base styles for mobile, use min-width queries to layer complexity. Desktop-first (max-width) means mobile loads unnecessary styles first.

Breakpoints: Content-Driven

Don't chase device sizes—let content tell you where to break. Start narrow, stretch until design breaks, add breakpoint there. Three breakpoints usually suffice (640, 768, 1024px). Use clamp() for fluid values without breakpoints.

Detect Input Method, Not Just Screen Size

Screen size doesn't tell you input method. A laptop with touchscreen, a tablet with keyboard—use pointer and hover queries:

/* Fine pointer (mouse, trackpad) */
@media (pointer: fine) {
  .button { padding: 8px 16px; }
}

/* Coarse pointer (touch, stylus) */
@media (pointer: coarse) {
  .button { padding: 12px 20px; }  /* Larger touch target */
}

/* Device supports hover */
@media (hover: hover) {
  .card:hover { transform: translateY(-2px); }
}

/* Device doesn't support hover (touch) */
@media (hover: none) {
  .card { /* No hover state - use active instead */ }
}

Critical: Don't rely on hover for functionality. Touch users can't hover.

Safe Areas: Handle the Notch

Modern phones have notches, rounded corners, and home indicators. Use env():

body {
  padding-top: env(safe-area-inset-top);
  padding-bottom: env(safe-area-inset-bottom);
  padding-left: env(safe-area-inset-left);
  padding-right: env(safe-area-inset-right);
}

/* With fallback */
.footer {
  padding-bottom: max(1rem, env(safe-area-inset-bottom));
}

Enable viewport-fit in your meta tag:

<meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover">

Responsive Images: Get It Right

srcset with Width Descriptors

<img
  src="hero-800.jpg"
  srcset="
    hero-400.jpg 400w,
    hero-800.jpg 800w,
    hero-1200.jpg 1200w
  "
  sizes="(max-width: 768px) 100vw, 50vw"
  alt="Hero image"
>

How it works:

• srcset lists available images with their actual widths (w descriptors)
• sizes tells the browser how wide the image will display
• Browser picks the best file based on viewport width AND device pixel ratio

Picture Element for Art Direction

When you need different crops/compositions (not just resolutions):

<picture>
  <source media="(min-width: 768px)" srcset="wide.jpg">
  <source media="(max-width: 767px)" srcset="tall.jpg">
  <img src="fallback.jpg" alt="...">
</picture>

Layout Adaptation Patterns

Navigation: Three stages—hamburger + drawer on mobile, horizontal compact on tablet, full with labels on desktop. Tables: Transform to cards on mobile using display: block and data-label attributes. Progressive disclosure: Use <details>/<summary> for content that can collapse on mobile.

Testing: Don't Trust DevTools Alone

DevTools device emulation is useful for layout but misses:

• Actual touch interactions
• Real CPU/memory constraints
• Network latency patterns
• Font rendering differences
• Browser chrome/keyboard appearances

Test on at least: One real iPhone, one real Android, a tablet if relevant. Cheap Android phones reveal performance issues you'll never see on simulators.

---

Avoid: Desktop-first design. Device detection instead of feature detection. Separate mobile/desktop codebases. Ignoring tablet and landscape. Assuming all mobile devices are powerful.

Reference: spatial-design.md

Spatial Design

Spacing Systems

Use 4pt Base, Not 8pt

8pt systems are too coarse—you'll frequently need 12px (between 8 and 16). Use 4pt for granularity: 4, 8, 12, 16, 24, 32, 48, 64, 96px.

Name Tokens Semantically

Name by relationship (--space-sm, --space-lg), not value (--spacing-8). Use gap instead of margins for sibling spacing—it eliminates margin collapse and cleanup hacks.

Grid Systems

The Self-Adjusting Grid

Use repeat(auto-fit, minmax(280px, 1fr)) for responsive grids without breakpoints. Columns are at least 280px, as many as fit per row, leftovers stretch. For complex layouts, use named grid areas (grid-template-areas) and redefine them at breakpoints.

Visual Hierarchy

The Squint Test

Blur your eyes (or screenshot and blur). Can you still identify:

• The most important element?
• The second most important?
• Clear groupings?

If everything looks the same weight blurred, you have a hierarchy problem.

Hierarchy Through Multiple Dimensions

Don't rely on size alone. Combine:

Tool	Strong Hierarchy	Weak Hierarchy
Size	3:1 ratio or more	<2:1 ratio
Weight	Bold vs Regular	Medium vs Regular
Color	High contrast	Similar tones
Position	Top/left (primary)	Bottom/right
Space	Surrounded by white space	Crowded

The best hierarchy uses 2-3 dimensions at once: A heading that's larger, bolder, AND has more space above it.

Cards Are Not Required

Cards are overused. Spacing and alignment create visual grouping naturally. Use cards only when content is truly distinct and actionable, items need visual comparison in a grid, or content needs clear interaction boundaries. Never nest cards inside cards—use spacing, typography, and subtle dividers for hierarchy within a card.

Container Queries

Viewport queries are for page layouts. Container queries are for components:

.card-container {
  container-type: inline-size;
}

.card {
  display: grid;
  gap: var(--space-md);
}

/* Card layout changes based on its container, not viewport */
@container (min-width: 400px) {
  .card {
    grid-template-columns: 120px 1fr;
  }
}

Why this matters: A card in a narrow sidebar stays compact, while the same card in a main content area expands—automatically, without viewport hacks.

Optical Adjustments

Text at margin-left: 0 looks indented due to letterform whitespace—use negative margin (-0.05em) to optically align. Geometrically centered icons often look off-center; play icons need to shift right, arrows shift toward their direction.

Touch Targets vs Visual Size

Buttons can look small but need large touch targets (44px minimum). Use padding or pseudo-elements:

.icon-button {
  width: 24px;  /* Visual size */
  height: 24px;
  position: relative;
}

.icon-button::before {
  content: '';
  position: absolute;
  inset: -10px;  /* Expand tap target to 44px */
}

Depth & Elevation

Create semantic z-index scales (dropdown → sticky → modal-backdrop → modal → toast → tooltip) instead of arbitrary numbers. For shadows, create a consistent elevation scale (sm → md → lg → xl). Key insight: Shadows should be subtle—if you can clearly see it, it's probably too strong.

---

Avoid: Arbitrary spacing values outside your scale. Making all spacing equal (variety creates hierarchy). Creating hierarchy through size alone - combine size, weight, color, and space.

Reference: typography.md

Typography

Classic Typography Principles

Vertical Rhythm

Your line-height should be the base unit for ALL vertical spacing. If body text has line-height: 1.5 on 16px type (= 24px), spacing values should be multiples of 24px. This creates subconscious harmony—text and space share a mathematical foundation.

Modular Scale & Hierarchy

The common mistake: too many font sizes that are too close together (14px, 15px, 16px, 18px...). This creates muddy hierarchy.

Use fewer sizes with more contrast. A 5-size system covers most needs:

Role	Typical Ratio	Use Case
xs	0.75rem	Captions, legal
sm	0.875rem	Secondary UI, metadata
base	1rem	Body text
lg	1.25-1.5rem	Subheadings, lead text
xl+	2-4rem	Headlines, hero text

Popular ratios: 1.25 (major third), 1.333 (perfect fourth), 1.5 (perfect fifth). Pick one and commit.

Readability & Measure

Use ch units for character-based measure (max-width: 65ch). Line-height scales inversely with line length—narrow columns need tighter leading, wide columns need more.

Non-obvious: Increase line-height for light text on dark backgrounds. The perceived weight is lighter, so text needs more breathing room. Add 0.05-0.1 to your normal line-height.

Font Selection & Pairing

Choosing Distinctive Fonts