frontend-go-live-check 1.3.0 → 1.4.0

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # Changelog
 
+## 1.4.0
+
+- New layout checks on every page at every screen size, each with Actual and Expected pictures where possible:
+  - text that spills out of its box (for example a button with a fixed size that is too small for its label);
+  - text drawn on top of other text;
+  - content cut off at the edge of the screen where the user cannot scroll to it.
+- New content checks:
+  - buttons and links covered by another element;
+  - unfinished text: `undefined`, `NaN`, `null`, `[object Object]`, `Invalid Date`, `{{ }}`, translation keys, lorem ipsum, TODO;
+  - stretched or squashed images;
+  - loading indicators still showing after the page finished loading.
+- Evidence outlines now include text that runs outside its element.
+
 ## 1.3.0
 
 - Every problem is shown as **Actual** next to **Expected**: a close-up of the problem outlined in red, and the same spot corrected (focus ring, contrast, text that fits, page that fits the screen, right-to-left…) outlined in green. Problems without a picture get one Expected sentence.

package/README.md

@@ -142,9 +142,9 @@ The report lists every sign-in method found (*email and password · Google · UA
 
 | | Area | What is checked |
 | :-: | --- | --- |
-| 🧭 | **Functionality** | JavaScript errors, console errors, failed requests, broken links, images and anchors, blank pages, the production build, the "page not found" page |
+| 🧭 | **Functionality** | JavaScript errors, console errors, failed requests, broken links, images and anchors, blank pages, buttons covered by something else, unfinished text (`undefined`, `NaN`, `[object Object]`, translation keys, lorem ipsum, TODO), loading spinners that never stop, the production build, the "page not found" page |
 | 🛟 | **Resilience** | Each page opened again with its API calls failing: does it crash, go blank, or tell the user? |
-| 📱 | **Design and responsive layout** | Every page at every screen size: sideways scrolling, cut-off or overlapping text and buttons, tiny text on phones, right-to-left layout (Arabic, Hebrew…), fonts that fail to load, too many fonts and sizes |
+| 📱 | **Design and responsive layout** | Every page at every screen size: sideways scrolling, text that spills out of its box (a button too small for its label), text on top of other text, content cut off at the screen edge, text cut off inside its box, overlapping buttons, stretched or squashed images, tiny text on phones, right-to-left layout (Arabic, Hebrew…), fonts that fail to load, too many fonts and sizes |
 | 🖼️ | **Visual changes** | A pixel comparison of every page with the saved baseline, with the changed areas in red |
 | ♿ | **Accessibility** | axe-core against WCAG 2.0 / 2.1 / 2.2 A and AA; keyboard-only use: visible focus, no traps, nothing that only a mouse can click; form field types |
 | ⚡ | **Performance** | Size, JavaScript, requests, load time, LCP, layout shift and frozen-page time for every page, against budgets; Lighthouse as a phone and as a desktop |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "frontend-go-live-check",
-  "version": "1.3.0",
+  "version": "1.4.0",
   "description": "Is your frontend ready to go live? One command tests any web frontend (React, Next.js, Vue, Angular, Svelte, plain HTML…): pages, responsive design, accessibility, keyboard, performance and load, API calls, security, SEO, sign-in and APIs from Postman/OpenAPI. Report with evidence, PDF and Word, and a pipeline gate that approves or rejects the merge.",
   "homepage": "https://www.npmjs.com/package/frontend-go-live-check",
   "repository": {

package/src/checks/browser.mjs

@@ -301,6 +301,18 @@ export async function runBrowserChecks({ base, config, reportDir, log, starts =
           if (!audit.viewportMeta) add({ ruleId: 'missing-viewport-meta', page: landedKey, view: tag });
           if (audit.overflow.length) await withEvidence({ ruleId: 'horizontal-overflow', page: landedKey, view: tag, detail: `The page is ${audit.docWidth}px wide on a ${audit.width}px screen.`, items: audit.overflow, selectors: audit.targets.overflow }, audit.targets.overflow, { screenEdge: audit.width });
           if (audit.clipped.length) await withEvidence({ ruleId: 'clipped-text', page: landedKey, view: tag, items: audit.clipped, selectors: audit.targets.clipped }, audit.targets.clipped);
+          if (audit.outside.length) await withEvidence({ ruleId: 'text-outside-box', page: landedKey, view: tag, items: audit.outside, selectors: audit.targets.outside }, audit.targets.outside);
+          if (audit.textOverlaps.length) await withEvidence({ ruleId: 'text-overlap', page: landedKey, view: tag, items: audit.textOverlaps, selectors: audit.targets.textOverlaps }, audit.targets.textOverlaps);
+          if (audit.cutOff.length) await withEvidence({ ruleId: 'cut-off-at-edge', page: landedKey, view: tag, items: audit.cutOff, selectors: audit.targets.cutOff }, audit.targets.cutOff);
+          if (audit.covered.length) await withEvidence({ ruleId: 'control-covered', page: landedKey, view: tag, items: audit.covered, selectors: audit.targets.covered }, audit.targets.covered);
+          if (audit.placeholders.length) await withEvidence({ ruleId: 'placeholder-text', page: landedKey, view: tag, items: audit.placeholders, selectors: audit.targets.placeholders }, audit.targets.placeholders);
+          if (audit.distorted.length) await withEvidence({ ruleId: 'distorted-image', page: landedKey, view: tag, items: audit.distorted, selectors: audit.targets.distorted }, audit.targets.distorted);
+          if (audit.loading.length) {
+            // Give slow data a little more time before calling it stuck.
+            await page.waitForTimeout(4000);
+            const again = await page.evaluate(inPageAudit, [Boolean(vp.isMobile) && vp.viewport.width < 600, vp.viewport.width]).catch(() => null);
+            if (again?.loading.length) await withEvidence({ ruleId: 'stuck-loading', page: landedKey, view: tag, items: again.loading, selectors: again.targets.loading }, again.targets.loading);
+          }
           if (audit.overlaps.length) await withEvidence({ ruleId: 'overlapping-elements', page: landedKey, view: tag, items: audit.overlaps, selectors: audit.targets.overlaps }, audit.targets.overlaps);
           if (audit.small.length) await withEvidence({ ruleId: 'small-text', page: landedKey, view: tag, items: audit.small, selectors: audit.targets.small }, audit.targets.small);
           for (const [i, src] of audit.brokenImages.entries()) await withEvidence({ ruleId: 'broken-image', page: landedKey, view: tag, detail: src, selectors: [audit.targets.brokenImages[i]] }, [audit.targets.brokenImages[i]]);

package/src/checks/evidence.mjs

@@ -23,8 +23,21 @@ function drawOutlines([selectors, label, screenEdge, colour = '#e01e1e']) {
     }
     if (el && !found.includes(el)) found.push(el);
   }
+  // The element's box plus wherever its content is drawn (text can run outside the box).
+  const extent = (el) => {
+    const b = el.getBoundingClientRect();
+    const range = document.createRange();
+    range.selectNodeContents(el);
+    const c = range.getBoundingClientRect();
+    if (!c.width || !c.height) return b;
+    const left = Math.min(b.left, c.left);
+    const top = Math.min(b.top, c.top);
+    const right = Math.max(b.right, c.right);
+    const bottom = Math.max(b.bottom, c.bottom);
+    return { left, top, right, bottom, width: right - left, height: bottom - top };
+  };
   found.forEach((el, i) => {
-    const r = el.getBoundingClientRect();
+    const r = extent(el);
     const box = document.createElement('div');
     box.style.cssText = `position:absolute;left:${r.left + scrollX - 3}px;top:${r.top + scrollY - 3}px;width:${Math.max(r.width, 4) + 6}px;height:${Math.max(r.height, 4) + 6}px;border:3px solid ${colour};border-radius:4px;box-shadow:0 0 0 2px rgba(255,255,255,.9),0 0 0 9999px rgba(0,0,0,.08);box-sizing:border-box`;
     const tag = document.createElement('div');
@@ -51,7 +64,7 @@ function drawOutlines([selectors, label, screenEdge, colour = '#e01e1e']) {
   // Show the first problem element in the middle of the screen.
   if (found[0] && !screenEdge) found[0].scrollIntoView({ block: 'center', inline: 'nearest' });
   // Where the outlined elements are on screen now (for the close-up picture).
-  const rects = found.map((el) => el.getBoundingClientRect());
+  const rects = found.map(extent);
   const box = rects.length
     ? { left: Math.min(...rects.map((r) => r.left)), top: Math.min(...rects.map((r) => r.top)), right: Math.max(...rects.map((r) => r.right)), bottom: Math.max(...rects.map((r) => r.bottom)) }
     : null;
@@ -106,7 +119,7 @@ export async function captureEvidence(page, reportDir, { selectors = [], label =
  * picture (outlined in green), then the page is put back exactly as it was.
  * Only for problems a picture can show; others get the Expected sentence only.
  */
-export const EXPECTED_VISUAL = new Set(['horizontal-overflow', 'clipped-text', 'small-text', 'focus-not-visible', 'mouse-only-control', 'rtl-missing', 'color-contrast', 'target-size']);
+export const EXPECTED_VISUAL = new Set(['horizontal-overflow', 'clipped-text', 'text-outside-box', 'cut-off-at-edge', 'small-text', 'focus-not-visible', 'mouse-only-control', 'rtl-missing', 'color-contrast', 'target-size']);
 
 /** Runs in the page: corrects the problem on these elements; remembers how to undo it. */
 function applyExpected([kind, selectors]) {
@@ -155,6 +168,17 @@ function applyExpected([kind, selectors]) {
       set(el, 'height', 'auto');
       set(el, 'max-height', 'none');
       set(el, 'white-space', 'normal');
+    } else if (kind === 'text-outside-box') {
+      for (const prop of ['width', 'height']) set(el, prop, 'auto');
+      set(el, 'max-width', '100%');
+      set(el, 'white-space', 'normal');
+      set(el, 'overflow-wrap', 'anywhere');
+      if (getComputedStyle(el).display === 'inline') set(el, 'display', 'inline-block');
+    } else if (kind === 'cut-off-at-edge') {
+      for (const prop of ['left', 'right', 'margin-left', 'margin-right', 'text-indent', 'transform']) if (getComputedStyle(el)[prop.replace(/-(.)/g, (_, c) => c.toUpperCase())] !== 'auto') set(el, prop, prop === 'transform' ? 'none' : prop === 'left' || prop === 'right' ? 'auto' : '0');
+      set(el, 'max-width', '100%');
+      set(el, 'overflow-wrap', 'anywhere');
+      set(el, 'white-space', 'normal');
     } else if (kind === 'small-text') {
       set(el, 'font-size', '14px');
     } else if (kind === 'color-contrast') {

package/src/checks/in-page.mjs

@@ -73,6 +73,178 @@ export function inPageAudit([phone, screenWidth]) {
     if (el.scrollWidth > el.clientWidth + 2 || el.scrollHeight > el.clientHeight + 2) { clipped.push(describe(el)); targets.clipped.push(cssPath(el)); }
   }
 
+  // Where an element's own text is drawn (it can be outside the element's box).
+  const range = document.createRange();
+  const textRect = (el, lines = []) => {
+    let box = null;
+    for (const n of el.childNodes) {
+      if (n.nodeType !== 3 || !n.textContent.trim()) continue;
+      range.selectNodeContents(n);
+      for (const r of range.getClientRects()) {
+        if (r.width < 1 || r.height < 1) continue;
+        if (lines.length < 20) lines.push({ left: r.left, top: r.top, right: r.right, bottom: r.bottom });
+        box = box ? { left: Math.min(box.left, r.left), top: Math.min(box.top, r.top), right: Math.max(box.right, r.right), bottom: Math.max(box.bottom, r.bottom) } : { left: r.left, top: r.top, right: r.right, bottom: r.bottom };
+      }
+    }
+    return box;
+  };
+  const transparent = (c) => !c || c === 'transparent' || /rgba\([^)]*,\s*0\)$/.test(c);
+  const srOnly = (el, cs, r) => r.width <= 2 || r.height <= 2 || (cs.clip && cs.clip !== 'auto') || (cs.clipPath && cs.clipPath !== 'none');
+  const inDialog = (el) => Boolean(el.closest('dialog, [role=dialog], [role=alertdialog], [aria-modal=true], [aria-hidden=true]'));
+  const texts = [];
+  for (const el of all) {
+    if (texts.length >= 600) break;
+    if (!visible(el) || !el.childNodes.length || inDialog(el)) continue;
+    const cs = getComputedStyle(el);
+    const r = el.getBoundingClientRect();
+    if (srOnly(el, cs, r) || transparent(cs.color)) continue;
+    const lines = [];
+    const t = textRect(el, lines);
+    if (t) texts.push({ el, cs, r, t, lines });
+  }
+
+  // Text that spills out of a box with a visible shape (a button, a badge, a card): the box is
+  // too small for its text, and the text runs over whatever is next to it.
+  const outside = [];
+  targets.outside = [];
+  for (const { el, cs, r, t } of texts) {
+    if (outside.length >= 5) break;
+    if (el === document.body || el === document.documentElement) continue;
+    if (/(hidden|clip)/.test(`${cs.overflowX} ${cs.overflowY}`)) continue; // that is clipped-text
+    const shaped = !transparent(cs.backgroundColor) || parseFloat(cs.borderLeftWidth) + parseFloat(cs.borderRightWidth) + parseFloat(cs.borderTopWidth) + parseFloat(cs.borderBottomWidth) > 0 || el.matches('button, [role=button], input, select, textarea');
+    if (!shaped) continue;
+    const slackY = Math.max(4, parseFloat(cs.fontSize) * 0.3);
+    const past = { right: t.right - r.right, left: r.left - t.left, bottom: t.bottom - r.bottom - slackY, top: r.top - t.top - slackY };
+    const worst = Object.entries(past).sort((a, b) => b[1] - a[1])[0];
+    if (worst[1] > 3) {
+      outside.push(`${describe(el)}: the text goes ${Math.round(worst[1] + (worst[0] === 'top' || worst[0] === 'bottom' ? slackY : 0))}px past the ${worst[0]} edge of its ${Math.round(r.width)} × ${Math.round(r.height)}px box`);
+      targets.outside.push(cssPath(el));
+    }
+  }
+
+  // Text drawn on top of other text (absolute positioning, negative margins, text spilling out).
+  const textOverlaps = [];
+  targets.textOverlaps = [];
+  const hit = (p, q) => {
+    const w = Math.min(p.right, q.right) - Math.max(p.left, q.left);
+    const h = Math.min(p.bottom, q.bottom) - Math.max(p.top, q.top);
+    if (w < 4 || h < 4) return null;
+    const smaller = Math.min((p.right - p.left) * (p.bottom - p.top), (q.right - q.left) * (q.bottom - q.top));
+    if (w * h < 0.15 * smaller) return null;
+    return { x: (Math.max(p.left, q.left) + Math.min(p.right, q.right)) / 2, y: (Math.max(p.top, q.top) + Math.min(p.bottom, q.bottom)) / 2 };
+  };
+  const reported = new Set();
+  for (let i = 0; i < texts.length && textOverlaps.length < 5; i++) {
+    const a = texts[i];
+    for (let j = i + 1; j < texts.length; j++) {
+      const b = texts[j];
+      if (!hit(a.t, b.t) || reported.has(b.el)) continue;
+      let point = null;
+      for (const p of a.lines) {
+        for (const q of b.lines) if ((point = hit(p, q))) break;
+        if (point) break;
+      }
+      if (!point) continue;
+      // Only when both texts can really be seen there (not one hidden behind a solid layer).
+      const top = document.elementFromPoint(point.x, point.y);
+      if (top && !(a.el.contains(top) || b.el.contains(top) || top.contains(a.el) || top.contains(b.el))) continue;
+      reported.add(a.el);
+      reported.add(b.el);
+      textOverlaps.push(`${describe(a.el).replace(/ ".*/, '')} "${[...a.el.childNodes].filter((n) => n.nodeType === 3).map((n) => n.textContent).join(' ').replace(/\s+/g, ' ').trim().slice(0, 30)}" and ${describe(b.el)}`);
+      targets.textOverlaps.push(cssPath(a.el), cssPath(b.el));
+      break;
+    }
+  }
+
+  // Content cut off at the edge of the screen where the user cannot scroll to it (pushed off to
+  // the left, or past the right edge when the page hides sideways scrolling).
+  const cutOff = [];
+  targets.cutOff = [];
+  for (const { el, t } of texts) {
+    if (cutOff.length >= 5) break;
+    if (insideFixedOrScroller(el) || overflow.some((o) => o.el.contains(el))) continue;
+    const left = t.left < -2 && t.right > 0;
+    const right = t.right > width + 2 && t.left < width && docWidth <= width + 1;
+    if (!left && !right) continue;
+    if (cutOff.length && targets.cutOff.some((sel) => document.querySelector(sel)?.contains(el))) continue;
+    cutOff.push(`${describe(el)}: ${left ? `starts ${Math.round(-t.left)}px before the left edge` : `goes ${Math.round(t.right - width)}px past the right edge`} of the screen`);
+    targets.cutOff.push(cssPath(el));
+  }
+
+  // Buttons and links covered by something else, so a click lands on the wrong thing.
+  const covered = [];
+  targets.covered = [];
+  for (const el of document.querySelectorAll('a[href], button, input:not([type=hidden]), select, textarea, [role=button]')) {
+    if (covered.length >= 5) break;
+    if (!visible(el) || inDialog(el) || el.disabled) continue;
+    const r = el.getBoundingClientRect();
+    if (r.width < 8 || r.height < 8 || r.top < 0 || r.left < 0 || r.bottom > innerHeight || r.right > innerWidth) continue;
+    const top = document.elementFromPoint(r.left + r.width / 2, r.top + r.height / 2);
+    if (!top || el.contains(top) || top.contains(el)) continue;
+    const label = top.closest('label');
+    if (label && (label.control === el || label.contains(el))) continue;
+    if (top.closest('dialog, [role=dialog], [role=alertdialog], [aria-modal=true]') || /cookie|consent|gdpr/i.test(`${top.closest('[id],[class]')?.id ?? ''} ${top.closest('[class]')?.className ?? ''}`)) continue;
+    covered.push(`${describe(el)} is under ${describe(top)}`);
+    targets.covered.push(cssPath(el), cssPath(top));
+  }
+
+  // Text that was never filled in: undefined, NaN, [object Object], template braces, lorem ipsum,
+  // TODO, translation keys shown instead of the translation.
+  const placeholders = [];
+  targets.placeholders = [];
+  const leftover = [
+    [/\bundefined\b/, 'undefined'], [/\bNaN\b/, 'NaN'], [/\[object Object\]/, '[object Object]'], [/Invalid Date/, 'Invalid Date'],
+    [/(^null$|:\s*null\b)/, 'null'], [/\{\{[^}]*\}\}|\$\{[^}]*\}/, 'template braces'], [/lorem ipsum/i, 'lorem ipsum'], [/\b(TODO|FIXME|TBD)\b/, 'TODO'],
+  ];
+  const key = /^[a-z][a-zA-Z0-9]*(\.[a-z][a-zA-Z0-9_]*){2,}$|^[a-z][a-zA-Z0-9]*\.[a-z]+[A-Z][a-zA-Z0-9]*$|^[A-Z][A-Z0-9]*(_[A-Z0-9]+){2,}$/;
+  const walker = document.createTreeWalker(document.body, NodeFilter.SHOW_TEXT);
+  for (let n = walker.nextNode(); n && placeholders.length < 5; n = walker.nextNode()) {
+    const text = n.textContent.replace(/\s+/g, ' ').trim();
+    const el = n.parentElement;
+    if (!text || !el || el.closest('script, style, noscript, template, code, pre, samp, kbd, textarea, [contenteditable]') || !visible(el)) continue;
+    const found = leftover.find(([re]) => re.test(text))?.[1] ?? (key.test(text) ? 'translation key' : '');
+    if (!found || targets.placeholders.includes(cssPath(el))) continue;
+    placeholders.push(`${describe(el)} shows "${text.slice(0, 60)}" (${found})`);
+    targets.placeholders.push(cssPath(el));
+  }
+  for (const input of document.querySelectorAll('input[placeholder], input[value]')) {
+    if (placeholders.length >= 5 || !visible(input)) continue;
+    const text = `${input.value} ${input.placeholder}`;
+    const found = leftover.slice(0, 6).find(([re]) => re.test(text))?.[1];
+    if (found) {
+      placeholders.push(`${describe(input)} shows "${text.trim().slice(0, 60)}" (${found})`);
+      targets.placeholders.push(cssPath(input));
+    }
+  }
+
+  // Images stretched or squashed (shown at a different shape than the picture).
+  const distorted = [];
+  targets.distorted = [];
+  for (const img of document.images) {
+    if (distorted.length >= 5 || !visible(img) || !img.naturalWidth || !img.naturalHeight || /\.svg(\?|#|$)/i.test(img.currentSrc || img.src)) continue;
+    const cs = getComputedStyle(img);
+    if (cs.objectFit !== 'fill') continue;
+    const r = img.getBoundingClientRect();
+    const box = { w: r.width - parseFloat(cs.paddingLeft) - parseFloat(cs.paddingRight), h: r.height - parseFloat(cs.paddingTop) - parseFloat(cs.paddingBottom) };
+    if (box.w < 16 || box.h < 16) continue;
+    const ratio = (box.w / box.h) / (img.naturalWidth / img.naturalHeight);
+    if (Math.abs(ratio - 1) > 0.1) {
+      distorted.push(`${(img.currentSrc || img.src).startsWith('data:') ? 'an embedded image' : (img.currentSrc || img.src).split('/').pop().slice(0, 50)} is ${img.naturalWidth} × ${img.naturalHeight} but shown at ${Math.round(box.w)} × ${Math.round(box.h)} (${ratio > 1 ? 'stretched wide' : 'squashed'})`);
+      targets.distorted.push(cssPath(img));
+    }
+  }
+
+  // A loading indicator still showing after the page finished loading.
+  const loading = [];
+  targets.loading = [];
+  for (const el of document.querySelectorAll('[aria-busy=true], [role=progressbar]:not([aria-valuenow]), [class*=spinner i], [class*=loader i], [class*=loading i], [class*=skeleton i]')) {
+    if (loading.length >= 3 || !visible(el) || inDialog(el) || targets.loading.some((sel) => document.querySelector(sel)?.contains(el))) continue;
+    const r = el.getBoundingClientRect();
+    if (r.width < 8 || r.height < 8) continue;
+    loading.push(describe(el));
+    targets.loading.push(cssPath(el));
+  }
+
   // Small text on phones.
   const small = [];
   if (phone) {
@@ -219,6 +391,13 @@ export function inPageAudit([phone, screenWidth]) {
     overflow: overflow.map((o) => `${describe(o.el)} reaches ${o.right}px`),
     targets: { ...targets, overflow: overflow.map((o) => cssPath(o.el)), brokenImages: [...document.images].filter((img) => img.complete && img.naturalWidth === 0 && (img.currentSrc || img.src)).slice(0, 10).map(cssPath) },
     clipped,
+    outside,
+    textOverlaps,
+    cutOff,
+    covered,
+    placeholders,
+    distorted,
+    loading,
     small,
     overlaps,
     brokenImages,

package/src/core/explain.mjs

@@ -40,6 +40,13 @@ export const EXPLAIN = {
   'missing-viewport-meta': { what: 'The page does not tell phones how wide it is, so phones show it zoomed out and tiny.', who: 'Phone users.', code: '<meta name="viewport" content="width=device-width, initial-scale=1">', ref: 'WCAG 1.4.10 Reflow' },
   'horizontal-overflow': { what: 'Something on the page is wider than the screen, so the whole page scrolls sideways (the dashed line in the picture is the edge of the screen).', who: 'Phone and tablet users: they have to scroll left and right to read the page.', code: '/* Wrap wide tables so only the table scrolls */\n.table-wrap { overflow-x: auto; }\n/* and let other content shrink */\nimg, video { max-width: 100%; }', ref: 'WCAG 1.4.10 Reflow' },
   'clipped-text': { what: 'Text is cut off inside its box, so part of it cannot be read.', who: 'Users on the screen sizes listed.', code: '/* Let the box grow, or show an ellipsis on purpose */\n.label { overflow: visible; }\n/* or */ .label { text-overflow: ellipsis; white-space: nowrap; overflow: hidden; }' },
+  'text-outside-box': { what: 'The box (for example a button) is smaller than its text, so the text runs out of it and over the page around it. Text outside the box is often hard or impossible to read.', who: 'Every user on the screen sizes listed.' },
+  'text-overlap': { what: 'Two pieces of text are drawn on top of each other, so neither can be read properly.', who: 'Every user on the screen sizes listed.' },
+  'cut-off-at-edge': { what: 'Part of the content is outside the screen and the page does not let the user scroll to it, so it cannot be seen at all.', who: 'Users on the screen sizes listed.' },
+  'control-covered': { what: 'Something lies on top of a button or link, so clicking it hits the covering element instead and nothing (or the wrong thing) happens.', who: 'Every user on the screen sizes listed.' },
+  'placeholder-text': { what: 'The page shows text that was never filled in properly: a value the code did not have (undefined, NaN, null), a translation key instead of the words, template braces or sample text.', who: 'Every user of this page; it looks broken and unprofessional.' },
+  'distorted-image': { what: 'An image is shown at a different shape than the picture itself, so it looks stretched or squashed.', who: 'Every user on the screen sizes listed.' },
+  'stuck-loading': { what: 'A loading indicator (spinner, skeleton, busy state) is still showing after the page and all its requests finished, so the user waits for content that never comes.', who: 'Every user of this page.' },
   'overlapping-elements': { what: 'Buttons or links lie on top of each other, so users may press the wrong one.', who: 'Users on the screen sizes listed, especially on touch screens.' },
   'small-text': { what: 'Text is smaller than 12 px on a phone and is hard to read.', who: 'Phone users, especially older users.', code: 'body { font-size: 16px; } /* and use rem for smaller text, never below 0.75rem */' },
   'rtl-missing': { what: 'The page is in a right-to-left language (Arabic…) but is laid out left to right.', who: 'Arabic readers: the text and layout run in the wrong direction.', code: '<html lang="ar" dir="rtl">' },
@@ -170,6 +177,13 @@ export const EXPECTED = {
   'missing-viewport-meta': 'Phones show the page at its normal size, not zoomed out.',
   'horizontal-overflow': 'The page fits the screen: no sideways scrolling. Wide content (such as a table) scrolls inside its own box.',
   'clipped-text': 'All the text is visible inside its box.',
+  'text-outside-box': 'The box grows to fit its text: all the text sits inside it and nothing runs over the page.',
+  'text-overlap': 'Each piece of text has its own space and can be read on its own.',
+  'cut-off-at-edge': 'All the content fits inside the screen.',
+  'control-covered': 'Nothing covers the button or link: a click on it works.',
+  'placeholder-text': 'Every value shows real text: a name, number, date or a clear "not available".',
+  'distorted-image': 'The image keeps its own shape: it fits or is cropped, never stretched.',
+  'stuck-loading': 'When loading ends the indicator goes away and the content (or an error message) is shown.',
   'overlapping-elements': 'Buttons and links sit apart, each easy to press on its own.',
   'small-text': 'Text on phones is at least 12 px (16 px for body text) and easy to read.',
   'rtl-missing': 'The Arabic page reads right to left: text, menus and layout are mirrored.',

package/src/core/rules.mjs

@@ -69,6 +69,34 @@ export const RULES = {
     area: 'responsive', severity: 'minor', title: 'Text is cut off inside its box',
     fix: 'Let the box grow (remove fixed width/height), allow wrapping, or use text-overflow: ellipsis with a title so the full text can still be read.',
   },
+  'text-outside-box': {
+    area: 'responsive', severity: 'major', title: 'Text spills out of its box',
+    fix: 'Let the box fit its text: remove the fixed width/height (use min-width/min-height), allow wrapping, or shorten the text.',
+  },
+  'text-overlap': {
+    area: 'responsive', severity: 'major', title: 'Text lies on top of other text',
+    fix: 'Give each piece of text its own space at this screen size: remove the absolute position or negative margin, or let the container grow.',
+  },
+  'cut-off-at-edge': {
+    area: 'responsive', severity: 'major', title: 'Content is cut off at the edge of the screen',
+    fix: 'Keep the content inside the screen: max-width: 100%, no fixed widths or negative offsets; let long words wrap.',
+  },
+  'control-covered': {
+    area: 'functionality', severity: 'major', title: 'A button or link is covered by something else',
+    fix: 'Move the covering element away, or fix its position/z-index so the button or link can be clicked. Decorative layers should use pointer-events: none.',
+  },
+  'placeholder-text': {
+    area: 'functionality', severity: 'major', title: 'Unfinished text on the page (undefined, NaN, a translation key…)',
+    fix: 'Show real values: handle missing data (show a dash or a message), format dates and numbers, add the missing translations, and remove sample text.',
+  },
+  'distorted-image': {
+    area: 'responsive', severity: 'minor', title: 'An image is stretched or squashed',
+    fix: 'Keep the picture\'s shape: set only the width (height: auto), or use object-fit: cover / contain.',
+  },
+  'stuck-loading': {
+    area: 'functionality', severity: 'major', title: 'The page is still loading after everything has loaded',
+    fix: 'Hide the loading indicator when the data arrives and when a request fails; show the content or an error message.',
+  },
   'overlapping-elements': {
     area: 'responsive', severity: 'minor', title: 'Buttons or links overlap each other',
     fix: 'Give the items room at this screen size: wrap them, stack them, or reduce their size. Overlapping controls are hard to tap.',