impeccable 3.0.1 → 3.0.2

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.
@@ -425,6 +425,35 @@ const ANTIPATTERNS = [
425
425
  skillSection: 'Layout & Space',
426
426
  skillGuideline: 'overflow container clipping positioned children',
427
427
  },
428
+ {
429
+ id: 'design-system-font',
430
+ category: 'quality',
431
+ name: 'Font outside DESIGN.md',
432
+ description:
433
+ 'A font is used that is not declared in DESIGN.md typography. Use the documented type system or update DESIGN.md if this is an intentional brand addition.',
434
+ skillSection: 'Typography',
435
+ skillGuideline: 'font family outside the project design system',
436
+ },
437
+ {
438
+ id: 'design-system-color',
439
+ category: 'quality',
440
+ severity: 'advisory',
441
+ name: 'Color outside DESIGN.md',
442
+ description:
443
+ 'A literal color is outside the DESIGN.md palette and sidecar tonal ramps. This may be legitimate, but it should be an intentional design-system addition rather than drift.',
444
+ skillSection: 'Color & Contrast',
445
+ skillGuideline: 'literal color outside the project design system',
446
+ },
447
+ {
448
+ id: 'design-system-radius',
449
+ category: 'quality',
450
+ severity: 'advisory',
451
+ name: 'Radius outside DESIGN.md',
452
+ description:
453
+ 'A border-radius value is outside the DESIGN.md rounded scale. Use a documented radius token or update the design system if the new shape is intentional.',
454
+ skillSection: 'Visual Details',
455
+ skillGuideline: 'border radius outside the project design system',
456
+ },
428
457
 
429
458
  // ── Provider tells: opt-in via --gpt / --gemini (gated off by default) ──
