impeccable 2.1.8 → 2.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 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 25 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 27 specific patterns including AI-generated UI tells, accessibility violations, and general design quality problems.
4
4
 
5
5
  ## Quick Start
6
6
 
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 25 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 27 specific patterns including AI-generated UI tells, accessibility violations, and general design quality problems.
4
4
 
5
5
  ## Quick Start
6
6
 
package/README.repo.md CHANGED
@@ -6,30 +6,30 @@ The vocabulary you didn't know you needed. 1 skill, 23 commands, and curated ant
6
6
 
7
7
  ## Why Impeccable?
8
8
 
9
- Anthropic created [frontend-design](https://github.com/anthropics/skills/tree/main/skills/frontend-design), a skill that guides Claude toward better UI design. Impeccable builds on that foundation with deeper expertise and more control.
9
+ Anthropic's [frontend-design](https://github.com/anthropics/skills/tree/main/skills/frontend-design) was the first widely-used design skill for Claude. Impeccable started from there.
10
10
 
11
- Every LLM learned from the same generic templates. Without guidance, you get the same predictable mistakes: Inter font, purple gradients, cards nested in cards, gray text on colored backgrounds.
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
- Impeccable fights that bias with:
14
- - **An expanded skill** with 7 domain-specific reference files ([view source](source/skills/impeccable/))
15
- - **23 commands** to audit, review, polish, distill, animate, and more
16
- - **Curated anti-patterns** that explicitly tell the AI what NOT to do
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.
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.
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](source/skills/impeccable/SKILL.md)):
22
+ A comprehensive design skill with 7 domain-specific references ([view skill](skill/SKILL.src.md)):
23
23
 
24
24
  | Reference | Covers |
25
25
  |-----------|--------|
26
- | [typography](source/skills/impeccable/reference/typography.md) | Type systems, font pairing, modular scales, OpenType |
27
- | [color-and-contrast](source/skills/impeccable/reference/color-and-contrast.md) | OKLCH, tinted neutrals, dark mode, accessibility |
28
- | [spatial-design](source/skills/impeccable/reference/spatial-design.md) | Spacing systems, grids, visual hierarchy |
29
- | [motion-design](source/skills/impeccable/reference/motion-design.md) | Easing curves, staggering, reduced motion |
30
- | [interaction-design](source/skills/impeccable/reference/interaction-design.md) | Forms, focus states, loading patterns |
31
- | [responsive-design](source/skills/impeccable/reference/responsive-design.md) | Mobile-first, fluid design, container queries |
32
- | [ux-writing](source/skills/impeccable/reference/ux-writing.md) | Button labels, error messages, empty states |
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 |
33
33
 
34
34
  ### 23 Commands
35
35
 
@@ -38,8 +38,8 @@ All commands are accessed through `/impeccable`:
38
38
  | Command | What it does |
39
39
  |---------|--------------|
40
40
  | `/impeccable craft` | Full shape-then-build flow with visual iteration |
41
- | `/impeccable teach` | One-time setup: gather design context, write PRODUCT.md and DESIGN.md |
42
- | `/impeccable document` | Generate DESIGN.md from existing project code |
41
+ | `/impeccable init` | One-time setup: gather design context, write PRODUCT.md and DESIGN.md, configure live mode, recommend next steps |
42
+ | `/impeccable document` | Generate root DESIGN.md from existing project code |
43
43
  | `/impeccable extract` | Pull reusable components and tokens into the design system |
44
44
  | `/impeccable shape` | Plan UX/UI before writing code |
45
45
  | `/impeccable critique` | UX design review: hierarchy, clarity, emotional resonance |
