similarbuild 0.1.0

package/templates/skills/sb-review-checks/scripts/lib/design-quality.mjs

@@ -0,0 +1,541 @@
+// design-quality.mjs — 12 pure-function checks for accessibility, performance,
+// and web-standards baselines. These are not opinions — they are baselines
+// every production fragment must clear. Inputs are the same `ctx` shape as
+// anti-patterns.mjs: { html, css, $, preset, styleBlocks }.
+//
+// Mechanical vs semantic split (pattern #11): every check here detects a
+// *structural* problem that regex/AST can find unambiguously. Things that
+// require semantic judgment ("is this alt text meaningful?", "is this the
+// right ARIA pattern?") are explicitly OUT — those are the LLM's job once
+// the violations land in the orchestrator. The script flags presence/absence,
+// not quality.
+
+const SEVERITY_ORDER = { high: 0, medium: 1, low: 2 }
+export function sortBySeverity(violations) {
+  return [...violations].sort((a, b) => {
+    const sa = SEVERITY_ORDER[a.severity] ?? 99
+    const sb = SEVERITY_ORDER[b.severity] ?? 99
+    return sa - sb
+  })
+}
+
+// Helpers ────────────────────────────────────────────────────────────────────
+
+// Best-effort: a button is "icon-only" when its text content is empty (after
+// trimming and stripping a single character / pictograph) and it has at most
+// one child element (an svg or img). This errs on the side of false positives
+// for the LLM to filter — better to flag a labeled button than miss a bare one.
+function isIconOnlyButton($, $btn) {
+  const text = $btn.text().replace(/\s+/g, '').trim()
+  if (text.length > 1) return false
+  // If the only "text" is a single emoji/pictograph (e.g. ☰, ×) treat as icon
+  const children = $btn.children()
+  const hasGlyph = children.length === 0 && text.length === 1
+  if (hasGlyph) return true
+  if (children.length === 1) {
+    const tag = (children[0].tagName || '').toLowerCase()
+    if (tag === 'svg' || tag === 'img' || tag === 'i' || tag === 'span') return true
+  }
+  if (children.length === 0 && text.length === 0) return true
+  return false
+}
+
+// Identifies "the hero image" for preload/lazy/fetchpriority checks.
+// Heuristic, in order: explicit fetchpriority="high"; ancestor class containing
+// "hero"; first <img> in document order. Returns the cheerio element or null.
+function findHeroImg($) {
+  const explicit = $('img[fetchpriority="high"]').first()
+  if (explicit.length) return explicit
+  const inHero = $('img').filter((_, el) => {
+    const $el = $(el)
+    let cur = $el
+    for (let i = 0; i < 8 && cur.length; i++) {
+      const cls = String(cur.attr('class') || '').toLowerCase()
+      if (/(^|[\s_-])hero([\s_-]|$)/.test(cls)) return true
+      cur = cur.parent()
+    }
+    return false
+  }).first()
+  if (inHero.length) return inHero
+  const first = $('img').first()
+  return first.length ? first : null
+}
+
+// Pattern #25 of the plan. The plain `findHeroImg` returns the first <img> as a
+// last-resort guess — but in builds where the hero is a CSS background-image,
+// the first <img> is the LOGO, not the hero. Flagging it as the hero produces
+// false positives (the logo doesn't need preload — the real hero does, and the
+// real hero is not an <img>). This variant returns a tiered confidence so
+// callers can choose to skip the lowest tier ("fallback") when a CSS-bg path
+// has already been considered.
+const HERO_IMG_CONFIDENCE = ['explicit', 'hero-ancestor', 'name-match', 'wide', 'fallback']
+export function findHeroImgWithConfidence($) {
+  const explicit = $('img[fetchpriority="high"]').first()
+  if (explicit.length) return { el: explicit, confidence: 'explicit' }
+  let inHero = null
+  $('img').each((_, el) => {
+    if (inHero) return
+    const $el = $(el)
+    let cur = $el
+    for (let i = 0; i < 8 && cur.length; i++) {
+      const cls = String(cur.attr('class') || '').toLowerCase()
+      if (/(^|[\s_-])hero([\s_-]|$)/.test(cls)) {
+        inHero = $el
+        return
+      }
+      cur = cur.parent()
+    }
+  })
+  if (inHero) return { el: inHero, confidence: 'hero-ancestor' }
+  let nameMatch = null
+  $('img').each((_, el) => {
+    if (nameMatch) return
+    const $el = $(el)
+    const src = String($el.attr('src') || $el.attr('data-src') || '').toLowerCase()
+    const alt = String($el.attr('alt') || '').toLowerCase()
+    if (/\b(hero|banner|cover)\b/.test(src) || /\b(hero|banner|cover)\b/.test(alt)) {
+      nameMatch = $el
+    }
+  })
+  if (nameMatch) return { el: nameMatch, confidence: 'name-match' }
+  let wideImg = null
+  $('img').each((_, el) => {
+    if (wideImg) return
+    const w = getImgWidth($(el))
+    if (Number.isFinite(w) && w >= 800) wideImg = $(el)
+  })
+  if (wideImg) return { el: wideImg, confidence: 'wide' }
+  const first = $('img').first()
+  if (first.length) return { el: first, confidence: 'fallback' }
+  return null
+}
+
+// Find the first CSS rule whose selector is a single root-scope class (no `__`
+// BEM-modifier, no descendant combinator) and whose body declares a
+// `background-image: url(...)`. The build skills (sb-build-wp,
+// sb-build-shopify) emit the section's root scope as a single class — so a
+// `background-image` declaration on that class is canonical hero-CSS-bg
+// territory. Returns `{ selector, url }` or null.
+export function findHeroCssBackgroundImage(css) {
+  if (!css || typeof css !== 'string') return null
+  // Strip CSS comments to keep the regex below simple.
+  const stripped = css.replace(/\/\*[\s\S]*?\*\//g, '')
+  // Walk top-level rule blocks. This keeps things readable; nested at-rules
+  // like @media{} won't match the simple `selector { ... }` form because the
+  // outer rule has nested braces — handled by skipping any "selector" that
+  // contains a `{`.
+  const RULE_RE = /([^{}]+?)\{([^{}]*?)\}/g
+  let m
+  while ((m = RULE_RE.exec(stripped)) !== null) {
+    const selectorRaw = m[1].trim()
+    const body = m[2]
+    if (!selectorRaw) continue
+    // Skip at-rules and comma-joined selectors with nested @media.
+    if (selectorRaw.startsWith('@')) continue
+    // For comma-separated selectors, accept if the FIRST selector is a root
+    // scope class — same heuristic as the build skills emit.
+    const firstSelector = selectorRaw.split(',')[0].trim()
+    // Single-class root scope: `.foo` or `.foo:pseudo`. Reject:
+    //   - descendant/child combinators (`.foo .bar`, `.foo > .bar`)
+    //   - BEM modifier (`__`)
+    //   - id selectors, type selectors, attribute selectors
+    if (!/^\.[A-Za-z][\w-]*(?::[A-Za-z-]+(?:\([^)]*\))?)?$/.test(firstSelector)) continue
+    if (firstSelector.includes('__')) continue
+    const bgMatch = body.match(/background(?:-image)?\s*:\s*[^;]*?url\(\s*['"]?([^'")]+?)['"]?\s*\)/i)
+    if (!bgMatch) continue
+    return { selector: firstSelector, url: bgMatch[1] }
+  }
+  return null
+}
+
+function getImgWidth($img) {
+  const explicit = parseInt(String($img.attr('width') || ''), 10)
+  if (Number.isFinite(explicit) && explicit > 0) return explicit
+  const style = String($img.attr('style') || '')
+  const m = style.match(/(?:^|;|\s)width\s*:\s*(\d+)\s*px/i)
+  if (m) return parseInt(m[1], 10)
+  return null
+}
+
+function collectPreloadHrefs($) {
+  return $('link[rel="preload"][as="image"]')
+    .map((_, el) => String($(el).attr('href') || ''))
+    .get()
+}
+
+// Checks ─────────────────────────────────────────────────────────────────────
+
+// a11y-button-aria — icon-only buttons need an aria-label
+export function checkButtonAria(ctx) {
+  const { $ } = ctx
+  const violations = []
+  $('button').each((_, el) => {
+    const $el = $(el)
+    if (!isIconOnlyButton($, $el)) return
+    if ($el.attr('aria-label')) return
+    if ($el.attr('aria-labelledby')) return
+    // <img alt="..."> child satisfies a11y too
+    const innerImgAlt = $el.find('img[alt]').first().attr('alt')
+    if (innerImgAlt && innerImgAlt.trim().length > 0) return
+    const cls = $el.attr('class') || ''
+    const hint = inferActionHint($el)
+    violations.push({
+      group: 'a11y',
+      id: 'a11y-button-aria',
+      location: cls ? `<button class="${cls}">` : '<button> (icon-only)',
+      issue: 'icon-only <button> without aria-label — screen readers announce nothing',
+      candidateFix: `add \`aria-label="${hint}"\` to the <button>`,
+      severity: 'high',
+    })
+  })
+  return violations
+}
+
+function inferActionHint($btn) {
+  const cls = String($btn.attr('class') || '').toLowerCase()
+  if (/(close|dismiss|×)/.test(cls)) return 'Close'
+  if (/(open|menu|hamburger|drawer)/.test(cls)) return 'Open menu'
+  if (/(prev|previous|back)/.test(cls)) return 'Previous'
+  if (/(next|forward)/.test(cls)) return 'Next'
+  if (/(search|find)/.test(cls)) return 'Search'
+  if (/(cart|bag)/.test(cls)) return 'Cart'
+  return 'Button action'
+}
+
+// a11y-img-alt — every <img> must have an alt attribute (empty allowed)
+export function checkImgAlt(ctx) {
+  const { $ } = ctx
+  const violations = []
+  $('img').each((_, el) => {
+    const $el = $(el)
+    if ($el.attr('alt') !== undefined) return
+    const src = $el.attr('src') || $el.attr('data-src') || ''
+    violations.push({
+      group: 'a11y',
+      id: 'a11y-img-alt',
+      location: src ? `<img src="${truncate(src, 60)}">` : '<img>',
+      issue: '<img> missing `alt` attribute — assistive tech reads the filename or skips the image',
+      candidateFix: `add \`alt=""\` (decorative) or \`alt="<short description>"\` to the <img src="${truncate(src, 60)}">`,
+      severity: 'high',
+    })
+  })
+  return violations
+}
+
+function truncate(s, n) {
+  return s.length > n ? s.slice(0, n - 1) + '…' : s
+}
+
+// a11y-heading-hierarchy — H1 absent OR multiple OR skips a level
+export function checkHeadingHierarchy(ctx) {
+  const { $ } = ctx
+  const violations = []
+  const levels = []
+  $('h1, h2, h3, h4, h5, h6').each((_, el) => {
+    const tag = (el.tagName || '').toLowerCase()
+    levels.push({ tag, n: parseInt(tag.slice(1), 10) })
+  })
+  if (levels.length === 0) return violations
+  const h1Count = levels.filter((l) => l.n === 1).length
+  if (h1Count === 0) {
+    // Sections without an H1 can be valid IF this is a sub-fragment — but the
+    // first heading shouldn't deeper than H2 (otherwise the doc starts at H3+).
+    if (levels[0].n > 2) {
+      violations.push({
+        group: 'a11y',
+        id: 'a11y-heading-hierarchy',
+        location: `first heading is <${levels[0].tag}>`,
+        issue: `document starts at <${levels[0].tag}> with no H1/H2 above — heading outline is broken`,
+        candidateFix: `change the first <${levels[0].tag}> to <h2> (or add an <h1> ancestor in the page chrome — the orchestrator will know which)`,
+        severity: 'medium',
+      })
+    }
+  } else if (h1Count > 1) {
+    violations.push({
+      group: 'a11y',
+      id: 'a11y-heading-hierarchy',
+      location: `${h1Count} <h1> elements`,
+      issue: `multiple <h1> elements (${h1Count}) — page should have exactly one`,
+      candidateFix: `keep the most prominent <h1> and demote the others to <h2>`,
+      severity: 'medium',
+    })
+  }
+  // Detect skips (e.g. H2 → H4)
+  for (let i = 1; i < levels.length; i++) {
+    const prev = levels[i - 1]
+    const cur = levels[i]
+    if (cur.n > prev.n + 1) {
+      violations.push({
+        group: 'a11y',
+        id: 'a11y-heading-hierarchy',
+        location: `<${prev.tag}> → <${cur.tag}> (heading ${i + 1})`,
+        issue: `heading level skip from <${prev.tag}> to <${cur.tag}> — outline is jagged`,
+        candidateFix: `change the <${cur.tag}> after the <${prev.tag}> to <h${prev.n + 1}>`,
+        severity: 'low',
+      })
+    }
+  }
+  return violations
+}
+
+// a11y-button-type — <button> without type="button" submits parent forms
+export function checkButtonType(ctx) {
+  const { $ } = ctx
+  const violations = []
+  $('button').each((_, el) => {
+    const $el = $(el)
+    const type = ($el.attr('type') || '').toLowerCase()
+    if (type === 'button' || type === 'submit' || type === 'reset') return
+    const cls = $el.attr('class') || ''
+    violations.push({
+      group: 'a11y',
+      id: 'a11y-button-type',
+      location: cls ? `<button class="${cls}">` : '<button>',
+      issue: '<button> without `type="button"` — defaults to type="submit" inside a form, can submit accidentally',
+      candidateFix: `add \`type="button"\` to the <button${cls ? ` class="${cls}"` : ''}>`,
+      severity: 'medium',
+    })
+  })
+  return violations
+}
+
+// a11y-nav-semantic — main navigation should be <nav>, not <div>
+// Heuristic: an element with a class containing "nav" / "menu" / "header" that
+// has an <ul> or multiple <a> children, and is itself a <div> (not <nav>),
+// AND there is no <nav> ancestor wrapping it.
+export function checkNavSemantic(ctx) {
+  const { $ } = ctx
+  const violations = []
+  $('div').each((_, el) => {
+    const $el = $(el)
+    const cls = String($el.attr('class') || '').toLowerCase()
+    if (!/(nav|menu|navigation)/.test(cls)) return
+    if (/(footer|sub|breadcrumb)/.test(cls)) return // skip secondary nav
+    if ($el.closest('nav').length) return
+    const links = $el.find('a').length
+    if (links < 2) return
+    violations.push({
+      group: 'a11y',
+      id: 'a11y-nav-semantic',
+      location: `<div class="${cls}"> with ${links} links`,
+      issue: 'navigation rendered as <div> — landmark roles missed by assistive tech',
+      candidateFix: `change \`<div class="${cls}">\` to \`<nav class="${cls}" aria-label="Main">\` (close the matching tag too)`,
+      severity: 'medium',
+    })
+  })
+  return violations
+}
+
+// perf-img-lazy — every non-hero <img> needs loading="lazy"
+export function checkImgLazy(ctx) {
+  const { $ } = ctx
+  const violations = []
+  const hero = findHeroImg($)
+  $('img').each((_, el) => {
+    const $el = $(el)
+    if (hero && $el.is(hero)) return
+    const loading = String($el.attr('loading') || '').toLowerCase()
+    if (loading === 'lazy') return
+    if (loading === 'eager') return // explicit eager is intentional (LCP fallback)
+    const src = $el.attr('src') || $el.attr('data-src') || ''
+    violations.push({
+      group: 'performance',
+      id: 'perf-img-lazy',
+      location: src ? `<img src="${truncate(src, 60)}">` : '<img>',
+      issue: 'non-hero <img> without `loading="lazy"` — eager load wastes bandwidth on below-fold images',
+      candidateFix: `add \`loading="lazy"\` to the <img src="${truncate(src, 60)}">`,
+      severity: 'medium',
+    })
+  })
+  return violations
+}
+
+// perf-hero-preload — hero needs `<link rel="preload" as="image">`.
+// Two-step detection (Pattern #25 of the plan):
+//   Step 1: search the scope CSS for a root-class rule with
+//           `background-image: url(...)`. If found, that IS the hero — verify
+//           a matching preload exists; flag against the bg URL otherwise.
+//   Step 2: only when no CSS-bg hero was found, fall back to <img> heroes.
+//           Skip the "first <img>" fallback tier — that's almost always the
+//           logo on builds where the hero uses CSS background-image.
+//   Step 3: if neither tier finds a hero, skip the check (no false positive).
+export function checkHeroPreload(ctx) {
+  const { $ } = ctx
+  const violations = []
+  const preloads = collectPreloadHrefs($)
+
+  // Step 1: CSS background-image hero.
+  const cssHero = findHeroCssBackgroundImage(ctx.css || '')
+  if (cssHero) {
+    if (preloads.some((href) => href === cssHero.url)) return violations
+    violations.push({
+      group: 'performance',
+      id: 'perf-hero-preload',
+      location: `CSS \`background-image\` on \`${cssHero.selector}\``,
+      issue: 'hero CSS background-image without `<link rel="preload">` — LCP starts the network round-trip late',
+      candidateFix: `add \`<link rel="preload" as="image" href="${cssHero.url}">\` at the top of the fragment`,
+      severity: 'medium',
+    })
+    return violations
+  }
+
+  // Step 2: <img> hero. Skip the lowest "first <img>" tier — the logo case.
+  const heroPick = findHeroImgWithConfidence($)
+  if (!heroPick || heroPick.confidence === 'fallback') return violations
+  const heroSrc = heroPick.el.attr('src') || heroPick.el.attr('data-src') || ''
+  if (!heroSrc) return violations
+  if (preloads.some((href) => href === heroSrc)) return violations
+  violations.push({
+    group: 'performance',
+    id: 'perf-hero-preload',
+    location: `hero <img src="${truncate(heroSrc, 60)}">`,
+    issue: 'hero image without `<link rel="preload">` — LCP starts the network round-trip late',
+    candidateFix: `add \`<link rel="preload" as="image" href="${heroSrc}">\` at the top of the fragment`,
+    severity: 'medium',
+  })
+  return violations
+}
+
+// perf-font-display — Google Fonts URL must include &display=swap
+export function checkFontDisplay(ctx) {
+  const { $ } = ctx
+  const violations = []
+  $('link[rel="stylesheet"][href*="fonts.googleapis.com"]').each((_, el) => {
+    const href = String($(el).attr('href') || '')
+    if (/[?&]display=swap\b/i.test(href)) return
+    violations.push({
+      group: 'performance',
+      id: 'perf-font-display',
+      location: `<link href="${truncate(href, 60)}">`,
+      issue: 'Google Fonts stylesheet without `&display=swap` — invisible text during font load (FOIT)',
+      candidateFix: `append \`&display=swap\` to the href of <link href="${truncate(href, 60)}">`,
+      severity: 'medium',
+    })
+  })
+  return violations
+}
+
+// perf-fetchpriority-hero — Shopify-only: hero needs fetchpriority="high"
+export function checkFetchpriorityHero(ctx) {
+  if (ctx.preset !== 'shopify-section') return []
+  const { $ } = ctx
+  const hero = findHeroImg($)
+  if (!hero) return []
+  const fp = String(hero.attr('fetchpriority') || '').toLowerCase()
+  if (fp === 'high') return []
+  const heroSrc = hero.attr('src') || hero.attr('data-src') || ''
+  return [{
+    group: 'performance',
+    id: 'perf-fetchpriority-hero',
+    location: `hero <img src="${truncate(heroSrc, 60)}">`,
+    issue: 'hero <img> without `fetchpriority="high"` — Shopify themes benefit from the hint to prioritize LCP',
+    candidateFix: `add \`fetchpriority="high"\` to the hero <img src="${truncate(heroSrc, 60)}">`,
+    severity: 'low',
+  }]
+}
+
+// web-srcset-responsive — large <img> without srcset wastes bandwidth on small viewports
+export function checkSrcsetResponsive(ctx) {
+  const { $ } = ctx
+  const violations = []
+  $('img').each((_, el) => {
+    const $el = $(el)
+    if ($el.attr('srcset')) return
+    const w = getImgWidth($el)
+    // Only flag images we know to be wide. Without a width attribute the file
+    // *might* still be huge, but flagging every <img> would be noise — let the
+    // LLM make a judgment call when explicit width is missing.
+    if (w == null || w <= 800) return
+    const src = $el.attr('src') || $el.attr('data-src') || ''
+    violations.push({
+      group: 'web-standards',
+      id: 'web-srcset-responsive',
+      location: src ? `<img src="${truncate(src, 60)}" width="${w}">` : `<img width="${w}">`,
+      issue: `<img> width=${w} without srcset — mobile viewports download the full-size file`,
+      candidateFix: `add \`srcset="${src} 1x, ${src} 2x"\` and \`sizes="(min-width: 1000px) 50vw, 100vw"\` to the <img> (the orchestrator can fill the actual srcset values from the inspection)`,
+      severity: 'low',
+    })
+  })
+  return violations
+}
+
+// web-modal-dialog — modals should be <dialog>, not <div>
+export function checkModalDialog(ctx) {
+  const { $ } = ctx
+  const violations = []
+  $('div').each((_, el) => {
+    const $el = $(el)
+    const cls = String($el.attr('class') || '').toLowerCase()
+    const role = String($el.attr('role') || '').toLowerCase()
+    const isModalCandidate = role === 'dialog' || /(^|[\s_-])modal([\s_-]|$)/.test(cls)
+    if (!isModalCandidate) return
+    if ($el.closest('dialog').length) return
+    violations.push({
+      group: 'web-standards',
+      id: 'web-modal-dialog',
+      location: `<div class="${cls}"${role ? ` role="${role}"` : ''}>`,
+      issue: 'modal as <div> instead of <dialog> — loses native focus trap, ESC handling, backdrop',
+      candidateFix: `change \`<div class="${cls}"${role ? ` role="${role}"` : ''}>\` to \`<dialog class="${cls}">\` and open with \`dialog.showModal()\`, close with \`dialog.close()\``,
+      severity: 'medium',
+    })
+  })
+  return violations
+}
+
+// web-preconnect-fonts — Google Fonts stylesheet without a preceding preconnect
+export function checkPreconnectFonts(ctx) {
+  const { $ } = ctx
+  const violations = []
+  const stylesheets = $('link[rel="stylesheet"][href*="fonts.googleapis.com"]')
+  if (stylesheets.length === 0) return violations
+  const preconnects = $('link[rel="preconnect"]').map((_, el) => String($(el).attr('href') || '')).get()
+  const hasGoogleApis = preconnects.some((h) => /fonts\.googleapis\.com/.test(h))
+  const hasGstatic = preconnects.some((h) => /fonts\.gstatic\.com/.test(h))
+  if (hasGoogleApis && hasGstatic) return violations
+  const missing = []
+  if (!hasGoogleApis) missing.push('https://fonts.googleapis.com')
+  if (!hasGstatic) missing.push('https://fonts.gstatic.com')
+  violations.push({
+    group: 'performance',
+    id: 'web-preconnect-fonts',
+    location: 'fragment <head>-position links',
+    issue: `Google Fonts loaded without <link rel="preconnect"> — DNS+TLS handshake delays font request${missing.length > 1 ? 's for ' + missing.join(' and ') : ' for ' + missing[0]}`,
+    candidateFix: `add ${missing.map((u) => `\`<link rel="preconnect" href="${u}"${u.includes('gstatic') ? ' crossorigin' : ''}>\``).join(' and ')} before the Google Fonts <link rel="stylesheet">`,
+    severity: 'low',
+  })
+  return violations
+}
+
+export const DESIGN_QUALITY_CHECKS = [
+  checkButtonAria,
+  checkImgAlt,
+  checkHeadingHierarchy,
+  checkButtonType,
+  checkNavSemantic,
+  checkImgLazy,
+  checkHeroPreload,
+  checkFontDisplay,
+  checkFetchpriorityHero,
+  checkSrcsetResponsive,
+  checkModalDialog,
+  checkPreconnectFonts,
+]
+
+export function runDesignQuality(ctx) {
+  const out = []
+  for (const fn of DESIGN_QUALITY_CHECKS) {
+    try {
+      out.push(...fn(ctx))
+    } catch (err) {
+      out.push({
+        group: 'design-quality',
+        id: fn.name || 'unknown',
+        location: 'check',
+        issue: `check threw: ${err.message}`,
+        candidateFix: 'inspect the input file — it may be malformed HTML',
+        severity: 'low',
+      })
+    }
+  }
+  return sortBySeverity(out)
+}