agentic-team-templates 0.16.0 → 0.18.0

package/templates/ux-designer/.cursor/rules/emotional-design.md

@@ -0,0 +1,217 @@
+# Emotional Design
+
+Designing experiences that create positive emotional connections, build trust, and drive engagement through psychology and behavioral science.
+
+## Core Principle
+
+**Eliminate frustration first, then add delight.** You cannot create positive emotions on top of a frustrating foundation. Fix the pain points before polishing the surface.
+
+## Norman's Three Levels of Emotional Design
+
+From Don Norman's *Emotional Design*:
+
+```markdown
+1. Visceral Level — Immediate, instinctive reaction
+   - First impression, visual appeal, aesthetic quality
+   - "This looks professional/trustworthy/beautiful"
+   - Driven by: color, typography, imagery, spacing, polish
+
+2. Behavioral Level — Experience during use
+   - Usability, effectiveness, efficiency, pleasure of use
+   - "This is easy to use and works exactly how I expected"
+   - Driven by: interaction design, performance, reliability, feedback
+
+3. Reflective Level — Meaning and memory after use
+   - Self-image, personal meaning, overall satisfaction
+   - "I feel smart/productive/capable using this"
+   - Driven by: brand perception, social proof, accomplishment, identity
+```
+
+### Application Priority
+
+```markdown
+Always in this order:
+1. Behavioral — If it doesn't work well, nothing else matters
+2. Visceral — First impressions determine whether users try it at all
+3. Reflective — Long-term satisfaction drives retention and advocacy
+```
+
+## Dopamine and Reward Patterns (Ethical Application)
+
+Understanding reward-driven behavior to create engaging experiences without manipulation.
+
+```markdown
+Ethical reward patterns:
+- Variable rewards: Personalized content feeds, curated recommendations
+  ✅ Showing relevant content the user will genuinely value
+  ❌ Infinite scroll designed to hijack attention
+
+- Achievement: Progress bars, completion badges, skill milestones
+  ✅ Celebrating genuine accomplishment (course completed, goal reached)
+  ❌ Fake achievements designed to manufacture engagement
+
+- Social validation: Meaningful feedback from peers
+  ✅ Showing who benefited from a contribution
+  ❌ Vanity metrics designed to create comparison anxiety
+
+Ethical boundary:
+  Ask: "Would users feel good about this if they understood exactly how it works?"
+  If yes → proceed. If no → redesign.
+```
+
+## Trust Building
+
+```markdown
+Trust signals:
+- Transparency: Show what data you collect, why, and how it's used
+- Consistency: Predictable behavior across all interactions
+- Competence: Polish, performance, and reliability signal quality
+- Security indicators: HTTPS, secure payment icons, privacy badges
+- Social proof: Real testimonials, usage stats, recognizable clients
+- Error handling: Graceful failures with honest communication
+
+Trust breakers:
+- Hidden fees or surprise costs
+- Manipulative urgency ("Only 2 left!")
+- Bait-and-switch (promising one thing, delivering another)
+- Data collection without clear consent
+- Broken promises (features that don't work as advertised)
+- Inconsistent behavior between screens or sessions
+```
+
+## Frustration Reduction
+
+The highest-impact emotional design work is removing negative experiences.
+
+```markdown
+Common frustration sources and fixes:
+
+1. Unexpected data loss
+   → Auto-save continuously; confirm before destructive actions
+
+2. Unclear errors
+   → Plain language errors with specific recovery steps
+
+3. Long wait times
+   → Skeleton screens, progress indicators, optimistic UI
+
+4. Dead ends
+   → Always provide a next action; never leave users stranded
+
+5. Forced repetition
+   → Remember user preferences; pre-fill known information
+
+6. Hidden functionality
+   → Make discoverable; use progressive disclosure, not hiding
+
+7. Inconsistent behavior
+   → Same action produces same result everywhere
+
+8. Interrupted flow
+   → Minimize modals, alerts, and interruptions during tasks
+```
+
+## Peak-End Rule (Daniel Kahneman)
+
+People judge experiences based on the peak (most intense moment) and the end (final moment), not the average.
+
+```markdown
+Application:
+- Design peak moments: Celebrate accomplishments, surprise with delight
+- Protect the ending: The last interaction shapes overall memory
+- Avoid negative peaks: A single terrible moment defines the whole experience
+
+Examples:
+  ✅ Onboarding ends with a personalized welcome and clear first action
+  ❌ Onboarding ends with a generic dashboard and no guidance
+
+  ✅ Checkout ends with confirmation, estimated delivery, and a thank-you
+  ❌ Checkout ends with an order number and nothing else
+
+  ✅ Error recovery ends with success confirmation and encouragement
+  ❌ Error recovery ends by silently returning to a generic page
+```
+
+## Aesthetic-Usability Effect
+
+Users perceive aesthetically pleasing designs as more usable, even when they're not.
+
+```markdown
+Application:
+- Visual polish creates a forgiveness buffer for minor usability issues
+- But it cannot compensate for fundamentally broken interactions
+- Invest in visual quality after behavioral quality is solid
+- Polish is not optional — it affects perceived trustworthiness and competence
+
+Warning:
+- Don't use aesthetics to mask usability problems
+- Beautiful and broken is worse than plain and functional
+```
+
+## Micro-Delight
+
+Small, unexpected positive moments that create emotional connection.
+
+```markdown
+Examples:
+- Confetti animation on milestone completion
+- Witty empty states: "No messages yet. Enjoy the silence."
+- Personalized greetings based on time of day
+- Smooth, satisfying animations for common actions
+- Easter eggs for power users
+
+Rules:
+- Delight should never interfere with task completion
+- Respect prefers-reduced-motion for animation-based delight
+- Don't repeat the same delight too often (it becomes noise)
+- Delight should feel authentic to the brand voice
+- Never use delight during error or frustration states
+```
+
+## Dark Pattern Avoidance
+
+Designing ethically means actively choosing not to manipulate users.
+
+```markdown
+Dark patterns to reject:
+- Confirmshaming: "No thanks, I don't want to save money"
+- Hidden costs: Fees revealed only at checkout
+- Trick questions: Double negatives in opt-out checkboxes
+- Forced continuity: Hard-to-cancel subscriptions
+- Disguised ads: Ads styled as content or navigation
+- Friend spam: Importing contacts without explicit consent
+- Roach motel: Easy to sign up, impossible to delete account
+- Misdirection: Visual design that draws attention away from what matters
+- Privacy zuckering: Confusing settings that maximize data collection
+
+Ethical test:
+  "If I explained this exact flow to a journalist, would I be proud?"
+  If yes → ship it. If no → redesign it.
+```
+
+## Onboarding Emotional Arc
+
+```markdown
+Ideal emotional progression:
+1. Curiosity (landing page) → "This looks like it could solve my problem"
+2. Confidence (sign up) → "This was easy, no surprises"
+3. Competence (first action) → "I did it! This works!"
+4. Investment (customization) → "This is starting to feel like mine"
+5. Achievement (first milestone) → "I'm making real progress"
+
+Each stage should have:
+- Clear, achievable next action
+- Immediate positive feedback
+- Zero unnecessary friction
+```
+
+## Anti-Patterns
+
+```markdown
+- Delight without function: Animation and personality over usability
+- Emotional manipulation: Guilt, shame, or fear to drive action
+- Ignoring negative emotions: Focusing on delight while users are frustrated
+- Tone-deaf celebration: Congratulating users for mundane tasks
+- Forced fun: Gamification that feels patronizing or irrelevant
+- Copy-and-paste personality: Brand voice that feels generic or insincere
+```

