How to write a UI prompt for an AI coding agent
Turn a rough product idea into a buildable UI prompt with the user goal, behavior, states, constraints, and pass-or-fail checks.
A strong UI prompt tells the agent who needs what outcome, how the interface should behave, which states it must handle, what project constraints apply, and how to verify the result. Name a component only when its behavior fits the job.
1. Start with the user goal, not a component name
Say who is trying to finish what task and why it matters. Add a UI term only after its behavior matches that job. A component name is one possible solution, not the product goal.
- Weak: Add a beautiful glassmorphism dashboard.
- Better: Help a support lead spot unresolved tickets, understand urgency, and open the next ticket without losing the current filters.
2. Describe behavior, states, and boundaries
Explain what opens the interface, what changes after each action, how it closes, and what must stay saved. Include loading, empty, error, success, retry, cancel, and permission states when they can occur.
3. Choose a pattern by behavior, then add style and motion
Use the atlas when you can picture the interface but do not know its name. Compare close patterns before choosing. Keep behavior, visual style, and motion as separate decisions so an aesthetic request does not silently change how the product works.
4. Add acceptance criteria the agent can verify
Turn important rules into observable pass-or-fail checks. Cover keyboard use, visible focus, status announcements, small screens, zoom, reduced motion, loading, failure, retry, and data persistence where they apply.
5. Give project context before asking for code
Name the existing stack, design system, reusable components, data source, route, and files that are in scope. Tell the agent what must not change. It should still inspect the real project and its tests before editing.
6. Use a prompt structure that leaves decisions visible
A useful order is: outcome, users and situation, behavior, states, content and data, visual direction, accessibility, project constraints, acceptance criteria, and work that is out of scope. Mark assumptions and open questions instead of hiding them.
- Outcome: who should be able to do what when this work is complete?
- Behavior and states: how does the flow start, change, finish, fail, and recover?
- Checks: what exact evidence will show that the result works?