430
459
  {
@@ -4394,6 +4423,7 @@ if (IS_BROWSER) {
4394
4423
  category: ap ? ap.category : 'quality',
4395
4424
  severity: ap?.severity || 'warning',
4396
4425
  detail: f.detail || f.snippet,
4426
+ ignoreValue: f.ignoreValue || f.value || '',
4397
4427
  name: ap ? ap.name : (f.type || f.id),
4398
4428
  description: ap ? ap.description : '',
4399
4429
  };
@@ -4430,10 +4460,203 @@ if (IS_BROWSER) {
4430
4460
  return [...groupMap.entries()].map(([el, findings]) => ({ el, findings }));
4431
4461
  }
4432
4462
 
4463
+ const DESIGN_COLOR_TOLERANCE = 6;
4464
+ const DESIGN_RADIUS_TOLERANCE_PX = 0.5;
4465
+ const DESIGN_SKIP_TAGS = new Set(['head', 'title', 'meta', 'link', 'style', 'script', 'noscript', 'template', 'source']);
4466
+
4467
+ function normalizeBrowserFontName(value) {
4468
+ return String(value || '')
4469
+ .trim()
4470
+ .replace(/^["']|["']$/g, '')
4471
+ .replace(/\+/g, ' ')
4472
+ .replace(/\s+/g, ' ')
4473
+ .toLowerCase();
4474
+ }
4475
+
4476
+ function browserPrimaryFont(stack) {
4477
+ if (!stack || /var\(/i.test(stack)) return '';
4478
+ return String(stack || '')
4479
+ .split(',')
4480
+ .map(normalizeBrowserFontName)
4481
+ .find(font => font && !GENERIC_FONTS.has(font)) || '';
4482
+ }
4483
+
4484
+ function browserDesignSystemConfig() {
4485
+ const raw = window.__IMPECCABLE_CONFIG__?.designSystem;
4486
+ if (!raw?.present) return null;
4487
+ const allowedFonts = new Set((raw.allowedFonts || []).map(normalizeBrowserFontName).filter(Boolean));
4488
+ const allowedColors = (raw.allowedColors || [])
4489
+ .filter(color => color && Number.isFinite(color.r) && Number.isFinite(color.g) && Number.isFinite(color.b))
4490
+ .map(color => ({ r: color.r, g: color.g, b: color.b }));
4491
+ const allowedRadii = (raw.allowedRadii || [])
4492
+ .map(Number)
4493
+ .filter(px => Number.isFinite(px));
4494
+ return {
4495
+ present: true,
4496
+ hasFonts: raw.hasFonts === true && allowedFonts.size > 0,
4497
+ allowedFonts,
4498
+ hasColors: raw.hasColors === true && allowedColors.length > 0,
4499
+ allowedColors,
4500
+ hasRadii: raw.hasRadii === true && allowedRadii.length > 0,
4501
+ allowedRadii,
4502
+ hasPillRadius: raw.hasPillRadius === true,
4503
+ };
4504
+ }
4505
+
4506
+ function browserColorsClose(a, b) {
4507
+ if (!a || !b) return false;
4508
+ return Math.max(
4509
+ Math.abs(a.r - b.r),
4510
+ Math.abs(a.g - b.g),
4511
+ Math.abs(a.b - b.b),
4512
+ ) <= DESIGN_COLOR_TOLERANCE;
4513
+ }
4514
+
4515
+ function isBrowserDesignColorAllowed(raw, designSystem) {
4516
+ if (!designSystem?.hasColors) return true;
4517
+ const text = String(raw || '').trim().toLowerCase();
4518
+ if (!text || text === 'transparent' || text === 'currentcolor' || text === 'inherit' || text === 'initial') return true;
4519
+ if (text.includes('var(')) return true;
4520
+ const parsed = parseAnyColor(text);
4521
+ if (!parsed) return true;
4522
+ if ((parsed.a ?? 1) <= 0.05) return true;
4523
+ return designSystem.allowedColors.some(color => browserColorsClose(parsed, color));
4524
+ }
4525
+
4526
+ function isBrowserTransparentCss(value) {
4527
+ const text = String(value || '').trim().toLowerCase();
4528
+ if (!text || text === 'transparent') return true;
4529
+ const parsed = parseAnyColor(text);
4530
+ return parsed ? (parsed.a ?? 1) <= 0.05 : false;
4531
+ }
4532
+
4533
+ function isBrowserDesignRadiusAllowed(raw, designSystem) {
4534
+ if (!designSystem?.hasRadii) return true;
4535
+ const text = String(raw || '').trim().toLowerCase();
4536
+ if (!text || text === '0' || text === 'none' || text === 'initial' || text === 'inherit') return true;
4537
+ if (text.includes('var(') || text.includes('%')) return true;
4538
+ const px = resolveLengthPx(text, 16);
4539
+ if (px == null || !Number.isFinite(px) || px <= DESIGN_RADIUS_TOLERANCE_PX) return true;
4540
+ if (designSystem.hasPillRadius && px >= 99) return true;
4541
+ return designSystem.allowedRadii.some(allowed => Math.abs(allowed - px) <= DESIGN_RADIUS_TOLERANCE_PX);
4542
+ }
4543
+
4544
+ function browserRadiusTokens(value) {
4545
+ return String(value || '')
4546
+ .replace(/\s*\/\s*/g, ' ')
4547
+ .split(/\s+/)
4548
+ .map(token => token.trim())
4549
+ .filter(Boolean);
4550
+ }
4551
+
4552
+ function browserHasDirectText(el) {
4553
+ return [...(el.childNodes || [])].some(node => node.nodeType === 3 && node.textContent.trim().length > 0);
4554
+ }
4555
+
4556
+ function browserSampleText(el) {
4557
+ const text = String(el.textContent || '').replace(/\s+/g, ' ').trim();
4558
+ return text ? ` "${text.slice(0, 40)}"` : '';
4559
+ }
4560
+
4561
+ function shouldSkipDesignElement(el) {
4562
+ const tag = el.tagName?.toLowerCase?.() || '';
4563
+ return DESIGN_SKIP_TAGS.has(tag) || isElementHidden(el);
4564
+ }
4565
+
4566
+ function checkElementDesignSystemDOM(el, designSystem, seen) {
4567
+ if (!designSystem?.present || shouldSkipDesignElement(el)) return [];
4568
+ const findings = [];
4569
+ const tag = el.tagName?.toLowerCase?.() || 'unknown';
4570
+ const style = getComputedStyle(el);
4571
+
4572
+ if (designSystem.hasFonts && browserHasDirectText(el)) {
4573
+ const font = browserPrimaryFont(style.fontFamily || '');
4574
+ if (font && !designSystem.allowedFonts.has(font) && !seen.fonts.has(font)) {
4575
+ seen.fonts.add(font);
4576
+ findings.push({
4577
+ type: 'design-system-font',
4578
+ detail: `${tag}${browserSampleText(el)} uses ${font}; not declared in DESIGN.md typography`,
4579
+ ignoreValue: font,
4580
+ });
4581
+ }
4582
+ }
4583
+
4584
+ if (designSystem.hasColors) {
4585
+ const colorChecks = [];
4586
+ if (browserHasDirectText(el)) colorChecks.push(['text color', style.color]);
4587
+ if (!isBrowserTransparentCss(style.backgroundColor)) colorChecks.push(['background', style.backgroundColor]);
4588
+ for (const side of ['Top', 'Right', 'Bottom', 'Left']) {
4589
+ if ((parseFloat(style[`border${side}Width`]) || 0) > 0) {
4590
+ colorChecks.push([`border-${side.toLowerCase()}`, style[`border${side}Color`]]);
4591
+ }
4592
+ }
4593
+ if ((parseFloat(style.outlineWidth) || 0) > 0) colorChecks.push(['outline', style.outlineColor]);
4594
+
4595
+ for (const [kind, raw] of colorChecks) {
4596
+ const label = String(raw || '').trim().replace(/\s+/g, ' ');
4597
+ if (isBrowserDesignColorAllowed(label, designSystem)) continue;
4598
+ const key = `${kind}:${label}`;
4599
+ if (seen.colors.has(key)) continue;
4600
+ seen.colors.add(key);
4601
+ findings.push({
4602
+ type: 'design-system-color',
4603
+ detail: `${kind} ${label} on ${tag}${browserSampleText(el)} is outside DESIGN.md colors`,
4604
+ ignoreValue: label,
4605
+ });
4606
+ }
4607
+ }
4608
+
4609
+ if (designSystem.hasRadii) {
4610
+ for (const token of browserRadiusTokens(style.borderRadius || '')) {
4611
+ if (isBrowserDesignRadiusAllowed(token, designSystem)) continue;
4612
+ if (seen.radii.has(token)) continue;
4613
+ seen.radii.add(token);
4614
+ findings.push({
4615
+ type: 'design-system-radius',
4616
+ detail: `border-radius ${token} on ${tag}${browserSampleText(el)} is outside the DESIGN.md rounded scale`,
4617
+ ignoreValue: token,
4618
+ });
4619
+ }
4620
+ }
4621
+
4622
+ return findings;
4623
+ }
4624
+
4625
+ function decodeBrowserGoogleFamily(value) {
4626
+ const family = String(value || '').split(':')[0].replace(/\+/g, ' ');
4627
+ try {
4628
+ return decodeURIComponent(family);
4629
+ } catch {
4630
+ return family;
4631
+ }
4632
+ }
4633
+
4634
+ function checkBrowserDesignSystemSources(designSystem, seen) {
4635
+ if (!designSystem?.hasFonts) return [];
4636
+ const findings = [];
4637
+ for (const link of document.querySelectorAll('link[href*="fonts.googleapis.com/css"]')) {
4638
+ const href = link.getAttribute('href') || '';
4639
+ for (const match of href.matchAll(/[?&]family=([^&]+)/g)) {
4640
+ const display = decodeBrowserGoogleFamily(match[1]);
4641
+ const font = normalizeBrowserFontName(display);
4642
+ if (!font || designSystem.allowedFonts.has(font) || seen.fonts.has(font)) continue;
4643
+ seen.fonts.add(font);
4644
+ findings.push({
4645
+ type: 'design-system-font',
4646
+ detail: `Google Fonts: ${display} is not declared in DESIGN.md typography`,
4647
+ ignoreValue: display,
4648
+ });
4649
+ }
4650
+ }
4651
+ return findings;
4652
+ }
4653
+
4433
4654
  function collectBrowserFindings() {
4434
4655
  const groupMap = new Map();
4435
4656
  const _disabled = EXTENSION_MODE ? (window.__IMPECCABLE_CONFIG__?.disabledRules || []) : [];
4436
4657
  const _ruleOk = (id) => !_disabled.length || !_disabled.includes(id);
4658
+ const designSystem = browserDesignSystemConfig();
4659
+ const designSeen = { fonts: new Set(), colors: new Set(), radii: new Set() };
4437
4660
  // Note: provider-gated rules (--gpt / --gemini) are NOT filtered here. In a
4438
4661
  // real browser env (detector page, live overlay, extension) running every
4439
4662
  // check is free, so we always surface them; the gating is purely a CLI
@@ -4464,6 +4687,7 @@ if (IS_BROWSER) {
4464
4687
  ...checkElementClippedOverflowDOM(el).map(f => ({ type: f.id, detail: f.snippet })),
4465
4688
  ...checkElementGptBorderShadowDOM(el).map(f => ({ type: f.id, detail: f.snippet })),
4466
4689
  ...checkElementTextOverflowDOM(el).map(f => ({ type: f.id, detail: f.snippet })),
4690
+ ...checkElementDesignSystemDOM(el, designSystem, designSeen),
4467
4691
  ].filter(f => _ruleOk(f.type));
4468
4692
 
4469
4693
  addBrowserFindings(groupMap, el, findings);
@@ -4480,6 +4704,13 @@ if (IS_BROWSER) {
4480
4704
 
4481
4705
  const pageLevelFindings = [];
4482
4706
 
4707
+ const designSourceFindings = checkBrowserDesignSystemSources(designSystem, designSeen)
4708
+ .filter(f => _ruleOk(f.type));
4709
+ if (designSourceFindings.length > 0) {
4710
+ pageLevelFindings.push(...designSourceFindings);
4711
+ addBrowserFindings(groupMap, document.body, designSourceFindings);
4712
+ }
4713
+
4483
4714
  const typoFindings = checkTypography().filter(f => _ruleOk(f.type));
4484
4715
  if (typoFindings.length > 0) {
4485
4716
  pageLevelFindings.push(...typoFindings);
@@ -23,6 +23,13 @@ export {
23
23
  checkHtmlPatterns,
24
24
  } from './rules/checks.mjs';
25
25
  export { createDetectorProfile, summarizeDetectorProfile } from './profile/profiler.mjs';
26
+ export {
27
+ parseFrontmatter as parseDesignFrontmatter,
28
+ normalizeDesignSystem,
29
+ loadDesignSystemForCwd,
30
+ checkSourceDesignSystem,
31
+ collectStaticDesignSystemFindings,
32
+ } from './design-system.mjs';
26
33
  export { detectHtml } from './engines/static-html/detect-html.mjs';
27
34
  export { detectUrl, createBrowserDetector } from './engines/browser/detect-url.mjs';
28
35
  export { detectText, extractStyleBlocks, extractCSSinJS } from './engines/regex/detect-text.mjs';
@@ -7,6 +7,25 @@ import { filterByProviders } from '../../registry/antipatterns.mjs';
7
7
  import { profileFindingsAsync, profileStep, profileStepAsync } from '../../profile/profiler.mjs';
8
8
  import { captureVisualContrastCandidate } from '../visual/screenshot-contrast.mjs';
9
9
 
10
+ function serializeDesignSystemForBrowser(designSystem) {
11
+ if (!designSystem?.present) return null;
12
+ return {
13
+ present: true,
14
+ hasFonts: designSystem.hasFonts === true,
15
+ allowedFonts: Array.from(designSystem.allowedFonts || []),
16
+ hasColors: designSystem.hasColors === true,
17
+ allowedColors: Array.from(designSystem.allowedColorKeys?.values?.() || [])
18
+ .map(entry => entry?.color)
19
+ .filter(color => color && Number.isFinite(color.r) && Number.isFinite(color.g) && Number.isFinite(color.b))
20
+ .map(color => ({ r: color.r, g: color.g, b: color.b })),
21
+ hasRadii: designSystem.hasRadii === true,
22
+ allowedRadii: (designSystem.allowedRadii || [])
23
+ .map(entry => Number(entry?.px))
24
+ .filter(px => Number.isFinite(px)),
25
+ hasPillRadius: designSystem.hasPillRadius === true,
26
+ };
27
+ }
28
+
10
29
  async function runVisualContrastFallback(page, serializedGroups, options, profile, target) {
11
30
  if (options?.visualContrast === false) return [];
12
31
  const maxCandidates = Number.isFinite(options?.visualContrastMaxCandidates)
@@ -163,17 +182,19 @@ async function detectUrl(url, options = {}) {
163
182
  }
164
183
 
165
184
  // Inject the browser detection script and collect results
185
+ const browserDesignSystem = serializeDesignSystemForBrowser(options?.designSystem);
166
186
  await profileStepAsync(profile, {
167
187
  engine: 'browser',
168
188
  phase: 'scan',
169
189
  ruleId: 'configure-pure-detect',
170
190
  target: url,
171
- }, () => page.evaluate(() => {
191
+ }, () => page.evaluate((designSystem) => {
172
192
  window.__IMPECCABLE_CONFIG__ = {
173
193
  ...(window.__IMPECCABLE_CONFIG__ || {}),
174
194
  autoScan: false,
195
+ ...(designSystem ? { designSystem } : {}),
175
196
  };
176
- }));
197
+ }, browserDesignSystem));
177
198
  await profileStepAsync(profile, {
178
199
  engine: 'browser',
179
200
  phase: 'scan',
@@ -192,7 +213,7 @@ async function detectUrl(url, options = {}) {
192
213
  return window.impeccableDetect({ decorate: false, serialize: true });
193
214
  });
194
215
  return serializedGroups.flatMap(({ findings }) =>
195
- findings.map(f => ({ id: f.type, snippet: f.detail }))
216
+ findings.map(f => ({ id: f.type, snippet: f.detail, ignoreValue: f.ignoreValue || '' }))
196
217
  );
197
218
  });
198
219
  const visualFindings = await runVisualContrastFallback(page, serializedGroups, options, profile, url);
@@ -213,7 +234,11 @@ async function detectUrl(url, options = {}) {
213
234
  }, () => browser.close());
214
235
  }
215
236
  }
216
- return filterByProviders(results.map(f => finding(f.id, url, f.snippet)), options.providers);
237
+ return filterByProviders(results.map(f => {
238
+ const item = finding(f.id, url, f.snippet);
239
+ if (f.ignoreValue) item.ignoreValue = f.ignoreValue;
240
+ return item;
241
+ }), options.providers);
217
242
  }
218
243
 
219
244
  async function createBrowserDetector(options = {}) {
@@ -1,4 +1,5 @@
1
1
  import { GENERIC_FONTS } from '../../shared/constants.mjs';
2
+ import { checkSourceDesignSystem } from '../../design-system.mjs';
2
3
  import { isFullPage } from '../../shared/page.mjs';
3
4
  import { finding } from '../../findings.mjs';
4
5
  import { filterByProviders } from '../../registry/antipatterns.mjs';
@@ -503,6 +504,15 @@ function detectText(content, filePath, options = {}) {
503
504
  }));
