agentic-team-templates 0.16.0 → 0.17.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentic-team-templates",
-  "version": "0.16.0",
+  "version": "0.17.0",
   "description": "AI coding assistant templates for Cursor IDE. Pre-configured rules and guidelines that help AI assistants write better code. - use at your own risk",
   "keywords": [
     "cursor",

package/src/index.js

@@ -112,6 +112,10 @@ const TEMPLATES = {
     description: 'AI agent utilities with context management and hallucination prevention',
     rules: ['action-control.md', 'context-management.md', 'hallucination-prevention.md', 'overview.md', 'token-optimization.md']
   },
+  'ux-designer': {
+    description: 'Principal-level UX design with user research, interaction design, design systems, accessibility, and emotional design',
+    rules: ['accessibility.md', 'emotional-design.md', 'handoff.md', 'information-architecture.md', 'interaction-design.md', 'overview.md', 'research.md', 'visual-design.md']
+  },
   'web-backend': {
     description: 'Backend APIs and services (REST, GraphQL, microservices)',
     rules: ['api-design.md', 'authentication.md', 'database-patterns.md', 'error-handling.md', 'overview.md', 'security.md', 'testing.md']
@@ -143,6 +147,10 @@ const TEMPLATE_ALIASES = {
   'cs': 'csharp-expert',
   'teach': 'educator',
   'teacher': 'educator',
+  'ux': 'ux-designer',
+  'uxd': 'ux-designer',
+  'design': 'ux-designer',
+  'designer': 'ux-designer',
 };
 
 /**
@@ -262,6 +270,7 @@ ${colors.yellow('Shorthand Aliases:')}
   cpp                            → cpp-expert
   csharp, cs                     → csharp-expert
   teach, teacher                 → educator
+  ux, uxd, design, designer      → ux-designer
 
 ${colors.yellow('Examples:')}
   npx cursor-templates js

package/src/index.test.js

@@ -98,6 +98,7 @@ describe('Constants', () => {
         'swift-expert',
         'testing',
         'utility-agent',
+        'ux-designer',
         'web-backend',
         'web-frontend',
       ];

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

@@ -0,0 +1,214 @@
+# Accessibility
+
+Designing inclusive experiences that work for all users regardless of ability, device, or context.
+
+## Core Principle
+
+**Accessibility is not a feature — it is a requirement.** An inaccessible product is a broken product. Design for the most constrained user and everyone benefits.
+
+## WCAG 2.2 AA — POUR Framework
+
+The Web Content Accessibility Guidelines organize requirements into four principles:
+
+### Perceivable
+
+Users must be able to perceive all information and UI components.
+
+```markdown
+Requirements:
+- Text alternatives for non-text content (alt text, aria-labels)
+- Captions and transcripts for audio/video content
+- Content adaptable to different presentations (screen reader, zoom, reflow)
+- Sufficient color contrast (4.5:1 for text, 3:1 for large text and UI components)
+- No information conveyed by color alone (add icons, text, patterns)
+- Text resizable up to 200% without loss of content or function
+- Content reflows at 320px width without horizontal scrolling
+```
+
+### Operable
+
+Users must be able to operate all UI components and navigation.
+
+```markdown
+Requirements:
+- All functionality available via keyboard
+- No keyboard traps (users can always Tab/Escape out)
+- Skip navigation link as first focusable element
+- Visible focus indicators on all interactive elements
+- No time limits (or provide extend/disable options)
+- No content that flashes more than 3 times per second
+- Page titles describe topic or purpose
+- Focus order follows logical reading sequence
+- Link purpose clear from link text alone (no "click here")
+- Multiple ways to find pages (navigation, search, sitemap)
+- Touch targets minimum 24x24px (44x44px recommended)
+```
+
+### Understandable
+
+Users must be able to understand the information and UI operation.
+
+```markdown
+Requirements:
+- Language of page declared in HTML lang attribute
+- Consistent navigation across pages
+- Consistent identification of UI components
+- Error identification with clear description
+- Labels or instructions for user input
+- Error prevention for legal/financial/data submissions (review before submit)
+- Context does not change unexpectedly on focus or input
+```
+
+### Robust
+
+Content must work with current and future assistive technologies.
+
+```markdown
+Requirements:
+- Valid HTML with proper semantic structure
+- Name, role, value programmatically determinable for all UI components
+- Status messages communicated via ARIA live regions without focus change
+- Compatible with screen readers, voice control, switch devices, and magnification
+```
+
+## Keyboard Navigation
+
+```markdown
+Requirements:
+- Tab: Move forward through focusable elements
+- Shift+Tab: Move backward
+- Enter/Space: Activate buttons and links
+- Arrow keys: Navigate within components (tabs, menus, radio groups)
+- Escape: Close modals, dropdowns, popovers
+- Home/End: Jump to first/last item in a list or slider
+
+Focus management:
+- Focus moves into modal when opened, returns to trigger when closed
+- Focus never gets lost or stuck
+- Focus indicators visible in all themes (light and dark)
+- Custom focus styles: minimum 2px solid outline with offset, 3:1 contrast ratio
+
+Tab order:
+- Follows visual layout (left-to-right, top-to-bottom in LTR languages)
+- Skip hidden/inactive elements
+- tabindex="0" for custom interactive elements
+- tabindex="-1" for programmatic focus (not in tab order)
+- Never use tabindex > 0 (breaks natural order)
+```
+
+## Screen Readers
+
+```markdown
+Semantic HTML:
+- Use <nav>, <main>, <header>, <footer>, <aside>, <section>, <article>
+- Headings form a logical outline (h1 → h2 → h3, no skipping levels)
+- Lists use <ul>/<ol>/<dl>, not styled divs
+- Tables use <th>, <caption>, and scope attributes
+- Forms use <label> associated with inputs via for/id
+
+ARIA (Accessible Rich Internet Applications):
+- Use native HTML elements first; ARIA is a supplement, not a replacement
+- aria-label: Name an element when visible text is insufficient
+- aria-describedby: Associate additional descriptions
+- aria-live="polite": Announce dynamic content changes (toasts, status updates)
+- aria-live="assertive": Interrupt for urgent messages (errors)
+- aria-expanded: Communicate open/closed state of collapsibles
+- aria-hidden="true": Hide decorative content from assistive tech
+- role attributes: Only when native HTML semantics are insufficient
+
+Testing:
+- Test with VoiceOver (macOS/iOS), NVDA or JAWS (Windows), TalkBack (Android)
+- Navigate the entire flow using only the screen reader
+- Verify all actions can be completed without visual reference
+```
+
+## ARIA Authoring Practices Guide (APG)
+
+Follow the WAI-ARIA APG patterns for complex components:
+
+```markdown
+Common patterns:
+- Accordion: aria-expanded, aria-controls, Enter/Space to toggle
+- Dialog (Modal): aria-modal, focus trap, Escape to close
+- Tabs: role="tablist"/"tab"/"tabpanel", Arrow keys to switch
+- Combobox: role="combobox", aria-autocomplete, list association
+- Menu: role="menu"/"menuitem", Arrow keys, Enter to select
+- Tooltip: role="tooltip", aria-describedby, Escape to dismiss
+- Disclosure: aria-expanded, controls relationship
+
+Rules:
+- Follow the APG keyboard interaction patterns exactly
+- Test with assistive technology, not just keyboard
+- Complex widgets need comprehensive ARIA markup
+```
+
+## Inclusive Design (Microsoft)
+
+Design for the full range of human diversity.
+
+```markdown
+Disability spectrum:
+  Permanent → Temporary → Situational
+  One arm    → Arm injury  → Carrying a baby
+  Blind      → Eye surgery → Driving
+  Deaf       → Ear infection → Loud environment
+  Non-verbal → Laryngitis  → Non-native speaker
+
+Principles:
+1. Recognize exclusion (who can't use this?)
+2. Learn from diversity (edge cases reveal design flaws)
+3. Solve for one, extend to many (curb cuts help wheelchairs, strollers, bikes)
+```
+
+## Cognitive Accessibility
+
+```markdown
+Guidelines:
+- Use plain language (aim for 8th-grade reading level)
+- Break content into short, scannable chunks
+- Use consistent and predictable patterns
+- Provide clear error messages with recovery instructions
+- Avoid time pressure (allow extended time or remove limits)
+- Support undo for destructive actions
+- Minimize required memory (show context, don't require recall)
+- Use familiar icons and established UI patterns
+- Progress indicators for multi-step processes
+- No unexpected changes in context
+```
+
+## Testing Checklist
+
+```markdown
+Automated (catch ~30% of issues):
+- axe-core or Lighthouse accessibility audit
+- Color contrast checker
+- HTML validation
+
+Manual (catch ~70% of issues):
+- Keyboard-only navigation (can you complete every task?)
+- Screen reader walkthrough (does every element announce correctly?)
+- Zoom to 200% (does content reflow without horizontal scroll?)
+- Color blindness simulation (is meaning preserved?)
+- Reduced motion test (does prefers-reduced-motion work?)
+- Touch target size verification (44x44px minimum)
+- Focus order verification (logical and predictable?)
+- Form error experience (clear, specific, recoverable?)
+
+User testing:
+- Include users with disabilities in research participants
+- Test with the assistive technologies your users actually use
+- Observe real behavior, don't rely on automated reports alone
+```
+
+## Anti-Patterns
+
+```markdown
+- Accessibility overlay widgets: Third-party "fix-it" overlays don't work and create new problems
+- Missing alt text: Images without alternatives are invisible to screen readers
+- Placeholder-only labels: Placeholders disappear on focus, leaving users without context
+- Focus suppression: outline: none without a replacement focus style
+- Mouse-only interactions: Drag-and-drop, hover reveals, or swipe without keyboard alternatives
+- CAPTCHAs without alternatives: Audio CAPTCHA or bypass for authenticated users
+- Auto-playing media: Audio or video that plays without user initiation
+- "Accessibility is done": It's never done — it requires ongoing testing and maintenance
+```

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