mirror of
https://github.com/pbakaus/impeccable.git
synced 2026-09-17 00:26:41 +03:00
Paul BakausandClaude Fable 5.1
f2c9aeab5b
`bun run build:extension` was broken on this branch: it still imported the deleted JS engine (cli/engine/registry/antipatterns.mjs, scripts/lib/browser-detector-bundle.js). The shipped shell now matches the new design. The content script only snapshots the DOM; an extension-owned offscreen document runs the WebAssembly rule core over that snapshot, so the scanned page's CSP no longer matters. That replaces the old approach of injecting a JS rules bundle into the page. New files: extension/offscreen/offscreen.html, plus the "offscreen" permission and a 'wasm-unsafe-eval' extension_pages CSP in the manifest. The manifest version stays at 1.3.3. The shell's own manifest carried 2.0.0; feature branches never bump versions, so the bump is a release step. The five generated detector pieces (core.js, core_bg.wasm, snapshot.js, overlay.js, antipatterns.json) are vendored at build time into the gitignored extension/detector/ by the new scripts/lib/detector-bundle.mjs, which resolves them the same three ways crates/core/build.rs resolves the native archive: IMPECCABLE_DETECTOR_LIB/extension-detector/, the ~/.impeccable/detector/<DETECTOR_VERSION>/ cache, then a checksum-verified download of detector-browser-bundle.zip from the detector release. antipatterns.json is no longer regenerated here. The zip packaging is unchanged. The Firefox variant still builds so `web-ext lint` keeps covering the shared shell, but it cannot scan: Gecko has no chrome.offscreen API. The build prints a one-line warning saying so. Also here: a referenced-path check that fails the build when the manifest or the service worker points at a file that is not in extension/, a resolver unit test wired into the core suite, and the detector rule count in the READMEs synced to the 61 the vendored registry carries. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Vau2X53xGTjjTCXWMVBoNY
91 lines
3.4 KiB
Markdown
91 lines
3.4 KiB
Markdown
# Impeccable CLI
|
|
|
|
Detect UI anti-patterns and design quality issues from the command line, and install the Impeccable design skill into your AI coding harness. The detector scans HTML, CSS, JSX, TSX, Vue, and Svelte files for 61 deterministic rules, including AI-generated UI tells, accessibility violations, and general design quality problems.
|
|
|
|
The npm package is a small launcher. It runs the `impeccable` engine binary for your platform, installed alongside it as an optional dependency (`@impeccable/cli-<os>-<arch>`), and falls back to a per-user cache or a one-time download when that package is missing.
|
|
|
|
## Quick Start
|
|
|
|
```bash
|
|
# Install skills into your AI harness (Claude, Cursor, Gemini, etc.)
|
|
npx impeccable install
|
|
|
|
# Non-interactive install for a specific scope
|
|
npx impeccable install -y --providers=claude,codex --scope=project
|
|
|
|
# First command to run inside your AI harness
|
|
/impeccable init
|
|
|
|
# Update skills to the latest version
|
|
npx impeccable update
|
|
|
|
# Install or update skills without hook manifests
|
|
npx impeccable install --no-hooks
|
|
|
|
# Link skills from a Git submodule checkout
|
|
npx impeccable link --source=.impeccable --providers=claude,cursor
|
|
|
|
# List all available commands
|
|
npx impeccable help
|
|
|
|
# Scan files or directories for anti-patterns
|
|
npx impeccable detect src/
|
|
|
|
# Scan a live URL (uses an installed Chrome, Chromium, or Edge)
|
|
npx impeccable detect https://example.com
|
|
|
|
# JSON output for CI/tooling
|
|
npx impeccable detect --json src/
|
|
```
|
|
|
|
`npx impeccable skills <command>` is the legacy namespace and still works.
|
|
|
|
## What It Detects
|
|
|
|
**AI Slop Tells**: patterns that scream "AI generated this":
|
|
- Side-tab accent borders, gradient text on headings
|
|
- Purple/violet gradients and cyan-on-dark palettes
|
|
- Dark mode with glowing accents, border + border-radius clashes
|
|
|
|
**Typography Issues**: overused fonts (Inter, Roboto), flat type hierarchy, single font families
|
|
|
|
**Color & Contrast**: WCAG AA violations, gray text on colored backgrounds, pure black/white
|
|
|
|
**Layout & Composition**: nested cards, monotonous spacing, everything-centered layouts
|
|
|
|
**Motion**: bounce/elastic easing, layout property transitions
|
|
|
|
**Quality**: tiny body text, cramped padding, long line lengths, small touch targets
|
|
|
|
61 deterministic detector rules in total. See the full catalog at [impeccable.style/slop](https://impeccable.style/slop).
|
|
|
|
## Exit Codes
|
|
|
|
- `0`: no issues found
|
|
- `2`: anti-patterns detected
|
|
|
|
## Options
|
|
|
|
```
|
|
impeccable detect [options] [file-or-dir-or-url...]
|
|
|
|
--json Output findings as JSON
|
|
--scope Only report rules in a design domain (type, layout)
|
|
--help Show help
|
|
```
|
|
|
|
## Requirements
|
|
|
|
- Node.js 22.18+ to run `npx impeccable`. The engine itself is a self-contained binary and needs no runtime; the skill installed into your harness calls it directly.
|
|
- For URL scans, an installed Chrome, Chromium, or Edge (set `IMPECCABLE_BROWSER` to point at one).
|
|
|
|
Binary lookup order: `IMPECCABLE_BIN`, the platform package, `~/.impeccable/bin/<version>/`, then a download of the pinned version into that cache. Set `IMPECCABLE_BIN` to a local build to skip all of that.
|
|
|
|
## Part of Impeccable
|
|
|
|
This CLI is part of [Impeccable](https://impeccable.style), a cross-provider design skill pack for AI-powered development tools. The full suite includes 23 commands for Claude, Cursor, GitHub Copilot, Gemini, Codex, Hermes Agent, Veto, and more.
|
|
|
|
## License
|
|
|
|
[Apache 2.0](https://github.com/pbakaus/impeccable/blob/main/LICENSE)
|