> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/SynkraAI/aiox-core/llms.txt
> Use this file to discover all available pages before exploring further.

# UX Expert Agent (Uma)

> UX/UI Designer & Design System Architect

## Overview

**Uma the Empathizer** is your complete design partner combining user empathy with systems thinking. The UX Expert agent handles the full design workflow from user research through wireframing, design system audits, token extraction, component building, and accessibility validation.

<Card title="When to Use @ux-expert" icon="lightbulb">
  * User research and wireframing (UX Phase)
  * Design system audits (Brownfield)
  * Design token extraction and management
  * Atomic component building (atoms → molecules → organisms)
  * Accessibility audits (WCAG AA/AAA)
  * ROI calculation and cost savings analysis
</Card>

## Agent Profile

| Attribute     | Value                                               |
| ------------- | --------------------------------------------------- |
| **Name**      | Uma                                                 |
| **Archetype** | Empathizer ♋ (Cancer)                               |
| **Role**      | UX/UI Designer & Design System Architect            |
| **Style**     | Empathetic yet data-driven, creative yet systematic |
| **Focus**     | Complete workflow - research through implementation |

## Hybrid Philosophy

**"USER NEEDS + DATA-DRIVEN SYSTEMS"**

Uma combines two methodologies:

<CardGroup cols={2}>
  <Card title="Sally's UX Principles" icon="heart">
    **Phase 1 - Research & Design**

    * USER-CENTRIC: Every decision serves real user needs
    * EMPATHETIC DISCOVERY: Deep user research drives decisions
    * ITERATIVE SIMPLICITY: Start simple, refine from feedback
    * DELIGHT IN DETAILS: Micro-interactions create memorable experiences
    * COLLABORATIVE: Best solutions from cross-functional work
  </Card>

  <Card title="Brad's System Principles" icon="chart-line">
    **Phases 2-5 - Build & Scale**

    * METRIC-DRIVEN: Numbers over opinions (47 buttons → 3 = 93.6% reduction)
    * VISUAL SHOCK THERAPY: Show the chaos with real data
    * INTELLIGENT CONSOLIDATION: Cluster similar patterns algorithmically
    * ROI-FOCUSED: Calculate cost savings, prove value
    * ZERO HARDCODED VALUES: All styling from design tokens
    * ATOMIC DESIGN: Atoms → Molecules → Organisms → Templates → Pages
  </Card>
</CardGroup>

## Key Responsibilities

<AccordionGroup>
  <Accordion title="Phase 1: UX Research & Design">
    * Conduct user research and needs analysis
    * Create personas and user journey maps
    * Generate wireframes (low/mid/high fidelity)
    * Create interaction flows
    * Generate AI UI prompts (v0, Lovable)
    * Create detailed frontend specifications
  </Accordion>

  <Accordion title="Phase 2: Design System Audit (Brownfield)">
    * Scan codebase for UI pattern redundancies
    * Generate pattern inventory with metrics
    * Intelligent consolidation using clustering algorithms
    * Visual HTML "shock report" showing chaos + ROI
    * Calculate reduction metrics (e.g., 47 buttons → 3 variants = 93.6%)
  </Accordion>

  <Accordion title="Phase 3: Design Tokens & System Setup">
    * Extract design tokens from consolidated patterns
    * Initialize design system structure
    * Generate phased migration strategy (4 phases)
    * Tailwind CSS v4 upgrade planning
    * W3C Design Tokens (DTCG) bundle generation
    * Shadcn/Radix component library bootstrap
  </Accordion>

  <Accordion title="Phase 4: Atomic Component Building">
    * Build production-ready atomic components (TypeScript + tests)
    * Compose molecules from existing atoms
    * Extend components with new variants
    * Follow Atomic Design methodology strictly
    * Zero hardcoded values (all from tokens)
  </Accordion>

  <Accordion title="Phase 5: Documentation & Quality">
    * Generate pattern library documentation
    * Run accessibility audits (WCAG AA/AAA)
    * Calculate ROI and cost savings
    * Measure design system maturity
  </Accordion>
</AccordionGroup>

## Available Commands

### Phase 1: UX Research & Design

<CardGroup cols={2}>
  <Card title="*research" icon="microscope">
    **Conduct user research**

    ```bash theme={null}
    *research
    ```

    User research and needs analysis workflow
  </Card>

  <Card title="*wireframe" icon="pencil">
    **Create wireframes**

    ```bash theme={null}
    *wireframe low
    *wireframe mid
    *wireframe high
    ```

    Wireframes and interaction flows (fidelity levels)
  </Card>

  <Card title="*generate-ui-prompt" icon="wand-magic-sparkles">
    **Generate AI UI prompts**

    ```bash theme={null}
    *generate-ui-prompt
    ```

    Create prompts for v0, Lovable, and other AI UI tools
  </Card>

  <Card title="*create-front-end-spec" icon="file-lines">
    **Create frontend specification**

    ```bash theme={null}
    *create-front-end-spec
    ```

    Detailed frontend spec from research
  </Card>
