Visuals enable Agent OS to direct your agents build interfaces that match your design vision. By including mockups, wireframes, or screenshots during the research phase, you give agents a clear visual target for implementation.
Including visuals is entirely optional, but when provided, they help reduce ambiguity and ensure the final implementation aligns with your expectations.
This page covers:
- When and where to add visuals
- File naming conventions
- Fidelity levels
- How visuals are used throughout the workflow
- Playwright integration
When and where to add visuals
Visuals are gathered during the research phase, which happens when you run the shape-spec command.
During this phase, Agent OS will prompt you about whether you have visual assets to include. If you do, place them in:
agent-os/specs/[this-spec]/planning/visuals/Commonly used formats for visuals: PNG, JPG, JPEG, PDF
Agent OS automatically detects and analyzes visual files in this folder, even if you don't explicitly mention them during the research phase.
File naming conventions
Give your visual files descriptive names that clearly indicate what they represent:
❌ Not descriptive
Screen Shot 2025-01-15.png
mockup-v3-final.jpg
image1.png
✅ Descriptive
user-profile-page.png
dashboard-mobile-320px.jpg
checkout-flow-wireframe.png
Consider including additional details in filenames:
- Component or page name:
user-profile-page.png - Viewport size:
dashboard-mobile-320px.jpg - State or variation:
form-validation-errors.png - Fidelity level:
checkout-flow-wireframe.png
Fidelity levels
Different visual assets serve different purposes. Agent OS recognizes two fidelity levels:
High-fidelity
Detailed mockups for exact implementation
High-fidelity mockups are detailed designs that agents should match closely, including exact colors, typography, spacing, and visual effects.
By default, Agent OS treats all visuals as high-fidelity unless you indicate otherwise.
Low-fidelity
Wireframes for structural guidance
Low-fidelity wireframes are rough layouts that provide structural guidance without dictating exact styling. Agents will use these for layout and component placement while applying your app's existing design system.
To indicate a visual is low-fidelity, include one of these keywords in the filename:
lofiorlo-fiwireframesketchrough
Example: homepage-wireframe.png or checkout-lofi-sketch.jpg
How visuals are used throughout the workflow
Visual assets are referenced at multiple stages of the Agent OS workflow:
1
Research phase
During shape-spec, Agent OS prompts you to add visuals and automatically detects any files placed in the planning/visuals/ folder.
It will then analyze the visuals and ask you clarifying questions based on what it "sees" in them, to help you refine the planning of this feature spec.
2
Specification phase
During write-spec, Agent OS references the visuals when generating the spec, mapping UI components and requirements to the visual assets.
3
Implementation phase
During implement-tasks or orchestrate-tasks, your agents reference the visuals to build components that match the design.
4
Verification phase
During final verification, your agents compare the implementation against the original visuals to ensure alignment.
Playwright integration
Agent OS includes Playwright MCP integration for browser-based visual verification. This enables agents to launch browsers, take screenshots, and compare implementations against your visual assets.
Using Playwright is optional. Without it, your agents can still analyze your visual assets and use them to guide their work. However, it's highly recommended since it adds a lot more reliability and accuracy to agents' visual UI implementation. And it's free!
To install Playwright, follow the instructions in the Playwright MCP repository.
Using Playwright with your agents
When creating custom Claude Code subagents for UI implementation, you can give them access to Playwright tools for browser-based verification.
Simply include Playwright in the tools available to your custom subagent. Learn more about the Playwright MCP integration.