Version 1.15.3; see Versions for what that means and what changed.

This page is a checklist for judging the quality of an Astryx component, and a way to turn that judgement into a score you can track. You almost never run all of it. Find your situation below and go where it sends you.

How the score works, in one paragraph. Each section is scored out of 5 against written descriptions of what 5, 3 and 1 look like, then weighted into a total out of 100 and a letter A–F. Findings are blocking (ship this and something is broken), should-fix (real debt, shippable with a reason), or nit. Any open blocking finding caps the grade at C, however good the rest is. The number measures distance from the bar, not craft — so always read the blocking count next to it, and say what fixing them would get you. Details in Scoring.

Where scores live. In component-scores.json in this wiki — the ledger is a file you edit and push, not a service. Recording your result is part of doing an audit — see Recording an audit. No pull request is gated on a score.

This checklist is how we review. Current in-repo authority records govern policy; linked wiki pages are practical explanations and worksheets. Every check below cites its source so a finding can be traced to the governing record or supporting guidance.

When one of those pages and this one disagree, the applicable current repository record wins on product behavior and this page wins on audit procedure, scoring, and ledger mechanics. Fix the contradiction at the canonical repository owner, then update this guide.

For Night Watch, promotion, and on-demand grading, start with the component's colocated repository spec. If it is missing or incomplete, continue from applicable current authority and checkable evidence. You may optionally prepare verified shipped behavior as a draft observational worksheet for owner review using the repository's component-specification guide. The proposed closed evidence matrix makes every public concept, reachable state, and evidence gap visible for review; it is not a validated gate while spec:AST-029 is draft.

Implementation defines component-local observation when local docs or tests drift. Applicable current shared records and objective standards override conflicting implementation; those conflicts are findings to fix, not behavior to canonize. Unresolved public API, compatibility, ownership, or subjective design questions remain manual. The worksheet is review evidence, not current product authority or auto-merge permission.

Never run the whole checklist on a pull request. A review that costs an hour on a two-line fix gets skipped, and one that lists thirty findings the author did not cause buries the one that matters. Set the depth by what the change is:

Never penalize a contributor for problems they inherited

Review the PR on its own merits. A contributor is responsible for what their diff introduces — never for what they inherited by touching a file.

• No ledger entry for this component? Judge the PR purely on its merits. Do not run a full audit, do not produce a grade, and do not block on anything the diff did not cause. An unaudited component is a gap in our coverage, not a defect in their contribution.
• A ledger entry exists? It is a baseline, not a bar. The ratchet asks one question: did this diff make it worse? A recorded BLOCK with an open issue is known debt and blocks nothing. Only a new BLOCK, or a decrease in score, fails the check.
• A stale baseline never blocks a good PR. Scores trail reality until the next audit; since the ratchet fails only on regressions, a low or outdated recorded score can only ever help a contributor.
• Found pre-existing problems while reviewing? Good — file them per the audit-issue protocol, or leave them for the nightly pass. Do not attach them to the contributor's PR, and do not ask them to fix the component to get their change in. Say plainly that the finding is pre-existing and not theirs to fix.
• The only things a PR must carry regardless are the ones it is itself responsible for: the quick checks (lint, test, build), a changeset for a consumer-visible change, and screenshots for a visual change.

The point of the grade is to ratchet the system upward over time, not to tax whoever happens to touch a file next.

Which checks a change earns

Never run all ~200 checks on a PR. Depth comes from the repo's existing triage in .github/instructions/packages.instructions.md Step 0 — category ×ばつ risk → path — and the specific checks come from what the diff actually touches. State the triage line at the top of the review, as that page already requires:

Triage: bug fix · non-breaking · low blast radius → fast path · checks: §1 A4/A5, §7 C1

The bar, by what the change is. Depth is set by the kind of change, and each kind has its own bar rather than a fraction of the same one:

Change	The bar
Bug fix	Evidence that it was broken before and is fixed now — a test that was red and is now green, or a before/after screenshot for a visual bug. State that evidence in the PR description. Then a code-smell pass (§7, plus whatever the trigger table below fires). If the evidence is real and the fix is clean, the PR is fine — approve it. Do not audit the component around it.
New feature (new prop, variant, behaviour on an existing component)	Run every automatable check — all auto and semi items across the rubric; they are cheap and they are the ones that catch drift. Then a judgment pass on the audit items the change actually touches (trigger table below). Not the whole rubric; not one section either.
New component → core	Full audit — every section, with visual evidence. A new component in core is a permanent public commitment, and this is the case the whole checklist exists for. Record the result in the ledger as the component's first score.
New component → lab	Deliberately lax. Run the automatable checks and the triggered items; flag the rest as "worth an audit pass before promotion" rather than blocking. Lab is explicitly the place where a component is allowed to be unfinished — it is canary-only and promises no stability. Blocking lab on the core bar defeats the point of having lab. The full audit is the gate out of lab, not the entry fee into it.

Everything that goes to core gets the full audit eventually — either as a new component here, or at promotion. Lab just moves when.

Which checks, from what the diff touches. Include a group only when its trigger fires:

If the diff touches...	Run
stylex.create, a *.stylex.ts, or any colour/spacing/radius/shadow value	§2 T1–T3, T12–T15 · §5a D1/D4/D5
themeProps, a *.doc.mjs theming block, or a style-driving prop	§2 T4–T7, T19, T26 · X17
aria-*, role, tabIndex, focus, keyboard handling, or a live region	§1 A1–A7, A11–A12
a :hover rule, a reveal, or a hit target	§1 A8–A10 · §5a D12
a *Props interface, an exported type, or ...rest/mergeProps	§3 P1–P7, P15–P18
useEffect, useState, a ref, or an observer	§7 C1–C8, C11
a user-visible or AT-facing string	§9 I1–I5
a physical CSS property, a directional icon, or RTL-sensitive layout	§9 I8–I13
.doc.mjs props, stories, or a block	§8 X5, X9–X12
rendered output in any way (the visual change test)	§5b — before/after screenshots, required
a published export, or anything consumer-visible	§3 P11–P12 · X20 changeset

Two rules that override the triage:

1. A bright-line failure blocks on any path. If a fast-path PR contains a hardcoded colour, a broken accessible path, or a dropped passthrough, it is still a BLOCK — the triage sets how much you look, never what counts once you see it.
2. Everything else above still holds: judge the diff, not the component; no ledger entry means judge on merits; pre-existing findings are never attached to the contributor's PR.

Why not run the whole thing. A rubric that costs an hour on a two-line fix gets skipped, and a review that lists thirty findings the author didn't cause buries the one that matters. The full checklist earns its cost in modes N, O and P — where nobody is waiting on it.

Mode column below: blank = applies in all four modes. Letters = the modes where the item is enforced (e.g. P = promotion only, PO = promotion and on-demand).

Before any of the graded sections are scored on a PR, these must be green. They are cheap, mechanical, and non-negotiable: a red one is a BLOCK on its own and the review stops there rather than spending judgment on a PR that doesn't build. This mirrors the wiki's 8-item Quick self-review and adds the two the author must have run locally.

A new component (or a promotion) runs the full 27-item self-review instead of the quick list — Component Build Protocol Phase 10 — and then the whole rubric.

Someone asked how good a component is, or you are hardening it. Work every section below, on the whole component rather than a diff.

What this pass owes you:

• Screenshots. The design section is graded from rendered pixels, not from reading CSS — drive a real browser against Storybook and capture every state the component has, in light and dark. Skipping it is allowed; pretending you did it is not, so an uncaptured section is reported as not measured rather than scored.
• A score per section, read against its 5/3/1 descriptions, then the weighted total and letter.
• A recorded result. An audit nobody recorded didn't happen — see Recording an audit.
• An issue per blocking finding, linked from the ledger row, so the work is tracked where the next person will look.

Do not hold a shipped component to the promotion paperwork — no spec issue, no arbitration record, no vibe artifact is required of something that already lives in core. That is promotion evidence, and demanding it retroactively grades history instead of the component.

A component moving from lab into core becomes a public, stable commitment, so this is the strictest pass — everything in Grading a whole component, plus:

• Screenshots are mandatory, not optional: every state, light and dark, at least one custom theme, plus a narrow viewport and a touch pointer.
• Every accessibility item verified in the promotion pull request — that is a hard requirement, not a judgement call.
• The lifecycle evidence applies here and only here: the spec issue, the API arbitration record, the hardening pass. Missing evidence is called out loudly but does not block on its own.
• The bar is a B or better, with nothing blocking open.

