The model isn’t the problem
How many times have you asked AI agents to generate some UI components that look OK, but the code is messy - or at least it doesn’t follow your codebase conventions? Then every change you need to make later is painful. The first thought is that the model is weak. But if you use modern AI models, this usually isn’t true: the newest models from OpenAI or Anthropic are strong.
The real problem is that you talk to the agent without a plan, without guidelines. You ask with a very limited description. If it doesn’t have a good plan, it will start to improvise very quickly.
When you don’t have a plan, AI fills the gaps with guesses
UI isn’t just markup. It includes state management, edge cases, accessibility, keyboard behavior, error handling, responsive design, and more. If you don’t write these rules down, the model has to guess and implement them by itself. This makes the code messy because you don’t maintain consistency across prompts and iterations. It can generate decent code and visuals in one pass, and then break it in the next pass when you want to add something to what you already had.
Let’s take a file upload component, for example. You write: “Build me a file upload component.” Now, imagine how many questions a frontend developer would have when they get such a request: what should validation look like, how should errors be handled, what about drag-and-drop, how do we inform the user about upload progress, and so on. Having those questions answered upfront can simplify your workflow with AI agents dramatically.
I switched from “generate a component” to “implement this spec.”
What does structured, ready-to-use data look like as a spec for an AI agent to work with? I started preparing specifications for UI components using a predefined schema. This way, each spec looks similar. I don’t forget any important parts, and my guides are concise. What does a spec include? Rules for state management, accessibility, and the overall design approach. A super minimal example:
Component: File Upload
States: idle, dragover, uploading(progress), success, error(retry)
Rules: accept=png/jpg/pdf, maxSize=10MB, multiple=true
A11y: keyboard trigger, aria-describedby errors, focus states
Output: React + Tailwind, no external deps
You’ll iterate anyway - so design for iteration.
Don’t expect good UI to be generated in one shot. You’ll iterate, and you’ll improve the initial specs and rules. I usually give the AI-ready specs, it generates the component, I iterate and fill the gaps, and then I update the original spec to include solutions for those gaps.
For example, I forgot about “remove file from list.” Now, it’s a line in the guide forever.
Guides compound. Components… mostly don’t.
Each time you discover an edge case, you add it once to the guide. The next project starts with a better baseline. You’re basically building “UI memory” outside your head. I usually don’t trust my memory - I trust a checklist I’ve already failed against. The guides are living documents that help in the future.
Less Ambiguity = less Improvisation
When constraints are explicit, the model has less room to invent. Without a spec, it might pick a random drag-and-drop library or architecture. AI will often go with wrong assumptions, invented props, inconsistent state logic, or styling approaches. With a spec, it has less room for invented pieces - it just follows the requirements.
Libraries come and go. My requirements don’t.
Libraries are awesome - don’t get me wrong. They improve implementation speed and consistency, but there’s also churn. You need to choose the right ones, and you need to update/upgrade them from time to time. It may or may not be simple in your project. You also end up patching them with custom solutions, so there’s a customization tax. They usually have opinionated patterns that may not match your product.
AI can generate code, and it does it better and better over time. What I really need are good requirements for it.
I built a small tool to store the guides (because my notes were chaotic).
At first, I stored the spec rules and guides in Markdown files as a plan for implementation, but I quickly noticed there were many repeatable patterns. I needed to copy them, merge them, and reuse them across many files. I thought it would be useful to have a single source for this data under one URL, so I could just pass it to an AI agent.
That’s how UIPotion.com came to life. It’s a catalog of UI guides/specs you can paste into AI and adapt. It’s mostly for my own workflow, but it might help if you’re doing similar experiments. The component specs are structured and based on a JSON schema for each category. That’s how I try to keep all component data consistent.
The workflow is very simple: you go to the UI Potion page, copy the link to a JSON file, and pass it to your AI agent. This can be in Cursor, v0, Lovable, or any similar service. This way, you don’t have to describe much, and you only iterate with fixes.
Try this once: write the guide before you generate the UI.
Experiment with this approach. Pick one UI element you generate often - like a modal, upload, table, etc. Write a mini spec. Generate from that. Keep the guide and always update it after you fix 1-2 issues. Don’t lock into UI libraries or frameworks; prepare general rules. Force the AI agent to review your codebase before implementing. It will adjust the solution accordingly.
If you try it, I’d love to hear what changed: did the first draft get cleaner? Does UI + AI work best when the spec is the artifact you maintain, not the code?
By the way, I’m working on a CLI tool/agent that’s aware of the HaroldJS static site generator and UI Potion. This way, you get results quicker. It’s still in active development, but please test and leave feedback: github.com/uiPotion/potion-kit.