504
505
  }
505
506
 
507
+ if (options?.designSystem) {
508
+ findings.push(...profileFindings(profile, {
509
+ engine: 'regex',
510
+ phase: 'source',
511
+ ruleId: 'design-system',
512
+ target: filePath,
513
+ }, () => checkSourceDesignSystem(content, filePath, { designSystem: options.designSystem })));
514
+ }
515
+
506
516
  // Deduplicate findings (same antipattern + similar snippet, within 2 lines)
507
517
  const deduped = [];
508
518
  for (const f of findings) {
@@ -272,6 +272,7 @@ const STATIC_DEFAULT_STYLE = {
272
272
  marginBottom: '0px',
273
273
  marginLeft: '0px',
274
274
  position: 'static',
275
+ visibility: 'visible',
275
276
  top: 'auto',
276
277
  right: 'auto',
277
278
  bottom: 'auto',
@@ -326,6 +327,7 @@ const STATIC_PROP_MAP = {
326
327
  'margin-bottom': 'marginBottom',
327
328
  'margin-left': 'marginLeft',
328
329
  'position': 'position',
330
+ 'visibility': 'visibility',
329
331
  'top': 'top',
330
332
  'right': 'right',
331
333
  'bottom': 'bottom',
@@ -2,6 +2,11 @@ import fs from 'node:fs';
2
2
  import path from 'node:path';
3
3
 
4
4
  import { GENERIC_FONTS, OVERUSED_FONTS } from '../../shared/constants.mjs';
5
+ import {
6
+ checkSourceDesignSystem,
7
+ collectStaticDesignSystemFindings,
8
+ mergeDesignSystemFindings,
9
+ } from '../../design-system.mjs';
5
10
  import { isFullPage } from '../../shared/page.mjs';
6
11
  import { finding } from '../../findings.mjs';
7
12
  import { profileFindings, profileStep, profileStepAsync } from '../../profile/profiler.mjs';
@@ -168,6 +173,22 @@ async function detectHtml(filePath, options = {}) {
168
173
  }
169
174
  }
170
175
 
176
+ if (options?.designSystem) {
177
+ const sourceDesignFindings = profileFindings(profile, {
178
+ engine: 'static-html',
179
+ phase: 'source',
180
+ ruleId: 'design-system',
181
+ target: filePath,
182
+ }, () => checkSourceDesignSystem(html, filePath, { designSystem: options.designSystem }));
183
+ const staticDesignFindings = profileFindings(profile, {
184
+ engine: 'static-html',
185
+ phase: 'page',
186
+ ruleId: 'design-system',
187
+ target: filePath,
188
+ }, () => collectStaticDesignSystemFindings(document, window, filePath, options.designSystem));
189
+ findings.push(...mergeDesignSystemFindings(staticDesignFindings, sourceDesignFindings));
190
+ }
191
+
171
192
  if (isFullPage(html)) {
172
193
  const runPageCheck = (ruleId, callback) => profile
173
194
  ? profileFindings(profile, { engine: 'static-html', phase: 'page', ruleId, target: filePath }, callback)
@@ -323,6 +323,35 @@ const ANTIPATTERNS = [
323
323
  skillSection: 'Layout & Space',
324
324
  skillGuideline: 'overflow container clipping positioned children',
325
325
  },
326
+ {
327
+ id: 'design-system-font',
328
+ category: 'quality',
329
+ name: 'Font outside DESIGN.md',
330
+ description:
331
+ 'A font is used that is not declared in DESIGN.md typography. Use the documented type system or update DESIGN.md if this is an intentional brand addition.',
332
+ skillSection: 'Typography',
333
+ skillGuideline: 'font family outside the project design system',
334
+ },
335
+ {
336
+ id: 'design-system-color',
337
+ category: 'quality',
338
+ severity: 'advisory',
339
+ name: 'Color outside DESIGN.md',
340
+ description:
341
+ 'A literal color is outside the DESIGN.md palette and sidecar tonal ramps. This may be legitimate, but it should be an intentional design-system addition rather than drift.',
342
+ skillSection: 'Color & Contrast',
343
+ skillGuideline: 'literal color outside the project design system',
344
+ },
345
+ {
346
+ id: 'design-system-radius',
347
+ category: 'quality',
348
+ severity: 'advisory',
349
+ name: 'Radius outside DESIGN.md',
350
+ description:
351
+ 'A border-radius value is outside the DESIGN.md rounded scale. Use a documented radius token or update the design system if the new shape is intentional.',
352
+ skillSection: 'Visual Details',
353
+ skillGuideline: 'border radius outside the project design system',
354
+ },
326
355
 
327
356
  // ── Provider tells: opt-in via --gpt / --gemini (gated off by default) ──
328
357
  {