package/templates/ux-designer/.cursor/rules/handoff.md

@@ -0,0 +1,251 @@
+# Design Handoff
+
+Bridging design and development through clear specifications, shared language, and measurable quality standards.
+
+## Core Principle
+
+**Handoff is not a moment — it is a continuous conversation.** Designers and developers should collaborate from the start, not pass artifacts over a wall.
+
+## Nielsen's 10 Usability Heuristics
+
+The standard evaluation framework for interface usability:
+
+```markdown
+1. Visibility of System Status
+   - Always keep users informed about what's happening
+   - Progress bars, loading states, status indicators
+
+2. Match Between System and Real World
+   - Use language and concepts familiar to the user
+   - Follow real-world conventions; information appears in natural order
+
+3. User Control and Freedom
+   - Support undo and redo
+   - Provide clearly marked "emergency exits"
+
+4. Consistency and Standards
+   - Follow platform conventions
+   - Same words/actions mean the same things everywhere
+
+5. Error Prevention
+   - Prevent errors before they occur
+   - Confirmation dialogs for destructive actions
+   - Constraints that eliminate impossible states
+
+6. Recognition Rather Than Recall
+   - Make options visible; minimize memory load
+   - Instructions visible or easily retrievable
+
+7. Flexibility and Efficiency of Use
+   - Accelerators for expert users (shortcuts, bulk actions)
+   - Customizable frequent actions
+
+8. Aesthetic and Minimalist Design
+   - No irrelevant or rarely needed information
+   - Every element competes for attention — earn its place
+
+9. Help Users Recognize, Diagnose, and Recover From Errors
+   - Plain language error messages (no codes)
+   - Precisely indicate the problem
+   - Suggest a solution
+
+10. Help and Documentation
+    - Searchable, task-focused
+    - Concrete steps to follow
+    - Keep it concise
+```
+
+## Specification Standards
+
+What every design handoff must include:
+
+```markdown
+Layout:
+- Responsive behavior at all breakpoints (mobile, tablet, desktop)
+- Spacing values using design tokens (not arbitrary pixel values)
+- Grid alignment and column usage
+- Max-width and min-width constraints
+
+Typography:
+- Font family, weight, size, line-height, letter-spacing (as tokens)
+- Heading hierarchy applied correctly
+- Truncation behavior for long content
+
+Color:
+- All colors referenced as design tokens
+- Light and dark mode specifications
+- Contrast ratios documented for key combinations
+
+Components:
+- All states specified (default, hover, focus, active, disabled, error, loading, empty)
+- Interaction behavior described (what happens on click, focus, blur)
+- Animation/transition specifications (duration, easing, trigger)
+- Responsive adaptations per breakpoint
+
+Content:
+- Real content examples (not lorem ipsum for final specs)
+- Character limits and truncation rules
+- Empty state designs
+- Error message copy
+```
+
+## Design Annotations
+
+Mark up designs with implementation context:
+
+```markdown
+Annotation types:
+- Spacing callouts: Token names and values for margins/padding
+- Interaction notes: "On hover, show tooltip after 500ms delay"
+- Responsive notes: "Stack columns below 768px"
+- Accessibility notes: "aria-label='Close dialog'", "Focus trap in modal"
+- Animation notes: "Fade in 200ms ease-out on mount"
+- Edge cases: "Truncate with ellipsis after 2 lines"
+- Conditional logic: "Show only when user has admin role"
+```
+
+## Prototyping
+
+```markdown
+Fidelity levels:
+- Low-fi (paper/wireframe): Validate layout and flow
+- Mid-fi (grayscale interactive): Validate interaction patterns
+- High-fi (visual + interactive): Validate look, feel, and motion
+- Code prototype: Validate feasibility and performance
+
+When to use each:
+- Exploring ideas → low-fi (fast, disposable)
+- User testing navigation → mid-fi (enough to test, not enough to distract)
+- Stakeholder sign-off → high-fi (shows the real vision)
+- Complex interactions → code prototype (some things can't be faked)
+
+Tools don't matter — outcomes do. Use whatever gets answers fastest.
+```
+
+## Design QA
+
+Review implemented designs against specifications:
+
+```markdown
+Checklist:
+- [ ] Layout matches spec at all breakpoints
+- [ ] Spacing uses correct design tokens
+- [ ] Typography matches spec (font, size, weight, line-height)
+- [ ] Colors match spec and meet contrast requirements
+- [ ] All interaction states implemented (hover, focus, active, disabled, error, loading, empty)
+- [ ] Animations match spec (duration, easing, trigger)
+- [ ] Keyboard navigation works correctly
+- [ ] Screen reader announces elements correctly
+- [ ] Focus order matches visual order
+- [ ] Error states display correctly with appropriate messages
+- [ ] Empty states display correctly
+- [ ] Content truncation works as specified
+- [ ] Responsive behavior matches spec at all breakpoints
+- [ ] Dark mode (if applicable) matches spec
+
+Process:
+1. Designer reviews implementation in staging environment
+2. File issues with screenshots showing expected vs. actual
+3. Prioritize: functional issues > accessibility issues > visual polish
+4. Re-review after fixes
+```
+
+## UX Metrics
+
+Measure what matters to validate design decisions:
+
+### Task-Level Metrics
+
+```markdown
+- Task success rate: % of users who complete the task correctly
+  Target: > 90% for critical flows, > 80% for secondary flows
+
+- Time on task: How long it takes to complete a task
+  Compare against baseline; aim for continuous reduction
+
+- Error rate: Number of errors per task attempt
+  Track by type (slips vs. mistakes) to inform different fixes
+
+- Task abandonment: % of users who start but don't finish
+  Identify where in the flow they drop off
+```
+
+### Experience Metrics
+
+```markdown
+- System Usability Scale (SUS):
+  10-question standardized questionnaire
+  Score: 0-100. Above 68 = above average. Above 80 = good. Above 90 = excellent.
+
+- Customer Satisfaction (CSAT): Post-interaction rating
+  "How satisfied were you with this experience?" (1-5 scale)
+
+- Net Promoter Score (NPS): Loyalty indicator
+  "How likely are you to recommend this?" (0-10)
+  Promoters (9-10) - Detractors (0-6) = NPS
+
+- Customer Effort Score (CES): Ease of use
+  "How easy was it to complete your task?" (1-7)
+```
+
+### Behavioral Metrics
+
+```markdown
+- Feature adoption rate: % of users who use a feature within first 30 days
+- Retention: % of users who return after day 1, 7, 30
+- Funnel completion: % conversion through multi-step flows
+- Rage clicks: Repeated rapid clicks on the same element (indicates frustration)
+- Dead clicks: Clicks on non-interactive elements (indicates confusion)
+```
+
+## Usability Testing
+
+```markdown
+Moderated testing:
+- 5 users per round (catches ~85% of usability issues)
+- Think-aloud protocol: users narrate their thought process
+- Task-based: give users realistic goals, not instructions
+- Observe behavior, not opinions
+- Record sessions for team review
+
+Unmoderated testing:
+- Larger sample size (20-50 users)
+- Task-based with screen recording
+- Useful for quantitative validation
+- Less nuance than moderated sessions
+
+Testing frequency:
+- Minimum: Every sprint or every 2 weeks
+- Ideal: Weekly lightweight tests on current work
+- Before launch: Full usability test on complete flow
+- After launch: Ongoing with analytics + periodic interviews
+```
+
+## Collaboration Practices
+
+```markdown
+Design-dev sync:
+- Weekly design review with developers during design phase
+- Pair on complex interactions (designer + developer together)
+- Shared language through design tokens and component names
+- Developers review prototypes before final spec
+
+Documentation:
+- Living design system documentation (not static PDFs)
+- Decision log: why design choices were made (not just what)
+- Changelog for design system updates
+- Migration guides when components change
+```
+
+## Anti-Patterns
+
+```markdown
+- Wall-of-specs handoff: Dumping a 50-page document without conversation
+- Pixel perfection over functionality: Debating 1px while ignoring broken flows
+- Designing in isolation: Creating specs without developer input on feasibility
+- Missing states: Only designing the happy path, leaving error/empty/loading to developers
+- Lorem ipsum in final specs: Real content reveals design issues placeholder text hides
+- No design QA: Assuming implementation matches spec without verification
+- Vanity metrics: Tracking page views instead of task success
+- Testing after launch only: Discovering usability issues when it's expensive to fix them
+```

