agentic-team-templates 0.16.0 → 0.18.0

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

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