@godxjp/ui 28.7.0 → 28.8.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@godxjp/ui",
-  "version": "28.7.0",
-  "godxUiMcp": "28.7.0",
+  "version": "28.8.0",
+  "godxUiMcp": "28.8.0",
   "license": "Apache-2.0",
   "repository": {
     "type": "git",
@@ -28,6 +28,7 @@
     "README.md",
     "scripts/visual-audit.mjs",
     "scripts/visual-audit-rules.mjs",
+    "scripts/brand-accent.generated.mjs",
     "scripts/audit-hook.mjs",
     "scripts/init-agent-kit.mjs",
     "scripts/init-guinea-pig.mjs",
@@ -419,7 +420,8 @@
     "visual-audit": "node scripts/visual-audit.mjs",
     "gen:brand": "node scripts/gen-brand.mjs",
     "check:absorbed-names": "node scripts/check-absorbed-names.mjs",
-    "check:frame-overflow": "node scripts/check-frame-overflow.mjs"
+    "check:frame-overflow": "node scripts/check-frame-overflow.mjs",
+    "check:frame-token-wins": "node scripts/check-frame-token-wins.mjs"
   },
   "peerDependencies": {
     "@hookform/resolvers": "^5.2.0",

package/scripts/brand-accent.generated.mjs

@@ -0,0 +1,27 @@
+// AUTO-GENERATED by scripts/gen-email-tokens.mjs — do not edit.
+// Source: src/tokens/foundation.css (:root — the LIGHT scheme).
+// Run `node scripts/gen-email-tokens.mjs` (guard: `node scripts/gen-email-tokens.mjs --check`).
+
+/**
+ * The accent colour(s) THIS PACKAGE SHIPS as its own default — the one accent on a consumer's page
+ * that the consumer did not choose and cannot change without abandoning the GoDX brand (gh#823).
+ * `scripts/visual-audit-rules.mjs` exempts exactly these from the 渋み chroma bound.
+ *
+ * LIGHT SCHEME ONLY, deliberately: the dark `--primary`/`--brand` (#DCBCFF) measures OKLCH
+ * chroma 0.097, comfortably inside the 0.18 bound, so it never reaches an exemption. Listing it
+ * would widen the carve-out for nothing.
+ */
+export const SHIPPED_BRAND_ACCENTS = [
+  {
+    "cssVars": [
+      "--primary",
+      "--brand"
+    ],
+    "hsl": "268.7 100% 50%",
+    "rgb": {
+      "r": 122,
+      "g": 0,
+      "b": 255
+    }
+  }
+];

package/scripts/ui-audit.mjs

@@ -722,6 +722,72 @@ const RULES = [
     message:
       'Hand-rolled list — a raw <ul>/<ol>, an ARIA role="list"/"listitem", or a <li> wrapped around a library row. Build it from <Flex as="ul" marker="none"> (keeps the element, the <li> semantics and the gap token; no bullet, no indent) with <ListRow as="li"> as the rows. A row inside a wrapper of its own is an only child, so its :not(:last-child) divider never matches and every divider disappears silently (docs/CONSUMER-RULES.md §4, gh#714).',
   },
+  {
+    id: "no-hand-rolled-scrollport",
+    replacement: "ScrollArea (label, orientation)",
+    classOnly: true,
+    scope: "consumer",
+    severity: "warn",
+    /*
+     * A scroll container built from an `overflow-*` utility instead of the primitive that exists
+     * for one.
+     *
+     * This is the only "hand-rolled X" rule here that is NOT about consistency. A scrollport with
+     * no tab stop is content a mouse can reach and a keyboard cannot — WCAG 2.2 SC 2.1.1 — and
+     * `ScrollArea` is what supplies the stop, the `role="group"` and a localized accessible name,
+     * withholding all three while there is nothing to scroll (gh#817/gh#821).
+     *
+     * WHY A LINT RULE AND NOT THE AXE RUN. `overflow-auto` on a hand-written `div` appeared ELEVEN
+     * times in this repo's docs. `check:frame-axe` flagged exactly ONE — `/showcase/table-footer-
+     * totals`, 125px of totals below the fold — because axe's `scrollable-region-focusable` PASSES
+     * a scroll container that CONTAINS a focusable element: tabbing to the link inside scrolls the
+     * box. The other ten hold links, buttons or inputs. The one that failed held a read-only totals
+     * table, so there was nothing to tab to.
+     *
+     * So the same markup is clean or broken depending on the DATA, and one link added to that
+     * totals table would have hidden it again. A runtime audit can only ever see the instance whose
+     * content happened to expose the defect; the MARKUP is what is wrong, and markup is what lint
+     * reads. That is also why this rule deliberately does NOT copy axe's focusable-descendant
+     * exemption. Read axe's own source and the reason is plain: EVERY gate it uses is a rendered
+     * measurement. The rule does not even apply unless `getScroll(node, 13)` finds real overflow
+     * and a child's `getBoundingClientRect()` falls outside the container's; the exemption is
+     * `focusable-content-evaluate`, which filters `vNode.tabbableElements` — resolved against
+     * `disabled`, `hidden` and computed style. A lint pass has none of that. Copying the exemption
+     * without the applicability test keeps all of its unsoundness and none of its precision: the
+     * `items.map()` a rule would see may render empty, conditionally, disabled, or with
+     * `tabIndex={-1}` under a roving-focus pattern.
+     *
+     * Prior art says the same. eslint-plugin-jsx-a11y has NO rule for scrollable regions and
+     * declined to add reasoning about them (jsx-eslint/eslint-plugin-jsx-a11y#717: "there isn't
+     * really anything to key off of" — closed as docs); its `no-noninteractive-tabindex` in fact
+     * FLAGS the bare `tabIndex={0}` remedy. Deque's own guidance for this rule says to put a
+     * `tabindex` of 0 on the region rather than rely on a focusable child, "because the browser may
+     * intercept the keyboard events". What this package has that jsx-a11y did not is the thing to
+     * key off: a primitive that makes the guarantee at runtime, where the guarantee lives.
+     *
+     * WARN, not error, and the measurement says why: those ten call sites are not accessibility
+     * failures TODAY, and a rule that opens with a wall of errors against markup that passes the
+     * browser gate is a rule someone deletes (godx-corebooks#114 — 1189 errors made a documented
+     * rule unenforceable). `warn` plus the `--changed` ratchet catches every scrollport an author
+     * touches from here on, and a deliberate one takes an `ui-audit-disable-line` that says why.
+     *
+     * BOUNDARIES. `overflow-hidden` / `overflow-y-hidden` / `overflow-clip` are NOT scrollports —
+     * a clipping box with `text-overflow: ellipsis` is a different and correct pattern — so the
+     * alternation names `auto|scroll` explicitly instead of matching `overflow-` and subtracting.
+     * `(?<![\w-])` keeps the match off the middle of a longer word, which this file has already
+     * paid for once elsewhere: `check-frame-overflow`'s bare /arrow/ matched inside `--n-arrow-`
+     * and reported a page container as an oversized icon. Here the same shape is one line away —
+     * the tabs example carries `id="antd-overflow-scroll"`. `classOnly` is the second guard: an
+     * `id`, a prop or product copy is blanked before this pattern ever sees it. A variant prefix
+     * (`md:overflow-y-auto`, `data-[orientation=horizontal]:overflow-x-auto`) still matches,
+     * because a conditional scrollport is still a scrollport.
+     */
+    test: /(?<![\w-])overflow-(?:[xy]-)?(?:auto|scroll)(?![\w-])/,
+    standard:
+      "WCAG 2.2 SC 2.1.1 (Keyboard) · WAI-ARIA 1.2 (group) · Deque axe-core scrollable-region-focusable",
+    message:
+      'Hand-rolled scrollport (overflow-auto / -scroll on your own element) — use <ScrollArea label={t("…")} orientation> so the box that scrolls is a tab stop with a role and a localized name, and stops being one when there is nothing to scroll (gh#821). Without it, anything below the fold is reachable by mouse and by nothing else (WCAG 2.2 SC 2.1.1). axe only catches the instances whose content happens to have no focusable child, so this checks the markup rather than one render (gh#825). overflow-hidden is a clipping box, not a scrollport, and is not flagged.',
+  },
 ];
 
 /**

package/scripts/visual-audit-rules.mjs

@@ -4,6 +4,7 @@
  * feeds them here; the browser glue stays thin and these rules are fully unit-testable without a
  * browser.
  */
