flawless-ui-ux 0.0.0-stage → 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,28 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+## Unreleased
+
+## 0.1.0
+
+Initial public release, consolidating the pre-release development iterations.
+
+### Added
+
+- A portable UI/UX skill for Codex and OpenCode, covering creation, redesign, refinement, and review with product-specific visual decisions.
+- Focused references for direction, structure, craft, interaction, calibration, contextual pattern prevention, review, and original design studies.
+- A Node-compatible local CLI with context, inspect, and verify operations, text/JSON output, explicit coverage, and coverage-aware exit codes.
+- Project-scoped source observations and optional saved decisions with provenance, content hashes, and stale-source indicators.
+- A Playwright/axe adapter for selected accessibility rules, rendered text size, horizontal overflow, visible broken images, runtime errors, and contextual copy/icon inventories.
+- Explicit run manifests and screenshots, with conservative comparison that keeps missing confirmed targets and changed conditions unverified.
+- A Bash skill installer that preserves existing installations, plus Windows/Ubuntu runtime, packaging, browser, and installer tests.
+- Public npm package configuration, the transparent pencil logo, usage documentation, and a manual release procedure.
+
+### Requirements and limits
+
+- Node 22.12+; Bun is the development/test toolchain.
+- Rendered inspection requires a separately prepared compatible Chromium browser and an explicitly supplied application URL.
+- CLI execution does not install the agent skill, start the application, download browsers, edit source files, or submit forms.
+- Contextual observations require judgment. Selected initial-state checks do not establish full WCAG conformance, business-flow correctness, or visual quality.
+- Matched host/model design-quality and latency evaluations remain pending.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 smokeeaasd
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,148 @@
-# Temporary Holding Version
+<p align="center">
+  <img src="https://cdn.jsdelivr.net/npm/flawless-ui-ux@0.1.0/docs/assets/logo.svg" alt="flawless-ui-ux" width="334" height="80">
+</p>
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+<p align="center">Design interfaces around the product. Refine them against the result.</p>
+
+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**.
+
+## Setup
+
+From your project directory, choose your package manager. The CLI requires **Node 22.12+**.
+
+```bash
+npx flawless-ui-ux@latest --help
+pnpm dlx flawless-ui-ux@latest --help
+bunx flawless-ui-ux@latest --help
+```
+
+The examples below use `npx`. Replace it with `pnpm dlx` or `bunx` to use the same operations. These commands run the CLI; connect the skill separately to use design guidance in your agent.
+
+### Connect your coding agent
+
+From a checkout of this repository, install the skill for your agent:
+
+```bash
+bash ./install.sh --codex
+bash ./install.sh --opencode
+```
+
+Use `--all-agents` for both. To install only in a project, run the following from that project's directory:
+
+```bash
+bash /path/to/flawless-ui-ux/install.sh --all-agents --project
+```
+
+Existing installations are preserved. On Windows, use Git Bash or WSL. Start a new agent session if needed for discovery.
+
+## Use the skill
+
+In Codex, select `$flawless-ui-ux` and describe what you want to build:
+
+```text
+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.
+
+## Inspect and verify
+
+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.
+
+### 1. Inspect the affected scope
+
+Start with project context or selected source files:
+
+```bash
+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:
+
+```bash
+# npm
+npx playwright@1.64.1 install chromium
+
+# pnpm
+pnpm dlx playwright@1.64.1 install chromium
+
+# Bun
+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:
+
+```bash
+npx flawless-ui-ux inspect --project . --source src/App.tsx --url http://localhost:5173 --output ../bloom-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**.
+
+### 2. Correct and compare
+
+Review the findings, make the relevant corrections, then repeat the saved scope:
+
+```bash
+npx flawless-ui-ux verify ../bloom-before/run.json --output ../bloom-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.
+
+## What gets checked
+
+| 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. |
+
+## Development
+
+Use the pinned Bun toolchain from a local checkout:
+
+```bash
+bun install --frozen-lockfile
+bun test
+```
+
+See the [testing guide](docs/testing.md) 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](evals/README.md).
+
+## Documentation
+
+- [CLI options, saved context, and comparison limits](docs/cli-contract.md)
+- [Design philosophy and product contract](docs/product-contract.md)
+- [Workflow guide](docs/workflow-procedures.md)
+- [Architecture](docs/skill-architecture.md)
+- [Delivery plan](docs/implementation-plan.md)
+- [Changelog](CHANGELOG.md)
+
+## License
+
+[MIT](LICENSE).

package/bin/flawless-ui-ux.js

@@ -0,0 +1,40 @@
+#!/usr/bin/env node
+import { parse } from '../src/options.js';
+import { context } from '../src/context.js';
+import { inspect } from '../src/inspect.js';
+import { verify } from '../src/verify.js';
+import { VERSION } from '../src/shared.js';
+
+const args = process.argv.slice(2);
+try {
+  const { operation, options } = parse([...args]);
+  if (operation === 'version') console.log(VERSION);
+  else if (operation === 'help') console.log(`flawless-ui-ux ${VERSION}
+  context [--project DIR] [--format text|json]
+  inspect [--project DIR] --source FILE [--source FILE ...] [--url URL]
+          [--selector CSS] [--viewport WIDTHxHEIGHT ...] [--output NEW_DIR]
+          [--timeout MS] [--browser-executable FILE] [--format text|json]
+  verify RUN_JSON [--output NEW_DIR] [--browser-executable FILE] [--format text|json]
+
+inspect requires a source or URL. Defaults: 1440x900 and 390x844, 15000 ms.
+No server startup, browser download, source edits, or form submission.
+FLAWLESS_BROWSER_EXECUTABLE explicitly selects an installed Chromium executable.
+Exit codes: 0 completed; 1 confirmed errors; 2 invalid/incomplete.`);
+  else {
+    const report = await ({ context, inspect, verify }[operation])(options);
+    if (options.format === 'json') console.log(JSON.stringify(report, null, 2));
+    else {
+      console.log(`${operation}: ${report.project}\nCoverage: ${JSON.stringify(report.coverage)} (${report.completion})`);
+      for (const f of report.findings) console.log(`[${f.status}/${f.severity}] ${f.checkId} ${f.target}: ${f.observation}\n  ${f.recommendation}`);
+      if (report.operation === 'context') console.log(JSON.stringify({ sources: report.sources, missing: report.missing, saved: report.saved, decisions: report.decisions }, null, 2));
+      if (report.comparison) console.log(`Comparison: ${JSON.stringify(report.comparison)}`);
+      for (const limit of [...report.limits, ...(report.claims || [])]) console.log(`Limit: ${limit}`);
+      if (report.artifacts?.manifest) console.log(`Manifest: ${report.artifacts.manifest}`);
+    }
+    process.exitCode = report.exitCode;
+  }
+} catch (error) {
+  console.error(error.message);
+  if (args.includes('json')) console.log(JSON.stringify({ schemaVersion: 1, operation: args[0] || null, completion: 'partial', coverage: {}, findings: [], limits: [error.message], exitCode: 2 }));
+  process.exitCode = 2;
+}

package/docs/assets/logo.svg

@@ -0,0 +1,18 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="334" height="80" viewBox="0 0 334 80" role="img" aria-labelledby="title"><title id="title">flawless-ui-ux</title>
+  <g transform="translate(20 20) scale(1.666667)"><path d="M4 20l1-5L16 4a2.83 2.83 0 0 1 4 4L9 19l-5 1Z" fill="#0ce491" stroke="#0ce491" stroke-width="1.25" stroke-linecap="round" stroke-linejoin="round"/></g>
+  <g fill="#ffffff" transform="translate(72 52) scale(0.018 -0.018)">
+    <path transform="translate(0 0)" d="M679 933L679 1080L969 1080L969 933ZM243 0L243 1139Q243 1180 246.5 1224Q250 1268 264.5 1309.5Q279 1351 311 1386Q348 1426 392 1444Q436 1462 481.5 1466Q527 1470 568 1470L705 1470L705 1322L578 1322Q499 1322 460 1283Q421 1244 421 1167L421 0ZM60 933L60 1080L705 1080L705 933ZM954 0L954 1470L1132 1470L1132 0Z"/>
+    <path transform="translate(1292 0)" d="M447 -30Q326 -30 244.5 14.5Q163 59 121.5 132Q80 205 80 292Q80 377 112 439Q144 501 203.5 543Q263 585 345 609Q422 630 517 645.5Q612 661 710 674Q808 687 894 699L830 662Q832 805 772 874.5Q712 944 564 944Q466 944 392.5 899Q319 854 289 755L120 806Q159 948 271 1029Q383 1110 566 1110Q713 1110 818.5 1057.5Q924 1005 970 899Q993 849 999 790.5Q1005 732 1005 668L1005 0L847 0L847 259L884 235Q823 103 713 36.5Q603 -30 447 -30ZM474 119Q570 119 640.5 153.5Q711 188 754 244.5Q797 301 810 368Q824 418 826 479Q828 540 828 574L890 547Q803 534 718.5 523Q634 512 559.5 500Q485 488 425 471Q381 457 342.5 434.5Q304 412 280.5 377.5Q257 343 257 293Q257 249 279.5 209Q302 169 349.5 144Q397 119 474 119Z"/>
+    <path transform="translate(2377 0)" d="M370 0L40 1081L217 1080L458 290L701 1080L858 1080L1100 290L1342 1080L1518 1080L1188 0L1040 0L779 821L518 0Z"/>
+    <path transform="translate(3935 0)" d="M160 0L160 1470L338 1470L338 0Z"/>
+    <path transform="translate(4433 0)" d="M608 -30Q449 -30 330.5 40.5Q212 111 146 237.5Q80 364 80 533Q80 710 145 839.5Q210 969 326.5 1039.5Q443 1110 600 1110Q763 1110 877.5 1035Q992 960 1049.5 821Q1107 682 1099 490L919 490L919 554Q916 753 838 851.5Q760 950 606 950Q441 950 355 844Q269 738 269 540Q269 349 355 244Q441 139 600 139Q707 139 786 188Q865 237 910 329L1081 270Q1018 127 891.5 48.5Q765 -30 608 -30ZM209 490L209 633L1007 633L1007 490Z"/>
+    <path transform="translate(5614 0)" d="M548 -29Q355 -29 231.5 55.5Q108 140 80 292L262 321Q284 233 363 181.5Q442 130 559 130Q669 130 732.5 176Q796 222 796 301Q796 346 775 374.5Q754 403 688.5 428Q623 453 491 489Q348 527 266 567.5Q184 608 149 662Q114 716 114 794Q114 889 166 960Q218 1031 311.5 1070.5Q405 1110 529 1110Q652 1110 749 1071Q846 1032 905.5 960.5Q965 889 976 794L794 761Q781 847 710 897.5Q639 948 529 951Q424 954 358.5 913Q293 872 293 803Q293 763 317.5 735.5Q342 708 408.5 683Q475 658 602 626Q745 590 827.5 547.5Q910 505 945 447.5Q980 390 980 306Q980 150 865 60.5Q750 -29 548 -29Z"/>
+    <path transform="translate(6675 0)" d="M548 -29Q355 -29 231.5 55.5Q108 140 80 292L262 321Q284 233 363 181.5Q442 130 559 130Q669 130 732.5 176Q796 222 796 301Q796 346 775 374.5Q754 403 688.5 428Q623 453 491 489Q348 527 266 567.5Q184 608 149 662Q114 716 114 794Q114 889 166 960Q218 1031 311.5 1070.5Q405 1110 529 1110Q652 1110 749 1071Q846 1032 905.5 960.5Q965 889 976 794L794 761Q781 847 710 897.5Q639 948 529 951Q424 954 358.5 913Q293 872 293 803Q293 763 317.5 735.5Q342 708 408.5 683Q475 658 602 626Q745 590 827.5 547.5Q910 505 945 447.5Q980 390 980 306Q980 150 865 60.5Q750 -29 548 -29Z"/>
+    <path transform="translate(7736 0)" d="M120 557L120 704L720 704L720 557Z"/>
+    <path transform="translate(8576 0)" d="M550 -28Q445 -28 371 5Q297 38 248 93Q199 148 171 215Q143 282 131.5 352Q120 422 120 483L120 1080L300 1080L300 539Q300 463 314 392Q328 321 361.5 264Q395 207 451.5 174Q508 141 593 141Q660 141 714.5 164Q769 187 808 232.5Q847 278 868.5 348Q890 418 890 511L1007 475Q1007 319 950.5 206Q894 93 791.5 32.5Q689 -28 550 -28ZM910 0L910 289L890 289L890 1080L1069 1080L1069 0Z"/>
+    <path transform="translate(9785 0)" d="M160 1271L160 1455L338 1455L338 1271ZM160 0L160 1080L338 1080L338 0Z"/>
+    <path transform="translate(10283 0)" d="M120 557L120 704L720 704L720 557Z"/>
+    <path transform="translate(11123 0)" d="M550 -28Q445 -28 371 5Q297 38 248 93Q199 148 171 215Q143 282 131.5 352Q120 422 120 483L120 1080L300 1080L300 539Q300 463 314 392Q328 321 361.5 264Q395 207 451.5 174Q508 141 593 141Q660 141 714.5 164Q769 187 808 232.5Q847 278 868.5 348Q890 418 890 511L1007 475Q1007 319 950.5 206Q894 93 791.5 32.5Q689 -28 550 -28ZM910 0L910 289L890 289L890 1080L1069 1080L1069 0Z"/>
+    <path transform="translate(12332 0)" d="M20 0L433 546L29 1080L241 1080L537 684L830 1080L1042 1080L638 546L1052 0L839 0L537 408L233 0Z"/>
+  </g>
+</svg>

package/install.sh

@@ -0,0 +1,62 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+usage() {
+  cat <<'EOF'
+Usage: ./install.sh [--codex | --opencode | --all-agents] [--project]
+
+Install the bundled skill for Codex, OpenCode, or both (the default).
+Use --project to install into the current project's agent directories.
+Existing installations are never overwritten.
+Requires Bash. On Windows, run with Git Bash or WSL.
+EOF
+}
+
+agent=all
+project=false
+for argument in "$@"; do
+  case "$argument" in
+    --codex) agent=codex ;;
+    --opencode) agent=opencode ;;
+    --all-agents) agent=all ;;
+    --project) project=true ;;
+    -h|--help) usage; exit 0 ;;
+    *) printf 'Unknown option: %s\n' "$argument" >&2; usage >&2; exit 2 ;;
+  esac
+done
+
+repository_dir="$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" && pwd)"
+source_dir="$repository_dir/skills/flawless-ui-ux"
+if [[ ! -f "$source_dir/SKILL.md" ]]; then
+  printf 'This checkout does not contain an installable skill yet.\n' >&2
+  exit 1
+fi
+
+destinations=()
+if [[ "$agent" == codex || "$agent" == all ]]; then
+  if $project; then
+    destinations+=("$PWD/.agents/skills/flawless-ui-ux")
+  else
+    destinations+=("${CODEX_HOME:-$HOME/.codex}/skills/flawless-ui-ux")
+  fi
+fi
+if [[ "$agent" == opencode || "$agent" == all ]]; then
+  if $project; then
+    destinations+=("$PWD/.opencode/skills/flawless-ui-ux")
+  else
+    destinations+=("${XDG_CONFIG_HOME:-$HOME/.config}/opencode/skills/flawless-ui-ux")
+  fi
+fi
+
+for destination in "${destinations[@]}"; do
+  if [[ -e "$destination" || -L "$destination" ]]; then
+    printf 'Installation already exists: %s\n' "$destination" >&2
+    exit 1
+  fi
+done
+for destination in "${destinations[@]}"; do
+  mkdir -p -- "$(dirname -- "$destination")"
+  mkdir -- "$destination"
+  cp -R -- "$source_dir/." "$destination/"
+  printf 'Installed flawless-ui-ux: %s\n' "$destination"
+done

package/package.json

@@ -1,6 +1,43 @@
 {
   "name": "flawless-ui-ux",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "A UI/UX skill and local inspection CLI for coding agents to build and refine product-specific interfaces.",
+  "type": "module",
+  "license": "MIT",
+  "packageManager": "bun@1.4.4",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/smokeeaasd/flawless-ui-ux.git"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "skills/flawless-ui-ux/",
+    "docs/assets/logo.svg",
+    "install.sh",
+    "LICENSE",
+    "README.md",
+    "CHANGELOG.md"
+  ],
+  "scripts": {
+    "test": "bun test",
+    "check:conventions": "bun scripts/check-conventions.js"
+  },
+  "devDependencies": {
+    "yaml": "2.9.1"
+  },
+  "dependencies": {
+    "@axe-core/playwright": "4.14.0",
+    "playwright": "1.64.1"
+  },
+  "bin": {
+    "flawless-ui-ux": "bin/flawless-ui-ux.js"
+  },
+  "engines": {
+    "node": ">=22.12.0"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  }
+}

package/skills/flawless-ui-ux/SKILL.md

@@ -0,0 +1,47 @@
+---
+name: flawless-ui-ux
+description: Create, redesign, refine, or review web interfaces with product-specific visual design and usable interactions.
+---
+
+# Flawless UI/UX
+
+Translate product intent into specific visual decisions. Quality combines functioning behavior, accessibility, identity, and finish. Build richness through hierarchy, proportions, rhythm, imagery, and detail suited to the product.
+
+## Work directly
+
+Inspect the requested target, surrounding components, content, and available assets. Establish what the user needs to understand or do, what may change, and which facts and behaviors must remain. Ask only when an unresolved fact materially changes the scope, identity, or outcome.
+
+- **Create:** build the requested surface and interactions; inherit the surrounding system when one exists.
+- **Redesign:** replace authorized visual decisions while preserving required content and behavior.
+- **Refine:** develop the existing intention; preserve everything outside the requested intervention. Keep wording fixed in visual-only work and presentation fixed in copy-only work.
+- **Review:** report prioritized findings without changing project files. Planning delivers a proposal rather than an implementation.
+
+Make a coherent composition from the actual material: choose what leads, how supporting information relates, and how the main action works. Select typography, color, density, imagery, and detail together. Carry that treatment through the whole target. A short brief still permits confident design choices; routine work can proceed without a written brief, concept presentation, or separate planning artifact.
+
+Use the project's stack and implement the requested behavior. Add interface elements because the task needs them, rather than creating extra product features to fill a conventional layout.
+
+## Use references for a decision
+
+For a new visual direction, start with [Direction](references/direction.md). For existing work, the entry point and project context may suffice. Otherwise read the relevant section below when it answers a concrete question; this table is not a reading sequence. Reuse material already read.
+
+| Question | Reference |
+|---|---|
+| How should navigation, records, forms, or content work together? | [Product structure](references/structure.md) |
+| How should type, spacing, color, imagery, or responsive layout be executed? | [Craft](references/craft.md) |
+| How should controls, feedback, keyboard access, and states behave? | [Interaction](references/interaction.md) |
+| What should change in a broad visual refinement? | [Calibration](references/calibration.md) |
+| Which recurring patterns need inspection? | [Contextual prevention](references/anti-slop.md) |
+| Would a worked composition clarify the design? | The relevant [design study](references/design-studies.md) |
+| Is a critique or deeper diagnosis needed? | [Review](references/review.md) |
+
+## Check the result
+
+Observe the primary task, affected states, and wide/narrow layouts with available tools. Check hierarchy, readable content, navigation, and overflow as well as calculations and controls.
+
+Before delivering a creation or redesign, read and perform the [final pattern pass](references/anti-slop.md#final-pass) on the completed target. For refinement, apply its affected checks within the authorized scope. Inspect actual copy and icons in source even when rendering is unavailable; correct observed repetition rather than merely claiming a review.
+
+Measure contrast against actual backgrounds. Run relevant project checks and meaningful tests; repeat affected checks after corrections. If rendering is unavailable, continue useful source work and state the limit. Static checks cannot establish visual quality.
+
+When the local CLI is available, use [executable inspection](references/inspection.md) for scoped evidence and corresponding verification. Read its coverage; contextual signals still require judgment.
+
+Finish when the requested result is complete and material issues within scope are resolved, or report the specific blocker. Preserve explicit choices and product facts; identify sample data and never invent credibility claims. Report the result, checks actually performed, and remaining limits concisely.

package/skills/flawless-ui-ux/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Flawless UI/UX"
+  short_description: "Contextual art direction and practical UI/UX refinement"
+  default_prompt: "Use $flawless-ui-ux to design or improve this interface for its users and purpose."

package/skills/flawless-ui-ux/references/anti-slop.md

@@ -0,0 +1,49 @@
+# Contextual prevention
+
+Use the final pass before delivering creation or redesign, and the relevant checks for focused work. Diagnose the pattern's effect; appearance alone does not establish authorship or poor quality.
+
+## Final pass
+
+Inspect the implemented target as a whole, including lower sections and working states. Use source for copy and icon use; use rendered inspection for visual relationships when available.
+
+- **Arrows and icons:** inspect buttons, links, captions, cards, and illustrations together. Remove arrows that merely decorate an already clear action. Retain useful direction, disclosure, chart meaning, and recognizable interaction cues; preserve or replace a sole action affordance before removing it.
+- **Copy:** read headings, descriptions, notes, and footer in sequence. Group repeated promises by meaning, including rephrased reassurance and rhetorical contrasts. Replace redundant wording with the distinct confirmed information needed there, or remove it. Preserve deliberate brand voice and protected text.
+- **Composition and treatment:** check repeated region shapes, competing emphasis, type roles, default styling, decoration, and unsupported proof. Use the relevant sections below when a signal needs diagnosis; retain choices that serve the product.
+
+Correct authorized issues, then recheck the affected content, controls, and layout. Preserve identity, useful density, and visual richness. During review-only work or outside the edit scope, report material findings instead. Keep unobserved visual effects explicit; a source pass cannot establish them.
+
+## Composition and substance
+
+Check whether hierarchy and region structure come from the content or an interchangeable template. Similar cards can help comparison; they are less useful when unrelated information receives identical emphasis. Develop different proportions or structures where the material needs them.
+
+A rich opening needs useful continuation. Lower regions should explain, compare, demonstrate, or support action rather than repeat the opening's promise. Keep useful content and intentional visual presence during cleanup.
+
+## Visual language and system fit
+
+Look for decorative elements competing with the work, incompatible treatments, or a palette swap over an unsuitable composition. A familiar convention can be the best solution when executed deliberately.
+
+Correct the specific relationship through scale, alignment, type, imagery, grouping, or color distribution. Cards, gradients, shadows, large type, dark surfaces, minimalism, and vivid colors are contextual choices rather than banned styles.
+
+## Typography and emphasis
+
+Inspect actual type roles, readability, loaded fonts, and the balance between display and working content. Scaffold defaults deserve assessment; unfamiliar fonts do not automatically improve identity. Keep variation meaningful instead of making every heading, caption, and number equally emphatic.
+
+Small, faint operational content beside oversized summaries can undermine the task. Increase its usable presence or rebalance the composition without flattening all roles.
+
+## Copy and proof
+
+Read the actual copy as a sequence. Repeated reassurance, rhetorical contrasts, metaphors, and payoffs can make operational content feel promotional and leave sections without distinct information. Use the concrete explanation or label needed there. Preserve expressive language when its role is deliberate and different.
+
+Check facts, terms, sample labels, and destinations. Remove invented customer proof, unsupported metrics, awards, and testimonials rather than replacing them with different unverified claims. Copy cleanup preserves the visual design unless wider changes are authorized.
+
+## Imagery and motion
+
+Check whether imagery shows relevant material or merely decorates a product-shaped slot. A conceptual illustration can be appropriate; a misleading representation of an actual customer, team, or product is a different issue. Preserve honest imagery and improve its relationship to the content.
+
+Use motion to clarify change or support the experience. Repeated entrances, delayed content, or scroll effects that impede reading need correction. Keep a useful reduced-motion experience.
+
+## Affordance and task flow
+
+Investigate overlays, excessive icon-only actions, redundant arrows, and navigation that promises a destination but only moves within unrelated content. Choose presentation for the task's duration and context; a dialog is useful for a bounded action and less useful for sustained work.
+
+Keep functioning behavior when changing presentation. An unnecessary feature can be removed within scope; an explicitly requested interaction must remain. Check relevant widths and states for clipped labels, unreachable controls, and broken transitions. Judge the observed effect rather than seeking a zero-pattern count.

package/skills/flawless-ui-ux/references/calibration.md

@@ -0,0 +1,29 @@
+# Visual calibration
+
+Use when a broad refinement request leaves the intervention unclear. A clear local correction can proceed directly.
+
+## Identify the difference
+
+Recover the requested outcome, current identity, and protected content or behavior. Translate “more professional”, “enterprise”, or “more impactful” into a specific issue in this context. Ask when different interpretations would materially change identity or scope.
+
+Locate the relationship that needs work:
+
+| Need | Possible intervention |
+|---|---|
+| Important content has too little presence | Strengthen its scale, position, contrast, imagery, or relationship to the action |
+| Several elements compete | Redistribute emphasis, grouping, and rhythm |
+| The interface feels inconsistent or unfinished | Resolve type roles, alignment, treatments, states, and continuity |
+
+Change the resources involved in that issue. Reducing visual competition does not require removing expression, and increasing presence does not require adding effects everywhere.
+
+## Choose the intervention
+
+A vivid event page's signup action can gain presence through its position and relationship to the ticket details, while the large image and color remain. A visual collection may need a different proportion between work and metadata to make its artifacts lead. A working queue may need quieter summary emphasis so records lead, while useful totals and density stay.
+
+These address similar attention problems through different choices. Compare the affected relationship and preserved content, rather than treating a larger button, new font, or neutral palette as a preset improvement.
+
+Keep wording protected in visual-only work. Report material copy issues separately; copy-only work preserves presentation.
+
+## Compare
+
+Use matching content, states, and widths when before/after evidence is available. Check the intended improvement and recognizable character retained. Verify affected behavior and access independently. Correct observed gaps and recheck them; report rendering-dependent expectations as unverified when tools are unavailable.

package/skills/flawless-ui-ux/references/craft.md

@@ -0,0 +1,39 @@
+# Craft
+
+Read the section that affects the current design decision. Preserve established tokens and components during focused refinement.
+
+## Hierarchy and layout
+
+Give the most useful information enough scale, position, and surrounding space to lead. Distinguish supporting roles through more than color: size, weight, alignment, grouping, and placement work together. Making every label prominent weakens the hierarchy.
+
+Use a shared alignment structure. Keep space within a group smaller than space between unrelated groups. Relate outer margins, content widths, and component spacing. A container should communicate ownership, state, or separation; repeated nested borders can obscure those relationships.
+
+Judge empty space by its effect. It can frame an image or create rhythm; it can also indicate an unbalanced grid or missing substance. Change proportions before automatically filling or removing it. Preserve useful density in working interfaces and suitable presence in expressive ones.
+
+## Typography
+
+Choose a family for actual content and character, with appropriate language coverage, weights, licensing, and availability. Verify the intended font loads; distinguish its role from the fallback. Familiar fonts are valid when they fit. Replacing a family without improving its relationship to the content is not personalization.
+
+Test real headings, long labels, paragraphs, and numbers. Adjust measure, size, weight, and leading together. Use tabular figures where they aid comparison. Keep important labels readable at their rendered size; avoid shrinking the interface to fit a miniature preview.
+
+Resolve awkward wrapping through permitted changes to measure, typography, or wording. Forced line breaks need checks at affected widths. Preserve protected copy and outer layout during typography-only work.
+
+## Color
+
+Assign surface, text, emphasis, and state roles before choosing isolated values. Keep supporting text readable while maintaining hierarchy through type and grouping. A rich palette can remain coherent when its distribution has purpose.
+
+Measure text against its actual background, including tinted surfaces and relevant states: generally 4.5:1 for normal text and 3:1 for large text, subject to the criterion's definitions and exceptions. Use [WCAG text contrast](https://www.w3.org/WAI/WCAG22/Understanding/contrast-minimum.html) for applicability. A scan of CSS colors against white is only a candidate finder; it does not resolve computed backgrounds, cascade, opacity, or text roles.
+
+Distinguish information by wording, shape, or another cue as well as color. Improve contrast with compatible foreground/background choices, size, and composition rather than making every text role equally emphatic.
+
+## Imagery and detail
+
+Use assets that explain the product, establish its character, or show real material. Inspect suitability, crop, resolution, and usage rights. Preserve required credits and distinguish illustrative imagery from actual customer or product evidence.
+
+Give important imagery sufficient scale. Match crop and placement to nearby text instead of treating the image as a leftover slot. Let borders, shadows, textures, illustrations, or motion contribute where useful; develop a consistent treatment without applying every effect everywhere.
+
+## Responsive composition
+
+Reconsider arrangement as available space changes. Stack, reorder, simplify presentation, or disclose secondary detail while retaining essential content and actions. Keep genuinely two-dimensional tables in a local scroll region; do not shrink the entire screen to avoid overflow.
+
+Inspect long content, intermediate widths, navigation height, and bottom sections. Check zoom and reflow where relevant. Fixed, sticky, and overflow rules must work together; a hidden or clipped control is not a finished responsive solution.

package/skills/flawless-ui-ux/references/design-studies.md

@@ -0,0 +1,52 @@
+# Design studies
+
+Consult a relevant study only when a worked composition helps resolve a choice. These original fictional plates illustrate relationships, not templates, prescribed fonts, or a ceiling on visual ambition. Inspect the relevant image when possible; the anatomy below remains usable without it.
+
+## Service offer
+
+[View the service study](../assets/design-studies/service.png).
+
+A rider needs repair prices and arrival instructions. Both proposals use the same facts:
+
+- The price-led structure puts comparable service/price rows before the visit information.
+- The process-led structure explains arrival, assessment, and collection before the prices.
+
+Aligned amounts and a clear next action make either readable. Carry the type roles into hours, location, details, and any requested form. On narrow screens, keep each service paired with its price.
+
+**Transfer:** choose which visitor question leads. A bold typographic offer and a restrained ledger can both preserve comparison. Verify accurate prices and a real destination for the visit action; the fictional name and palette are not the design principle.
+
+## Operational workspace
+
+[View the workspace study](../assets/design-studies/workspace.png).
+
+A receptionist finds a bicycle, understands repair status, and marks work ready for collection. Compact navigation, search, status filters, aligned records, and a selected-record panel keep identity, state, and the next action close.
+
+Reuse type roles and spacing in details, errors, and empty results. Keep selection and keyboard focus distinct. At narrower widths, preserve key record information and a detail/return path. A status change can alter membership in a filtered queue; counts and feedback must follow the actual rules.
+
+**Transfer:** useful density through grouping and alignment. Verify the record/action relationship; tiny type and repair-themed styling are not requirements for an operational interface.
+
+## Editorial guide
+
+[View the reading study](../assets/design-studies/reading.png).
+
+A reader learns furniture care, jumps to a topic, and returns to the explanation. Distinct title/body/note roles, a bounded reading column, and supporting contents navigation establish the path. Figures and captions stay related.
+
+At smaller widths, move the index without covering the article; retain anchors, readable measure, and enlarged-text access.
+
+**Transfer:** the relationship between reading and wayfinding. Strong photography or a text-led composition can express the subject. Verify heading order, reading continuity, and return paths rather than copying serif type or paper colors.
+
+## Visual collection
+
+[View the collection study](../assets/design-studies/collection.png).
+
+A visitor explores fictional graphic works. A leading artifact, varied aligned image sizes, and adjacent title/category/year metadata let the work carry character without losing orientation.
+
+Details preserve item identity and provide next/previous and return actions. On narrow screens, preserve order and readable metadata. Keep essential information available beyond hover and useful context on return.
+
+**Transfer:** artifact scale, sequence, and navigation. Verify finding, opening, understanding, and leaving an item; the plate's palette and geometric artworks are examples, not assets to insert into unrelated products.
+
+## Applying a study
+
+Transfer the useful relationship to actual content and available resources. Supplied brand material or a mockup may be a better basis. Keep any rationale in working notes, not visitor-facing slogans.
+
+Carry the chosen relationships into lower regions and relevant states. Compare the implemented result when tools permit; the plate itself proves neither responsive behavior nor working interactions.