agentic-team-templates 0.16.0 → 0.17.0

package/templates/ux-designer/.cursorrules/overview.md

@@ -0,0 +1,110 @@
+# UX Designer
+
+Principal-level UX design guidelines covering user research, interaction design, design systems, accessibility, and emotional design.
+
+## Scope
+
+This ruleset applies to:
+
+- User research and discovery
+- Information architecture and navigation
+- Interaction design and patterns
+- Visual design and design systems
+- Accessibility and inclusive design
+- Emotional design and user delight
+- Design-to-development handoff and UX metrics
+
+## Core Philosophy
+
+**Frustration elimination is the north star.** Every design decision should reduce friction, confusion, and cognitive load. Delight follows naturally when barriers disappear.
+
+### Guiding Beliefs
+
+1. **Simplicity over complexity** - The best interface is the one users don't notice
+2. **Accessibility is non-negotiable** - Design for the margins; everyone benefits
+3. **Evidence over opinion** - Research and data settle design debates, not authority
+4. **Behavior over preference** - What users do matters more than what they say
+5. **Consistency breeds trust** - Predictable patterns reduce cognitive overhead
+
+## Fundamental Principles
+
+### 1. User-Centered Design
+
+Every decision starts and ends with the user. Assumptions are hypotheses to be validated, not truths to be defended.
+
+```markdown
+Step 1: Understand (Research who the users are and what they need)
+Step 2: Define (Frame the problem clearly before solving it)
+Step 3: Ideate (Explore multiple solutions, not just the first one)
+Step 4: Prototype (Make it tangible before making it real)
+Step 5: Test (Validate with real users, iterate on findings)
+```
+
+### 2. Progressive Disclosure
+
+Reveal complexity only when needed. Show the essential, hide the advanced, and let users drill deeper on demand.
+
+```markdown
+Level 1: Primary actions visible at all times
+Level 2: Secondary actions one click away
+Level 3: Advanced settings behind explicit navigation
+```
+
+### 3. Don't Make Me Think
+
+Borrowed from Steve Krug: interfaces should be self-evident. If a user has to stop and think about how something works, the design has failed.
+
+### 4. Respect Cognitive Load
+
+Humans have limited working memory (~4 items at a time per Miller's Law, revised). Every unnecessary element competes for attention.
+
+### 5. Design for Recovery
+
+Users will make mistakes. Design systems that make errors reversible, provide clear feedback, and never punish exploration.
+
+## Decision Framework
+
+When evaluating design choices, apply this priority stack:
+
+```markdown
+1. Does it remove user frustration? (Highest priority)
+2. Does it meet accessibility requirements (WCAG 2.2 AA)?
+3. Does it follow established interaction patterns?
+4. Does it align with the design system?
+5. Does it add delight without adding complexity?
+```
+
+### When in Doubt
+
+- Choose the option that reduces the number of decisions the user must make
+- Choose the option that works for the most constrained user (low vision, motor impairment, cognitive disability)
+- Choose the option that requires fewer taps/clicks to complete the task
+- Prototype both options and test with users
+
+## Key Frameworks
+
+| Framework | Author/Source | Purpose |
+|-----------|---------------|---------|
+| Jobs-to-be-Done | Clayton Christensen | Understanding user motivations |
+| Don Norman's Design Principles | Don Norman | Interaction design fundamentals |
+| Gestalt Principles | Wertheimer et al. | Visual perception and grouping |
+| Atomic Design | Brad Frost | Scalable design system architecture |
+| WCAG 2.2 | W3C | Accessibility compliance |
+| Nielsen's 10 Heuristics | Jakob Nielsen | Usability evaluation |
+| Emotional Design (3 levels) | Don Norman | Visceral, behavioral, reflective design |
+| Fitts's Law | Paul Fitts | Target size and distance optimization |
+| Hick's Law | William Hick | Decision time and option count |
+
+## Definition of Done (Design)
+
+A design deliverable is complete when:
+
+- [ ] User problem is validated through research (not assumed)
+- [ ] Accessibility audited against WCAG 2.2 AA
+- [ ] Keyboard navigation flow documented
+- [ ] Screen reader experience specified
+- [ ] Responsive behavior defined for all breakpoints
+- [ ] Interaction states documented (default, hover, focus, active, disabled, error, loading, empty)
+- [ ] Edge cases addressed (empty states, error states, long content, truncation)
+- [ ] Handoff spec reviewed with engineering
+- [ ] Usability tested with representative users

package/templates/ux-designer/.cursorrules/research.md

@@ -0,0 +1,181 @@
+# User Research
+
+Evidence-based methods for understanding users, validating assumptions, and making informed design decisions.
+
+## Core Principle
+
+**Talk to users early, often, and honestly.** Research is not a phase; it is a continuous practice embedded in every stage of design.
+
+## Research Methods
+
+### User Interviews
+
+Structured conversations to uncover user needs, behaviors, and pain points.
+
+```markdown
+Planning:
+- Define research questions (what you want to learn, not what you'll ask)
+- Recruit 5-8 participants per segment (saturation point per Nielsen)
+- Prepare a discussion guide with open-ended questions
+
+During:
+- Ask about past behavior, not hypothetical futures
+- "Tell me about the last time you..." > "Would you ever..."
+- Follow the energy: when they lean in, dig deeper
+- Silence is a tool; let them fill the gaps
+
+After:
+- Synthesize within 24 hours while memory is fresh
+- Tag quotes and observations by theme
+- Share raw findings before interpreting them
+```
+
+### The Mom Test (Rob Fitzpatrick)
+
+Rules for asking questions that even your mom can't lie to you about:
+
+```markdown
+1. Talk about their life, not your idea
+2. Ask about specifics in the past, not generics about the future
+3. Talk less, listen more
+
+Bad: "Would you use an app that does X?"
+Good: "How do you currently handle X? Walk me through the last time."
+
+Bad: "Do you think this is a good idea?"
+Good: "What solutions have you tried? What worked and what didn't?"
+```
+
+### Jobs-to-be-Done (Clayton Christensen)
+
+Understand the progress users are trying to make in a given circumstance.
+
+```markdown
+Framework:
+"When I [situation], I want to [motivation], so I can [expected outcome]."
+
+Example:
+"When I'm onboarding a new team member, I want to share access quickly,
+ so I can get them productive on day one."
+
+Key insight: Users don't buy products; they hire them to do a job.
+Competing products are rarely in the same category.
+```
+
+### Empathy Mapping
+
+Collaborative visualization of what users say, think, do, and feel.
+
+```markdown
+Quadrants:
+┌─────────────────┬─────────────────┐
+│     SAYS         │     THINKS       │
+│ (Direct quotes)  │ (Inferred from   │
+│                  │  behavior)        │
+├─────────────────┼─────────────────┤
+│     DOES         │     FEELS        │
+│ (Observed        │ (Emotional       │
+│  actions)        │  state)          │
+└─────────────────┴─────────────────┘
+
+Use after interviews to align the team on user perspective.
+```
+
+## Personas
+
+Archetypes representing user segments, grounded in research data.
+
+```markdown
+Structure:
+- Name, photo, demographic snapshot
+- Goals (what they want to achieve)
+- Frustrations (what blocks them today)
+- Behaviors (how they currently work)
+- Context (devices, environment, constraints)
+- Quote (real or composite from interviews)
+
+Rules:
+- Derived from research, never invented
+- 3-5 personas maximum (more dilutes focus)
+- Include an "edge case" persona (accessibility, low-tech, etc.)
+- Revisit and update quarterly
+```
+
+## Journey Mapping
+
+Visualize the end-to-end user experience across touchpoints.
+
+```markdown
+Columns: Stages of the journey (Awareness → Consideration → Action → Retention)
+Rows:
+- Actions (what the user does)
+- Touchpoints (where they interact)
+- Thoughts (what they're thinking)
+- Emotions (how they feel — map on a curve)
+- Pain points (friction moments)
+- Opportunities (design intervention points)
+
+Rules:
+- Map current state before designing future state
+- Base on observed behavior, not ideal paths
+- Identify the "moments of truth" — where experience breaks or bonds
+```
+
+## Continuous Discovery (Teresa Torres)
+
+Research is not a project; it is a weekly habit.
+
+```markdown
+Principles:
+1. Talk to users every week (minimum 1 interview/week)
+2. Map the opportunity space, not the solution space
+3. Use opportunity solution trees to connect outcomes → opportunities → solutions
+4. Run small experiments before building features
+5. Separate discovery (what to build) from delivery (how to build it)
+
+Opportunity Solution Tree:
+  Desired Outcome
+      ├── Opportunity A
+      │   ├── Solution 1 → Experiment
+      │   └── Solution 2 → Experiment
+      └── Opportunity B
+          ├── Solution 3 → Experiment
+          └── Solution 4 → Experiment
+```
+
+## Survey Design
+
+Quantitative validation of qualitative findings.
+
+```markdown
+Rules:
+- Use surveys to measure, not to discover (interviews first)
+- Limit to 5-10 questions (completion rate drops after 10)
+- Avoid leading questions and double-barreled items
+- Include a mix of Likert scale, multiple choice, and one open-ended
+- Report confidence intervals, not just percentages
+- Minimum viable sample: 30 for directional, 100+ for statistical significance
+```
+
+## Research Ethics
+
+```markdown
+Non-negotiable:
+- Informed consent before every session
+- Anonymize data before sharing
+- Participants can stop at any time without consequence
+- Compensate participants fairly for their time
+- Never manipulate or deceive during research
+- Store recordings securely; delete when analysis is complete
+```
+
+## Anti-Patterns
+
+```markdown
+- Confirmation bias: Only talking to users who validate your hypothesis
+- Leading questions: "Don't you think this is easier?"
+- Proxy research: Asking stakeholders what users want instead of asking users
+- Research theater: Conducting research with no intention to act on findings
+- Big-bang research: Doing all research upfront and none after launch
+- Persona fiction: Creating personas from assumptions instead of data
+```

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

@@ -0,0 +1,191 @@
+# Visual Design
+
+Principles and systems for visual communication, design systems, and consistent UI expression.
+
+## Core Principle
+
+**Visual design is communication, not decoration.** Every pixel should serve a purpose: establish hierarchy, group related elements, guide attention, or reinforce meaning.
+
+## Gestalt Principles of Visual Perception
+
+How humans naturally perceive and group visual elements:
+
+```markdown
+Proximity — Elements close together are perceived as related
+  → Group related form fields; separate unrelated sections with whitespace
+
+Similarity — Elements that look alike are perceived as related
+  → Use consistent styling for same-type elements (all links blue, all tags pills)
+
+Continuity — The eye follows lines, curves, and sequences
+  → Align elements to create visual flow; use grids and alignment
+
+Closure — The mind completes incomplete shapes
+  → Progress bars, partially visible cards (indicating scrollable content)
+
+Figure-Ground — Users distinguish foreground from background
+  → Modals dim the background; selected items highlight against the list
+
+Common Region — Elements within a boundary are perceived as grouped
+  → Cards, bordered sections, background color changes for groupings
+```
+
+## Atomic Design (Brad Frost)
+
+Scalable methodology for building design systems from smallest to largest:
+
+```markdown
+1. Atoms — Smallest UI elements (button, input, label, icon, color, font)
+2. Molecules — Simple groups of atoms (search bar = input + button)
+3. Organisms — Complex components (header = logo + nav + search + avatar)
+4. Templates — Page-level layouts with placeholder content
+5. Pages — Templates populated with real content
+
+Rules:
+- Design atoms before molecules, molecules before organisms
+- Every component should be self-contained and reusable
+- Document every component with usage guidelines and examples
+- Name components by what they are, not where they appear
+```
+
+## Design Tokens (W3C Community Group)
+
+The single source of truth for design decisions, expressed as platform-agnostic values.
+
+```markdown
+Token categories:
+- Color: color.primary, color.error, color.surface, color.text.primary
+- Typography: font.family.body, font.size.lg, font.weight.bold, line-height.tight
+- Spacing: space.xs (4px), space.sm (8px), space.md (16px), space.lg (24px), space.xl (32px)
+- Border: border.radius.sm, border.width.default, border.color.subtle
+- Shadow: shadow.sm, shadow.md, shadow.lg
+- Motion: duration.fast (100ms), duration.normal (200ms), easing.standard
+- Breakpoints: breakpoint.sm (640px), breakpoint.md (768px), breakpoint.lg (1024px)
+
+Rules:
+- Tokens are the API of the design system
+- Never use raw values in components — always reference tokens
+- Semantic tokens (color.error) alias primitive tokens (red.500)
+- Support theming through token swapping (light/dark mode)
+```
+
+## Typography
+
+```markdown
+Hierarchy:
+- Display: Hero headings, landing pages (32-72px)
+- H1: Page titles (28-36px)
+- H2: Section headings (22-28px)
+- H3: Subsection headings (18-22px)
+- Body: Paragraph text (16px baseline)
+- Small: Captions, metadata (12-14px)
+
+Rules:
+- Maximum 2 font families (one for headings, one for body — or the same)
+- Body text minimum 16px (anything smaller causes readability issues)
+- Line height: 1.4-1.6 for body text, 1.1-1.3 for headings
+- Line length: 45-75 characters per line (optimal ~66)
+- Paragraph spacing: 1em minimum between paragraphs
+- Contrast ratio: 4.5:1 minimum for body text, 3:1 for large text (WCAG AA)
+```
+
+## Color
+
+```markdown
+System:
+- Primary: Brand color, used for CTAs and key interactive elements
+- Secondary: Supporting color for less prominent interactive elements
+- Neutral: Grays for text, borders, backgrounds, dividers
+- Error: Red/warm for error states and destructive actions
+- Warning: Amber/yellow for caution and non-blocking alerts
+- Success: Green for confirmation and positive feedback
+- Info: Blue for informational messages
+
+Rules:
+- Never use color as the only indicator (add icons, text, patterns)
+- Test with color blindness simulators (protanopia, deuteranopia, tritanopia)
+- Dark mode is not inverted light mode — redesign contrast and emphasis
+- Limit palette to 5-8 functional colors plus neutrals
+- Ensure all color combinations meet WCAG 2.2 AA contrast ratios
+```
+
+## Spacing and Layout
+
+```markdown
+Spacing scale (base-8 system):
+  4px  — Tight: between related inline elements
+  8px  — Small: between related stacked elements
+  16px — Medium: between components within a section
+  24px — Large: between sections
+  32px — Extra-large: major section breaks
+  48px — 2XL: page-level breathing room
+
+Grid:
+- Use a consistent column grid (12-column for web, 4-column for mobile)
+- Gutters match the spacing scale (16px or 24px)
+- Content maxwidth: 1200-1440px for readability
+- Responsive breakpoints: 640, 768, 1024, 1280px
+
+Whitespace:
+- Whitespace is not wasted space — it creates hierarchy and breathing room
+- More whitespace = more perceived quality and readability
+- Group related elements with less whitespace; separate unrelated with more
+```
+
+## Iconography
+
+```markdown
+Rules:
+- Use a single icon set for consistency (don't mix icon libraries)
+- Icons must be accompanied by text labels (except universally recognized: close, search, menu)
+- Minimum touch target: 44x44px even if the icon is smaller
+- Support both outlined and filled variants for state changes
+- Ensure icons work at small sizes (16px minimum)
+- Provide alt text or aria-label for meaningful icons
+- Use aria-hidden="true" for decorative icons
+```
+
+## Responsive Design
+
+```markdown
+Approach: Mobile-first, scale up
+
+Breakpoints:
+  < 640px   — Mobile (single column, stacked layout)
+  640-768px  — Large mobile / small tablet
+  768-1024px — Tablet (2-column where appropriate)
+  1024-1280px — Desktop
+  > 1280px   — Wide desktop (max-width container, don't stretch)
+
+Rules:
+- Design mobile first, then adapt for larger screens
+- Touch targets: 44x44px minimum on mobile
+- No horizontal scrolling on any breakpoint
+- Images are fluid (max-width: 100%)
+- Typography scales with viewport (clamp() for fluid type)
+- Test on real devices, not just browser resize
+```
+
+## Design System Governance
+
+```markdown
+Rules:
+- Every component needs documentation: usage, props, do/don't examples
+- Changes to tokens or components require design review
+- Deprecate before removing — provide migration path
+- Version the design system alongside code releases
+- Audit for consistency quarterly
+- Component library is the single source of truth (not a Figma file that diverges)
+```
+
+## Anti-Patterns
+
+```markdown
+- Snowflake components: One-off designs that don't use the design system
+- Token bypass: Hard-coding values instead of referencing tokens
+- Decoration-driven design: Visual flourishes that add no meaning
+- Inconsistent spacing: Mixing arbitrary pixel values instead of a scale
+- Font overload: More than 2 font families or 4+ weights
+- Color soup: Too many colors with no systematic rationale
+- Pixel-perfect obsession: Spending hours on 1px alignment instead of testing usability
+```

package/templates/ux-designer/CLAUDE.md

@@ -0,0 +1,124 @@
+# UX Designer Development Guide
+
+Principal-level UX design guidelines covering user research, interaction design, design systems, accessibility, and emotional design.
+
+---
+
+## Overview
+
+This guide applies to:
+
+- User research and discovery
+- Information architecture and navigation
+- Interaction design and patterns
+- Visual design and design systems
+- Accessibility and inclusive design
+- Emotional design and user delight
+- Design-to-development handoff and UX metrics
+
+### Key Principles
+
+1. **Frustration Elimination** - Remove friction before adding delight
+2. **Simplicity Over Complexity** - The best interface is the one users don't notice
+3. **Accessibility is Non-Negotiable** - Design for the margins; everyone benefits
+4. **Evidence Over Opinion** - Research and data settle design debates
+5. **Consistency Breeds Trust** - Predictable patterns reduce cognitive overhead
+
+### Core Frameworks
+
+| Framework | Purpose |
+|-----------|---------|
+| Jobs-to-be-Done (Christensen) | Understanding user motivations |
+| Don Norman's 6 Principles | Interaction design fundamentals |
+| Gestalt Principles | Visual perception and grouping |
+| Atomic Design (Frost) | Scalable design systems |
+| WCAG 2.2 AA (POUR) | Accessibility compliance |
+| Nielsen's 10 Heuristics | Usability evaluation |
+| Norman's 3 Levels | Emotional design |
+| Fitts's Law / Hick's Law | Interaction optimization |
+
+---
+
+## User Research
+
+- **The Mom Test** (Fitzpatrick): Ask about past behavior, not hypothetical futures
+- **Continuous Discovery** (Torres): Talk to users weekly, map opportunity space
+- **Empathy Mapping**: Visualize what users say, think, do, and feel
+- **Journey Mapping**: Visualize end-to-end experience across touchpoints
+- **JTBD Framework**: "When I [situation], I want to [motivation], so I can [outcome]"
+
+---
+
+## Information Architecture
+
+- **Mental Models** (Indi Young): Align structure to user thinking, not org charts
+- **Card Sorting**: Open sort to discover, closed sort to validate
+- **Tree Testing**: Validate findability without visual design influence
+- **Miller's Law**: Limit primary navigation to 4-7 items
+- Labels use user language, not internal jargon
+
+---
+
+## Interaction Design
+
+- **Don Norman's Principles**: Visibility, feedback, constraints, mapping, consistency, affordance
+- **Fitts's Law**: Large targets, close to focus, minimize distance
+- **Hick's Law**: Fewer choices, smart defaults, progressive disclosure
+- **Jakob's Law**: Follow platform conventions; users expect consistency
+- All interactive elements specify: default, hover, focus, active, disabled, error, loading, empty states
+- Forms: one column, labels above fields, inline validation on blur
+
+---
+
+## Visual Design
+
+- **Gestalt Principles**: Proximity, similarity, continuity, closure, figure-ground, common region
+- **Atomic Design**: Atoms → molecules → organisms → templates → pages
+- **Design Tokens**: Single source of truth for colors, typography, spacing, motion
+- Base-8 spacing scale (4, 8, 16, 24, 32, 48px)
+- Maximum 2 font families; body text minimum 16px
+- Color system: primary, secondary, neutral, error, warning, success, info
+
+---
+
+## Accessibility (WCAG 2.2 AA)
+
+- **POUR**: Perceivable, Operable, Understandable, Robust
+- Keyboard navigation for all functionality; no keyboard traps
+- Screen reader tested (VoiceOver, NVDA, TalkBack)
+- 4.5:1 contrast for text, 3:1 for large text and UI components
+- ARIA used as supplement to semantic HTML, not replacement
+- Follow ARIA APG patterns for complex widgets
+- Cognitive accessibility: plain language, predictable patterns, undo support
+
+---
+
+## Emotional Design
+
+- **Norman's 3 Levels**: Visceral (looks), behavioral (works), reflective (means)
+- **Peak-End Rule** (Kahneman): Peak moments and endings define memory
+- Trust building: transparency, consistency, competence, honest error handling
+- Frustration reduction is higher priority than delight addition
+- Dark pattern avoidance: confirmshaming, hidden costs, trick questions, forced continuity
+
+---
+
+## Handoff and Metrics
+
+- **Nielsen's 10 Heuristics** for usability evaluation
+- Specs include all states, responsive behavior, accessibility notes, animation details
+- Design QA: review implementation against spec at all breakpoints
+- UX metrics: task success rate (>90%), time on task, error rate, SUS score (>68)
+- Usability testing: 5 users per round, think-aloud, task-based, weekly cadence
+
+---
+
+## Decision Framework
+
+When evaluating design choices:
+
+1. Does it remove user frustration? (Highest priority)
+2. Does it meet accessibility requirements (WCAG 2.2 AA)?
+3. Does it follow established interaction patterns?
+4. Does it align with the design system?
+5. Does it add delight without adding complexity?