A structured 4-stage workflow for creating and iterating on UI designs. This process ensures thoughtful design decisions with user approval at each stage.
Stages: Layout → Theme → Animation → Implementation
Approval: Required between each stage
Output: Single HTML file per design iteration
Location: design_iterations/ folder
✅ STRONGLY RECOMMENDED to delegate for:
Why delegate?
⚠️ Simple cases only:
// For UI design work
task(
subagent_type="OpenFrontendSpecialist",
description="Design {feature} UI",
prompt="Design a {feature} following the 4-stage workflow:
Requirements:
- {requirement 1}
- {requirement 2}
Context: {what this UI is for}
Follow the design iteration workflow:
1. Layout (ASCII wireframe)
2. Theme (design system, colors)
3. Animation (micro-interactions)
4. Implementation (single HTML file)
Request approval between each stage."
)
| Scenario | Action | Why |
|---|---|---|
| "Create a landing page for our SaaS product" | ✅ Delegate to OpenFrontendSpecialist | Complex UI design, needs 4-stage workflow |
| "Design a user dashboard with charts" | ✅ Delegate to OpenFrontendSpecialist | Complex layout, visual design, interactions |
| "Build a component library with our brand" | ✅ Delegate to OpenFrontendSpecialist | Design system work, requires theme expertise |
| "Fix button color from blue to green" | ⚠️ Execute directly | Simple CSS change |
| "Update hero text content" | ⚠️ Execute directly | Content update only |
CRITICAL: Before starting any design work, create a persistent design plan file.
Location: .tmp/design-plans/{project-name}-{feature-name}.md
Purpose:
When to Create:
Template:
---
project: {project-name}
feature: {feature-name}
created: {ISO timestamp}
updated: {ISO timestamp}
status: in_progress
current_stage: layout
---
# Design Plan: {Feature Name}
## User Requirements
{What the user asked for - verbatim or close paraphrase}
## Design Goals
- {goal 1}
- {goal 2}
- {goal 3}
## Target Audience
{Who will use this UI}
## Technical Constraints
- Framework: {Next.js, React, etc.}
- Responsive: {Yes/No}
- Accessibility: {WCAG level}
- Browser support: {Modern, IE11+, etc.}
---
## Stage 1: Layout Design
### Status
- [ ] Layout planned
- [ ] ASCII wireframe created
- [ ] User approved
### Layout Structure
{ASCII wireframe will be added here}
### Component Breakdown
{Component list will be added here}
### User Feedback
{User comments and requested changes}
---
## Stage 2: Theme Design
### Status
- [ ] Design system selected
- [ ] Color palette chosen
- [ ] Typography defined
- [ ] User approved
### Theme Details
{Theme specifications will be added here}
### User Feedback
{User comments and requested changes}
---
## Stage 3: Animation Design
### Status
- [ ] Micro-interactions defined
- [ ] Animation timing set
- [ ] User approved
### Animation Details
{Animation specifications will be added here}
### User Feedback
{User comments and requested changes}
---
## Stage 4: Implementation
### Status
- [ ] HTML structure complete
- [ ] CSS applied
- [ ] Animations implemented
- [ ] User approved
### Output Files
- HTML: {file path}
- CSS: {file path}
- Assets: {file paths}
### User Feedback
{Final comments and requested changes}
---
## Design Evolution
### Iteration 1
- Date: {timestamp}
- Changes: {what changed}
- Reason: {why it changed}
### Iteration 2
- Date: {timestamp}
- Changes: {what changed}
- Reason: {why it changed}
Workflow Integration:
.tmp/design-plans/{name}.mdBenefits:
Purpose: Create persistent plan file before any design work
Process:
.tmp/design-plans/{project-name}-{feature-name}.mdDeliverable: Design plan file created and initialized
Example:
✅ Design plan created: .tmp/design-plans/saas-landing-page.md
You can review and edit this file at any time. All design decisions will be tracked here.
Ready to proceed to Stage 1 (Layout Design)?
Approval Gate: "Plan file created. Ready to start layout design?"
Purpose: Define the structure and component hierarchy before visual design
Process:
.tmp/design-plans/{name}.mdDeliverable:
Example Output:
## Core UI Components
**Header Area**
- Logo/brand (Top left)
- Navigation menu (Top center)
- User actions (Top right)
**Main Content Area**
- Hero section (Full width)
- Feature cards (3-column grid on desktop, stack on mobile)
- Call-to-action (Centered)
**Footer**
- Links (4-column grid)
- Social icons (Centered)
- Copyright (Bottom)
## Layout Structure
Desktop (1024px+):
┌─────────────────────────────────────────────────┐
│ [Logo] Navigation [User Menu] │
├─────────────────────────────────────────────────┤
│ │
│ HERO SECTION │
│ (Full width, centered text) │
│ │
├─────────────────────────────────────────────────┤
│ ┌─────────┐ ┌─────────┐ ┌─────────┐ │
│ │ Card 1 │ │ Card 2 │ │ Card 3 │ │
│ │ │ │ │ │ │ │
│ └─────────┘ └─────────┘ └─────────┘ │
├─────────────────────────────────────────────────┤
│ [Call to Action] │
├─────────────────────────────────────────────────┤
│ Links Links Links Social │
│ Copyright │
└─────────────────────────────────────────────────┘
Mobile (< 768px):
┌─────────────────┐
│ ☰ Logo [👤] │
├─────────────────┤
│ │
│ HERO SECTION │
│ │
├─────────────────┤
│ ┌───────────┐ │
│ │ Card 1 │ │
│ └───────────┘ │
│ ┌───────────┐ │
│ │ Card 2 │ │
│ └───────────┘ │
│ ┌───────────┐ │
│ │ Card 3 │ │
│ └───────────┘ │
├─────────────────┤
│ [CTA] │
├─────────────────┤
│ Links │
│ Social │
│ Copyright │
└─────────────────┘
Approval Gate: "Would you like to proceed with this layout or need modifications?"
Purpose: Define colors, typography, spacing, and visual style
Process:
.tmp/design-plans/{name}.mdDeliverable:
design_iterations/theme_N.cssTheme Selection Criteria:
| Style | Use When | Avoid When |
|---|---|---|
| Neo-Brutalism | Creative/artistic projects, retro aesthetic | Enterprise apps, accessibility-critical |
| Modern Dark | SaaS, developer tools, professional dashboards | Playful consumer apps |
| Custom | Specific brand requirements | Time-constrained projects |
Example Output:
## Theme Design: Modern Professional
**Style Reference**: Vercel/Linear aesthetic
**Color Palette**: Monochromatic with accent
**Typography**: Inter (UI) + JetBrains Mono (code)
**Spacing**: 4px base unit
**Shadows**: Subtle, soft elevation
**Theme File**: design_iterations/theme_1.css
Key Design Decisions:
- Primary: Neutral gray for professional feel
- Accent: Subtle blue for interactive elements
- Radius: 0.625rem for modern, friendly feel
- Shadows: Soft, minimal elevation
- Fonts: System-like for familiarity
File Naming: theme_1.css, theme_2.css, etc.
Approval Gate: "Does this theme match your vision, or would you like adjustments?"
Purpose: Define micro-interactions and transitions
Process:
.tmp/design-plans/{name}.mdDeliverable:
Example Output:
## Animation Design: Smooth & Professional
### Button Interactions
hover: 200ms ease-out [Y0→-2, shadow↗]
press: 100ms ease-in [S1→0.95]
ripple: 400ms ease-out [S0→2, α1→0]
### Card Interactions
cardHover: 300ms ease-out [Y0→-4, shadow↗]
cardClick: 200ms ease-out [S1→1.02]
### Page Transitions
pageEnter: 300ms ease-out [α0→1, Y+20→0]
pageExit: 200ms ease-in [α1→0]
### Loading States
spinner: 1000ms ∞ linear [R360°]
skeleton: 2000ms ∞ [bg: muted↔accent]
### Micro-Interactions
inputFocus: 200ms ease-out [S1→1.01, ring]
linkHover: 250ms ease-out [underline 0→100%]
**Philosophy**: Subtle, purposeful animations that enhance UX without distraction
**Performance**: All animations use transform/opacity for 60fps
**Accessibility**: Respects prefers-reduced-motion
Approval Gate: "Are these animations appropriate for your design, or should we adjust?"
Purpose: Generate complete HTML file with all components
Process:
.tmp/design-plans/{name}.mdDeliverable:
File Organization:
design_iterations/
├── theme_1.css # Theme file from Stage 2
├── dashboard_1.html # Initial design
├── dashboard_1_1.html # First iteration
├── dashboard_1_2.html # Second iteration
├── chat_ui_1.html # Different design
└── chat_ui_1_1.html # Iteration of chat UI
Naming Conventions:
| Type | Format | Example |
|---|---|---|
| Initial design | {name}_1.html |
table_1.html |
| First iteration | {name}_1_1.html |
table_1_1.html |
| Second iteration | {name}_1_2.html |
table_1_2.html |
| New design | {name}_2.html |
table_2.html |
Implementation Checklist:
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>Design Name</title>
<!-- ✅ Preconnect to external resources -->
<link rel="preconnect" href="https://fonts.googleapis.com">
<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
<!-- ✅ Load fonts -->
<link href="https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700&display=swap" rel="stylesheet">
<!-- ✅ Load Tailwind (script tag, not stylesheet) -->
<script src="https://cdn.tailwindcss.com"></script>
<!-- ✅ Load Flowbite if needed -->
<link href="https://cdn.jsdelivr.net/npm/flowbite@2.0.0/dist/flowbite.min.css" rel="stylesheet">
<!-- ✅ Load icons -->
<script src="https://unpkg.com/lucide@latest/dist/umd/lucide.min.js"></script>
<!-- ✅ Link theme CSS -->
<link rel="stylesheet" href="theme_1.css">
<!-- ✅ Custom styles with !important for overrides -->
<style>
body {
font-family: 'Inter', sans-serif !important;
color: var(--foreground) !important;
}
h1, h2, h3, h4, h5, h6 {
font-weight: 600 !important;
}
/* Custom animations */
@keyframes fadeIn {
from { opacity: 0; transform: translateY(20px); }
to { opacity: 1; transform: translateY(0); }
}
.animate-fade-in {
animation: fadeIn 300ms ease-out;
}
</style>
</head>
<body>
<!-- ✅ Semantic HTML structure -->
<header>
<!-- Header content -->
</header>
<main>
<!-- Main content -->
</main>
<footer>
<!-- Footer content -->
</footer>
<!-- ✅ Load Flowbite JS if needed -->
<script src="https://cdn.jsdelivr.net/npm/flowbite@2.0.0/dist/flowbite.min.js"></script>
<!-- ✅ Initialize icons -->
<script>
lucide.createIcons();
</script>
<!-- ✅ Custom JavaScript -->
<script>
// Interactive functionality
</script>
</body>
</html>
Approval Gate: "Please review the design. Would you like any changes or iterations?"
Delegate to Image Specialist subagent when users request:
task(
subagent_type="Image Specialist",
description="Generate/edit visual content",
prompt="Context to load:
- .opencode/context/core/visual-development.md
Task: [Specific visual requirement]
Requirements:
- [Visual style/aesthetic]
- [Dimensions/format]
- [Key elements to include]
- [Color scheme/branding]
Output: [Expected deliverable]"
)
Architecture Diagram:
task(
subagent_type="Image Specialist",
description="Generate microservices architecture diagram",
prompt="Create a diagram showing:
- 5 microservices (API Gateway, Auth, Orders, Payments, Notifications)
- Database connections
- Message queue (RabbitMQ)
- External services (Stripe, SendGrid)
Style: Clean, professional, modern
Format: PNG, 1920x1080"
)
UI Mockup:
task(
subagent_type="Image Specialist",
description="Generate dashboard mockup",
prompt="Create a mockup for an analytics dashboard:
- Header with navigation
- 4 metric cards (Users, Revenue, Conversion, Retention)
- Line chart showing trends
- Data table below
Style: Modern, dark theme, professional
Format: PNG, 1440x900"
)
Social Media Graphic:
task(
subagent_type="Image Specialist",
description="Generate product launch graphic",
prompt="Create a social media graphic announcing new feature:
- Bold headline: 'Introducing Real-Time Collaboration'
- Subtext: 'Work together, ship faster'
- Brand colors: #6366f1 (primary), #1e293b (dark)
- Include abstract collaboration visual
Format: PNG, 1200x630 (Twitter/LinkedIn)"
)
Use design-iteration workflow instead when:
Use image-specialist when:
Create new iteration ({name}_1_1.html) when:
Create new design ({name}_2.html) when:
User: "Can you make the buttons larger and change the color?"
1. Read current file: dashboard_1.html
2. Make requested changes
3. Save as: dashboard_1_1.html
4. Present changes to user
User: "Perfect! Now can we add a sidebar?"
1. Read current file: dashboard_1_1.html
2. Add sidebar component
3. Save as: dashboard_1_2.html
4. Present changes to user
✅ Do:
❌ Don't:
✅ Do:
❌ Don't:
✅ Do:
❌ Don't:
✅ Do:
❌ Don't:
design_iterations/
├── theme_1.css
├── theme_2.css
├── landing_1.html
├── landing_1_1.html
├── landing_1_2.html
├── dashboard_1.html
├── dashboard_1_1.html
└── README.md (optional: design notes)
Track iterations:
design_1.htmldesign_1_1.htmldesign_1_2.htmldesign_1_3.htmlNew major version:
design_2.htmldesign_2_1.html, design_2_2.htmlAfter Layout:
"Here's the proposed layout structure. The design uses a [description].
Would you like to proceed with this layout, or should we make adjustments?"
After Theme:
"I've created a [style] theme with [key features]. The theme file is saved as theme_N.css.
Does this match your vision, or would you like to adjust colors/typography?"
After Animation:
"Here's the animation plan using [timing/style]. All animations are optimized for performance.
Are these animations appropriate, or should we adjust the timing/effects?"
After Implementation:
"I've created the complete design as {filename}.html. The design includes [key features].
Please review and let me know if you'd like any changes or iterations."
User requests change:
"I'll update the design with [changes] and save it as {filename}_N.html.
This preserves the previous version for reference."
Scenario: User opens .tmp/design-plans/{name}.md and makes changes
Process:
Example:
User: "I've updated the plan file - changed the color scheme to dark mode"
Agent:
✅ Read updated plan: .tmp/design-plans/saas-landing-page.md
Changes detected:
- Color scheme: Light → Dark mode
- Primary color: Blue → Purple
This affects:
- Stage 2 (Theme) - needs regeneration
- Stage 4 (Implementation) - needs CSS update
Would you like me to:
1. Regenerate theme with dark mode
2. Update implementation with new theme
Scenario: User requests changes during a stage
Process:
Example:
Stage 1 - Layout Design
Agent: [presents wireframe]
User: "Make the hero section taller and move CTA above the fold"
Agent:
✅ Updated plan file with feedback
✅ Revised layout wireframe
✅ Updated plan file with Iteration 2
[presents updated wireframe]
Format:
## Design Evolution
### Iteration 1 - Initial Layout
- Date: 2026-01-30T10:00:00Z
- Stage: Layout
- Changes: Initial wireframe created
- User feedback: "Hero section too short, CTA below fold"
### Iteration 2 - Revised Layout
- Date: 2026-01-30T10:15:00Z
- Stage: Layout
- Changes: Increased hero height from 400px to 600px, moved CTA above fold
- User feedback: "Perfect! Approved."
- Status: ✅ Approved
### Iteration 3 - Theme Adjustment
- Date: 2026-01-30T10:30:00Z
- Stage: Theme
- Changes: Changed from light to dark mode, primary color blue → purple
- User feedback: "Love the dark mode!"
- Status: ✅ Approved
Problem: Subagents lose context between calls
Solution: Always pass plan file path
Pattern:
// When delegating to subagent
task(
subagent_type="OpenFrontendSpecialist",
description="Implement Stage 4",
prompt="Load design plan from .tmp/design-plans/saas-landing-page.md
Read the plan file for:
- All approved decisions from Stages 1-3
- User requirements and constraints
- Design evolution and iterations
Implement Stage 4 (Implementation) following all approved decisions.
Update the plan file with:
- Output file paths
- Implementation status
- Any issues encountered"
)
Benefits:
Best Practices:
Before presenting each stage:
Layout Stage:
Theme Stage:
Animation Stage:
Implementation Stage:
Issue: User wants to skip stages Solution: Explain benefits of structured approach, but accommodate if insisted
Issue: Theme doesn't match user vision Solution: Iterate on theme file, create theme_2.css with adjustments
Issue: Animations feel too slow/fast Solution: Adjust timing in micro-syntax, regenerate with new values
Issue: Design doesn't work on mobile Solution: Review responsive breakpoints, add mobile-specific styles
Issue: Colors have poor contrast Solution: Use WCAG contrast checker, adjust OKLCH lightness values