Visual UI Verification
Relevant source files
The following files were used as context for generating this wiki page:
Visual UI Verification in the Barekey project is a systematic approach used by AI agents and developers to ensure the integrity of the user interface during development. It relies on the agent-browser toolset to capture baselines, annotate current states, and perform differential analysis to prevent unintended pixel changes or layout shifts.
This process is critical for maintaining "Vercel/Apple-tier DX," characterized by clean, minimal, and fast interfaces with clear hover/focus states for every interactive element. Verification occurs at multiple stages: before starting a task, after every UI change, and before finishing a task.
Sources: AGENTS.md:6-12, AGENTS.md:104-124
Workflow Architecture
The verification workflow is integrated into the agent's standard development cycle. It utilizes a local development server typically running on http://localhost:5173.
Verification Lifecycle
The following flowchart illustrates the mandatory steps for UI verification during a feature implementation:
The diagram shows the iterative nature of the verification process, moving from baseline capture to differential analysis.
Sources: AGENTS.md:104-124
Tooling and Commands
The primary tool for this system is agent-browser. It provides three distinct functions: capturing raw visuals, generating structural snapshots, and performing image differencing.
| Command | Purpose | Usage Phase |
|---|---|---|
agent-browser open <url> | Opens the browser at the local dev environment URL. | Initial setup |
agent-browser screenshot <name>.png | Captures a raw image of the current UI. | Baseline |
agent-browser snapshot -i | Generates a structural reading of the UI elements. | Implementation |
agent-browser screenshot --annotate <name>.png | Captures a screenshot with @ref IDs for interaction. | Iteration |
agent-browser diff screenshot --baseline <file>.png | Compares current state against the baseline. | Finalization |
Sources: AGENTS.md:104-124
Component-Specific Verification
Different pages within the Barekey UI have specific verification requirements based on their complexity and interactive elements.
Variable Management UI
The Variables page requires verification of complex states including draft changes, decrypted values, and file import previews. Verification must confirm that:
- Encrypted values are masked as
••••••••••until decrypted. - Draft rows (new or updated) are visually distinct or correctly listed in the table.
- The "Save all" and "Discard all" buttons accurately reflect the existence of unsaved changes.
Sources: pkg/ui/src/pages/o/[org]/project/[projectSlug]/variables/page.tsx:100-140, pkg/ui/src/pages/o/[org]/project/[projectSlug]/variables/page.tsx:430-460
Organization and Project Settings
Verification for settings pages focuses on state transitions such as:
- Loading States: Skeletons must be visible while queries are pending.
- Destructive Actions: Confirmation dialogs (e.g., project deletion) must show countdowns or prerequisites correctly.
- Input Validation: Error messages must appear when invalid names or slugs are entered.
Sources: pkg/ui/src/pages/o/[org]/projects/page.tsx:120-150, pkg/ui/src/pages/o/[org]/settings/page.tsx:400-450
Implementation Standards
To ensure successful verification, the UI must adhere to specific TypeScript and Styling rules.
- Styling: Only Shadcn components and Tailwind utility classes are permitted; custom CSS is avoided unless strictly necessary.
- Interactivity: Every interactive element MUST have clear hover and focus states.
- Accessibility: Interaction with elements during verification is handled via
@refIDs provided by theagent-browserannotation system.
Sources: AGENTS.md:143-146, AGENTS.md:113-115
Known Limitations and Troubleshooting
In certain environments, visual verification may be blocked due to network restrictions.
- Localhost Access: In some execution environments,
agent-browsermay fail to navigate tolocalhostwithnet::ERR_INTERNET_DISCONNECTED. - Fallback Strategy: If visual verification is blocked, the workflow reverts to code review, linting, and UI build validation only.
- Route Collisions: Verification must account for reserved slugs like
/o/newor/o/selectwhich could override dynamic organization routes.
Sources: INDEX.md:38-46, INDEX.md:49-52
Summary
Visual UI Verification is a core pillar of the Barekey development workflow. By enforcing baseline comparisons and annotated snapshots, the project ensures that its high standard for developer experience (DX) is maintained across every commit, preventing regressions in layout, interactivity, or visual styling.