impeccable 3.2.1 → 3.3.1

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.
@@ -2,7 +2,7 @@ import fs from 'node:fs';
2
2
  import path from 'node:path';
3
3
 
4
4
  import { profileStep, recordProfileEvent } from '../../profile/profiler.mjs';
5
- import { parseAnyColor, resolveLengthPx, resolveVarRefs } from '../../rules/checks.mjs';
5
+ import { collectCssCustomProps, cssLengthToPx, parseAnyColor, resolveLengthPx, resolveVarRefs } from '../../rules/checks.mjs';
6
6
 
7
7
  // ---------------------------------------------------------------------------
8
8
  // jsdom CSS-variable border override map
@@ -245,6 +245,10 @@ const STATIC_DEFAULT_STYLE = {
245
245
  outlineColor: 'rgb(0, 0, 0)',
246
246
  outlineStyle: 'none',
247
247
  boxShadow: 'none',
248
+ // NOT in STATIC_INHERITED_PROPS even though text-shadow inherits in real
249
+ // CSS: the glow check only needs to fire once, on the element that
250
+ // declares the shadow, not on every descendant.
251
+ textShadow: 'none',
248
252
  fontFamily: '',
249
253
  fontSize: '16px',
250
254
  fontStyle: 'normal',
@@ -302,6 +306,7 @@ const STATIC_PROP_MAP = {
302
306
  'outline-color': 'outlineColor',
303
307
  'outline-style': 'outlineStyle',
304
308
  'box-shadow': 'boxShadow',
309
+ 'text-shadow': 'textShadow',
305
310
  'font-family': 'fontFamily',
306
311
  'font-size': 'fontSize',
307
312
  'font-style': 'fontStyle',
@@ -420,6 +425,22 @@ function extractStaticColor(value) {
420
425
  if (!value) return '';
421
426
  const raw = String(value).trim();
422
427
  if (/^var\(/i.test(raw)) return raw;
428
+ // color-mix(...) needs balanced-paren capture (its arguments regularly
429
+ // contain nested var()/oklch() calls AND the keyword `transparent`, which
430
+ // the flat regex below would otherwise pluck out of the middle of the
431
+ // expression and report as the whole color).
432
+ const mixStart = raw.search(/color-mix\(/i);
433
+ if (mixStart !== -1) {
434
+ let depth = 0;
435
+ for (let i = raw.indexOf('(', mixStart); i < raw.length; i++) {
436
+ if (raw[i] === '(') depth++;
437
+ else if (raw[i] === ')') {
438
+ depth--;
439
+ if (depth === 0) return raw.slice(mixStart, i + 1);
440
+ }
441
+ }
442
+ return '';
443
+ }
423
444
  const colorLike = raw.match(/(?:rgba?\([^)]+\)|oklch\([^)]+\)|oklab\([^)]+\)|lch\([^)]+\)|lab\([^)]+\)|hsla?\([^)]+\)|hwb\([^)]+\)|#[0-9a-f]{3,8}\b|\b(?:black|white|gray|grey|silver|red|green|blue|transparent)\b)/i);
424
445
  if (!colorLike) return '';
425
446
  return colorLike[0];
@@ -532,6 +553,15 @@ function expandStaticDeclaration(prop, value) {
532
553
  const beforeImage = hasImage ? v.split(/(?:repeating-)?(?:linear|radial|conic)-gradient\(|url\(/i)[0] : v;
533
554
  const color = extractStaticColor(hasImage ? beforeImage : v);
534
555
  if (color) out.push(['backgroundColor', color]);
556
+ // The `background` shorthand resets every longhand it does not set.
557
+ // Without this, `pre code { background: none }` leaves an earlier
558
+ // `background: var(--surface)` color standing and the contrast checks
559
+ // measure text against a surface the browser never paints. var() values
560
+ // stay untouched: they may resolve to a color later in the pipeline.
561
+ if (!color && !hasImage && !/var\(/i.test(v)) {
562
+ out.push(['backgroundColor', 'rgba(0, 0, 0, 0)']);
563
+ out.push(['backgroundImage', 'none']);
564
+ }
535
565
  return out;
536
566
  }
537
567
  if (p === 'border') {
@@ -702,7 +732,20 @@ function collectStaticCssRules(cssText, csstree) {
702
732
  });
703
733
  });
704
734
  for (const selector of splitCssList(selectorText)) {
705
- if (selector) rules.push({ selector, declarations, specificity: staticSpecificity(selector), order: order++ });
735
+ if (!selector) continue;
736
+ // :hover rules can't be matched statically as-is (no interaction
737
+ // state), but they carry real cascade weight while hovered. Tag
738
+ // them and record a state-stripped selector so the hover pass can
739
+ // find their targets; specificity stays computed from the ORIGINAL
740
+ // selector (per CSS, :hover counts as a class).
741
+ const isHover = /:hover\b/i.test(selector);
742
+ let matchSelector = null;
743
+ if (isHover) {
744
+ matchSelector = selector.replace(/:hover\b/gi, '').trim();
745
+ if (!matchSelector || /[>+~]\s*$/.test(matchSelector)) matchSelector = null;
746
+ else matchSelector = matchSelector.replace(/(^|[\s>+~])(?=$|[\s>+~])/g, '$1*');
747
+ }
748
+ rules.push({ selector, declarations, specificity: staticSpecificity(selector), order: order++, isHover, matchSelector });
706
749
  }
707
750
  return;
708
751
  }
