Building a UI/UX Research Agent for Web Development

andreiluchici
Jan 22
5 min read

A practical guide to building an AI agent that automates design research

This image was generated using OpenAI's GPT-5.2 version.

Introduction

If you've been doing web development for any amount of time, you know the cycle: you need a landing page, you reach for shadcn, you get something that looks like every other SaaS landing page from 2023. Or worse—you're stuck on a bug, you've been copy-pasting between ChatGPT and your codebase for an hour, and you're one "I don't have access to your codebase" away from throwing your laptop.

The naive workflow looks like this: complain to ChatGPT about what's broken, ask it what info it needs, switch to another tool to extract the relevant code, paste everything back, and repeat until sanity depletes. Too much context-switching. Too many iterations.

What if we could externalise this entire process? An agent that takes your complaint, digs through your codebase, researches solutions, and comes back with actual fresh ideas—not the same recycled Tailwind templates.

That's what we're building today: fixitmany.

Use Cases for our Research Agent

Use Case 1: Design Inspiration

You want to improve a landing page, but you're out of ideas. Or you have a vision, but every AI suggestion is the same hero-section-with-gradient nonsense. The agent should:

Understand your current design
Research fresh, unconventional approaches
Suggest specific implementations that aren't just "add a CTA button"

Use Case 2: Bug Research

You've got a bug you can't crack. The agent should:

Extract relevant code segments automatically
Research similar issues and solutions
Come back with targeted fixes, not generic advice

Use Case 3: Component Modernisation

You have an existing component that works but feels dated or clunky. Maybe it's a card, a modal, or a data table. The agent should:

Analyse your current implementation
Research modern patterns for that component type
Suggest specific improvements (accessibility, animations, UX patterns)
Provide updated code that you can drop in

Architecture

We're building a tool-using agent with five core capabilities:

read_file - Extract code from your project
list_files - Understand project structure
write_file - Output improved components
search_web - Research design trends and solutions
fetch_url - Read documentation and articles

The key insight is that the agent decides which tools to use and when. You give it a problem, and it figures out the research path. The agentic loop follows a simple pattern:

Think → Act → Observe → Repeat.

The agent supports multiple LLM providers: Anthropic (Claude), OpenAI (GPT), and Google (Gemini). This flexibility allows you to choose the model that best fits your needs or switch between providers as needed.

Step-by-Step Tutorial

Step 1: Project Setup

Clone the repository and install as a global CLI command:

git clone https://github.com/m-dragosvelicu/ui-agent.gitcd ui-agent/uiux-agentpip install -e .

This installs fixitmany as a command you can run from anywhere.

Step 2: Configure API Keys

Set your API key as an environment variable. You only need the key for the provider you want to use. Gemini is the default provider:

# For Gemini (default)
export GOOGLE_API_KEY="your-key"

# For Claude
export ANTHROPIC_API_KEY="your-key"

# For OpenAI
export OPENAI_API_KEY="your-key"

Or create a .env file in the uiux-agent directory:

cp .env.example .env 
# Edit .env and add your key(s)

Step 3: Run the Agent

Point it at your project and describe what you need:

# Basic usage (Gemini is default)
fixitmany "Improve my landing page" -p ./my-project

# Use Claude instead
fixitmany --provider anthropic "Fix this bug" -p ./my-project

# Use OpenAI instead
fixitmany --provider openai "Modernize this component" -p ./my-project

# Interactive chat mode
fixitmany --interactive -p ./my-project

How It Works Under the Hood

The Tools

The agent has five tools defined in tools.py. Each tool is a Python function that performs a specific action:

read_file: Reads file contents with truncation for large files
list_files: Recursively lists files, skipping node_modules and .git
write_file: Creates directories as needed and writes content
search_web: Uses DuckDuckGo HTML search for web results
fetch_url: Extracts clean text content from web pages

The Provider Abstraction

The providers.py file defines a common interface that works with Anthropic, OpenAI, and Gemini. Each provider converts messages and tool definitions to its native format, allowing you to switch between models with a simple --provider flag.

The Agent Loop

The agent.py file contains the main loop. It continuously calls the LLM until it gets a final response or reaches the maximum iteration limit (15 by default).

The loop works as follows:

Send the user's task to the LLM with available tools
If the LLM returns tool calls, execute them
Feed the tool results back to the LLM
Repeat until the LLM provides a final answer
Return the final text response to the user

Real Example: Improving a Product Card

Let's see the agent in action. We have a basic product card component—functional but forgettable. It's the kind of card you've seen on every e-commerce tutorial since 2019: border, rounded corners, shadow, done.

The original component:

export function ProductCard({ title, price, image, description, onAddToCart }) {
  return (
    <div className="border rounded-lg p-4 shadow-sm">
      <img src={image} alt={title} className="w-full h-48 object-cover rounded" />
      <h3 className="text-lg font-semibold mt-2">{title}</h3>
      <p className="text-gray-600 text-sm mt-1">{description}</p>
      <div className="flex justify-between items-center mt-4">
        <span className="text-xl font-bold">${price}</span>
        <button onClick={onAddToCart} className="bg-blue-500 text-white px-4 py-2 rounded">
          Add to Cart
        </button>
      </div>
    </div>
  );
}

Running the agent:

fixitmany "This product card is boring. Every e-commerce site looks like this. I want something that feels premium and modern - maybe some micro-interactions, better visual hierarchy." -p ./example-project

What the Agent Does

The agent autonomously executes the following steps:

list_files("./example-project") → maps the project structure
read_file("./example-project/components/ProductCard.tsx") → examines current code
search_web("modern product card design trends 2024 e-commerce") → finds current patterns
search_web("framer motion product card hover animations") → digs into specific techniques
write_file("./example-project/components/ProductCard.improved.tsx") → outputs the improved version

Agent Output

The agent's analysis:

"This card screams 'Bootstrap tutorial from 2019'. Here's what's wrong: Zero hierarchy—the price and button compete for attention. No interactivity—static as a newspaper ad. Generic shadow—the 'I learned CSS yesterday' special."

The agent recommends:

Stacked visual layers using subtle transforms on hover
Price badge that floats over the image corner
Animated cart button that expands with a satisfying spring
Quick-view overlay on image hover

The agent then writes a completely improved component using Framer Motion for animations, with proper hover states, visual hierarchy, and micro-interactions.

What Makes This Different

Externalised thinking – You fire off the task and come back to the results
Tool-use autonomy – The agent decides what to research, not you
Fresh perspectives – By searching beyond its training data, it finds current trends
Codebase awareness – It reads your actual code, not generic examples
Multi-provider support – Switch between Claude, GPT, or Gemini based on your needs

Safety

The agent NEVER overwrites existing files. If you ask it to write to a file that already exists, it creates a new file with a .new suffix instead. For example, if ProductCard.tsx exists, the agent will create ProductCard.new.tsx instead of overwriting the original.

Stop settling for stale components. Build agents that find the fresh stuff for you. The key difference from manual copy-paste workflows, the agent makes the research decisions itself. It doesn't just search once—it iterates based on what it finds, then writes the improved component directly to your project.

Repository: https://github.com/m-dragosvelicu/ui-agent