Feature Request: Design & UX Personas for Agent Teams

Feature Request: Design & UX Personas for Agent Teams

Preflight Checklist

• I have searched existing requests and this feature hasn't been requested yet
• This is a single feature request (not multiple features)

Problem Statement

Claude Code's agent teams currently spawn all teammates as undifferentiated general-purpose agents. This works well for technical tasks but lacks design-focused perspectives needed for UI/UX work.

When building user interfaces, teams need both:

1. Technical expertise - Code quality, patterns, implementation
2. Design expertise - Visual consistency, accessibility, user experience

Current agent personas (general-purpose, bash, explore, plan) are all code-centric. There's no way to have agents review components for:

• Design system token usage vs hardcoded values
• Accessibility compliance (WCAG, ARIA labels, keyboard navigation)
• Visual consistency with established patterns
• UX patterns (feedback states, error handling, loading states)

Concrete impact:

• Accessibility issues slip through reviews
• Design system inconsistencies accumulate
• UX edge cases get missed (empty states, error states)
• Component APIs become developer-focused rather than user-friendly

Proposed Solution

Add design-focused agent personas that can be used in Agent Teams alongside technical agents:

1. UX Designer Persona

System Prompt: "You are a UX Designer focused on user-centered design and best practices. When working on features:
- Apply UX design principles: hierarchy, affordance, feedback, consistency
- Advocate for the user's perspective - prioritize usability over developer convenience
- Design intuitive information architecture and user flows
- Consider all user states (loading, error, empty, success, partial content)
- Apply established UX patterns (Miller's Law, Fitts's Law, Hick's Law, Gestalt principles)
- Ensure accessible and inclusive design from the start
- Create clear visual hierarchy with proper spacing and typography
- Design for edge cases and failure modes, not just happy paths
- Validate solutions against user needs, not technical constraints"

2. Accessibility Specialist Persona

System Prompt: "You are an Accessibility Specialist focused on WCAG compliance and inclusive design. When reviewing implementations:
- Verify semantic HTML (proper heading structure, landmark regions, list structures)
- Check ARIA labels, roles, and states where needed
- Test keyboard navigation (visible focus, logical tab order, skip links)
- Validate screen reader compatibility (VoiceOver, NVDA, JAWS)
- Ensure color contrast meets WCAG AA standards (4.5:1 for normal text)
- Check text sizing and scalability (support 200% zoom without horizontal scroll)
- Validate form labels, error messages, and instructions
- Test with assistive technologies and document accessibility requirements
- Advocate for universal design - accessibility benefits everyone"

3. Design System Expert Persona

System Prompt: "You are a Design System Expert with an eye for pixel-perfect detail. When building features:
- Ensure exact adherence to design specifications (spacing, colors, typography, borders)
- Review implementations for visual consistency with Figma designs
- Catch pixel-level deviations: 1px border errors, incorrect border radius, misaligned elements
- Enforce design token usage (zero hardcoded colors, spacing, or font sizes)
- Recommend existing components over custom solutions to maintain consistency
- Guide component API design to match design system patterns
- Document patterns and provide examples for other developers
- Spot visual drift and inconsistencies across the application
- Validate that implementations match design specifications exactly
- Balance design ideals with technical feasibility"

4. QA Specialist Persona (New!)

System Prompt: "You are a QA Specialist focused on rigorous testing and quality assurance. When validating features:
- Design comprehensive test plans covering happy paths, edge cases, and failure scenarios
- Test boundaries: empty inputs, maximum values, null/undefined, network failures
- Validate cross-browser and cross-device compatibility
- Test error handling and recovery paths
- Ensure accessibility requirements are actually testable and verified
- Identify race conditions, timing issues, and state management bugs
- Validate data persistence and integrity
- Test user flows end-to-end, not just individual functions
- Verify requirements are completely met, not partially implemented
- Advocate for testability and error handling during development
- Think like a user trying to break the system - be thorough and skeptical"

Example Usage: Collaborative Agent Teams

# Enable agent teams
export CLAUDE_AGENT_TEAMS=true

# Create a balanced team for UI development
claude-code "Build a TreatmentCard component. UX Designer should spec the UI, Accessibility reviews, QA writes tests. Collaborate throughout."

Sample conversation showing cross-functional collaboration:

Phase 1: Requirements & Design

• You: "We need a treatment tracking feature for isolated animals"
• UX Designer: "Proposed: Treatment cards with progress bars, action buttons, empty states. Thoughts @Dev @QA?"
• QA: "I'll need to test: day counting accuracy, multiple treatments, edge cases (completion, overdue), error handling"
• Developer: "@UX - should completed treatments disappear or show history?"
• UX Designer: "Move to 'Completed' section at bottom with green checkmark. Keep for history."

Phase 2: Implementation with real-time collaboration

• Developer: "Implementing data structure. @UX - should 'notes' field be optional?"
• UX Designer: "Yes, optional. But we need 'startDate' displayed as 'Started: DD/MM/YYYY'"
• Developer: "Got it. @Design System Expert - use ActionCard as base?"
• Design System Expert: "Yes! Already has badge support. Use spacing.lg for padding, colors.primaryGreen for progress fill"
• Accessibility: "Add aria-label to progress bar: 'Treatment progress: day 3 of 10'. Use role='progressbar'"
• Developer: "All added. @QA - what test cases should I prioritize?"

Phase 3: QA validation

• QA: "Testing found: progress bar doesn't recalculate when duration changes. Future dates currently allowed."
• Developer: "Fixing progress calculation. @UX - should we prevent future dates?"
• UX Designer: "Yes - prevent with error: 'Administration date cannot be in the future'"
• QA: "Re-test: both fixes working. Recommend: Ready for production"
• Accessibility: "WCAG AA compliance verified. Sign-off: Approve"
• UX Designer: "Design system tokens used correctly. Sign-off: Approve"

Result: 4 personas collaborated through entire lifecycle, issues caught during planning, no rework needed.

Key Benefits of Cross-Communication

Traditional Workflow (Sequential):

Requirements → UX Design → Dev Implementation → QA Testing → (problems found) → Back to Design → Reimplement → Retest
Timeline: 2 weeks, 3+ rounds of rework

Collaborative Agent Team Workflow:

Requirements + UX + Dev + QA (all discuss from start)
→ Issues caught during planning
→ Dev asks UX questions BEFORE implementing
→ QA writes tests while Dev builds
→ Single round of testing
Timeline: 1 week, 1 round of refinement

Why it's faster:

• Upstream communication: Dev asks UX before coding, not after
• Parallel work: QA writes tests while Dev implements
• Fewer handoffs: Everyone shares context from the start
• Better decisions: Made with all perspectives in the room

Implementation Options

Option A: Built-in Personas (Recommended)

Add UX Designer, Accessibility Specialist, Design System Expert, and QA Specialist as built-in agent types, similar to how general-purpose, bash, explore exist today.

Benefits:

• Zero configuration required
• Immediate value for all users
• Consistent quality across projects

Option B: Custom Agent Definitions

Allow users to define these personas in .claude/agents/ files and reference them in Agent Teams (building on #24316).

Benefits:

• More flexible and extensible
• Users can customize for their design system
• Builds on existing custom agent work

Recommended: Provide both - built-in personas for immediate use, with customization option for advanced users.

Priority

Medium-High - Enhances Claude Code for UI-heavy projects and design system work.

Impact: High for teams building user interfaces, design systems, or accessibility-first applications.

Effort: Medium - Can leverage existing agent infrastructure; primarily requires new system prompts.

Relationship to Existing Requests

This request complements but is distinct from:

• #24316 (Custom agent definitions) - Focuses on technical permissions; this focuses on design/UX perspectives
• #6208 (Non-coding modes) - Covers business analysis; this covers design, accessibility, and QA
• #18212 (Custom agents) - General custom agents; this proposes specific design-focused built-ins

Use Case Example

Scenario: Building a treatment tracking feature

With collaborative agent teams:

1. All 4 personas collaborate from requirements through deployment
2. UX proposes solutions → Dev asks clarifying questions BEFORE coding
3. Design System Expert prevents reinventing existing components
4. QA writes tests while Dev implements (parallel work)
5. Accessibility reviews during implementation, not after
6. Issues caught early through cross-discussion
7. No rework needed - got it right the first time
8. 2 rounds of QA instead of typical 4-5
9. Time savings: ~40% compared to sequential workflow

Without collaborative teams:

• Sequential handoffs (UX → Dev → QA)
• Dev implements what they think UX wants
• QA finds issues later in the cycle
• Multiple rounds of rework
• Time lost to context switching between phases

Additional Context

Industry trend: Modern development increasingly blends design and code (design systems, UX engineering, frontend architecture). Tools that support both perspectives are more valuable than code-only or design-only tools.

Similar examples: Figma's Dev Mode (bridges design and development), Storybook (used by both designers and developers), Zeroheight (design system documentation for both roles).

Claude Code is uniquely positioned to bring AI assistance to this design+code intersection with collaborative agent teams.

---

Sources:

• Issue #24316 - Custom agent definitions for teams
• Issue #6208 - Non-coding focused modes
• Agent Teams Documentation