claude-code-workflow 7.2.27 → 7.2.28

package/.claude/skills/team-uidesign/specs/ux-writing.md

@@ -0,0 +1,86 @@
+# UX Writing Standards
+
+Guidelines for all text content in UI components. From Impeccable's UX writing reference.
+
+---
+
+## Button Labels
+
+- **NEVER**: "OK", "Submit", "Yes", "No", "Cancel" (generic)
+- **ALWAYS**: verb + object — "Save changes", "Create account", "Delete message"
+- Destructive actions: name the destruction + show count — "Delete 5 items" not "Delete selected"
+- Primary CTA: specific benefit — "Start free trial" not "Get started"
+
+## Error Messages
+
+Formula: (1) What happened + (2) Why + (3) How to fix
+
+| Type | Template |
+|------|----------|
+| Format | "{Field} must be {format}. Example: {example}" |
+| Required | "{Field} is required to {reason}" |
+| Permission | "You don't have access to {resource}. Contact {who} for access" |
+| Network | "Couldn't reach the server. Check your connection and try again" |
+| Server | "Something went wrong on our end. Try again in a few minutes" |
+
+- Never blame user: "Please enter..." not "You entered..."
+- Never use codes alone: "Error 404" → "Page not found"
+- Be specific: "Password must be 8+ characters with a number" not "Invalid password"
+
+## Empty States
+
+Three components: (1) Acknowledge + (2) Explain value + (3) Provide action
+
+| Context | Example |
+|---------|---------|
+| First use | "No projects yet. Create your first project to get started. [Create project]" |
+| Search | "No results for '{query}'. Try a different search term or [browse all]" |
+| Filtered | "No items match these filters. [Clear filters]" |
+| Error | "Couldn't load items. [Try again]" |
+
+## Loading States
+
+- Be specific: "Saving your draft..." not "Loading..."
+- Multi-step: show progress — "Uploading (2 of 5 files)..."
+- Duration hint: "This usually takes about 30 seconds"
+
+## Confirmation Dialogs
+
+- Use sparingly — prefer undo over confirm
+- Title: what will happen — "Delete this project?"
+- Body: consequences — "This will permanently delete 12 files. This can't be undone."
+- Buttons: specific — "Delete project" / "Keep project" (not OK/Cancel)
+
+## Voice & Tone
+
+- **Voice**: consistent brand personality (professional/friendly/technical — choose one)
+- **Tone**: adapts to moment — cheerful for success, empathetic for errors, neutral for routine
+- Keep consistent: same word for same concept everywhere (delete/remove/trash → pick one)
+
+## Form Instructions
+
+- Show format with placeholder: `placeholder="john@example.com"`
+- Explain non-obvious fields with helper text below label
+- Mark optional fields (not required ones) — most fields should be required
+- Group related fields with clear section headers
+
+## Translation Planning
+
+| Language | Length vs English |
+|----------|------------------|
+| German | +30% |
+| French | +20% |
+| Finnish | +30-40% |
+| Chinese | -30% |
+| Japanese | -10-20% |
+
+- Design for longest language (German)
+- Never truncate translated text — allow wrapping
+- Avoid idioms and cultural references in source text
+
+## Redundant Copy Detection
+
+- Don't repeat visible information (heading ≠ first paragraph)
+- Labels describe the field, not restate the value
+- Tooltips add information, not repeat the label
+- If heading says it all, skip the intro paragraph

package/.claude/skills/team-ux-improve/SKILL.md

@@ -98,6 +98,9 @@ Execute built-in Phase 1 (task discovery) -> role Phase 2-4 -> built-in Phase 5
 ## Specs Reference
 
 - [specs/pipelines.md](specs/pipelines.md) — Pipeline definitions and task registry
+- [specs/design-standards.md](specs/design-standards.md) — Impeccable visual design standards
+- [specs/anti-patterns.md](specs/anti-patterns.md) — AI slop detection catalog (20 items)
+- [specs/heuristics.md](specs/heuristics.md) — Nielsen's 10 usability heuristics evaluation framework
 
 ## Session Directory
 

package/.claude/skills/team-ux-improve/roles/designer/role.md