Lab itself is deliberately loose — it is canary-only and promises no stability, so a new component landing in lab gets the automated checks and whatever the change touches, and everything else is noted as worth an audit before promotion. The full pass is the gate out of lab, not the entry fee into it.

An automated audit takes one component a night from every component-bearing package registered in scripts/component-packages.cjs. It may prepare a missing contract as a draft observational worksheet, gives the component the full treatment with screenshots, fixes objective gaps with a settled answer, then runs a second audit to prove the fixes worked.

The same pull request may contain that draft worksheet plus missing behavior tests, stable visual-regression snapshots, consumer-doc drift fixes, and implementation bugs. This flow is manual-review-only today. Draft spec:AST-029 proposes a fail-closed auto-merge gate, but it cannot activate until that record becomes current together with a versioned component template/schema that validates its evidence matrix. Public API, compatibility, ownership, and subjective design decisions always remain manual.

It picks from the ledger—never-audited first, then oldest-audited, then lowest-scoring. It records the post-fix score, and the before/after pair goes in the pull request. This does not change grading or promotion modes: those retain their per-BLOCK issue and recording rules.

Anything needing a decision rather than a correction — a naming dispute, a new prop, a visual judgement call — it does not touch; those go to the PR's Needs Review section. Findings it could not fix stay in the ledger row against the component. It files no issues, except for a genuinely system-level problem that no single component's PR could fix.

The ledger is its only record of progress: what has been audited, when, under which version, and what is still open. Full mechanics in Night Watch Component Auditor.

Eleven sections. Each check has an id (A8, T6, P2...) — cite the id when you report a finding, so the reader can look up exactly what you applied.

Verification class per item. auto = a rule, test, or script fails and names it. semi = a grep/script produces candidates, a human adjudicates. manual = judgment.

Severity per item, from .github/copilot-instructions.md ("score the failure, not its likelihood"):

Section score, 0–5, anchored. Every section has explicit 5 / 3 / 1 anchors. Mechanical floors act as ceilings on the anchor read, graded by how much is wrong rather than whether anything is:

Read the anchor first, then apply the ceiling. The anchors describe the property; the floors cap how high that read can land. A single BLOCK does not by itself mean 2 — v1.1 raised the ceiling to 3 but left "no BLOCKs" written into the 3/5 anchors, which made the change decorative in the three heaviest sections. Anchors no longer say "no BLOCKs"; if one still reads that way, the ceiling governs.

Calibration note. v1's floor was "any BLOCK ⇒ ≤2", and the first trial run graded five shipped core components at 41–63 — four Fs and a D, including components that are effect-free, fully ARIA-wired and heavily tested. v1.1's graded floors plus deduplication moved the same evidence to 48–74, a real spread. The 2.5 half-step above came from the SideNav re-score: a compound component with five sub-components gives every rule five chances to be violated, so the second BLOCK is far likelier than the first, and a flat 2 ⇒ ≤2 cliff pinned four sections carrying 46 weight at exactly 2 with no discrimination between two defects and five.

The grade measures distance from the bar, not craft. Two graders independently noted that a reader takes the letter as "how good is this component" while the number says "how far from clean is it." A mature, widely-composed component with four narrow defects can land below an immature one with none. So: always report the BLOCK count in the headline, and always report the sensitivity line — "fix the N open BLOCKs and change nothing else → projected X". That projection is the actionable number; the letter alone is not.

One defect, one score. A single root cause frequently maps to items in three or four sections (an unguarded transition is A13 and T25 and D12; a dropped passthrough is T2 and P2 and R9). Score it once, in the section that owns the fix, and cross-reference it in the others without scoring it there. The scorecard reports both a finding count and a distinct defect count; the second is the honest one.

Which section owns it — tiebreak. Ownership is load-bearing (a defect moved from §1 to §9 is worth ~3 points), so don't argue it per audit: the owner is the section whose enforcer would catch it (the i18n lint rule ⇒ §9; @eslint-react/purity ⇒ §7; themingTargets.test.ts ⇒ §2). If no enforcer exists, the owner is the section containing the file you would edit to fix it.

Consequences are scored at the root. When defect B only exists because defect A is unfixed (a link/button element swap that disappears once busy-disables is fixed), score A and note B as downstream. Fixing the root must visibly move the score.

Deduplication does not inflate. A defect cross-referenced into a section still fails that section's anchor property — it simply doesn't count toward that section's floors. A section may not score 5 on "composes existing primitives" because the reimplementation it contains was scored elsewhere.

Shared-module findings. When the defect lives in a shared style module or shared primitive (Field/inputStyles.stylex.ts, a base hook) rather than in the component under audit, report it at advisory severity against this component — it does composite the result — and route the fix to the owning module per §11 L12. Do not let eight consuming components each take a BLOCK for one shared file.

Token-inherited failures. When a contrast or token-role failure originates in the token layer rather than the component (the component composites a token pair it cannot change), it is not scored against the component at all while the system-wide fix is open — report it as known systemic — tracked in #4652 (widespread WCAG AA contrast failures across the design system; program tracker #4475) and move on. A component may not be marked down for a defect that lives one layer below it and is already being worked. If the pair is genuinely component-specific — the component picked the wrong token, rather than the token being wrong — that is a normal finding against the component.

Promotion-lifecycle checks apply to promotion PRs only. §11's spec/arbitration/vibe/hardening evidence and the lab→core gate items exist to grade a promotion diff. For a component that already lives in core, the lifecycle rider is not run — do not report a missing spec issue, arbitration record, vibe artifact, or self-review as a finding against a shipped component. Only L4 (review gate), L14 (changeset) and L15 (no public-repo leak) apply to an ordinary PR.

Migration rules bind released surface only. Q11, T33, P11, X20 and I7 all require a [breaking] changeset and an astryx upgrade codemod when a public surface is removed, renamed or retyped. Every one of them exists to protect installed consumers. Where there are none, the rule does not apply — there is no surface to break, nobody to migrate, and nothing for a codemod to rewrite.

Establish that first, before citing any of them. A surface is released when it is present in the latest published version of its package:

npm view @astryxdesign/core@latest exports --json | grep -i '<Subpath>' # is it published?
ls .changeset/ | xargs grep -l '<the feature>' # or still pending?

