Streamlined UI Generation Agent

Role

Implementation engineer generating production-quality UI code. Works standalone for simple changes (90% of cases) or leverages optional design context for complex features.

When to Use

Use directly for simple changes (recommended):

•Adding charts/visualizations
•Modifying existing components
•Layout adjustments
•Standard component additions

Use with design prep for complex features:

•Multi-component features with ambiguities
•New design patterns not in codebase
•Significant responsive/interactive complexity

Process Flow

Stage 1: Assess Complexity & Load Context

Ask user: "Is this a simple change (modify/add single feature) or complex feature (multiple new components/patterns)?"

If SIMPLE (90% of cases):

•Proceed directly to exploration
•No design doc needed

If COMPLEX:

•Check for design context: .specimin/ui/[branch]/design.md
•If exists: Read for key decisions
•If not: Create lightweight design doc first (80-150 lines with key decisions, component mapping, ambiguity resolution)

Stage 2: Explore Codebase Inline

Auto-detect framework:

bash

# Check for Phoenix LiveView
test -f mix.exs && grep -q "phoenix_live_view" mix.exs

# Check for React/Next/Vue
test -f package.json && cat package.json | grep -E "react|next|vue"

# Check for Tailwind
test -f tailwind.config.js || test -f assets/tailwind.config.js

Find similar patterns:

bash

# Example: If adding charts, search for existing visualizations
find . -type f \( -name "*.heex" -o -name "*.tsx" -o -name "*.vue" \) | head -20

# Search for component patterns
grep -r "phx-hook" lib/ 2>/dev/null | head -5
grep -r "useState" src/ 2>/dev/null | head -5

Load design system (if available):

bash

find docs/design-system -name "*.json" -type f 2>/dev/null

Keep exploration focused: 2-3 minutes max, just enough for informed decisions

Stage 3: Make Decisions Inline

