fix(docs): close the loop-blind loader check and two overclaims

Verification of the previous commit found one mutation still green and one
comment stating a false rationale.

The loader mirror check read the candidate array's DECLARATION, so it could see
a reordered literal but not what the loop did with it. Both
`for (const c of [...candidates].reverse())` and an `unshift` after the literal
flip which page renders while the declaration still reads correctly, and both
passed. A check on where a value is declared says nothing about how it is used,
and resolution is a property of the use. It now also pins that the loop
consumes the array directly and that nothing else touches it.

The enumeration detector's comment claimed the backtick-and-quote rule is what
keeps the badge paragraph's next sentence out of the enumeration it comments on.
It is not — sentence segmentation does, and writing that sentence in the exact
shape the rule was said to exclude leaves the check green. The comment now says
what the rule is actually for and records what it does not do.

Also corrects the page's own account of the dot. The dot is `currentColor`, so
it is the same hue as the label and renders the same grey: it is a peripheral
channel, not a greyscale one, and the label remains what separates one tone from
another. The sentence this branch replaced was therefore accurate about
greyscale and wrong only by omission — a smaller defect than the previous
commit message claimed.

Adds the assertion that rule had been missing: nothing checked the toned-badge
dot existed, so deleting it kept every suite green and silently re-falsified the
page. Both halves mutation-proven.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

Author: blove

apps/website/app/docs/__tests__/nav.test.ts

