smokeeaasd/flawless-ui-ux

What is flawless-ui-ux?

flawless-ui-ux is a UI/UX design skill and a local inspection CLI for coding agents. It helps agents create, redesign, refine, and review interfaces around a product's audience, content, and identity.

The skill guides layout, typography, color, and interaction decisions for web, native mobile, and desktop interfaces. The CLI inspects selected source files and browser interfaces, providing observations the agent can use to find issues and verify corrections. You describe the task; your coding agent applies the guidance in your existing project.

Without skill vs. with skill

Created in Codex with GPT 6.1 Sol (low), then refined with flawless-ui-ux using the same model and reasoning setting.

Install

From your project directory, run one command with your preferred package manager:

# npm
npx flawless-ui-ux@latest install

# pnpm
pnpm dlx flawless-ui-ux@latest install

# Bun
bunx flawless-ui-ux@latest install

Requires Node 22.12+. In a terminal, choose project or global scope, select one or more agents, and confirm the destinations before copying. Use Space to select and Enter to continue. Ctrl+C cancels before installation files are written.

Explicit flags run directly:

npx flawless-ui-ux install --codex
npx flawless-ui-ux install --codex --devin
npx flawless-ui-ux install --claude-code --global
npx flawless-ui-ux install --project ./app
npx flawless-ui-ux install --yes

--yes skips the menu and uses the defaults when no other flags are supplied: all supported agents in the current project. JSON output, CI, and non-terminal execution remain noninteractive. Use --format json for machine-readable output.

npx skills add smokeeaasd/flawless-ui-ux --skill flawless-ui-ux

This installs the skill through the Skills CLI. Its runtime requirements and agent selection follow that installer. The inspection CLI is available separately through the npm commands in this guide.

bash /absolute/path/flawless-ui-ux/install.sh --codex --project

The Bash alternative requires --project for local installation; its default is global. Windows users need Git Bash or WSL.

Use the skill

Describe the interface you need and name the skill:

Use the flawless-ui-ux skill to build a financial dashboard for freelancers.

In Codex, invoke $flawless-ui-ux. Hosts with slash commands use /flawless-ui-ux; Pi uses /skill:flawless-ui-ux. You can also request the skill by name through your host's skill mechanism. Start a new session after installation if discovery needs to refresh.

Continue in the same conversation as the interface develops:

Task	Example request
Create	Build a landing page for an app that coordinates deployments and incident handoffs.
Redesign	Redesign this account screen for mobile using the supplied brand palette. Preserve its content and behavior.
Refine	Give the main action more presence while preserving the page's visual character.
Focus	Improve typography and spacing. Preserve wording, colors, and functionality.
Review	Review this dashboard for readability, navigation, accessibility, and repeated generic patterns. Report findings without editing files.

How it works

The skill guides design and implementation. It connects product context to composition, typography, color, density, imagery, and interaction. Focused references support creation, redesign, refinement, and review in your existing stack.

For new interfaces and broad redesigns, the agent considers at least three meaningfully different compositions internally before implementation, then chooses an approach for the product and task. Focused refinements preserve the authorized scope and established decisions.

The design guidance applies to web, native mobile, and desktop interfaces. The CLI's rendered checks cover browser interfaces; native verification uses appropriate platform and project tools.

Refinement develops the intended character. An interface may need more presence, less competing emphasis, or a more consistent finish. The right intervention depends on the content and task. Generic copy, repetitive decoration, and familiar patterns are reviewed in context, alongside usability and accessibility.

The CLI checks the implementation. Collect project context, inspect selected source files or a running interface, and compare the result after corrections. Your agent makes the changes; the CLI provides observations and records what was actually checked.

Product context and workflows

Keep product facts and design decisions in your existing Markdown documents. The agent reuses them across tasks; context files are optional. Use context --source docs/brief.md to select a document outside the conventional locations.

To prepare missing records, run:

npx flawless-ui-ux init

