impeccable 2.3.2 → 3.0.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 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 27 specific patterns including AI-generated UI tells, accessibility violations, and general design quality problems.
3
+ Detect UI anti-patterns and design quality issues from the command line. Scans HTML, CSS, JSX, TSX, Vue, and Svelte files for 41 deterministic rules, including AI-generated UI tells, accessibility violations, and general design quality problems.
4
4
 
5
5
  ## Quick Start
6
6
 
@@ -8,9 +8,21 @@ Detect UI anti-patterns and design quality issues from the command line. Scans H
8
8
  # Install skills into your AI harness (Claude, Cursor, Gemini, etc.)
9
9
  npx impeccable skills install
10
10
 
11
+ # Non-interactive install for a specific scope
12
+ npx impeccable skills install -y --providers=claude,codex --scope=project
13
+
14
+ # First command to run inside your AI harness
15
+ /impeccable init
16
+
11
17
  # Update skills to the latest version
12
18
  npx impeccable skills update
13
19
 
20
+ # Install or update skills without hook manifests
21
+ npx impeccable skills install --no-hooks
22
+
23
+ # Link skills from a Git submodule checkout
24
+ npx impeccable skills link --source=.impeccable --providers=claude,cursor
25
+
14
26
  # List all available commands
15
27
  npx impeccable skills help
16
28
 
@@ -23,7 +35,7 @@ npx impeccable detect https://example.com
23
35
  # JSON output for CI/tooling
24
36
  npx impeccable detect --json src/
25
37
 
26
- # Regex-only mode (faster, no jsdom)
38
+ # Deprecated compatibility flag; full scan still runs
27
39
  npx impeccable detect --fast src/
28
40
  ```
29
41
 
@@ -44,7 +56,7 @@ npx impeccable detect --fast src/
44
56
 
45
57
  **Quality**: tiny body text, cramped padding, long line lengths, small touch targets
46
58
 
47
- 25 detections in total. See the full list at [impeccable.style](https://impeccable.style).
59
+ 41 deterministic detector rules in total. See the full catalog at [impeccable.style/slop](https://impeccable.style/slop).
48
60
 
49
61
  ## Exit Codes
50
62
 
@@ -63,13 +75,13 @@ impeccable detect [options] [file-or-dir-or-url...]
63
75
 
64
76
  ## Requirements
65
77
 
66
- - Node.js 18+
78
+ - Node.js 24+
67
79
  - `jsdom` (included as dependency, used for HTML scanning)
68
80
  - `puppeteer` (optional, only needed for URL scanning)
69
81
 
70
82
  ## Part of Impeccable
71
83
 
72
- This CLI is part of [Impeccable](https://impeccable.style), a cross-provider design skill pack for AI-powered development tools. The full suite includes 22 steering commands for Claude, Cursor, Gemini, Codex, and more.
84
+ 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, Gemini, Codex, and more.
73
85
 
74
86
  ## License
75
87
 
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 27 specific patterns including AI-generated UI tells, accessibility violations, and general design quality problems.
3
+ Detect UI anti-patterns and design quality issues from the command line. Scans HTML, CSS, JSX, TSX, Vue, and Svelte files for 41 deterministic rules, including AI-generated UI tells, accessibility violations, and general design quality problems.
4
4
 
5
5
  ## Quick Start
6
6
 
@@ -8,9 +8,21 @@ Detect UI anti-patterns and design quality issues from the command line. Scans H
8
8
  # Install skills into your AI harness (Claude, Cursor, Gemini, etc.)
9
9
  npx impeccable skills install
10
10
 
11
+ # Non-interactive install for a specific scope
12
+ npx impeccable skills install -y --providers=claude,codex --scope=project
13
+
14
+ # First command to run inside your AI harness
15
+ /impeccable init
16
+
11
17
  # Update skills to the latest version
12
18
  npx impeccable skills update
13
19
 
20
+ # Install or update skills without hook manifests
21
+ npx impeccable skills install --no-hooks
22
+
23
+ # Link skills from a Git submodule checkout
24
+ npx impeccable skills link --source=.impeccable --providers=claude,cursor
25
+
14
26
  # List all available commands
15
27
  npx impeccable skills help
16
28
 
@@ -23,7 +35,7 @@ npx impeccable detect https://example.com
23
35
  # JSON output for CI/tooling
24
36
  npx impeccable detect --json src/
25
37
 
26
- # Regex-only mode (faster, no jsdom)
38
+ # Deprecated compatibility flag; full scan still runs
27
39
  npx impeccable detect --fast src/
28
40
  ```
