agentic-team-templates 0.16.0 → 0.17.0

package/templates/ux-designer/.cursorrules/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/.cursorrules/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
+```

package/templates/ux-designer/.cursorrules/interaction-design.md

@@ -0,0 +1,221 @@
+# Interaction Design
+
+Designing how users interact with interfaces — controls, feedback, transitions, and behavior.
+
+## Core Principle
+
+**Every interaction should feel inevitable.** When a user taps, clicks, or swipes, the response should be exactly what they expected. Surprise is the enemy of usability.
+
+## Don Norman's Design Principles
+
+Six fundamental principles from *The Design of Everyday Things*:
+
+```markdown
+1. Visibility — Can users see what actions are available?
+2. Feedback — Does the system respond to every user action?
+3. Constraints — Does the design prevent errors?
+4. Mapping — Do controls relate naturally to their effects?
+5. Consistency — Do similar things work the same way?
+6. Affordance — Does the element suggest how to interact with it?
+```
+
+### Application
+
+```markdown
+Visibility:
+  ✅ Primary actions are visible buttons, not hidden in menus
+  ❌ Key features accessible only through right-click or gestures
+
+Feedback:
+  ✅ Button changes state on press; loading spinner appears immediately
+  ❌ User clicks "Save" and nothing visibly happens for 3 seconds
+
+Constraints:
+  ✅ Date picker prevents selecting impossible dates
+  ❌ Free text field for dates with no validation until submission
+
+Mapping:
+  ✅ Volume slider moves left-to-right for quieter-to-louder
+  ❌ Toggle labeled "Enable" that turns things off when activated
+
+Consistency:
+  ✅ "Delete" always requires confirmation, everywhere
+  ❌ Delete confirms in Settings but is instant in the dashboard
+
+Affordance:
+  ✅ Buttons look clickable (raised, colored, labeled)
+  ❌ Flat text that is secretly a link with no visual indicator
+```
+
+## Fitts's Law
+
+The time to reach a target is proportional to the distance and inversely proportional to the target size.
+
+```markdown
+Application:
+- Make primary action targets large (minimum 44x44px touch, 24x24px cursor)
+- Place frequently-used actions close to the user's current focus
+- Corners and edges of the screen are effectively infinite in size (use them)
+- Reduce the distance between related sequential actions
+
+Examples:
+  ✅ Submit button directly below the last form field
+  ❌ Submit button at the top of the page, far from the form
+  ✅ "Confirm" dialog button near the action that triggered it
+  ❌ Confirmation modal that appears at the center regardless of trigger location
+```
+
+## Hick's Law
+
+Decision time increases logarithmically with the number of choices.
+
+```markdown
+Application:
+- Limit choices to 5-7 options per decision
+- Use smart defaults to eliminate unnecessary decisions
+- Group and categorize when many options are unavoidable
+- Progressive disclosure: show essentials first, details on demand
+- Recommend the best option clearly
+
+Examples:
+  ✅ Pricing page with 3 plans, one highlighted as "Most Popular"
+  ❌ Pricing page with 12 plans and a comparison matrix
+  ✅ Smart default selected in a dropdown
+  ❌ Empty dropdown requiring the user to scroll through 100 options
+```
+
+## Jakob's Law
+
+Users spend most of their time on other sites/apps. They expect yours to work the same way.
+
+```markdown
+Application:
+- Follow platform conventions (iOS, Android, Web)
+- Use standard interaction patterns (pull-to-refresh, swipe-to-delete)
+- Place navigation where users expect it
+- Don't reinvent standard components for novelty's sake
+
+When to break convention:
+- Only when user testing proves the new pattern is measurably better
+- AND the learning cost is low enough to justify the improvement
+```
+
+## Interaction Patterns
+
+### Forms
+
+```markdown
+Rules:
+- One column layout (users read forms top-to-bottom)
+- Labels above fields (not inline placeholders as labels)
+- Mark optional fields, not required (most fields should be required)
+- Inline validation on blur, not on keystroke
+- Group related fields with clear section headings
+- Smart defaults reduce effort
+- Autofocus the first field
+- Tab order follows visual order
+
+Error handling:
+- Show errors inline next to the offending field
+- Use plain language: "Enter a valid email" not "Error 422"
+- Preserve user input on error (never clear the form)
+- Scroll to first error and focus it
+```
+
+### Buttons and CTAs
+
+```markdown
+Hierarchy:
+- Primary: One per screen/section. High contrast, filled.
+- Secondary: Supporting actions. Outlined or lower contrast.
+- Tertiary: Minimal actions. Text-only or links.
+- Destructive: Red or distinct treatment. Always requires confirmation.
+
+Labels:
+- Use verbs: "Save Changes", "Send Invite", "Delete Account"
+- Be specific: "Create Project" > "Submit" > "OK"
+- Match the action to the outcome: "Place Order" not "Continue"
+```
+
+### States
+
+Every interactive element must define all possible states:
+
+```markdown
+States:
+- Default — Resting state
+- Hover — Cursor over (desktop only)
+- Focus — Keyboard navigation highlight (mandatory for accessibility)
+- Active/Pressed — During interaction
+- Disabled — Cannot interact (must explain why)
+- Loading — Waiting for response
+- Error — Something went wrong
+- Success — Action completed
+- Empty — No content to display
+```
+
+### Microinteractions (Dan Saffer)
+
+Small, contained product moments that accomplish a single task.
+
+```markdown
+Structure:
+1. Trigger — What initiates the interaction (user action or system event)
+2. Rules — What happens when triggered
+3. Feedback — How the user knows what happened
+4. Loops & Modes — What changes over time or repeated use
+
+Examples:
+- Pull-to-refresh: Trigger → animation → content update → settle
+- Like button: Tap → heart animation → count increment → color change
+- Form submission: Click → button loading state → success message → redirect
+
+Rules:
+- Keep them fast (< 300ms for direct manipulation)
+- Make them skippable (animation shouldn't block workflow)
+- Degrade gracefully (functionality works even if animation fails)
+```
+
+### Animation and Motion
+
+```markdown
+Purpose of motion:
+- Provide feedback (button pressed, item added)
+- Show relationships (element came from here, goes to there)
+- Direct attention (notification appeared)
+- Communicate state change (loading → loaded)
+
+Principles:
+- Motion should have purpose — never purely decorative
+- Duration: 100-300ms for micro, 300-500ms for macro transitions
+- Easing: ease-out for entrances, ease-in for exits, ease-in-out for movement
+- Respect prefers-reduced-motion media query (mandatory)
+- Stagger animations for groups (40-80ms offset per item)
+```
+
+## Navigation Interactions
+
+```markdown
+Page transitions:
+- Forward navigation: slide left / fade in
+- Backward navigation: slide right / fade in
+- Modal opening: scale up from trigger or fade in
+- Modal closing: reverse of opening
+
+Tab/section switching:
+- Instant swap (no transition) or quick crossfade (150ms)
+- Never animate content the user is trying to read
+```
+
+## Anti-Patterns
+
+```markdown
+- Modal abuse: Using modals for content that should be a page
+- Double-click traps: Actions that fire twice on double-click
+- Invisible scrolling: Content below the fold with no scroll indicator
+- Disabled without explanation: Grayed-out buttons with no tooltip or message
+- Hover-dependent UI: Features only accessible on hover (fails on touch)
+- Infinite scroll without position: No way to return to a specific item
+- Auto-advancing carousels: Users can't read at carousel speed
+- Dark patterns: Trick questions, hidden costs, forced continuity, misdirection
+```