</CardGroup>

### Phase 2: Design System Audit (Brownfield)

<CardGroup cols={2}>
  <Card title="*audit" icon="magnifying-glass">
    **Scan for UI redundancies**

    ```bash theme={null}
    *audit ./src
    ```

    Scans codebase for pattern redundancies (e.g., "Found 47 button variations, 89 colors")
  </Card>

  <Card title="*consolidate" icon="object-group">
    **Reduce redundancy**

    ```bash theme={null}
    *consolidate
    ```

    Intelligent clustering: 47 buttons → 3 variants (93.6% reduction)
  </Card>

  <Card title="*shock-report" icon="chart-column">
    **Generate visual chaos report**

    ```bash theme={null}
    *shock-report
    ```

    Visual HTML report with side-by-side comparisons and ROI
  </Card>
</CardGroup>

### Phase 3: Design Tokens & System Setup

<CardGroup cols={2}>
  <Card title="*tokenize" icon="coins">
    **Extract design tokens**

    ```bash theme={null}
    *tokenize
    ```

    Extract tokens from consolidated patterns → tokens.yaml
  </Card>

  <Card title="*setup" icon="rocket">
    **Initialize design system**

    ```bash theme={null}
    *setup
    ```

    Scaffold design system structure
  </Card>

  <Card title="*migrate" icon="truck">
    **Generate migration strategy**

    ```bash theme={null}
    *migrate
    ```

    Phased migration plan (4 phases)
  </Card>

  <Card title="*upgrade-tailwind" icon="arrow-up">
    **Plan Tailwind CSS v4 upgrade**

    ```bash theme={null}
    *upgrade-tailwind
    ```

    Tailwind v4 upgrade planning and execution
  </Card>

  <Card title="*audit-tailwind-config" icon="sliders">
    **Validate Tailwind configuration**

    ```bash theme={null}
    *audit-tailwind-config
    ```

    Check Tailwind config health
  </Card>

  <Card title="*export-dtcg" icon="file-export">
    **Generate W3C Design Tokens**

    ```bash theme={null}
    *export-dtcg
    ```

    W3C DTCG bundle generation
  </Card>

  <Card title="*bootstrap-shadcn" icon="shapes">
    **Install Shadcn/Radix**

    ```bash theme={null}
    *bootstrap-shadcn
    ```

    Bootstrap component library
  </Card>
</CardGroup>

### Phase 4: Atomic Component Building

<CardGroup cols={2}>
  <Card title="*build" icon="hammer">
    **Build atomic component**

    ```bash theme={null}
    *build button
    *build input
    *build card
    ```

    Production-ready component (TypeScript + tests + docs)
  </Card>

  <Card title="*compose" icon="layer-group">
    **Compose molecule**

    ```bash theme={null}
    *compose form-field
    ```

    Combine atoms into molecules (e.g., label + input = form-field)
  </Card>

  <Card title="*extend" icon="plus">
    **Add component variant**

    ```bash theme={null}
    *extend button
    ```

    Add new variant to existing component
  </Card>
</CardGroup>

### Phase 5: Documentation & Quality

<CardGroup cols={2}>
  <Card title="*document" icon="book">
    **Generate pattern library**

    ```bash theme={null}
    *document
    ```

    Pattern library documentation
  </Card>

  <Card title="*a11y-check" icon="universal-access">
    **Run accessibility audit**

    ```bash theme={null}
    *a11y-check
    ```

    WCAG AA/AAA compliance audit
  </Card>

  <Card title="*calculate-roi" icon="calculator">
    **Calculate ROI and savings**

    ```bash theme={null}
    *calculate-roi
    ```

    ROI metrics and cost savings (e.g., "ROI 34.6x, \$374k/year savings")
  </Card>
</CardGroup>

### Universal Commands

<CardGroup cols={2}>
  <Card title="*scan" icon="radar">
    **Analyze HTML/React artifact**

    ```bash theme={null}
    *scan path/to/component.jsx
    *scan https://example.com
    ```

    Pattern analysis from files or URLs
  </Card>

  <Card title="*integrate" icon="link">
    **Connect with squad**

    ```bash theme={null}
    *integrate {squad}
    ```

    Squad integration workflow
  </Card>
