impeccable 3.1.0 → 3.2.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 +2 -2
- package/README.npm.md +2 -2
- package/README.repo.md +43 -3
- package/cli/bin/commands/skills.mjs +35 -3
- package/cli/engine/detect-antipatterns-browser.js +47 -0
- package/cli/engine/registry/antipatterns.mjs +11 -0
- package/cli/engine/rules/checks.mjs +36 -0
- package/package.json +3 -3
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 45 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
|
+
45 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
|
|
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 45 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
|
+
45 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
|
|
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 45 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
|
+
- **45 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
|
|
|
@@ -258,6 +258,46 @@ If you reach for one command often, pin it with `/impeccable pin audit` to get `
|
|
|
258
258
|
|
|
259
259
|
**Note:** Codex uses skills here, not `/prompts:` commands. Open `/skills` or type `$impeccable`. Repo-local installs live in `.agents/skills/`; user-wide installs live in `~/.agents/skills/`. GitHub Copilot uses `.github/skills/`. Restart the tool if a newly installed skill does not appear.
|
|
260
260
|
|
|
261
|
+
## Keeping `.impeccable` out of git
|
|
262
|
+
|
|
263
|
+
As you run commands, Impeccable writes working files under `.impeccable/`: critique and polish screenshots, live-mode session and preview state, runtime caches, and per-developer config. Most of it is ephemeral and should not be committed, while a few files are shared project artifacts that belong in the repo. Add this block to your project's `.gitignore`:
|
|
264
|
+
|
|
265
|
+
```gitignore
|
|
266
|
+
# impeccable-ignore-start
|
|
267
|
+
# Ephemeral output, runtime state, and per-dev overrides.
|
|
268
|
+
# Unanchored: .impeccable may sit at the repo root or under a nested
|
|
269
|
+
# workspace (apps/web/.impeccable/...); anchored patterns would miss it.
|
|
270
|
+
# Shared artifacts stay tracked: config.json, live/config.json,
|
|
271
|
+
# design.json, critique/*.md.
|
|
272
|
+
.impeccable/config.local.json
|
|
273
|
+
.impeccable/hook.cache.json
|
|
274
|
+
.impeccable/hook.pending.json
|
|
275
|
+
.impeccable/*.png
|
|
276
|
+
.impeccable/live/server.json
|
|
277
|
+
.impeccable/live/sessions/
|
|
278
|
+
.impeccable/live/previews/
|
|
279
|
+
.impeccable/live/annotations/
|
|
280
|
+
.impeccable/live/cache/
|
|
281
|
+
.impeccable/live/manual-edit-apply-transaction.json
|
|
282
|
+
.impeccable/live/manual-edit-events.jsonl
|
|
283
|
+
.impeccable/live/manual-edit-evidence/
|
|
284
|
+
.impeccable/live/pending-manual-edits.json
|
|
285
|
+
.impeccable/live/deferred-svelte-component-accepts.json
|
|
286
|
+
.impeccable/live/*.png
|
|
287
|
+
# impeccable-ignore-end
|
|
288
|
+
```
|
|
289
|
+
|
|
290
|
+
The block is wrapped in `# impeccable-ignore-start` / `# impeccable-ignore-end` markers so you can recognize and refresh it later. Patterns are unanchored on purpose: in a monorepo the active project (and its `.impeccable/` directory) often lives under a nested workspace path like `apps/web/`, and a root-anchored pattern would miss it.
|
|
291
|
+
|
|
292
|
+
**Keep these tracked** (they are shared project artifacts, do not add them to `.gitignore`):
|
|
293
|
+
|
|
294
|
+
- `.impeccable/config.json` (unified shared config)
|
|
295
|
+
- `.impeccable/live/config.json` (live-mode framework wiring)
|
|
296
|
+
- `.impeccable/design.json` (shared design spec)
|
|
297
|
+
- `.impeccable/critique/*.md` (review reports)
|
|
298
|
+
|
|
299
|
+
If an ephemeral file (a screenshot, `config.local.json`) was committed before you added the block, `.gitignore` will not untrack it automatically. Run `git rm --cached <path>` to stop tracking it without deleting your local copy.
|
|
300
|
+
|
|
261
301
|
## Design hook
|
|
262
302
|
|
|
263
303
|
On Claude Code, GitHub Copilot, Codex, and Cursor, `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, and Codex surface findings after the edit. Cursor blocks bad proposed writes before they land.
|
|
@@ -301,7 +341,7 @@ npx impeccable ignores add-file "src/legacy/**"
|
|
|
301
341
|
npx impeccable ignores add-value overused-font Inter --reason "Brand font"
|
|
302
342
|
```
|
|
303
343
|
|
|
304
|
-
The detector catches
|
|
344
|
+
The detector catches 45 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).
|
|
305
345
|
|
|
306
346
|
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.
|
|
307
347
|
|
|
@@ -1010,6 +1010,36 @@ async function chooseInstallPlan(projectRoot, flags, { yes } = {}) {
|
|
|
1010
1010
|
return { targets, scope, installRoot, hookRoot: projectRoot, detections };
|
|
1011
1011
|
}
|
|
1012
1012
|
|
|
1013
|
+
/**
|
|
1014
|
+
* Whether `localSkillsDir` is a symlink that points at ANOTHER in-project
|
|
1015
|
+
* provider's skills dir (e.g. `.claude/skills -> ../.agents/skills`, the shape a
|
|
1016
|
+
* prior `npx skills` install can leave behind). Only these get dropped so each
|
|
1017
|
+
* provider can receive its own compiled variant. A symlink to anywhere else -
|
|
1018
|
+
* notably a user's external shared skills dir (`~/.claude/skills ->
|
|
1019
|
+
* ~/.config/agents/skills`) - is preserved and written through. See issue #295.
|
|
1020
|
+
*/
|
|
1021
|
+
function isInProjectProviderLink(localSkillsDir, root, provider) {
|
|
1022
|
+
let target;
|
|
1023
|
+
try {
|
|
1024
|
+
if (!lstatSync(localSkillsDir).isSymbolicLink()) return false;
|
|
1025
|
+
target = readlinkSync(localSkillsDir);
|
|
1026
|
+
} catch {
|
|
1027
|
+
return false; // not a symlink, or unreadable
|
|
1028
|
+
}
|
|
1029
|
+
// Resolve the link's TARGET lexically against the link's own directory. We
|
|
1030
|
+
// deliberately do NOT realpathSync the target:
|
|
1031
|
+
// * it lets a not-yet-created in-project target still match, so a dangling
|
|
1032
|
+
// `.claude/skills -> ../.agents/skills` is still dropped;
|
|
1033
|
+
// * it compares the ACTUAL target, not a shared realpath, so two providers
|
|
1034
|
+
// pointing at the SAME external dir are never misread as in-project.
|
|
1035
|
+
const resolvedTarget = resolve(dirname(localSkillsDir), target);
|
|
1036
|
+
for (const other of PROVIDER_DIRS) {
|
|
1037
|
+
if (other === provider) continue;
|
|
1038
|
+
if (resolvedTarget === join(root, other, 'skills')) return true;
|
|
1039
|
+
}
|
|
1040
|
+
return false;
|
|
1041
|
+
}
|
|
1042
|
+
|
|
1013
1043
|
/**
|
|
1014
1044
|
* Copy each target provider's compiled skill variant from an extracted bundle
|
|
1015
1045
|
* into the project. Writes real directories (copy, never symlink) so every
|
|
@@ -1022,10 +1052,12 @@ function copyProviderSkills(bundleDir, root, targets) {
|
|
|
1022
1052
|
if (existsSync(srcDir)) {
|
|
1023
1053
|
const localSkillsDir = join(root, provider, 'skills');
|
|
1024
1054
|
// A previous `npx skills` install may have left this provider's skills dir
|
|
1025
|
-
// as a symlink to
|
|
1026
|
-
// write a real, provider-specific directory
|
|
1055
|
+
// as a symlink to ANOTHER in-project provider's canonical copy. Drop only
|
|
1056
|
+
// that link so we write a real, provider-specific directory. A user's
|
|
1057
|
+
// external shared-skills symlink (e.g. ~/.claude/skills ->
|
|
1058
|
+
// ~/.config/agents/skills) is preserved and written through. See #295.
|
|
1027
1059
|
try {
|
|
1028
|
-
if (
|
|
1060
|
+
if (isInProjectProviderLink(localSkillsDir, root, provider)) unlinkSync(localSkillsDir);
|
|
1029
1061
|
} catch {}
|
|
1030
1062
|
for (const skill of readdirSync(srcDir, { withFileTypes: true })) {
|
|
1031
1063
|
if (!skill.isDirectory()) continue;
|
|
@@ -478,6 +478,17 @@ const ANTIPATTERNS = [
|
|
|
478
478
|
skillSection: 'Visual Details',
|
|
479
479
|
skillGuideline: 'repeating-gradient decorative stripes',
|
|
480
480
|
},
|
|
481
|
+
{
|
|
482
|
+
id: 'codex-grid-background',
|
|
483
|
+
category: 'slop',
|
|
484
|
+
severity: 'advisory',
|
|
485
|
+
gated: 'gpt',
|
|
486
|
+
name: 'Decorative grid-line background',
|
|
487
|
+
description:
|
|
488
|
+
'A two-axis grid drawn with hairline linear-gradient layers ("1px, transparent 1px" on both axes) is a recurring generated-UI signature. Reserve grid overlays for actual canvas, map, blueprint, or measurement surfaces; elsewhere use product structure or a plain surface.',
|
|
489
|
+
skillSection: 'Visual Details',
|
|
490
|
+
skillGuideline: 'two-axis grid-line gradient background',
|
|
491
|
+
},
|
|
481
492
|
{
|
|
482
493
|
id: 'theater-slop-phrase',
|
|
483
494
|
category: 'slop',
|
|
@@ -1172,6 +1183,42 @@ function checkHtmlPatterns(html) {
|
|
|
1172
1183
|
findings.push({ id: 'repeating-stripes-gradient', snippet: 'repeating-gradient decorative stripes' });
|
|
1173
1184
|
}
|
|
1174
1185
|
|
|
1186
|
+
// --- Provider tells (gated): two-axis grid-line background (Codex/GPT) ---
|
|
1187
|
+
// The Codex grid tell is two hairline `linear-gradient(... <color> 1px,
|
|
1188
|
+
// transparent 1px)` layers (one per axis) tiled by a repeating
|
|
1189
|
+
// `background-size` cell. Both signals must co-occur in the SAME style block
|
|
1190
|
+
// (a CSS rule body or one inline `style="..."`): two hairline stops WITHOUT a
|
|
1191
|
+
// tiling background-size is a fixed crosshair, not a grid, and a single
|
|
1192
|
+
// hairline is a legitimate ruled line. Scoping to one block also stops
|
|
1193
|
+
// unrelated single-axis rules on separate elements from adding up across the
|
|
1194
|
+
// page. Count hairlines only inside `background`/`background-image` values so
|
|
1195
|
+
// a hairline in an unrelated property (mask-image, border-image) can't stand
|
|
1196
|
+
// in for the second axis. Colors like `oklch(96% 0.012 82 / 0.055)` carry
|
|
1197
|
+
// nested parens, so match the hairline stop directly rather than parsing
|
|
1198
|
+
// whole gradient layers.
|
|
1199
|
+
{
|
|
1200
|
+
const hairlineRe = /\b\d{1,3}px\s*,\s*transparent\s+\d{1,3}px/gi;
|
|
1201
|
+
const gridSizeRe = /background-size\s*:[^;{}"']*\b\d{1,3}px\b/i;
|
|
1202
|
+
const bgDeclRe = /\bbackground(?:-image)?\s*:\s*([^;{}"']*)/gi;
|
|
1203
|
+
const blockRe = /\{([^{}]*)\}|style\s*=\s*"([^"]*)"|style\s*=\s*'([^']*)'/gi;
|
|
1204
|
+
let blk;
|
|
1205
|
+
while ((blk = blockRe.exec(html)) !== null) {
|
|
1206
|
+
const block = blk[1] || blk[2] || blk[3] || '';
|
|
1207
|
+
if (!gridSizeRe.test(block)) continue;
|
|
1208
|
+
let hairlineCount = 0;
|
|
1209
|
+
let bm;
|
|
1210
|
+
bgDeclRe.lastIndex = 0;
|
|
1211
|
+
while ((bm = bgDeclRe.exec(block)) !== null) {
|
|
1212
|
+
const stops = bm[1].match(hairlineRe);
|
|
1213
|
+
if (stops) hairlineCount += stops.length;
|
|
1214
|
+
}
|
|
1215
|
+
if (hairlineCount >= 2) {
|
|
1216
|
+
findings.push({ id: 'codex-grid-background', snippet: 'two-axis grid-line gradient background' });
|
|
1217
|
+
break;
|
|
1218
|
+
}
|
|
1219
|
+
}
|
|
1220
|
+
}
|
|
1221
|
+
|
|
1175
1222
|
// --- Provider tells (gated): "X theater" framing copy (GPT) ---
|
|
1176
1223
|
// Lives here (regex-on-HTML) rather than in the text-content analyzers so it
|
|
1177
1224
|
// runs in the bundled browser path too, not just the CLI/static path.
|
|
@@ -376,6 +376,17 @@ const ANTIPATTERNS = [
|
|
|
376
376
|
skillSection: 'Visual Details',
|
|
377
377
|
skillGuideline: 'repeating-gradient decorative stripes',
|
|
378
378
|
},
|
|
379
|
+
{
|
|
380
|
+
id: 'codex-grid-background',
|
|
381
|
+
category: 'slop',
|
|
382
|
+
severity: 'advisory',
|
|
383
|
+
gated: 'gpt',
|
|
384
|
+
name: 'Decorative grid-line background',
|
|
385
|
+
description:
|
|
386
|
+
'A two-axis grid drawn with hairline linear-gradient layers ("1px, transparent 1px" on both axes) is a recurring generated-UI signature. Reserve grid overlays for actual canvas, map, blueprint, or measurement surfaces; elsewhere use product structure or a plain surface.',
|
|
387
|
+
skillSection: 'Visual Details',
|
|
388
|
+
skillGuideline: 'two-axis grid-line gradient background',
|
|
389
|
+
},
|
|
379
390
|
{
|
|
380
391
|
id: 'theater-slop-phrase',
|
|
381
392
|
category: 'slop',
|
|
@@ -573,6 +573,42 @@ function checkHtmlPatterns(html) {
|
|
|
573
573
|
findings.push({ id: 'repeating-stripes-gradient', snippet: 'repeating-gradient decorative stripes' });
|
|
574
574
|
}
|
|
575
575
|
|
|
576
|
+
// --- Provider tells (gated): two-axis grid-line background (Codex/GPT) ---
|
|
577
|
+
// The Codex grid tell is two hairline `linear-gradient(... <color> 1px,
|
|
578
|
+
// transparent 1px)` layers (one per axis) tiled by a repeating
|
|
579
|
+
// `background-size` cell. Both signals must co-occur in the SAME style block
|
|
580
|
+
// (a CSS rule body or one inline `style="..."`): two hairline stops WITHOUT a
|
|
581
|
+
// tiling background-size is a fixed crosshair, not a grid, and a single
|
|
582
|
+
// hairline is a legitimate ruled line. Scoping to one block also stops
|
|
583
|
+
// unrelated single-axis rules on separate elements from adding up across the
|
|
584
|
+
// page. Count hairlines only inside `background`/`background-image` values so
|
|
585
|
+
// a hairline in an unrelated property (mask-image, border-image) can't stand
|
|
586
|
+
// in for the second axis. Colors like `oklch(96% 0.012 82 / 0.055)` carry
|
|
587
|
+
// nested parens, so match the hairline stop directly rather than parsing
|
|
588
|
+
// whole gradient layers.
|
|
589
|
+
{
|
|
590
|
+
const hairlineRe = /\b\d{1,3}px\s*,\s*transparent\s+\d{1,3}px/gi;
|
|
591
|
+
const gridSizeRe = /background-size\s*:[^;{}"']*\b\d{1,3}px\b/i;
|
|
592
|
+
const bgDeclRe = /\bbackground(?:-image)?\s*:\s*([^;{}"']*)/gi;
|
|
593
|
+
const blockRe = /\{([^{}]*)\}|style\s*=\s*"([^"]*)"|style\s*=\s*'([^']*)'/gi;
|
|
594
|
+
let blk;
|
|
595
|
+
while ((blk = blockRe.exec(html)) !== null) {
|
|
596
|
+
const block = blk[1] || blk[2] || blk[3] || '';
|
|
597
|
+
if (!gridSizeRe.test(block)) continue;
|
|
598
|
+
let hairlineCount = 0;
|
|
599
|
+
let bm;
|
|
600
|
+
bgDeclRe.lastIndex = 0;
|
|
601
|
+
while ((bm = bgDeclRe.exec(block)) !== null) {
|
|
602
|
+
const stops = bm[1].match(hairlineRe);
|
|
603
|
+
if (stops) hairlineCount += stops.length;
|
|
604
|
+
}
|
|
605
|
+
if (hairlineCount >= 2) {
|
|
606
|
+
findings.push({ id: 'codex-grid-background', snippet: 'two-axis grid-line gradient background' });
|
|
607
|
+
break;
|
|
608
|
+
}
|
|
609
|
+
}
|
|
610
|
+
}
|
|
611
|
+
|
|
576
612
|
// --- Provider tells (gated): "X theater" framing copy (GPT) ---
|
|
577
613
|
// Lives here (regex-on-HTML) rather than in the text-content analyzers so it
|
|
578
614
|
// runs in the bundled browser path too, not just the CLI/static path.
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "impeccable",
|
|
3
|
-
"version": "3.
|
|
3
|
+
"version": "3.2.0",
|
|
4
4
|
"author": "Paul Bakaus",
|
|
5
5
|
"description": "Design skills, commands, and anti-pattern detection for AI coding agents",
|
|
6
6
|
"keywords": [
|
|
@@ -93,12 +93,12 @@
|
|
|
93
93
|
"@ai-sdk/google": "^3.0.75",
|
|
94
94
|
"@ai-sdk/openai": "^3.0.53",
|
|
95
95
|
"@anthropic-ai/claude-agent-sdk": "^0.3.165",
|
|
96
|
-
"@anthropic-ai/sdk": "^0.
|
|
96
|
+
"@anthropic-ai/sdk": "^0.105.0",
|
|
97
97
|
"@google/genai": "^2.8.0",
|
|
98
98
|
"@paper-design/shaders": "^0.0.76",
|
|
99
99
|
"ai": "^6.0.168",
|
|
100
100
|
"archiver": "^8.0.0",
|
|
101
|
-
"astro": "^
|
|
101
|
+
"astro": "^7.0.0",
|
|
102
102
|
"fontkit": "^2.0.4",
|
|
103
103
|
"modern-screenshot": "^4.7.0",
|
|
104
104
|
"motion": "^12.38.0",
|