@@ -101,6 +101,36 @@ const handleSubmit = async () => {
 | Text input for folder path | Add directory picker: `<input type="file" webkitdirectory />` |
 | No validation | Add validation rules and error messages |
 
+### Visual Design Solutions
+
+Reference `specs/design-standards.md` for target standards.
+
+| Issue | Solution Design |
+|-------|-----------------|
+| Pure black/white | Define OKLCH neutral scale tinted toward brand hue (chroma 0.005-0.01) |
+| Generic fonts | Select from: Instrument Sans, Plus Jakarta Sans, DM Sans, Space Grotesk, Fraunces |
+| No modular scale | Choose ratio (1.200 or 1.250), derive all sizes from base 16px |
+| Missing fluid sizing | Apply clamp() to display sizes (xl+): `clamp(1.25rem, 1.1rem + 0.5vw, 1.5rem)` |
+| All buttons primary | Define: primary (filled), secondary (outline/ghost), tertiary (text link) |
+| Monotonous spacing | Apply 4pt scale with rhythm: tight (4-8px), comfortable (16-24px), generous (48-96px) |
+| Nested cards | Flatten: remove inner card, use spacing + subtle border-bottom divider |
+| Layout animations | Replace with transform: translateX/Y/scale + opacity transitions |
+| No reduced-motion | Add global `@media (prefers-reduced-motion: reduce)` reset |
+| Missing focus-visible | Add `:focus-visible { outline: 2px solid var(--accent); outline-offset: 2px }` |
+| Bounce easing | Replace with ease-out-quart: `cubic-bezier(0.25, 1, 0.5, 1)` |
+| Missing interaction states | Define all 8 states per component with CSS selectors and ARIA attributes |
+
+### UX Writing Solutions
+
+| Issue | Solution |
+|-------|----------|
+| Generic button labels | Replace with verb+object: "Save changes", "Create project", "Delete 3 items" |
+| Error without guidance | Apply formula: what happened + why + how to fix. Template per error type |
+| Empty state without action | Three parts: acknowledge → explain value → provide action button |
+| Loading text generic | Be specific: "Saving your draft..." not "Loading..." Show progress for multi-step |
+| Confirmation too generic | Title: what will happen. Body: consequences. Buttons: specific actions (not OK/Cancel) |
+| Redundant copy | Remove intro paragraph if heading is self-explanatory. Labels ≠ values |
+
 ## Phase 4: Design Document Generation
 
 1. Generate implementation guide for each issue and write to `<session>/artifacts/design-guide.md`

package/.claude/skills/team-ux-improve/roles/diagnoser/role.md

@@ -69,6 +69,20 @@ For each issue from scan report:
 | No error handling | Missing catch block | Add try/catch with error state |
 | Race condition | Multiple concurrent requests | Add request cancellation or debounce |
 
+### Visual Design Diagnosis
+
+| Pattern | Root Cause | Fix Strategy |
+|---------|------------|--------------|
+| Pure black/white colors | No intentional color system | Introduce OKLCH palette with tinted neutrals |
+| Generic font usage | Default font selection | Replace with distinctive alternatives from recommended list |
+| Missing interaction states | Incomplete component design | Add all 8 states per Impeccable spec |
+| Layout animations | Wrong animation properties | Switch to transform + opacity, add will-change via JS |
+| No reduced-motion | Accessibility oversight | Add @media (prefers-reduced-motion: reduce) global query |
+| All buttons primary | No hierarchy design | Establish primary/secondary/tertiary button system |
+| Monotonous spacing | No spacing system | Implement 4pt scale with rhythm variation |
+| Nested cards | Over-containment | Flatten to spacing + dividers |
+| Missing focus-visible | Outdated focus handling | Replace :focus with :focus-visible, add ring spec |
+
 ## Phase 4: Diagnosis Report
 
 1. Generate root cause analysis for each issue and write to `<session>/artifacts/diagnosis.md`
@@ -87,7 +101,8 @@ If new root cause patterns discovered:
               pattern_types: {
                 state_management: <count>,
                 event_binding: <count>,
-                async_handling: <count>
+                async_handling: <count>,
+                visual_design: <count>
               }
             })
    ```

package/.claude/skills/team-ux-improve/roles/scanner/role.md

@@ -63,6 +63,48 @@ Scan strategy:
 | Input without validation | Form input without validation rules | Low |
 | Missing file selector | Text input for file/folder path without picker | Medium |
 
+### Visual Design Scanning
+
+In addition to interaction issues, scan for visual design quality problems.
+Reference `specs/design-standards.md` and `specs/anti-patterns.md`.
+
+| Category | Detection Pattern | Severity |
+|----------|-------------------|----------|
+| AI color palette | Cyan (#00d4ff, #06b6d4), purple-blue gradients on dark | High |
+| Pure black/white | #000, #fff, rgb(0,0,0), rgb(255,255,255) as primary colors | High |
+| Generic font | Inter, Roboto, Open Sans, Arial as primary font-family | Medium |
+| All buttons primary | Every button has same fill treatment, no hierarchy | High |
+| Nested cards | border/shadow inside border/shadow containers | Medium |
+| No focus-visible | Using :focus or outline:none without :focus-visible | High |
+| Layout animations | Animating width/height/margin/padding | Medium |
+| No reduced-motion | Missing @media(prefers-reduced-motion) | Medium |
+| Bounce easing | cubic-bezier with negative values, spring/bounce | Medium |
+| Monotonous spacing | >70% same padding/margin value | Low |
+| Missing 8 states | Interactive elements with <5 defined states | Medium |
+| Glassmorphism overuse | backdrop-filter:blur on >2 components | Medium |
+| Generic button labels | "OK", "Submit", "Yes/No", "Cancel" without specific verb+object | Medium |
+| Error messages without fix guidance | Error shows "Something went wrong" with no next step | High |
+| Empty states without action | Data list shows "No data" without create/import action | Medium |
+| Redundant copy | Heading text repeated in first paragraph (>50% word overlap) | Low |
+
+### Heuristic UX Scanning
+
+Apply Nielsen's 10 usability heuristics as a structured scan checklist.
+Reference: `specs/heuristics.md`
+
+| Heuristic | What to Check | Severity |
+|-----------|---------------|----------|
+| Visibility of system status | Loading indicators, progress bars, state feedback, timestamps | High |
+| Match between system and real world | Jargon-free labels, familiar metaphors, logical ordering | Medium |
+| User control and freedom | Undo/redo, back navigation, cancel actions, escape from modals | High |
+| Consistency and standards | Same terms/icons for same actions, platform conventions | Medium |
+| Error prevention | Confirmation for destructive actions, input validation, disable invalid options | High |
+| Recognition over recall | Visible options, recent items, search suggestions, breadcrumbs | Medium |
+| Flexibility and efficiency | Keyboard shortcuts, power-user features, bulk actions | Low |
+| Aesthetic and minimalist design | Information density, noise reduction, visual hierarchy | Medium |
+| Help users recover from errors | Error messages with fix guidance (what+why+fix), retry options | High |
+| Help and documentation | Tooltips, onboarding, contextual help, empty states with guidance | Low |
+
 For each component file:
 1. Read file content
 2. Scan for interaction patterns using Grep
@@ -73,7 +115,7 @@ For each component file:
 ## Phase 4: Issue Report Generation
 
 1. Classify issues by severity (High/Medium/Low)
-2. Group by category (unresponsive, missing feedback, state issues, input UX)
+2. Group by category (unresponsive, missing feedback, state issues, input UX, visual design)
 3. Generate structured report and write to `<session>/artifacts/scan-report.md`
 4. Share state via team_msg:
    ```