29
41
 
@@ -44,7 +56,7 @@ npx impeccable detect --fast src/
44
56
 
45
57
  **Quality**: tiny body text, cramped padding, long line lengths, small touch targets
46
58
 
47
- 25 detections in total. See the full list at [impeccable.style](https://impeccable.style).
59
+ 41 deterministic detector rules in total. See the full catalog at [impeccable.style/slop](https://impeccable.style/slop).
48
60
 
49
61
  ## Exit Codes
50
62
 
@@ -63,13 +75,13 @@ impeccable detect [options] [file-or-dir-or-url...]
63
75
 
64
76
  ## Requirements
65
77
 
66
- - Node.js 18+
78
+ - Node.js 24+
67
79
  - `jsdom` (included as dependency, used for HTML scanning)
68
80
  - `puppeteer` (optional, only needed for URL scanning)
69
81
 
70
82
  ## Part of Impeccable
71
83
 
72
- This CLI is part of [Impeccable](https://impeccable.style), a cross-provider design skill pack for AI-powered development tools. The full suite includes 22 steering commands for Claude, Cursor, Gemini, Codex, and more.
84
+ 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, Gemini, Codex, and more.
73
85
 
74
86
  ## License
75
87
 
package/README.repo.md CHANGED
@@ -1,8 +1,8 @@
1
1
  # Impeccable
2
2
 
3
- The vocabulary you didn't know you needed. 1 skill, 23 commands, and curated anti-patterns for impeccable frontend design.
3
+ Design guidance for AI coding agents. 1 skill, 23 commands, live browser iteration, and 41 deterministic detector rules for AI-generated frontend design.
4
4
 
5
- > **Quick start:** Visit [impeccable.style](https://impeccable.style) to download ready-to-use bundles.
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
 
7
7
  ## Why Impeccable?
8
8
 
@@ -11,25 +11,27 @@ Anthropic's [frontend-design](https://github.com/anthropics/skills/tree/main/ski
11
11
  Every model trained on the same SaaS templates. Skip the guidance and you get the same handful of tells on every project: Inter for everything, purple-to-blue gradients, cards nested in cards, gray text on colored backgrounds, the rounded-square icon tile above every heading.
12
12
 
13
13
  Impeccable adds:
14
- - **7 domain reference files** ([view source](skill/)). Typography, color, motion, spatial, interaction, responsive, UX writing. Load on every command, alongside a brand-vs-product register that adjusts the defaults.
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
- - **27 deterministic anti-pattern rules** plus a 12-rule LLM critique pass. CLI and browser extension run the deterministic ones with no LLM and no API key. Each is tied to specific design guidance the skill teaches against.
16
+ - **41 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
 
20
20
  ### The Skill: impeccable
21
21
 
22
- A comprehensive design skill with 7 domain-specific references ([view skill](skill/SKILL.src.md)):
22
+ The skill installs as one command:
23
23
 
24
- | Reference | Covers |
25
- |-----------|--------|
26
- | [typography](skill/reference/typography.md) | Type systems, font pairing, modular scales, OpenType |
27
- | [color-and-contrast](skill/reference/color-and-contrast.md) | OKLCH, tinted neutrals, dark mode, accessibility |
28
- | [spatial-design](skill/reference/spatial-design.md) | Spacing systems, grids, visual hierarchy |
29
- | [motion-design](skill/reference/motion-design.md) | Easing curves, staggering, reduced motion |
30
- | [interaction-design](skill/reference/interaction-design.md) | Forms, focus states, loading patterns |
31
- | [responsive-design](skill/reference/responsive-design.md) | Mobile-first, fluid design, container queries |
32
- | [ux-writing](skill/reference/ux-writing.md) | Button labels, error messages, empty states |
24
+ ```bash
25
+ /impeccable <command> <target>
26
+ ```
27
+
28
+ Start every new project with:
29
+
30
+ ```bash
31
+ /impeccable init
32
+ ```
33
+
34
+ `init` asks whether the surface is brand (marketing, landing, portfolio) or product (app UI, dashboard, tool), then writes project context that every later command reads.
33
35
 
34
36
  ### 23 Commands
35
37
 
@@ -98,18 +100,44 @@ Visit [impeccable.style](https://impeccable.style#casestudies) to see before/aft
98
100
  From the root of your project, run:
99
101
 
100
102
  ```bash
101
- npx impeccable skills install
103
+ npx impeccable install
104
+ ```
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 Codex, it also installs the provider-native hook manifest for the current project. Works with Cursor, Claude Code, Gemini CLI, Codex CLI, and every other supported tool. Reload your harness afterward.
107
+
108
+ To refresh an existing install, run:
109
+
110
+ ```bash
111
+ npx impeccable update
112
+ ```
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.
115
+
116
+ ### Option 2: Git Submodule
117
+
118
+ For teams that want to keep Impeccable vendored and updated through Git, add this repo as a submodule and link the compiled provider build into your harness folders:
119
+
120
+ ```bash
121
+ git submodule add https://github.com/pbakaus/impeccable .impeccable
122
+ npx impeccable link --source=.impeccable --providers=claude,cursor
123
+ git add .gitmodules .impeccable .claude .cursor
124
+ git commit -m "Add Impeccable skills"
102
125
  ```
103
126
 
104
- This auto-detects your harness and writes the build compiled for it to the right location (`.claude/skills/`, `.cursor/skills/`, etc.). Works with Cursor, Claude Code, Gemini CLI, Codex CLI, and every other supported tool. Reload your harness afterward.
127
+ Use the providers your project needs, for example `claude`, `cursor`, `gemini`, `codex`, `github`, `opencode`, `pi`, `qoder`, `trae`, `trae-cn`, or `rovo-dev`. The command links individual skill folders from `.impeccable/dist/universal/` and leaves existing real skill directories untouched unless you pass `--force`.
105
128
 
106
- Claude Code users can alternatively install the plugin with `/plugin marketplace add pbakaus/impeccable`. The general-purpose `npx skills add pbakaus/impeccable` also works, though it installs one shared build for all harnesses rather than the one compiled for yours.
129
+ To update later:
107
130
 
108
- ### Option 2: Download from Website
131
+ ```bash
132
+ git submodule update --remote .impeccable
133
+ npx impeccable link --source=.impeccable --providers=claude,cursor
134
+ ```
135
+
136
+ ### Option 3: Download from Website
109
137
 
110
138
  Visit [impeccable.style](https://impeccable.style), download the ZIP for your tool, and extract to your project.
111
139
 
112
- ### Option 3: Copy from Repository
140
+ ### Option 4: Copy from Repository
113
141
 
114
142
  **Cursor:**
115
143
  ```bash
@@ -157,13 +185,16 @@ cp -r dist/gemini/.gemini your-project/
157
185
  ```bash
158
186
  # Project-local
159
187
  cp -r dist/agents/.agents your-project/
188
+ mkdir -p your-project/.codex
189
+ cp dist/codex/.codex/hooks.json your-project/.codex/hooks.json
160
190
 
161
- # Or user-wide
191
+ # Or install the skill user-wide. Copy .codex/hooks.json into each project
192
+ # where you want the design hook to run.
162
193
  mkdir -p ~/.agents/skills
163
194
  cp -r dist/agents/.agents/skills/* ~/.agents/skills/
164
195
  ```
165
196
 
166
- > The asset-producer subagent ships nested inside the skill's own `agents/` folder, which Codex auto-discovers. No separate `.codex/agents/` copy is needed.
197
+ > The asset-producer subagent ships nested inside the skill's own `agents/` folder, which Codex auto-discovers. No separate `.codex/agents/` copy is needed. The hook is project-local because Codex discovers hooks from `.codex/hooks.json` next to trusted project config.
167
198
 
168
199
  **GitHub Copilot:**
169
200
  ```bash
@@ -227,6 +258,31 @@ If you reach for one command often, pin it with `/impeccable pin audit` to get `
227
258
 
228
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.
229
260
 
261
+ ## Design hook
262
+
263
+ On Claude Code, 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 and Codex surface findings after the edit. Cursor blocks bad proposed writes before they land.
264
+
265
+ Installed hook surfaces:
266
+
267
+ - Claude Code: `.claude/settings.local.json` (gitignored, machine-local) runs `${CLAUDE_PROJECT_DIR}/.claude/skills/impeccable/scripts/hook.mjs`. A hook moved into the shared `settings.json` is honored in place.
268
+ - Cursor: `.cursor/hooks.json` runs `.cursor/skills/impeccable/scripts/hook-before-edit.mjs`.
269
+ - Codex: `.codex/hooks.json` runs `.agents/skills/impeccable/scripts/hook.mjs`.
270
+
271
+ The installer preserves unrelated hook entries and settings. If a hook manifest is malformed, install/update aborts by default; rerun with `--force` to back up the malformed file as `.bak` and replace it.
272
+
273
+ On an interactive `install`/`update`, Impeccable explains the hook and offers to install it (default yes). Your choice is remembered per-developer in the gitignored `.impeccable/config.local.json`, so you are not asked again; `--no-hooks` skips it for that run without recording anything. Hook settings (enable/ignore rules, etc.) live under the `hook` key of `.impeccable/config.json`, managed with `/impeccable hooks`.
274
+
275
+ For debugging, set `hook.auditLog` in `.impeccable/config.json` to a path (or the legacy `IMPECCABLE_HOOK_LOG` env var) to write one NDJSON line per hook invocation. Leave it unset for normal use.
276
+
277
+ Codex requires one platform step that Impeccable cannot safely skip: open `/hooks` after install or update and approve the project hook. There is no Codex marketplace/plugin install flow for this hook.
278
+
279
+ Manual copy commands are fallback/debug instructions. The normal path is:
280
+
281
+ ```bash
282
+ npx impeccable install
283
+ npx impeccable update
284
+ ```
285
+
230
286
  ## CLI
231
287
 
232
288
  Impeccable includes a standalone CLI for detecting anti-patterns without an AI harness:
@@ -238,7 +294,7 @@ npx impeccable detect https://example.com # scan a URL (Puppeteer)
238
294
  npx impeccable detect --fast --json . # regex-only, JSON output
239
295
  ```
240
296
 
241
- The detector catches 24 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).
297
+ The detector catches 41 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).
242
298
 
243
299
  ## Supported Tools
244
300
 
@@ -264,14 +320,12 @@ Join the community and ecosystem conversations:
264
320
 
265
321
  ## Contributing
266
322
 
267
- See [DEVELOP.md](DEVELOP.md) for contributor guidelines and build instructions.
323
+ See [DEVELOP.md](docs/DEVELOP.md) for contributor guidelines and build instructions.
268
324
 
269
325
  ## License
270
326
 
271
327
  Apache 2.0. See [LICENSE](LICENSE).
272
328
 
273
- The impeccable skill builds on [Anthropic's original frontend-design skill](https://github.com/anthropics/skills/tree/main/skills/frontend-design). See [NOTICE.md](NOTICE.md) for attribution.
274
-
275
329
  ---
276
330
 
277
331
  Created by [Paul Bakaus](https://www.paulbakaus.com)
package/cli/bin/cli.js CHANGED
@@ -5,7 +5,7 @@
5
5
  *
6
6
  * Usage:
7
7
  * npx impeccable detect [file-or-dir-or-url...]
8
- * npx impeccable skills help|install|update
8
+ * npx impeccable help|install|update
9
9
  * npx impeccable --help
10
10
  */
11
11
 
@@ -14,43 +14,62 @@ import { join, dirname } from 'node:path';
14
14
  import { fileURLToPath } from 'node:url';
15
15
 
16
16
  const __dirname = dirname(fileURLToPath(import.meta.url));
17
- const args = process.argv.slice(2);
18
- const command = args[0];
17
+ const SKILL_COMMANDS = new Set(['help', 'install', 'link', 'update', 'check']);
19
18
 
20
- if (!command || command === '--help' || command === '-h') {
21
- console.log(`Usage: impeccable <command> [options]
19
+ async function main() {
20
+ const args = process.argv.slice(2);
21
+ const command = args[0];
22
+
23
+ if (!command || command === '--help' || command === '-h') {
24
+ console.log(`Usage: impeccable <command> [options]
22
25
 
23
26
  Commands:
24
27
  detect [file-or-dir-or-url...] Scan for UI anti-patterns and design quality issues
25
- skills help List all available skills and commands
26
- skills install Install impeccable skills into your project
27
- skills update Update skills to the latest version
28
- skills check Check if skill updates are available
28
+ help List all available skills and commands
29
+ install Install impeccable skills into your project or global harness
30
+ link Symlink skills from a local checkout or submodule
31
+ update Update skills to the latest version
32
+ check Check if skill updates are available
29
33
 
30
34
  Options:
31
35
  --help Show this help message
32
36
  --version Show version number
33
37
 
34
- Run 'impeccable <command> --help' for command-specific options.`);
35
- process.exit(0);
36
- }
38
+ Compatibility:
39
+ impeccable skills <command> Legacy namespace; still supported.`);
40
+ process.exit(0);
41
+ }
37
42
 
38
- if (command === '--version' || command === '-v') {
39
- const pkg = JSON.parse(readFileSync(join(__dirname, '..', '..', 'package.json'), 'utf8'));
40
- console.log(pkg.version);
41
- process.exit(0);
42
- }
43
+ if (command === '--version' || command === '-v') {
44
+ const pkg = JSON.parse(readFileSync(join(__dirname, '..', '..', 'package.json'), 'utf8'));
45
+ console.log(pkg.version);
46
+ process.exit(0);
47
+ }
43
48
 
44
- if (command === 'detect') {
45
- process.argv = [process.argv[0], process.argv[1], ...args.slice(1)];
46
- const { detectCli } = await import('../engine/detect-antipatterns.mjs');
47
- await detectCli();
48
- } else if (command === 'skills') {
49
- const { run } = await import('./commands/skills.mjs');
50
- await run(args.slice(1));
51
- } else {
52
- // Default: treat as detect arguments (allow `npx impeccable src/` shorthand)
53
- process.argv = [process.argv[0], process.argv[1], ...args];
54
- const { detectCli } = await import('../engine/detect-antipatterns.mjs');
55
- await detectCli();
49
+ if (command === 'detect') {
50
+ process.argv = [process.argv[0], process.argv[1], ...args.slice(1)];
51
+ const { detectCli } = await import('../engine/detect-antipatterns.mjs');
52
+ await detectCli();
53
+ } else if (command === 'skills') {
54
+ const { run } = await import('./commands/skills.mjs');
55
+ await run(args.slice(1));
56
+ } else if (SKILL_COMMANDS.has(command)) {
57
+ const { run } = await import('./commands/skills.mjs');
58
+ await run(args);
59
+ } else {
60
+ // Default: treat as detect arguments (allow `npx impeccable src/` shorthand)
61
+ process.argv = [process.argv[0], process.argv[1], ...args];
62
+ const { detectCli } = await import('../engine/detect-antipatterns.mjs');
63
+ await detectCli();
64
+ }
56
65
  }
66
+
67
+ main().catch(error => {
68
+ if (error?.code === 'IMPECCABLE_PROMPT_ABORT') {
69
+ console.log('\nAborted.');
70
+ process.exit(130);
71
+ }
72
+
73
+ console.error(error?.message || error);
74
+ process.exit(1);
75
+ });