@tinkcarlos/skillora 0.2.0

package/.claude/skills/frontend-design/references/ux-guidelines.md

@@ -0,0 +1,640 @@
+# UX Guidelines Reference
+
+98 essential UX best practices, anti-patterns, and accessibility rules.
+
+---
+
+## Navigation & Structure (15 guidelines)
+
+### 1. Primary Navigation
+- Maximum 7±2 items in main navigation
+- Use clear, action-oriented labels
+- Highlight current page/section
+- Mobile: Use hamburger menu with clear open/close states
+
+### 2. Breadcrumbs
+- Show on all pages beyond homepage (>2 levels deep)
+- Use ">" or "/" as separator
+- Make all items except current clickable
+- Current item should not be a link
+
+### 3. Footer Navigation
+- Include sitemap-style links for SEO
+- Group by category (Company, Product, Resources, Legal)
+- Include contact info and social links
+- Repeat key CTAs
+
+### 4. Search
+- Place in consistent location (top right common)
+- Show clear search icon (magnifying glass)
+- Provide autocomplete suggestions
+- Show "No results" with helpful alternatives
+
+### 5. Back Navigation
+- Always provide clear back/return path
+- Preserve scroll position when returning
+- Use browser back button correctly
+- In modals: clear close button
+
+### 6. Page Structure
+- Use semantic HTML (header, nav, main, aside, footer)
+- Implement skip-to-content link
+- Logical heading hierarchy (H1 → H2 → H3)
+- One H1 per page
+
+### 7. Loading States
+- Show skeleton screens instead of spinners
+- Indicate progress for long operations
+- Preserve layout during loading
+- Show partial content when available
+
+### 8. Empty States
+- Explain what belongs in empty area
+- Provide clear action to populate
+- Use friendly illustrations (optional)
+- Never show truly blank screens
+
+### 9. Error Pages (404/500)
+- Maintain site branding and navigation
+- Explain what happened in plain language
+- Provide clear next steps (home, search, contact)
+- Log errors for monitoring
+
+### 10. Pagination vs Infinite Scroll
+- **Pagination**: Better for goal-oriented browsing, SEO
+- **Infinite Scroll**: Better for discovery, social feeds
+- Always show load progress
+- Provide "Back to top" button
+
+### 11. Tabs vs Accordion
+- **Tabs**: For parallel content comparison, desktop
+- **Accordion**: For sequential content, FAQ, mobile
+- Show one item open by default
+- Allow opening multiple accordion items
+
+### 12. Modal Usage
+- Use sparingly for critical actions
+- Close on overlay click and Escape key
+- Trap focus inside modal
+- Return focus on close
+
+### 13. Sidebar Navigation
+- Collapsible for desktop flexibility
+- Highlight active section
+- Group related items
+- Show icons for quick scanning
+
+### 14. Progressive Disclosure
+- Show only necessary info initially
+- Use "Show more" or expanding sections
+- Don't hide critical information
+- Reduce cognitive load
+
+### 15. Content Hierarchy
+- Most important content above fold
+- Use F-pattern or Z-pattern layouts
+- Break up long content with headings
+- Use whitespace to group related items
+
+---
+
+## Forms & Input (20 guidelines)
+
+### 16. Form Layout
+- One column forms perform best
+- Group related fields with fieldsets
+- Left-align labels (or top-align on mobile)
+- 8-16px spacing between fields
+
+### 17. Label Placement
+- **Top-aligned**: Fastest completion, best for mobile
+- **Left-aligned**: Better scanability, longer forms
+- **Inline/Placeholder**: Avoid (disappears on focus)
+
+### 18. Required Fields
+- Mark required fields clearly (asterisk + "required")
+- Or mark optional fields instead
+- Don't make everything required
+- Explain requirements upfront
+
+### 19. Input Field Sizing
+- Match input width to expected content
+- Phone: ~150px, Email: ~250px, Text: ~400px
+- Full width on mobile
+- Consistent heights within form
+
+### 20. Placeholder Text
+- Use for format hints, not labels
+- Gray color to distinguish from entered text
+- Disappears on focus (never sole label)
+- Example: "e.g., john@example.com"
+
+### 21. Input Validation
+- Validate on blur, not on every keystroke
+- Show errors inline next to field
+- Use red for errors, green for success
+- Explain how to fix the error
+
+### 22. Error Messages
+- Be specific: "Password must be 8+ characters"
+- Not generic: "Invalid input"
+- Place below/beside the field
+- Don't clear the field on error
+
+### 23. Success States
+- Confirm successful submission clearly
+- Show checkmark or success message
+- Provide next steps
+- Don't leave user wondering "did it work?"
+
+### 24. Password Fields
+- Show/hide password toggle
+- Display strength meter
+- Show requirements upfront
+- Allow paste in password fields
+
+### 25. Select vs Radio
+- **Radio**: 2-5 options, all visible
+- **Select**: 5+ options, space constrained
+- Never mix in same form
+- Custom selects: maintain accessibility
+
+### 26. Checkbox vs Toggle
+- **Checkbox**: Multiple selections, forms
+- **Toggle**: Binary on/off, instant effect
+- Checkbox needs submit button
+- Toggle takes effect immediately
+
+### 27. Date Input
+- Use native date picker when possible
+- Allow manual entry in common formats
+- Show expected format
+- Consider date range presets
+
+### 28. File Upload
+- Show accepted formats and size limits
+- Drag and drop support
+- Progress indicator for large files
+- Preview uploaded files
+
+### 29. Multi-step Forms
+- Show progress indicator
+- Allow back navigation
+- Save progress between steps
+- Summarize before final submit
+
+### 30. Autofill & Autocomplete
+- Use correct input types for autofill
+- name="email", autocomplete="email"
+- Don't disable browser autofill
+- Provide smart suggestions
+
+### 31. Form Submit Button
+- Clear label: "Create Account" not "Submit"
+- Disable during submission
+- Show loading state
+- Single primary action button
+
+### 32. Inline Editing
+- Clear edit mode indication
+- Save on blur or explicit save button
+- Cancel option to revert
+- Show what's being edited
+
+### 33. Search/Filter Forms
+- Apply filters immediately (no submit)
+- Show active filter count
+- Clear all filters option
+- Persist filters in URL
+
+### 34. Form Accessibility
+- All inputs need visible labels
+- Error messages linked to fields
+- Tab order logical
+- Screen reader tested
+
+### 35. Mobile Form Optimization
+- Appropriate keyboard types (email, number, tel)
+- Large touch targets (44x44px minimum)
+- Minimize typing required
+- Use device capabilities (camera, location)
+
+---
+
+## Buttons & CTAs (15 guidelines)
+
+### 36. Button Hierarchy
+- **Primary**: Main action, one per view
+- **Secondary**: Supporting actions
+- **Tertiary/Ghost**: Cancel, back, less important
+
+### 37. Button States
+- Default, Hover, Active, Focus, Disabled
+- Visible focus ring for accessibility
+- Disabled: reduced opacity + cursor: not-allowed
+- Loading state for async actions
+
+### 38. Button Labels
+- Use action verbs: "Download", "Save", "Delete"
+- Avoid vague: "Click Here", "Submit"
+- Include context: "Add to Cart", "Start Free Trial"
+- Consistent terminology throughout
+
+### 39. Button Size
+- Minimum touch target: 44x44px
+- Desktop: 36-48px height typical
+- Consistent padding: 12-24px horizontal
+- Full width on mobile for primary actions
+
+### 40. Icon Buttons
+- Always include tooltip/label
+- aria-label for accessibility
+- Standard icons for common actions
+- Text label when space allows
+
+### 41. Destructive Actions
+- Red color for delete/remove
+- Confirmation dialog required
+- Option to undo when possible
+- Clear warning message
+
+### 42. Call-to-Action (CTA)
+- One primary CTA per section
+- High contrast, prominent placement
+- Action-oriented text
+- Above the fold for key CTAs
+
+### 43. Button Groups
+- Related actions grouped together
+- Clear visual connection
+- Consistent spacing (4-8px)
+- Logical order (cancel before submit)
+
+### 44. Toggle Buttons
+- Clear on/off state
+- Immediate visual feedback
+- Accessible state announcement
+- Consider using actual toggle for settings
+
+### 45. Floating Action Button (FAB)
+- Single primary action per screen
+- Bottom right placement (Material Design)
+- 56px size, consistent shadow
+- Extended FAB with label for clarity
+
+### 46. Button Loading States
+- Replace text with spinner
+- Or show spinner beside text
+- Disable during loading
+- Maintain button size
+
+### 47. Ghost/Text Buttons
+- Use for secondary actions
+- Clear hover state
+- Adequate padding for touch
+- Don't overuse—reduces clickability
+
+### 48. Split Buttons
+- Primary action + dropdown
+- Clear separation indicator
+- Accessible dropdown
+- Use sparingly
+
+### 49. Button Placement
+- Primary action on right (LTR)
+- Or at bottom for forms
+- Consistent throughout app
+- Close/Cancel on left
+
+### 50. Disabled Buttons
+- Explain why disabled
+- Use tooltip or helper text
+- Don't completely hide
+- 0.5 opacity + no pointer events
+
+---
+
+## Feedback & Communication (15 guidelines)
+
+### 51. Toast Notifications
+- Brief, dismissible messages
+- Auto-dismiss after 3-5 seconds
+- Position: top-right or bottom-center
+- Allow manual dismiss
+
+### 52. Alert Types
+- **Info** (blue): Neutral information
+- **Success** (green): Completed actions
+- **Warning** (yellow): Potential issues
+- **Error** (red): Something went wrong
+
+### 53. Inline Feedback
+- Show feedback near the action
+- Don't rely only on color
+- Include icon + text
+- Persist until acknowledged or resolved
+
+### 54. Progress Indicators
+- Determinate: Known duration (progress bar)
+- Indeterminate: Unknown duration (spinner)
+- Show percentage when possible
+- Estimate time remaining for long tasks
+
+### 55. Skeleton Screens
+- Match content layout
+- Subtle animation (pulse or shimmer)
+- Replace with content progressively
+- Better UX than spinners
+
+### 56. Confirmation Messages
+- Confirm important actions
+- "Are you sure?" with consequences
+- Clear accept/cancel buttons
+- Show what will be affected
+
+### 57. Undo Functionality
+- Offer undo for destructive actions
+- Toast with undo button
+- Time-limited (5-10 seconds)
+- Better than confirmation dialogs
+
+### 58. Help Text
+- Place near relevant fields
+- Persistent (don't hide on focus)
+- Brief and scannable
+- Link to detailed help if needed
+
+### 59. Tooltips
+- Hover/focus triggered
+- Brief content (1-2 lines)
+- Consistent placement
+- Touch: tap to show, tap elsewhere to dismiss
+
+### 60. Empty Data Handling
+- Friendly illustration (optional)
+- Clear explanation
+- Action to add data
+- Don't show "0 results" tables
+
+### 61. System Status
+- Always indicate system state
+- Loading, saving, synced indicators
+- Connection status (online/offline)
+- Background task progress
+
+### 62. Micro-interactions
+- Button press feedback
+- Form submission animations
+- Toggle state changes
+- Delightful but not distracting
+
+### 63. Error Recovery
+- Help users recover from errors
+- Don't lose their input
+- Suggest alternatives
+- Provide contact support option
+
+### 64. Onboarding
+- Progressive disclosure
+- Skippable but accessible later
+- Highlight key features
+- Don't overwhelm
+
+### 65. Copy/Microcopy
+- Human, not robotic
+- Consistent terminology
+- Culturally appropriate
+- Test with real users
+
+---
+
+## Accessibility (18 guidelines)
+
+### 66. Color Contrast
+- 4.5:1 minimum for normal text
+- 3:1 for large text (18pt+)
+- Don't rely on color alone
+- Test with contrast checkers
+
+### 67. Focus Indicators
+- Visible focus ring (2px+)
+- High contrast from background
+- Never remove focus styles
+- Custom focus styles allowed
+
+### 68. Keyboard Navigation
+- All interactive elements focusable
+- Logical tab order
+- No keyboard traps
+- Skip links for main content
+
+### 69. Screen Reader Support
+- Semantic HTML first
+- ARIA labels when needed
+- Alt text for images
+- Test with screen readers
+
+### 70. Alt Text
+- Describe image content/function
+- Decorative images: alt=""
+- Complex images: long description
+- Don't start with "Image of..."
+
+### 71. Link Text
+- Descriptive link text
+- Avoid "click here", "read more"
+- Underline links in body text
+- Distinguish from buttons
+
+### 72. Form Labels
+- Every input needs a label
+- Labels associated with inputs (for/id)
+- Required field indication
+- Error states linked to inputs
+
+### 73. ARIA Usage
+- Use native HTML first
+- ARIA supplements, doesn't replace
+- Test ARIA implementations
+- Don't overuse ARIA
+
+### 74. Touch Targets
+- Minimum 44x44px
+- 8px minimum spacing
+- Adequate padding, not just icon size
+- Consider thumb zones on mobile
+
+### 75. Text Sizing
+- Allow 200% zoom without breaking
+- Use relative units (rem, em)
+- Don't disable zoom
+- Test text scaling
+
+### 76. Motion & Animation
+- Respect prefers-reduced-motion
+- Avoid flashing content
+- Provide pause/stop for auto-play
+- No content-conveying motion
+
+### 77. Reading Order
+- DOM order matches visual order
+- Logical heading structure
+- Content accessible without CSS
+- Test with screen reader
+
+### 78. Language
+- Set page language (lang attribute)
+- Mark language changes in content
+- Plain language preferred
+- Reading level appropriate
+
+### 79. Timing
+- Allow enough time to read/act
+- Warn before timeouts
+- Allow time extensions
+- Save progress frequently
+
+### 80. Cognitive Load
+- Clear, simple language
+- Break up complex tasks
+- Provide help and documentation
+- Consistent patterns
+
+### 81. Testing Accessibility
+- Automated tools (axe, WAVE)
+- Manual keyboard testing
+- Screen reader testing
+- User testing with disabilities
+
+### 82. WCAG Compliance
+- Level A: Minimum requirement
+- Level AA: Recommended standard
+- Level AAA: Enhanced accessibility
+- Know your legal requirements
+
+### 83. Accessible Media
+- Captions for video
+- Transcripts for audio
+- Audio description for video
+- Player controls accessible
+
+---
+
+## Performance & Technical (15 guidelines)
+
+### 84. Page Load
+- First Contentful Paint < 1.8s
+- Largest Contentful Paint < 2.5s
+- Show loading skeleton immediately
+- Prioritize above-fold content
+
+### 85. Interaction Response
+- < 100ms feels instant
+- 100-300ms noticeable
+- 300ms+ show loading indicator
+- First Input Delay < 100ms
+
+### 86. Image Optimization
+- Use modern formats (WebP, AVIF)
+- Lazy load below-fold images
+- Provide srcset for responsive
+- Compress appropriately
+
+### 87. Layout Stability
+- Cumulative Layout Shift < 0.1
+- Reserve space for images
+- Reserve space for ads
+- No late-loading content push
+
+### 88. Offline Support
+- Service worker for reliability
+- Cache critical assets
+- Graceful offline behavior
+- Sync when reconnected
+
+### 89. Mobile Optimization
+- Responsive design required
+- Touch-friendly interactions
+- Appropriate input types
+- Device testing
+
+### 90. Progressive Enhancement
+- Core functionality without JS
+- Enhance with JavaScript
+- Feature detection, not browser detection
+- Graceful degradation
+
+### 91. URL Design
+- Clean, readable URLs
+- Reflect content hierarchy
+- Stable, don't break links
+- Support deep linking
+
+### 92. State Management
+- Preserve state in URL when relevant
+- Browser back button works
+- Refresh doesn't lose data
+- Form data persisted
+
+### 93. Error Handling
+- Catch all errors gracefully
+- User-friendly error messages
+- Log errors for debugging
+- Retry mechanisms for network
+
+### 94. Cross-Browser
+- Test major browsers
+- Progressive enhancement
+- Polyfills when needed
+- Document supported browsers
+
+### 95. Print Styles
+- Print stylesheet
+- Hide navigation/ads
+- Readable typography
+- Proper page breaks
+
+### 96. Security UX
+- Clear HTTPS indicator
+- Explain security features
+- Don't ask for unnecessary data
+- Privacy-respecting defaults
+
+### 97. Internationalization
+- Plan for translation (text expansion)
+- Right-to-left support if needed
+- Date/time/number formats
+- Cultural considerations
+
+### 98. Analytics & Tracking
+- Respect DNT (Do Not Track)
+- Clear privacy policy
+- Consent for cookies/tracking
+- Minimal data collection
+
+---
+
+## Quick Reference Checklist
+
+### Before Launch
+- [ ] All pages have proper headings (H1-H6)
+- [ ] All images have alt text
+- [ ] Color contrast meets WCAG AA
+- [ ] All forms have labels
+- [ ] Keyboard navigation works
+- [ ] Error handling implemented
+- [ ] Loading states defined
+- [ ] Empty states designed
+- [ ] Mobile responsive tested
+- [ ] Cross-browser tested
+- [ ] Performance metrics acceptable
+- [ ] Accessibility audit passed
+
+### For Every Component
+- [ ] Has hover state
+- [ ] Has focus state
+- [ ] Has disabled state (if applicable)
+- [ ] Has error state (if applicable)
+- [ ] Has loading state (if applicable)
+- [ ] Touch target adequate
+- [ ] Screen reader accessible