nimiq-branding-cli 1.3.0 → 1.3.2

package/LINT.md

@@ -93,6 +93,17 @@ to flag *"this is getting busy, is it justified?"* — the deterministic half of
 |---|---|
 | focus outline removed w/o `:focus-visible` | a stylesheet rule kills `outline` on a focusable/global selector and **no** `:focus-visible` rule anywhere restores a ring (cross-origin sheets are skipped, never guessed) |
 | Mulish not loaded | a declared `Mulish` `@font-face` that didn't load (`document.fonts.check` false) → the page silently falls back to a system font |
+| **text contrast below WCAG AA** | text below `4.5:1` (normal) / `3.0:1` (large) against its *determinable* background. Background is read by walking ancestors; if none is found (a hero's gradient lives on a separate layer) the element is **skipped**, and ratios < 1.6:1 are treated as undetectable-bg, not flagged. **Honest caveat:** nimiq.com itself ships sub-AA secondary grey (≈`2.37:1`), so this is a **warning that the reference also trips** — it surfaces a real a11y debt rather than pretending the brand is perfect. |
+| multiple `<h1>` per page | more than one visible `<h1>`. Level *skips* (h2→h4) are intentionally **not** checked — nimiq.com/about jumps h1→h4 for styling, so a no-skip rule would flag the reference |
+
+**Layout, data & motion**
+
+| Check | Threshold |
+|---|---|
+| unconstrained text column | a body paragraph with `max-width: none` rendered wider than 760px — nimiq's wide copy always caps its measure |
+| NIM amount wrong semantic color | a `+N NIM`/`%` that isn't green (incoming/up), or a `−N`/`−%` that isn't navy/red (outgoing/down) — skill Addresses. Only fires on wallet/POS surfaces |
+| address not uppercase / flat | a display NIM address (≥20px) rendered lowercase or as one flat string instead of the uppercase 3×3 grid |
+| pulsing "live" dot animation | a small (≤28px) round element on an `infinite` animation that isn't a spinner/loader — the fake-"live" glow the slop blacklist names |
 
 **Headline typography & line breaks** (closes the "lint passes ≠ brand-correct" gap)
 
@@ -118,13 +129,18 @@ Weight/tracking are heading-scoped (buttons and bold body labels are legitimatel
 orphan check is general (it caught a body banner, not a heading) but gated at ≥ 20px so calibrated
 fine-print under 20px — which wasn't measured on the reference — is never flagged.
 
-**Mobile (a second pass at 390px)**
+**Responsive sweep (360 · 414 · 768 · 1024 · 1280px)**
+
+The desktop pass renders at 1440; this sweep re-measures at five more widths so a layout that's
+clean at phone *and* desktop but **breaks in the tablet / small-laptop no-man's-land** is caught —
+the single most common responsive bug a fixed 390+1440 check misses. Measured: nimiq.com has **zero
+horizontal overflow at every width** 320→1440, so overflow-at-a-breakpoint is calibrated to 0.
 
 | Check | Threshold |
 |---|---|
-| horizontal overflow | `scrollWidth > viewport` by > 4px |
-| tap targets too small | a button / input / link-button under 30px (inline text links are exempt) |
-| text smaller than 12px | any text element below 12px at mobile width |
+| horizontal overflow at a breakpoint | `scrollWidth > viewport` by > 4px at **any** swept width (reports which widths and by how much) |
+| tap targets too small | a button / input / link-button under 30px at any width (reports the worst breakpoint) |
+| text smaller than 12px | any text element below 12px at any width (reports the worst breakpoint) |
 
 The curated spacing scale (from `assets/css/modern/spacing.css`, desktop max of each step):
 `8 · 12 · 16 · 24 · 32 · 40 · 48 · 72 · 80 · 96 · 144 · 200`. Sub-8px is treated as optical

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nimiq-branding-cli",
-  "version": "1.3.0",
+  "version": "1.3.2",
   "description": "nq — pixel-verified Nimiq UI component registry + CLI. 39 components (Vue 3 + plain HTML) diffed against the real Nimiq apps, plus the team's real asset library. Unofficial community tool.",
   "type": "module",
   "bin": {

package/scripts/lint.mjs

@@ -82,6 +82,23 @@ function pageProbe({ SPACING_SCALE, ANCHORS, RADIUS_SCALE }) {
     }
     return [255, 255, 255];
   };
+  // like effBg but reports whether a real background was actually found. Heroes paint their
+  // gradient on a separate absolutely-positioned layer, so the text's ancestors are transparent
+  // and we'd wrongly default to white — `found:false` lets the contrast check skip those.
+  const effBgF = (el) => {
+    let e = el;
+    while (e && e.nodeType === 1) {
+      const cs = getComputedStyle(e);
+      const bc = toRGBA(cs.backgroundColor);
+      if (bc && bc[3] >= 0.5) return { rgb: bc.slice(0, 3), found: true };
+      if (cs.backgroundImage && cs.backgroundImage !== 'none') {
+        const cols = (cs.backgroundImage.match(/rgba?\([^)]+\)|#[0-9a-fA-F]{3,8}/g) || []).map(toRGB).filter(Boolean);
+        if (cols.length) return { rgb: cols.reduce((d, c) => relLum(c) < relLum(d) ? c : d), found: true };
+      }
+      e = e.parentElement;
+    }
+    return { rgb: [255, 255, 255], found: false };
+  };
   const visible = (el) => { const cs = getComputedStyle(el); if (cs.display === 'none' || cs.visibility === 'hidden' || +cs.opacity === 0) return false; const r = el.getBoundingClientRect(); return r.width > 1 && r.height > 1; };
   const directText = (el) => [...el.childNodes].filter((n) => n.nodeType === 3).map((n) => n.textContent).join('').trim();
   const matchAny = (el, sel) => { try { return el.closest(sel); } catch { return null; } };
@@ -114,6 +131,7 @@ function pageProbe({ SPACING_SCALE, ANCHORS, RADIUS_SCALE }) {
     tightLeadingH: [], tightLeadingBody: [], offFont: {},
     blackBg: [], accentStripe: [], greenAction: [], dupGradIds: [], genericIcon: [], featherIcon: [],
     bakedIcon: [], duotoneBlack: [], modalBlack: [], flatNavySection: [], glowShadow: [], fontsNotLoaded: false, noFocusRing: false,
+    lowContrast: [], h1Count: 0, unconstrained: [], amountColor: [], addrStructure: [], pulseDot: [],
   };
 
   for (const el of document.querySelectorAll('body *')) {
@@ -195,6 +213,45 @@ function pageProbe({ SPACING_SCALE, ANCHORS, RADIUS_SCALE }) {
       }
     }
 
+    // GENERAL TEXT CONTRAST (WARNING, WCAG AA) — only where the background is actually determinable
+    // (effBgF.found), skipping ratio<1.6 = an undetectable layered-hero bg, not a real defect.
+    // NOTE: nimiq.com itself ships sub-AA secondary grey (≈2.37:1), so this WARNS, never gates.
+    if (txt && !inCode && fg && el.children.length === 0 && (toRGBA(cs.color)?.[3] ?? 1) > 0.3) {
+      const cb = effBgF(el);
+      if (cb.found) {
+        const fsc = px(cs.fontSize), large = fsc >= 24 || (fsc >= 18.66 && +cs.fontWeight >= 700);
+        const ratio = contrast(fg, cb.rgb);
+        if (ratio >= 1.6 && ratio < (large ? 3.0 : 4.5)) o.lowContrast.push({ ratio, fg: `rgb(${fg.join(',')})`, bg: `rgb(${cb.rgb.map((x) => Math.round(x)).join(',')})`, fs: fsc, snippet: txt.slice(0, 26) });
+      }
+    }
+
+    // NIM amount / %-change semantic color (WARNING): incoming +N green; outgoing −N NIM navy;
+    // %-change green up / red down (skill Addresses). Only fires on wallet/POS surfaces.
+    if (txt && !inCode && fg) {
+      const m = txt.trim().match(/^([+\-−])\s?[\d][\d.,  ]*\s?(NIM|%)$/i);
+      if (m) {
+        const up = m[1] === '+', pct = /%$/.test(txt.trim());
+        const greenish = dist(fg, ANCHORS.green) < 60 || (hue(fg) >= 140 && hue(fg) <= 178 && sat(fg) > 0.2);
+        const reddish = dist(fg, ANCHORS.red) < 70 || (hue(fg) <= 18 && sat(fg) > 0.35);
+        const navyish = gray(fg) || dist(fg, ANCHORS.navy) < 70;
+        const ok = up ? greenish : (pct ? reddish : (navyish || reddish));
+        if (!ok) o.amountColor.push(`"${txt.slice(0, 18)}" ${up ? 'increase not green' : pct ? 'decrease not red' : 'outgoing not navy/red'}`);
+      }
+    }
+
+    // live address structure (WARNING): a display NIM address (≥20px) must be uppercase + chunked
+    // into the 3×3 grid, not one flat lowercased string (skill Addresses).
+    if (txt && /^NQ[0-9A-Z]{2}(\s?[0-9A-Z]{4}){8}$/i.test(txt.replace(/\s+/g, ' ').trim()) && px(cs.fontSize) >= 20) {
+      if (txt !== txt.toUpperCase()) o.addrStructure.push(`address not uppercase "${txt.slice(0, 22)}…"`);
+      else if (el.children.length === 0) o.addrStructure.push('address as one flat string (use the 3×3 grid)');
+    }
+
+    // pulsing "live" dot (slop): a small round element on an infinite animation that isn't a spinner.
+    if (cs.animationName && cs.animationName !== 'none' && /(^|,)\s*infinite\s*(,|$)/.test(cs.animationIterationCount) && r.width <= 28 && r.height <= 28) {
+      const round = cs.borderRadius.includes('50%') || px(cs.borderRadius) >= Math.min(r.width, r.height) / 2 - 1;
+      if (round && !matchAny(el, '[class*="spin" i],[class*="load" i],[class*="progress" i],[class*="skeleton" i]')) o.pulseDot.push(`<${tag}> infinite pulse on a ${Math.round(r.width)}×${Math.round(r.height)} dot`);
+    }
+
     // BUTTON shape + fill + gradient anchor
     if (isBtn && txt && r.width >= 80 && r.height >= 26 && !el.matches('.nq-button-s')) {
       const rad = px(cs.borderRadius);
@@ -265,6 +322,8 @@ function pageProbe({ SPACING_SCALE, ANCHORS, RADIUS_SCALE }) {
       const fs = px(cs.fontSize) || 16; const ch = Math.round(r.width / (fs * 0.5));
       if (ch > 88) o.wideText.push({ ch, snippet: txt.slice(0, 50) });
       if (cs.lineHeight !== 'normal' && px(cs.lineHeight) / fs < 1.35) o.tightLeadingBody.push(`${(px(cs.lineHeight) / fs).toFixed(2)} @ ${fs}px "${txt.slice(0, 38)}"`);
+      // unconstrained text column (rule: cap the measure) — nimiq's wide copy always sets a max-width
+      if (cs.maxWidth === 'none' && r.width > 760) o.unconstrained.push({ w: Math.round(r.width), ch, snippet: txt.slice(0, 40) });
     }
     if (txt) { const fs = px(cs.fontSize); if (fs) o.fontSizes[fs] = (o.fontSizes[fs] || 0) + 1; }
     // font-family — Nimiq text is Mulish (+ Fira Mono for data). A named third-party face is off-brand.
@@ -330,6 +389,10 @@ function pageProbe({ SPACING_SCALE, ANCHORS, RADIUS_SCALE }) {
   }
   o.dupGradIds = Object.entries(gradById).filter(([, sigs]) => sigs.size > 1).map(([id, sigs]) => `#${id} (${sigs.size} differing defs)`);
 
+  // heading hierarchy — exactly one <h1> per page. (Level SKIPS are NOT checked: nimiq.com/about
+  // jumps h1→h4 for styling, so a no-skip rule would flag the reference.)
+  o.h1Count = [...document.querySelectorAll('h1')].filter((e) => visible(e)).length;
+
   // per-section text-ink ratio (full-width bands)
   const vw = innerWidth;
   const leaves = [...document.querySelectorAll('body *')].filter((el) => !matchAny(el, 'svg') && visible(el) && el.children.length === 0 && directText(el)).map((el) => el.getBoundingClientRect());
@@ -420,10 +483,20 @@ export async function lint(target, opts = {}) {
     try { const en = page.locator('button.flag-btn', { hasText: 'English' }).first(); if (await en.count()) { await en.click({ timeout: 3000 }); await page.waitForLoadState('networkidle', { timeout: 12000 }).catch(() => {}); await page.waitForTimeout(1000); } } catch {}
     await page.evaluate(async () => { const s = innerHeight * 0.8; for (let y = 0; y < document.body.scrollHeight; y += s) { scrollTo(0, y); await new Promise((r) => setTimeout(r, 200)); } scrollTo(0, 0); await new Promise((r) => setTimeout(r, 350)); });
     const r = await page.evaluate(pageProbe, { SPACING_SCALE, ANCHORS, RADIUS_SCALE });
-    // second pass at mobile width (no reload — resize + re-measure)
-    await page.setViewportSize({ width: 390, height: 844 });
-    await page.waitForTimeout(500);
-    const mob = await page.evaluate(mobileProbe);
+    // responsive sweep — overflow / tap-targets / tiny-text across standard breakpoints. The 1440
+    // desktop pass above already covered the wide end; overflow at ANY intermediate width is the
+    // "no-man's-land" bug a fixed 390+1440 check misses. nimiq.com is overflow-clean at every width.
+    const SWEEP = [360, 414, 768, 1024, 1280];
+    const sweep = [];
+    for (const w of SWEEP) {
+      await page.setViewportSize({ width: w, height: 900 });
+      await page.waitForTimeout(350);
+      await page.evaluate(async () => { const s = innerHeight * 0.8; for (let y = 0; y < document.body.scrollHeight; y += s) { scrollTo(0, y); await new Promise((r) => setTimeout(r, 80)); } scrollTo(0, 0); await new Promise((r) => setTimeout(r, 120)); });
+      sweep.push({ w, ...(await page.evaluate(mobileProbe)) });
+    }
+    const overflowAt = sweep.filter((s) => s.overflowPx > 4);
+    const tapWorst = sweep.reduce((a, s) => (s.smallTargetN > a.smallTargetN ? s : a), sweep[0]);
+    const tinyWorst = sweep.reduce((a, s) => (s.tinyText > a.tinyText ? s : a), sweep[0]);
 
     // social-icon exemption (run in Node — SOCIAL anchors aren't in the page context)
     const socialName = (rgb) => { let best = Infinity, name = null; for (const [k, v] of Object.entries(SOCIAL)) { const d = Math.hypot(rgb[0] - v[0], rgb[1] - v[1], rgb[2] - v[2]); if (d < best) { best = d; name = k; } } return best <= SOCIAL_DELTA ? name : null; };
@@ -462,6 +535,12 @@ export async function lint(target, opts = {}) {
       ['heading line-height off (nimiq 1.25–1.3)', r.tightLeadingH.length, r.tightLeadingH[0]],
       ['cramped body line-height (<1.35; nimiq 1.5)', r.tightLeadingBody.length, r.tightLeadingBody[0]],
       ['non-brand font on text (Mulish / Fira only)', offFont.length, offFont.map(([f, n]) => `${f}×${n}`).join(' ')],
+      ['text contrast below WCAG AA', r.lowContrast.length, r.lowContrast.length && `worst ${Math.min(...r.lowContrast.map((c) => c.ratio))}:1 — ${r.lowContrast[0].fg} on ${r.lowContrast[0].bg} @ ${r.lowContrast[0].fs}px`],
+      ['multiple <h1> on the page', r.h1Count > 1 ? r.h1Count : 0, r.h1Count > 1 ? `${r.h1Count} h1 elements` : ''],
+      ['unconstrained text column (set max-width)', r.unconstrained.length, r.unconstrained[0] && `${r.unconstrained[0].w}px (${r.unconstrained[0].ch}ch)`],
+      ['NIM amount wrong semantic color', r.amountColor.length, r.amountColor[0]],
+      ['address not uppercase / flat (use 3×3 grid)', r.addrStructure.length, r.addrStructure[0]],
+      ['pulsing "live" dot animation', r.pulseDot.length, r.pulseDot[0]],
       ['uppercase eyebrow (colored / long / pill)', r.uppercase.length, r.uppercase[0]],
       ['non-pill action buttons', r.nonPill.length, r.nonPill[0]],
       ['flat-fill colored button (needs gradient)', r.flatColorBtn.length, r.flatColorBtn[0]],
@@ -481,13 +560,13 @@ export async function lint(target, opts = {}) {
       ['flat-fill navy/colored section (use radial)', r.flatNavySection.length, r.flatNavySection[0]],
       ['focus outline removed w/o :focus-visible', r.noFocusRing ? 1 : 0, r.noFocusRing ? 'add a :focus-visible ring' : ''],
       ['Mulish not loaded (system-font fallback)', r.fontsNotLoaded ? 1 : 0, r.fontsNotLoaded ? 'load Mulish' : ''],
-      ['mobile horizontal overflow @390px', mob.overflowPx > 4 ? 1 : 0, `${mob.overflowPx}px`],
-      ['mobile tap targets < 36px', mob.smallTargetN, mob.smallTargets[0]],
-      ['text smaller than 12px @390px', mob.tinyText, `${mob.tinyText} element type(s)`],
+      ['horizontal overflow at a breakpoint', overflowAt.length, overflowAt.map((s) => `${s.w}px:${s.overflowPx}px`).join(' ')],
+      ['tap targets < 36px (any breakpoint)', tapWorst.smallTargetN, tapWorst.smallTargetN ? `@${tapWorst.w}px ${tapWorst.smallTargets[0] || ''}` : ''],
+      ['text smaller than 12px (any breakpoint)', tinyWorst.tinyText, tinyWorst.tinyText ? `@${tinyWorst.w}px, ${tinyWorst.tinyText} type(s)` : ''],
     ];
     warnCount = warns.reduce((n, w) => n + (w[1] ? 1 : 0), 0);
 
-    if (opts.json) { out(JSON.stringify({ url, errorCount, warnCount, raw: r, mobile: mob, exemptSocial: exemptSocial.map(([c, v]) => ({ color: c, icon: v.social })) }, null, 2)); return { errorCount, warnCount }; }
+    if (opts.json) { out(JSON.stringify({ url, errorCount, warnCount, raw: r, responsive: sweep, exemptSocial: exemptSocial.map(([c, v]) => ({ color: c, icon: v.social })) }, null, 2)); return { errorCount, warnCount }; }
 
     out(`\n══════ nq lint — ${target} ══════\n`);
     out('ERRORS  (off-brand / a11y — must fix to pass)');