I started building UI screens with coding agents for college projects. Sometimes I needed a new screen; other times I just needed to adjust an existing one. A recurring frustration was that the agent would introduce design choices that felt generic or didn't fit the project, leaving me to work through another round of corrections.

That led me to build flawless-ui-ux, a free, open-source UI/UX skill and local inspection CLI. I still use it for my college work, but I wanted other developers to be able to use it in their own projects too. It works with Claude Code, Codex, and other coding agents.

The useful question became: how do I give the agent enough context to make better decisions, then inspect what it actually built?

Two examples of refinement

The coffee shop homepage and fintech SaaS dashboard below are illustrative examples, not college assignments. Both started in Codex with GPT 6.1 Sol on low reasoning, followed by refinement with the skill using the same model and reasoning setting.

These are sequential before-and-after examples. The refined version gets another pass over an existing interface, so this is not a controlled comparison that isolates the skill's effect, or evidence that every task will improve in the same way.

A coffee shop homepage

Before:

Coffee shop homepage before refinement: a split hero with a large slogan, coffee photograph, and oversized logo over the image.

After:

Coffee shop homepage after refinement: a prominent Bruma wordmark, plain description, menu button, opening hours, location, and a coffee photograph.

The initial screen already had a clear visual direction. The refinement changed the hierarchy: the café name became the main heading, the description explained what the place serves, and opening hours and location moved into the first screen. The photograph remained central without carrying an oversized second wordmark.

That gives me specific choices to evaluate: can a visitor understand the business, find its menu, and work out when and where to visit? Whether the new type and palette fit a real café would still depend on its identity.

A fintech SaaS dashboard

Before:

Fintech dashboard before refinement: green-tinted metric cards, a welcome heading, promotional sidebar panel, and cash-flow chart.

After:

Fintech dashboard after refinement: a financial-overview heading, flatter account-summary row, reduced sidebar promotion, and more restrained chart and card styling.

Here, the refinement reduced competing surfaces. The top metrics became a flatter summary row, the heading named the screen's purpose, and the sidebar promotion disappeared. The cash-flow chart and account information remained the core content.

This is a different design problem from the café hero. I want a dashboard to make comparison and repeated use easier. A screenshot can show hierarchy and density, but it cannot establish that the underlying calculations or interactions are correct.

Give the agent a task it can evaluate

The skill connects design decisions to the audience, content, and identity of the project. When asking for a change, I can also limit the scope. For example:

Use the flawless-ui-ux skill to review this dashboard. It is for freelancers checking income and expenses. Improve hierarchy and readability while preserving the existing data, actions, and brand colors. Explain the changes and check the rendered result.

This is an example request readers can adapt, not the recorded prompt behind the screenshots above.

Inspect the implementation after the visual pass

The CLI provides observations for the agent to review. Source checks and browser checks have different coverage: inspecting a file alone does not establish what the page looks like at a particular viewport.

For a project using src/App.tsx:

npx flawless-ui-ux inspect --project . --source src/App.tsx --format json

For browser inspection, start the app separately and prepare Chromium once:

npx playwright@1.64.1 install chromium

Then inspect your actual development-server URL and save a baseline in a new directory:

npx flawless-ui-ux inspect --project . --source src/App.tsx --url http://localhost:5173 --output ../app-before --format json

After making corrections, verify against the saved scope:

npx flawless-ui-ux verify ../app-before/run.json --output ../app-after --format json

Replace the source path and URL with your own. Browser checks include selected accessibility rules, horizontal overflow, computed text sizes, visible broken images, and uncaught JavaScript errors. Verification distinguishes persistent, new, and no-longer-observed findings.

Those observations help with review. They do not certify accessibility, measure design quality, or prove that every user journey works. I would still review the screenshots and test the interactions that matter.

Try it in your own project

The CLI requires Node.js 22.12 or newer. To install the skill for Claude Code:

npx flawless-ui-ux@latest install --claude-code

You can also install the skill through the Skills CLI:

npx skills add smokeeaasd/flawless-ui-ux --skill flawless-ui-ux -a claude-code

Start a fresh agent session if needed for discovery, then ask it to use the skill. The repository includes installation instructions for other agents and the CLI's inspection limits.

Repository and documentation · npm package

I am continuing to use this in my college projects and improve it as I find issues. Looking at these two examples, which design decisions would you still change, and what would you test before calling the screen finished?

Writing disclosure: this article was drafted in English with AI assistance from my project context, notes, documentation, and example screenshots.