audit

name	adhoc_design_review
description	Merged design review skill set: critique, audit, hardening, optimization, polish, normalization, and intensity adjustment.

Ad-hoc Design Review

This file is a grouped copy of the source bundle from C:\Users\jan.papousek\Downloads\impeccable-style-universal\.agents\skills, focused on review, refinement, and system quality.

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: audit

---

name: audit description: Perform comprehensive audit of interface quality across accessibility, performance, theming, and responsive design. Generates detailed report of issues with severity ratings and recommendations. user-invokable: true argument-hint: [AREA=]

Run systematic quality checks and generate a comprehensive audit report with prioritized issues and actionable recommendations. Don't fix issues - document them for other commands to address.

First: Use the design-foundation skill for design principles and anti-patterns.

Diagnostic Scan

Run comprehensive checks across multiple dimensions:

1. Accessibility (A11y) - Check for:

   • Contrast issues: Text contrast ratios < 4.5:1 (or 7:1 for AAA)
   • Missing ARIA: Interactive elements without proper roles, labels, or states
   • Keyboard navigation: Missing focus indicators, illogical tab order, keyboard traps
   • Semantic HTML: Improper heading hierarchy, missing landmarks, divs instead of buttons
   • Alt text: Missing or poor image descriptions
   • Form issues: Inputs without labels, poor error messaging, missing required indicators

2. Performance - Check for:

   • Layout thrashing: Reading/writing layout properties in loops
   • Expensive animations: Animating layout properties (width, height, top, left) instead of transform/opacity
   • Missing optimization: Images without lazy loading, unoptimized assets, missing will-change
   • Bundle size: Unnecessary imports, unused dependencies
   • Render performance: Unnecessary re-renders, missing memoization

3. Theming - Check for:

   • Hard-coded colors: Colors not using design tokens
   • Broken dark mode: Missing dark mode variants, poor contrast in dark theme
   • Inconsistent tokens: Using wrong tokens, mixing token types
   • Theme switching issues: Values that don't update on theme change

4. Responsive Design - Check for:

   • Fixed widths: Hard-coded widths that break on mobile
   • Touch targets: Interactive elements < 44x44px
   • Horizontal scroll: Content overflow on narrow viewports
   • Text scaling: Layouts that break when text size increases
   • Missing breakpoints: No mobile/tablet variants

5. Anti-Patterns (CRITICAL) - Check against ALL the DON'T guidelines in the design-foundation skill. Look for AI slop tells (AI color palette, gradient text, glassmorphism, hero metrics, card grids, generic fonts) and general design anti-patterns (gray on color, nested cards, bounce easing, redundant copy).

CRITICAL: This is an audit, not a fix. Document issues thoroughly with clear explanations of impact. Use other commands (normalize, optimize, harden, etc.) to fix issues after audit.

Generate Comprehensive Report

Create a detailed audit report with the following structure:

Anti-Patterns Verdict

Start here. Pass/fail: Does this look AI-generated? List specific tells from the skill's Anti-Patterns section. Be brutally honest.

Executive Summary

• Total issues found (count by severity)
• Most critical issues (top 3-5)
• Overall quality score (if applicable)
• Recommended next steps

Detailed Findings by Severity

For each issue, document:

• Location: Where the issue occurs (component, file, line)
• Severity: Critical / High / Medium / Low
• Category: Accessibility / Performance / Theming / Responsive
• Description: What the issue is
• Impact: How it affects users
• WCAG/Standard: Which standard it violates (if applicable)
• Recommendation: How to fix it
• Suggested command: Which command to use (prefer: /extract, /distill, /arrange, /harden, /clarify, /critique, /delight, /onboard, /colorize, /animate, /audit, /quieter, /bolder, /typeset, /polish, /normalize, /overdrive, /adapt, /optimize — or other installed skills you're sure exist)

Critical Issues

[Issues that block core functionality or violate WCAG A]

High-Severity Issues

[Significant usability/accessibility impact, WCAG AA violations]

Medium-Severity Issues

[Quality issues, WCAG AAA violations, performance concerns]

Low-Severity Issues

[Minor inconsistencies, optimization opportunities]

Patterns & Systemic Issues

Identify recurring problems:

• "Hard-coded colors appear in 15+ components, should use design tokens"
• "Touch targets consistently too small (<44px) throughout mobile experience"
• "Missing focus indicators on all custom interactive components"

Positive Findings

Note what's working well:

• Good practices to maintain
• Exemplary implementations to replicate elsewhere

Recommendations by Priority

Create actionable plan:

1. Immediate: Critical blockers to fix first
2. Short-term: High-severity issues (this sprint)
3. Medium-term: Quality improvements (next sprint)
4. Long-term: Nice-to-haves and optimizations

Suggested Commands for Fixes

Map issues to available commands. Prefer these: /extract, /distill, /arrange, /harden, /clarify, /critique, /delight, /onboard, /colorize, /animate, /audit, /quieter, /bolder, /typeset, /polish, /normalize, /overdrive, /adapt, /optimize. You may also suggest other installed skills you're sure exist, but never invent commands.

Examples:

• "Use /normalize to align with design system (addresses N theming issues)"
• "Use /optimize to improve performance (addresses N performance issues)"
• "Use /harden to improve resilience (addresses N edge cases)"

IMPORTANT: Be thorough but actionable. Too many low-priority issues creates noise. Focus on what actually matters.

NEVER:

• Report issues without explaining impact (why does this matter?)
• Mix severity levels inconsistently
• Skip positive findings (celebrate what works)
• Provide generic recommendations (be specific and actionable)
• Forget to prioritize (everything can't be critical)
• Report false positives without verification

Remember: You're a quality auditor with exceptional attention to detail. Document systematically, prioritize ruthlessly, and provide clear paths to improvement. A good audit makes fixing easy.

Source Skill: critique

---

name: critique description: Evaluate design effectiveness from a UX perspective. Assesses visual hierarchy, information architecture, emotional resonance, and overall design quality with actionable feedback. user-invokable: true argument-hint: [AREA=]

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 the interface is trying to accomplish.

---

Conduct a holistic design critique, evaluating whether the interface actually works—not just technically, but as a designed experience. Think like a design director giving feedback.

Design Critique

Evaluate the interface across these dimensions:

1. AI Slop Detection (CRITICAL)

This is the most important check. Does this look like every other AI-generated interface from 2024-2025?

Review the design against ALL the DON'T guidelines in the design-foundation skill—they are the fingerprints of AI-generated work. Check for the AI color palette, gradient text, dark mode with glowing accents, glassmorphism, hero metric layouts, identical card grids, generic fonts, and all other tells.

The test: If you showed this to someone and said "AI made this," would they believe you immediately? If yes, that's the problem.

2. Visual Hierarchy

• Does the eye flow to the most important element first?
• Is there a clear primary action? Can you spot it in 2 seconds?
• Do size, color, and position communicate importance correctly?
• Is there visual competition between elements that should have different weights?

3. Information Architecture

• Is the structure intuitive? Would a new user understand the organization?
• Is related content grouped logically?
• Are there too many choices at once? (cognitive overload)
• Is the navigation clear and predictable?

4. Emotional Resonance

• What emotion does this interface evoke? Is that intentional?
• Does it match the brand personality?
• Does it feel trustworthy, approachable, premium, playful—whatever it should feel?
• Would the target user feel "this is for me"?

5. Discoverability & Affordance

• Are interactive elements obviously interactive?
• Would a user know what to do without instructions?
• Are hover/focus states providing useful feedback?
• Are there hidden features that should be more visible?

6. Composition & Balance

• Does the layout feel balanced or uncomfortably weighted?
• Is whitespace used intentionally or just leftover?
• Is there visual rhythm in spacing and repetition?
• Does asymmetry feel designed or accidental?

7. Typography as Communication

• Does the type hierarchy clearly signal what to read first, second, third?
• Is body text comfortable to read? (line length, spacing, size)
• Do font choices reinforce the brand/tone?
• Is there enough contrast between heading levels?

8. Color with Purpose

• Is color used to communicate, not just decorate?
• Does the palette feel cohesive?
• Are accent colors drawing attention to the right things?
• Does it work for colorblind users? (not just technically—does meaning still come through?)

9. States & Edge Cases

• Empty states: Do they guide users toward action, or just say "nothing here"?
• Loading states: Do they reduce perceived wait time?
• Error states: Are they helpful and non-blaming?
• Success states: Do they confirm and guide next steps?

10. Microcopy & Voice

• Is the writing clear and concise?
• Does it sound like a human (the right human for this brand)?
• Are labels and buttons unambiguous?
• Does error copy help users fix the problem?

Generate Critique Report

Structure your feedback as a design director would:

Anti-Patterns Verdict

Start here. Pass/fail: Does this look AI-generated? List specific tells from the skill's Anti-Patterns section. Be brutally honest.

Overall Impression

A brief gut reaction—what works, what doesn't, and the single biggest opportunity.

What's Working

Highlight 2-3 things done well. Be specific about why they work.

Priority Issues

The 3-5 most impactful design problems, ordered by importance:

For each issue:

• What: Name the problem clearly
• Why it matters: How this hurts users or undermines goals
• Fix: What to do about it (be concrete)
• Command: Which command to use (prefer: /extract, /distill, /arrange, /harden, /clarify, /critique, /delight, /onboard, /colorize, /animate, /audit, /quieter, /bolder, /typeset, /polish, /normalize, /overdrive, /adapt, /optimize — or other installed skills you're sure exist)

Minor Observations

Quick notes on smaller issues worth addressing.

Questions to Consider

Provocative questions that might unlock better solutions:

• "What if the primary action were more prominent?"
• "Does this need to feel this complex?"
• "What would a confident version of this look like?"

Remember:

• Be direct—vague feedback wastes everyone's time
• Be specific—"the submit button" not "some elements"
• Say what's wrong AND why it matters to users
• Give concrete suggestions, not just "consider exploring..."
• Prioritize ruthlessly—if everything is important, nothing is
• Don't soften criticism—developers need honest feedback to ship great design

Source Skill: harden

---

name: harden description: Improve interface resilience through better error handling, i18n support, text overflow handling, and edge case management. Makes interfaces robust and production-ready. user-invokable: true argument-hint: [TARGET=]

Strengthen interfaces against edge cases, errors, internationalization issues, and real-world usage scenarios that break idealized designs.

Assess Hardening Needs

Identify weaknesses and edge cases:

1. Test with extreme inputs:

   • Very long text (names, descriptions, titles)
   • Very short text (empty, single character)
   • Special characters (emoji, RTL text, accents)
   • Large numbers (millions, billions)
   • Many items (1000+ list items, 50+ options)
   • No data (empty states)

2. Test error scenarios:

   • Network failures (offline, slow, timeout)
   • API errors (400, 401, 403, 404, 500)
   • Validation errors
   • Permission errors
   • Rate limiting
   • Concurrent operations

3. Test internationalization:

   • Long translations (German is often 30% longer than English)
   • RTL languages (Arabic, Hebrew)
   • Character sets (Chinese, Japanese, Korean, emoji)
   • Date/time formats
   • Number formats (1,000 vs 1.000)
   • Currency symbols

CRITICAL: Designs that only work with perfect data aren't production-ready. Harden against reality.

Hardening Dimensions

Systematically improve resilience:

Text Overflow & Wrapping

Long text handling:

/* Single line with ellipsis */
.truncate {
  overflow: hidden;
  text-overflow: ellipsis;
  white-space: nowrap;
}

/* Multi-line with clamp */
.line-clamp {
  display: -webkit-box;
  -webkit-line-clamp: 3;
  -webkit-box-orient: vertical;
  overflow: hidden;
}

/* Allow wrapping */
.wrap {
  word-wrap: break-word;
  overflow-wrap: break-word;
  hyphens: auto;
}

Flex/Grid overflow:

/* Prevent flex items from overflowing */
.flex-item {
  min-width: 0; /* Allow shrinking below content size */
  overflow: hidden;
}

/* Prevent grid items from overflowing */
.grid-item {
  min-width: 0;
  min-height: 0;
}

Responsive text sizing:

• Use clamp() for fluid typography
• Set minimum readable sizes (14px on mobile)
• Test text scaling (zoom to 200%)
• Ensure containers expand with text

Internationalization (i18n)

Text expansion:

• Add 30-40% space budget for translations
• Use flexbox/grid that adapts to content
• Test with longest language (usually German)
• Avoid fixed widths on text containers

// ❌ Bad: Assumes short English text
<button className="w-24">Submit</button>

// ✅ Good: Adapts to content
<button className="px-4 py-2">Submit</button>

RTL (Right-to-Left) support:

/* Use logical properties */
margin-inline-start: 1rem; /* Not margin-left */
padding-inline: 1rem; /* Not padding-left/right */
border-inline-end: 1px solid; /* Not border-right */

/* Or use dir attribute */
[dir="rtl"] .arrow { transform: scaleX(-1); }

Character set support:

• Use UTF-8 encoding everywhere
• Test with Chinese/Japanese/Korean (CJK) characters
• Test with emoji (they can be 2-4 bytes)
• Handle different scripts (Latin, Cyrillic, Arabic, etc.)

Date/Time formatting:

// ✅ Use Intl API for proper formatting
new Intl.DateTimeFormat('en-US').format(date); // 1/15/2024
new Intl.DateTimeFormat('de-DE').format(date); // 15.1.2024

new Intl.NumberFormat('en-US', { 
  style: 'currency', 
  currency: 'USD' 
}).format(1234.56); // $1,234.56

Pluralization:

// ❌ Bad: Assumes English pluralization
`${count} item${count !== 1 ? 's' : ''}`

// ✅ Good: Use proper i18n library
t('items', { count }) // Handles complex plural rules

Error Handling

Network errors:

• Show clear error messages
• Provide retry button
• Explain what happened
• Offer offline mode (if applicable)
• Handle timeout scenarios

// Error states with recovery
{error && (
  <ErrorMessage>
    <p>Failed to load data. {error.message}</p>
    <button onClick={retry}>Try again</button>
  </ErrorMessage>
)}

Form validation errors:

• Inline errors near fields
• Clear, specific messages
• Suggest corrections
• Don't block submission unnecessarily
• Preserve user input on error

API errors:

• Handle each status code appropriately
  • 400: Show validation errors
  • 401: Redirect to login
  • 403: Show permission error
  • 404: Show not found state
  • 429: Show rate limit message
  • 500: Show generic error, offer support

Graceful degradation:

• Core functionality works without JavaScript
• Images have alt text
• Progressive enhancement
• Fallbacks for unsupported features

Edge Cases & Boundary Conditions

Empty states:

• No items in list
• No search results
• No notifications
• No data to display
• Provide clear next action

Loading states:

• Initial load
• Pagination load
• Refresh
• Show what's loading ("Loading your projects...")
• Time estimates for long operations

Large datasets:

• Pagination or virtual scrolling
• Search/filter capabilities
• Performance optimization
• Don't load all 10,000 items at once

Concurrent operations:

• Prevent double-submission (disable button while loading)
• Handle race conditions
• Optimistic updates with rollback
• Conflict resolution

Permission states:

• No permission to view
• No permission to edit
• Read-only mode
• Clear explanation of why

Browser compatibility:

• Polyfills for modern features
• Fallbacks for unsupported CSS
• Feature detection (not browser detection)
• Test in target browsers

Input Validation & Sanitization

Client-side validation:

• Required fields
• Format validation (email, phone, URL)
• Length limits
• Pattern matching
• Custom validation rules

Server-side validation (always):

• Never trust client-side only
• Validate and sanitize all inputs
• Protect against injection attacks
• Rate limiting

Constraint handling:

<!-- Set clear constraints -->
<input 
  type="text"
  maxlength="100"
  pattern="[A-Za-z0-9]+"
  required
  aria-describedby="username-hint"
/>
<small id="username-hint">
  Letters and numbers only, up to 100 characters
</small>

Accessibility Resilience

Keyboard navigation:

• All functionality accessible via keyboard
• Logical tab order
• Focus management in modals
• Skip links for long content

Screen reader support:

• Proper ARIA labels
• Announce dynamic changes (live regions)
• Descriptive alt text
• Semantic HTML

Motion sensitivity:

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

High contrast mode:

• Test in Windows high contrast mode
• Don't rely only on color
• Provide alternative visual cues

Performance Resilience

Slow connections:

• Progressive image loading
• Skeleton screens
• Optimistic UI updates
• Offline support (service workers)

Memory leaks:

• Clean up event listeners
• Cancel subscriptions
• Clear timers/intervals
• Abort pending requests on unmount

Throttling & Debouncing:

// Debounce search input
const debouncedSearch = debounce(handleSearch, 300);

// Throttle scroll handler
const throttledScroll = throttle(handleScroll, 100);

Testing Strategies

Manual testing:

• Test with extreme data (very long, very short, empty)
• Test in different languages
• Test offline
• Test slow connection (throttle to 3G)
• Test with screen reader
• Test keyboard-only navigation
• Test on old browsers

Automated testing:

• Unit tests for edge cases
• Integration tests for error scenarios
• E2E tests for critical paths
• Visual regression tests
• Accessibility tests (axe, WAVE)

IMPORTANT: Hardening is about expecting the unexpected. Real users will do things you never imagined.

NEVER:

• Assume perfect input (validate everything)
• Ignore internationalization (design for global)
• Leave error messages generic ("Error occurred")
• Forget offline scenarios
• Trust client-side validation alone
• Use fixed widths for text
• Assume English-length text
• Block entire interface when one component errors

Verify Hardening

Test thoroughly with edge cases:

• Long text: Try names with 100+ characters
• Emoji: Use emoji in all text fields
• RTL: Test with Arabic or Hebrew
• CJK: Test with Chinese/Japanese/Korean
• Network issues: Disable internet, throttle connection
• Large datasets: Test with 1000+ items
• Concurrent actions: Click submit 10 times rapidly
• Errors: Force API errors, test all error states
• Empty: Remove all data, test empty states

Remember: You're hardening for production reality, not demo perfection. Expect users to input weird data, lose connection mid-flow, and use your product in unexpected ways. Build resilience into every component.

Source Skill: normalize

---

name: normalize description: Normalize design to match your design system and ensure consistency user-invokable: true argument-hint: [FEATURE=]

Analyze and redesign the feature to perfectly match our design system standards, aesthetics, and established patterns.

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.

---

Plan

Before making changes, deeply understand the context:

1. Discover the design system: Search for design system documentation, UI guidelines, component libraries, or style guides (grep for "design system", "ui guide", "style guide", etc.). Study it thoroughly until you understand:

   • Core design principles and aesthetic direction
   • Target audience and personas
   • Component patterns and conventions
   • Design tokens (colors, typography, spacing)

   CRITICAL: If something isn't clear, ask. Don't guess at design system principles.

2. Analyze the current feature: Assess what works and what doesn't:

   • Where does it deviate from design system patterns?
   • Which inconsistencies are cosmetic vs. functional?
   • What's the root cause—missing tokens, one-off implementations, or conceptual misalignment?

3. Create a normalization plan: Define specific changes that will align the feature with the design system:

   • Which components can be replaced with design system equivalents?
   • Which styles need to use design tokens instead of hard-coded values?
   • How can UX patterns match established user flows?

   IMPORTANT: Great design is effective design. Prioritize UX consistency and usability over visual polish alone. Think through the best possible experience for your use case and personas first.

Execute

Systematically address all inconsistencies across these dimensions:

• Typography: Use design system fonts, sizes, weights, and line heights. Replace hard-coded values with typographic tokens or classes.
• Color & Theme: Apply design system color tokens. Remove one-off color choices that break the palette.
• Spacing & Layout: Use spacing tokens (margins, padding, gaps). Align with grid systems and layout patterns used elsewhere.
• Components: Replace custom implementations with design system components. Ensure props and variants match established patterns.
• Motion & Interaction: Match animation timing, easing, and interaction patterns to other features.
• Responsive Behavior: Ensure breakpoints and responsive patterns align with design system standards.
• Accessibility: Verify contrast ratios, focus states, ARIA labels match design system requirements.
• Progressive Disclosure: Match information hierarchy and complexity management to established patterns.

NEVER:

• Create new one-off components when design system equivalents exist
• Hard-code values that should use design tokens
• Introduce new patterns that diverge from the design system
• Compromise accessibility for visual consistency

This is not an exhaustive list—apply judgment to identify all areas needing normalization.

Clean Up

After normalization, ensure code quality:

• Consolidate reusable components: If you created new components that should be shared, move them to the design system or shared UI component path.
• Remove orphaned code: Delete unused implementations, styles, or files made obsolete by normalization.
• Verify quality: Lint, type-check, and test according to repository guidelines. Ensure normalization didn't introduce regressions.
• Ensure DRYness: Look for duplication introduced during refactoring and consolidate.

Remember: You are a brilliant design-focused interface designer with impeccable taste, equally strong in UX and UI. Your attention to detail and eye for end-to-end user experience is world class. Execute with precision and thoroughness.

Source Skill: optimize

---

name: optimize description: Improve interface performance across loading speed, rendering, animations, images, and bundle size. Makes experiences faster and smoother. user-invokable: true argument-hint: [TARGET=]

Identify and fix performance issues to create faster, smoother user experiences.

Assess Performance Issues

Understand current performance and identify problems:

1. Measure current state:

   • Core Web Vitals: LCP, FID/INP, CLS scores
   • Load time: Time to interactive, first contentful paint
   • Bundle size: JavaScript, CSS, image sizes
   • Runtime performance: Frame rate, memory usage, CPU usage
   • Network: Request count, payload sizes, waterfall

2. Identify bottlenecks:

   • What's slow? (Initial load? Interactions? Animations?)
   • What's causing it? (Large images? Expensive JavaScript? Layout thrashing?)
   • How bad is it? (Perceivable? Annoying? Blocking?)
   • Who's affected? (All users? Mobile only? Slow connections?)

CRITICAL: Measure before and after. Premature optimization wastes time. Optimize what actually matters.

Optimization Strategy

Create systematic improvement plan:

Loading Performance

Optimize Images:

• Use modern formats (WebP, AVIF)
• Proper sizing (don't load 3000px image for 300px display)
• Lazy loading for below-fold images
• Responsive images (srcset, picture element)
• Compress images (80-85% quality is usually imperceptible)
• Use CDN for faster delivery

<img 
  src="hero.webp"
  srcset="hero-400.webp 400w, hero-800.webp 800w, hero-1200.webp 1200w"
  sizes="(max-width: 400px) 400px, (max-width: 800px) 800px, 1200px"
  loading="lazy"
  alt="Hero image"
/>

Reduce JavaScript Bundle:

• Code splitting (route-based, component-based)
• Tree shaking (remove unused code)
• Remove unused dependencies
• Lazy load non-critical code
• Use dynamic imports for large components

// Lazy load heavy component
const HeavyChart = lazy(() => import('./HeavyChart'));

Optimize CSS:

• Remove unused CSS
• Critical CSS inline, rest async
• Minimize CSS files
• Use CSS containment for independent regions

Optimize Fonts:

• Use font-display: swap or optional
• Subset fonts (only characters you need)
• Preload critical fonts
• Use system fonts when appropriate
• Limit font weights loaded

@font-face {
  font-family: 'CustomFont';
  src: url('/fonts/custom.woff2') format('woff2');
  font-display: swap; /* Show fallback immediately */
  unicode-range: U+0020-007F; /* Basic Latin only */
}

Optimize Loading Strategy:

• Critical resources first (async/defer non-critical)
• Preload critical assets
• Prefetch likely next pages
• Service worker for offline/caching
• HTTP/2 or HTTP/3 for multiplexing

Rendering Performance

Avoid Layout Thrashing:

// ❌ Bad: Alternating reads and writes (causes reflows)
elements.forEach(el => {
  const height = el.offsetHeight; // Read (forces layout)
  el.style.height = height * 2; // Write
});

// ✅ Good: Batch reads, then batch writes
const heights = elements.map(el => el.offsetHeight); // All reads
elements.forEach((el, i) => {
  el.style.height = heights[i] * 2; // All writes
});

Optimize Rendering:

• Use CSS contain property for independent regions
• Minimize DOM depth (flatter is faster)
• Reduce DOM size (fewer elements)
• Use content-visibility: auto for long lists
• Virtual scrolling for very long lists (react-window, react-virtualized)

Reduce Paint & Composite:

• Use transform and opacity for animations (GPU-accelerated)
• Avoid animating layout properties (width, height, top, left)
• Use will-change sparingly for known expensive operations
• Minimize paint areas (smaller is faster)

Animation Performance

GPU Acceleration:

/* ✅ GPU-accelerated (fast) */
.animated {
  transform: translateX(100px);
  opacity: 0.5;
}

/* ❌ CPU-bound (slow) */
.animated {
  left: 100px;
  width: 300px;
}

Smooth 60fps:

• Target 16ms per frame (60fps)
• Use requestAnimationFrame for JS animations
• Debounce/throttle scroll handlers
• Use CSS animations when possible
• Avoid long-running JavaScript during animations

Intersection Observer:

// Efficiently detect when elements enter viewport
const observer = new IntersectionObserver((entries) => {
  entries.forEach(entry => {
    if (entry.isIntersecting) {
      // Element is visible, lazy load or animate
    }
  });
});

React/Framework Optimization

React-specific:

• Use memo() for expensive components
• useMemo() and useCallback() for expensive computations
• Virtualize long lists
• Code split routes
• Avoid inline function creation in render
• Use React DevTools Profiler

Framework-agnostic:

• Minimize re-renders
• Debounce expensive operations
• Memoize computed values
• Lazy load routes and components

Network Optimization

Reduce Requests:

• Combine small files
• Use SVG sprites for icons
• Inline small critical assets
• Remove unused third-party scripts

Optimize APIs:

• Use pagination (don't load everything)
• GraphQL to request only needed fields
• Response compression (gzip, brotli)
• HTTP caching headers
• CDN for static assets

Optimize for Slow Connections:

• Adaptive loading based on connection (navigator.connection)
• Optimistic UI updates
• Request prioritization
• Progressive enhancement

Core Web Vitals Optimization

Largest Contentful Paint (LCP < 2.5s)

• Optimize hero images
• Inline critical CSS
• Preload key resources
• Use CDN
• Server-side rendering

First Input Delay (FID < 100ms) / INP (< 200ms)

• Break up long tasks
• Defer non-critical JavaScript
• Use web workers for heavy computation
• Reduce JavaScript execution time

Cumulative Layout Shift (CLS < 0.1)

• Set dimensions on images and videos
• Don't inject content above existing content
• Use aspect-ratio CSS property
• Reserve space for ads/embeds
• Avoid animations that cause layout shifts

/* Reserve space for image */
.image-container {
  aspect-ratio: 16 / 9;
}

Performance Monitoring

Tools to use:

• Chrome DevTools (Lighthouse, Performance panel)
• WebPageTest
• Core Web Vitals (Chrome UX Report)
• Bundle analyzers (webpack-bundle-analyzer)
• Performance monitoring (Sentry, DataDog, New Relic)

Key metrics:

• LCP, FID/INP, CLS (Core Web Vitals)
• Time to Interactive (TTI)
• First Contentful Paint (FCP)
• Total Blocking Time (TBT)
• Bundle size
• Request count

IMPORTANT: Measure on real devices with real network conditions. Desktop Chrome with fast connection isn't representative.

NEVER:

• Optimize without measuring (premature optimization)
• Sacrifice accessibility for performance
• Break functionality while optimizing
• Use will-change everywhere (creates new layers, uses memory)
• Lazy load above-fold content
• Optimize micro-optimizations while ignoring major issues (optimize the biggest bottleneck first)
• Forget about mobile performance (often slower devices, slower connections)

Verify Improvements

Test that optimizations worked:

• Before/after metrics: Compare Lighthouse scores
• Real user monitoring: Track improvements for real users
• Different devices: Test on low-end Android, not just flagship iPhone
• Slow connections: Throttle to 3G, test experience
• No regressions: Ensure functionality still works
• User perception: Does it feel faster?

Remember: Performance is a feature. Fast experiences feel more responsive, more polished, more professional. Optimize systematically, measure ruthlessly, and prioritize user-perceived performance.

Source Skill: polish

---

name: polish description: Final quality pass before shipping. Fixes alignment, spacing, consistency, and detail issues that separate good from great. user-invokable: true argument-hint: [TARGET=]

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: quality bar (MVP vs flagship).

---

Perform a meticulous final pass to catch all the small details that separate good work from great work. The difference between shipped and polished.

Pre-Polish Assessment

Understand the current state and goals:

1. Review completeness:

   • Is it functionally complete?
   • Are there known issues to preserve (mark with TODOs)?
   • What's the quality bar? (MVP vs flagship feature?)
   • When does it ship? (How much time for polish?)

2. Identify polish areas:

   • Visual inconsistencies
   • Spacing and alignment issues
   • Interaction state gaps
   • Copy inconsistencies
   • Edge cases and error states
   • Loading and transition smoothness

CRITICAL: Polish is the last step, not the first. Don't polish work that's not functionally complete.

Polish Systematically

Work through these dimensions methodically:

Visual Alignment & Spacing

• Pixel-perfect alignment: Everything lines up to grid
• Consistent spacing: All gaps use spacing scale (no random 13px gaps)
• Optical alignment: Adjust for visual weight (icons may need offset for optical centering)
• Responsive consistency: Spacing and alignment work at all breakpoints
• Grid adherence: Elements snap to baseline grid

Check:

• Enable grid overlay and verify alignment
• Check spacing with browser inspector
• Test at multiple viewport sizes
• Look for elements that "feel" off

Typography Refinement

• Hierarchy consistency: Same elements use same sizes/weights throughout
• Line length: 45-75 characters for body text
• Line height: Appropriate for font size and context
• Widows & orphans: No single words on last line
• Hyphenation: Appropriate for language and column width
• Kerning: Adjust letter spacing where needed (especially headlines)
• Font loading: No FOUT/FOIT flashes

Color & Contrast

• Contrast ratios: All text meets WCAG standards
• Consistent token usage: No hard-coded colors, all use design tokens
• Theme consistency: Works in all theme variants
• Color meaning: Same colors mean same things throughout
• Accessible focus: Focus indicators visible with sufficient contrast
• Tinted neutrals: No pure gray or pure black—add subtle color tint (0.01 chroma)
• Gray on color: Never put gray text on colored backgrounds—use a shade of that color or transparency

Interaction States

Every interactive element needs all states:

• Default: Resting state
• Hover: Subtle feedback (color, scale, shadow)
• Focus: Keyboard focus indicator (never remove without replacement)
• Active: Click/tap feedback
• Disabled: Clearly non-interactive
• Loading: Async action feedback
• Error: Validation or error state
• Success: Successful completion

Missing states create confusion and broken experiences.

Micro-interactions & Transitions

• Smooth transitions: All state changes animated appropriately (150-300ms)
• Consistent easing: Use ease-out-quart/quint/expo for natural deceleration. Never bounce or elastic—they feel dated.
• No jank: 60fps animations, only animate transform and opacity
• Appropriate motion: Motion serves purpose, not decoration
• Reduced motion: Respects prefers-reduced-motion

Content & Copy

• Consistent terminology: Same things called same names throughout
• Consistent capitalization: Title Case vs Sentence case applied consistently
• Grammar & spelling: No typos
• Appropriate length: Not too wordy, not too terse
• Punctuation consistency: Periods on sentences, not on labels (unless all labels have them)

Icons & Images

• Consistent style: All icons from same family or matching style
• Appropriate sizing: Icons sized consistently for context
• Proper alignment: Icons align with adjacent text optically
• Alt text: All images have descriptive alt text
• Loading states: Images don't cause layout shift, proper aspect ratios
• Retina support: 2x assets for high-DPI screens

Forms & Inputs

• Label consistency: All inputs properly labeled
• Required indicators: Clear and consistent
• Error messages: Helpful and consistent
• Tab order: Logical keyboard navigation
• Auto-focus: Appropriate (don't overuse)
• Validation timing: Consistent (on blur vs on submit)

Edge Cases & Error States

• Loading states: All async actions have loading feedback
• Empty states: Helpful empty states, not just blank space
• Error states: Clear error messages with recovery paths
• Success states: Confirmation of successful actions
• Long content: Handles very long names, descriptions, etc.
• No content: Handles missing data gracefully
• Offline: Appropriate offline handling (if applicable)

Responsiveness

• All breakpoints: Test mobile, tablet, desktop
• Touch targets: 44x44px minimum on touch devices
• Readable text: No text smaller than 14px on mobile
• No horizontal scroll: Content fits viewport
• Appropriate reflow: Content adapts logically

Performance

• Fast initial load: Optimize critical path
• No layout shift: Elements don't jump after load (CLS)
• Smooth interactions: No lag or jank
• Optimized images: Appropriate formats and sizes
• Lazy loading: Off-screen content loads lazily

Code Quality

• Remove console logs: No debug logging in production
• Remove commented code: Clean up dead code
• Remove unused imports: Clean up unused dependencies
• Consistent naming: Variables and functions follow conventions
• Type safety: No TypeScript any or ignored errors
• Accessibility: Proper ARIA labels and semantic HTML

Polish Checklist

Go through systematically:

• Visual alignment perfect at all breakpoints
• Spacing uses design tokens consistently
• Typography hierarchy consistent
• All interactive states implemented
• All transitions smooth (60fps)
• Copy is consistent and polished
• Icons are consistent and properly sized
• All forms properly labeled and validated
• Error states are helpful
• Loading states are clear
• Empty states are welcoming
• Touch targets are 44x44px minimum
• Contrast ratios meet WCAG AA
• Keyboard navigation works
• Focus indicators visible
• No console errors or warnings
• No layout shift on load
• Works in all supported browsers
• Respects reduced motion preference
• Code is clean (no TODOs, console.logs, commented code)

IMPORTANT: Polish is about details. Zoom in. Squint at it. Use it yourself. The little things add up.

NEVER:

• Polish before it's functionally complete
• Spend hours on polish if it ships in 30 minutes (triage)
• Introduce bugs while polishing (test thoroughly)
• Ignore systematic issues (if spacing is off everywhere, fix the system)
• Perfect one thing while leaving others rough (consistent quality level)

Final Verification

Before marking as done:

• Use it yourself: Actually interact with the feature
• Test on real devices: Not just browser DevTools
• Ask someone else to review: Fresh eyes catch things
• Compare to design: Match intended design
• Check all states: Don't just test happy path

Remember: You have impeccable attention to detail and exquisite taste. Polish until it feels effortless, looks intentional, and works flawlessly. Sweat the details - they matter.

Source Skill: quieter

---

name: quieter description: Tone down overly bold or visually aggressive designs. Reduces intensity while maintaining design quality and impact. user-invokable: true argument-hint: [TARGET=]

Reduce visual intensity in designs that are too bold, aggressive, or overstimulating, creating a more refined and approachable aesthetic without losing effectiveness.

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 intense:

1. Identify intensity sources:

   • Color saturation: Overly bright or saturated colors
   • Contrast extremes: Too much high-contrast juxtaposition
   • Visual weight: Too many bold, heavy elements competing
   • Animation excess: Too much motion or overly dramatic effects
   • Complexity: Too many visual elements, patterns, or decorations
   • Scale: Everything is large and loud with no hierarchy

2. Understand the context:

   • What's the purpose? (Marketing vs tool vs reading experience)
   • Who's the audience? (Some contexts need energy)
   • What's working? (Don't throw away good ideas)
   • What's the core message? (Preserve what matters)

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

CRITICAL: "Quieter" doesn't mean boring or generic. It means refined, sophisticated, and easier on the eyes. Think luxury, not laziness.

Plan Refinement

Create a strategy to reduce intensity while maintaining impact:

• Color approach: Desaturate or shift to more sophisticated tones?
• Hierarchy approach: Which elements should stay bold (very few), which should recede?
• Simplification approach: What can be removed entirely?
• Sophistication approach: How can we signal quality through restraint?

IMPORTANT: Great quiet design is harder than great bold design. Subtlety requires precision.

Refine the Design

Systematically reduce intensity across these dimensions:

Color Refinement

• Reduce saturation: Shift from fully saturated to 70-85% saturation
• Soften palette: Replace bright colors with muted, sophisticated tones
• Reduce color variety: Use fewer colors more thoughtfully
• Neutral dominance: Let neutrals do more work, use color as accent (10% rule)
• Gentler contrasts: High contrast only where it matters most
• Tinted grays: Use warm or cool tinted grays instead of pure gray—adds sophistication without loudness
• Never gray on color: If you have gray text on a colored background, use a darker shade of that color or transparency instead

Visual Weight Reduction

• Typography: Reduce font weights (900 → 600, 700 → 500), decrease sizes where appropriate
• Hierarchy through subtlety: Use weight, size, and space instead of color and boldness
• White space: Increase breathing room, reduce density
• Borders & lines: Reduce thickness, decrease opacity, or remove entirely

Simplification

• Remove decorative elements: Gradients, shadows, patterns, textures that don't serve purpose
• Simplify shapes: Reduce border radius extremes, simplify custom shapes
• Reduce layering: Flatten visual hierarchy where possible
• Clean up effects: Reduce or remove blur effects, glows, multiple shadows

Motion Reduction

• Reduce animation intensity: Shorter distances (10-20px instead of 40px), gentler easing
• Remove decorative animations: Keep functional motion, remove flourishes
• Subtle micro-interactions: Replace dramatic effects with gentle feedback
• Refined easing: Use ease-out-quart for smooth, understated motion—never bounce or elastic
• Remove animations entirely if they're not serving a clear purpose

Composition Refinement

• Reduce scale jumps: Smaller contrast between sizes creates calmer feeling
• Align to grid: Bring rogue elements back into systematic alignment
• Even out spacing: Replace extreme spacing variations with consistent rhythm

NEVER:

• Make everything the same size/weight (hierarchy still matters)
• Remove all color (quiet ≠ grayscale)
• Eliminate all personality (maintain character through refinement)
• Sacrifice usability for aesthetics (functional elements still need clear affordances)
• Make everything small and light (some anchors needed)

Verify Quality

Ensure refinement maintains quality:

• Still functional: Can users still accomplish tasks easily?
• Still distinctive: Does it have character, or is it generic now?
• Better reading: Is text easier to read for extended periods?
• Sophistication: Does it feel more refined and premium?

Remember: Quiet design is confident design. It doesn't need to shout. Less is more, but less is also harder. Refine with precision and maintain intentionality.

Shared References

Reference: interaction-design.md

Interaction Design

The Eight Interactive States

Every interactive element needs these states designed:

State	When	Visual Treatment
Default	At rest	Base styling
Hover	Pointer over (not touch)	Subtle lift, color shift
Focus	Keyboard/programmatic focus	Visible ring (see below)
Active	Being pressed	Pressed in, darker
Disabled	Not interactive	Reduced opacity, no pointer
Loading	Processing	Spinner, skeleton
Error	Invalid state	Red border, icon, message
Success	Completed	Green check, confirmation

The common miss: Designing hover without focus, or vice versa. They're different. Keyboard users never see hover states.

Focus Rings: Do Them Right

Never outline: none without replacement. It's an accessibility violation. Instead, use :focus-visible to show focus only for keyboard users:

/* Hide focus ring for mouse/touch */
button:focus {
  outline: none;
}

/* Show focus ring for keyboard */
button:focus-visible {
  outline: 2px solid var(--color-accent);
  outline-offset: 2px;
}

Focus ring design:

• High contrast (3:1 minimum against adjacent colors)
• 2-3px thick
• Offset from element (not inside it)
• Consistent across all interactive elements

Form Design: The Non-Obvious

Placeholders aren't labels—they disappear on input. Always use visible <label> elements. Validate on blur, not on every keystroke (exception: password strength). Place errors below fields with aria-describedby connecting them.

Loading States

Optimistic updates: Show success immediately, rollback on failure. Use for low-stakes actions (likes, follows), not payments or destructive actions. Skeleton screens > spinners—they preview content shape and feel faster than generic spinners.

Modals: The Inert Approach

Focus trapping in modals used to require complex JavaScript. Now use the inert attribute:

<!-- When modal is open -->
<main inert>
  <!-- Content behind modal can't be focused or clicked -->
</main>
<dialog open>
  <h2>Modal Title</h2>
  <!-- Focus stays inside modal -->
</dialog>

Or use the native <dialog> element:

const dialog = document.querySelector('dialog');
dialog.showModal();  // Opens with focus trap, closes on Escape

The Popover API

For tooltips, dropdowns, and non-modal overlays, use native popovers:

<button popovertarget="menu">Open menu</button>
<div id="menu" popover>
  <button>Option 1</button>
  <button>Option 2</button>
</div>

Benefits: Light-dismiss (click outside closes), proper stacking, no z-index wars, accessible by default.

Destructive Actions: Undo > Confirm

Undo is better than confirmation dialogs—users click through confirmations mindlessly. Remove from UI immediately, show undo toast, actually delete after toast expires. Use confirmation only for truly irreversible actions (account deletion), high-cost actions, or batch operations.

Keyboard Navigation Patterns

Roving Tabindex

For component groups (tabs, menu items, radio groups), one item is tabbable; arrow keys move within:

<div role="tablist">
  <button role="tab" tabindex="0">Tab 1</button>
  <button role="tab" tabindex="-1">Tab 2</button>
  <button role="tab" tabindex="-1">Tab 3</button>
</div>

Arrow keys move tabindex="0" between items. Tab moves to the next component entirely.

Skip Links

Provide skip links (<a href="#main-content">Skip to main content</a>) for keyboard users to jump past navigation. Hide off-screen, show on focus.

Gesture Discoverability

Swipe-to-delete and similar gestures are invisible. Hint at their existence:

• Partially reveal: Show delete button peeking from edge
• Onboarding: Coach marks on first use
• Alternative: Always provide a visible fallback (menu with "Delete")

Don't rely on gestures as the only way to perform actions.

---

Avoid: Removing focus indicators without alternatives. Using placeholder text as labels. Touch targets <44x44px. Generic error messages. Custom controls without ARIA/keyboard support.

Reference: ux-writing.md

UX Writing

The Button Label Problem

Never use "OK", "Submit", or "Yes/No". These are lazy and ambiguous. Use specific verb + object patterns:

Bad	Good	Why
OK	Save changes	Says what will happen
Submit	Create account	Outcome-focused
Yes	Delete message	Confirms the action
Cancel	Keep editing	Clarifies what "cancel" means
Click here	Download PDF	Describes the destination

For destructive actions, name the destruction:

• "Delete" not "Remove" (delete is permanent, remove implies recoverable)
• "Delete 5 items" not "Delete selected" (show the count)

Error Messages: The Formula

Every error message should answer: (1) What happened? (2) Why? (3) How to fix it? Example: "Email address isn't valid. Please include an @ symbol." not "Invalid input".

Error Message Templates

Situation	Template
Format error	"[Field] needs to be [format]. Example: [example]"
Missing required	"Please enter [what's missing]"
Permission denied	"You don't have access to [thing]. [What to do instead]"
Network error	"We couldn't reach [thing]. Check your connection and [action]."
Server error	"Something went wrong on our end. We're looking into it. [Alternative action]"

Don't Blame the User

Reframe errors: "Please enter a date in MM/DD/YYYY format" not "You entered an invalid date".

Empty States Are Opportunities

Empty states are onboarding moments: (1) Acknowledge briefly, (2) Explain the value of filling it, (3) Provide a clear action. "No projects yet. Create your first one to get started." not just "No items".

Voice vs Tone

Voice is your brand's personality—consistent everywhere. Tone adapts to the moment.

Moment	Tone Shift
Success	Celebratory, brief: "Done! Your changes are live."
Error	Empathetic, helpful: "That didn't work. Here's what to try..."
Loading	Reassuring: "Saving your work..."
Destructive confirm	Serious, clear: "Delete this project? This can't be undone."

Never use humor for errors. Users are already frustrated. Be helpful, not cute.

Writing for Accessibility

Link text must have standalone meaning—"View pricing plans" not "Click here". Alt text describes information, not the image—"Revenue increased 40% in Q4" not "Chart". Use alt="" for decorative images. Icon buttons need aria-label for screen reader context.

Writing for Translation

Plan for Expansion

German text is ~30% longer than English. Allocate space:

Language	Expansion
German	+30%
French	+20%
Finnish	+30-40%
Chinese	-30% (fewer chars, but same width)

Translation-Friendly Patterns

Keep numbers separate ("New messages: 3" not "You have 3 new messages"). Use full sentences as single strings (word order varies by language). Avoid abbreviations ("5 minutes ago" not "5 mins ago"). Give translators context about where strings appear.

Consistency: The Terminology Problem

Pick one term and stick with it:

Inconsistent	Consistent
Delete / Remove / Trash	Delete
Settings / Preferences / Options	Settings
Sign in / Log in / Enter	Sign in
Create / Add / New	Create

Build a terminology glossary and enforce it. Variety creates confusion.

Avoid Redundant Copy

If the heading explains it, the intro is redundant. If the button is clear, don't explain it again. Say it once, say it well.

Loading States

Be specific: "Saving your draft..." not "Loading...". For long waits, set expectations ("This usually takes 30 seconds") or show progress.

Confirmation Dialogs: Use Sparingly

Most confirmation dialogs are design failures—consider undo instead. When you must confirm: name the action, explain consequences, use specific button labels ("Delete project" / "Keep project", not "Yes" / "No").

Form Instructions

Show format with placeholders, not instructions. For non-obvious fields, explain why you're asking.

---

Avoid: Jargon without explanation. Blaming users ("You made an error" → "This field is required"). Vague errors ("Something went wrong"). Varying terminology for variety. Humor for errors.