package/.claude/skills/team-ux-improve/specs/anti-patterns.md

@@ -0,0 +1,103 @@
+# AI Slop Detection Catalog
+
+20 visual anti-patterns commonly produced by AI code generation. Use during scanning to flag design quality issues.
+
+### 1. AI Color Palette
+- **Pattern**: Cyan (#00d4ff, #06b6d4), purple-blue gradients on dark backgrounds as default aesthetic
+- **Detection**: Search for cyan/teal hex values, linear-gradient with blue-purple stops on dark bg
+- **Severity**: P1
+
+### 2. Gradient Text
+- **Pattern**: `background-clip: text` + `-webkit-text-fill-color: transparent` on headings or metric values
+- **Detection**: Grep for `background-clip:\s*text` or `-webkit-background-clip:\s*text`
+- **Severity**: P1
+
+### 3. Default Dark Mode + Glow
+- **Pattern**: Dark background (#0a0a0a, #111) with neon accent colors and box-shadow glow effects
+- **Detection**: Dark bg colors + box-shadow with colored spread on interactive elements
+- **Severity**: P2
+
+### 4. Glassmorphism Everywhere
+- **Pattern**: `backdrop-filter: blur()` applied to more than 2 components
+- **Detection**: Count occurrences of `backdrop-filter:\s*blur` across components
+- **Severity**: P1
+
+### 5. Hero Metric Layout
+- **Pattern**: Large number + small label arranged in card grid, dashboard-style metrics as default layout
+- **Detection**: Pattern of large font-size number + small text label repeated 3+ times in grid
+- **Severity**: P2
+
+### 6. Identical Card Grids
+- **Pattern**: 3+ cards with identical size, structure, and visual weight
+- **Detection**: Repeated card components with same dimensions and no visual differentiation
+- **Severity**: P2
+
+### 7. Nested Cards
+- **Pattern**: Border/shadow container inside another border/shadow container
+- **Detection**: Card component rendered inside another card component, nested border-radius + box-shadow
+- **Severity**: P2
+
+### 8. Generic Fonts
+- **Pattern**: Inter, Roboto, Open Sans, Lato, Montserrat, Arial as primary font-family
+- **Detection**: Grep font-family declarations for generic font names
+- **Severity**: P2
+
+### 9. Rounded Rect + Generic Shadow
+- **Pattern**: `border-radius: 8-16px` + `box-shadow: 0 1-4px ...` on more than 5 elements
+- **Detection**: Count elements with both border-radius and box-shadow, flag if >5
+- **Severity**: P3
+
+### 10. Large Icons Above Every Heading
+- **Pattern**: Decorative icon/emoji placed above section headings, repeated 3+ times
+- **Detection**: Icon component or SVG immediately preceding heading elements, 3+ occurrences
+- **Severity**: P2
+
+### 11. One-Side Border Accent
+- **Pattern**: `border-left: 3-4px solid <accent>` as visual accent on cards/sections
+- **Detection**: Grep for `border-left:\s*\d+px\s+solid` repeated across components
+- **Severity**: P3
+
+### 12. Decorative Sparklines
+- **Pattern**: Tiny inline charts without axis labels, data values, or interactive tooltips
+- **Detection**: Small chart components (<100px height) without label/tooltip props
+- **Severity**: P2
+
+### 13. Bounce/Elastic Easing
+- **Pattern**: `cubic-bezier` with negative control point values, spring/bounce animation keywords
+- **Detection**: Grep for `cubic-bezier\([^)]*-` or animation names containing bounce/spring/elastic
+- **Severity**: P2
+
+### 14. Redundant Copy
+- **Pattern**: Heading text restated in immediately following body paragraph with >50% word overlap
+- **Detection**: Compare heading text with first paragraph text for word overlap
+- **Severity**: P3
+
+### 15. All Buttons Primary
+- **Pattern**: Every button uses same filled/accent treatment, no visual hierarchy
+- **Detection**: All button variants resolve to same background-color, no secondary/tertiary variants
+- **Severity**: P1
+
+### 16. Everything Centered
+- **Pattern**: Body text centered (`text-align: center`), more than 60% of sections centered
+- **Detection**: Count `text-align: center` on non-heading, non-hero elements
+- **Severity**: P2
+
+### 17. Same Spacing Everywhere
+- **Pattern**: >70% of padding/margin values are identical (e.g., all `p-4` or `p-6`)
+- **Detection**: Extract padding/margin values, check distribution uniformity
+- **Severity**: P2
+
+### 18. Monospace as Tech Aesthetic
+- **Pattern**: Monospace font applied to non-code elements (headings, labels, navigation)
+- **Detection**: `font-family: monospace` or code font on non-`<code>`/`<pre>` elements
+- **Severity**: P3
+
+### 19. Modal Overuse
+- **Pattern**: More than 3 modal dialogs for non-critical interactions (settings, confirmations, info)
+- **Detection**: Count modal/dialog component usages, check trigger context
+- **Severity**: P3
+
+### 20. Pure Black/White
+- **Pattern**: #000, #fff, rgb(0,0,0), rgb(255,255,255) as primary background or text colors
+- **Detection**: Grep for exact #000, #fff, rgb(0,0,0), rgb(255,255,255) in color/background properties
+- **Severity**: P1

package/.claude/skills/team-ux-improve/specs/design-standards.md

@@ -0,0 +1,54 @@
+# Visual Design Standards
+
+Reference for visual design quality detection. Scanner and diagnoser use these standards to identify design issues.
+
+## Color Standards
+
+- **OKLCH** for perceptually uniform palettes
+- **Tinted neutrals**: chroma 0.005-0.01, never pure gray (#808080) or pure black/white (#000, #fff)
+- **60-30-10 rule**: 60% neutral, 30% secondary, 10% accent
+- **WCAG AA contrast**: normal text 4.5:1, large text 3:1, UI components 3:1
+- **Text on colored backgrounds**: use `color-mix(in oklch, ...)` not gray text
+
+## Typography Standards
+
+- **Avoid generic fonts**: Inter, Roboto, Open Sans, Lato, Montserrat, Arial
+- **Modular scale** (choose one ratio consistently): 1.125, 1.200, 1.250, 1.333
+- **Fluid sizing**: `clamp()` for display text (xl and above)
+- **Line height**: body 1.5, headings 1.2, small text 1.6
+- **Reading width**: `max-width: 65ch`
+- **Font loading**: `font-display: swap`
+
+## Spacing Standards
+
+- **4pt base scale**: 0, 4, 8, 12, 16, 20, 24, 32, 40, 48, 64, 96 px
+- **Rhythm variation**: tight (4-8px), comfortable (16-24px), generous (48-96px)
+- **Sibling spacing**: `gap` over `margin`
+- **No nested cards**. Touch targets: 44x44px min
+
+## Motion Standards
+
+- **Animate ONLY**: transform, opacity, clip-path, background-color, color, box-shadow, filter
+- **NEVER animate**: width, height, top, left, margin, padding
+- **Easing**: ease-out-quart `cubic-bezier(0.25, 1, 0.5, 1)` default. No bounce/elastic/linear
+- **Duration**: instant 100ms, fast 150ms, normal 250ms, slow 400ms
+- **Reduced motion**: `@media (prefers-reduced-motion: reduce)` REQUIRED
+
+## 8 Interaction States
+
+| State | CSS | Requirement |
+|-------|-----|-------------|
+| Default | -- | Base appearance |
+| Hover | `:hover` in `@media(hover:hover)` | Subtle change |
+| Focus | `:focus-visible` | 2px solid accent, offset 2px, 3:1 contrast |
+| Active | `:active` | Scale(0.97) or darker |
+| Disabled | `[disabled]` | Opacity 0.5 |
+| Loading | `[aria-busy]` | Spinner/skeleton |
+| Error | `[aria-invalid]` | Red border + message |
+| Success | custom | Green check |
+
+## Visual Hierarchy
+
+- **Squint test**: blur page, identify top 2 elements + groupings
+- **1 primary CTA** per viewport
+- **Progressive disclosure**: reveal complexity on demand

package/.claude/skills/team-ux-improve/specs/heuristics.md

@@ -0,0 +1,88 @@
+# Nielsen's 10 Usability Heuristics
+
+Structured evaluation framework for UX scanning. Score each 0-4.
+
+## 1. Visibility of System Status
+The system should always keep users informed about what is going on.
+- Loading indicators for async operations (> 200ms)
+- Progress bars for multi-step processes
+- State feedback (saved, syncing, error)
+- Timestamps on data ("Updated 5 minutes ago")
+- Active state indicators (selected tab, current page)
+
+## 2. Match Between System and Real World
+Speak the user's language, not technical jargon.
+- Labels use familiar words (not internal terms)
+- Icons match real-world metaphors
+- Information appears in natural/logical order
+- Dates, numbers, currencies in locale format
+
+## 3. User Control and Freedom
+Users need a clearly marked "emergency exit."
+- Undo/redo for destructive or complex actions
+- Back/cancel navigation always available
+- Escape key closes modals/popovers
+- Clear way to deselect, clear filters, reset
+
+## 4. Consistency and Standards
+Same words and actions should mean the same thing.
+- One term per concept (delete/remove/trash → pick one)
+- Same icon for same action across pages
+- Follow platform conventions (links underlined, × means close)
+- Consistent placement of actions (save always top-right, etc.)
+
+## 5. Error Prevention
+Better to prevent errors than show good error messages.
+- Confirmation for destructive actions (with undo preferred)
+- Input validation on blur (not just submit)
+- Disable invalid options (gray out, not hide)
+- Type-ahead/autocomplete for known-value fields
+- Character counts for limited fields
+
+## 6. Recognition Rather Than Recall
+Minimize user memory load.
+- Show options visibly (don't require memorization)
+- Recent items, favorites, search suggestions
+- Breadcrumbs for navigation context
+- Inline help/tooltips for non-obvious fields
+- Persistent important info (don't hide behind clicks)
+
+## 7. Flexibility and Efficiency of Use
+Accelerators for power users without confusing beginners.
+- Keyboard shortcuts for frequent actions
+- Bulk actions (select all, batch edit)
+- Customizable views/layouts
+- Search/filter as primary navigation for large datasets
+
+## 8. Aesthetic and Minimalist Design
+Every extra unit of information competes with relevant units.
+- Remove decorative elements that don't aid comprehension
+- Progressive disclosure (summary → detail on demand)
+- Visual hierarchy: clear primary, secondary, tertiary
+- Information density appropriate for use case
+
+## 9. Help Users Recognize, Diagnose, and Recover from Errors
+Error messages should be expressed in plain language.
+- Formula: what happened + why + how to fix
+- No error codes without explanation
+- Suggest specific corrective action
+- Preserve user input on error (don't clear forms)
+- Retry option for network/server errors
+
+## 10. Help and Documentation
+Easy to search, focused on user's task.
+- Contextual help (tooltips, info icons)
+- Onboarding for first-time users
+- Empty states with guidance and action
+- Keyboard shortcut reference
+- FAQ/search for complex features
+
+## Severity Scale
+
+| Rating | Description |
+|--------|-------------|
+| 0 | Not a usability problem |
+| 1 | Cosmetic — fix if time permits |
+| 2 | Minor — low priority fix |
+| 3 | Major — important to fix, high priority |
+| 4 | Catastrophe — must fix before release |

package/.claude/skills/team-ux-improve/wisdom/anti-patterns/common-ux-pitfalls.md

@@ -4,14 +4,46 @@
 - Buttons without loading states during async operations
 - Missing error handling with user feedback
 - State changes without visual updates
-- Double-click vulnerabilities
-
-## State Issues
-- Stale data after mutations
-- Race conditions in async operations
-- Missing rollback for failed optimistic updates
-
-## Feedback Issues
+- Double-click vulnerabilities (missing debounce)
+- No disabled state during processing
 - Silent failures without user notification
 - Generic error messages without actionable guidance
 - Missing confirmation for destructive actions
+- No empty state placeholder for data lists
+- Input without validation rules or inline feedback
+
+## State Management Issues
+- Stale data after mutations (direct array/object mutation)
+- Race conditions in async operations (no cancellation)
+- Missing rollback for failed optimistic updates
+- Stale closure capturing old state value
+- Missing loading/error/success state tracking
+
+## Visual Design Anti-Patterns (AI Slop)
+- AI Color Palette: cyan-on-dark, purple gradients (zero design intent)
+- Gradient text: background-clip: text as emphasis crutch
+- Glassmorphism everywhere: backdrop-filter as default aesthetic
+- All Buttons Primary: no visual hierarchy, every button filled
+- Pure Black/White: #000/#fff without tint (harsh, sterile)
+- Generic fonts: Inter, Roboto as defaults (forgettable)
+- Identical card grids: all items same visual weight
+- Nested cards: cards inside cards creating noise
+- Same spacing everywhere: no rhythm variation
+- Bounce/elastic easing: dated animation feel
+- Everything centered: including body text
+
+## Motion Issues
+- Layout animations (width/height/margin/padding triggers)
+- No reduced-motion query (@media prefers-reduced-motion)
+- CSS will-change set permanently (GPU waste)
+- ease/linear as default easing (unnatural)
+- Stagger exceeding 500ms total
+
+## Accessibility Issues
+- outline: none without :focus-visible replacement
+- Missing :focus-visible (using bare :focus)
+- Color-only state indication
+- Touch targets < 44px
+- No skip links
+- Placeholder used as label
+- Missing aria-describedby for error messages

package/.claude/skills/team-ux-improve/wisdom/patterns/state-management.md

@@ -1,14 +1,34 @@
 # State Management Patterns
 
-## Local Component State
-- Use for UI-only state (open/closed, hover, focus)
-- Keep close to where it's used
-
-## Shared State
-- Lift state to lowest common ancestor
-- Use context or state management library for deep trees
-
-## Async State
-- Track loading, error, and success states
-- Handle race conditions with request cancellation
-- Implement retry logic with exponential backoff
+## Reactive Update Rules
+- NEVER mutate arrays/objects directly
+- React: use spread operator, filter/map for new references
+- Vue: use ref() for primitives, reactive() for objects, computed() for derived
+- Always trigger re-render through proper state API
+
+## Async State Pattern
+```
+const [data, setData] = useState(null);
+const [loading, setLoading] = useState(false);
+const [error, setError] = useState(null);
+
+// Always: loading -> success/error -> cleanup
+```
+
+## Race Condition Prevention
+- AbortController for fetch cancellation
+- Debounce for search/filter inputs (250-500ms)
+- Latest-wins pattern for concurrent requests
+- Disable trigger during processing
+
+## Optimistic Updates
+- Update UI immediately
+- Track pending state
+- Rollback on failure with error notification
+- Never lose user data silently
+
+## Form State
+- Controlled inputs (React) / v-model (Vue)
+- Validation on blur + on submit
+- Error clearing on re-input
+- Dirty tracking for unsaved changes warning

package/.claude/skills/team-ux-improve/wisdom/patterns/ui-feedback.md

@@ -1,16 +1,40 @@
 # UI Feedback Patterns
 
 ## Loading States
-- Use skeleton loaders for content areas
-- Disable buttons during async operations
-- Show progress indicators for long operations
+- Button: set disabled + aria-busy="true", show spinner, restore on complete
+- Page: skeleton screens (prefer over spinners for content areas)
+- Inline: progress indicator for multi-step operations
+- Duration: show loading after 200ms delay (avoid flash for fast operations)
 
-## Error Handling
-- Display errors inline when possible
-- Provide actionable error messages
-- Allow retry for transient failures
+## Error States
+- Form: inline validation with aria-invalid + aria-describedby
+- API: toast/snackbar for non-blocking, inline for blocking errors
+- Error message: specific, actionable (not "Something went wrong")
+- Visual: red border on input, error icon, error text below
 
-## Success Feedback
-- Toast notifications for non-critical successes
-- Inline confirmation for critical actions
-- Auto-dismiss non-critical notifications
+## Success States
+- Form submit: success message + next action guidance
+- CRUD: optimistic update with subtle confirmation
+- Duration: success message visible 3-5 seconds
+
+## Empty States
+- Data list: illustration + message + primary action
+- Search: "No results" + suggestions
+- First use: onboarding guidance
+
+## Focus Feedback
+- :focus-visible only (not bare :focus)
+- Ring: 2px solid accent, offset 2px
+- Contrast: 3:1 against adjacent colors
+- Custom for dark backgrounds: lighter ring color
+
+## Hover Feedback
+- Wrap in @media(hover:hover) for touch safety
+- Subtle: background opacity change or slight color shift
+- Duration: 100-150ms transition
+- Cursor: pointer for clickable, not-allowed for disabled
+
+## Active Feedback
+- Scale: transform: scale(0.97) for physical feel
+- Or: darker background shade
+- Duration: instant (< 50ms feel)