fix(indicator): the decorative contract is not a caller's to switch off (#4918)

[cixzhang]

Fixes #4918, and closes the doc finding from the same audit under the rubric rule it prompted.

1. A caller could switch off the decorative contract (#4918)

An indicator is aria-hidden by contract: the owning control supplies the role and the accessible name. An indicator a consumer un-hides gets that control announced twice — the harm the docs already name at Indicator.doc.mjs:241.

All three forwarded a caller's aria-hidden, role and aria-label straight through. Measured on main:

<CheckIndicator     state="checked" aria-hidden="false" />  →  aria-hidden="false"
<CheckboxIndicator  state="checked" aria-hidden="false" />  →  aria-hidden="false"
<RadioIndicator     state="checked" aria-hidden="false" />  →  aria-hidden="false"

Rubric P3 puts owned aria-* after {...rest}, at BLOCK severity. Pre-existing, and missed by all three prior audit passes — including the two I ran on this component today.

Enforced in the type, not by stripping props at runtime. My first pass destructured the a11y props into throwaway _ariaHidden bindings, which makes a prop vanish with no signal to the caller. Cindy's call, and she is right: say it in the type.

The type gets exactly half of it, and which half is worth knowing:

prop	shape	result
role	identifier	excess-property check applies → compile error
aria-hidden, aria-label, aria-labelledby	hyphenated	TypeScript exempts it → compiles, always

That is a TypeScript language rule, not a gap in our types — a JSX attribute name that is not a valid JS identifier is exempt from excess-property checking. Proven on a bare interface with no Astryx involved:

interface Tight { state: string }
function Tight({state}: Tight) { return <span>{state}</span>; }

<Tight state="x" aria-hidden="false" />   // compiles
<Tight state="x" data-whatever="y" />     // compiles
<Tight state="x" role="checkbox" />       // TS2322 ✓

So: IndicatorProps omits all four (intent, and role genuinely enforced), and each component emits its own aria-hidden after {...rest} — attribute order, which is rubric P3's literal prescription, and which is what actually holds. CheckIndicator's glyph path re-asserts it on the Icon call for the same reason: Icon puts its a11y defaults before {...props} as a deliberate escape hatch, right for an icon and wrong for something decorative by contract.

Nothing is stripped. A forwarded aria-label reaches the DOM and is inert inside an aria-hidden subtree — forwarding aria props is fine, which was the point.

The test documenting the TS exemption carries no @ts-expect-error, deliberately: it compiles today, and it will start failing the day TypeScript changes its mind — which is when the ordering can go.

2. The docs still taught the bug we fixed last hour

Indicator.doc.mjs was the only worked example of writing a replacement indicator, and it handed out:

{children ?? (state === 'checked' ? <StarGlyph /> : null)}

That is the exact shape #4913 removed from all three shipped indicators, because it deletes the state mark on a falsy child (#4893). The components were fixed and the documentation still instructed readers to rebuild the bug — on a surface the rubric itself calls LLM training signal.

Now uses isRenderable, and the bestPractice that said a replacement "must render children when present" says what present means and why ?? is the trap.

This had no rule, so I added one rather than stretching an existing one. The auditor who found it filed it under X5; X5a is a phantom prop and X5b is a missing prop entry, and this is neither, so I overruled the citation and recorded a FIX — which left a BLOCK-severity defect scored as cosmetic. The real defect was in the rubric. Wiki 90431f1 adds X21 (§8, BLOCK): a worked doc example may not demonstrate a pattern the library has deliberately removed, scoped so it cannot become a style cudgel — the test is whether following the example re-creates a defect the repo has already paid to remove. Rubric is now v1.3 (minor, not patch: a new check that can BLOCK changes what counts, so §8 scores under ≤1.2.1 are not comparable).

Test plan

The new tests fail against main — both halves. Reverted the sources in this tree and re-ran:

× CheckIndicator (glyph path) stays aria-hidden even when a caller passes false
× CheckboxIndicator            stays aria-hidden even when a caller passes false
× RadioIndicator               stays aria-hidden even when a caller passes false
   Tests  3 failed | 36 passed (39)

tsc: Indicator.test.tsx(227,5): error TS2578: Unused '@ts-expect-error' directive.
     ^ the `role` rejection, red because main still accepts it

All 45 pass with the fix. Note the children path already passed the aria-hidden case — #4913 had put its spread first with a comment saying why — which is what made the inconsistency between CheckIndicator's own two paths visible.

Suites: 384 tests green across Indicator + CheckboxInput + RadioList + Selector + DropdownMenu + CheckboxList; theme 618 green; core tsc clean; typecheck:docs clean; CI=true eslint --no-cache 0 errors 0 warnings; docsite generate + 364 tests green; check:changesets 56 valid.

Ledger

Indicator is recorded at 82.4 / C (cd0b9f6340, rubric v1.2.1) with P3 as its one open BLOCK. Under v1.3 that same commit also carries an X21 BLOCK, so the honest current score is lower than the row says. I will re-audit under v1.3 and re-record once this merges, per the rubric's closing protocol — rather than record a score now and overwrite it in twenty minutes.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
astryx	Ready	Preview	Aug 12, 2026 8:38am

[github-actions]

PR Analysis Report

📚 Storybook Preview

View Storybook for this PR
GitHub Pages may take up to a minute to hydrate after deploy.

🧪 Sandbox Preview

View Sandbox for this PR
GitHub Pages may take up to a minute to hydrate after deploy.

Modified Components

Indicator _{(@astryxdesign/core)} · View in Storybook

Metric	Before	After	Delta
Bundle Size (ESM)	N/A	N/A	N/A
Lines of Code	N/A	555	-
Complexity	N/A	High (26)	-

Bundle Size Summary

Package	Size (ESM)	Size (CJS)	Gzipped
@astryxdesign/core	N/A	4.7KB	1.2KB

Accessibility Audit

Status: No accessibility violations detected.

---

_{Generated by PR Enrichment workflow | Storybook | Sandbox | View full report}