@surea11y/core 1.6.0 → 1.8.0

package/src/checks/automatic/contrast-enhanced.js

@@ -216,16 +216,28 @@ function runInPage(ctx) {
 
       const det = details && typeof details === 'object' ? details : { reasonCode: 'UNKNOWN' };
 
+      // The background is the only input this rule can fail to resolve; every other
+      // reason code here describes a ratio it did compute.
+      const uncertainty =
+        det.reasonCode === 'BACKGROUND_NOT_COMPUTABLE'
+          ? {
+              code: 'not-computable',
+              needed: 'The effective background colour behind this text.',
+              evidence: { reasonCode: det.reasonCode, foreground: det.fg || null }
+            }
+          : null;
+
       const occBase = {
         selector: '',
         html: '',
         summary: '',
-        hint: '',
+        hint: `Change the text color, the background color, or both, so the contrast ratio reaches at least ${params && params.threshold}:1.`,
         i18n: {
           summaryKey: 'contrastEnhanced_fail_belowThreshold',
-          hintKey: '',
+          hintKey: 'contrastEnhanced_hint_fail',
           params: params && typeof params === 'object' ? params : {}
         },
+        ...(uncertainty ? { uncertainty } : {}),
         data: { details: det }
       };
 
@@ -486,11 +498,11 @@ function runInPage(ctx) {
           {
             selector: '',
             summary: '',
-            hint: '',
+            hint: "Measure this text's contrast by hand on the rendered page. Normal text needs at least 4.5:1 and large text 3:1 (7:1 and 4.5:1 for AAA).",
             html: '',
             i18n: {
               summaryKey: 'contrastEnhanced_cantTell_engineFailure',
-              hintKey: '',
+              hintKey: 'contrast_hint_cantTell_manual',
               params: { reasonCode: 'ENGINE_EXCEPTION' }
             },
             data: { details: { reasonCode: 'ENGINE_EXCEPTION' } }

package/src/checks/automatic/contrast-minimum.js

@@ -20,6 +20,10 @@
  *   size: 3:1 for large text, 4.5:1 for everything else. Text is large at
  *   24px or more, or at 14pt (about 18.667px) or more when the computed font
  *   weight is 700 or higher.
+ * @implementation-notes
+ * - Its thresholds are settings (`settings` below), so another standard's
+ *   contrast requirement is a variant of this rule rather than a copy
+ *   (docs/RULE_AUTHORING.md, "Rule variants"). Without settings it is WCAG's.
  */
 
 const id = 'contrast-minimum';
@@ -65,6 +69,21 @@ function runInPage(ctx) {
     }
   }
 
+  // Thresholds (see `settings` below): WCAG 1.4.3's by default. A variant of
+  // this rule, another standard's contrast requirement, passes its own in
+  // ctx.config (docs/RULE_AUTHORING.md, "Rule variants").
+  const cfg = ctx.config && typeof ctx.config === 'object' ? ctx.config : {};
+  const setting = (v, d) => (typeof v === 'number' && Number.isFinite(v) ? v : d);
+  const BOLD_LARGE_MIN_PX = setting(cfg.boldLargeMinPx, null);
+  const LARGE_TEXT_RATIO = setting(cfg.largeTextRatio, 3);
+  const NORMAL_TEXT_RATIO = setting(cfg.normalTextRatio, 4.5);
+  // The font and analysis caches hold verdicts that depend on those
+  // thresholds, so other thresholds get caches of their own.
+  const SETTINGS_KEY =
+    BOLD_LARGE_MIN_PX === null && LARGE_TEXT_RATIO === 3 && NORMAL_TEXT_RATIO === 4.5
+      ? ''
+      : '|' + [BOLD_LARGE_MIN_PX, LARGE_TEXT_RATIO, NORMAL_TEXT_RATIO].join('|');
+
   const __contrastSharedCache =
     helpers && helpers.contrast && helpers.contrast.sharedCache
       ? helpers.contrast.sharedCache
@@ -82,8 +101,9 @@ function runInPage(ctx) {
     ? __contrastSharedCache.__elFgCache || (__contrastSharedCache.__elFgCache = new WeakMap())
     : null;
 
+  const FONT_CACHE = '__elFontCache' + SETTINGS_KEY;
   const __elFontCache = __contrastSharedCache
-    ? __contrastSharedCache.__elFontCache || (__contrastSharedCache.__elFontCache = new WeakMap())
+    ? __contrastSharedCache[FONT_CACHE] || (__contrastSharedCache[FONT_CACHE] = new WeakMap())
     : new WeakMap();
 
   function safeComputedStyle(el) {
@@ -124,7 +144,10 @@ function runInPage(ctx) {
 
       const sizePx = Number.isFinite(fontSizePx) ? fontSizePx : 0;
       const isBold = Number.isFinite(fontWeightNum) && fontWeightNum >= 700;
-      const isLarge = helpers.contrast.isLargeText(sizePx, fontWeightNum);
+      const isLarge =
+        BOLD_LARGE_MIN_PX === null
+          ? helpers.contrast.isLargeText(sizePx, fontWeightNum)
+          : helpers.contrast.isLargeText(sizePx, fontWeightNum, BOLD_LARGE_MIN_PX);
 
       const out = {
         fontSizePx: sizePx,
@@ -213,16 +236,28 @@ function runInPage(ctx) {
 
       const det = details && typeof details === 'object' ? details : { reasonCode: 'UNKNOWN' };
 
+      // The background is the only input this rule can fail to resolve; every other
+      // reason code here describes a ratio it did compute.
+      const uncertainty =
+        det.reasonCode === 'BACKGROUND_NOT_COMPUTABLE'
+          ? {
+              code: 'not-computable',
+              needed: 'The effective background colour behind this text.',
+              evidence: { reasonCode: det.reasonCode, foreground: det.fg || null }
+            }
+          : null;
+
       const occBase = {
         selector: '',
         html: '',
         summary: '',
-        hint: '',
+        hint: `Change the text color, the background color, or both, so the contrast ratio reaches at least ${params && params.threshold}:1.`,
         i18n: {
           summaryKey: 'contrastMinimum_fail_belowThreshold',
-          hintKey: '',
+          hintKey: 'contrastMinimum_hint_fail',
           params: params && typeof params === 'object' ? params : {}
         },
+        ...(uncertainty ? { uncertainty } : {}),
         data: { details: det }
       };
 
@@ -266,9 +301,10 @@ function runInPage(ctx) {
   let __elAnalysisCache = new WeakMap();
   if (__contrastSharedCache) {
     try {
-      if (!__contrastSharedCache.__elAnalysisCacheAA)
-        __contrastSharedCache.__elAnalysisCacheAA = new WeakMap();
-      __elAnalysisCache = __contrastSharedCache.__elAnalysisCacheAA;
+      const ANALYSIS_CACHE = '__elAnalysisCacheAA' + SETTINGS_KEY;
+      if (!__contrastSharedCache[ANALYSIS_CACHE])
+        __contrastSharedCache[ANALYSIS_CACHE] = new WeakMap();
+      __elAnalysisCache = __contrastSharedCache[ANALYSIS_CACHE];
     } catch {
       __elAnalysisCache = new WeakMap();
     }
@@ -360,7 +396,12 @@ function runInPage(ctx) {
               const ratio = helpers.contrast.contrastRatio(fgOpaque, bgOpaque);
 
               const font = getFontInfo(el);
-              const threshold = helpers.contrast.requiredRatio('AA', font.isLargeText);
+              const threshold =
+                SETTINGS_KEY === ''
+                  ? helpers.contrast.requiredRatio('AA', font.isLargeText)
+                  : font.isLargeText
+                    ? LARGE_TEXT_RATIO
+                    : NORMAL_TEXT_RATIO;
 
               analysis = {
                 computable: true,
@@ -479,11 +520,11 @@ function runInPage(ctx) {
           {
             selector: '',
             summary: '',
-            hint: '',
+            hint: "Measure this text's contrast by hand on the rendered page. Normal text needs at least 4.5:1 and large text 3:1 (7:1 and 4.5:1 for AAA).",
             html: '',
             i18n: {
               summaryKey: 'contrastMinimum_cantTell_engineFailure',
-              hintKey: '',
+              hintKey: 'contrast_hint_cantTell_manual',
               params: { reasonCode: 'ENGINE_EXCEPTION' }
             },
             data: { details: { reasonCode: 'ENGINE_EXCEPTION' } }
@@ -552,4 +593,9 @@ function runInPage(ctx) {
   };
 }
 
-module.exports = { id, meta, runInPage };
+// The thresholds a variant may change (docs/RULE_AUTHORING.md, "Rule
+// variants"), with WCAG 1.4.3's as defaults: the size from which bold text is
+// large (null: WCAG's 14pt), and the ratios large and other text need.
+const settings = { boldLargeMinPx: null, largeTextRatio: 3, normalTextRatio: 4.5 };
+
+module.exports = { id, meta, runInPage, settings };

package/src/checks/automatic/css-orientation-lock.js

@@ -20,6 +20,16 @@
  *   regardless of the device's actual orientation, which defeats WCAG
  *   1.3.4's requirement that content not restrict its view to a single
  *   display orientation unless that orientation is essential.
+ *   Such a rotation fails.
+ *
+ *   A second shape is asked about (cantTell): an orientation media block
+ *   that hides the page's content with `display: none` or `visibility:
+ *   hidden`, the usual form of WCAG F100 (content replaced by a "rotate
+ *   your device" message in one orientation). The hidden element counts as
+ *   the page's content when it is `html` or `body`, the `main` landmark, an
+ *   ancestor of it, or, on a page without a main landmark, an element
+ *   holding at least half of the body's text. Whether the orientation is
+ *   essential, and whether the page stays usable, is left to a person.
  * @implementation-notes
  * - The rotation DEGREE is what makes this the exploit signature, not
  *   merely the presence of a `rotate()` function: a small decorative icon
@@ -38,11 +48,16 @@
  *   security model) and are skipped, same class of limitation as any
  *   check that can only see same-origin/inspectable content (compare
  *   `iframe-focusable-content`).
- * - Not per-element: this is a whole-document/whole-stylesheet concern,
- *   so occurrences are reported against `document.documentElement`,
+ * - A rotation lock is not decided per element: this is a
+ *   whole-document/whole-stylesheet concern, so its occurrences are
+ *   reported against `document.documentElement`,
  *   matching the "whole-document checks" precedent documented in
  *   `docs/RULE_AUTHORING.md` §11.2 (e.g. `aria-hidden-body`,
- *   `meta-viewport-zoom-enabled`).
+ *   `meta-viewport-zoom-enabled`). A hidden-content finding is reported
+ *   against the hidden element.
+ * - The rotation lock stays a failure, as in ACT b33eff, which assumes the
+ *   orientation is not essential; a person reviewing an essential lock (a
+ *   piano keyboard, a cheque scan) can set that finding aside.
  */
 
 const id = 'css-orientation-lock';
@@ -50,7 +65,7 @@ const id = 'css-orientation-lock';
 const meta = {
   title: 'CSS must not lock the page to a single orientation',
   description:
-    'Checks that no @media (orientation: portrait|landscape) rule sets a transform: rotate(...) on the page, a known technique for defeating device orientation.',
+    "Checks that no @media (orientation: portrait|landscape) rule sets a transform: rotate(...) on the page, a known technique for defeating device orientation, and asks about any such rule that hides the page's main content.",
   i18n: {
     titleKey: 'cssOrientationLock_title',
     descriptionKey: 'cssOrientationLock_description'
@@ -228,18 +243,52 @@ function runInPage(ctx) {
     return m.includes('orientation') && (m.includes('portrait') || m.includes('landscape'));
   }
 
-  function scanRuleList(rules, mediaText, findings) {
+  function hidesContent(styleDecl) {
+    if (!styleDecl || typeof styleDecl.getPropertyValue !== 'function') return false;
+    const display = trim(styleDecl.getPropertyValue('display')).toLowerCase();
+    const visibility = trim(styleDecl.getPropertyValue('visibility')).toLowerCase();
+    return display === 'none' || visibility === 'hidden' || visibility === 'collapse';
+  }
+
+  function scanRuleList(rules, mediaText, findings, hidings) {
     if (!rules) return;
     for (const r of rules) {
-      if (!r) continue;
-      if (r.type === CSS_STYLE_RULE && isLockingRotation(r.style)) {
+      if (!r || r.type !== CSS_STYLE_RULE) continue;
+      if (isLockingRotation(r.style)) {
         findings.push({ mediaText, selectorText: trim(r.selectorText) });
       }
+      if (r.selectorText && hidesContent(r.style)) {
+        hidings.push({ mediaText, selectorText: trim(r.selectorText) });
+      }
     }
   }
 
+  // Whether an element hidden by an orientation block holds the page's
+  // content: the root, the body, the main landmark or an ancestor of it, or,
+  // with no main landmark, most of the body's text.
+  function textLength(el) {
+    return String((el && el.textContent) || '').replace(/\s+/g, '').length;
+  }
+  let mainEl = null;
+  try {
+    mainEl = document.querySelector('main, [role="main"]');
+  } catch {
+    mainEl = null;
+  }
+  const bodyTextLength = document.body ? textLength(document.body) : 0;
+
+  function holdsPageContent(el) {
+    if (!el || el.nodeType !== 1) return false;
+    const tag = String(el.localName || '').toLowerCase();
+    if (tag === 'html' || tag === 'body') return true;
+    if (mainEl) return el === mainEl || (typeof el.contains === 'function' && el.contains(mainEl));
+    return bodyTextLength > 0 && textLength(el) * 2 >= bodyTextLength;
+  }
+
   const findings = [];
+  const hidings = [];
   let sheetCount = 0;
+  let unreadableSheetCount = 0;
 
   try {
     const sheets = document.styleSheets || [];
@@ -248,7 +297,10 @@ function runInPage(ctx) {
       try {
         rules = sheet && sheet.cssRules ? sheet.cssRules : null;
       } catch {
-        continue; // cross-origin stylesheet, not inspectable
+        // Cross-origin, not inspectable. Counted, since a lock could be
+        // declared there and a `pass` would claim more than was checked.
+        unreadableSheetCount += 1;
+        continue;
       }
       if (!rules) continue;
       sheetCount += 1;
@@ -257,22 +309,116 @@ function runInPage(ctx) {
         if (!rule2 || rule2.type !== CSS_MEDIA_RULE) continue;
         const mediaText = rule2.media ? rule2.media.mediaText : '';
         if (!isOrientationMedia(mediaText)) continue;
-        scanRuleList(rule2.cssRules, mediaText, findings);
+        scanRuleList(rule2.cssRules, mediaText, findings, hidings);
       }
     }
   } catch {
     // no-throw: treat as no accessible stylesheets
   }
 
-  if (sheetCount === 0) {
-    return { ruleId: rule.ruleId, outcome: 'notApplicable', severity: 'minor', occurrences: [] };
+  const scanTarget = document.documentElement || document.body || null;
+
+  function unreadableSheetsOccurrence(count) {
+    return helpers.reportOccurrence(scanTarget, {
+      summary: `${count} stylesheet(s) could not be read, so whether this page locks its orientation could not be determined.`,
+      hint: 'Cross-origin stylesheets are not inspectable from the page. Check any third-party CSS for an orientation media query containing a rotate() transform, or re-run the scan with those stylesheets served same-origin.',
+      i18n: {
+        summaryKey: 'cssOrientationLock_summary_cantTell_unreadableSheets',
+        hintKey: 'cssOrientationLock_hint_cantTell_unreadableSheets',
+        params: { count: String(count) }
+      },
+      uncertainty: {
+        code: 'not-computable',
+        needed: 'The contents of the stylesheets this scan could not read.',
+        evidence: { unreadableSheetCount: count, reasonCode: 'STYLESHEETS_NOT_READABLE' }
+      },
+      data: {
+        details: {
+          reasonCode: 'STYLESHEETS_NOT_READABLE',
+          unreadableSheetCount: count
+        }
+      }
+    });
+  }
+
+  // Orientation blocks hiding the page's content (F100): one question per
+  // hidden element.
+  const hiddenContent = [];
+  const seenHidden = new Set();
+  for (const h of hidings) {
+    let matched;
+    try {
+      matched = Array.from(document.querySelectorAll(h.selectorText));
+    } catch {
+      matched = [];
+    }
+    for (const el of matched) {
+      if (seenHidden.has(el) || !holdsPageContent(el)) continue;
+      seenHidden.add(el);
+      hiddenContent.push({ el, mediaText: h.mediaText, selectorText: h.selectorText });
+    }
+  }
+  const hiddenContentOccurrences = hiddenContent.map((f) =>
+    helpers.reportOccurrence(f.el, {
+      occurrenceOutcome: 'cantTell',
+      summary: `A "${f.mediaText}" media query hides "${f.selectorText}", which holds the page's main content, so the page may not be usable in that orientation.`,
+      hint: 'Check that the page can be viewed and operated in both portrait and landscape. If this media query replaces the content with a message asking the user to rotate the device, show the content instead, unless one orientation is essential.',
+      i18n: {
+        summaryKey: 'cssOrientationLock_summary_cantTell_hidesContent',
+        hintKey: 'cssOrientationLock_hint_cantTell_hidesContent',
+        params: { mediaText: f.mediaText, selectorText: f.selectorText }
+      },
+      uncertainty: {
+        code: 'judgement-required',
+        needed:
+          'Whether the page stays usable in that orientation, and whether one orientation is essential.',
+        evidence: {
+          mediaText: f.mediaText,
+          selectorText: f.selectorText,
+          reasonCode: 'ORIENTATION_MEDIA_HIDES_CONTENT'
+        }
+      },
+      data: {
+        details: {
+          reasonCode: 'ORIENTATION_MEDIA_HIDES_CONTENT',
+          mediaText: f.mediaText,
+          selectorText: f.selectorText
+        }
+      }
+    })
+  );
+
+  // A lock found in a readable sheet is still a lock, so `fail` outranks the
+  // uncertainty below.
+  if (!findings.length && hiddenContentOccurrences.length) {
+    const unreadable =
+      unreadableSheetCount > 0 ? [unreadableSheetsOccurrence(unreadableSheetCount)] : [];
+    return {
+      ruleId: rule.ruleId,
+      outcome: 'cantTell',
+      severity: rule.defaultSeverity || 'serious',
+      confidence: 'low',
+      occurrences: hiddenContentOccurrences.concat(unreadable)
+    };
   }
 
   if (!findings.length) {
+    if (unreadableSheetCount > 0) {
+      return {
+        ruleId: rule.ruleId,
+        outcome: 'cantTell',
+        severity: rule.defaultSeverity || 'serious',
+        confidence: 'low',
+        occurrences: [unreadableSheetsOccurrence(unreadableSheetCount)]
+      };
+    }
+    if (sheetCount === 0) {
+      return { ruleId: rule.ruleId, outcome: 'notApplicable', severity: 'minor', occurrences: [] };
+    }
     return { ruleId: rule.ruleId, outcome: 'pass', severity: 'minor', occurrences: [] };
   }
 
-  const target = document.documentElement || document.body || null;
+  const target = scanTarget;
   const occurrences = findings.map((f) =>
     helpers.reportOccurrence(target, {
       summary: f.selectorText
@@ -296,6 +442,19 @@ function runInPage(ctx) {
     })
   );
 
+  if (hiddenContentOccurrences.length) {
+    // See helpers.resolveTieredOutcome: the lock fails, and the hidden-content
+    // questions are kept beside it.
+    return {
+      ruleId: rule.ruleId,
+      ...helpers.resolveTieredOutcome(
+        occurrences,
+        hiddenContentOccurrences,
+        rule.defaultSeverity || 'serious'
+      )
+    };
+  }
+
   return {
     ruleId: rule.ruleId,
     outcome: 'fail',

package/src/checks/automatic/definition-list-children-valid.js

@@ -9,16 +9,21 @@
  * @standard WCAG 2.2
  * @sc 1.3.1
  * @applicability
- *   Applies to <dl> elements that have at least one direct element child.
+ *   Applies to <dl> elements that have at least one direct element child or
+ *   non-whitespace text directly inside them.
  * @expectation
  *   Every direct element child is <dt>, <dd>, <script>, <template>, <style>,
  *   or a <div> whose own children are drawn from that same set (a single
  *   level of wrapping div is allowed, matching how authors commonly group
- *   dt/dd pairs). If the flattened set contains any <dt> or <dd> at all, it
- *   must contain BOTH (an unbalanced dt-without-dd or dd-without-dt is
- *   invalid). A flattened set with neither is vacuously fine, not a
- *   violation (see implementation-notes). Any other direct or wrapped child
- *   breaks the description-list semantics assistive technologies rely on.
+ *   dt/dd pairs). Non-whitespace text directly inside the <dl> or a wrapping
+ *   <div> is an invalid child too. If the flattened set contains any <dt> or
+ *   <dd> at all, it must contain BOTH (an unbalanced dt-without-dd or
+ *   dd-without-dt is invalid), and read in order it must be groups of one
+ *   or more <dt> followed by one or more <dd>: a <dd> before the first <dt>
+ *   has no term, and a <dt> after the last <dd> has no definition. A
+ *   flattened set with neither is vacuously fine, not a violation (see
+ *   implementation-notes). Any other direct or wrapped child breaks the
+ *   description-list semantics assistive technologies rely on.
  * @implementation-notes
  * - Only one level of <div> wrapping is flattened, a <div> nested inside
  *   another wrapping <div> is not flattened further and its contents are
@@ -27,6 +32,11 @@
  *   with NEITHER dt nor dd, whether from an empty wrapping <div>, only
  *   <script>/<template>/<style> content, or a childless <dl>, is not flagged; only
  *   an unbalanced dt/dd pairing is a real structural problem.
+ * - The order check reads the flattened dt/dd sequence across wrapping
+ *   <div> boundaries, so a term and its definition split into two sibling
+ *   <div>s still pass: assistive technologies get the same terms and
+ *   definitions. The stricter HTML content model (each <div> holds a whole
+ *   group) is not checked here.
  * - Distinct, atomic decision from dlitem-parent-valid (the
  *   inverse relationship: does a given <dt>/<dd> have a valid parent).
  */
@@ -72,17 +82,29 @@ function runInPage(ctx) {
   const occurrences = [];
   let applicableCount = 0;
 
+  // Non-whitespace text directly inside `parent` (the <dl> or a wrapping
+  // <div>).
+  function hasDirectText(parent) {
+    for (const node of parent.childNodes || []) {
+      if (node && node.nodeType === 3 && /\S/.test(node.nodeValue || '')) return true;
+    }
+    return false;
+  }
+
   for (const el of nodes) {
     if (!el || !el.children) continue;
-    if (!el.children.length) continue;
+    const dlHasText = hasDirectText(el);
+    if (!el.children.length && !dlHasText) continue;
 
     applicableCount += 1;
 
     // Flatten one level of wrapping <div> (common dt/dd grouping pattern).
     const flattened = [];
+    let hasText = dlHasText;
     for (const child of el.children) {
       if (!child || !child.tagName) continue;
       if (child.tagName.toLowerCase() === 'div') {
+        if (hasDirectText(child)) hasText = true;
         for (const grandchild of child.children || []) {
           if (grandchild && grandchild.tagName) flattened.push(grandchild);
         }
@@ -94,50 +116,72 @@ function runInPage(ctx) {
     let hasDt = false;
     let hasDd = false;
     const invalidTags = [];
+    // The dt/dd sequence in document order, for the group-order check.
+    const sequence = [];
     for (const node of flattened) {
       const tag = node.tagName.toLowerCase();
       if (tag === 'dt') {
         hasDt = true;
+        sequence.push(tag);
         continue;
       }
       if (tag === 'dd') {
         hasDd = true;
+        sequence.push(tag);
         continue;
       }
       if (!PASSTHROUGH_TAGS.has(tag)) invalidTags.push(tag);
     }
+    if (hasText) invalidTags.push('#text');
     const dedupedInvalidTags = [...new Set(invalidTags)];
 
+    // Groups of one or more dt then one or more dd: the sequence starts
+    // with a dt and ends with a dd.
+    const badOrder =
+      hasDt && hasDd && (sequence[0] !== 'dt' || sequence[sequence.length - 1] !== 'dd');
+
     // The dt/dd pairing is only required "when not empty", a <dl> with
     // NEITHER dt nor dd (whether childless after flattening, only
     // passthrough script/template/style content, or an empty wrapping div)
     // is vacuously fine, not a violation. Only an UNBALANCED pairing (dt
-    // present without any dd, or vice versa) is a real structural problem.
+    // present without any dd, or vice versa) or a misordered one is a
+    // real structural problem.
     const reasonCode = invalidTags.length
       ? 'DL_INVALID_CHILD'
       : (hasDt || hasDd) && !(hasDt && hasDd)
         ? 'DL_NO_DT_DD'
-        : null;
+        : badOrder
+          ? 'DL_DT_DD_ORDER'
+          : null;
     if (!reasonCode) continue;
 
-    const summary = invalidTags.length
-      ? 'This description list contains a direct or wrapped child that is not part of a dt/dd group.'
-      : 'This description list has no <dt>/<dd> term-definition group.';
-    const hint = invalidTags.length
-      ? 'Only use <dt>/<dd> (optionally wrapped in one <div>), <script>, <template>, or <style> inside <dl>.'
-      : 'Add at least one <dt>/<dd> pair inside this <dl>.';
+    const TEXT = {
+      DL_INVALID_CHILD: {
+        summary:
+          'This description list contains a direct or wrapped child that is not part of a dt/dd group.',
+        hint: 'Only use <dt>/<dd> (optionally wrapped in one <div>), <script>, <template>, or <style> inside <dl>.',
+        key: 'invalidChild'
+      },
+      DL_NO_DT_DD: {
+        summary: 'This description list has no <dt>/<dd> term-definition group.',
+        hint: 'Add at least one <dt>/<dd> pair inside this <dl>.',
+        key: 'noDtDd'
+      },
+      DL_DT_DD_ORDER: {
+        summary:
+          'In this description list, a <dd> comes before any <dt>, or the last <dt> has no <dd> after it.',
+        hint: 'Order each group as one or more <dt> followed by one or more <dd>.',
+        key: 'order'
+      }
+    }[reasonCode];
 
     occurrences.push(
       helpers.reportOccurrence(el, {
-        summary,
-        hint,
+        summary: TEXT.summary,
+        hint: TEXT.hint,
         i18n: {
-          summaryKey: invalidTags.length
-            ? 'definitionListChildrenValid_summary_fail_invalidChild'
-            : 'definitionListChildrenValid_summary_fail_noDtDd',
-          hintKey: invalidTags.length
-            ? 'definitionListChildrenValid_hint_fail_invalidChild'
-            : 'definitionListChildrenValid_hint_fail_noDtDd',
+          summaryKey: `definitionListChildrenValid_summary_fail_${TEXT.key}`,
+          hintKey: `definitionListChildrenValid_hint_fail_${TEXT.key}`,
           params: { invalidChildren: dedupedInvalidTags.join(', ') }
         },
         data: {