package/templates/ux-designer/.cursor/rules/information-architecture.md

@@ -0,0 +1,193 @@
+# Information Architecture
+
+Organizing, structuring, and labeling content so users can find what they need and understand where they are.
+
+## Core Principle
+
+**If users can't find it, it doesn't exist.** The best content in the world is worthless behind poor navigation, ambiguous labels, or buried hierarchies.
+
+## Foundational Concepts (Rosenfeld & Morville)
+
+Information architecture addresses four core systems:
+
+```markdown
+1. Organization Systems — How content is grouped and categorized
+2. Labeling Systems — How content is named and described
+3. Navigation Systems — How users move through content
+4. Search Systems — How users query and filter content
+```
+
+## Mental Models (Indi Young)
+
+Design information structures that match how users think, not how the organization is structured.
+
+```markdown
+Rule: Users don't care about your org chart.
+
+Process:
+1. Interview users about their tasks and thought processes
+2. Map their mental model of the domain
+3. Identify gaps between their model and your structure
+4. Align your IA to their model, not the other way around
+
+Example:
+  Internal structure: Products → Enterprise → SMB → Consumer
+  User mental model: "I need a tool that does X for a team of Y"
+  → Organize by use case and team size, not by business segment
+```
+
+## Miller's Law
+
+Users can hold approximately 4 items (revised from 7 +/- 2) in working memory at once.
+
+```markdown
+Application:
+- Limit primary navigation to 4-7 items
+- Chunk related content into meaningful groups
+- Use progressive disclosure to manage complexity
+- Avoid menus deeper than 3 levels
+```
+
+## Card Sorting
+
+Discover how users naturally group and label content.
+
+```markdown
+Open Card Sort:
+- Give users content cards with no predefined categories
+- They create and name their own groups
+- Use when building IA from scratch
+- Minimum 15 participants for reliable patterns
+
+Closed Card Sort:
+- Provide predefined categories
+- Users sort content into those categories
+- Use to validate an existing IA structure
+- Identify content that users can't confidently place
+
+Hybrid Card Sort:
+- Provide some categories, allow users to create new ones
+- Best of both worlds for iterative refinement
+
+Analysis:
+- Look for agreement rates > 60% for confident groupings
+- Items with low agreement need relabeling or restructuring
+- Dendrogram analysis reveals natural clusters
+```
+
+## Tree Testing
+
+Validate whether users can find items in a proposed hierarchy without visual design influence.
+
+```markdown
+Process:
+1. Create a text-only tree of your proposed navigation
+2. Give users tasks: "Where would you find X?"
+3. Measure success rate, directness, and time to complete
+
+Metrics:
+- Task success rate > 80% = strong IA
+- Directness score > 70% = clear paths (users didn't backtrack)
+- First-click correctness > 60% = good top-level labeling
+
+Rules:
+- Test before visual design (eliminates bias from layout/color)
+- 50+ participants for statistical reliability
+- Test with realistic tasks, not "find the About page"
+```
+
+## Navigation Patterns
+
+### Primary Navigation
+
+```markdown
+Types:
+- Top bar: Best for 4-7 top-level items (web)
+- Sidebar: Best for 8+ items or deep hierarchies (apps, dashboards)
+- Bottom tab bar: Best for 3-5 core actions (mobile)
+- Hamburger menu: Last resort — hides everything, reduces discoverability
+
+Rules:
+- Current location must always be visible
+- Navigation labels should be nouns (what it is), not verbs (what you do)
+- Icon + label > icon alone (icons are ambiguous without labels)
+```
+
+### Breadcrumbs
+
+```markdown
+Use when:
+- Hierarchy is 3+ levels deep
+- Users may land on deep pages from search
+- Users need to understand their location in context
+
+Don't use when:
+- Navigation is flat (1-2 levels)
+- Site is task-based rather than content-based
+```
+
+### Search
+
+```markdown
+Search is not a replacement for good navigation — it's a supplement.
+
+Requirements:
+- Autocomplete suggestions after 2+ characters
+- Fuzzy matching for typos
+- Recent searches for returning users
+- Scoped search within current section
+- Clear indication of result count and relevance
+- Empty state with helpful suggestions
+```
+
+## Sitemaps and User Flows
+
+### Sitemaps
+
+```markdown
+Purpose: Document the complete content structure
+Format: Hierarchical tree diagram
+
+Rules:
+- Include every page/screen
+- Label with user-facing names (not internal codenames)
+- Mark authenticated vs. public areas
+- Version and date every sitemap
+- Update when IA changes
+```
+
+### User Flows
+
+```markdown
+Purpose: Document paths users take to complete tasks
+Format: Flowchart with decision points
+
+Rules:
+- Start with the user's goal, not your homepage
+- Include error paths and edge cases
+- Mark decision points clearly
+- Note where users enter from (deep links, search, referrals)
+- Validate flows against analytics data
+```
+
+## Labeling
+
+```markdown
+Rules:
+- Use the user's language, not internal jargon
+- Be specific: "Order History" > "History"
+- Be consistent: Don't call it "Settings" in one place and "Preferences" in another
+- Test labels with tree testing or first-click testing
+- Avoid clever or branded terms for navigation (users don't know your brand vocabulary)
+```
+
+## Anti-Patterns
+
+```markdown
+- Org-chart navigation: Structuring IA to match internal departments
+- Jargon labels: Using internal terminology users don't recognize
+- Deep nesting: Burying content 4+ levels deep
+- Orphan pages: Content reachable only through search, not navigation
+- Mega-menu overload: Dumping every link into a massive dropdown
+- Mystery meat navigation: Icons without labels, hover-only reveals
+```