Design interfaces around the product. Refine them against the result.
flawless-ui-ux helps coding agents create, redesign, and refine web interfaces with a visual identity suited to the product. A skill guides design and implementation; a local CLI collects evidence and checks what changed after corrections. Works with Codex and OpenCode.
From your project directory, choose your package manager to install the skill for Codex and OpenCode in that project. The CLI requires Node 22.12+; no checkout or Bash is needed.
npx flawless-ui-ux@latest install
pnpm dlx flawless-ui-ux@latest install
bunx flawless-ui-ux@latest install
Run one of these commands. The examples below use npx; replace it with pnpm dlx or bunx to use the same operations.
For a specific agent, or an installation across projects:
npx flawless-ui-ux install --codex
npx flawless-ui-ux install --opencode --global
The default is both agents in the current project. Use --codex, --opencode, or --all-agents to select targets. --global explicitly installs in your user profile; --project <directory> selects another project. Start a new agent session if needed for discovery.
Existing installations are never overwritten, including links and local changes. All selected destinations are checked before copying. Review or remove an existing installation yourself before reinstalling. Global paths honor CODEX_HOME and XDG_CONFIG_HOME; project paths are .agents/skills/flawless-ui-ux for Codex and .opencode/skills/flawless-ui-ux for OpenCode.
Alternative: install from a checkout with Bash #
bash ./install.sh --codex --project
bash ./install.sh --opencode --project
Run these from the target project's directory, using the script's absolute path when the checkout is elsewhere. Use --all-agents for both. The legacy Bash script requires --project for local installation and otherwise installs globally. On Windows, this alternative requires Git Bash or WSL.
In Codex, select $flawless-ui-ux and describe what you want to build:
Use $flawless-ui-ux to build a financial dashboard for freelancers.
In OpenCode, request the installed skill by name. Continue in the same conversation to develop the result:
| Goal | Example request |
|---|---|
| Create | Build a landing page for a DevOps app that coordinates deployments and incident handoffs. |
| Redesign | Redesign the mobile account screen using the supplied brand palette. Preserve its content and behavior. |
| Refine | Strengthen the main action and improve hierarchy while preserving the page's visual character. |
| Focus | Improve typography and spacing. Preserve wording, colors, and functionality. |
| Review | Review this dashboard for readability, navigation, repeated slogans, and redundant icon cues. Report findings without editing files. |
The skill connects product intent to composition, typography, color, density, imagery, and interaction. It works with your project's stack and existing constraints, using focused references when they answer a design question. Refinement can add presence, redistribute emphasis, or improve finish; it does not prescribe a universal aesthetic.
Use the CLI directly or have your agent run it as part of the task. Design and corrections stay with you and your agent; the CLI supplies observations and comparisons.
Start with project context or selected source files:
npx flawless-ui-ux context --project . --format json
npx flawless-ui-ux inspect --project . --source src/App.tsx --format json
For rendered checks, start your application and prepare a browser using one of these commands:
npx playwright@1.64.1 install chromium
pnpm dlx playwright@1.64.1 install chromium
bunx playwright@1.64.1 install chromium
The version matches the CLI's browser adapter. Alternatively, select an installed compatible Chromium executable with --browser-executable or FLAWLESS_BROWSER_EXECUTABLE.
Inspect the actual development-server URL and save a baseline:
npx flawless-ui-ux inspect --project . --source src/App.tsx --url http://localhost:5173 --output ../app-before --format json
Repeat --source for additional files, use --selector for a specific region, or repeat --viewport WIDTHxHEIGHT to select widths. Default samples are 1440×900 and 390×844.
Review the findings, make the relevant corrections, then repeat the saved scope:
npx flawless-ui-ux verify ../app-before/run.json --output ../app-after --format json
Verification separates persistent, new, and no-longer-observed findings. A missing confirmed target or changed conditions remain unverified instead of being counted as a repair. Keep the same browser selection between runs.
Without --output, results go to stdout. With it, a new directory receives run.json and any screenshots; the parent must already exist. Existing output directories are never overwritten. For review-only work, keep artifacts outside the project.
| Area | Evidence |
|---|---|
| Accessibility | Selected axe contrast and accessible-name rules, with upstream evidence and incomplete results retained. |
| Readability and layout | Computed text sizes and horizontal overflow at the requested widths. |
| Assets and runtime | Visible broken images and uncaught JavaScript errors in the sampled state. |
| Copy and icons | Exact repeated phrases and arrow cues for contextual review. |
| Source | Literal pixel font sizes and arrow/icon cues in selected files. |
Small text, overflow, and repetition require judgment. A small font size alone is not a WCAG failure, and an arrow count does not determine whether an interface is good. The skill's contextual review considers what each element contributes to the product.
Inspection does not edit sources, start servers, download browsers, or submit forms. These initial-state samples do not establish full WCAG conformance, keyboard journeys, business-flow correctness, or visual quality.
| Exit code | Meaning |
|---|---|
0 |
Requested coverage completed without confirmed errors. |
1 |
Requested coverage completed with confirmed errors. |
2 |
Invalid input or incomplete requested coverage. |
Use the pinned Bun toolchain from a local checkout:
bun install --frozen-lockfile
bun test
See the testing guide for browser fixtures, distribution checks, and Windows/Ubuntu CI. Automated tests validate runtime and packaging behavior; matched host/model evaluations of design quality and elapsed time remain pending in the manual evaluation kit.
MIT.