The CLI creates product/design Markdown templates or reuses supported existing documents, preserving their content. Your agent fills the records from the project and your decisions. Read them later with context; initialization does not generate a brief or choose a visual style.

Inspect related screens with repeated --url inputs and --consistency for a contextual style inventory. Add --flow flows/edit-member.json to exercise explicitly defined UI actions, expectations, and named states in a permitted test environment. Verification requires the unchanged flow file to be selected again. See workflow examples and limits.

Inspect and verify

Use the CLI directly, or ask your agent to include these checks in its work. Replace npx with pnpm dlx or bunx throughout.

Start with context and source

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

Check the running interface

Start your app and prepare the browser once:

npx [email protected] install chromium
# or: pnpm dlx [email protected] install chromium
# or: bunx [email protected] install chromium

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

After corrections, repeat the saved scope:

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

The comparison separates persistent, new, and no-longer-observed findings. Missing confirmed targets and changed conditions remain unverified.

Area	Evidence collected
Accessibility	Selected axe contrast and accessible-name rules, including incomplete results for review
Text and layout	Computed font sizes and horizontal overflow at the sampled widths
Assets and runtime	Visible broken images and uncaught JavaScript errors
Copy and icons	Exact repeated phrases and arrow cues for contextual review
Source	Literal pixel font sizes and arrow/icon cues in selected files

• Default viewport samples are 1440 × 900 and 390 × 844. Repeat --viewport WIDTHxHEIGHT to choose others.
• Repeat --source for additional files, or use --selector to inspect a region.
• Use --browser-executable or FLAWLESS_BROWSER_EXECUTABLE to select an installed compatible Chromium. Keep browser conditions consistent between runs.
• With --output, a new directory receives run.json and available screenshots; its parent must exist. Existing output directories are preserved. Without it, results go to stdout.

These samples do not establish full WCAG conformance, complete keyboard journeys, business-flow correctness, or visual quality. Explicit flows cover only their selected actions and expectations. Small text and repetition require context. Ordinary inspection does not perform UI actions or submit forms. Explicit flows run selected actions with network-write and popup blocking. Inspection does not edit files, start servers, or download browsers.

CLI exit codes: 0 for completed coverage without confirmed errors, 1 for completed coverage with confirmed errors, and 2 for invalid input or incomplete requested coverage. The installer also returns 0 when confirmation is declined and 130 when a prompt is interrupted.

Installation notes

Existing files, local changes, and links are preserved. Review or remove an old installation before reinstalling. Host rules, plugins, permissions, and trust settings stay under your control.

The twelve supported agents use five project copies of the same skill. Hosts that discover .agents/skills share one copy; others use their native directories.

• Grok Build: project skills become available after folder trust.
• DeepSeek Harness: install from the nearest Git root, or the working directory without Git. Custom provider roots may change discovery.
• Kiro: custom agents can reference skills through skill:// resources.
• Global paths: honor each host's configuration directory and overrides. Devin uses APPDATA on Windows and XDG_CONFIG_HOME elsewhere.

See the installation contract for exact paths and the testing guide for recorded compatibility evidence and pending checks.

Development

bun install --frozen-lockfile
bun test

Bun is the development toolchain; the published CLI runs on Node. See testing for browser fixtures, packaging checks, and Windows/Ubuntu CI.

Documentation

• 2.0 migration — report schema changes and compatibility
• Product-aware workflows — Markdown context, selected flows, and cross-screen evidence
• Workflow guide — creation, redesign, refinement, and review
• CLI contract — installation paths, options, context, and comparison limits
• Product contract — philosophy and scope
• Architecture — skill, project context, and inspection core
• Manual evaluations — reproducible tasks and evidence criteria
• Changelog

License

MIT.

Agent icons are provided by Lobe Icons, using theme-aware images pinned to a specific revision. Product names and marks belong to their respective owners. Badges use Shields.io. Monthly downloads refer to the npm CLI package.