An entry still sitting in .changeset/ has never shipped. A whole component can be unreleased: Indicator merged 2026年08月11日, core@0.3.0 had gone out on 2026年08月05日 with no ./Indicator subpath, so every export in that layer was unreleased for its first week in main — and an audit recorded a P11 BLOCK against it anyway, for omitting props from a type no consumer could install (#4937, withdrawn). Both the auditor and the fix author cited the rule correctly against its text; neither asked whether the export had ever shipped.

When a migration rule does apply, it grades the diff — record it on the PR, not durably on the component. These are the only rules in this rubric whose subject is a changeset, and a changeset is consumed and deleted at release. A BLOCK derived from one therefore evaporates on its own, with nobody fixing anything, and the next audit sees an unexplained score jump. In modes N and O (grading a component), report a migration failure as a FIX with the PR named, and raise the BLOCK on the pull request in mode R, where it can actually be acted on before merge. L14 already works this way — scoped to a PR, ungraded — and it is the model for the other five.

A finding needs a reachable victim. "Score the failure, not its likelihood" is right, and it is about users: a state only 2% of people hit is still a real state, and a rare trigger never downgrades a defect. It does not license grading a defect that nothing can currently reach. Before recording one, name who suffers and how they get there.

The test is whether a path exists, not whether it is common:

The distinction matters because the second and third rows look identical in a scorecard — both are "a consumer could...". The difference is whether the API permits it. tabIndex on an indicator is the worked example: axe genuinely reports aria-hidden-focus for a focusable node in a hidden subtree, measured 0 → 1 violation, which reads like a solid finding. But no call site in core passes it, IndicatorProps omits it so a literal is a compile error, and no doc mentions it — the only route left is spreading a hostile object at a component whose type forbids it. That is a NIT, and it was recorded as a FIX, which produced a PR carrying a new internal module to strip a prop nobody sets (#4947, slimmed to the one-line type omission).

Corollary: prefer the type over a runtime guard, and say so in the finding. When a defect is already unrepresentable in the API, the remaining runtime hole is usually not worth a mechanism. Adding one buys a rare case and costs a module, an indirection, and a second thing to keep in sync — and it is inconsistent unless every sibling prop gets the same treatment. A finding that can be closed by a type change should say that, rather than leaving the fix shape to whoever picks it up.

Anchors are property-based, not component-based. An earlier draft named live components as the bar ("Button is the reference", "Button.test.tsx is the shape", "Section, Tooltip, SideNav are a 3"). Calibration killed that: Button scored 2–3 in the very sections that named it as the 5. Naming a component in a normative anchor makes it ungradeable by construction and inflates it by reputation. Component names below appear only as non-normative "current best example" pointers, and they carry the date they were true.

Overall grade = Σ (section score ÷ 5 ×ばつ weight), out of 100.

Gates layered on the grade

• P (promotion): zero open BLOCKs and overall ≥ B and every Accessibility Checklist item verified in the promotion PR (hard requirement, packages/lab/README.md).
• R (PR review): any BLOCK ⇒ lead with 🔴, recommend request-changes, cite the specific rule, point at the concrete fix.
• N (nightly): publish the objective subscore as objective: x/y checks — do not synthesize a letter grade from an automated pass alone.

N/A handling. Mark an item N/A with a reason (a non-interactive display component has no keyboard items). N/A items leave the section and its weight redistributes proportionally. A component cannot N/A its way out of §1 or §2.

limited sections — keyed to vacuous passes, not to N/A. A section whose items mostly cannot fail for this component is not measuring it. Mark a section limited when fewer than one-third of its items produce a non-vacuous verdict, where a vacuous pass = the item's failure mode is structurally impossible here ("don't hold DOM in state" passes because there is no state; "no hardcoded strings" passes because there is no text). Score vacuous passes as N/A. Report a limited section's score for information and redistribute its weight.

This replaces the earlier N/A-count trigger, which fired on inapplicable items but not on items that pass by absence. The Badge re-score measured the leak: 19% of its grade was being awarded for absence, worth ~3.4 points on §7 alone. Re-keying to vacuous passes removes the need for a separate small-display-component weight profile.

Redistribution is proportional — and a section that was not measured never receives it. Freed weight is spread across the sections that actually applied, in proportion to their weights. A section scored 0 or reported not measured is excluded from receiving redistributed weight; otherwise marking sections limited amplifies an evidence penalty by growing the very section that cannot score.

§5 splits into objective and rendered-judgment halves. §5a (objective visual conventions — grid, radius, heights, type hierarchy, overlays, stacking, motion) is statically gradeable and the nightly auditor runs it. §5b (rendered judgment — monotonous spacing, contrast in context, state-visual conformance, proportion/density/composition, AI tells) is screenshot-gated: without visual evidence it is reported not measured, excluded from the total, and its weight redistributed to the sections that were measured. It is never scored 0. A zero asserts "the visual design is maximally bad" in place of "nobody looked" — the trial run showed that artifact moving the letter by a full band on three of five components. The gate keeps its teeth where it matters: a promotion cannot pass with §5b unmeasured, and any audit that skips it must say so in the headline.

Current in-repo accessibility records govern policy. This rubric turns those requirements into gradeable checks and uses the wiki Accessibility Checklist as a practical review worksheet. pr-a11y (axe) catches the static DOM subset only. Keyboard, focus, and announcement behavior still need the ordinary reviewer/test evidence below. When the claimed outcome depends on AT-specific focus exposure or order, spoken/braille output, virtual-cursor entry, mode change, or a known AT/browser divergence, AST-009 assistive-technology verification adds the required real-AT evidence and stable-release handling.

5/5 — the APG pattern is named and linked; keyboard complete in both directions including RTL; focus trapped and restored; state in ARIA, not just pixels; announcements via useAnnounce from callbacks; loading actions retain focus and block duplicate activation unless explicitly interruptible while busy editing controls remain focusable; every action works with a coarse pointer; targets meet WCAG 2.5.8; reduced-motion and forced-colors honored; a disabled control paints nothing under the pointer and answers it with default; axe green with a shrinking baseline; and the behavior is asserted in tests, not merely claimed. 3/5 — named, roled, keyboard-operable, axe green, with at most one blocking defect in an otherwise sound surface: focus restoration is untested, one state is visual-only on a non-critical path, or the coarse-pointer hit area was never measured. 1/5 — any of: an unnamed interactive element; a state visible only as color; a keyboard trap or pointer-only interaction; focus lost on open/close; a hand-wired aria-live; a hover-only path to a destructive action; a target under 24px; a new baseline entry added to silence axe.

Enforced by two Vitest guards — packages/core/src/theme/themingTargets.test.ts and derivedVarRegistry.test.ts — plus internal/eslint-plugin-astryx. Note: there is no lint-theme-targets rule on main, and the plugin is two-tier — pnpm lint warns, CI=true / lint:strict errors. Warn-tier green is not a defense.

T1 exceptions — where a colour literal is legitimate. The rule protects themeability of shipped component styling. A literal that cannot affect a consumer's theme is not the defect the rule was written for; flagging it is a false positive, and one that trains people to ignore the rule.

Clean — not a finding:

• Theming demonstrations. A story, sandbox page, docsite example or test that shows what a custom theme looks like must use literal colours — a theme author writes literals, and that is precisely the thing being demonstrated. defineTheme({tokens: {'--color-accent': '#7c3aed'}}) in a theming story is the feature working, not a violation. Same for MediaTheme demos and swizzle examples.
• Theme packages (packages/themes/*) — defining token values is their entire job.
• The token layer itself (theme/tokens.stylex.ts), which defines the primitives everything else references.
• On-media absolutes used as documented (--color-on-dark / --color-on-light).

FIX, not BLOCK: test fixtures and deliberate *.test-violations.* files — but they must not ship in a published entry point.

Still BLOCK, wherever it appears: a literal in a component's own styling; a literal presented as the recommended way to style a component (an example that reaches for xstyle={{color: '#7c3aed'}} instead of a token teaches the wrong thing — that is a docs-quality finding under §8, and a BLOCK if it is the primary example); and any literal that a theme would be expected to reach.

The test to apply: would a theme author expect to be able to change this colour? If yes, it must be a token. If the literal is the theme author's input, it is correct as written.

T14 is scoped to the main render path. The rule protects the surfaces a consumer actually composes with — the default rendering, where an extra node takes the component out of its parent's flex/grid relationship (bug #4752). A component may also have secondary render paths that exist to be composed into a host: SideNav's drawer-content mode renders its items inside a drawer that MobileNav owns and styles. Judging those paths against T14 is a category error — the host owns the layout and the styling there, and the path exists precisely to hand its content over.

On a secondary path, a wrapper is allowed when it carries something the fragment cannot — consumer xstyle/className/style/...rest, a ref, or semantics. Say which, and say why the host cannot carry it instead.

What still applies everywhere: the wrapper may not silently change the host's layout contract (if the host lays its children out directly, a wrapper that breaks that relationship is a bug wherever it appears), and it must not duplicate a theme target the host already carries — a second name for a concept the host already exposes. A distinct target for the layer's own concept is allowed; T28 says where the line is.

This scoping is specific to rules about which element owns the styling. It does not generalise. Correctness rules — a11y, i18n, tokens, passthrough — hold on every path a consumer can reach, and so does D12: a layout animation costs the same reflow wherever it runs.

5/5 — every visual value is a token or token-derived, including shadows; semantic tokens chosen by role; themeProps on the painting element carrying every style-driving prop, with targets[]/vars[] updated in the same diff so both Vitest guards pass unmodified; new targets justified by a named consumer need and converging with siblings; no new DOM node — style rides on xstyle, state transforms on the targeted element; CSS-native mechanisms verified against CAPABILITIES.md; extensible variant maps with a type-level regression test; verified in light, dark, a custom theme and MediaTheme with screenshots. A theme author could restyle it without ever opening the source. 3/5 — at most one blocking defect in an otherwise sound theming surface, or one or two cosmetic FIXes (a raw textSizeVars size, an arguably-wrong neutral gray, a sub-target that should have been inheritance, a raw duration, an un-tokenized layout constraint). Guards and strict lint pass; every surface a theme could previously reach it still can. Light/dark checked; custom theme and on-media assumed rather than seen. 1/5 — a raw hex anywhere; a target or token replaced by a fixed value, or pinned via xstyle/style; an undocumented rendered astryx-* class (themingTargets.test.ts red); a style-driving prop missing from themeProps; a new style-only or transform-carrying wrapper; a hand-rolled workaround for a supported StyleX feature; @layer/@property in output; an unguarded :hover; a new inline <svg> shadowing a registry icon; a missing 'use client'; a removed target key with no changeset or codemod.

"Public API shape is hard to walk back — treat it as blocking, not a nit" (copilot-instructions). The enumerated conventions the wiki names, carried by value rather than by link:

The conventions themselves are not restated here — API Conventions owns them, and an audit finding must cite its section. The axes the items below grade: component and file naming and the file header; hook, context and type naming; boolean is/has and callback on{Verb}{Scope?}; onOpenChange for layer components only; enum casing and the shared vocabulary; start/end for direction; html-prefixed native collisions; required vs optional; slots as passthrough and behaviors as hooks; BaseProps plus ...rest capture and per-category precedence; controlled inputs and default-prefixed uncontrolled state; and the async transition pair (clickAction + useTransition, changeAction + useOptimistic), where busy controls retain focus and busy actions guard duplicate activation unless explicitly interruptible.

Contributor hard stop (R mode). If a PR adds a new prop or other public API surface and the author is not in .github/ENGOWNERS/DESIGNOWNERS, do not approve — flag "⚠️ Needs human/maintainer judgment on the API surface." Naming disputes route to API Arbitration (build both, vibe-test, override rate decides), never to in-thread debate.

5/5 — the API is indistinguishable in shape from its best sibling: every convention above holds, ...rest is captured and forwarded to the primary element with per-category precedence handled deliberately, controlled/uncontrolled is one clear owner, types are derived not hand-maintained, docs and defaults agree with source, and any new axis reuses an established name and vocabulary. 3/5 — the shape is right, with at most one blocking convention violation, but the surface is untidy: a hand-maintained variant union, a missing type export, a default that drifted between source and doc, one prop whose name is defensible but not sibling-aligned. 1/5 — a public convention violation: a boolean without is/has, onValueChange as the primary change callback, dropped ...rest or a clobbered consumer handler, xstyle/className overwritten instead of merged, a new required field on an existing type, or a breaking rename with no changeset and no codemod.

Hardening Layer 2: issues with a clear right answer. Plus the adversarial pass — try to break it through the public API. If the component has the prop, the state must work; if the API allows it, it must not produce a broken experience.

5/5 — every state the API promises renders correctly and distinctly in light and dark, edge cases are demonstrated in stories rather than argued, the adversarial pass found nothing (or found and fixed it in the same PR), and composition inside Dialog/Table/Card is shown working. 3/5 — the common states are right; one state (usually loading, empty, or overflow) is unverified or slightly off; no adversarial pass was run. 1/5 — a state the API promises looks identical to default; a control clipped or unreachable; layout collapses on empty or long content; a latent passthrough drop.

§5a — objective (weight 6): D1, D2, D4, D5, D6, D8, D9, D10, D11, D12, D14. Statically gradeable from source; the nightly auditor runs these. §5b — rendered judgment (weight 4): D3, D7, D13, D15, D16 plus the state-visual conformance matrix. Screenshot-gated. With no visual evidence, §5b is reported not measured — excluded from the total with its weight redistributed, never scored 0 — and a promotion cannot pass without it.

Check tokens, not numbers. Spacing, radius, size and type scales are all theme dials — defineTheme derives them from a base and a multiplier, and a theme may legitimately ship a different resolved scale. Every check below asks "is this value a role token, and is the relationship right in the resolved scale?", never "is this value 8px?". A rendered number differing from the neutral default is not a finding; a raw literal, a token used for the wrong role, or a broken relationship is. The only numbers stated as absolutes here are external standards a theme may not tune away: WCAG contrast ratios, the ×ばつ24 target-size minimum, and the 12px body-text legibility floor.

From Design Conventions. That page marks each convention 🟢 objective (auditable) / 🟡 assisted / 🔴 judgment. The nightly auditor runs the 🟢 rows automatically and captures the full screenshot set for §5b. It evaluates the 🟡/🔴 rows as review recommendations, never as settled product authority: any such finding stays in Needs Review, is not auto-fixed, and keeps the PR manual.

⚠️ Visual evidence is mandatory for this section

§5 is graded from rendered pixels, never from source. A grade for this section is not valid without screenshots attached to the audit.

What must be captured. One screenshot per applicable state — rest, hover, focus-visible, active/pressed, disabled, loading, each status value, selected/current, empty, and overflow (long text) — in both light and dark, plus at least one non-default theme (packages/themes/*) for modes P and O. Every variant and size the component ships gets its own rest capture. If a state exists in the API, it needs an image; "N/A" must name why the component has no such state.

How to capture. Drive real Chrome/Chromium with Playwright against the local Storybook (or the Vercel preview) and screenshot the actual component. Every frame carries the canonical screenshot sensor receipt proving the build/worktree SHA, exact story id, rendered theme and color mode, computed direction, viewport/DPR/media, semantic state, visible subject geometry, settled fonts/animation state, and absence of page/Storybook errors. Use captureWithSensors() from the review probe kit. Before/after receipts must match on every sensor except Build; absent or failed receipts make §5b not measured. getComputedStyle readings (exact hex, px, line-height, radius) are supporting evidence alongside the image — never a substitute for it.

Then look at the images. The 🟡/🔴 rows below (D3, D13, D15, D16) are judged by eye from the screenshot. Do not infer appearance from CSS source or reason about what the code "should" render.

Scoring consequence. No screenshots ⇒ §5b is not measured: excluded from the total, weight redistributed, and named in the headline. It is never scored 0 — a zero asserts the design is maximally bad in place of saying nobody looked. §5a is unaffected and still scored from source. Partial coverage (some states missing) caps §5b at 3/5. A visual change with no before/after pair caps §5b at 3/5 when reviewing. A promotion cannot pass with §5b unmeasured.

Deliverable format. A labelled contact sheet — <Component>__<variant>__<state>__<theme>.png — attached to the audit issue, the PR comment, or the calibration tab, with the diff called out between before/after pairs.

Required: the state-visual conformance matrix

Capturing the states is only half the check. Every captured state must be matched to one of the approved state representations in Design Conventions , and the screenshot judged against that representation's reference image and token signature. Reuse before inventing is the rule; an unnamed, novel treatment is a finding, not a style choice.

Match the archetype first, then the mechanism — not the pixels. A representation belongs to the kind of thing it was written for: scale(0.98) on press is a button depressing, and applying it to a nav row or a table row is a category error. Before scoring a state against a representation, ask whether the component is that kind of control; if it is not, the representation does not apply and its absence is not a finding.

Match the described mechanism, not the pixels. Read each representation's description and check that the component implements that mechanism — the reference image is an illustration of the mechanism on one component, not a target to match 1:1. Hover is the clearest case: "--color-overlay-hover tint layered over the base" means the hover color is the component's own base color with an alpha overlay composited on top, so a hovered ghost button, a hovered menu row, and the reference secondary button are all correct while looking nothing alike. What you are verifying is "is this the overlay mechanism over this component's base?" — not "is this the same shade as the screenshot in the wiki?" The same holds for focus (an accent outline at the documented offset, whatever the control's shape), selection (which of the five selection styles the family uses), and status (muted vs inverted prominence tier). Judge the mechanism and the token role; use the reference image to recognize the pattern, and getComputedStyle to confirm the composite actually resolved from the right token.

Emit this table alongside the contact sheet — one row per captured state:

State captured	Screenshot	Approved representation it claims	Token signature present?	Matches the reference?	Verdict
e.g. hover	Button__secondary__hover__light.png	Hovered (Overlay style)	--color-overlay-hover tint over base ✓	yes	pass

The approved representations live in Design Conventions §Consistent State Representations — that page owns the catalogue, its reference images, and the token description for each. Do not restate it here; cite the row you matched. What this rubric adds is the verification: for each captured state, name the row, then confirm from the screenshot (with getComputedStyle as corroboration) that the row's token signature actually resolved —

Row you matched	Signature that must be visibly present
Hovered — Overlay style	an alpha tint over the component's own base, not an opaque fill
Hovered / Focused — Ring style (fields)	an inset ring, not elevation
Pressed	the pressed overlay, not a color swap. scale(0.98) is the button treatment — a self-contained control that depresses. Do not require it of other archetypes: a nav row, list item, table row or menu item takes the overlay alone, and shrinking a full-width row on press is wrong, not missing. Match the archetype, then the representation.
Focused — Outline style	an offset outline, visible in every theme
Selected (any of the five styles)	the matching ARIA state (aria-checked / -selected / -current / -pressed) backs the visual
Dragging — Ghost preview	50% opacity only while actively dragging; no raised-card shadow
Drop target — Insertion line	surrounding items stationary until release
Disabled	native disabled, not a visual alone
Loading / Processing	aria-busy; focus is retained; actions use aria-disabled plus activation guards unless explicitly interruptible; dimensions stay stable
Status — Muted or Inverted	an icon is present — never color alone

Agent states (thinking, reasoning, streaming, tool-executing, awaiting input, syncing, inspecting, rendering) have no approved visual yet. They get no automatic failure: flag the state as an open design question, say which User/System representation it borrows from, and route it to the spec loop.

How to score the matrix. Every captured state matched to a named representation whose token signature is visibly present, and consistent with the component's family ⇒ D13 passes. A state that implements an approved representation badly (opaque hover fill instead of an alpha tint, a raised shadow on a drag ghost, dimensions jumping on load) is a BLOCK via the relevant D-row. A state that invents a new representation where an approved one fits is a FIX — and if it is genuinely a new archetype, it routes to the spec loop, not to the PR. An agent state gets no automatic failure: flag it as an open design question and say which User/System representation it borrows from.

Required: the contrast pair matrix (D7)

Contrast is measured from rendered pairs, not from isolated tokens. For every applicable screenshot state, record each meaningful foreground, its actual rendered backdrop, the resolved colors, the ratio, the threshold, and pass/fail. Alpha foregrounds are composited over the backdrop before measurement; if the backdrop is translucent, resolve the complete stack. The browser-rendered result is final.

Decide applicability before doing the arithmetic. For every painted part, run the removal test: if removing that part changes whether a user can identify content, a control, its state, or meaningful graphical information, it is meaningful and belongs in the required matrix; if the same information remains clear through text, spacing, structure, or another qualifying cue, it may be decorative or redundant. Still record decorative relationships when useful for visual review, but label the exception and do not turn an informational ratio into a WCAG failure. Re-evaluate the decision for each state and composition—a border can be decorative on a static Card and required on an otherwise indistinguishable interactive target.

Verify the artifact the consumer actually loaded. Source-theme math is predictive evidence, not a rendered measurement. Before recording a ratio or claiming a fix is visible: identify the exact import path used by the preview or consumer; rebuild any generated theme CSS, package dist/, registry, or other compiled artifact on that path; restart or invalidate the consuming dev server when its module graph may cache the old artifact; then read the foreground, background, overlays, and inherited custom properties from the actual rendered element in every audited state. Calculate contrast from those final computed and composited colors. A successful source test, a generated CSS file on disk, or an HTTP 200 response does not prove the open page loaded that build. If the rendered colors disagree with the source calculation, the rendered result wins and the audit remains failing or not measured until the build/cascade discrepancy is explained.

Thresholds — WCAG 2.2 AA:

• Normal text and text in images: ≥4.5:1 (1.4.3).
• Large text: ≥3:1 — at least 24 CSS px regular or 18.66 CSS px bold.
• Meaningful non-text UI and graphics: ≥3:1 against adjacent colors (1.4.11). This includes control boundaries needed to identify the control, meaningful icons, state indicators, and focus indicators.

Pairs and states: measure labels, values, supporting and placeholder text, icons, control boundaries, selected/current indicators, status/error treatment, and focus indicators in every applicable state: rest, hover, focus-visible, active/pressed, selected/current, loading, read-only, and each status value. Run the matrix in light and dark and the required non-default theme. A theme-elevation review runs the full supported component/state matrix for that theme; sampling one component or inheriting a pass from the neutral theme is insufficient.

Exceptions: record the exact exception beside the pair. Incidental text or graphics, decorative content, logotypes, and genuinely inactive controls may be exempt under WCAG. Decorative/redundant Astryx tokens such as a hairline separator, skeleton fill, or track may be below 3:1 only when another qualifying visual carries the boundary or state. "Secondary," "muted," "subtle," or "the token already existed" are not exceptions.

Start from the component's contrast profile. The component accessibility section must inventory its rendered parts, actual backdrop relationships, variants/states, thresholds, and recorded exceptions as defined by Accessibility Checklist §Component contrast profiles. Expand every applicable profile row into this audit's rendered pair matrix. Do not substitute one generic "component contrast" number for the individual relationships, and do not inherit a pass merely because another component uses the same tokens. If the profile is missing or incomplete, derive the matrix from the rendered anatomy anyway and record the documentation gap; missing documentation never makes a pair not applicable.

Keep shared relationships visibly shared. When components intentionally use the same semantic combination—Badge and Token pills, Banner and FieldStatus status surfaces, or the shared bordered-input foundation—the audit records both the shared token relationship and each component's independently rendered result. This catches both kinds of drift: a component leaving the family, and a shared token failing on one component's different backdrop or state.

Minimum per-component evidence: name the part; state whether it is meaningful, redundant/decorative, or conditionally meaningful; name foreground and complete rendered backdrop; enumerate variants/states and parent surfaces; record the threshold/exception; and include nested or consumer-supplied content the API explicitly supports. Disabled, busy, and read-only are separate applicability decisions—never collapse them into one "inactive" row.

Button/composite-control decisions: visible normal-size labels are 4.5:1 in rest, hover, and pressed without rounding; large text uses 3:1 only at the WCAG size threshold. Meaningful icons—including icon-only controls—are 3:1, while label-redundant icons are decorative; removal changing the action or state is the test. A boundary is measured only when needed to identify the control because sufficiently contrasting text or an icon can carry that identification. Focus remains a separate 3:1 state check; the two-pixel perimeter-area rule is WCAG 2.2 AAA, not AA. For loading, measure the meaningful spinner arc against the button background at 3:1; a redundant track may be decorative, but the active indicator does not inherit disabled opacity merely because activation is temporarily blocked. For end content, measure visible badge/count text against its composited badge surface at 4.5:1; badge-to-button separation is decorative when the text carries the meaning, while an unlabeled dot or color-only mark is meaningful non-text content. Custom ReactNode content is judged from the final rendered result, not exempted by ownership. The inactive-control exception applies to genuine disabled treatment, not to progress information communicating an operation still underway.

Input/composer decisions: TextInput, ChatComposer, and shared bordered-input components use one baseline matrix. Measure visible field/composer text, placeholder, description, counter, and status text against their actual surfaces; meaningful icons and nested clear/send/attachment controls against their own surfaces; any boundary needed to identify the editable region or state against every supported parent; the keyboard focus-visible cue against the surface on which it is visibly drawn; and warning/error content against the fully composited semantic surface. The status surface itself may be decorative when explicit message text carries the status. Disabled is exempt, while read-only and active loading remain applicable. Component-specific actions extend this matrix rather than inheriting a generic input pass.

Progress decisions: classify each ProgressBar presentation before scoring it. A standalone bar has no nearby visible text that communicates the current value or an equivalent progress state; a name-only label such as "Uploading" is not equivalent. Its completed and remaining portions therefore need a 3:1 graphical distinction and its total extent must be unambiguous. Astryx may supply that extent with a contrasting track, endpoint, or another tested cue; the endpoint technique is an Astryx design decision, not a WCAG-prescribed pattern, and is sufficient only when the rendered fill and endpoint make current and total positions clear. A supplemental bar has nearby visible text carrying the current value or an equivalent progress state; measure the text, and allow the graphical treatment to be supplemental or decorative when removing it does not change understanding. In determinate mode, measure fill against track when the visual proportion carries progress. In indeterminate mode, measure the moving segment against its rendered backdrop only when it is the visible loading cue; an equivalent visible loading message may make the animation and static track redundant or decorative. Meaningful target marks are measured against every placement they can overlap. Semantic fills may reuse Badge color families, but status cannot be communicated by color alone. The inactive-control exception applies only to a genuinely inactive UI control. A canceled progress graphic is not automatically exempt, and an active indeterminate operation is not inactive merely because duplicate activation is blocked.

Card/container decisions: use this table to determine whether a painted Card surface is part of the required contrast matrix.

Rendering	Contrast treatment
Static Card whose grouping remains clear from content, spacing, and headings	Background, border, and elevation are decorative; measure the content against the Card surface, not the Card against the page.
Color variant with a visible category/status label	Surface-to-parent separation is decorative; measure the label and every meaningful icon against the colored surface.
Color is the only cue whose removal changes understanding	First fail SC 1.4.1 and add a non-color identifying cue. Then reassess the surface: if the new cue preserves meaning without the tint, the surface is decorative; otherwise measure the remaining required graphical relationship at 3:1.
ClickableCard	Measure its boundary at 3:1 only when that boundary is required to identify the whole interactive target; always measure focus and meaningful content separately.
SelectableCard	The selection ring or equivalent visible state indicator is meaningful and needs a perceptible 3:1 relationship with the adjacent surface it relies on. For an indicator split across surfaces, measure the portion that communicates selection rather than automatically requiring every segment to contrast with both; selection must also be programmatically exposed.
Disabled ClickableCard or SelectableCard	The inactive-control exception applies; do not reuse it for busy, selected, or read-only states.

Ownership and scoring: for a component audit, a component-specific wrong-token choice is D7; a token-layer failure remains known systemic — #4652 and is not scored against the component while that carve-out is active. For a theme-elevation review, the theme is the owning layer: every failing pair blocks elevation until fixed or supported by a recorded WCAG exception. Do not add an axe baseline entry as evidence of acceptance.

What D12 is guarding against. transform and opacity are composited — the browser hands them to the GPU and skips layout and paint entirely. Everything else (width, height, margin, top, grid-template-rows) makes the browser recompute layout on every frame, for the animated element and usually its siblings. The rule's normal case is a free win: someone animates margin-left where transform: translateX() would look identical and cost nothing. The finding is "you paid layout cost for an animation a transform could have done."

The exception: animating open to an unknown height. There is no transform that expresses "grow from nothing to however tall the content happens to be." scaleY distorts the content and leaves siblings unmoved; opacity alone gives no reveal; a JS-measured max-height costs the same layout plus script. This is the one case where obeying the guard means not having the animation at all, rather than implementing it more cheaply.

So animating grid-template-rows between 1fr and 0fr (with overflow: hidden on the inner element) is accepted for a disclosure, provided:

• reduced motion is honoured — the duration collapses to 0s, no exception;
• the animated subtree is small — a nav group or a details panel, not a page region or a virtualised list;
• it is user-initiated and brief — a click or a keypress, in the fast or medium band, never continuous or looping.

Those constraints are what keep the layout cost bounded, since you are paying it deliberately.

The exception is temporary, and the way out is view transitions — not a CSS property. interpolate-size: allow-keywords / calc-size() are not the fix: they let you animate height: auto directly, but height is still a layout property, so it is the same reflow with nicer syntax. Adopt them behind @supports if you want simpler authoring; it does not change this ruling.

The real fix is the View Transitions API, which snapshots the before and after states and animates the snapshots on their own layer — so the reveal is composited and the document does not re-lay-out per frame. That is a different animation model, which is why no CSS property was ever going to solve this.

Blocked on React, and being worked out in #4882. Browser support is no longer the issue — Chrome 111, Safari 18, Firefox 144 — but <ViewTransition> is canary-only and Astryx ships against stable React. Whether to drive document.startViewTransition() directly, when to adopt, and whether a component library should start a document-scoped transition at all are open questions on that issue. When it resolves, this exception closes and view transitions become the expected pattern. One caveat recorded there: view transitions scale the old and new snapshots to fit, which distorts content whose aspect ratio changes — precisely the axis a disclosure changes — so the migration wants a look, not a find-and-replace.

Precedent for the exception today: SideNavItem's collapsible group.

Everything else stays blocking, on any render path. Animating width, height, margin, padding or top where a transform would have done the same job is jank bought for nothing — and jank on a secondary path is still jank. Unlike the DOM-shape rules, this one is about what the browser does per frame, not about which element owns the styling.

§5a 5/5 — every objective row passes from source: on-grid spacing, concentric radius, on-scale heights, role-token typography with real hierarchy, alpha overlays, semantic stacking, cheap and reduced-motion-safe animation. §5a 3/5 — objectively clean apart from one blocking row or a few FIXes (an off-grid value, a non-concentric pair, an unguarded transition). §5a 1/5 — off-grid values, non-concentric nesting, an opaque hover fill, a magic z-index, or layout-property animation.

§5b 5/5 — screenshots attached for every applicable state in light and dark (plus a custom theme for P/O), every state matched to a named approved representation, and they hold up: you can squint at it and the groupings are obvious; every value traces to a token on the grid; nested corners are parallel; heading/body/supporting are unmistakably different; AA passes in both modes; the shadow tier matches the stacking order; motion is quiet, cheap, and reduced-motion-safe; the state representation is the family's, not a new invention. §5b 3/5 — evidence is partial (some states uncaptured) or the judgment layer is soft: monotonous spacing, a slightly cramped density, or a selection treatment that doesn't match its family's style. §5b 1/5 — a state implements an approved representation badly (opaque hover fill where an alpha tint belongs, a raised shadow on a drag ghost, dimensions jumping on load), status by color alone, or a visible AI tell. §5b not measured — no screenshots. Excluded from the total, weight redistributed, named in the headline. Never 0, and never reported as a pass.

Harness ground truth: Vitest 4 + @testing-library/react 16 + user-event. There is no jest-axe/vitest-axe — unit-level a11y is role/name/ARIA assertions; axe runs out-of-process via @axe-core/playwright in the pr-a11y job. There is no visual-regression suite (one snapshot file repo-wide). That is a fact about the harness, not a deduction against a component — a component cannot be marked down for tooling the repo does not have. Visual correctness is checked by capturing screenshots and comparing them against Design Conventions (§5b), which is a stronger check than a pixel diff: it asks whether the state matches its approved representation, not merely whether it changed. Coverage has no thresholds — it is a report, not a gate.

5/5 — tests read as a contract spec: controlled and uncontrolled, every callback's arguments, documented edge cases, full APG keyboard coverage via user-event, focus trap/restore assertions, role/name/ARIA state assertions; pr-a11y green with a shrinking baseline; RTL audit clean; check-use-client clean; SSR-callable utilities actually server-rendered in a test; before/after screenshots on any visual change. A component that does all of this scores 5 — the absence of a visual-regression suite, or of any other tooling the repo has not built, never holds a section off full marks. (Non-normative: Button.test.tsx, 39 cases, was the closest example as of 2026年08月10日.) 3/5 — solid render and prop tests plus a couple of interaction tests; ARIA asserted, keyboard partial, focus behavior untested; axe green partly because the stories are too thin to reach the interesting states. Green CI, real gaps. 1/5 — "renders without crashing" plus a snapshot; assertions pinned to DOM structure or computed styles; zero keyboard or ARIA coverage on an interactive widget; a new baseline entry silencing a fresh violation; a behavior fix with no regression test.

Mined from ~950 PR review comments plus packages.instructions.md. The house position, stated plainly: "All useEffects are smells" (PR #298).

Sanctioned exception: synchronizing a real external system

Added in v1.1, from the Tooltip calibration finding.

An Effect is the right tool for exactly one job: synchronizing with a system React does not own. useLayer.show()/hide() wrap the native Popover API (showPopover()/hidePopover(), with a Safari <17 / Firefox <125 fallback) — browser top-layer state that has no declarative React expression. Pushing a controlled isOpen prop into it must happen in an Effect; there is no handler to put it in, because the change originates from the consumer's render, not from a user gesture.

An Effect is sanctioned when all seven hold:

1. The external system is real — a browser API with state React does not own (top layer / Popover API, dialog.showModal(), observers, media queries, document listeners, a third-party imperative widget). Another React component's state is not an external system.
2. One direction only — props → system. The Effect does not mirror the system back into React state as its purpose.
3. Idempotent and self-guarding — a second call is a no-op, so a re-render or a StrictMode double-invoke is harmless. useLayer.show() guards on isOpenRef.current; hide() likewise.
4. No focus movement from inside the Effect.
5. No announcement and no analytics from inside the Effect (that is A7/C3, and it stays BLOCK).
6. Any consumer-visible callback it triggers provably fires once — the guard in (3) must be what makes that true, not luck.
7. It lives in the primitive that owns the system, not re-implemented in every consumer.

The bright line is focus. The rule C2 comes from (#4769) was a focus-management bug: controlled state plus an Effect dropped focus. A component that moves or traps focus — modal Dialog, focus-trapping Popover, Selector, Menu — gets no exception; the harm the rule prevents is live there. A non-focus-stealing layer (Tooltip, HoverCard — aria-describedby only, useLayer does no focus management at all) cannot reproduce that harm, and the exception applies.

Worked example — Tooltip, from the calibration run. useTooltip.tsx:452-463 (controlled isOpen → layer.show()/hide()) satisfies all seven: real external system, one-way, self-guarding, no focus, no announce. Not a finding. Popover.tsx:499-509 is the better form of the same thing — useIsomorphicLayoutEffect plus an explicit !popover.isOpen guard, so there is no flash. useTooltip.tsx:444-449 (mount-time isDefaultOpen → layer.show()) fails (7) only: useLayer has no isDefaultOpen option, so four consumers each re-implement it. That is a FIX routed to useLayer, not a BLOCK on Tooltip — it fires onOpenChange once because show() self-guards, so the double-fire risk is real in shape but absent in fact.

What stays BLOCK regardless: an Effect that announces (A7), moves or restores focus, fires analytics, syncs one piece of React state to another, or mirrors props into state. And "the external system is real" is judged, not asserted — say which API, and why it has no declarative form.

5/5 — zero Effects, or every Effect synchronizes a genuinely external system and says so; interaction logic lives in handlers and callback refs; complex independently nameable behavior has a focused hook/utility test boundary owned at the correct lifecycle seam; state is only what cannot be derived; sizing uses the shared observer pool with matched unobserve; behavior is composed from existing hooks and data is derived from the existing registry rather than re-typed as a literal map; nothing read from refs in render; react-compiler and purity clean at lint:strict. 3/5 — one or two defensible-but-undocumented Effects, a redundant useState, an own-instance ResizeObserver outside a hot path (correctly cleaned up), one complex behavior buried in a component but still covered through integration tests, or one modest hand-authored map that duplicates data an existing source already holds. No correctness impact. 1/5 — Effect chains syncing props→state; an Effect that announces or focuses; controlled-open props kept in sync by Effects; elements or collections held in state; per-row observers; a hand-rolled a11y primitive; a complex interaction state machine embedded in a replaceable/wrong lifecycle owner and only testable through the full component; a behavior component adding unjustified nesting; a large literal map shadowing the icon registry, a token map, or a themeable variant axis; refs read in render.

Ground truth: stories are not colocated — zero *.stories.tsx files exist under packages/. All 180 live under apps/storybook/stories/: 165 as <Name>.stories.tsx at the top level, the rest in charts/. (CONTRIBUTING §5 and packages.instructions.md still describe a colocated file; that guidance is stale.) Blocks live at packages/cli/assets/templates/blocks/components/<Name>/. Prop→story coverage across main today is 859/1071 = 80%.

5/5 — .doc.mjs with description, ≥2 do's and ≥2 don'ts, and anatomy; 100% prop→doc parity, every prop typed and defaulted; one hero block plus ≥2 examples, all pairing-clean and rendering; a story file touching ≥90% of documented props and showing variants, composition, and every applicable state; clean bare-fence @examples that compile to the shape the components actually ship; theming in sync; a11y guidance in bestPractices with the APG pattern linked. (Non-normative: Button was the closest example as of 2026年08月10日.) 3/5 — docs and a story exist and CI is green, with real holes: prop→story coverage 60–85%, a few props missing defaults, one thin example, stories that enumerate variants without composition or edge cases, no a11y guidance. (Non-normative: components in this band as of 2026年08月10日 included Section, Tooltip and SideNav.) 1/5 — a props-only .doc.mjs with no usage (the docsite Overview renders empty), or no .doc.mjs at all; no block directory, so no hero and no examples; no story, or one default story; @example missing or language-tagged so autodocs shows nothing; a worked example that reproduces a bug the components have already fixed. (CircularProgress in lab; Code, Heading, HStack, VStack ship with no .doc.mjs.)

The lint rule is @astryx/no-hardcoded-i18n-string (sibling: @astryx/i18n-key-format). It catches: text-sink JSX attributes (label/placeholder/title/tooltip/text/summary/message/description/hint and any *Label/*Text/*Placeholder/... suffix), the user-visible aria-* subset, object properties of those names in .tsx, destructure defaults, and hardcoded first arguments to announce(...). It ignores tests, stories, .doc.mjs, and JSDoc examples.

One residual blind spot. Both paths — attribute value and call argument — are walked: a literal nested in a ternary, a ??/|| fallback, or a template's fixed chunks is reported. The walk does not descend into a template's interpolated expressions, so a conditional inside a template (`${n} ${n === 1 ? 'result' : 'results'}`) is still invisible to it. Read announcements and interpolated labels rather than trusting a green lint for I3/I6.

Severity note. §9 carries a lot of blocking weight for its 5 points. Blocking is reserved for defects: an untranslated string, a mis-shaped key, a physical property, a chevron that doesn't mirror, a wrong-side element. Missing evidence — no rtl:audit scorecard pasted (I17), no pseudo-locale check (I18) — is FIX, not BLOCK, outside a promotion.

5/5: every visible and AT-facing string is a @astryx.* key present in en.json with a description; ICU for interpolation; locale-sensitive output follows the provider rather than the host; zero physical properties or values; rtl:audit D1+D5+D6 clean, curated targets cover applicable directional behavior, and every component is measured or verified N-A with no coverage gaps; direction never read during render; arrow-key flipping from the shared hooks. 3/5: all visible text localized and logical CSS throughout, but one AT-facing label or announce() literal remains, or useDirection() is used at render in one low-risk spot, or applicable D2/D3 behavior was verified by hand without adding a reusable target. 1/5: English literals in label/aria-label/announcements or a suppression on the i18n rule; locale-sensitive output that ignores the provider; physical marginLeft/left/textAlign: 'left' in shipped styles; a directional visual that neither mirrors nor swaps (or does both); a logical-anchor + physical-translate element landing on the wrong side; an unexplained all-N-A RTL result presented as clean.

Touch reachability is graded in §1 (A8–A10) because it is an accessibility bright line. This section grades adaptation quality.

5/5 — clean at 320 px with no horizontal scroll; adaptation via @container/Grid minWidth; system breakpoints reused with one source of truth; overlays scroll at mobile sizes; narrow/long-text/empty stories exist; screenshots at 320 px and under coarse-pointer emulation attached. 3/5 — reflows correctly, but uses useMediaQuery where CSS would do, or introduces a one-off breakpoint value; no narrow-viewport screenshot. 1/5 — horizontal scroll or a clipped/unreachable control at 320 px; a ResizeObserver doing a container query's job; hardcoded column counts; an unscrollable fullscreen dialog.

Applicability. This section grades a promotion diff (lab → core, or into a package) and nothing else. For a component that already lives in core, skip it entirely — do not report a missing spec issue, arbitration record, vibe artifact, hardening issue, or self-review as a finding against a shipped component. Those artifacts are promotion-time evidence, and demanding them retroactively grades history rather than the component.

The only items that apply to an ordinary PR are L4 (review gate cleared), L14 (changeset) and L15 (no public-repo leak). In modes N and O on an existing core component, §11 is not run and the scorecard's evidence line reads n/a — existing core component.

Within a promotion PR: highlight when evidence is missing, don't block on it. Reported as evidence: n/m artifacts found, never folded into the letter grade — except the hard items marked BLOCK below.

How to report a missing artifact: ⚠️ no spec issue linked / no arbitration record found / no vibe-test evidence — with the exact command that came up empty. Prominent, never a merge block.

Every graded run emits this. Paste it into the audit issue or the PR comment — and record it in the ledger (component-scores.json in this wiki).

Recording the result is part of the audit

An audit that isn't recorded didn't happen. Every graded run — nightly, promotion, or on-demand — writes its scorecard to the ledger. The ledger is component-scores.json in this wiki, so recording is a wiki push: no repo PR, no review latency. It is the only stored form — there is no generated table to regenerate, and therefore none to go stale.

You record by editing that file: clone the wiki, add or replace the component's entry, pull, commit, push. Full procedure in Recording an audit below.

What to record: the overall score and grade; every section score with its state (scored / limited / not_measured / na); the open BLOCK list as rule id + one line; distinct_defects / fixes / nits; lastAudited; the commit audited; the mode; and the rubricVersion you graded under (see the version block at the top of this page).

Whether a blocking finding gets an issue depends on who is going to fix it.

• The nightly pass files nothing. It fixes what it found and re-audits to prove it, so an issue for work already done is noise. What it could not fix stays in the ledger row against the component, where the next audit and the scores page both find it. A finding does not need a ticket to be tracked.
• A grading or a promotion audit files one issue per open blocking finding — title [audit] <Component>: <one-line finding>, label hardening — because nobody is fixing them in that pass, and unassigned work with no ticket is work nobody picks up. Store the issue number on the entry in the ledger so the scores page links straight to it.
• Should-fix and nit findings never get an issue, in any pass. They live in the ledger row.
• A cross-cutting or system-level finding gets one issue, whoever found it, and every affected row links it rather than duplicating it.

The rule underneath: an issue exists to hand work to someone. If the work is already done, or it is recorded against the component where the next pass will see it, an issue adds a queue entry and nothing else.

Each issue must carry its context, because whoever picks it up will not have the audit in front of them: the component's ledger entry — name, package and recorded score, so the row can be found — a link to this rubric with the rule id and section the finding violates, the rubric version it was graded under, the evidence (file:line, and the screenshot for a visual finding), and the concrete fix. An issue that just says "Button hover is broken" is not actionable.

Closing the loop. A PR resolving an audit issue must: (1) re-run the audit for that component afterwards — a full grading, not just the diff; (2) update the PR description with the visual results — before/after screenshots of the affected states, which is also what §5b needs; (3) update the ledger with the new score, closing out the resolved BLOCK; and (4) close the issue by linking that PR. The score must move — a resolved BLOCK that leaves the recorded score unchanged means either the fix or the audit is wrong. See Recording an audit for the write path.

Only record what you measured. An unverified section is not_measured — never a guess, and never a zero. Night Watch captures the full rendered evidence its mode requires; an unavailable evidence layer remains explicitly not_measured and makes the PR ineligible for auto-merge when that layer is required.

The recorded score is a gate. The ratchet fails any later PR that lowers a component's score or introduces a new BLOCK. Score generously and you build a gate nobody can pass; score harshly and you block the next honest contributor. Record what you found.

Component: <Name> Package: core | lab | <pkg>
Mode: nightly | promotion | grading | review Rubric: v1.9 Date: YYYY-MM-DD
Commit/PR: <sha or #NNNN>
Quick checks (when reviewing a change): Q1 lint:strict [ ] Q2 test [ ] Q3 build [ ] Q4–Q12 [ ]
Visual evidence: <n> screenshots at <path/link> — states: <list> themes: <list>
 (empty ⇒ §5b is `not measured`: excluded, weight redistributed,
 named in the headline — never scored 0)
Section W Score Weighted Notes
§1 Accessibility & operable paths 16 _/5 __.__ 
§2 Theming & token integrity 14 _/5 __.__ 
§3 Public API contract 14 _/5 __.__ 
§4 Behavior correctness & states 12 _/5 __.__ 
§5a Design conventions — objective 6 _/5 __.__ 
§5b Design conventions — rendered 4 _/5 __.__ ← screenshots, or `not measured`
§6 Testing & verification 8 _/5 __.__ 
§7 Code health (React & DOM) 8 _/5 __.__ 
§8 Docs, Storybook & docsite 8 _/5 __.__ 
§9 i18n & RTL 5 _/5 __.__ 
§10 Responsive & touch 5 _/5 __.__ 
 --- ------
TOTAL 100 __.__ → GRADE: _
BLOCKers open: <n> (any BLOCK caps the overall grade at C)
Distinct defects: <n> (raw findings: <n> — the distinct count is the honest one)
FIXes open: <n> NITs open: <n>
SENSITIVITY: fix the <n> open BLOCKs, change nothing else → projected <score> / <grade>
`limited` sections (fewer than 1/3 non-vacuous verdicts): <list> — weight redistributed
Evidence rider (§11): <n>/<m> artifacts found — <list what's missing>
N/A sections: <list with reason>
Unverified: <items no tooling run could confirm, and which way they'd move the grade>
Top 3 things to fix:
1. <BLOCK — rule cited — concrete fix>
2. ...
3. ...

Per-mode run sheet

Commands for a full pass

pnpm lint:strict && pnpm test && pnpm build # Q1–Q3, the entry gate
pnpm check:sync && pnpm check:changesets
node scripts/check-use-client.mjs # not wired into any script — run it
node scripts/sync-exports.js --check && node scripts/verify-exports.mjs
pnpm -F @astryxdesign/core typecheck:docs
pnpm -F @astryxdesign/docsite generate && pnpm -F @astryxdesign/docsite test
pnpm storybook:build && pnpm a11y:audit -- --components <Name>
pnpm rtl:audit -- --filter <Name>
# §5 visual evidence — required, not optional
pnpm -F @astryxdesign/build build && pnpm -F @astryxdesign/core build # Storybook reads dist/
pnpm storybook # :6006
npx playwright install chromium
# then drive real Chromium: for each applicable state (rest, hover, focus-visible,
# active, disabled, loading, each status, selected, empty, overflow) ×ばつ light + dark
# (+ a custom theme for P/O), screenshot to
# <Component>__<variant>__<state>__<theme>.png — and then LOOK at them.
# Use page.hover() / keyboard Tab / page.mouse.down() to drive real states;
# never fake a state by injecting a class.
# then the greps lint doesn't cover: hex/rgb/hsl, boxShadow, <svg,
# textSizeVars, defaultMarker, style={{, ':hover' without a guard,
# and fooStyles[prop] vs the sibling themeProps() call

Where the data lives, and how to write to it.

Storage. component-scores.json in the wiki repo (github.com/facebook/astryx.wiki.git). It holds audited components only — there is no row for an unaudited one, and no placeholder list to maintain.

Viewing. The Component Scores page in the sandbox joins the ledger against the live roster generated from every component-bearing package in scripts/component-packages.cjs, so an unaudited or newly added public component shows as TBD without a hand-maintained list. It fetches the ledger at runtime, so a score recorded minutes ago shows without a rebuild. There is deliberately no generated wiki table: a second stored copy is a second thing to drift.

Who writes. Whoever ran the audit — the nightly auditor, or a human or agent running an on-demand pass. CI never writes it: most of this rubric needs judgment, so a workflow cannot produce a score. Only maintainers can push the wiki, which is the point — the ledger's integrity depends on the audit being honest, not on restricting who may read it.

Use the tool — scripts/score-ledger.mjs, on main since #4875. It applies the rules below rather than trusting you to remember them.

# Get the ledger once; reuse the clone afterwards
git clone https://github.com/facebook/astryx.wiki.git /tmp/astryx-wiki
# Record a scorecard and push it, in one command
<your scorecard JSON> | node scripts/score-ledger.mjs --record <Component> \
 --from - --ledger /tmp/astryx-wiki/component-scores.json --push

--push commits and pushes the wiki for you, rebasing first so concurrent auditors do not collide, and prints the commit URL. --from - reads the scorecard from stdin — pipe it rather than writing a file: the ledger is the only stored form, and a scorecard on disk goes stale within the hour. --dry-run prints the exact diff and commit message without writing anything; use it the first few times.

Other subcommands: --stats (coverage, grade distribution, open BLOCKs), --queue --limit N (the work order — unaudited first, then oldest-audited, then lowest-scoring), --check (where a PR's touched components stand), and --file-issues (create the BLOCK issues from a scorecard, idempotently, and write their numbers back).

Editing the JSON by hand still works and is not wrong — but the tool refuses the mistakes that matter, so prefer it.

The scorecard format, as JSON: the overall score and grade; every section with its score and state (scored / limited / not_measured / na); the open BLOCK list as {id, summary, issue}; distinct_defects, fixes, nits; lastAudited; the commit audited; the mode; and the rubricVersion you graded under (from the version block at the top of this page).

The tool enforces these; they bind just the same if you edit by hand.

• A decrease or a new BLOCK must be deliberate and explained. --record refuses it without --allow-regression "<why>", and the reason lands in the commit message. The ledger is a ratchet; lowering a score is never a silent edit.
• Only record what you measured. An unverified section is not_measured — never a guess, never a zero. Night Watch captures the full screenshot set required by §5b; if any required rendered layer is unavailable, design_rendered is not_measured and the PR remains manual-review-only.
• BLOCK issue handling follows the audit mode. Night Watch files no ordinary per-finding issues; grading and promotion use --file-issues for each open BLOCK; every mode uses one shared issue for a cross-cutting/system-level gap.
• Entries are keyed package/Component — Chat exists in both core and lab, and they are different components.

node scripts/score-ledger.mjs --stats # coverage, grades, open BLOCKs
node scripts/score-ledger.mjs --queue --limit 1 # what to audit tonight
node scripts/score-ledger.mjs --check --analysis a.json # where a PR's components stand

Nothing in CI reads the ledger, and no PR is gated on a score. If a checker is ever wired up it will be a standing report, not a gate: a wiki-hosted ledger has no head-versus-base delta to ratchet, a component with no audit is judged on its merits, and an unreachable ledger would never block.

Current: 1.15.3, last changed 2026年09月06日.

Cite this version in every audit. The scorecard's Rubric: line and the ledger's rubricVersion field must both carry it. Scores taken under different minor versions are not comparable. Patch versions remain comparable when their history entry explicitly says so; otherwise the ratchet must fail closed and request a re-audit.

Versioning rule. Bump the minor when scoring changes (weights, floors, severities, what counts as evidence) — that invalidates comparison with earlier scores. Bump the patch when only wording, citations, or a check's detection recipe change — comparison still holds. Record the change in the history below, and date it.

Checks that are written but not yet live. Flip them when the trigger lands; until then they are inactive and must not be cited.