@@ -149,10 +149,16 @@ describe("documentation navigation", () => {
     // with `path.resolve` slipped through the same pair of holes: the fragments
     // are all still present, and the count only ever counted `path.join`.
     //
-    // The array's own text answers all three questions at once — which
-    // candidates, how many, in what order — and answers them about the thing
-    // `resolveHref` actually reproduces rather than about tokens that happen to
-    // appear near it.
+    // The array's own text answers three of the four questions at once — which
+    // candidates, how many, in what order as WRITTEN.
+    //
+    // It does not answer the fourth, which is what the loop does with them, and
+    // that gap is checked separately below. Reading the declaration alone was
+    // itself defeatable: `for (const c of [...candidates].reverse())` flips
+    // precedence with the literal untouched, and an `unshift` after the literal
+    // adds a highest-precedence candidate the declaration never mentions. Both
+    // passed. A check on where a value is DECLARED says nothing about how it is
+    // USED, and resolution is a property of the use.
     const candidates = /const candidates = \[([\s\S]*?)\];/.exec(LOADER_SOURCE);
 
     expect(
@@ -171,6 +177,27 @@ describe("documentation navigation", () => {
     ).toBe(
       'path.join(root, `${base}.mdx`), path.join(root, base, "index.mdx")',
     );
+
+    // And that the loop consumes the array UNMODIFIED, in declaration order.
+    expect(
+      LOADER_SOURCE.includes("for (const c of candidates) {"),
+      "lib/docs/load.ts no longer iterates `candidates` directly. Anything " +
+        "between the array and the loop — `.reverse()`, a spread, a sort — " +
+        "changes which candidate wins while leaving the declaration above " +
+        "looking correct. Mirror the new behaviour in `resolveHref`, then " +
+        "update this check.",
+    ).toBe(true);
+
+    // Two mentions and no more: the declaration and the loop. A third is a
+    // mutation of the list (`unshift`, `push`, `splice`) that the declaration
+    // cannot show.
+    expect(
+      [...LOADER_SOURCE.matchAll(/\bcandidates\b/g)].length,
+      "lib/docs/load.ts mentions `candidates` somewhere beyond declaring and " +
+        "iterating it. If the list is mutated after it is built, the array " +
+        "literal is no longer the resolution order — update `resolveHref` and " +
+        "this check together.",
+    ).toBe(2);
   });
 
   it("places Grouping directly after Filtering", () => {

apps/website/content/docs/grid/cell-presentations.mdx

@@ -174,10 +174,15 @@ spotting. The dot restores that as shape and colour at no cost to the label,
 since a dot is a graphical object and owes 3:1 rather than 4.5:1. An untoned
 chip draws no dot.
 
-So both this and `PretableStatus` show a dot, and the chip is what separates
-them: a badge is a noun the row _is_ — a category, a flag — and reads as a
-bounded chip; a status is a state the row is _in_, and reads as a dot beside
-plain text.
+The dot is drawn in `currentColor`, so it is the same hue as the label. That
+makes it a _peripheral_ channel, not a greyscale one: it tells you at a glance
+which rows carry a tone, but in greyscale it renders the same grey as the label,
+and the label is still what distinguishes one tone from another.
+
+So a toned chip and a `PretableStatus` both show a dot, and the chip is what
+separates them: a badge is a noun the row _is_ — a category, a flag — and reads
+as a bounded chip; a status is a state the row is _in_, and reads as a dot
+beside plain text.
 
 `PretableBadgeTone` is `"positive"`, `"negative"`, `"warning"` or `"info"`.
 There is deliberately **no `neutral` member**: a badge with no tone is the

apps/website/lib/docs/__tests__/docs-api-surface.test.ts

@@ -203,7 +203,8 @@ function stringUnionMembers(body: string): string[] | undefined {
     .split("|")
     .map((part) => part.trim());
 
-  if (parts.length === 0) return undefined;
+  // No empty-array guard: `String.prototype.split` never returns one, so a
+  // check for it would be a branch no input can reach.
   if (!parts.every((part) => /^"[^"]*"$/.test(part))) return undefined;
 
   return parts.map((part) => part.slice(1, -1));
@@ -862,9 +863,16 @@ interface ProseEnumeration {
  * is not wrong, and this file's own history says a check that fails on a
  * non-defect is a check the next author deletes.
  *
- * The literal is required in backticks too, and quoted, which is what keeps the
- * badge paragraph's next sentence — "There is deliberately no `neutral`
- * member" — out of the enumeration it is commenting on.
+ * The literal is required in backticks too, and quoted, so that a name-drop
+ * with no members listed is not read as an enumeration of zero.
+ *
+ * It is NOT what keeps the badge paragraph's next sentence — "There is
+ * deliberately no `neutral` member" — out of the enumeration it comments on;
+ * an earlier draft of this comment claimed that, and it is wrong. Sentence
+ * segmentation does it: the enumerating sentence ends at its own period, and
+ * the next one is a separate candidate that never names the type in backticks.
+ * Writing that next sentence as ``no `"neutral"` member`` — the exact shape the
+ * quoting rule was supposed to exclude — leaves this check green.
  *
  * A sentence ends at the first `.` followed by whitespace or end of text, so a
  * decimal inside one (`-0.2`) does not cut it short.

packages/ui/src/__tests__/css-cascade.test.ts

@@ -635,6 +635,32 @@ describe("grid.css cascade contract", () => {
         `badge rule "${selector.trim()}" mixes a fill; the badge's fill is the grid surface, untinted`,
       ).not.toMatch(/background[^;]*color-mix/);
     }
+
+    // The dot a TONED badge carries, which nothing asserted until now — and the
+    // docs page describes it, so deleting this rule silently made that page
+    // wrong. It exists because dropping the tinted fill above fixed the
+    // contrast but left tone readable only by reading the label; the dot puts
+    // it back as shape, so scanning a column is spotting again.
+    const dot = css.match(
+      /:where\(\[data-pretable-badge\]\[data-pretable-tone\]\)::before\s*\{([\s\S]*?)\}/,
+    )?.[1];
+    expect(
+      dot,
+      "no toned-badge ::before rule. The dot is the only tone channel that " +
+        "survives peripheral vision, and `grid/cell-presentations.mdx` tells " +
+        "readers it is there.",
+    ).toBeDefined();
+    expect(dot).toMatch(/content:\s*""/);
+    // `currentColor`, not a per-tone background: that is what makes the dot
+    // track the label's tone with no rule per tone, and it is the claim the
+    // docs page makes about greyscale (same hue as the label, so the label is
+    // still what separates one tone from another).
+    expect(dot).toMatch(/background:\s*currentColor/);
+
+    // Not also asserting the pseudo-element stays outside :where() — the
+    // "no pseudo-element inside :where()" test below already covers every rule
+    // in the file, and it fires on this one. A second copy here would be a
+    // check with nothing of its own to catch.
   });
 
   test("the entity's secondary line is dimmed by a token, never by opacity", () => {