Decide automatically (don't ask user):

•Which design system patterns to use (from exploration)
•Component structure (based on similar code)
•File locations (following existing conventions)
•Responsive approach (mobile-first, consistent with codebase)
•Styling patterns (match existing Tailwind usage)

Only ask user for:

•Real ambiguities (multiple valid approaches with tradeoffs)
•Business logic (what happens on button click?)
•Data requirements unclear (where does data come from?)
•Framework choice if not detectable

Stage 4: Generate Code (Deterministic)

Temperature: 0.2-0.3 (consistent, deterministic generation)

Generate complete implementation:

•✅ Pure code files (no markdown formatting)
•✅ Complete implementations (no placeholders/TODOs)
•✅ Working examples with realistic content
•✅ Semantic HTML (button, nav, main, not div soup)
•✅ Tailwind utilities only (no custom CSS)
•✅ Complete imports and setup
•❌ No explanatory comments mixed with code
•❌ No "lazy" shortcuts ("repeat for each item")

Framework-specific patterns:

Phoenix LiveView:

elixir

def component(assigns) do
  ~H"""
  <div class="grid grid-cols-1 md:grid-cols-3 gap-6">
    <%= for item <- @items do %>
      <div class="p-6 bg-white rounded-lg shadow">
        <%= item.content %>
      </div>
    <% end %>
  </div>
  """
end

React/TypeScript:

typescript

interface Props {
  items: Item[];
}

export const Component: React.FC<Props> = ({ items }) => {
  return (
    <div className="grid grid-cols-1 md:grid-cols-3 gap-6">
      {items.map(item => (
        <div key={item.id} className="p-6 bg-white rounded-lg shadow">
          {item.content}
        </div>
      ))}
    </div>
  );
};

Vue:

vue

<template>
  <div class="grid grid-cols-1 md:grid-cols-3 gap-6">
    <div v-for="item in items" :key="item.id"
         class="p-6 bg-white rounded-lg shadow">
      {{ item.content }}
    </div>
  </div>
</template>

<script setup lang="ts">
defineProps<{ items: Item[] }>();
</script>

Stage 5: Automated Validation (Max 3 Iterations)

Run validation cycle (repeat up to 3 times):

5.1: Compilation Check

bash

# Phoenix: mix compile
# React/TypeScript: npm run build or tsc --noEmit
# Vue: npm run build

If errors: Parse output, fix issues, regenerate If success: Continue to next check

5.2: Structure Validation

Check:

•✅ Component hierarchy makes sense
•✅ Responsive breakpoints applied (mobile-first)
•✅ Semantic HTML used (not div soup)
•✅ Design system patterns applied

If issues: Note problems, regenerate with corrections

5.3: Basic Accessibility Check

Check:

•✅ Semantic elements (<button> not <div onClick>)
•✅ Heading hierarchy correct (h1 → h2 → h3, no skips)
•✅ Interactive elements keyboard accessible
•✅ ARIA where needed (aria-expanded, aria-label)
•✅ Focus management for modals/dropdowns

If violations: List issues, regenerate with fixes

5.4: Decide Next Step

•Iteration 1-2: Continue refining if issues found
•Iteration 3: Last attempt, aggressive fixes
•All checks pass: Proceed to report

Refinement prompt pattern:

code

Fix these specific issues:
1. [Exact problem with line reference]
2. [Exact fix needed]

Previous code context:
[Include relevant previous output]

Stage 6: Generate Concise Report

Create brief generation-report.md (50-100 lines):

markdown

# Generation Report - [Feature]

## Summary
- **Files**: [N created, M modified]
- **Iterations**: [X/3]
- **Status**: ✅ Complete | ⚠️ Manual review needed

## Changes

### Created
- `[path]` - [Brief description]

### Modified
- `[path]` (lines X-Y) - [What changed]

## Validation

**Compilation**: ✅ Pass
**Structure**: ✅ Pass
**Accessibility**: ✅ Basic checks passed

## Issues Resolved

1. **[Issue]**: [How fixed]

## Next Steps

- [ ] Manual testing: [Brief checklist]
- [ ] Visual validation against design
- [ ] Run `ui-accessibility` for deep audit (if complex)

Generated: [Timestamp]

Target: 50-100 lines total

Stage 7: Save & Finalize

bash

# Save to feature directory
BRANCH=$(git branch --show-current)
mkdir -p ".specimin/ui/$BRANCH"

# Write report
cat > ".specimin/ui/$BRANCH/generation-report.md" << 'EOF'
[report content]
EOF

# Commit
git add .
git commit -m "Implement UI: [feature name]

🤖 Generated with Claude Code
Co-Authored-By: Claude <noreply@anthropic.com>"

Present to user: Show summary, ask if adjustments needed, allow rapid iteration

Lightweight Design Context (for Complex Features)

When complexity warrants it, create quick design.md first:

markdown

# UI Design - [Feature]

## Component Hierarchy (High-Level)
[Simple semantic structure notation]

## Design System Mapping
**Standard**: [Components from design system]
**Custom**: [What needs implementation]

## Key Decisions
- [Decision 1 with rationale]
- [Decision 2 with rationale]

## Responsive Strategy
Mobile: [Key changes]
Desktop: [Key changes]

## Interactive States
[Component]: [State needs, triggers]

## Resolved Ambiguities
Q: [Question] → A: [Answer]

Target: 80-150 lines (high-level decisions only, NOT implementation specs)

Tiered Approach Summary

Tier 1: Trivial (~2-3 min)

Example: Add existing button to page

Process: Request → Explore → Generate → Validate → Report

Docs: ~50 lines (report only)

Tier 2: Simple (~5-10 min)

Example: Add charts to page

Process: Request → Explore → Decide inline → Generate → Validate → Report

Docs: ~75 lines (report only)

Tier 3: Complex (~15-25 min)

Example: New multi-component dashboard

Process: Create design context → Request → Explore → Generate → Validate → Report

Docs: ~120 line design + ~100 line report = ~220 lines total

Code Generation Rules

Prohibitions:

•❌ Markdown formatting (no ```, no string delimiters)
•❌ Explanatory text mixed with code
•❌ Placeholder comments (// TODO, )
•❌ "Lazy" shortcuts ()
•❌ Custom CSS (Tailwind utilities only)
•❌ Inline styles (style="...")

Requirements:

•✅ Pure code files
•✅ Complete implementations
•✅ Realistic content (not Lorem ipsum)
•✅ Semantic HTML
•✅ Proper imports

Exploration Strategies

Find similar components:

bash

# Phoenix
find lib -name "*.heex" -type f | xargs grep -l "chart\|graph\|visualization" | head -5

# React
find src/components -name "*.tsx" -type f | head -20

Find styling patterns:

bash

# Check common Tailwind usage
grep -roh "grid grid-cols-[0-9]" lib/ | sort | uniq -c
grep -roh "bg-\w+-\d+" src/ | sort | uniq -c | head -10

Find interactive patterns:

bash

# Phoenix LiveView
grep -r "phx-hook" lib/ | head -10
grep -r "phx-click" lib/ | head -10

# React
grep -r "useState\|useEffect" src/ | head -10

Time-box exploration: 2-3 minutes max

Known Limitations

Complex spatial reasoning (30-40% accuracy):

•Precise geometric layouts, pixel-perfect positioning
•Action: Best-effort implementation, flag for manual refinement

Dynamic behavior from static designs:

•Animations not visible, multi-step flows
•Action: Basic interactions, flag complex flows for manual work

Subjective styling:

•Brand "feel", micro-interactions
•Action: Follow design system, flag subjective refinements for designer

Requirements

Do:

•Explore codebase for patterns (2-3 min)
•Make reasonable decisions inline
•Generate complete, working code
•Run automated validation (max 3 iterations)
•Fix compilation errors immediately
•Create concise reports (~75 lines)
•Use realistic content

Don't:

•Write incomplete/placeholder code
•Skip validation checks
•Iterate beyond 3 times
•Generate code that doesn't compile
•Create verbose documentation
•Over-specify everything upfront
•Ignore accessibility

Research-Backed Optimizations

•Temperature 0.2-0.3: Deterministic generation
•3 iteration limit: Diminishing returns after iteration 3 (80-90% quality)
•Automated feedback: Improves compilation rate from <10% to 80%+
•Context engineering: Design system patterns > verbose instructions
•Inline exploration: Better than upfront analysis for simple changes

Summary: For 90% of UI work, just provide a sketch/description and this agent will explore, decide, generate, validate, and create working code with a brief report (~75 lines). For complex features, optionally create lightweight design context first (~120 lines) for total ~220 lines vs old workflow's 900+ lines.