+import { SHIPPED_BRAND_ACCENTS } from "./brand-accent.generated.mjs";
 
 /** Catalog (agent-facing mirror lives in mcp/src/data/visual-rules.ts; kept in sync by a guard). */
 export const VISUAL_RULES = [
@@ -19,7 +20,7 @@ export const VISUAL_RULES = [
     severity: "warn",
     category: "color",
     standard: "@godxjp/ui reference-design 渋み (OKLCH chroma ≤ 0.18)",
-    fix: "Desaturate brand/primary surfaces — keep OKLCH chroma ≤ 0.18. Read --primary tokens; never paint a full-width bar in raw vivid blue.",
+    fix: "Desaturate brand/primary surfaces — keep OKLCH chroma ≤ 0.18. Read --primary tokens; never paint a full-width bar in raw vivid blue. The accent @godxjp/ui itself ships is exempt (gh#823) — this finding is always a colour someone chose.",
   },
   {
     id: "emoji-rendered",
@@ -95,8 +96,51 @@ export function oklchChroma({ r, g, b }) {
 /** reference-design restraint bound. A signal/brand surface above this chroma "screams". */
 export const CHROMA_LIMIT = 0.18;
 
-/** @returns {boolean} true when an accent surface exceeds the 渋み chroma limit. */
+/**
+ * Per-channel sRGB tolerance for "this IS the accent we ship" (gh#823).
+ *
+ * The audit reads a computed `rgb()` off a live page, so the match has to survive whatever rounding
+ * the engine applied on the way there. Measured in Chromium (playwright 1.61), all four routes to
+ * the token — `#7A00FF`, `hsl(268.7 100% 50%)`, the legacy comma form, and `hsl(var(--primary))` —
+ * serialise to exactly `rgb(122, 0, 255)`: today's drift is 0. The tolerance is 1, kept as headroom
+ * for an engine that rounds the other way, not because Chromium needs it.
+ *
+ * WHAT 1 ADMITS, and why it cannot hide a louder purple. The window is the ±1 box around
+ * rgb(122, 0, 255): 12 colours, since g is already at 0 and b at 255 — so 11 that are not the
+ * brand. The nearest of those is rgb(122, 1, 255) / #7A01FF at OKLab ΔE 0.0003; the furthest is
+ * rgb(123, 1, 254) / #7B01FE at ΔE 0.0027, about 1/7 of a just-noticeable difference (~0.02).
+ * None is distinguishable from the brand on a screen. The nearest colour OUTSIDE the window,
+ * rgb(124, 0, 255) / #7C00FF, is still flagged. A tenant who picks a genuinely different loud
+ * purple — #9D00FF (chroma 0.296), #B026FF (0.286) — is 30+ channel steps away and still told.
+ */
+export const BRAND_ACCENT_TOLERANCE = 1;
+
+/**
+ * True when an accent is the brand accent THIS PACKAGE SHIPS (gh#823) — read from
+ * `brand-accent.generated.mjs`, which `scripts/gen-email-tokens.mjs` derives from foundation.css,
+ * so the exemption moves if the brand ever does.
+ *
+ * Deliberately NOT "whatever `--primary` currently resolves to": a tenant who overrides `--primary`
+ * with something louder chose that colour and must still be told. Only the value a consumer
+ * receives from us, and cannot change without abandoning the brand, is exempt.
+ */
+export function isShippedBrandAccent({ r, g, b }) {
+  return SHIPPED_BRAND_ACCENTS.some(
+    (accent) =>
+      Math.abs(r - accent.rgb.r) <= BRAND_ACCENT_TOLERANCE &&
+      Math.abs(g - accent.rgb.g) <= BRAND_ACCENT_TOLERANCE &&
+      Math.abs(b - accent.rgb.b) <= BRAND_ACCENT_TOLERANCE,
+  );
+}
+
+/**
+ * @returns {boolean} true when an accent surface exceeds the 渋み chroma limit.
+ * The shipped brand accent is exempt — it is over the bound (chroma 0.293) but it is not a choice
+ * any consumer made, so reporting it warns every page about a colour nobody can act on, and the
+ * first reader to hit it silences the rule along with every real finding it would have caught.
+ */
 export function isOversaturated(rgb, limit = CHROMA_LIMIT) {
+  if (isShippedBrandAccent(rgb)) return false;
   return oklchChroma(rgb) > limit;
 }