@@ -93,11 +93,23 @@ Visit [impeccable.style](https://impeccable.style#casestudies) to see before/aft
93
93
 
94
94
  ## Installation
95
95
 
96
- ### Option 1: Download from Website (Recommended)
96
+ ### Option 1: CLI installer (Recommended)
97
+
98
+ From the root of your project, run:
99
+
100
+ ```bash
101
+ npx impeccable skills install
102
+ ```
103
+
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.
105
+
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.
107
+
108
+ ### Option 2: Download from Website
97
109
 
98
110
  Visit [impeccable.style](https://impeccable.style), download the ZIP for your tool, and extract to your project.
99
111
 
100
- ### Option 2: Copy from Repository
112
+ ### Option 3: Copy from Repository
101
113
 
102
114
  **Cursor:**
103
115
  ```bash
@@ -145,10 +157,14 @@ cp -r dist/gemini/.gemini your-project/
145
157
  ```bash
146
158
  # Project-local
147
159
  cp -r dist/agents/.agents your-project/
160
+ mkdir -p your-project/.codex
161
+ cp -r dist/codex/.codex/agents your-project/.codex/
148
162
 
149
163
  # Or user-wide
150
164
  mkdir -p ~/.agents/skills
151
165
  cp -r dist/agents/.agents/skills/* ~/.agents/skills/
166
+ mkdir -p ~/.codex
167
+ cp -r dist/codex/.codex/agents ~/.codex/
152
168
  ```
153
169
 
154
170
  **GitHub Copilot:**
@@ -180,24 +196,37 @@ cp -r dist/rovo-dev/.rovodev your-project/
180
196
  cp -r dist/rovo-dev/.rovodev/skills/* ~/.rovodev/skills/
181
197
  ```
182
198
 
199
+ **Qoder:**
200
+ ```bash
201
+ # Project-specific
202
+ cp -r dist/qoder/.qoder your-project/
203
+
204
+ # Or global (applies to all projects)
205
+ cp -r dist/qoder/.qoder/skills/* ~/.qoder/skills/
206
+ ```
207
+
183
208
  ## Usage
184
209
 
185
- Once installed, use commands in your AI harness:
210
+ Once installed, every command runs through the single `/impeccable` skill:
186
211
 
187
212
  ```
188
- /audit # Find issues
189
- /normalize # Fix inconsistencies
190
- /polish # Final cleanup
191
- /distill # Remove complexity
213
+ /impeccable audit # Find issues
214
+ /impeccable polish # Final cleanup
215
+ /impeccable distill # Remove complexity
216
+ /impeccable critique # Full design review
192
217
  ```
193
218
 
219
+ Type `/impeccable` alone to see the full command list.
220
+
194
221
  Most commands accept an optional argument to focus on a specific area:
195
222
 
196
223
  ```
197
- /audit header
198
- /polish checkout-form
224
+ /impeccable audit the header
225
+ /impeccable polish the checkout form
199
226
  ```
200
227
 
228
+ If you reach for one command often, pin it with `/impeccable pin audit` to get `/audit` as a standalone shortcut.
229
+
201
230
  **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.
202
231
 
203
232
  ## CLI
@@ -225,6 +254,15 @@ The detector catches 24 issues across AI slop (side-tab borders, purple gradient
225
254
  - [Kiro](https://kiro.dev)
226
255
  - [Trae](https://trae.ai)
227
256
  - [Rovo Dev](https://www.atlassian.com/software/rovo)
257
+ - [Qoder](https://qoder.com)
258
+
259
+ ## Community & Ecosystem
260
+
261
+ Join the community and ecosystem conversations:
262
+
263
+ - GitHub Discussions: file bugs, request features, and help newcomers.
264
+ - [Impeccable on npm](https://www.npmjs.com/package/impeccable): grab the CLI, follow releases, and star the package.
265
+ - Follow @pbakaus on Twitter for release notes, sample lint reports, and video highlights of new rules.
228
266
 
229
267
  ## Contributing
230
268
 
@@ -36,14 +36,14 @@ Run 'impeccable <command> --help' for command-specific options.`);
36
36
  }
37
37
 
38
38
  if (command === '--version' || command === '-v') {
39
- const pkg = JSON.parse(readFileSync(join(__dirname, '..', 'package.json'), 'utf8'));
39
+ const pkg = JSON.parse(readFileSync(join(__dirname, '..', '..', 'package.json'), 'utf8'));
40
40
  console.log(pkg.version);
41
41
  process.exit(0);
42
42
  }
43
43
 
44
44
  if (command === 'detect') {
45
45
  process.argv = [process.argv[0], process.argv[1], ...args.slice(1)];
46
- const { detectCli } = await import('../src/detect-antipatterns.mjs');
46
+ const { detectCli } = await import('../engine/detect-antipatterns.mjs');
47
47
  await detectCli();
48
48
  } else if (command === 'skills') {
49
49
  const { run } = await import('./commands/skills.mjs');
@@ -51,6 +51,6 @@ if (command === 'detect') {
51
51
  } else {
52
52
  // Default: treat as detect arguments (allow `npx impeccable src/` shorthand)
53
53
  process.argv = [process.argv[0], process.argv[1], ...args];
54
- const { detectCli } = await import('../src/detect-antipatterns.mjs');
54
+ const { detectCli } = await import('../engine/detect-antipatterns.mjs');
55
55
  await detectCli();
56
56
  }
@@ -3,7 +3,7 @@
3
3
  *
4
4
  * Usage:
5
5
  * impeccable skills help Show all available skills and commands
6
- * impeccable skills install Install skills via npx skills add
6
+ * impeccable skills install Install compiled skills from the universal bundle
7
7
  * impeccable skills update Update skills to latest version
8
8
  */
9
9
 
@@ -14,13 +14,30 @@ import { createInterface } from 'node:readline';
14
14
  import { fileURLToPath } from 'node:url';
15
15
  import { get } from 'node:https';
16
16
  import { createHash } from 'node:crypto';
17
- import { tmpdir } from 'node:os';
17
+ import { tmpdir, homedir } from 'node:os';
18
18
 
19
19
  const __dirname = dirname(fileURLToPath(import.meta.url));
20
20
  const API_BASE = 'https://impeccable.style';
21
21
 
22
22
  // Provider folder names in project roots
23
- const PROVIDER_DIRS = ['.claude', '.cursor', '.gemini', '.agents', '.github', '.kiro', '.opencode', '.pi', '.trae', '.trae-cn'];
23
+ const PROVIDER_DIRS = ['.claude', '.cursor', '.gemini', '.agents', '.github', '.kiro', '.opencode', '.pi', '.qoder', '.trae', '.trae-cn'];
24
+
25
+ // When a project has no harness folder yet, infer the target from globally
26
+ // installed harnesses (~/.claude, ~/.codex, ...). Codex reads skills from
27
+ // .agents/skills, so ~/.codex maps to the .agents bundle variant.
28
+ const GLOBAL_HARNESS_HINTS = [
29
+ { home: '.claude', provider: '.claude' },
30
+ { home: '.codex', provider: '.agents' },
31
+ { home: '.cursor', provider: '.cursor' },
32
+ { home: '.gemini', provider: '.gemini' },
33
+ { home: '.kiro', provider: '.kiro' },
34
+ { home: '.opencode', provider: '.opencode' },
35
+ { home: '.qoder', provider: '.qoder' },
36
+ ];
37
+
38
+ // Last-resort default when nothing is detected: Claude Code + the universal
39
+ // (.agents, also Codex) folder, which covers the most common setups.
40
+ const DEFAULT_TARGETS = ['.claude', '.agents'];
24
41
 
25
42
  function ask(question) {
26
43
  const rl = createInterface({ input: process.stdin, output: process.stdout });
@@ -112,7 +129,7 @@ async function downloadAndExtractBundle() {
112
129
  */
113
130
  function normalizeForHash(content) {
114
131
  return content
115
- .replace(/\.(claude|cursor|agents|github|gemini|codex|kiro|opencode|pi|trae|trae-cn|rovodev)\/skills\//g, '.PROVIDER/skills/')
132
+ .replace(/\.(claude|cursor|agents|github|gemini|codex|kiro|opencode|pi|qoder|trae|trae-cn|rovodev)\/skills\//g, '.PROVIDER/skills/')
116
133
  .replace(/^version:\s*.+$/m, 'version: NORMALIZED');
117
134
  }
118
135
 
@@ -321,10 +338,71 @@ function renameSkillsWithPrefix(root, prefix) {
321
338
  return count;
322
339
  }
323
340
 
341
+ /**
342
+ * Decide which provider folders to install into.
343
+ * 1. An explicit --providers=.claude,.cursor list wins.
344
+ * 2. Otherwise, harness folders already present in the project.
345
+ * 3. Otherwise, infer from globally installed harnesses (~/.claude, ~/.codex).
346
+ * 4. Otherwise, a sensible default (.claude + .agents).
347
+ */
348
+ function resolveInstallTargets(root, providersValue) {
349
+ if (providersValue) {
350
+ const wanted = providersValue
351
+ .split(',')
352
+ .map(s => s.trim())
353
+ .filter(Boolean)
354
+ .map(s => (s.startsWith('.') ? s : `.${s}`))
355
+ .filter(p => PROVIDER_DIRS.includes(p));
356
+ return [...new Set(wanted)];
357
+ }
358
+
359
+ const inProject = PROVIDER_DIRS.filter(d => existsSync(join(root, d)));
360
+ if (inProject.length > 0) return inProject;
361
+
362
+ const home = homedir();
363
+ const inferred = [];
364
+ for (const { home: h, provider } of GLOBAL_HARNESS_HINTS) {
365
+ if (existsSync(join(home, h)) && !inferred.includes(provider)) inferred.push(provider);
366
+ }
367
+ if (inferred.length > 0) return inferred;
368
+
369
+ return [...DEFAULT_TARGETS];
370
+ }
371
+
372
+ /**
373
+ * Copy each target provider's compiled skill variant from an extracted bundle
374
+ * into the project. Writes real directories (copy, never symlink) so every
375
+ * harness keeps the build that was compiled for it. Returns skills written.
376
+ */
377
+ function copyProviderSkills(bundleDir, root, targets) {
378
+ let written = 0;
379
+ for (const provider of targets) {
380
+ const srcDir = join(bundleDir, provider, 'skills');
381
+ if (!existsSync(srcDir)) continue;
382
+ const localSkillsDir = join(root, provider, 'skills');
383
+ // A previous `npx skills` install may have left this provider's skills dir
384
+ // as a symlink to another provider's canonical copy. Drop the link so we
385
+ // write a real, provider-specific directory instead of writing through it.
386
+ try {
387
+ if (lstatSync(localSkillsDir).isSymbolicLink()) unlinkSync(localSkillsDir);
388
+ } catch {}
389
+ for (const skill of readdirSync(srcDir, { withFileTypes: true })) {
390
+ if (!skill.isDirectory()) continue;
391
+ const src = join(srcDir, skill.name);
392
+ const dest = join(localSkillsDir, skill.name);
393
+ rmSync(dest, { recursive: true, force: true });
394
+ copyDirSync(src, dest);
395
+ written++;
396
+ }
397
+ }
398
+ return written;
399
+ }
400
+
324
401
  async function install(flags) {
325
402
  const force = flags.includes('--force');
326
403
  const yes = flags.includes('-y') || flags.includes('--yes');
327
404
  const prefixFlag = flags.find(f => f.startsWith('--prefix='));
405
+ const providersFlag = flags.find(f => f.startsWith('--providers='));
328
406
  const root = findProjectRoot();
329
407
  const existing = isAlreadyInstalled(root);
330
408
 
@@ -334,12 +412,51 @@ async function install(flags) {
334
412
  process.exit(0);
335
413
  }
336
414
 
337
- console.log('Installing impeccable skills via npx skills...\n');
415
+ // Decide which harness folders to install into, then copy each harness's own
416
+ // compiled variant from the universal bundle. We deliberately do NOT shell out
417
+ // to `npx skills add`: its name-based discovery can install the uncompiled
418
+ // source, and its symlink default points every harness at one shared variant.
419
+ // Copying per-provider variants is the only correct install for this skill.
420
+ const targets = resolveInstallTargets(root, providersFlag ? providersFlag.split('=')[1] : null);
421
+ if (targets.length === 0) {
422
+ console.error('Could not determine a target harness folder.');
423
+ console.error('Pass one explicitly, e.g. --providers=.claude,.cursor');
424
+ process.exit(1);
425
+ }
426
+
427
+ if (!yes) {
428
+ console.log(`Target harness folder(s): ${targets.join(', ')}`);
429
+ const ans = await ask(`Install impeccable skills into ${targets.length} folder(s)? (Y/n) `);
430
+ if (ans === 'n' || ans === 'no') {
431
+ console.log('Aborted. Re-run with --providers=<dirs> to choose explicitly (e.g. --providers=.claude,.cursor).');
432
+ process.exit(0);
433
+ }
434
+ }
435
+
436
+ console.log('\nDownloading impeccable skills...');
437
+ let bundleDir;
438
+ try {
439
+ bundleDir = await downloadAndExtractBundle();
440
+ } catch (e) {
441
+ console.error(`Download failed: ${e.message}`);
442
+ process.exit(1);
443
+ }
444
+
445
+ let written = 0;
338
446
  try {
339
- execSync(`npx skills add pbakaus/impeccable${yes ? ' -y' : ''}`, { stdio: 'inherit' });
447
+ written = copyProviderSkills(bundleDir, root, targets);
340
448
  } catch (e) {
341
- process.exit(e.status ?? 1);
449
+ rmSync(bundleDir, { recursive: true, force: true });
450
+ console.error(`Install failed: ${e.message}`);
451
+ process.exit(1);
452
+ }
453
+ rmSync(bundleDir, { recursive: true, force: true });
454
+
455
+ if (written === 0) {
456
+ console.error(`Nothing was installed: the bundle had no variants for ${targets.join(', ')}.`);
457
+ process.exit(1);
342
458
  }
459
+ console.log(`Installed impeccable into: ${targets.join(', ')}`);
343
460
 
344
461
  // Ask about prefixing (skip in CI mode unless --prefix= is set)
345
462
  let prefix = '';
@@ -364,7 +481,7 @@ async function install(flags) {
364
481
 
365
482
  // Clean up deprecated skills from previous versions
366
483
  try {
367
- const { cleanup } = await import('../../source/skills/impeccable/scripts/cleanup-deprecated.mjs');
484
+ const { cleanup } = await import('../../../skill/scripts/cleanup-deprecated.mjs');
368
485
  const result = cleanup(root);
369
486
  const total = result.deletedPaths.length + result.removedLockEntries.length;
370
487
  if (total > 0) {
@@ -374,7 +491,7 @@ async function install(flags) {
374
491
  // Cleanup script not available -- skip
375
492
  }
376
493
 
377
- console.log(`\nDone! Run /${prefix}impeccable teach in your AI harness to set up design context.\n`);
494
+ console.log(`\nDone! Run /${prefix}impeccable init in your AI harness to set up design context.\n`);
378
495
  }
379
496
 
380
497
  /** Detect prefix by looking for the 'impeccable' skill (or legacy 'teach-impeccable') */
@@ -513,7 +630,7 @@ async function update(flags = []) {
513
630
 
514
631
  // Clean up deprecated skills from previous versions.
515
632
  try {
516
- const { cleanup } = await import('../../source/skills/impeccable/scripts/cleanup-deprecated.mjs');
633
+ const { cleanup } = await import('../../../skill/scripts/cleanup-deprecated.mjs');
517
634
  const root = findProjectRoot();
518
635
  const result = cleanup(root);
519
636
  const total = result.deletedPaths.length + result.removedLockEntries.length;
@@ -598,7 +715,7 @@ async function update(flags = []) {
598
715
 
599
716
  // Run cleanup to remove deprecated stubs from the fresh download
600
717
  try {
601
- const { cleanup: postCleanup } = await import('../../source/skills/impeccable/scripts/cleanup-deprecated.mjs');
718
+ const { cleanup: postCleanup } = await import('../../../skill/scripts/cleanup-deprecated.mjs');
602
719
  postCleanup(root);
603
720
  } catch {
604
721
  // Not available -- skip