@@ -805,6 +848,13 @@ class StaticDocument {
805
848
  this.domutils = modules.domutils;
806
849
  this._wrappers = new WeakMap();
807
850
  this._styleMap = new WeakMap();
851
+ this._hoverStyleMap = new WeakMap();
852
+ this._accentDashPseudo = new WeakSet();
853
+ // Elements whose ::before/::after paints a full-cover opaque surface
854
+ // (position absolute/fixed + inset 0 + solid background). The pseudo is
855
+ // the element's visible background for contrast purposes even though it
856
+ // never joins the element cascade.
857
+ this._pseudoSurface = new WeakMap();
808
858
  }
809
859
  wrap(node) {
810
860
  let wrapped = this._wrappers.get(node);
@@ -841,6 +891,24 @@ class StaticDocument {
841
891
  getStyle(el) {
842
892
  return this._styleMap.get(el.node) || makeStaticStyle();
843
893
  }
894
+ setHoverStyle(node, style) {
895
+ this._hoverStyleMap.set(node, style);
896
+ }
897
+ getHoverStyle(el) {
898
+ return this._hoverStyleMap.get(el.node) || null;
899
+ }
900
+ setAccentDashPseudo(node) {
901
+ this._accentDashPseudo.add(node);
902
+ }
903
+ hasAccentDashPseudo(el) {
904
+ return this._accentDashPseudo.has(el.node);
905
+ }
906
+ setPseudoSurface(node, color) {
907
+ this._pseudoSurface.set(node, color);
908
+ }
909
+ getPseudoSurface(el) {
910
+ return this._pseudoSurface.get(el.node) || null;
911
+ }
844
912
  }
845
913
 
846
914
  function makeStaticStyle(values = {}) {
@@ -856,6 +924,9 @@ function buildStaticWindow(staticDoc) {
856
924
  return {
857
925
  document: staticDoc,
858
926
  getComputedStyle: (el) => staticDoc.getStyle(el),
927
+ getHoverStyle: (el) => staticDoc.getHoverStyle(el),
928
+ hasAccentDashPseudo: (el) => staticDoc.hasAccentDashPseudo(el),
929
+ getPseudoSurface: (el) => staticDoc.getPseudoSurface(el),
859
930
  };
860
931
  }
861
932
 
@@ -886,6 +957,13 @@ function collectStaticCssText(root, fileDir, profile, filePath, modules) {
886
957
 
887
958
  function buildStaticStyleMap(root, staticDoc, cssText, modules, profile, filePath) {
888
959
  const specified = new Map();
960
+ // Declarations from :hover rules, matched via their state-stripped
961
+ // selectors. Merged per-property against the resting cascade in
962
+ // computeNode — a hover declaration only takes effect if it would win
963
+ // the cascade while the element is hovered (all resting rules still
964
+ // apply in that state).
965
+ const hoverSpecified = new Map();
966
+ const rootCustomProps = collectCssCustomProps(cssText);
889
967
  const allNodes = modules.selectAll('*', root.children || []);
890
968
  const rules = profileStep(profile, {
891
969
  engine: 'static-html',
@@ -901,9 +979,65 @@ function buildStaticStyleMap(root, staticDoc, cssText, modules, profile, filePat
901
979
  target: filePath,
902
980
  }, () => {
903
981
  for (const rule of rules) {
982
+ // ::before/::after rules can't join the element cascade (pseudo
983
+ // elements aren't DOM nodes), but one shape matters to the eyebrow
984
+ // check: the short chromatic "kicker dash" (content box 8-80px wide,
985
+ // 1-6px tall, accent-colored fill). Mark the base-selector matches
986
+ // so checkElementHeroEyebrow can see the dash.
987
+ if (!rule.isHover) {
988
+ const pm = rule.selector.match(/^(.+?)\s*::?(?:before|after)$/i);
989
+ if (pm) {
990
+ const decls = new Map();
991
+ for (const d of rule.declarations) decls.set(d.prop.toLowerCase(), d.value);
992
+ const w = cssLengthToPx(resolveVarRefs(decls.get('width') || decls.get('inline-size') || '', rootCustomProps));
993
+ const h = cssLengthToPx(resolveVarRefs(decls.get('height') || decls.get('block-size') || '', rootCustomProps));
994
+ if (w != null && h != null && w >= 8 && w <= 80 && h >= 1 && h <= 6) {
995
+ const bgRaw = String(resolveVarRefs(decls.get('background-color') || decls.get('background') || '', rootCustomProps));
996
+ const token = bgRaw.match(/(?:rgba?|hsla?|oklch|oklab|lab|lch|hwb|color-mix)\([^)]*(?:\([^)]*\))?[^)]*\)|#[0-9a-f]{3,8}\b/i);
997
+ const c = parseAnyColor(token ? token[0] : bgRaw);
998
+ if (c && (c.a ?? 1) >= 0.1 && Math.max(c.r, c.g, c.b) - Math.min(c.r, c.g, c.b) >= 30) {
999
+ try {
1000
+ for (const node of modules.selectAll(pm[1], root.children || [])) {
1001
+ staticDoc.setAccentDashPseudo(node);
1002
+ }
1003
+ } catch { /* unsupported base selector */ }
1004
+ }
1005
+ }
1006
+ // Full-cover surface pseudo: the CTA construction where the
1007
+ // element itself stays transparent and a ::before/::after with
1008
+ // position absolute/fixed + inset 0 (or all four sides 0, or
1009
+ // 100% width and height) plus an opaque background paints the
1010
+ // visible surface. Mark base-selector matches so the contrast
1011
+ // checks measure text against the surface the browser renders.
1012
+ const pseudoPos = String(decls.get('position') || '').toLowerCase();
1013
+ if (pseudoPos === 'absolute' || pseudoPos === 'fixed') {
1014
+ const zeroLen = v => v != null && /^0(?:px)?$/.test(String(v).trim());
1015
+ const insetRaw = String(decls.get('inset') || '').trim();
1016
+ const coversBox = (insetRaw !== '' && insetRaw.split(/\s+/).every(t => /^0(?:px)?$/.test(t)))
1017
+ || ['top', 'right', 'bottom', 'left'].every(side => zeroLen(decls.get(side)))
1018
+ || (String(decls.get('width') || '').trim() === '100%'
1019
+ && String(decls.get('height') || '').trim() === '100%');
1020
+ if (coversBox && decls.has('content')) {
1021
+ const surfRaw = String(resolveVarRefs(decls.get('background-color') || decls.get('background') || '', rootCustomProps));
1022
+ const surfToken = surfRaw.match(/(?:rgba?|hsla?|oklch|oklab|lab|lch|hwb|color-mix)\([^)]*(?:\([^)]*\))?[^)]*\)|#[0-9a-f]{3,8}\b/i);
1023
+ const surf = parseAnyColor(surfToken ? surfToken[0] : surfRaw);
1024
+ if (surf && (surf.a ?? 1) >= 0.9 && !/gradient/i.test(surfRaw)) {
1025
+ try {
1026
+ for (const node of modules.selectAll(pm[1], root.children || [])) {
1027
+ staticDoc.setPseudoSurface(node, surf);
1028
+ }
1029
+ } catch { /* unsupported base selector */ }
1030
+ }
1031
+ }
1032
+ }
1033
+ continue;
1034
+ }
1035
+ }
1036
+ const matchSelector = rule.isHover ? rule.matchSelector : rule.selector;
1037
+ if (!matchSelector) continue;
904
1038
  let matched;
905
1039
  try {
906
- matched = modules.selectAll(rule.selector, root.children || []);
1040
+ matched = modules.selectAll(matchSelector, root.children || []);
907
1041
  } catch {
908
1042
  recordProfileEvent(profile, {
909
1043
  engine: 'static-html',
@@ -912,13 +1046,13 @@ function buildStaticStyleMap(root, staticDoc, cssText, modules, profile, filePat
912
1046
  target: filePath,
913
1047
  ms: 0,
914
1048
  findings: 0,
915
- detail: rule.selector,
1049
+ detail: matchSelector,
916
1050
  });
917
1051
  continue;
918
1052
  }
919
1053
  for (const node of matched) {
920
1054
  for (const decl of rule.declarations) {
921
- applyStaticDeclaration(specified, node, decl.prop, decl.value, {
1055
+ applyStaticDeclaration(rule.isHover ? hoverSpecified : specified, node, decl.prop, decl.value, {
922
1056
  important: decl.important,
923
1057
  specificity: rule.specificity,
924
1058
  order: rule.order,
@@ -961,6 +1095,28 @@ function buildStaticStyleMap(root, staticDoc, cssText, modules, profile, filePat
961
1095
  }
962
1096
  const style = makeStaticStyle(values);
963
1097
  staticDoc.setStyle(node, style);
1098
+
1099
+ // Hover pass: limited to the two properties the hover-contrast check
1100
+ // consumes. A hover declaration wins only if it beats the resting
1101
+ // winner for that property under normal cascade rules (specificity /
1102
+ // order / importance) — exactly what a browser computes while the
1103
+ // element is hovered.
1104
+ const hoverMap = hoverSpecified.get(node);
1105
+ if (hoverMap) {
1106
+ let hoverValues = null;
1107
+ for (const prop of ['color', 'backgroundColor']) {
1108
+ const hoverDecl = hoverMap.get(prop);
1109
+ if (!hoverDecl) continue;
1110
+ const restingDecl = specifiedMap.get(prop);
1111
+ if (!compareStaticPriority(restingDecl, hoverDecl)) continue;
1112
+ const next = normalizeStaticCssValue(prop, hoverDecl.value, customProps, parentStyle, values);
1113
+ if (next === values[prop]) continue;
1114
+ if (!hoverValues) hoverValues = { ...values };
1115
+ hoverValues[prop] = next;
1116
+ }
1117
+ if (hoverValues) staticDoc.setHoverStyle(node, makeStaticStyle(hoverValues));
1118
+ }
1119
+
964
1120
  for (const child of node.children || []) {
965
1121
  if (child.type === 'tag') computeNode(child, style, customProps);
966
1122
  }
@@ -18,6 +18,7 @@ import {
18
18
  checkElementGlow,
19
19
  checkElementGptBorderShadow,
20
20
  checkElementHeroEyebrow,
21
+ checkElementHoverContrast,
21
22
  checkElementIconTile,
22
23
  checkElementItalicSerif,
23
24
  checkElementMotion,
@@ -25,13 +26,14 @@ import {
25
26
  checkElementQuality,
26
27
  checkCreamPalette,
27
28
  checkHtmlPatterns,
29
+ checkNumberedSectionLabelsFromDoc,
28
30
  checkPageLayout,
29
31
  checkPageQualityFromDoc,
32
+ checkRepeatedContainerTextFromDoc,
30
33
  checkRepeatedSectionKickersFromDoc,
31
34
  resolveBackground,
32
35
  resolveBorderRadiusPx,
33
36
  } from '../../rules/checks.mjs';
34
- import { filterByProviders } from '../../registry/antipatterns.mjs';
35
37
  import { detectText, runTextContentAnalyzers } from '../regex/detect-text.mjs';
36
38
  import {
37
39
  StaticDocument,
@@ -90,8 +92,9 @@ function checkElementBrokenImage(el) {
90
92
  }
91
93
 
92
94
  const STATIC_ELEMENT_RULES = [
93
- { id: 'border-rules', selector: '*', run: (el, tag, style, window, customPropMap) => checkElementBorders(tag, style, null, resolveBorderRadiusPx(el, style, parseFloat(style.width) || 0, window)) },
95
+ { id: 'border-rules', selector: '*', run: (el, tag, style, window, customPropMap) => checkElementBorders(tag, style, null, resolveBorderRadiusPx(el, style, parseFloat(style.width) || 0, window), el) },
94
96
  { id: 'color-rules', selector: '*', run: (el, tag, style, window, customPropMap) => checkElementColors(el, style, tag, window, customPropMap, false) },
97
+ { id: 'hover-color-rules', selector: '*', run: (el, tag, style, window) => checkElementHoverContrast(el, style, tag, window) },
95
98
  { id: 'dark-glow', selector: '*', run: (el, tag, style, window, customPropMap) => checkElementGlow(tag, style, resolveBackground(el.parentElement || el, window, customPropMap)) },
96
99
  { id: 'motion-rules', selector: '*', run: (el, tag, style) => checkElementMotion(tag, style) },
97
100
  { id: 'icon-tile-stack', selector: 'h1,h2,h3,h4,h5,h6', run: (el, tag, _style, window) => checkElementIconTile(el, tag, window) },
@@ -200,6 +203,12 @@ async function detectHtml(filePath, options = {}) {
200
203
  for (const f of runPageCheck('repeated-section-kickers', () => checkRepeatedSectionKickersFromDoc(document, window))) {
201
204
  findings.push(finding(f.id, filePath, f.snippet));
202
205
  }
206
+ for (const f of runPageCheck('numbered-section-labels', () => checkNumberedSectionLabelsFromDoc(document, window))) {
207
+ findings.push(finding(f.id, filePath, f.snippet));
208
+ }
209
+ for (const f of runPageCheck('repeated-container-text', () => checkRepeatedContainerTextFromDoc(document, window))) {
210
+ findings.push(finding(f.id, filePath, f.snippet));
211
+ }
203
212
  for (const f of runPageCheck('layout-rules', () => checkPageLayout(document, window))) {
204
213
  findings.push(finding(f.id, filePath, f.snippet));
205
214
  }
@@ -212,7 +221,12 @@ async function detectHtml(filePath, options = {}) {
212
221
  for (const f of runPageCheck('html-patterns', () => checkHtmlPatterns(html).filter(item =>
213
222
  item.id !== 'bounce-easing' && item.id !== 'layout-transition'
214
223
  ))) {
215
- findings.push(finding(f.id, filePath, f.snippet));
224
+ const item = finding(f.id, filePath, f.snippet);
225
+ // Position-aware severity promotion: checks may attach a per-finding
226
+ // severity (e.g. a pulsing dot inside a header/nav landmark) that
227
+ // overrides the registry default.
228
+ if (f.severity) item.severity = f.severity;
229
+ findings.push(item);
216
230
  }
217
231
  // Text-content analyzers (em-dash overuse, marketing buzzwords,
218
232
  // numbered section markers, aphoristic cadence) live in the regex
@@ -224,11 +238,10 @@ async function detectHtml(filePath, options = {}) {
224
238
  }
225
239
  }
226
240
 
227
- const byProvider = filterByProviders(findings, options.providers);
228
241
  // Static-HTML findings carry no line number, so only whole-file
229
242
  // `impeccable-disable` directives apply here — exactly the standalone-document
230
243
  // waiver this primitive targets. Bypassed by `--no-config` / `--no-inline-ignores`.
231
- return options?.inlineIgnores === false ? byProvider : applyInlineIgnores(byProvider, html);
244
+ return options?.inlineIgnores === false ? findings : applyInlineIgnores(findings, html);
232
245
  }
233
246
 
234
247
  export { checkStaticPageTypography, STATIC_ELEMENT_RULES, detectHtml };
@@ -6,7 +6,13 @@ function getAP(id) {
6
6
 
7
7
  function finding(id, filePath, snippet, line = 0) {
8
8
  const ap = getAP(id);
9
- return { antipattern: id, name: ap.name, description: ap.description, severity: ap.severity || 'warning', file: filePath, line, snippet };
9
+ const base = { antipattern: id, name: ap.name, description: ap.description, severity: ap.severity || 'warning', category: ap.category || null, file: filePath, line, snippet };
10
+ // Advisory findings are detected but reported separately and never counted as
11
+ // failures. Carry the flag on the finding so every consumer (CLI, JSON, hook)
12
+ // can partition without a registry lookup. Only stamped when true to keep the
13
+ // finding shape stable for the vast majority of rules.
14
+ if (ap.advisory === true) base.advisory = true;
15
+ return base;
10
16
  }
11
17
 
12
18
  export { getAP, finding };
@@ -32,9 +32,9 @@ const ANTIPATTERNS = [
32
32
  id: 'single-font',
33
33
  category: 'slop',
34
34
  scopes: ['type'],
35
- name: 'Single font for everything',
35
+ name: 'Single font without hierarchy',
36
36
  description:
37
- 'Only one font family is used for the entire page. Pair a distinctive display font with a refined body font to create typographic hierarchy.',
37
+ 'Only one font family is used for the entire page. A single family can work when weight and size contrast carry the hierarchy; otherwise pair a distinctive display font with a refined body font.',
38
38
  skillSection: 'Typography',
39
39
  skillGuideline: 'only one font family for the entire page',
40
40
  },
@@ -104,15 +104,60 @@ const ANTIPATTERNS = [
104
104
  skillSection: 'Motion',
105
105
  skillGuideline: 'bounce or elastic easing',
106
106
  },
107
+ {
108
+ id: 'pulsing-dot',
109
+ category: 'slop',
110
+ name: 'Pulsing status dot',
111
+ description:
112
+ 'Small pulsing status dots simulate liveness decoratively. Reserve pulse animation for indicators tied to genuinely live, changing data; a static indicator with clear labeling is honest and calmer.',
113
+ skillSection: 'Motion',
114
+ skillGuideline: 'decorative pulsing status dot',
115
+ },
116
+ {
117
+ id: 'blinking-cursor',
118
+ category: 'slop',
119
+ severity: 'advisory',
120
+ name: 'Decorative blinking cursor',
121
+ description:
122
+ 'A blinking text cursor animated into a hero or landing section simulates typing where no input exists. It borrows the dev-tool aesthetic as decoration. Real editable fields draw their own caret; anywhere else, let the composition hold attention without a fake prompt.',
123
+ skillSection: 'Motion',
124
+ },
125
+ {
126
+ id: 'shape-assembled-illustration',
127
+ category: 'slop',
128
+ severity: 'advisory',
129
+ name: 'Shape-assembled illustration',
130
+ description:
131
+ 'A large inline SVG that builds a pictorial scene from a pile of primitive shapes reads as placeholder clip art, not illustration. Icons, logos, and data graphics are fine at their scale; a hero-sized visual deserves real artwork, a photograph, or a deliberately drawn graphic.',
132
+ skillSection: 'Imagery',
133
+ },
107
134
  {
108
135
  id: 'dark-glow',
109
136
  category: 'slop',
110
- name: 'Dark mode with glowing accents',
137
+ name: 'Glowing shadow accents',
111
138
  description:
112
- 'Dark backgrounds with colored box-shadow glows are the default "cool" look of AI-generated UIs. Use subtle, purposeful lighting instead — or skip the dark theme entirely.',
139
+ 'Colored glow shadows — a zero-offset chromatic halo (box- or text-shadow) on any background, or any colored blurred shadow on a dark background — are the default "cool" look of AI-generated UIs. Use neutral elevation shadows and subtle, purposeful lighting instead.',
113
140
  skillSection: 'Color & Contrast',
114
141
  skillGuideline: 'dark mode with glowing accents',
115
142
  },
143
+ {
144
+ id: 'radial-halo',
145
+ category: 'slop',
146
+ name: 'Radial-gradient background halo',
147
+ description:
148
+ 'A chromatic radial-gradient wash — saturated at the center, fading to transparent — used as a decorative background glow on a dark page. Same tell as glowing shadows, drawn with a gradient instead of a shadow. Ground the surface with a solid or subtly shifted background instead.',
149
+ skillSection: 'Color & Contrast',
150
+ skillGuideline: 'dark mode with glowing accents',
151
+ },
152
+ {
153
+ id: 'marquee',
154
+ category: 'slop',
155
+ name: 'Auto-scrolling marquee',
156
+ description:
157
+ 'Continuously auto-scrolling content demands attention it has not earned and hides half its content at any moment. Reserve motion for content that changes; let readers move at their own pace.',
158
+ skillSection: 'Motion',
159
+ skillGuideline: 'auto-scrolling marquee',
160
+ },
116
161
  {
117
162
  id: 'icon-tile-stack',
118
163
  category: 'slop',
@@ -155,22 +200,27 @@ const ANTIPATTERNS = [
155
200
  skillGuideline: 'repeated eyebrow or kicker labels as section scaffolding',
156
201
  },
157
202
  {
158
- id: 'numbered-section-markers',
203
+ id: 'numbered-section-labels',
159
204
  category: 'slop',
160
- scopes: ['layout'],
205
+ scopes: ['type'],
161
206
  severity: 'advisory',
162
- name: 'Numbered section markers (01 / 02 / 03)',
207
+ name: 'Tiny numbered section labels',
163
208
  description:
164
- 'Numbered display markers as section labels (01, 02, 03) are the AI editorial scaffold one tier deeper than tracked eyebrow chips. If you find yourself reaching for them, choose a different section cadence.',
209
+ 'Small numeric index labels riding next to section headings, repeated section after section, are AI editorial scaffolding — a page numbering its own chapters instead of earning structure. Let hierarchy, content, and rhythm carry the sequence.',
165
210
  skillSection: 'Layout & Space',
166
211
  skillGuideline: 'numbered section markers',
167
212
  },
168
213
  {
169
214
  id: 'em-dash-overuse',
170
215
  category: 'slop',
216
+ // Advisory: humans use em-dashes legitimately, so this rule is opt-in noise
217
+ // rather than a failure. It fires only on the AI saturation pattern, not on
218
+ // ordinary prose. Advisory findings are surfaced separately, never counted
219
+ // as failures, and skipped by the design hook unless a project opts in.
220
+ advisory: true,
171
221
  name: 'Em-dash overuse',
172
222
  description:
173
- 'More than two em-dashes (— or --) in body copy is an AI cadence tell. Use commas, colons, periods, or parentheses instead.',
223
+ 'Em-dash saturation in body copy is an AI cadence tell. Advisory only: humans use em-dashes legitimately, so this fires only on saturation — at least 8 em-dashes (— or --) at a density near one per 500 characters of body text — never on a long article that uses a few. Prefer commas, colons, periods, or parentheses.',
174
224
  skillSection: 'Copy',
175
225
  skillGuideline: 'no em dashes',
176
226
  },
@@ -223,6 +273,49 @@ const ANTIPATTERNS = [
223
273
  },
224
274
 
225
275
  // ── Quality: general design and accessibility issues ──
276
+ {
277
+ id: 'script-error',
278
+ category: 'quality',
279
+ severity: 'error',
280
+ name: 'Uncaught script error on load',
281
+ description:
282
+ 'A script threw an uncaught exception or failed to parse while the page loaded. Broken JavaScript silently kills reveals, interactions, and dynamic content, and can leave most of a page invisible. Fix the error before judging anything else.',
283
+ },
284
+ {
285
+ id: 'content-hidden-at-rest',
286
+ category: 'quality',
287
+ severity: 'error',
288
+ scopes: ['layout'],
289
+ name: 'Content invisible at rest',
290
+ description:
291
+ 'A large share of the page text sits at opacity 0 or visibility hidden even after every reveal handler had a chance to run. This is the failed-reveal signature: the content shipped but never becomes visible. Make content visible by default and let JavaScript enhance its entrance instead of gating its existence.',
292
+ },
293
+ {
294
+ id: 'edge-flush-cards',
295
+ category: 'quality',
296
+ scopes: ['layout'],
297
+ name: 'Cards flush against the scroller edge',
298
+ description:
299
+ 'Cards inside a horizontal scroller or tab panel sit flush against the container edge at rest while keeping a gutter on the other side, so their edges and rounded corners get cut off. Usually the panel is sized wider than its clip box. Keep a consistent inset on both sides.',
300
+ },
301
+ {
302
+ id: 'text-occlusion',
303
+ category: 'quality',
304
+ scopes: ['layout'],
305
+ name: 'Text occluded by an overlapping element',
306
+ description:
307
+ 'Text is painted under an opaque element or a second text run, so part of it cannot be read. A decorative box, a stacked layer, or an inline element with leaked padding lands on the words instead of beside them. Give overlapping layers room, or move the text out from under the layer above it.',
308
+ skillSection: 'Layout & Space',
309
+ },
310
+ {
311
+ id: 'first-viewport-column-overflow',
312
+ category: 'quality',
313
+ scopes: ['layout'],
314
+ name: 'One column stretches the first viewport',
315
+ description:
316
+ 'A multi-column opening section lets one column run far past the fold while its sibling fits in a single viewport, so the short column floats in dead space and the fold falls deep inside one section. Balance the columns, cap the tall one, or let the long content flow below the opening row.',
317
+ skillSection: 'Layout & Space',
318
+ },
226
319
  {
227
320
  id: 'gray-on-color',
228
321
  category: 'quality',
@@ -292,6 +385,15 @@ const ANTIPATTERNS = [
292
385
  description:
293
386
  'Heading levels should not skip (e.g. h1 then h3 with no h2). Screen readers use heading hierarchy for navigation. Skipping levels breaks the document outline.',
294
387
  },
388
+ {
389
+ id: 'heading-rhythm',
390
+ category: 'quality',
391
+ scopes: ['layout', 'type'],
392
+ name: 'Heading crowded against the previous block',
393
+ description:
394
+ 'A heading binds to the content it introduces, so the rendered space above it should exceed the space below it. When headings across a page sit as close or closer to the block above than to their own content, every section reads as if it captions the previous one. Open up the space above each heading.',
395
+ skillSection: 'Layout & Space',
396
+ },
295
397
  {
296
398
  id: 'justified-text',
297
399
  category: 'quality',
@@ -308,6 +410,14 @@ const ANTIPATTERNS = [
308
410
  description:
309
411
  'Body text below 12px is hard to read, especially on high-DPI screens. Use at least 14px for body content, 16px is ideal.',
310
412
  },
413
+ {
414
+ id: 'undersized-ui-text',
415
+ category: 'quality',
416
+ scopes: ['type'],
417
+ name: 'Undersized functional text',
418
+ description:
419
+ 'Interactive and content-bearing UI text (links, buttons, nav items, labels, table cells, meta rows, timecodes) below 11px is a legibility failure, not a style choice. WCAG sets no absolute pixel floor, but functional text under 11px is a defensible quality bar: it fails on high-DPI and small viewports and it degrades tap and read targets. The 11px floor holds even inside a footer; only non-interactive legal smallprint gets the softer 10px floor. Being ON the DESIGN.md size ramp does not exempt a value here: adding 8px to the ramp launders the token but not the legibility problem, and that is exactly the escape hatch this rule closes. Exempts sup/sub, visually-hidden (sr-only) text, and code/terminal contexts. Decorative letterspaced micro-labels are still functional and stay in scope.',
420
+ },
311
421
  {
312
422
  id: 'all-caps-body',
313
423
  category: 'quality',
@@ -336,6 +446,13 @@ const ANTIPATTERNS = [
336
446
  skillSection: 'Layout & Space',
337
447
  skillGuideline: 'content wider than its container',
338
448
  },
449
+ {
450
+ id: 'repeated-container-text',
451
+ category: 'quality',
452
+ name: 'Same text repeated inside one container',
453
+ description:
454
+ 'The same literal text rendered three or more times in structurally different spots inside a single card or panel is redundant messaging — usually a status or label wired into every slot of a template. Say it once, in the slot where it matters most.',
455
+ },
339
456
  {
340
457
  id: 'clipped-overflow-container',
341
458
  category: 'quality',
@@ -388,12 +505,11 @@ const ANTIPATTERNS = [
388
505
  skillGuideline: 'font size outside the project design system',
389
506
  },
390
507
 
391
- // ── Provider tells: opt-in via --gpt / --gemini (gated off by default) ──
508
+ // ── Common generated-UI tells ───────────────────────────────────────────
392
509
  {
393
510
  id: 'gpt-thin-border-wide-shadow',
394
511
  category: 'slop',
395
512
  severity: 'advisory',
396
- gated: 'gpt',
397
513
  name: 'Hairline border with wide shadow',
398
514
  description:
399
515
  'A hairline border paired with a wide, diffuse shadow is a recurring generated-UI signature. Commit to one — a defined edge or a soft elevation — rather than both at once.',
@@ -404,7 +520,6 @@ const ANTIPATTERNS = [
404
520
  id: 'repeating-stripes-gradient',
405
521
  category: 'slop',
406
522
  severity: 'advisory',
407
- gated: 'gpt',
408
523
  name: 'Repeating-gradient stripes',
409
524
  description:
410
525
  'Repeating-gradient stripes used as surface decoration are a recurring generated-UI signature. Reach for a deliberate texture or leave the surface plain.',
@@ -415,10 +530,9 @@ const ANTIPATTERNS = [
415
530
  id: 'codex-grid-background',
416
531
  category: 'slop',
417
532
  severity: 'advisory',
418
- gated: 'gpt',
419
533
  name: 'Decorative grid-line background',
420
534
  description:
421
- '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.',
535
+ 'A decorative grid or line-field background drawn with hairline linear-gradient layers tiled by a fixed pixel cell 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.',
422
536
  skillSection: 'Visual Details',
423
537
  skillGuideline: 'two-axis grid-line gradient background',
424
538
  },
@@ -426,7 +540,6 @@ const ANTIPATTERNS = [
426
540
  id: 'theater-slop-phrase',
427
541
  category: 'slop',
428
542
  severity: 'advisory',
429
- gated: 'gpt',
430
543
  name: 'Theater framing copy',
431
544
  description:
432
545
  'Dismissing something as "theater" is a recurring generated-copy tic. Say plainly what the thing does or does not do.',
@@ -437,7 +550,6 @@ const ANTIPATTERNS = [
437
550
  id: 'image-hover-transform',
438
551
  category: 'slop',
439
552
  severity: 'advisory',
440
- gated: 'gemini',
441
553
  name: 'Image hover transform',
442
554
  description:
443
555
  'Scaling or rotating an image on hover is a recurring generated-UI signature. Let imagery sit still, or use a subtler, purposeful interaction.',
@@ -457,6 +569,18 @@ function getAntipattern(id) {
457
569
  return ANTIPATTERNS.find(rule => rule.id === id);
458
570
  }
459
571
 
572
+ // Advisory rules are detected and reported, but never treated as failures:
573
+ // the CLI lists them under a separate "Advisory" section, they do not affect
574
+ // exit codes or the failure count, and the design hook skips them by default.
575
+ // The set is derived from the registry so a rule only needs `advisory: true`.
576
+ const ADVISORY_RULE_IDS = new Set(
577
+ ANTIPATTERNS.filter(rule => rule.advisory === true).map(rule => rule.id),
578
+ );
579
+
580
+ function isAdvisoryRule(id) {
581
+ return ADVISORY_RULE_IDS.has(id);
582
+ }
583
+
460
584
  function getRulesForCategory(category) {
461
585
  return ANTIPATTERNS.filter(rule => rule.category === category);
462
586
  }
@@ -465,25 +589,6 @@ function getRuleEngineSupport(engine) {
465
589
  return RULE_ENGINE_SUPPORT[engine] || new Set();
466
590
  }
467
591
 
468
- // Set of provider tags that gate rules off by default (e.g. 'gpt', 'gemini').
469
- const GATED_PROVIDERS = new Set(
470
- ANTIPATTERNS.map(rule => rule.gated).filter(Boolean),
471
- );
472
-
473
- // Drop findings for rules gated behind a provider tag unless that provider
474
- // was explicitly enabled (CLI --gpt / --gemini). Non-gated findings always
475
- // pass through. `findings` carry the rule id on `.antipattern`.
476
- function filterByProviders(findings, providers = []) {
477
- const enabled = new Set(providers || []);
478
- if (!GATED_PROVIDERS.size) return findings;
479
- return findings.filter(f => {
480
- const rule = getAntipattern(f.antipattern);
481
- if (!rule || !rule.gated) return true;
482
- return enabled.has(rule.gated);
483
- });
484
- }
485
-
486
-
487
592
  // Set of scope tags rules can declare (e.g. 'type', 'layout'). Used by the
488
593
  // CLI --scope flag to narrow output to one design domain.
489
594
  const RULE_SCOPES = new Set(
@@ -505,10 +610,10 @@ export {
505
610
  ANTIPATTERNS,
506
611
  RULE_SCOPES,
507
612
  RULE_ENGINE_SUPPORT,
508
- GATED_PROVIDERS,
613
+ ADVISORY_RULE_IDS,
509
614
  getAntipattern,
510
615
  getRulesForCategory,
511
616
  getRuleEngineSupport,
512
- filterByProviders,
617
+ isAdvisoryRule,
513
618
  filterByScopes,
514
619
  };