learnship 1.9.0

package/skills/impeccable/animate/SKILL.md

@@ -0,0 +1,190 @@
+---
+name: animate
+description: Review a feature and enhance it with purposeful animations, micro-interactions, and motion effects that improve usability and delight.
+args:
+  - name: target
+    description: The feature or component to animate (optional)
+    required: false
+user-invokable: true
+---
+
+Analyze a feature and strategically add animations and micro-interactions that enhance understanding, provide feedback, and create delight.
+
+## MANDATORY PREPARATION
+
+### Context Gathering (Do This First)
+
+You cannot do a great job without having necessary context, such as target audience (critical), desired use-cases (critical), brand personality/tone (playful vs serious, energetic vs calm), and performance constraints.
+
+Attempt to gather these from the current thread or codebase.
+
+1. If you don't find *exact* information and have to infer from existing design and functionality, you MUST STOP and Ask the user: whether you got it right.
+2. Otherwise, if you can't fully infer or your level of confidence is medium or lower, you MUST Ask the user: clarifying questions first to complete your context.
+
+Do NOT proceed until you have answers. Guessing leads to inappropriate or excessive animation.
+
+### Use frontend-design skill
+
+Use the frontend-design skill for design principles and anti-patterns. Do NOT proceed until it has executed and you know all DO's and DON'Ts.
+
+---
+
+## 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:
+
+**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):**
+```css
+/* 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
+```css
+/* Prefer for simple, declarative animations */
+- transitions for state changes
+- @keyframes for complex sequences
+- transform + opacity only (GPU-accelerated)
+```
+
+### JavaScript Animation
+```javascript
+/* 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
+```css
+@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.

package/skills/impeccable/audit/SKILL.md

@@ -0,0 +1,129 @@
+---
+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.
+args:
+  - name: area
+    description: The feature or area to audit (optional)
+    required: false
+user-invokable: true
+---
+
+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 frontend-design 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 frontend-design 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: /polish, /audit, /critique, /normalize, /colorize, /animate, /bolder, /quieter, /distill, /clarify, /optimize, /harden, /delight, /extract, /adapt, /onboard, /teach-impeccable — 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: /polish, /audit, /critique, /normalize, /colorize, /animate, /bolder, /quieter, /distill, /clarify, /optimize, /harden, /delight, /extract, /adapt, /onboard, /teach-impeccable. 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.
+

package/skills/impeccable/bolder/SKILL.md

@@ -0,0 +1,132 @@
+---
+name: bolder
+description: Amplify safe or boring designs to make them more visually interesting and stimulating. Increases impact while maintaining usability.
+args:
+  - name: target
+    description: The feature or component to make bolder (optional)
+    required: false
+user-invokable: true
+---
+
+Increase visual impact and personality in designs that are too safe, generic, or visually underwhelming, creating more engaging and memorable experiences.
+
+## MANDATORY PREPARATION
+
+### Context Gathering (Do This First)
+
+You cannot do a great job without having necessary context, such as target audience (critical), desired use-cases (critical), brand personality/tone, and everything else that a great human designer would need as well.
+
+Attempt to gather these from the current thread or codebase.
+
+1. If you don't find *exact* information and have to infer from existing design and functionality, you MUST STOP and Ask the user: whether you got it right.
+2. Otherwise, if you can't fully infer or your level of confidence is medium or lower, you MUST Ask the user: clarifying questions first to complete your context.
+
+Do NOT proceed until you have answers. Guessing leads to generic AI slop.
+
+### Use frontend-design skill
+
+Use the frontend-design skill for design principles and anti-patterns. Do NOT proceed until it has executed and you know all DO's and DON'Ts.
+
+---
+
+## 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:
+
+**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 frontend-design 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 frontend-design 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.

package/skills/impeccable/clarify/SKILL.md

@@ -0,0 +1,180 @@
+---
+name: clarify
+description: Improve unclear UX copy, error messages, microcopy, labels, and instructions. Makes interfaces easier to understand and use.
+args:
+  - name: target
+    description: The feature or component with unclear copy (optional)
+    required: false
+user-invokable: true
+---
+
+Identify and improve unclear, confusing, or poorly written interface text to make the product easier to understand and use.
+
+## Assess Current Copy
+
+Identify what makes the text unclear or ineffective:
+
+1. **Find clarity problems**:
+   - **Jargon**: Technical terms users won't understand
+   - **Ambiguity**: Multiple interpretations possible
+   - **Passive voice**: "Your file has been uploaded" vs "We uploaded your file"
+   - **Length**: Too wordy or too terse
+   - **Assumptions**: Assuming user knowledge they don't have
+   - **Missing context**: Users don't know what to do or why
+   - **Tone mismatch**: Too formal, too casual, or inappropriate for situation
+
+2. **Understand the context**:
+   - Who's the audience? (Technical? General? First-time users?)
+   - What's the user's mental state? (Stressed during error? Confident during success?)
+   - What's the action? (What do we want users to do?)
+   - What's the constraint? (Character limits? Space limitations?)
+
+**CRITICAL**: Clear copy helps users succeed. Unclear copy creates frustration, errors, and support tickets.
+
+## Plan Copy Improvements
+
+Create a strategy for clearer communication:
+
+- **Primary message**: What's the ONE thing users need to know?
+- **Action needed**: What should users do next (if anything)?
+- **Tone**: How should this feel? (Helpful? Apologetic? Encouraging?)
+- **Constraints**: Length limits, brand voice, localization considerations
+
+**IMPORTANT**: Good UX writing is invisible. Users should understand immediately without noticing the words.
+
+## Improve Copy Systematically
+
+Refine text across these common areas:
+
+### Error Messages
+**Bad**: "Error 403: Forbidden"
+**Good**: "You don't have permission to view this page. Contact your admin for access."
+
+**Bad**: "Invalid input"
+**Good**: "Email addresses need an @ symbol. Try: name@example.com"
+
+**Principles**:
+- Explain what went wrong in plain language
+- Suggest how to fix it
+- Don't blame the user
+- Include examples when helpful
+- Link to help/support if applicable
+
+### Form Labels & Instructions
+**Bad**: "DOB (MM/DD/YYYY)"
+**Good**: "Date of birth" (with placeholder showing format)
+
+**Bad**: "Enter value here"
+**Good**: "Your email address" or "Company name"
+
+**Principles**:
+- Use clear, specific labels (not generic placeholders)
+- Show format expectations with examples
+- Explain why you're asking (when not obvious)
+- Put instructions before the field, not after
+- Keep required field indicators clear
+
+### Button & CTA Text
+**Bad**: "Click here" | "Submit" | "OK"
+**Good**: "Create account" | "Save changes" | "Got it, thanks"
+
+**Principles**:
+- Describe the action specifically
+- Use active voice (verb + noun)
+- Match user's mental model
+- Be specific ("Save" is better than "OK")
+
+### Help Text & Tooltips
+**Bad**: "This is the username field"
+**Good**: "Choose a username. You can change this later in Settings."
+
+**Principles**:
+- Add value (don't just repeat the label)
+- Answer the implicit question ("What is this?" or "Why do you need this?")
+- Keep it brief but complete
+- Link to detailed docs if needed
+
+### Empty States
+**Bad**: "No items"
+**Good**: "No projects yet. Create your first project to get started."
+
+**Principles**:
+- Explain why it's empty (if not obvious)
+- Show next action clearly
+- Make it welcoming, not dead-end
+
+### Success Messages
+**Bad**: "Success"
+**Good**: "Settings saved! Your changes will take effect immediately."
+
+**Principles**:
+- Confirm what happened
+- Explain what happens next (if relevant)
+- Be brief but complete
+- Match the user's emotional moment (celebrate big wins)
+
+### Loading States
+**Bad**: "Loading..." (for 30+ seconds)
+**Good**: "Analyzing your data... this usually takes 30-60 seconds"
+
+**Principles**:
+- Set expectations (how long?)
+- Explain what's happening (when it's not obvious)
+- Show progress when possible
+- Offer escape hatch if appropriate ("Cancel")
+
+### Confirmation Dialogs
+**Bad**: "Are you sure?"
+**Good**: "Delete 'Project Alpha'? This can't be undone."
+
+**Principles**:
+- State the specific action
+- Explain consequences (especially for destructive actions)
+- Use clear button labels ("Delete project" not "Yes")
+- Don't overuse confirmations (only for risky actions)
+
+### Navigation & Wayfinding
+**Bad**: Generic labels like "Items" | "Things" | "Stuff"
+**Good**: Specific labels like "Your projects" | "Team members" | "Settings"
+
+**Principles**:
+- Be specific and descriptive
+- Use language users understand (not internal jargon)
+- Make hierarchy clear
+- Consider information scent (breadcrumbs, current location)
+
+## Apply Clarity Principles
+
+Every piece of copy should follow these rules:
+
+1. **Be specific**: "Enter email" not "Enter value"
+2. **Be concise**: Cut unnecessary words (but don't sacrifice clarity)
+3. **Be active**: "Save changes" not "Changes will be saved"
+4. **Be human**: "Oops, something went wrong" not "System error encountered"
+5. **Be helpful**: Tell users what to do, not just what happened
+6. **Be consistent**: Use same terms throughout (don't vary for variety)
+
+**NEVER**:
+- Use jargon without explanation
+- Blame users ("You made an error" → "This field is required")
+- Be vague ("Something went wrong" without explanation)
+- Use passive voice unnecessarily
+- Write overly long explanations (be concise)
+- Use humor for errors (be empathetic instead)
+- Assume technical knowledge
+- Vary terminology (pick one term and stick with it)
+- Repeat information (headers restating intros, redundant explanations)
+- Use placeholders as the only labels (they disappear when users type)
+
+## Verify Improvements
+
+Test that copy improvements work:
+
+- **Comprehension**: Can users understand without context?
+- **Actionability**: Do users know what to do next?
+- **Brevity**: Is it as short as possible while remaining clear?
+- **Consistency**: Does it match terminology elsewhere?
+- **Tone**: Is it appropriate for the situation?
+
+Remember: You're a clarity expert with excellent communication skills. Write like you're explaining to a smart friend who's unfamiliar with the product. Be clear, be helpful, be human.
+