impeccable 3.2.0 → 3.3.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +3 -3
- package/README.npm.md +3 -3
- package/README.repo.md +48 -10
- package/cli/bin/commands/ignores.mjs +27 -6
- package/cli/bin/commands/skills.mjs +151 -77
- package/cli/engine/browser/injected/index.mjs +69 -6
- package/cli/engine/cli/main.mjs +63 -9
- package/cli/engine/design-system.mjs +171 -0
- package/cli/engine/detect-antipatterns-browser.js +2819 -159
- package/cli/engine/engines/browser/detect-url.mjs +67 -4
- package/cli/engine/engines/regex/detect-text.mjs +253 -72
- package/cli/engine/engines/static-html/css-cascade.mjs +161 -5
- package/cli/engine/engines/static-html/detect-html.mjs +18 -5
- package/cli/engine/findings.mjs +1 -1
- package/cli/engine/registry/antipatterns.mjs +160 -27
- package/cli/engine/rules/checks.mjs +2608 -139
- package/cli/engine/shared/fonts.mjs +30 -0
- package/cli/lib/download-providers.js +2 -0
- package/cli/lib/impeccable-config.mjs +15 -6
- package/package.json +11 -24
package/README.md
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# Impeccable CLI
|
|
2
2
|
|
|
3
|
-
Detect UI anti-patterns and design quality issues from the command line. Scans HTML, CSS, JSX, TSX, Vue, and Svelte files for
|
|
3
|
+
Detect UI anti-patterns and design quality issues from the command line. Scans HTML, CSS, JSX, TSX, Vue, and Svelte files for 58 deterministic rules, including AI-generated UI tells, accessibility violations, and general design quality problems.
|
|
4
4
|
|
|
5
5
|
## Quick Start
|
|
6
6
|
|
|
@@ -56,7 +56,7 @@ npx impeccable detect --fast src/
|
|
|
56
56
|
|
|
57
57
|
**Quality**: tiny body text, cramped padding, long line lengths, small touch targets
|
|
58
58
|
|
|
59
|
-
|
|
59
|
+
58 deterministic detector rules in total. See the full catalog at [impeccable.style/slop](https://impeccable.style/slop).
|
|
60
60
|
|
|
61
61
|
## Exit Codes
|
|
62
62
|
|
|
@@ -75,7 +75,7 @@ impeccable detect [options] [file-or-dir-or-url...]
|
|
|
75
75
|
|
|
76
76
|
## Requirements
|
|
77
77
|
|
|
78
|
-
- Node.js
|
|
78
|
+
- Node.js 22.12+
|
|
79
79
|
- `jsdom` (included as dependency, used for HTML scanning)
|
|
80
80
|
- `puppeteer` (optional, only needed for URL scanning)
|
|
81
81
|
|
package/README.npm.md
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# Impeccable CLI
|
|
2
2
|
|
|
3
|
-
Detect UI anti-patterns and design quality issues from the command line. Scans HTML, CSS, JSX, TSX, Vue, and Svelte files for
|
|
3
|
+
Detect UI anti-patterns and design quality issues from the command line. Scans HTML, CSS, JSX, TSX, Vue, and Svelte files for 58 deterministic rules, including AI-generated UI tells, accessibility violations, and general design quality problems.
|
|
4
4
|
|
|
5
5
|
## Quick Start
|
|
6
6
|
|
|
@@ -56,7 +56,7 @@ npx impeccable detect --fast src/
|
|
|
56
56
|
|
|
57
57
|
**Quality**: tiny body text, cramped padding, long line lengths, small touch targets
|
|
58
58
|
|
|
59
|
-
|
|
59
|
+
58 deterministic detector rules in total. See the full catalog at [impeccable.style/slop](https://impeccable.style/slop).
|
|
60
60
|
|
|
61
61
|
## Exit Codes
|
|
62
62
|
|
|
@@ -75,7 +75,7 @@ impeccable detect [options] [file-or-dir-or-url...]
|
|
|
75
75
|
|
|
76
76
|
## Requirements
|
|
77
77
|
|
|
78
|
-
- Node.js
|
|
78
|
+
- Node.js 22.12+
|
|
79
79
|
- `jsdom` (included as dependency, used for HTML scanning)
|
|
80
80
|
- `puppeteer` (optional, only needed for URL scanning)
|
|
81
81
|
|
package/README.repo.md
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# Impeccable
|
|
2
2
|
|
|
3
|
-
Design guidance for AI coding agents. 1 skill, 23 commands, live browser iteration, and
|
|
3
|
+
Design guidance for AI coding agents. 1 skill, 23 commands, live browser iteration, and 58 deterministic detector rules for AI-generated frontend design.
|
|
4
4
|
|
|
5
5
|
> **Quick start:** From your project root, run `npx impeccable install`, then run `/impeccable init` inside your AI coding tool. Full docs: [impeccable.style](https://impeccable.style).
|
|
6
6
|
|
|
@@ -13,7 +13,7 @@ Every model trained on the same SaaS templates. Skip the guidance and you get th
|
|
|
13
13
|
Impeccable adds:
|
|
14
14
|
- **One setup flow.** `/impeccable init` writes `PRODUCT.md` and offers `DESIGN.md`, so later commands know the audience, brand/product lane, voice, anti-references, colors, type, and components.
|
|
15
15
|
- **23 commands.** A shared design vocabulary with your AI: `polish`, `audit`, `critique`, `distill`, `animate`, `bolder`, `quieter`, and more.
|
|
16
|
-
- **
|
|
16
|
+
- **58 deterministic detector rules** plus LLM-only critique checks. The CLI and browser extension run the deterministic rules with no LLM and no API key.
|
|
17
17
|
|
|
18
18
|
## What's Included
|
|
19
19
|
|
|
@@ -91,7 +91,7 @@ The skill includes explicit guidance on what to avoid:
|
|
|
91
91
|
|
|
92
92
|
## See It In Action
|
|
93
93
|
|
|
94
|
-
Visit [
|
|
94
|
+
Visit [the Neo Mirai case study](https://impeccable.style/cases/neo-mirai) to see a before/after case study of a real project transformed with Impeccable commands.
|
|
95
95
|
|
|
96
96
|
## Installation
|
|
97
97
|
|
|
@@ -103,7 +103,7 @@ From the root of your project, run:
|
|
|
103
103
|
npx impeccable install
|
|
104
104
|
```
|
|
105
105
|
|
|
106
|
-
This shows the harness folders it detected (for example `~/.claude`, `~/.codex`, or project-local `.cursor`), lets you keep the detected set or customize providers, then asks whether to install into the current project or globally. Use `--providers=claude,codex,cursor` and `--scope=project|global` to skip those choices in scripts. On Claude Code, Cursor, and
|
|
106
|
+
This shows the harness folders it detected (for example `~/.claude`, `~/.codex`, `~/.grok`, or project-local `.cursor`), lets you keep the detected set or customize providers, then asks whether to install into the current project or globally. Use `--providers=claude,codex,cursor,grok` and `--scope=project|global` to skip those choices in scripts. On Claude Code, Cursor, Codex, GitHub Copilot, and Grok Build, it also installs the provider-native hook manifest for the current project. Works with Cursor, Claude Code, Gemini CLI, Codex CLI, Grok Build, and every other supported tool. Reload your harness afterward.
|
|
107
107
|
|
|
108
108
|
To refresh an existing install, run:
|
|
109
109
|
|
|
@@ -111,7 +111,7 @@ To refresh an existing install, run:
|
|
|
111
111
|
npx impeccable update
|
|
112
112
|
```
|
|
113
113
|
|
|
114
|
-
Codex users should open `/hooks` after install or update and approve the project hook when prompted. Codex tracks trust by hook definition, so updates that change `.codex/hooks.json` can require approval again.
|
|
114
|
+
Codex users should open `/hooks` after install or update and approve the project hook when prompted. Codex tracks trust by hook definition, so updates that change `.codex/hooks.json` can require approval again. Grok Build users need project folder trust (`/hooks-trust` or launch with `--trust`) before `.grok/hooks/` scripts run.
|
|
115
115
|
|
|
116
116
|
### Option 2: Git Submodule
|
|
117
117
|
|
|
@@ -124,7 +124,7 @@ git add .gitmodules .impeccable .claude .cursor
|
|
|
124
124
|
git commit -m "Add Impeccable skills"
|
|
125
125
|
```
|
|
126
126
|
|
|
127
|
-
Use the providers your project needs, for example `claude`, `cursor`, `gemini`, `codex`, `github`, `opencode`, `pi`, `qoder`, `trae`, `trae-cn`,
|
|
127
|
+
Use the providers your project needs, for example `claude`, `cursor`, `gemini`, `codex`, `github`, `grok`, `opencode`, `pi`, `qoder`, `trae`, `trae-cn`, `rovo-dev`, or `vibe`. The command links individual skill folders from `.impeccable/dist/universal/` and leaves existing real skill directories untouched unless you pass `--force`.
|
|
128
128
|
|
|
129
129
|
To update later:
|
|
130
130
|
|
|
@@ -133,11 +133,27 @@ git submodule update --remote .impeccable
|
|
|
133
133
|
npx impeccable link --source=.impeccable --providers=claude,cursor
|
|
134
134
|
```
|
|
135
135
|
|
|
136
|
-
### Option 3:
|
|
136
|
+
### Option 3: Plugin install
|
|
137
|
+
|
|
138
|
+
**Claude Code:**
|
|
139
|
+
```bash
|
|
140
|
+
/plugin marketplace add pbakaus/impeccable
|
|
141
|
+
```
|
|
142
|
+
|
|
143
|
+
> Claude Code only. After adding the marketplace, open `/plugin` and install Impeccable from the list.
|
|
144
|
+
|
|
145
|
+
**Grok Build:**
|
|
146
|
+
```bash
|
|
147
|
+
grok plugin install pbakaus/impeccable#plugin --trust
|
|
148
|
+
```
|
|
149
|
+
|
|
150
|
+
> Grok Build only. The `#plugin` suffix installs the slim plugin package (skills, agents, and hooks) instead of the full monorepo. Then run `/impeccable init` in a Grok session. Project-scoped installs via `npx impeccable install --providers=grok` also work and write `.grok/skills/` plus `.grok/hooks/impeccable.json`.
|
|
151
|
+
|
|
152
|
+
### Option 4: Download from Website
|
|
137
153
|
|
|
138
154
|
Visit [impeccable.style](https://impeccable.style), download the ZIP for your tool, and extract to your project.
|
|
139
155
|
|
|
140
|
-
### Option
|
|
156
|
+
### Option 5: Copy from Repository
|
|
141
157
|
|
|
142
158
|
**Cursor:**
|
|
143
159
|
```bash
|
|
@@ -234,6 +250,26 @@ cp -r dist/qoder/.qoder your-project/
|
|
|
234
250
|
cp -r dist/qoder/.qoder/skills/* ~/.qoder/skills/
|
|
235
251
|
```
|
|
236
252
|
|
|
253
|
+
**Mistral Vibe:**
|
|
254
|
+
```bash
|
|
255
|
+
# Project-specific
|
|
256
|
+
cp -r dist/vibe/.vibe your-project/
|
|
257
|
+
|
|
258
|
+
# Or global (applies to all projects)
|
|
259
|
+
cp -r dist/vibe/.vibe/skills/* ~/.vibe/skills/
|
|
260
|
+
```
|
|
261
|
+
|
|
262
|
+
**Grok Build:**
|
|
263
|
+
```bash
|
|
264
|
+
# Project-specific
|
|
265
|
+
cp -r dist/grok/.grok your-project/
|
|
266
|
+
|
|
267
|
+
# Or global (applies to all projects)
|
|
268
|
+
cp -r dist/grok/.grok/skills/* ~/.grok/skills/
|
|
269
|
+
```
|
|
270
|
+
|
|
271
|
+
> Prefer `npx impeccable install --providers=grok` or `grok plugin install pbakaus/impeccable#plugin --trust` so the design hook installs too. Project hooks need `/hooks-trust` (or `--trust`) once per folder.
|
|
272
|
+
|
|
237
273
|
## Usage
|
|
238
274
|
|
|
239
275
|
Once installed, every command runs through the single `/impeccable` skill:
|
|
@@ -300,7 +336,7 @@ If an ephemeral file (a screenshot, `config.local.json`) was committed before yo
|
|
|
300
336
|
|
|
301
337
|
## Design hook
|
|
302
338
|
|
|
303
|
-
On Claude Code, GitHub Copilot, Codex, and
|
|
339
|
+
On Claude Code, GitHub Copilot, Codex, Cursor, and Grok Build, `npx impeccable install` and `npx impeccable update` install a provider-native hook manifest along with the skill payload. The hook runs the Impeccable design detector on direct UI file edits and surfaces findings back into the agent flow. Claude Code, GitHub Copilot, Codex, and Grok Build surface findings after the edit (and run a deeper pass on Stop where supported). Cursor blocks bad proposed writes before they land.
|
|
304
340
|
|
|
305
341
|
Installed hook surfaces:
|
|
306
342
|
|
|
@@ -341,7 +377,7 @@ npx impeccable ignores add-file "src/legacy/**"
|
|
|
341
377
|
npx impeccable ignores add-value overused-font Inter --reason "Brand font"
|
|
342
378
|
```
|
|
343
379
|
|
|
344
|
-
The detector catches
|
|
380
|
+
The detector catches 49 deterministic issues across AI slop (side-tab borders, purple gradients, bounce easing, dark glows) and general design quality (line length, cramped padding, small touch targets, skipped headings, and more).
|
|
345
381
|
|
|
346
382
|
By default, `detect` respects the same `.impeccable/config.json` and `.impeccable/config.local.json` detector config as the design hook: `detector.ignoreRules`, `detector.ignoreFiles`, `detector.ignoreValues`, and `detector.designSystem.enabled`. Hook lifecycle settings such as `hook.enabled` only affect automatic hook execution.
|
|
347
383
|
|
|
@@ -356,12 +392,14 @@ Full detector docs: [impeccable.style/docs/detector](https://impeccable.style/do
|
|
|
356
392
|
- [GitHub Copilot](https://github.com/features/copilot)
|
|
357
393
|
- [Gemini CLI](https://github.com/google-gemini/gemini-cli)
|
|
358
394
|
- [Codex CLI](https://github.com/openai/codex)
|
|
395
|
+
- [Grok Build](https://x.ai/cli)
|
|
359
396
|
- [OpenCode](https://opencode.ai)
|
|
360
397
|
- [Pi](https://pi.dev)
|
|
361
398
|
- [Kiro](https://kiro.dev)
|
|
362
399
|
- [Trae](https://trae.ai)
|
|
363
400
|
- [Rovo Dev](https://www.atlassian.com/software/rovo)
|
|
364
401
|
- [Qoder](https://qoder.com)
|
|
402
|
+
- [Mistral Vibe](https://docs.mistral.ai/vibe/code/overview)
|
|
365
403
|
|
|
366
404
|
## Community & Ecosystem
|
|
367
405
|
|
|
@@ -78,6 +78,20 @@ function parseScope(args, { allowAll = false } = {}) {
|
|
|
78
78
|
return { local, all, rest };
|
|
79
79
|
}
|
|
80
80
|
|
|
81
|
+
// An empty glob used to be dropped by filter(Boolean), so `--file=` reported
|
|
82
|
+
// success and wrote an entry with no files: the user asked to scope a rule to one
|
|
83
|
+
// file and silently got the project-wide suppression instead. Refuse it.
|
|
84
|
+
function requireGlob(raw, flag) {
|
|
85
|
+
const glob = String(raw ?? '').trim();
|
|
86
|
+
if (!glob) throw new Error(`${flag} requires a non-empty glob`);
|
|
87
|
+
// A following flag is not a glob. `--file --reason "why"` consumed `--reason`
|
|
88
|
+
// as the scope and left the reason text to fold into the value, storing
|
|
89
|
+
// value="* why" files=["--reason"] and reporting success. Same silent-no-op
|
|
90
|
+
// class as an unknown flag folding into the value; refuse it the same way.
|
|
91
|
+
if (glob.startsWith('--')) throw new Error(`${flag} requires a glob, got the flag ${glob}`);
|
|
92
|
+
return glob;
|
|
93
|
+
}
|
|
94
|
+
|
|
81
95
|
function parseValueArgs(args, { allowUnscopedWildcard = false } = {}) {
|
|
82
96
|
const positionals = [];
|
|
83
97
|
const files = [];
|
|
@@ -93,11 +107,11 @@ function parseValueArgs(args, { allowUnscopedWildcard = false } = {}) {
|
|
|
93
107
|
reason = arg.slice('--reason='.length).trim();
|
|
94
108
|
} else if (arg === '--file' || arg === '--files') {
|
|
95
109
|
if (i + 1 >= args.length) throw new Error(`${arg} requires a glob`);
|
|
96
|
-
files.push(
|
|
110
|
+
files.push(requireGlob(args[++i], arg));
|
|
97
111
|
} else if (arg.startsWith('--file=')) {
|
|
98
|
-
files.push(arg.slice('--file='.length)
|
|
112
|
+
files.push(requireGlob(arg.slice('--file='.length), '--file'));
|
|
99
113
|
} else if (arg.startsWith('--files=')) {
|
|
100
|
-
files.push(arg.slice('--files='.length)
|
|
114
|
+
files.push(requireGlob(arg.slice('--files='.length), '--files'));
|
|
101
115
|
} else if (arg.startsWith('--')) {
|
|
102
116
|
throw new Error(`Unknown add-value flag: ${arg}`);
|
|
103
117
|
} else {
|
|
@@ -108,7 +122,9 @@ function parseValueArgs(args, { allowUnscopedWildcard = false } = {}) {
|
|
|
108
122
|
const [rule, ...valueParts] = positionals;
|
|
109
123
|
const value = normalizeIgnoreValue(valueParts.join(' '));
|
|
110
124
|
if (!rule || !value) throw new Error('Pass a rule id and value, e.g. impeccable ignores add-value overused-font Inter');
|
|
111
|
-
|
|
125
|
+
// Sorted: the dedup key compares the files array, so an unsorted scope made
|
|
126
|
+
// `--file b.css --file a.css` a different entry from `--file a.css --file b.css`.
|
|
127
|
+
const scopedFiles = Array.from(new Set(files.filter(Boolean))).sort();
|
|
112
128
|
if (value === '*' && scopedFiles.length === 0 && !allowUnscopedWildcard) {
|
|
113
129
|
throw new Error('Wildcard value ignores must be scoped with --file <glob>.');
|
|
114
130
|
}
|
|
@@ -226,12 +242,14 @@ function addValue(cwd, args) {
|
|
|
226
242
|
if (parsed.reason) existing.reason = parsed.reason;
|
|
227
243
|
if (parsed.files.length) existing.files = parsed.files;
|
|
228
244
|
} else {
|
|
245
|
+
// rule, value, files, createdAt, reason — the same order the normalizers emit,
|
|
246
|
+
// so a fresh entry survives the next write untouched.
|
|
229
247
|
const entry = {
|
|
230
248
|
rule: parsed.rule,
|
|
231
249
|
value: parsed.value,
|
|
232
|
-
createdAt: new Date().toISOString(),
|
|
233
250
|
};
|
|
234
251
|
if (parsed.files.length) entry.files = parsed.files;
|
|
252
|
+
entry.createdAt = new Date().toISOString();
|
|
235
253
|
if (parsed.reason) entry.reason = parsed.reason;
|
|
236
254
|
config.ignoreValues.push(entry);
|
|
237
255
|
}
|
|
@@ -299,7 +317,10 @@ function clear(cwd, args) {
|
|
|
299
317
|
}
|
|
300
318
|
|
|
301
319
|
function ignoreValueKey(entry) {
|
|
302
|
-
|
|
320
|
+
// Sorted: a file scope is a set. Comparing stored order made an on-disk scope
|
|
321
|
+
// miss the sorted argv form, so a re-add duplicated the entry and a remove
|
|
322
|
+
// silently failed. Every key that hashes `files` must sort — there are four.
|
|
323
|
+
const files = Array.isArray(entry.files) && entry.files.length ? [...entry.files].sort().join('\x1f') : '';
|
|
303
324
|
return `${String(entry.rule || '').trim().toLowerCase()}\0${normalizeIgnoreValue(entry.value)}\0${files}`;
|
|
304
325
|
}
|
|
305
326
|
|