@etus/seven-skill 0.1.0-beta.1

package/cli/engine/rules/checks.mjs

@@ -0,0 +1,1518 @@
+// SPDX-License-Identifier: Apache-2.0
+// ETUS Digital — Seven Design System. Detector architecture adapted from
+// impeccable (Paul Bakaus, Apache-2.0). See packages/seven-skill/NOTICE.md.
+
+import {
+  PT_PT_VOCAB_PAIRS,
+  SAFE_TAGS,
+  SYSTEM_FONT_FALLBACK_TOKENS,
+} from '../shared/constants.mjs'
+import {
+  colorToHex,
+  contrastRatio,
+  getHue,
+  hasChroma,
+  isFuchsia,
+  isNeutralColor,
+  parseRgb,
+  relativeLuminance,
+} from '../shared/color.mjs'
+import {
+  colorToCssVar,
+  componentRadiiPx,
+  isAllowedFontFamily,
+  minFontSizePx,
+  pillRadiiPx,
+  sanctionedEasingBeziers,
+  suggestSemanticToken,
+  surfaceRadiiPx,
+} from '../shared/tokens.mjs'
+
+// Detection runs in two worlds: Node (regex + static-html) and a real browser.
+// `window` only exists in the browser; the *-DOM adapters key off this flag.
+const DETECTOR_IS_BROWSER = typeof window !== 'undefined'
+
+// ─── Section 1: Seven text checks (regex-on-source) ─────────────────────────
+// These eight checks scan raw file text and need no computed-style cascade.
+// Every engine runs them: the regex engine over source text, the static-html
+// and browser engines over the markup + stylesheet text they extract.
+
+function lineOf(text, index) {
+  let line = 1
+  for (let i = 0; i < index && i < text.length; i++) {
+    if (text.charCodeAt(i) === 10) line++
+  }
+  return line
+}
+
+function snippetAt(text, index, padding = 40) {
+  const start = Math.max(0, index - padding)
+  const end = Math.min(text.length, index + padding + 20)
+  return text.slice(start, end).replace(/\s+/g, ' ').trim()
+}
+
+function parseFontFamilyValue(raw) {
+  return raw
+    .split(',')
+    .map((s) => s.trim().toLowerCase().replace(/^['"]/, '').replace(/['"]$/, ''))
+}
+
+/**
+ * Classify a CSS variable name as 'color', 'length', or 'unknown' from Seven's
+ * naming conventions. Length wins when both signals appear (e.g.
+ * --button-border-width is a length even though `border` is a color signal).
+ */
+function classifyVarName(name) {
+  const hasColorSignal =
+    /(?:^|-)(?:color|fg|bg|primary|secondary|accent|background|foreground|muted|destructive|warning|success|info|brand|surface|ring|border|stroke|fill|outline)(?:$|-)/i.test(name)
+  const hasLengthSignal =
+    /(?:^|-)(?:width|height|radius|padding|margin|gap|inset|offset|space|font-size|line-height|leading|tracking|letter-spacing|fs|size|weight|duration|delay)(?:$|-)/i.test(name)
+  if (hasLengthSignal) return 'length'
+  if (hasColorSignal) return 'color'
+  if (/-text$/i.test(name)) return 'length'
+  return 'unknown'
+}
+
+/** A value that is exactly `var(--something)` with optional whitespace. */
+function isSingleVarReference(value) {
+  return /^\s*var\(\s*--[a-zA-Z0-9-]+\s*\)\s*$/.test(value)
+}
+
+function isWithinSvgOrChartTag(text, index) {
+  const before = text.slice(Math.max(0, index - 800), index).toLowerCase()
+  const lastSvgOpen = before.lastIndexOf('<svg')
+  const lastSvgClose = before.lastIndexOf('</svg>')
+  if (lastSvgOpen > lastSvgClose) return true
+  return /data-role\s*=\s*['"]chart['"]/i.test(before)
+}
+
+const FONT_FAMILY_RE = /font-family\s*:\s*([^;{}\n]+)/gi
+
+export function checkNonInterFont(text) {
+  const findings = []
+  let match
+  while ((match = FONT_FAMILY_RE.exec(text)) !== null) {
+    const parts = parseFontFamilyValue(match[1])
+    const primary = parts[0] ?? ''
+    if (!primary || primary.startsWith('var(') || primary.startsWith('inherit')) continue
+    // Token-grounded: the allowed families come from the @etus/tokens
+    // fontFamily tokens (plus JetBrains Mono and the system fallbacks).
+    if (isAllowedFontFamily(primary) || SYSTEM_FONT_FALLBACK_TOKENS.has(primary)) {
+      continue
+    }
+    findings.push({ id: 'non-inter-font', line: lineOf(text, match.index), snippet: snippetAt(text, match.index) })
+  }
+  return findings
+}
+
+const HEX_COLOR_RE = /#(?:[0-9a-fA-F]{8}|[0-9a-fA-F]{6}|[0-9a-fA-F]{3,4})\b/g
+const RGB_COLOR_RE = /\brgba?\s*\(\s*\d+\s*,\s*\d+\s*,\s*\d+\s*[,/)]/g
+const HSL_COLOR_RE = /\bhsla?\s*\(\s*\d+(?:deg)?\s*,?\s*\d+%/g
+const OKLCH_LITERAL_RE = /\boklch\s*\(\s*[\d.]+/g
+
+/**
+ * Extract the full color value starting at `index` — the regexes above match a
+ * prefix for rgb/hsl/oklch, so the closing paren has to be read back to get a
+ * value the token lookup can resolve.
+ */
+function fullColorAt(text, index) {
+  const rest = text.slice(index, index + 80)
+  if (rest[0] === '#') return (rest.match(/^#[0-9a-fA-F]{3,8}/) || [''])[0]
+  const fn = rest.match(/^(?:rgba?|hsla?|oklch)\s*\([^)]*\)/i)
+  return fn ? fn[0] : ''
+}
+
+export function checkHardcodedColorNotToken(text) {
+  const findings = []
+  const seen = new Set()
+  const add = (match) => {
+    const key = `${match.index}:${match[0]}`
+    if (seen.has(key)) return
+    seen.add(key)
+    // Token-grounded: when the literal is a Seven token value, name the token
+    // so the fix is precise instead of a generic "use a variable".
+    const cssVar = colorToCssVar(fullColorAt(text, match.index))
+    const base = snippetAt(text, match.index)
+    findings.push({
+      id: 'hardcoded-color-not-token',
+      line: lineOf(text, match.index),
+      snippet: cssVar ? `${base} (use var(${cssVar}))` : base,
+    })
+  }
+  let m
+  while ((m = HEX_COLOR_RE.exec(text)) !== null) add(m)
+  while ((m = RGB_COLOR_RE.exec(text)) !== null) add(m)
+  while ((m = HSL_COLOR_RE.exec(text)) !== null) add(m)
+  while ((m = OKLCH_LITERAL_RE.exec(text)) !== null) add(m)
+  return findings
+}
+
+// Tailwind default palette colors. A `bg-green-500` / `text-neutral-900` /
+// `border-red-200` utility paints a color that bypasses @etus/tokens exactly
+// as a hex literal does — the token scale never sees it.
+const TW_PALETTE_HUES =
+  'slate|gray|zinc|neutral|stone|red|orange|amber|yellow|lime|green|emerald|teal|cyan|sky|blue|indigo|violet|purple|fuchsia|pink|rose'
+const TW_COLOR_UTILITIES =
+  'bg|text|border|ring|ring-offset|from|to|via|fill|stroke|outline|decoration|divide|placeholder|caret|accent|shadow'
+const RAW_TW_PALETTE_RE = new RegExp(
+  `\\b(?:${TW_COLOR_UTILITIES})-(${TW_PALETTE_HUES})-\\d{2,3}\\b`,
+  'g'
+)
+
+// Each Tailwind hue family maps onto a Seven semantic role. The actual token
+// name for that role is then resolved from the @etus/tokens snapshot, so the
+// finding points at the real Seven equivalent — not a generic "use a token".
+const TW_HUE_TO_ROLE = {
+  red: 'destructive', rose: 'destructive',
+  green: 'success', emerald: 'success', lime: 'success', teal: 'success',
+  amber: 'warning', yellow: 'warning', orange: 'warning',
+  blue: 'info', sky: 'info', cyan: 'info', indigo: 'info',
+  violet: 'accent', purple: 'accent', fuchsia: 'accent', pink: 'accent',
+  slate: 'muted', gray: 'muted', zinc: 'muted', neutral: 'muted', stone: 'muted',
+}
+
+export function checkRawTailwindPaletteColor(text) {
+  const findings = []
+  let match
+  RAW_TW_PALETTE_RE.lastIndex = 0
+  while ((match = RAW_TW_PALETTE_RE.exec(text)) !== null) {
+    const role = TW_HUE_TO_ROLE[match[1]]
+    const token = role ? suggestSemanticToken(role) : null
+    const suggestion = token
+      ? `use the Seven ${role} token: bg-[color:var(${token})]`
+      : 'use a Seven color token: bg-[color:var(--...)]'
+    findings.push({
+      id: 'raw-tailwind-palette-color',
+      line: lineOf(text, match.index),
+      snippet: `${match[0]}: Tailwind palette color bypasses @etus/tokens; ${suggestion}`,
+    })
+  }
+  return findings
+}
+
+const COLOR_PROP_RE = /(?:bg|text|border|ring)-\[(?:([a-z]+):)?([^\]]+)\]/g
+
+export function checkMissingColorTypeHint(text) {
+  const findings = []
+  let match
+  while ((match = COLOR_PROP_RE.exec(text)) !== null) {
+    const hint = match[1]
+    const value = match[2] ?? ''
+    if (hint) continue
+    if (!isSingleVarReference(value)) continue
+    const varName = value.match(/var\(\s*(--[a-zA-Z0-9-]+)/)?.[1] ?? ''
+    if (classifyVarName(varName) !== 'color') continue
+    findings.push({
+      id: 'missing-color-type-hint',
+      line: lineOf(text, match.index),
+      snippet: snippetAt(text, match.index),
+    })
+  }
+  return findings
+}
+
+const LENGTH_PROP_RE = /\btext-\[(?:([a-z]+):)?([^\]]+)\]/g
+
+export function checkMissingLengthTypeHint(text) {
+  const findings = []
+  let match
+  while ((match = LENGTH_PROP_RE.exec(text)) !== null) {
+    const hint = match[1]
+    const value = match[2] ?? ''
+    if (hint) continue
+    if (!isSingleVarReference(value)) continue
+    const varName = value.match(/var\(\s*(--[a-zA-Z0-9-]+)/)?.[1] ?? ''
+    if (classifyVarName(varName) !== 'length') continue
+    findings.push({
+      id: 'missing-length-type-hint',
+      line: lineOf(text, match.index),
+      snippet: snippetAt(text, match.index),
+    })
+  }
+  return findings
+}
+
+const CLASS_ATTR_RE = /\b(?:className|class)\s*=\s*["'`]([^"'`]+)["'`]/g
+
+export function checkLeadingNoneWithLengthVar(text) {
+  const findings = []
+  let match
+  while ((match = CLASS_ATTR_RE.exec(text)) !== null) {
+    const classes = match[1] ?? ''
+    if (!/\bleading-none\b/.test(classes)) continue
+    if (!/text-\[length:var\(/.test(classes)) continue
+    findings.push({
+      id: 'leading-none-with-length-var',
+      line: lineOf(text, match.index),
+      snippet: snippetAt(text, match.index),
+    })
+  }
+  return findings
+}
+
+const FUCHSIA_OKLCH_RE = /oklch\(\s*[0-9.]+%?\s+[0-9.]+\s+(2[89][0-9]|3[0-3][0-9])(?:\.[0-9]+)?\s*[/)]/gi
+const FUCHSIA_HEX_RE = /#(?:d9[0-9a-f]{1,2}[0-9a-f]ef|d946ef|e879f9|c026d3|a21caf|86198f)\b/gi
+
+export function checkFuchsiaInUiChrome(text) {
+  const findings = []
+  let match
+  while ((match = FUCHSIA_HEX_RE.exec(text)) !== null) {
+    if (isWithinSvgOrChartTag(text, match.index)) continue
+    findings.push({ id: 'fuchsia-in-ui-chrome', line: lineOf(text, match.index), snippet: snippetAt(text, match.index) })
+  }
+  while ((match = FUCHSIA_OKLCH_RE.exec(text)) !== null) {
+    if (isWithinSvgOrChartTag(text, match.index)) continue
+    findings.push({ id: 'fuchsia-in-ui-chrome', line: lineOf(text, match.index), snippet: snippetAt(text, match.index) })
+  }
+  return findings
+}
+
+export function checkPtPtVocab(text) {
+  const findings = []
+  for (const pair of PT_PT_VOCAB_PAIRS) {
+    const re = new RegExp(`\\b${pair.ptPt}\\b`, 'giu')
+    let match
+    while ((match = re.exec(text)) !== null) {
+      findings.push({
+        id: 'pt-pt-vocab',
+        line: lineOf(text, match.index),
+        snippet: `${snippetAt(text, match.index)} (use "${pair.ptBr}")`,
+      })
+    }
+  }
+  return findings
+}
+
+const PURE_BLACK_WHITE_RE =
+  /(?:#(?:0{3,4}|0{6}|0{8})\b|#(?:f{3,4}|f{6}|f{8})\b|\brgba?\s*\(\s*0\s*,\s*0\s*,\s*0\s*[,/)]|\brgba?\s*\(\s*255\s*,\s*255\s*,\s*255\s*[,/)])/gi
+
+export function checkPureBlackOrWhite(text) {
+  const findings = []
+  let match
+  while ((match = PURE_BLACK_WHITE_RE.exec(text)) !== null) {
+    // Token-grounded: pure black/white are primitives; name the base token.
+    const cssVar = colorToCssVar(fullColorAt(text, match.index))
+    const base = snippetAt(text, match.index)
+    findings.push({
+      id: 'pure-black-or-white',
+      line: lineOf(text, match.index),
+      snippet: cssVar ? `${base} (use var(${cssVar}))` : base,
+    })
+  }
+  return findings
+}
+
+// Emoji characters render as multicolor glyphs regardless of CSS `color` and
+// have no place in Seven chrome copy. The class covers flags, pictographs,
+// symbols, dingbats, variation selectors, ZWJ sequences, and skin-tone
+// modifiers — the same range the upstream detector used to exclude emoji-only
+// text nodes from contrast checks.
+const EMOJI_CHAR_RE = /[\u{1F1E6}-\u{1F1FF}\u{1F300}-\u{1F9FF}\u{1FA00}-\u{1FAFF}\u{2600}-\u{27BF}\u{2300}-\u{23FF}\u{FE0F}\u{200D}\u{1F3FB}-\u{1F3FF}]/u
+const EMOJI_CHARS_GLOBAL = /[\u{1F1E6}-\u{1F1FF}\u{1F300}-\u{1F9FF}\u{1FA00}-\u{1FAFF}\u{2600}-\u{27BF}\u{2300}-\u{23FF}\u{FE0F}\u{200D}\u{1F3FB}-\u{1F3FF}]/gu
+
+export function isEmojiOnlyText(text) {
+  if (!text) return false
+  if (!EMOJI_CHAR_RE.test(text)) return false
+  return text.replace(EMOJI_CHARS_GLOBAL, '').trim() === ''
+}
+
+// Chrome elements whose text content must not carry emoji glyphs.
+const CHROME_TEXT_TAG_RE =
+  /<(button|h[1-6]|label|a)\b[^>]*>([\s\S]*?)<\/\1>/gi
+
+export function checkEmojiInChrome(text) {
+  const findings = []
+  let match
+  CHROME_TEXT_TAG_RE.lastIndex = 0
+  while ((match = CHROME_TEXT_TAG_RE.exec(text)) !== null) {
+    // Strip nested tags so we only test the rendered text run.
+    const inner = match[2].replace(/<[^>]+>/g, '')
+    if (!EMOJI_CHAR_RE.test(inner)) continue
+    findings.push({
+      id: 'emoji-in-chrome',
+      line: lineOf(text, match.index),
+      snippet: snippetAt(text, match.index),
+    })
+  }
+  return findings
+}
+
+// Em-dash (U+2014) and en-dash (U+2013) in user-facing copy. JSX/HTML text
+// runs and string literals carry copy; the long dash there reads as
+// machine-generated prose.
+const LONG_DASH_RE = /[–—]/g
+
+export function checkForbiddenEmDash(text) {
+  // Mask JS/CSS block and line comments before scanning. JSDoc and `//`
+  // explanatory comments are developer prose, not user-facing copy, and they
+  // routinely use the long dash as rhetorical punctuation. Newlines are kept
+  // so line offsets stay accurate for the surviving matches. The `[^:]` guard
+  // on `//` keeps `https://` from being treated as a comment start.
+  const masked = text
+    .replace(/\/\*[\s\S]*?\*\//g, (m) => m.replace(/[^\n]/g, ' '))
+    .replace(/(^|[^:])\/\/[^\n]*/g, (m, lead) => lead + m.slice(lead.length).replace(/./g, ' '))
+  const findings = []
+  let match
+  LONG_DASH_RE.lastIndex = 0
+  while ((match = LONG_DASH_RE.exec(masked)) !== null) {
+    findings.push({
+      id: 'forbidden-em-dash',
+      line: lineOf(text, match.index),
+      snippet: snippetAt(text, match.index),
+    })
+  }
+  return findings
+}
+
+/**
+ * The Seven text-check set. Every engine iterates this map: the regex engine
+ * runs each check against source text; the static-html and browser engines
+ * run them against the markup and stylesheet text extracted from the
+ * parsed/rendered document. These checks are deliberately text-based.
+ */
+export const CHECKS = {
+  'non-inter-font': checkNonInterFont,
+  'hardcoded-color-not-token': checkHardcodedColorNotToken,
+  'raw-tailwind-palette-color': checkRawTailwindPaletteColor,
+  'missing-color-type-hint': checkMissingColorTypeHint,
+  'missing-length-type-hint': checkMissingLengthTypeHint,
+  'leading-none-with-length-var': checkLeadingNoneWithLengthVar,
+  'fuchsia-in-ui-chrome': checkFuchsiaInUiChrome,
+  'pt-pt-vocab': checkPtPtVocab,
+  'pure-black-or-white': checkPureBlackOrWhite,
+  'emoji-in-chrome': checkEmojiInChrome,
+  'forbidden-em-dash': checkForbiddenEmDash,
+}
+
+/** Run every text check against a text blob, returning raw `{ id, line, snippet }`. */
+export function runChecks(text, ruleIds = null) {
+  const findings = []
+  for (const [id, check] of Object.entries(CHECKS)) {
+    if (ruleIds && !ruleIds.includes(id)) continue
+    findings.push(...check(text))
+  }
+  return findings
+}
+
+// ─── Section 2: pure element checks (computed-style inputs) ──────────────────
+// These run on extracted style props and DOM-only inputs, so they work in both
+// the static-html cascade and a real browser. They take numbers and resolved
+// colors, never raw DOM nodes — the adapters in Section 4/5 do the extraction.
+
+const BORDER_SAFE_TAGS = new Set([
+  'html', 'head', 'body', 'script', 'style', 'link', 'meta', 'title', 'br',
+  'svg', 'path', 'circle', 'rect', 'line', 'polyline', 'polygon', 'g', 'defs', 'use',
+  'table', 'thead', 'tbody', 'tfoot', 'tr', 'th', 'td', 'hr', 'input', 'textarea', 'select',
+])
+const HEADING_TAGS = new Set(['h1', 'h2', 'h3', 'h4', 'h5', 'h6'])
+
+// Seven's two radius stacks, token-grounded from @etus/tokens. Component scale
+// is for buttons/inputs/badges; surface scale is for cards/dialogs/popovers.
+// Mixing them on one element is the `radius-mixed-scales` drift.
+const COMPONENT_RADII = new Set(componentRadiiPx())
+const SURFACE_RADII = new Set(surfaceRadiiPx())
+// The pill/full-radius floor: any radius at or above this is a pill.
+const PILL_RADIUS_MIN = pillRadiiPx()[0] ?? 9999
+
+/**
+ * Side-stripe border check. A border-left or border-right thicker than 1px,
+ * carrying a non-neutral (accent) color, is the banned Seven side stripe.
+ * Top/bottom accents are not the side-stripe pattern and are left alone.
+ */
+function checkBorders(tag, widths, colors) {
+  if (BORDER_SAFE_TAGS.has(tag)) return []
+  const findings = []
+  for (const side of ['Left', 'Right']) {
+    const w = widths[side]
+    if (w <= 1 || isNeutralColor(colors[side])) continue
+    const otherSides = ['Top', 'Right', 'Bottom', 'Left'].filter((s) => s !== side)
+    const maxOther = Math.max(...otherSides.map((s) => widths[s]))
+    // Only a stripe if this side stands out: the others are hairline-or-absent
+    // or this side is at least twice as thick.
+    if (!(maxOther <= 1 || w >= maxOther * 2)) continue
+    findings.push({
+      id: 'side-stripe-border',
+      snippet: `border-${side.toLowerCase()}: ${w}px accent stripe`,
+    })
+  }
+  return findings
+}
+
+/**
+ * Radius-mixed-scales check. A single element resolving border-radius corners
+ * that fall in both the component scale and the surface scale is drift.
+ */
+function checkRadiusMixedScales(tag, cornerRadii) {
+  if (BORDER_SAFE_TAGS.has(tag)) return []
+  const rounded = cornerRadii.map((r) => Math.round(r)).filter((r) => r > 0)
+  const hasComponent = rounded.some((r) => COMPONENT_RADII.has(r))
+  const hasSurface = rounded.some((r) => SURFACE_RADII.has(r))
+  if (hasComponent && hasSurface) {
+    return [{
+      id: 'radius-mixed-scales',
+      snippet: `mixed radius scales: ${[...new Set(rounded)].join('px / ')}px on one element`,
+    }]
+  }
+  return []
+}
+
+const BUTTON_TAGS = new Set(['button'])
+
+/** Pill radius on a button. Buttons stay on the component radius scale. */
+function checkPillOnButton(tag, role, radiusPx, classList) {
+  const isButton = BUTTON_TAGS.has(tag) || role === 'button'
+  if (!isButton) return []
+  const classStr = typeof classList === 'string' ? classList : ''
+  if (radiusPx >= PILL_RADIUS_MIN || /\brounded-full\b/.test(classStr)) {
+    return [{ id: 'pill-on-button', snippet: `pill radius on <${tag}>` }]
+  }
+  return []
+}
+
+const INTERACTIVE_ROLES = new Set(['button', 'link', 'menuitem', 'tab', 'option'])
+
+/**
+ * Tactile-press check. Every Seven affordance gets the system-wide micro-press
+ * — a transform transition that the hover/active states drive. A clickable
+ * element whose transition-property covers neither `transform` nor `all` has
+ * opted out.
+ */
+function checkTactilePress(tag, role, transitionProperty, classList, hasClickHandler) {
+  const isClickable =
+    tag === 'button' ||
+    (tag === 'a' && role === 'button') ||
+    INTERACTIVE_ROLES.has(role) ||
+    hasClickHandler
+  if (!isClickable) return []
+  const props = (transitionProperty || '')
+    .split(',')
+    .map((p) => p.trim().toLowerCase())
+    .filter(Boolean)
+  const classStr = typeof classList === 'string' ? classList : ''
+  const hasTransformTransition =
+    props.includes('transform') ||
+    props.includes('all') ||
+    /\btransition(?:-transform)?\b/.test(classStr)
+  if (hasTransformTransition) return []
+  return [{ id: 'missing-tactile-press', snippet: `clickable <${tag}> with no tactile-press transition` }]
+}
+
+/**
+ * Non-Lucide icon check. Lucide icons use a 24x24 viewBox, 2px stroke, round
+ * caps and joins, and no fill. An inline <svg> that visibly deviates from that
+ * contract is a non-Lucide icon.
+ */
+function checkLucideIcon(viewBox, strokeWidth, strokeLinecap, fill) {
+  // No identifying attributes at all — likely a decorative shape, not an icon.
+  if (!viewBox && !strokeWidth) return []
+  const vb = (viewBox || '').trim()
+  const isLucideViewBox = vb === '' || vb === '0 0 24 24'
+  const sw = strokeWidth != null && strokeWidth !== '' ? parseFloat(strokeWidth) : null
+  const isLucideStroke = sw == null || sw === 2
+  const cap = (strokeLinecap || '').toLowerCase()
+  const isLucideCap = cap === '' || cap === 'round'
+  const f = (fill || '').toLowerCase()
+  const isLucideFill = f === '' || f === 'none'
+  if (isLucideViewBox && isLucideStroke && isLucideCap && isLucideFill) return []
+  const reasons = []
+  if (!isLucideViewBox) reasons.push(`viewBox ${vb}`)
+  if (!isLucideStroke) reasons.push(`stroke-width ${strokeWidth}`)
+  if (!isLucideCap) reasons.push(`stroke-linecap ${cap}`)
+  if (!isLucideFill) reasons.push(`fill ${f}`)
+  return [{ id: 'non-lucide-icon', snippet: `non-Lucide <svg> (${reasons.join(', ')})` }]
+}
+
+/**
+ * Color checks: low-contrast, gray-on-color, gradient-text-decorative, plus a
+ * pure-black background flag and fuchsia chroma on chrome. Background-dependent
+ * checks run against a solid bg or, for gradients, every gradient stop.
+ */
+function checkColors(opts) {
+  const {
+    tag, textColor, bgColor, effectiveBg, fontSize, fontWeight,
+    hasDirectText, isEmojiOnly, bgClip, bgImage, classList,
+  } = opts
+  if (SAFE_TAGS.has(tag)) {
+    const isStyledButton =
+      (tag === 'a' || tag === 'button') && hasDirectText && bgColor && bgColor.a > 0.5
+    if (!isStyledButton) return []
+  }
+  const findings = []
+
+  // Pure black background (solid or near-solid only).
+  if (bgColor && bgColor.a >= 0.9 && bgColor.r === 0 && bgColor.g === 0 && bgColor.b === 0) {
+    findings.push({ id: 'pure-black-or-white', snippet: '#000000 background' })
+  }
+
+  if (hasDirectText && textColor && !isEmojiOnly && effectiveBg) {
+    // Gray text on a colored background.
+    const textLum = relativeLuminance(textColor)
+    const isGray = !hasChroma(textColor, 20) && textLum > 0.05 && textLum < 0.85
+    if (isGray && hasChroma(effectiveBg, 40)) {
+      findings.push({
+        id: 'gray-on-color',
+        snippet: `text ${colorToHex(textColor)} on bg ${colorToHex(effectiveBg)}`,
+      })
+    }
+
+    // Low contrast (WCAG 2.1 AA).
+    const ratio = contrastRatio(textColor, effectiveBg)
+    const isLargeText = fontSize >= 24 || (fontSize >= 18.66 && fontWeight >= 700)
+    const threshold = isLargeText ? 3.0 : 4.5
+    if (ratio < threshold) {
+      findings.push({
+        id: 'low-contrast',
+        snippet: `${ratio.toFixed(1)}:1 (need ${threshold}:1) — text ${colorToHex(textColor)} on ${colorToHex(effectiveBg)}`,
+      })
+    }
+
+    // Fuchsia chroma on UI chrome text.
+    if (isFuchsia(textColor) && tag !== 'svg') {
+      findings.push({ id: 'fuchsia-in-ui-chrome', snippet: `fuchsia text ${colorToHex(textColor)} on chrome` })
+    }
+  }
+
+  // Decorative gradient text.
+  if (bgClip === 'text' && bgImage && bgImage.includes('gradient')) {
+    findings.push({ id: 'gradient-text-decorative', snippet: 'background-clip: text + gradient' })
+  }
+
+  // Tailwind class checks.
+  if (classList) {
+    const classStr = typeof classList === 'string' ? classList : Array.from(classList).join(' ')
+    if (/\bbg-black\b(?!\/)/.test(classStr) || /\bbg-white\b(?!\/)/.test(classStr)) {
+      findings.push({ id: 'pure-black-or-white', snippet: /\bbg-white\b/.test(classStr) ? 'bg-white' : 'bg-black' })
+    }
+    const grayMatch = classStr.match(/\btext-(?:gray|slate|zinc|neutral|stone)-\d+\b/)
+    const colorBgMatch = classStr.match(
+      /\bbg-(?:red|orange|amber|yellow|lime|green|emerald|teal|cyan|sky|blue|indigo|violet|purple|fuchsia|pink|rose)-\d+\b/
+    )
+    if (grayMatch && colorBgMatch) {
+      findings.push({ id: 'gray-on-color', snippet: `${grayMatch[0]} on ${colorBgMatch[0]}` })
+    }
+    if (/\bbg-clip-text\b/.test(classStr) && /\bbg-gradient-to-/.test(classStr)) {
+      findings.push({ id: 'gradient-text-decorative', snippet: 'bg-clip-text + bg-gradient (Tailwind)' })
+    }
+    if (/\bfuchsia-\d/.test(classStr) && /\b(?:bg|text|border|ring)-fuchsia-\d/.test(classStr)) {
+      findings.push({ id: 'fuchsia-in-ui-chrome', snippet: 'fuchsia utility on chrome' })
+    }
+  }
+
+  return findings
+}
+
+function isCardLikeFromProps(hasShadow, hasBorder, hasRadius, hasBg) {
+  if (!hasShadow && !hasBorder) return false
+  return hasRadius || hasBg
+}
+
+const LAYOUT_TRANSITION_PROPS = new Set([
+  'width', 'height', 'padding', 'margin',
+  'max-height', 'max-width', 'min-height', 'min-width',
+  'padding-top', 'padding-right', 'padding-bottom', 'padding-left',
+  'margin-top', 'margin-right', 'margin-bottom', 'margin-left',
+])
+
+/**
+ * True when a cubic-bezier matches a sanctioned Seven easing token. The
+ * catalog declares --ease-bounce and --ease-spring, so an overshooting curve
+ * that IS one of those token values is on-system, not drift.
+ */
+function isSanctionedBezier(a, b, c, d) {
+  return sanctionedEasingBeziers().some(
+    ([x1, y1, x2, y2]) =>
+      Math.abs(x1 - a) < 0.01 &&
+      Math.abs(y1 - b) < 0.01 &&
+      Math.abs(x2 - c) < 0.01 &&
+      Math.abs(y2 - d) < 0.01
+  )
+}
+
+/** Motion checks: bounce/elastic easing and layout-property transitions. */
+function checkMotion(opts) {
+  const { tag, transitionProperty, animationName, timingFunctions, classList } = opts
+  if (SAFE_TAGS.has(tag)) return []
+  const findings = []
+
+  if (animationName && animationName !== 'none' && /bounce|elastic|wobble|jiggle|spring/i.test(animationName)) {
+    findings.push({ id: 'bounce-easing', snippet: `animation: ${animationName}` })
+  }
+  if (classList && /\banimate-bounce\b/.test(classList)) {
+    findings.push({ id: 'bounce-easing', snippet: 'animate-bounce (Tailwind)' })
+  }
+  if (timingFunctions) {
+    const bezierRe = /cubic-bezier\(\s*([\d.-]+)\s*,\s*([\d.-]+)\s*,\s*([\d.-]+)\s*,\s*([\d.-]+)\s*\)/g
+    let m
+    while ((m = bezierRe.exec(timingFunctions)) !== null) {
+      const x1 = parseFloat(m[1])
+      const y1 = parseFloat(m[2])
+      const x2 = parseFloat(m[3])
+      const y2 = parseFloat(m[4])
+      const overshoots = y1 < -0.1 || y1 > 1.1 || y2 < -0.1 || y2 > 1.1
+      if (overshoots && !isSanctionedBezier(x1, y1, x2, y2)) {
+        findings.push({ id: 'bounce-easing', snippet: `cubic-bezier(${m[1]}, ${m[2]}, ${m[3]}, ${m[4]})` })
+        break
+      }
+    }
+  }
+
+  if (transitionProperty && transitionProperty !== 'all' && transitionProperty !== 'none') {
+    const props = transitionProperty.split(',').map((p) => p.trim().toLowerCase())
+    const layoutFound = props.filter((p) => LAYOUT_TRANSITION_PROPS.has(p))
+    if (layoutFound.length > 0) {
+      findings.push({ id: 'layout-transition', snippet: `transition: ${layoutFound.join(', ')}` })
+    }
+  }
+
+  return findings
+}
+
+/**
+ * Glow check. A colored, blurred box-shadow on a dark surface is the AI "dark
+ * glow" look; in Seven, shadows are reserved for overlays and cards carry
+ * hierarchy with borders — so the finding is `shadows-not-borders`.
+ */
+function checkGlow(opts) {
+  const { boxShadow, effectiveBg } = opts
+  if (!boxShadow || boxShadow === 'none') return []
+  if (!effectiveBg) return []
+  const bgLum = relativeLuminance(effectiveBg)
+  if (bgLum >= 0.1) return []
+
+  const parts = boxShadow.split(/,(?![^(]*\))/)
+  for (const shadow of parts) {
+    const colorMatch = shadow.match(/rgba?\([^)]+\)/)
+    if (!colorMatch) continue
+    const color = parseRgb(colorMatch[0])
+    if (!color || !hasChroma(color, 30)) continue
+    const afterColor = shadow.substring(shadow.indexOf(colorMatch[0]) + colorMatch[0].length)
+    const beforeColor = shadow.substring(0, shadow.indexOf(colorMatch[0]))
+    const pxVals = [...beforeColor.matchAll(/([\d.]+)px/g), ...afterColor.matchAll(/([\d.]+)px/g)]
+      .map((m) => parseFloat(m[1]))
+    if (pxVals.length >= 3 && pxVals[2] > 4) {
+      return [{ id: 'shadows-not-borders', snippet: `colored glow (${colorToHex(color)}) on dark surface` }]
+    }
+  }
+  return []
+}
+
+const QUALITY_TEXT_TAGS = new Set(['p', 'li', 'td', 'th', 'dd', 'blockquote', 'figcaption'])
+
+/**
+ * Quality checks on text-bearing elements: line-length, cramped-padding,
+ * body-text-viewport-edge, tight-leading, justified-text, tiny-text,
+ * all-caps-body, wide-tracking. Two checks (line-length, cramped-padding,
+ * body-text-viewport-edge) need element rects; pass `rect: null` to skip them.
+ */
+function checkQuality(opts) {
+  const {
+    el, tag, style, hasDirectText, textLen, fontSize, lineHeightPx, letterSpacingPx,
+    rect, lineMax = 80, viewportWidth = 0,
+  } = opts
+  const findings = []
+
+  if (rect && hasDirectText && QUALITY_TEXT_TAGS.has(tag) && rect.width > 0 && textLen > lineMax) {
+    const charsPerLine = rect.width / (fontSize * 0.5)
+    if (charsPerLine > lineMax + 5) {
+      findings.push({ id: 'line-length', snippet: `~${Math.round(charsPerLine)} chars/line (aim for <${lineMax})` })
+    }
+  }
+
+  if (rect && hasDirectText && textLen > 20 && rect.width > 100 && rect.height > 30) {
+    const borders = {
+      top: parseFloat(style.borderTopWidth) || 0,
+      right: parseFloat(style.borderRightWidth) || 0,
+      bottom: parseFloat(style.borderBottomWidth) || 0,
+      left: parseFloat(style.borderLeftWidth) || 0,
+    }
+    const borderCount = Object.values(borders).filter((w) => w > 0).length
+    const hasBg = style.backgroundColor && style.backgroundColor !== 'rgba(0, 0, 0, 0)'
+    if (borderCount >= 2 || hasBg) {
+      const vPads = []
+      const hPads = []
+      if (hasBg || borders.top > 0) vPads.push(parseFloat(style.paddingTop) || 0)
+      if (hasBg || borders.bottom > 0) vPads.push(parseFloat(style.paddingBottom) || 0)
+      if (hasBg || borders.left > 0) hPads.push(parseFloat(style.paddingLeft) || 0)
+      if (hasBg || borders.right > 0) hPads.push(parseFloat(style.paddingRight) || 0)
+      const vMin = vPads.length ? Math.min(...vPads) : Infinity
+      const hMin = hPads.length ? Math.min(...hPads) : Infinity
+      const vThresh = Math.max(4, fontSize * 0.3)
+      const hThresh = Math.max(8, fontSize * 0.5)
+      if (vMin < vThresh) {
+        findings.push({ id: 'cramped-padding', snippet: `${vMin}px vertical padding (need >=${vThresh.toFixed(1)}px for ${fontSize}px text)` })
+      } else if (hMin < hThresh) {
+        findings.push({ id: 'cramped-padding', snippet: `${hMin}px horizontal padding (need >=${hThresh.toFixed(1)}px for ${fontSize}px text)` })
+      }
+    }
+  }
+
+  if (rect && hasDirectText && textLen > 40 && ['P', 'LI'].includes(tag.toUpperCase()) && viewportWidth > 0) {
+    const inNavHeader = el.closest && (el.closest('nav') || el.closest('header'))
+    const hasOwnBg =
+      style.backgroundColor && style.backgroundColor !== 'rgba(0, 0, 0, 0)' && style.backgroundColor !== 'transparent'
+    const isPositioned = ['fixed', 'absolute'].includes(style.position || '')
+    const widthRatio = rect.width / viewportWidth
+    const leftClose = rect.left < 16
+    const rightClose = rect.right > viewportWidth - 16
+    if (!inNavHeader && !hasOwnBg && !isPositioned && widthRatio > 0.5 && (leftClose || rightClose)) {
+      const which =
+        leftClose && rightClose
+          ? `left ${Math.round(rect.left)}px / right ${Math.round(viewportWidth - rect.right)}px`
+          : leftClose
+            ? `left ${Math.round(rect.left)}px`
+            : `right ${Math.round(viewportWidth - rect.right)}px`
+      findings.push({
+        id: 'body-text-viewport-edge',
+        snippet: `<${tag.toLowerCase()}> with ${textLen}-char body bleeds to viewport edge (${which})`,
+      })
+    }
+  }
+
+  if (hasDirectText && textLen > 50 && !HEADING_TAGS.has(tag)) {
+    if (lineHeightPx != null && fontSize > 0) {
+      const ratio = lineHeightPx / fontSize
+      if (ratio > 0 && ratio < 1.3) {
+        findings.push({ id: 'tight-leading', snippet: `line-height ${ratio.toFixed(2)}x (need >=1.3)` })
+      }
+    }
+  }
+
+  if (hasDirectText && style.textAlign === 'justify') {
+    const hyphens = style.hyphens || style.webkitHyphens || ''
+    if (hyphens !== 'auto') {
+      findings.push({ id: 'justified-text', snippet: 'text-align: justify without hyphens: auto' })
+    }
+  }
+
+  // Token-grounded: the floor is the smallest @etus/tokens font-size token.
+  if (hasDirectText && textLen > 20 && fontSize < minFontSizePx()) {
+    const skipTags = ['sub', 'sup', 'code', 'kbd', 'samp', 'var', 'caption', 'figcaption']
+    const inUIContext =
+      el.closest &&
+      el.closest(
+        'button, a, label, summary, [role="button"], [role="link"], [role="tab"], [role="menuitem"], [role="option"], nav, footer, [class*="badge" i], [class*="chip" i], [class*="pill" i], [class*="tag" i], [class*="label" i], [class*="caption" i]'
+      )
+    const isUppercase = style.textTransform === 'uppercase'
+    if (!skipTags.includes(tag) && !inUIContext && !isUppercase) {
+      findings.push({ id: 'tiny-text', snippet: `${fontSize}px body text` })
+    }
+  }
+
+  if (hasDirectText && textLen > 30 && style.textTransform === 'uppercase' && !HEADING_TAGS.has(tag)) {
+    findings.push({ id: 'all-caps-body', snippet: `text-transform: uppercase on ${textLen} chars of body text` })
+  }
+
+  if (hasDirectText && textLen > 20 && style.textTransform !== 'uppercase') {
+    if (letterSpacingPx != null && letterSpacingPx > 0 && fontSize > 0) {
+      const trackingEm = letterSpacingPx / fontSize
+      if (trackingEm > 0.05) {
+        findings.push({ id: 'wide-tracking', snippet: `letter-spacing: ${trackingEm.toFixed(2)}em on body text` })
+      }
+    }
+  }
+
+  return findings
+}
+
+// ─── Section 3: regex-on-HTML page checks ───────────────────────────────────
+
+/**
+ * Page-level checks that read the raw HTML string with no DOM access. Shared
+ * by the static-html and browser engines.
+ */
+export function checkHtmlPatterns(html) {
+  const findings = []
+
+  // Pure black background.
+  if (/background(?:-color)?\s*:\s*(?:#000000|#000|rgb\(\s*0,\s*0,\s*0\s*\))\b/gi.test(html)) {
+    findings.push({ id: 'pure-black-or-white', snippet: 'Pure #000 background' })
+  }
+
+  // Decorative gradient text.
+  const gradientRe = /(?:-webkit-)?background-clip\s*:\s*text/gi
+  let gm
+  while ((gm = gradientRe.exec(html)) !== null) {
+    const start = Math.max(0, gm.index - 200)
+    const context = html.substring(start, gm.index + gm[0].length + 200)
+    if (/gradient/i.test(context)) {
+      findings.push({ id: 'gradient-text-decorative', snippet: 'background-clip: text + gradient' })
+      break
+    }
+  }
+  if (/\bbg-clip-text\b/.test(html) && /\bbg-gradient-to-/.test(html)) {
+    findings.push({ id: 'gradient-text-decorative', snippet: 'bg-clip-text + bg-gradient (Tailwind)' })
+  }
+
+  // Monotonous spacing.
+  const spacingValues = []
+  let sm
+  const spacingRe = /(?:padding|margin)(?:-(?:top|right|bottom|left))?\s*:\s*(\d+)px/gi
+  while ((sm = spacingRe.exec(html)) !== null) {
+    const v = parseInt(sm[1], 10)
+    if (v > 0 && v < 200) spacingValues.push(v)
+  }
+  const gapRe = /gap\s*:\s*(\d+)px/gi
+  while ((sm = gapRe.exec(html)) !== null) spacingValues.push(parseInt(sm[1], 10))
+  const twSpaceRe = /\b(?:p|px|py|pt|pb|pl|pr|m|mx|my|mt|mb|ml|mr|gap)-(\d+)\b/g
+  while ((sm = twSpaceRe.exec(html)) !== null) spacingValues.push(parseInt(sm[1], 10) * 4)
+  const remSpacingRe = /(?:padding|margin)(?:-(?:top|right|bottom|left))?\s*:\s*([\d.]+)rem/gi
+  while ((sm = remSpacingRe.exec(html)) !== null) {
+    const v = Math.round(parseFloat(sm[1]) * 16)
+    if (v > 0 && v < 200) spacingValues.push(v)
+  }
+  const roundedSpacing = spacingValues.map((v) => Math.round(v / 4) * 4)
+  if (roundedSpacing.length >= 10) {
+    const counts = {}
+    for (const v of roundedSpacing) counts[v] = (counts[v] || 0) + 1
+    const maxCount = Math.max(...Object.values(counts))
+    const dominantPct = maxCount / roundedSpacing.length
+    const unique = [...new Set(roundedSpacing)].filter((v) => v > 0)
+    if (dominantPct > 0.6 && unique.length <= 3) {
+      const dominant = Object.entries(counts).sort((a, b) => b[1] - a[1])[0][0]
+      findings.push({
+        id: 'monotonous-spacing',
+        snippet: `~${dominant}px used ${maxCount}/${roundedSpacing.length} times (${Math.round(dominantPct * 100)}%)`,
+      })
+    }
+  }
+
+  // Bounce / elastic animation names.
+  if (/animation(?:-name)?\s*:\s*[^;]*\b(bounce|elastic|wobble|jiggle|spring)\b/gi.test(html)) {
+    findings.push({ id: 'bounce-easing', snippet: 'Bounce/elastic animation in CSS' })
+  }
+  const bezierRe = /cubic-bezier\(\s*([\d.-]+)\s*,\s*([\d.-]+)\s*,\s*([\d.-]+)\s*,\s*([\d.-]+)\s*\)/g
+  let bm
+  while ((bm = bezierRe.exec(html)) !== null) {
+    const x1 = parseFloat(bm[1])
+    const y1 = parseFloat(bm[2])
+    const x2 = parseFloat(bm[3])
+    const y2 = parseFloat(bm[4])
+    const overshoots = y1 < -0.1 || y1 > 1.1 || y2 < -0.1 || y2 > 1.1
+    if (overshoots && !isSanctionedBezier(x1, y1, x2, y2)) {
+      findings.push({ id: 'bounce-easing', snippet: `cubic-bezier(${bm[1]}, ${bm[2]}, ${bm[3]}, ${bm[4]})` })
+      break
+    }
+  }
+
+  // Layout-property transitions.
+  const transRe = /transition(?:-property)?\s*:\s*([^;{}]+)/gi
+  let tm
+  while ((tm = transRe.exec(html)) !== null) {
+    const val = tm[1].toLowerCase()
+    if (/\ball\b/.test(val)) continue
+    const found = val.match(/\b(?:(?:max|min)-)?(?:width|height)\b|\bpadding(?:-(?:top|right|bottom|left))?\b|\bmargin(?:-(?:top|right|bottom|left))?\b/gi)
+    if (found) {
+      findings.push({ id: 'layout-transition', snippet: `transition: ${found.join(', ')}` })
+      break
+    }
+  }
+
+  // Glow on a dark surface.
+  const darkBgRe = /background(?:-color)?\s*:\s*(?:#(?:0[0-9a-f]|1[0-9a-f]|2[0-3])[0-9a-f]{4}\b|#(?:0|1)[0-9a-f]{2}\b|rgb\(\s*(\d{1,2})\s*,\s*(\d{1,2})\s*,\s*(\d{1,2})\s*\))/gi
+  const twDarkBg = /\bbg-(?:gray|slate|zinc|neutral|stone)-(?:9\d{2}|800)\b/
+  if (darkBgRe.test(html) || twDarkBg.test(html)) {
+    const shadowRe = /box-shadow\s*:\s*([^;{}]+)/gi
+    let shm
+    while ((shm = shadowRe.exec(html)) !== null) {
+      const val = shm[1]
+      const colorMatch = val.match(/rgba?\(\s*(\d+)\s*,\s*(\d+)\s*,\s*(\d+)/)
+      if (!colorMatch) continue
+      const [r, g, b] = [+colorMatch[1], +colorMatch[2], +colorMatch[3]]
+      if (Math.max(r, g, b) - Math.min(r, g, b) < 30) continue
+      const pxVals = [...val.matchAll(/(\d+)px|(?<![.\d])\b(0)\b(?![.\d])/g)].map((p) => +(p[1] || p[2]))
+      if (pxVals.length >= 3 && pxVals[2] > 4) {
+        findings.push({ id: 'shadows-not-borders', snippet: `colored glow (rgb(${r},${g},${b})) on dark page` })
+        break
+      }
+    }
+  }
+
+  return findings
+}
+
+// ─── Section 4: background resolution ───────────────────────────────────────
+
+function readOwnBackgroundColor(el, computedStyle) {
+  const bg = parseRgb(computedStyle.backgroundColor)
+  if (DETECTOR_IS_BROWSER || (bg && bg.a >= 0.1)) return bg
+  const rawStyle = el.getAttribute?.('style') || ''
+  const bgMatch = rawStyle.match(/background(?:-color)?\s*:\s*([^;]+)/i)
+  const inlineBg = bgMatch ? bgMatch[1].trim() : ''
+  if (!inlineBg) return bg
+  if (/gradient/i.test(inlineBg) || /url\s*\(/i.test(inlineBg)) return bg
+  const fromRgb = parseRgb(inlineBg)
+  if (fromRgb) return fromRgb
+  const hexMatch = inlineBg.match(/#([0-9a-f]{6}|[0-9a-f]{3})\b/i)
+  if (hexMatch) {
+    const h = hexMatch[1]
+    if (h.length === 6) {
+      return { r: parseInt(h.slice(0, 2), 16), g: parseInt(h.slice(2, 4), 16), b: parseInt(h.slice(4, 6), 16), a: 1 }
+    }
+    return { r: parseInt(h[0] + h[0], 16), g: parseInt(h[1] + h[1], 16), b: parseInt(h[2] + h[2], 16), a: 1 }
+  }
+  return bg
+}
+
+/**
+ * Walk the ancestor chain for the first opaque background color. Body/html
+ * gradients are treated as decorative and resolve to white; on other elements
+ * a gradient with no underlying solid color bails to null.
+ */
+export function resolveBackground(el, win) {
+  let current = el
+  while (current && current.nodeType === 1) {
+    const style = DETECTOR_IS_BROWSER ? getComputedStyle(current) : win.getComputedStyle(current)
+    const bgImage = style.backgroundImage || ''
+    const hasGradientOrUrl =
+      bgImage && bgImage !== 'none' && (/gradient/i.test(bgImage) || /url\s*\(/i.test(bgImage))
+    const bg = parseRgb(style.backgroundColor)
+    if (bg && bg.a > 0.1) {
+      if (DETECTOR_IS_BROWSER || bg.a >= 0.5) return bg
+    }
+    if (hasGradientOrUrl) {
+      if (current.tagName === 'BODY' || current.tagName === 'HTML') {
+        return { r: 255, g: 255, b: 255, a: 1 }
+      }
+      return null
+    }
+    current = current.parentElement
+  }
+  return { r: 255, g: 255, b: 255, a: 1 }
+}
+
+// Parse a single CSS length token to pixels.
+function parseRadiusToPx(value, widthPx) {
+  if (!value || typeof value !== 'string') return null
+  const trimmed = value.trim()
+  if (!trimmed) return null
+  const first = trimmed.split(/\s+/)[0]
+  const num = parseFloat(first)
+  if (Number.isNaN(num)) return null
+  if (/%$/.test(first)) {
+    if (widthPx && widthPx > 0) return (num / 100) * widthPx
+    return num
+  }
+  return num
+}
+
+export function resolveBorderRadiusPx(el, style, widthPx) {
+  const fromComputed = parseRadiusToPx(style.borderRadius, widthPx)
+  if (fromComputed !== null) return fromComputed
+  return 0
+}
+
+// Resolve var(--X[, fallback]) refs in a value string against a custom-prop
+// map. Recurses up to 8 levels for chained refs. Returns the original string
+// when no refs are present or the chain does not resolve. The static CSS
+// cascade depends on this to resolve Tailwind v4 token wrappers.
+export function resolveVarRefs(raw, customPropMap, depth = 0) {
+  if (typeof raw !== 'string' || !raw.includes('var(')) return raw
+  if (depth > 8) return raw
+  return raw.replace(/var\(\s*(--[a-zA-Z0-9_-]+)\s*(?:,\s*([^)]+))?\)/g, (full, name, fallback) => {
+    const v = customPropMap && (customPropMap.get ? customPropMap.get(name) : customPropMap[name])
+    if (v != null) return resolveVarRefs(v, customPropMap, depth + 1)
+    return fallback ? resolveVarRefs(fallback.trim(), customPropMap, depth + 1) : full
+  })
+}
+
+// OKLCH -> sRGB conversion (Bjorn Ottosson's matrices). L in 0..1 (or %),
+// C typically 0..~0.4, H in degrees. Returns clamped {r,g,b,a:1} in 0..255.
+// Needed because the static cascade cannot compute oklch() — and Seven's
+// token ramp is OKLCH throughout, so without this the palette is invisible
+// to the contrast and color checks.
+export function oklchToRgb(L, C, H) {
+  const hRad = (H * Math.PI) / 180
+  const a = C * Math.cos(hRad)
+  const b = C * Math.sin(hRad)
+  const l_ = L + 0.3963377774 * a + 0.2158037573 * b
+  const m_ = L - 0.1055613458 * a - 0.0638541728 * b
+  const s_ = L - 0.0894841775 * a - 1.291485548 * b
+  const lc = l_ * l_ * l_
+  const mc = m_ * m_ * m_
+  const sc = s_ * s_ * s_
+  const rLin = 4.0767416621 * lc - 3.3077115913 * mc + 0.2309699292 * sc
+  const gLin = -1.2684380046 * lc + 2.6097574011 * mc - 0.3413193965 * sc
+  const bLin = -0.0041960863 * lc - 0.7034186147 * mc + 1.707614701 * sc
+  const enc = (x) => {
+    const c = Math.max(0, Math.min(1, x))
+    return c <= 0.0031308 ? 12.92 * c : 1.055 * Math.pow(c, 1 / 2.4) - 0.055
+  }
+  return {
+    r: Math.round(enc(rLin) * 255),
+    g: Math.round(enc(gLin) * 255),
+    b: Math.round(enc(bLin) * 255),
+    a: 1,
+  }
+}
+
+// Extended color parser: rgb/rgba/hex/oklch. Returns null on no match. Used
+// by the static cascade where a value might be any CSS color form.
+export function parseAnyColor(s) {
+  if (!s || typeof s !== 'string') return null
+  const str = s.trim()
+  if (str === 'transparent' || str === 'currentcolor' || str === 'inherit') return null
+  let m
+  m = str.match(/rgba?\(\s*(\d+(?:\.\d+)?)\s*,?\s*(\d+(?:\.\d+)?)\s*,?\s*(\d+(?:\.\d+)?)(?:\s*[,/]\s*([\d.]+))?\s*\)/)
+  if (m) {
+    return { r: Math.round(+m[1]), g: Math.round(+m[2]), b: Math.round(+m[3]), a: m[4] !== undefined ? +m[4] : 1 }
+  }
+  m = str.match(/^#([0-9a-f]{3,8})$/i)
+  if (m) {
+    const h = m[1]
+    if (h.length === 3 || h.length === 4) {
+      return {
+        r: parseInt(h[0] + h[0], 16),
+        g: parseInt(h[1] + h[1], 16),
+        b: parseInt(h[2] + h[2], 16),
+        a: h.length === 4 ? parseInt(h[3] + h[3], 16) / 255 : 1,
+      }
+    }
+    if (h.length === 6 || h.length === 8) {
+      return {
+        r: parseInt(h.slice(0, 2), 16),
+        g: parseInt(h.slice(2, 4), 16),
+        b: parseInt(h.slice(4, 6), 16),
+        a: h.length === 8 ? parseInt(h.slice(6, 8), 16) / 255 : 1,
+      }
+    }
+  }
+  // OKLCH — the CSS minifier may drop the space after `%`, so the L/C
+  // separator can be absent. Match L (optional %), then C and H permissively.
+  m = str.match(/oklch\(\s*([\d.]+)(%?)\s*[\s,]*\s*([\d.]+)\s*[\s,]+\s*([-\d.]+)(?:deg)?\s*\)/i)
+  if (m) {
+    const Lnum = parseFloat(m[1])
+    const L = m[2] === '%' ? Lnum / 100 : Lnum
+    return oklchToRgb(L, parseFloat(m[3]), parseFloat(m[4]))
+  }
+  return null
+}
+
+// Resolve a CSS length value (line-height, letter-spacing, etc.) given a
+// font-size context. Returns null for "normal" / unparseable values.
+export function resolveLengthPx(value, fontSizePx) {
+  if (!value || value === 'normal' || value === 'auto' || value === 'inherit') return null
+  const num = parseFloat(value)
+  if (Number.isNaN(num)) return null
+  if (value.endsWith('px')) return num
+  if (value.endsWith('rem')) return num * 16
+  if (value.endsWith('em')) return num * fontSizePx
+  if (value.endsWith('%')) return (num / 100) * fontSizePx
+  return num * fontSizePx
+}
+
+// Resolve a CSS font-size value to pixels by walking up the parent chain.
+function resolveFontSizePx(el, win) {
+  const chain = []
+  let cur = el
+  while (cur && cur.nodeType === 1) {
+    const fs = (win ? win.getComputedStyle(cur) : getComputedStyle(cur)).fontSize
+    chain.push(fs || '')
+    cur = cur.parentElement
+  }
+  let px = 16
+  for (let i = chain.length - 1; i >= 0; i--) {
+    const v = chain[i]
+    if (!v || v === 'inherit') continue
+    const num = parseFloat(v)
+    if (Number.isNaN(num)) continue
+    if (v.endsWith('px')) px = num
+    else if (v.endsWith('rem')) px = num * 16
+    else if (v.endsWith('em')) px = num * px
+    else if (v.endsWith('%')) px = (num / 100) * px
+    else px = num
+  }
+  return px
+}
+
+// Collect every corner radius a style resolves. A real browser exposes each
+// corner as a longhand; the static cascade stores `border-radius` verbatim,
+// which may be a multi-value shorthand (`8px 8px 24px 24px`). Both forms are
+// handled so the mixed-scales check sees all four corners.
+function collectCornerRadii(style, widthPx) {
+  const corners = [
+    style.borderTopLeftRadius,
+    style.borderTopRightRadius,
+    style.borderBottomLeftRadius,
+    style.borderBottomRightRadius,
+  ].filter((v) => v != null && v !== '')
+  if (corners.length > 0) {
+    return corners.map((v) => parseRadiusToPx(v, widthPx) || 0)
+  }
+  // Shorthand string: split on `/` (horizontal / vertical radii) then on
+  // whitespace, parsing each token independently.
+  const raw = typeof style.borderRadius === 'string' ? style.borderRadius.trim() : ''
+  if (!raw) return [0]
+  const tokens = raw
+    .split('/')
+    .join(' ')
+    .split(/\s+/)
+    .filter(Boolean)
+  if (tokens.length <= 1) {
+    return [parseRadiusToPx(raw, widthPx) || 0]
+  }
+  return tokens.map((t) => parseRadiusToPx(t, widthPx) || 0)
+}
+
+// ─── Section 5: browser element adapters (live DOM) ─────────────────────────
+
+export function checkElementBordersDOM(el) {
+  const tag = el.tagName.toLowerCase()
+  if (BORDER_SAFE_TAGS.has(tag)) return []
+  const rect = el.getBoundingClientRect()
+  if (rect.width < 20 || rect.height < 20) return []
+  const style = getComputedStyle(el)
+  const widths = {}
+  const colors = {}
+  for (const s of ['Top', 'Right', 'Bottom', 'Left']) {
+    widths[s] = parseFloat(style[`border${s}Width`]) || 0
+    colors[s] = style[`border${s}Color`] || ''
+  }
+  const findings = checkBorders(tag, widths, colors)
+  findings.push(...checkRadiusMixedScales(tag, collectCornerRadii(style, rect.width)))
+  return findings
+}
+
+export function checkElementColorsDOM(el) {
+  const tag = el.tagName.toLowerCase()
+  const rect = el.getBoundingClientRect()
+  if (rect.width < 10 || rect.height < 10) return []
+  const style = getComputedStyle(el)
+  const directText = [...el.childNodes].filter((n) => n.nodeType === 3).map((n) => n.textContent).join('')
+  const hasDirectText = directText.trim().length > 0
+  return checkColors({
+    tag,
+    textColor: parseRgb(style.color),
+    bgColor: readOwnBackgroundColor(el, style),
+    effectiveBg: resolveBackground(el),
+    fontSize: parseFloat(style.fontSize) || 16,
+    fontWeight: parseInt(style.fontWeight) || 400,
+    hasDirectText,
+    isEmojiOnly: isEmojiOnlyText(directText),
+    bgClip: style.webkitBackgroundClip || style.backgroundClip || '',
+    bgImage: style.backgroundImage || '',
+    classList: el.getAttribute('class') || '',
+  })
+}
+
+export function checkElementGlowDOM(el) {
+  const tag = el.tagName.toLowerCase()
+  const style = getComputedStyle(el)
+  if (!style.boxShadow || style.boxShadow === 'none') return []
+  const parentBg = el.parentElement ? resolveBackground(el.parentElement) : resolveBackground(el)
+  return checkGlow({ tag, boxShadow: style.boxShadow, effectiveBg: parentBg })
+}
+
+export function checkElementMotionDOM(el) {
+  const tag = el.tagName.toLowerCase()
+  if (SAFE_TAGS.has(tag)) return []
+  const style = getComputedStyle(el)
+  return checkMotion({
+    tag,
+    transitionProperty: style.transitionProperty || '',
+    animationName: style.animationName || '',
+    timingFunctions: [style.animationTimingFunction, style.transitionTimingFunction].filter(Boolean).join(' '),
+    classList: el.getAttribute('class') || '',
+  })
+}
+
+export function checkElementTactilePressDOM(el) {
+  const tag = el.tagName.toLowerCase()
+  const style = getComputedStyle(el)
+  return checkTactilePress(
+    tag,
+    (el.getAttribute('role') || '').toLowerCase(),
+    style.transitionProperty || '',
+    el.getAttribute('class') || '',
+    el.hasAttribute && el.hasAttribute('onclick')
+  )
+}
+
+export function checkElementPillOnButtonDOM(el) {
+  const tag = el.tagName.toLowerCase()
+  const style = getComputedStyle(el)
+  const rect = el.getBoundingClientRect()
+  return checkPillOnButton(
+    tag,
+    (el.getAttribute('role') || '').toLowerCase(),
+    resolveBorderRadiusPx(el, style, rect.width),
+    el.getAttribute('class') || ''
+  )
+}
+
+export function checkElementLucideIconDOM(el) {
+  if (el.tagName.toLowerCase() !== 'svg') return []
+  return checkLucideIcon(
+    el.getAttribute('viewBox') || '',
+    el.getAttribute('stroke-width') || '',
+    el.getAttribute('stroke-linecap') || '',
+    el.getAttribute('fill') || ''
+  )
+}
+
+export function checkElementQualityDOM(el) {
+  const tag = el.tagName.toLowerCase()
+  const style = getComputedStyle(el)
+  const hasDirectText = [...el.childNodes].some((n) => n.nodeType === 3 && n.textContent.trim().length > 10)
+  const textLen = el.textContent?.trim().length || 0
+  const fontSize = parseFloat(style.fontSize) || 16
+  const lineHeightPx = resolveLengthPx(style.lineHeight, fontSize)
+  const letterSpacingPx = resolveLengthPx(style.letterSpacing, fontSize)
+  const rect = el.getBoundingClientRect()
+  const viewportWidth = typeof window !== 'undefined' ? window.innerWidth || 0 : 0
+  return checkQuality({
+    el, tag, style, hasDirectText, textLen, fontSize, lineHeightPx, letterSpacingPx, rect, viewportWidth,
+  })
+}
+
+export function checkPageQualityDOM() {
+  return checkPageQualityFromDoc(document).map((f) => ({ type: f.id, detail: f.snippet }))
+}
+
+// ─── Section 6: Node element adapters (static cascade) ──────────────────────
+
+export function checkElementBorders(tag, style, overrides) {
+  const sides = ['Top', 'Right', 'Bottom', 'Left']
+  const widths = {}
+  const colors = {}
+  for (const s of sides) {
+    widths[s] = parseFloat(style[`border${s}Width`]) || 0
+    colors[s] = style[`border${s}Color`] || ''
+    // The static cascade may drop a var()-bearing border shorthand; the
+    // pre-pass override fills the missing side so the side-stripe check runs.
+    if (widths[s] === 0 && overrides && overrides[s]) {
+      widths[s] = overrides[s].width
+      colors[s] = overrides[s].color
+    } else if (colors[s] && colors[s].startsWith('var(') && overrides && overrides[s]) {
+      colors[s] = overrides[s].color
+    }
+  }
+  const findings = checkBorders(tag, widths, colors)
+  findings.push(...checkRadiusMixedScales(tag, collectCornerRadii(style, parseFloat(style.width) || 0)))
+  return findings
+}
+
+export function checkElementColors(el, style, tag, window) {
+  const directText = [...el.childNodes].filter((n) => n.nodeType === 3).map((n) => n.textContent).join('')
+  const hasDirectText = directText.trim().length > 0
+  return checkColors({
+    tag,
+    textColor: parseRgb(style.color),
+    bgColor: readOwnBackgroundColor(el, style),
+    effectiveBg: resolveBackground(el, window),
+    fontSize: parseFloat(style.fontSize) || 16,
+    fontWeight: parseInt(style.fontWeight) || 400,
+    hasDirectText,
+    isEmojiOnly: isEmojiOnlyText(directText),
+    bgClip: style.webkitBackgroundClip || style.backgroundClip || '',
+    bgImage: style.backgroundImage || '',
+    classList: el.getAttribute?.('class') || el.className || '',
+  })
+}
+
+export function checkElementGlow(tag, style, effectiveBg) {
+  if (!style.boxShadow || style.boxShadow === 'none') return []
+  return checkGlow({ tag, boxShadow: style.boxShadow, effectiveBg })
+}
+
+export function checkElementMotion(tag, style) {
+  return checkMotion({
+    tag,
+    transitionProperty: style.transitionProperty || '',
+    animationName: style.animationName || '',
+    timingFunctions: [style.animationTimingFunction, style.transitionTimingFunction].filter(Boolean).join(' '),
+    classList: '',
+  })
+}
+
+export function checkElementTactilePress(el, style, tag) {
+  return checkTactilePress(
+    tag,
+    (el.getAttribute?.('role') || '').toLowerCase(),
+    style.transitionProperty || '',
+    el.getAttribute?.('class') || '',
+    !!el.getAttribute?.('onclick')
+  )
+}
+
+export function checkElementPillOnButton(el, style, tag) {
+  return checkPillOnButton(
+    tag,
+    (el.getAttribute?.('role') || '').toLowerCase(),
+    resolveBorderRadiusPx(el, style, parseFloat(style.width) || 0),
+    el.getAttribute?.('class') || ''
+  )
+}
+
+export function checkElementLucideIcon(el, tag) {
+  if (tag !== 'svg') return []
+  return checkLucideIcon(
+    el.getAttribute?.('viewBox') || '',
+    el.getAttribute?.('stroke-width') || '',
+    el.getAttribute?.('stroke-linecap') || '',
+    el.getAttribute?.('fill') || ''
+  )
+}
+
+export function checkElementQuality(el, style, tag, window) {
+  const hasDirectText = [...el.childNodes].some((n) => n.nodeType === 3 && n.textContent.trim().length > 10)
+  const textLen = el.textContent?.trim().length || 0
+  const fontSize = resolveFontSizePx(el, window)
+  const lineHeightPx = resolveLengthPx(style.lineHeight, fontSize)
+  const letterSpacingPx = resolveLengthPx(style.letterSpacing, fontSize)
+  // The static cascade does no layout — pass rect: null to skip the three
+  // rect-dependent rules (line-length, cramped-padding, body-text-viewport-edge).
+  return checkQuality({ el, tag, style, hasDirectText, textLen, fontSize, lineHeightPx, letterSpacingPx, rect: null })
+}
+
+// ─── Section 7: page-level checks ───────────────────────────────────────────
+
+/** Skipped-heading walk. Works on any Document (browser or static). */
+export function checkPageQualityFromDoc(doc) {
+  const findings = []
+  const headings = doc.querySelectorAll('h1, h2, h3, h4, h5, h6')
+  let prevLevel = 0
+  let prevText = ''
+  for (const h of headings) {
+    const level = parseInt(h.tagName[1])
+    const text = (h.textContent || '').trim().replace(/\s+/g, ' ').slice(0, 60)
+    if (prevLevel > 0 && level > prevLevel + 1) {
+      findings.push({
+        id: 'skipped-heading',
+        snippet: `<h${prevLevel}> "${prevText}" followed by <h${level}> "${text}" (missing h${prevLevel + 1})`,
+      })
+    }
+    prevLevel = level
+    prevText = text
+  }
+  return findings
+}
+
+/** Flat-type-hierarchy page check. */
+export function checkPageTypography(doc, win) {
+  const findings = []
+  const sizes = new Set()
+  for (const el of doc.querySelectorAll('h1, h2, h3, h4, h5, h6, p, span, a, li, td, th, label, button, div')) {
+    const fontSize = parseFloat(win.getComputedStyle(el).fontSize)
+    if (fontSize >= 8 && fontSize < 200) sizes.add(Math.round(fontSize * 10) / 10)
+  }
+  if (sizes.size >= 3) {
+    const sorted = [...sizes].sort((a, b) => a - b)
+    const ratio = sorted[sorted.length - 1] / sorted[0]
+    if (ratio < 2.0) {
+      findings.push({
+        id: 'flat-type-hierarchy',
+        snippet: `Sizes: ${sorted.map((s) => s + 'px').join(', ')} (ratio ${ratio.toFixed(1)}:1)`,
+      })
+    }
+  }
+  return findings
+}
+
+function isCardLike(el, win) {
+  const tag = el.tagName.toLowerCase()
+  if (SAFE_TAGS.has(tag) || ['input', 'select', 'textarea', 'img', 'video', 'canvas', 'picture'].includes(tag)) {
+    return false
+  }
+  const style = win.getComputedStyle(el)
+  const rawStyle = el.getAttribute?.('style') || ''
+  const cls = el.getAttribute?.('class') || ''
+  const hasShadow =
+    (style.boxShadow && style.boxShadow !== 'none') ||
+    /\bshadow(?:-sm|-md|-lg|-xl|-2xl)?\b/.test(cls) ||
+    /box-shadow/i.test(rawStyle)
+  const hasBorder = /\bborder\b/.test(cls) || (parseFloat(style.borderTopWidth) || 0) > 0
+  const widthPx = parseFloat(style.width) || 0
+  const hasRadius =
+    resolveBorderRadiusPx(el, style, widthPx) > 0 ||
+    /\brounded(?:-sm|-md|-lg|-xl|-2xl|-full)?\b/.test(cls) ||
+    /border-radius/i.test(rawStyle)
+  const hasBg =
+    /\bbg-(?:white|gray-\d+|slate-\d+)\b/.test(cls) ||
+    /background(?:-color)?\s*:\s*(?!transparent)/i.test(rawStyle) ||
+    (style.backgroundColor && style.backgroundColor !== 'rgba(0, 0, 0, 0)')
+  return isCardLikeFromProps(hasShadow, hasBorder, hasRadius, hasBg)
+}
+
+/** Nested-cards and everything-centered page checks. */
+export function checkPageLayout(doc, win) {
+  const findings = []
+
+  const allEls = doc.querySelectorAll('*')
+  const flaggedEls = new Set()
+  for (const el of allEls) {
+    if (!isCardLike(el, win)) continue
+    if (flaggedEls.has(el)) continue
+    const tag = el.tagName.toLowerCase()
+    const cls = el.getAttribute?.('class') || ''
+    const rawStyle = el.getAttribute?.('style') || ''
+    if (['pre', 'code'].includes(tag)) continue
+    if (/\b(?:absolute|fixed)\b/.test(cls) || /position\s*:\s*(?:absolute|fixed)/i.test(rawStyle)) continue
+    if ((el.textContent?.trim().length || 0) < 10) continue
+    if (/\b(?:dropdown|popover|tooltip|menu|modal|dialog)\b/i.test(cls)) continue
+    let parent = el.parentElement
+    while (parent) {
+      if (isCardLike(parent, win)) {
+        flaggedEls.add(el)
+        break
+      }
+      parent = parent.parentElement
+    }
+  }
+  for (const el of flaggedEls) {
+    let isAncestorOfFlagged = false
+    for (const other of flaggedEls) {
+      if (other !== el && el.contains(other)) {
+        isAncestorOfFlagged = true
+        break
+      }
+    }
+    if (!isAncestorOfFlagged) {
+      findings.push({ id: 'nested-cards', snippet: `Card inside card (${el.tagName.toLowerCase()})` })
+    }
+  }
+
+  const textEls = doc.querySelectorAll('h1, h2, h3, h4, h5, h6, p, li, div, button')
+  let centeredCount = 0
+  let totalText = 0
+  for (const el of textEls) {
+    const hasDirectText = [...el.childNodes].some((n) => n.nodeType === 3 && n.textContent.trim().length >= 3)
+    if (!hasDirectText) continue
+    totalText++
+    let cur = el
+    let isCentered = false
+    while (cur && cur.nodeType === 1) {
+      const rawStyle = cur.getAttribute?.('style') || ''
+      const cls = cur.getAttribute?.('class') || ''
+      if (/text-align\s*:\s*center/i.test(rawStyle) || /\btext-center\b/.test(cls)) {
+        isCentered = true
+        break
+      }
+      if (cur.tagName === 'BODY') break
+      cur = cur.parentElement
+    }
+    if (isCentered) centeredCount++
+  }
+  if (totalText >= 5 && centeredCount / totalText > 0.7) {
+    findings.push({
+      id: 'everything-centered',
+      snippet: `${centeredCount}/${totalText} text elements centered (${Math.round((centeredCount / totalText) * 100)}%)`,
+    })
+  }
+
+  return findings
+}
+
+export {
+  checkBorders,
+  checkRadiusMixedScales,
+  checkPillOnButton,
+  checkTactilePress,
+  checkLucideIcon,
+  checkColors,
+  checkGlow,
+  checkMotion,
+  checkQuality,
+  isCardLikeFromProps,
+  isCardLike,
+  readOwnBackgroundColor,
+}