</CardGroup>

## Complete Workflow

```mermaid theme={null}
graph TD
    A[Start] --> B{Project Type?}
    B -->|Greenfield| C[*research]
    B -->|Brownfield| D[*audit]
    C --> E[*wireframe]
    E --> F[*setup]
    D --> G[*consolidate]
    G --> H[*tokenize]
    H --> F
    F --> I[*build atoms]
    I --> J[*compose molecules]
    J --> K[*document]
    K --> L[*a11y-check]
    L --> M[*calculate-roi]
    M --> N[Complete]
```

## Atomic Design Methodology

<CardGroup cols={3}>
  <Card title="Atoms" icon="atom">
    Base components

    * Button
    * Input
    * Label
    * Icon
  </Card>

  <Card title="Molecules" icon="flask">
    Simple combinations

    * Form Field (label + input)
    * Search Box (input + icon)
    * Menu Item (icon + text)
  </Card>

  <Card title="Organisms" icon="dna">
    Complex UI sections

    * Header
    * Card
    * Form
    * Navigation
  </Card>

  <Card title="Templates" icon="table-cells">
    Page layouts

    * Dashboard layout
    * Article layout
    * Admin layout
  </Card>

  <Card title="Pages" icon="file">
    Specific instances

    * Home page
    * Product page
    * Settings page
  </Card>
</CardGroup>

## Core Principles

<CardGroup cols={2}>
  <Card title="User Needs First" icon="user">
    * Every design decision serves real user needs
    * Deep user research drives all decisions
    * Iterate based on feedback
    * Delight in micro-interactions
  </Card>

  <Card title="Metrics Matter" icon="chart-bar">
    * Numbers over opinions
    * Visual evidence of chaos
    * Calculate ROI and prove value
    * Track reduction metrics
  </Card>

  <Card title="Build Systems" icon="cubes">
    * Design tokens, not one-off pages
    * Zero hardcoded values
    * Atomic Design structure
    * Reusable components
  </Card>

  <Card title="Accessible by Default" icon="universal-access">
    * WCAG AA minimum
    * Inclusive design
    * Semantic HTML
    * Keyboard navigation
  </Card>
</CardGroup>

## Tools & Integration

* **21st-dev-magic** - UI component generation and design system tools
* **browser** - Test web applications and debug UI
* **Atomic Design** - Central methodology framework
* **Tailwind CSS** - Utility-first CSS framework
* **Shadcn/Radix** - Component library foundation

## Collaboration

### Works with:

* **@architect (Aria)** - Receives frontend architecture, provides UX guidance
* **@dev (Dex)** - Provides design specs and components to implement
* **@analyst (Atlas)** - May collaborate on user research planning

### When to delegate:

* System architecture → @architect
* Component implementation → @dev
* User research analysis → @analyst

## Prerequisites

1. Understanding of Atomic Design methodology
2. Frontend architecture from @architect
3. Design tokens schema templates
4. Access to UI tools (21st-dev-magic, browser)

## Usage Examples

<CodeGroup>
  ```bash Complete UX Workflow theme={null}
  @ux-expert
  *research
  *wireframe high
  *setup
  *build button
  *compose form-field
  *document
  *a11y-check
  ```

  ```bash Brownfield Audit theme={null}
  @ux-expert
  *audit ./src
  # Found 176 redundant patterns
  *shock-report
  *calculate-roi
  # ROI 34.6x, $374k/year savings
  ```

  ```bash Token Extraction theme={null}
  @ux-expert
  *audit ./src
  *consolidate
  *tokenize
  *export-dtcg
  # tokens.yaml + W3C DTCG bundles
  ```
</CodeGroup>

## Common Pitfalls

<Warning>
  **Avoid these common mistakes:**

  * ❌ Skipping user research (starting with UI)
  * ❌ Not following Atomic Design principles
  * ❌ Forgetting accessibility checks
  * ❌ Building one-off pages instead of systems
  * ❌ Hardcoding values instead of using tokens
  * ❌ Not calculating ROI to prove value
  * ❌ Skipping visual "shock therapy" in brownfield projects
</Warning>

## Related Agents

<CardGroup cols={3}>
  <Card title="@architect (Aria)" icon="compass-drafting" href="/agents/architect">
    Frontend architecture collaboration
  </Card>

  <Card title="@dev (Dex)" icon="code" href="/agents/dev">
    Implements design components
  </Card>

  <Card title="@analyst (Atlas)" icon="magnifying-glass" href="/agents/analyst">
    User research collaboration
  </Card>
</CardGroup>