Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

docs: consolidate the review and contribution guidance into one source of truth (#4877)

Cindy Zhang33411eb08a75
diff --git a/.github/REVIEW_GATE.md b/.github/REVIEW_GATE.md
index 2bbd49f03a..60af380801 100644
--- a/.github/REVIEW_GATE.md
+++ b/.github/REVIEW_GATE.md
@@ -7,12 +7,12 @@ neutral yellow "waiting" signal, not a red failure).
## TL;DR
-| Author | High-risk code | Design-affecting change | Everything else |
-| --- | --- | --- | --- |
-| **Eng owner** (`ENGOWNERS`) | self-serve | advisory label only | self-serve |
-| **Design owner** (`DESIGNOWNERS`) | needs code review | self-serve | self-serve |
-| **Contributor** (anyone else) | needs code review | needs code review + design label | needs code review |
-| **Bot** (Dependabot, etc.) | exempt | exempt | exempt |
+| Author | High-risk code | Design-affecting change | Everything else |
+| --------------------------------- | ----------------- | -------------------------------- | ----------------- |
+| **Eng owner** (`ENGOWNERS`) | self-serve | advisory label only | self-serve |
+| **Design owner** (`DESIGNOWNERS`) | needs code review | self-serve | self-serve |
+| **Contributor** (anyone else) | needs code review | needs code review + design label | needs code review |
+| **Bot** (Dependabot, etc.) | exempt | exempt | exempt |
- **Code review is the only hard gate.** It shows up as the `review-required`
status: `pending` (🟑, blocks the merge) or `success` (🟒).
@@ -22,12 +22,12 @@ neutral yellow "waiting" signal, not a red failure).
## Sources of truth
-| File | Meaning |
-| --- | --- |
-| `.github/ENGOWNERS` | Engineering team. Self-serve **code**. |
-| `.github/DESIGNOWNERS` | Design team. Self-serve **design**. Checked first. |
-| `.github/CODEOWNERS` (`*` line) | Who can **clear** the code gate (and native review requirement). |
-| `.github/copilot-instructions.md` + `instructions/*` | Copilot reviewer guidance (advisory). |
+| File | Meaning |
+| ---------------------------------------------------- | ---------------------------------------------------------------- |
+| `.github/ENGOWNERS` | Engineering team. Self-serve **code**. |
+| `.github/DESIGNOWNERS` | Design team. Self-serve **design**. Checked first. |
+| `.github/CODEOWNERS` (`*` line) | Who can **clear** the code gate (and native review requirement). |
+| `.github/copilot-instructions.md` + `instructions/*` | Copilot reviewer guidance (advisory). |
Author bucket is resolved in order: **design owner β†’ eng owner β†’ contributor.**
A handle in `DESIGNOWNERS` is treated as a design owner even if also an eng
@@ -36,20 +36,25 @@ label so the contribution queue is filterable).
## What counts as high-risk / design-affecting
-Detection is **path-based and deterministic** (no LLM in the enforcement path).
-`packages/lab/**` is filtered out entirely first β€” lab is canary staging, so
-new components there are expected and never gate.
+Detection is **deterministic** (no LLM in the enforcement path): code detection
+is path-based; design detection combines paths with a deterministic score over
+the diff content (`.github/scripts/lib/classify-visual.js`), because most
+component styling is an inline `stylex.create` edit in a `.tsx` that no path
+pattern can see. `packages/lab/**` is filtered out entirely first β€” lab is
+canary staging, so new components there are expected and never gate.
**High-risk code** (drives the code gate):
+
- a new package (`packages/<name>/package.json` added)
- a new component/module in a published `src/` (not lab)
- a runtime change under `packages/core/src/**` (incl. styling `.tsx`; excludes
tests/docs/stories) β€” core has high blast radius
- a public API surface change (a `src/**/index.ts(x)` barrel or a
`package.json`)
-- **plus:** *any* PR from a contributor (see policy note below)
+- **plus:** _any_ PR from a contributor (see policy note below)
**Design-affecting** (drives the advisory design label):
+
- StyleX styling, theme/token files, template `.tsx`, docsite visual dirs
(`app`/`components`/`themes`)
@@ -102,6 +107,7 @@ write but are not owners. (Repo admins can still bypass.)
## Why a commit status (not a check run)
The gate is a **commit status**, not a check run, for two reasons:
+
1. Branch protection requires `review-required` as a **status context**
("Expected β€” waiting for status to be reported"); a check run of the same
name does not satisfy it.
@@ -115,6 +121,7 @@ to failure).
## Recovery / manual re-flag
`review-signal.yml` has a `workflow_dispatch`:
+
- blank `pr` input β†’ re-flag **all** open PRs (backfill / mass recovery)
- a PR number β†’ re-flag just that one
diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md
index 748baf7e90..66f7b6949b 100644
--- a/.github/copilot-instructions.md
+++ b/.github/copilot-instructions.md
@@ -1,63 +1,30 @@
# Copilot instructions for Astryx
Astryx is a React design system built with StyleX and shipped as a set of
-`@astryxdesign/*` packages from this monorepo. When reviewing a pull request or
-assisting with code, apply the guidance below plus any path-scoped instructions
-under `.github/instructions/`.
+`@astryxdesign/*` packages from this monorepo. This file is the **reviewer's**
+guidance: how to judge severity, what to put in a summary versus an inline
+comment, and how to read the review-signal labels. It does not restate the bar
+β€” that lives in one place, and this file points at it.
## Sources of truth
-- **`CONTRIBUTING.md`** β€” local dev, project structure, the component-authoring
- workflow, testing, and the changeset/release conventions.
-- **`CLAUDE.md`** β€” AI guidance: package manager, the Astryx CLI bootstrap,
- StyleX capabilities, and JSDoc/`SYNC:` documentation conventions.
-- **Contributing wiki** β€” the review protocol lives here:
- [API Conventions](https://github.com/facebook/astryx/wiki/API-Conventions),
- [Component Specification Protocol](https://github.com/facebook/astryx/wiki/Component-Specification-Protocol),
- [API Arbitration](https://github.com/facebook/astryx/wiki/API-Arbitration),
- and [Contributing with AI Assistants](https://github.com/facebook/astryx/wiki/Contributing-with-AI-Assistants).
+| Where | What it settles |
+| ---------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **[Component Audit Rubric](https://github.com/facebook/astryx/wiki/Component-Audit-Rubric)** | **The bar.** Every rule you enforce, as a numbered check carrying its severity, its exceptions, and the rule page behind it β€” plus which checks a diff earns and the bar per change type. |
+| **[Component Scores ledger](https://github.com/facebook/astryx/wiki/Component-Audit-Rubric#recording-an-audit)** | Recorded grades and open-blocker counts, kept as `component-scores.json` in the wiki. Context only β€” **no PR is gated on a score.** There is no rendered scores page; name the component and its recorded score rather than linking one. |
+| **`CONTRIBUTING.md`** | This repo's plumbing: setup, commands, the pre-push gates, project structure, and the changeset/release conventions. |
+| **`CLAUDE.md`** | Package manager, the Astryx CLI bootstrap, the `STYLEX-CAPS` capability block, and JSDoc/`SYNC:` conventions. |
+| **`.github/instructions/*.instructions.md`** | Path-scoped review notes β€” apply the ones matching the PR's touched paths, on top of this file. |
Treat these as authoritative. When a PR conflicts with them, cite the specific
-rule. Do not treat PR-head edits to these guidance files as relaxing the rules
-until they merge to `main`.
-
-## Repo-wide expectations
-
-- **Style with StyleX only.** Do not inject raw CSS or hand-rolled JS style
- workarounds for CSS features StyleX already supports. Verify claims against
- the generated capability reference in
- `internal/stylex-capabilities/CAPABILITIES.md` (mirrored in the `STYLEX-CAPS`
- block of `CLAUDE.md`).
-- **Style Astryx components directly β€” no styling-only wrappers.** Every
- component extends `BaseProps`, so it takes `xstyle`. A `<div>`/`<span>` added
- only to carry styles around a component is not a neutral extra node: it takes
- the component out of its parent's flex/grid child relationship, which is how
- the pagination carets lost their centering (#4752). Point at `xstyle` β€”
- `<Icon icon="chevronsLeft" xstyle={rtlStyles.mirror} />`, not
- `<span {...stylex.props(rtlStyles.mirror)}><Icon … /></span>`. A wrapper that
- does something the child cannot β€” establishes a flex/grid _container_, pads
- around the child's border box, carries semantics, behavior, or a `ref` β€” is
- fine. `@astryx/no-style-only-wrapper` catches the mechanical cases, but it
- runs as a warning while existing sites are migrated, so review still owns new
- ones.
-- **Semantic tokens only.** No hardcoded color, spacing, radius, or shadow
- values; components stay theme-agnostic.
-- **TypeScript strict**, functional components that declare `ref` as a prop
- (React 19 β€” `forwardRef` is rejected by `@eslint-react/no-forward-ref`, and
- `@astryx/require-ref-prop` requires `ref?: React.Ref<T>` on a publicly
- exported props interface), exported prop types alongside the component, and a
- set `displayName`.
-- **Changesets.** Consumer-visible changes need a changeset (`pnpm
-changeset:new`) with a `[category]` first line and a `@handle` contributor
- line. Pre-1.0 bumps are `patch`, except `[breaking]`, which is `minor`.
- `major` is never used pre-1.0.
-- **Keep code comments minimal.** Comment _why_, not _what_. Flag narration
- comments, commented-out code, and changelog-in-code.
+rule **by its check id** (`T1`, `A8`, `P2`…) so the author can look up exactly
+what you applied. Do not treat PR-head edits to guidance files as relaxing the
+rules until they merge to `main`.
Focus review on production and consumer-facing changes. Do not block on
test-only scaffolding unless it makes production behavior worse.
-## Blocking criteria β€” score the failure, not its likelihood
+## Severity β€” score the failure, not its likelihood
A finding's severity is set by **what breaks if it ships**, not by how likely
the trigger is, who wrote it, or whether a linter already flagged it. A rare
@@ -67,80 +34,30 @@ path works," or the author's seniority soften a bright-line violation into
advisory. Score the failure first; use likelihood only to prioritize the fix,
never to decide whether it blocks.
-When a finding is blocking, **lead with πŸ”΄, recommend request-changes, cite the
-specific rule, and point at the concrete fix** (the token to use, the API a
-sibling already establishes, the accessible path that must work). Separate the
-_finding_ from the _remedy_: a blocking bug stays blocking even when the exact
-fix is an open question β€” state the block, then ask about the approach.
-
-**πŸ”΄ Always blocking:**
-
-- **Hardcoded colors.** Every color is either a token β€” `var(--color-*)` β€” or
- **derived from tokens** via `color-mix()` / `light-dark()` / `calc()` whose
- inputs are vars. **No raw hex/rgb/hsl anywhere**, including as an argument to
- `light-dark()` or `color-mix()`, behind a `const`, or under an
- `eslint-disable`. "No suitable token exists" is **not** an exception: prefer an
- existing semantic token (e.g. `--color-overlay` for a scrim), derive from one
- (the on-media absolutes `--color-on-dark` / `--color-on-light` for fixed
- values over images), or add a token. Same rule for spacing, radius, and
- shadow β€” token or derived-from-token, never a raw value.
-- **Removing a themeable surface.** Replacing a token, a `themeProps` target, or
- a `MediaTheme`-flowed override with a fixed value so a theme can no longer
- influence it. Ask _"is this still themeable?"_ before _"is this lint-clean?"_.
- A value pinned on `xstyle` / `style` sits at the top of the cascade (see the
- Cascade Model in [Theming Infrastructure](https://github.com/facebook/astryx/wiki/Theming-Infrastructure))
- and takes that surface out of the theme system β€” blocking even when it renders
- correctly.
-- **Raw CSS or hand-rolled JS style workarounds** for anything StyleX supports
- (verify against `internal/stylex-capabilities/CAPABILITIES.md`), or raw HTML
- where an Astryx primitive exists.
-- **A broken accessible path β€” any modality.** Mouse, keyboard, screen reader,
- and touch must all keep the control operable. Touch is an operable modality:
- hover-gated reveals break **hybrid devices** (touchscreen laptops report
- `hover: hover` + `pointer: fine`), so a control that only appears on `:hover`
- can leave an invisible-but-clickable element β€” especially destructive ones.
- Prefer `@media (any-pointer: coarse)` ("the device _has_ touch", incl.
- hybrids) over `hover: none` for "always show". Also blocking: focus lost on
- state change, a focusable element removed from the DOM, or an interactive
- target below the minimum size.
-- **Accessibility.** Beyond the broken-path rule above, each of these is a
- bright line on its own:
- - an interactive element without an accessible name;
- - a state change not exposed to assistive tech (visual-only state);
- - a keyboard trap, or an interaction that only works with a pointer;
- - state signaled by color alone;
- - focus not managed on open/close of an overlay (trap while open via
- `useFocusTrap`, restore on close);
- - a live announcement that bypasses `useAnnounce` (a hand-wired `aria-live`
- node);
- - hardcoded English in an AT-facing string (labels, announcements, hints β€”
- same i18n rule as visible text);
- - a new component that hasn't run the
- [Accessibility Checklist](https://github.com/facebook/astryx/wiki/Accessibility-Checklist).
-
- The `pr-a11y` axe audit catches the static/DOM-level subset of these
- automatically; axe cannot see keyboard, focus, or announcement _behavior_ β€”
- those are on the reviewer.
-
-- **Hardcoded user-facing strings.** All UI text goes through `useTranslator()`
- / the i18n key system (`@astryx/no-hardcoded-i18n-string`), and new keys must
- match the required format (`@astryx/i18n-key-format`).
-- **Public API-convention violations** (see [API Conventions](https://github.com/facebook/astryx/wiki/API-Conventions)) β€”
- booleans not `is`/`has`-prefixed, wrong callback shape (`onValueChange` for the
- primary change instead of `onChange`; missing the `changeAction` async twin β€”
- the shipped convention is `<verb>Action` (`changeAction`, `clickAction`),
- not `on<Verb>Action`),
- inventing a name when a sibling convention exists (match `showOn`, `endContent`,
- etc.), dropping `...rest` / passthrough, or `xstyle`/`className`/`style`
- overwritten instead of merged via `mergeProps`. Public API shape is hard to
- walk back β€” treat it as blocking, not a nit.
-- **A real bug or breaking change**, including _latent_ ones: a passthrough
- silently dropped, a feature that breaks when composed with another, a
- regression in an existing behavior.
-- **Public-repo leak** β€” internal identifiers (T/D/S/P-numbers), infra names,
- unixnames or `@meta.com` emails, or tool/assistant fingerprints in any
- committed text (code, comments, PR title/body, changeset).
-- **Missing changeset** for a consumer-visible change.
+**πŸ”΄ Blocking.** The rubric marks these `BLOCK` and is the single statement of
+what each one means and when it applies β€” read the check before you cite it,
+because several carry exceptions the one-line name does not:
+
+- [Hardcoded colors, spacing, radius, or shadow](https://github.com/facebook/astryx/wiki/Component-Audit-Rubric#2--theming--token-integrity--weight-14) (`T1`, `T3`)
+- [Removing a themeable surface](https://github.com/facebook/astryx/wiki/Component-Audit-Rubric#2--theming--token-integrity--weight-14) (`T2`)
+- [Raw CSS where StyleX suffices, or raw HTML where a primitive exists](https://github.com/facebook/astryx/wiki/Component-Audit-Rubric#2--theming--token-integrity--weight-14) (`T8`, `T29`)
+- [A broken accessible path, in any modality](https://github.com/facebook/astryx/wiki/Component-Audit-Rubric#1--accessibility--operable-paths--weight-16) (`A8`)
+- [The accessibility bright lines](https://github.com/facebook/astryx/wiki/Component-Audit-Rubric#1--accessibility--operable-paths--weight-16) β€” accessible name, exposed state, focus management, forced colors (`A1`, `A3`, `A11`–`A14`)
+- [Hardcoded user-facing and AT-facing strings](https://github.com/facebook/astryx/wiki/Component-Audit-Rubric#9--i18n--rtl--weight-5) (`I1`–`I4`, `A16`)
+- [Public API-convention violations](https://github.com/facebook/astryx/wiki/Component-Audit-Rubric#3--public-api-contract--weight-14) (`P1`–`P10`)
+- [Dropped passthroughs, latent bugs, and breaking changes](https://github.com/facebook/astryx/wiki/Component-Audit-Rubric#3--public-api-contract--weight-14) (`P2`, `P11`, `P12`)
+- [A public-repo leak](https://github.com/facebook/astryx/wiki/Component-Audit-Rubric#11--lifecycle--process-evidence--promotion-prs-only-ungraded-rider) (`L15`)
+- [A missing changeset](https://github.com/facebook/astryx/wiki/Component-Audit-Rubric#8--docs-storybook--docsite--weight-8) (`X20`)
+
+**A bright-line failure blocks on any path.** The triage sets _how much you
+look_, never _what counts once you see it_ β€” a fast-path PR with a hardcoded
+color is still blocking.
+
+**How to report a blocker.** Lead with πŸ”΄, recommend request-changes, cite the
+check id, and point at the concrete fix β€” the token to use, the API a sibling
+already establishes, the accessible path that must work. Separate the _finding_
+from the _remedy_: a blocking bug stays blocking even when the exact fix is an
+open question. State the block, then ask about the approach.
**🟑 Advisory (maintainer judgment):** design-taste calls, optional refactors,
and questions where the _fix_ is genuinely open. The underlying _finding_ may
@@ -152,6 +69,14 @@ guarantee.
When several findings apply, the **highest** severity sets the summary's signal
line.
+**Never charge a contributor for inherited debt.** Judge the diff, not the
+component. A pre-existing problem you notice while reviewing is real and worth
+filing, but say plainly that it is pre-existing and not theirs to fix β€” do not
+attach it to their PR or make their change wait on it. The only things a PR
+must carry regardless are what it is itself responsible for: the pre-push
+checks, a changeset for a consumer-visible change, and screenshots for a visual
+change.
+
## Same bar for every author
**Who opened the PR does not change the review.** Apply the same checks, the
@@ -161,18 +86,29 @@ whether it comes from a maintainer or a first-time contributor; a broken
accessible path is a blocker either way. Do not soften a finding because of who
wrote it, and do not treat an owner's PR as pre-vetted.
+What the bucket _does_ change is framing, not severity:
+
+- **Contributor** β†’ your review is the _initial pass_ that tells a code owner
+ where to focus.
+- **Design owner** β†’ same checks, framed for a designer: name what crosses into
+ engineering territory and needs an engineer's eye.
+- **Eng owner** β†’ assistant framing: the same findings, as input to the author's
+ own judgment.
+
> **The merge gate is a separate, workflow-driven mechanism.** The
-> `review-signal` workflow applies two labels from the changed paths and
-> disables auto-merge when either fires β€” `needs:code-review` (high-risk code
-> area) and `needs:design-review` (design-affecting change). Copilot **reads**
-> these labels to focus its review but never sets, clears, or gates on them; an
-> entitled owner's approval clears them. Which team self-serves which domain is
-> the workflow's concern, not the reviewer's β€” your job is to surface every
-> finding at its true severity for every PR. See
+> `review-signal` workflow applies two labels from the changed paths and the
+> diff content β€” `needs:code-review` (high-risk code area) and
+> `needs:design-review` (design-affecting change) β€” and disables auto-merge when
+> the **code** gate fires. The design label is advisory and does not block the
+> merge. Copilot **reads** these labels to focus its review but never sets,
+> clears, or gates on them; an entitled owner's approval clears them. Which team
+> self-serves which domain is the workflow's concern, not the reviewer's β€” your
+> job is to surface every finding at its true severity for every PR. See
> [Review gate](./REVIEW_GATE.md) for the gating policy.
**High-risk vs. low-risk areas.** _High-risk_ = public API changes, new
-components/modules, new packages, or a suspected regression. _Low-risk_ = themes
+components/modules, new packages, or a suspected regression. _Low-risk_ = lab
+(`packages/lab/**`, filtered out of signal detection entirely), themes
(`packages/themes/**`), templates (`packages/cli/assets/templates/**`), sandbox
(`apps/sandbox/**`), storybook (`apps/storybook/**`), and docsite
(`apps/docsite/**`). The low-risk carve-out applies to the **code** gate; the
@@ -185,7 +121,7 @@ Open the summary comment with one signal line so posture is scannable at a
glance:
- πŸ”΄ **Blocking** β€” either a blocking finding from
- [Blocking criteria](#blocking-criteria--score-the-failure-not-its-likelihood)
+ [Blocking criteria](#severity--score-the-failure-not-its-likelihood)
is present, or a review-signal label is (`needs:code-review` and/or
`needs:design-review`). Name the specific trigger(s) β€” the rule violated and
the file, or the label. A content blocker counts even on a PR the workflow
@@ -200,6 +136,17 @@ State the reason on the same line, e.g. `πŸ”΄ Blocking β€” hardcoded color in
Thumbnail.tsx (colors must be a token or derived from one)` or `πŸ”΄ Blocking β€”
new component in packages/core (needs:code-review)`.
+Also state the **triage line** at the top of the review, so the depth you chose
+is legible and the breaking-change question is answered on every PR:
+
+`Triage: bug fix Β· non-breaking Β· low blast radius β†’ fast path Β· checks: Β§1 A4/A5, Β§7 C1`
+
+The category Γ— risk β†’ path mechanic is in
+[`instructions/packages.instructions.md`](./instructions/packages.instructions.md);
+what each kind of change has to carry is in
+[the rubric's bar per change type](https://github.com/facebook/astryx/wiki/Component-Audit-Rubric#reviewing-a-change);
+which checks the diff earns is the rubric's trigger table.
+
## Summary comment vs. inline comments
- **Summary comment** carries the Review Signal, the triage line, the
@@ -215,33 +162,37 @@ new component in packages/core (needs:code-review)`.
## The review-signal labels are signals to you
A deterministic workflow (`.github/workflows/review-signal.yml`) applies two
-labels from the changed paths + author, and disables auto-merge when either
-fires. **It posts no explanation of its own β€” that's your job.** When a PR
-carries one of these labels, explain _why_ review is needed with real judgment
-(the workflow only knows the area; you assess the actual change):
+labels and disables auto-merge when the code gate fires. **It posts no
+explanation of its own β€” that's your job.** When a PR carries one of these
+labels, explain _why_ review is needed with real judgment (the workflow only
+knows the area and a diff score; you assess the actual change):
- **`needs:code-review`** β€” a high-risk **code** area (new package, new
- component/module, public API surface). **Lead with πŸ”΄ Code review required**
- and focus on _what_ a human should scrutinize β€” API shape,
- regression/blast-radius, spec/lab coverage β€” rather than re-deciding whether
- it's risky.
-- **`needs:design-review`** β€” a **design-affecting** change (StyleX,
- theme/token files, templates, a new component). Lead with πŸ”΄ and evaluate the
- change against **Design Conventions** β€” the checkable smells especially:
- tokens-not-raw-values, 4px-grid spacing, concentric radius
- (`r_inner β‰ˆ r_outer βˆ’ gap`), WCAG AA contrast in light _and_ dark, alpha (not
- opaque) interaction overlays, status paired with an icon (never color alone),
- elevation↔z-index order, `transform`/`opacity`-only motion with reduced-motion
- honored, and type hierarchy β‰₯1.25 / leading β‰₯1.3 / body β‰₯12px. The
- path-detection only knows a design _area_ was touched β€” you supply the design
- critique.
-
-Both labels are path-based determinations of _area_, so treat them as
-authoritative for whether review is needed:
+ component/module, public API surface), or any PR from a contributor. **Lead
+ with πŸ”΄ Code review required** and focus on _what_ a human should scrutinize β€”
+ API shape, regression/blast-radius, spec/lab coverage β€” rather than
+ re-deciding whether it's risky.
+- **`needs:design-review`** β€” a **design-affecting** change (StyleX, theme/token
+ files, templates, a new component). Lead with πŸ”΄ and evaluate the change
+ against **[Design Conventions](https://github.com/facebook/astryx/wiki/Design-Conventions)**
+ β€” the objectively checkable smells especially: tokens-not-raw-values, 4px-grid
+ spacing, concentric radius (`r_inner β‰ˆ r_outer βˆ’ gap`), WCAG AA contrast in
+ light _and_ dark, alpha (not opaque) interaction overlays, status paired with
+ an icon (never color alone), elevation↔z-index order, `transform`/`opacity`-only
+ motion with reduced-motion honored, and type hierarchy β‰₯1.25 / leading β‰₯1.3 /
+ body β‰₯12px. Detection only knows a design _area_ was touched β€” you supply the
+ design critique.
+
+Code detection is path-based; design detection combines paths with a
+deterministic score over the diff content
+(`.github/scripts/lib/classify-visual.js`), because most component styling is an
+inline `stylex.create` edit in a `.tsx` that no path pattern can see. Both are
+determinations of _area_, so treat them as authoritative for whether review is
+needed:
- **The labels sharpen your review; they never replace your judgment.** Still
- raise 🟑 for regression or judgment concerns the path detection can't see
- (e.g. an unintended behavior change) even on an _unlabeled_ PR.
+ raise 🟑 for regression or judgment concerns the detection can't see (e.g. an
+ unintended behavior change) even on an _unlabeled_ PR.
- **You do not set or remove these labels.** The workflow applies them and an
entitled owner's approval clears them. One-way: the workflow informs you; you
never gate the merge.
diff --git a/.github/instructions/blog.instructions.md b/.github/instructions/blog.instructions.md
index 95c99166ea..c68a7654a4 100644
--- a/.github/instructions/blog.instructions.md
+++ b/.github/instructions/blog.instructions.md
@@ -1,5 +1,5 @@
---
-applyTo: "apps/docsite/src/content/blog/posts/**"
+applyTo: 'apps/docsite/src/content/blog/posts/**'
---
# Blog post review instructions
@@ -9,102 +9,48 @@ README). Review them for substance, accuracy, efficiency, craft, and voice.
Advisory: post a scorecard and specific, quotable findings with concrete fixes;
never rewrite the author's voice.
-> **Canonical rubric.** This file is the operational copy; the full rubric,
-> rationale, and sources live in the
+> **The rubric is the wiki page.** Read
> [Blog Review Rubric](https://github.com/facebook/astryx/wiki/Blog-Review-Rubric)
-> wiki page. If the two ever diverge, the wiki wins β€” update it there.
+> and apply it: the per-`type` profiles (`update`, `engineering`, `design`,
+> `guide`, `perspective`/`story`), the per-type category weights, the five
+> scoring categories, the grade scale, the unscored reader reflection, and the
+> report format all live there. This file carries only what the reviewer needs
+> from the checkout.
> **Scope note.** These files also match `docsite.instructions.md` (the
-> data-from-pipeline rule). That rule is about docsite *code*, not blog prose β€”
-> apply the rubric below to the post content.
+> data-from-pipeline rule). That rule is about docsite _code_, not blog prose β€”
+> apply the rubric to the post content.
> **Do not detect "AI vs human."** LLMs are unreliable at authorship detection,
-> and "feels AI-written" is neither verifiable nor actionable. Judge *observable
-> writing quality* and give a concrete fix. Never output a human-vs-AI verdict.
+> and "feels AI-written" is neither verifiable nor actionable. Judge _observable
+> writing quality_ and give a concrete fix. Never output a human-vs-AI verdict.
-## 1. Read the post, then read its `type` β€” the type sets the bar
+## The accuracy gate β€” this is the part that needs the checkout
-A changelog digest and a philosophy essay are good in different ways; don't judge
-one by the other's standard. Match `type` to a profile and use its weights:
+The gate applies first, to every type, and it is where a reviewer with the repo
+is strongest: **verify every checkable claim against the current branch.** A
+blog post ships to the world, so a wrong command or an invented API misleads
+real readers.
-| `type` | Profile | Good looks like | Don't penalize for |
-|---|---|---|---|
-| `update` | Changelog digest | Scannable; accurate commands/versions; each change stated once with its user-facing effect | Lacking narrative/journey |
-| `engineering` | Technical deep-dive | Specifics: real numbers, named systems, code, the journey (what was tried, what broke, trade-offs) | Length that carries detail |
-| `design` | Design rationale | The *why*, trade-offs, principle→application | Fewer hard numbers than engineering |
-| `guide` | How-to | Correct, complete, followable steps | Being dry/instructional |
-| `perspective`/`story` | Opinion/narrative | A real point of view, authentic specifics, community warmth | Lacking benchmarks/code |
-
-**Per-type weights (each column sums to 100):**
-
-| Category | `update` | `engineering` | `design` | `guide` | `perspective`/`story` |
-|---|---|---|---|---|---|
-| Substance & purpose | 20 | 30 | 30 | 25 | 30 |
-| Accuracy | 30 | 25 | 20 | 30 | 10 |
-| Information efficiency | 25 | 15 | 15 | 20 | 15 |
-| Craft | 15 | 20 | 20 | 15 | 20 |
-| Voice & fit | 10 | 10 | 15 | 10 | 25 |
-
-## 2. Accuracy gate (applies first, all types)
-
-A blog post ships to the world; a wrong command or invented API misleads real
-readers. **Verify checkable claims against the current branch** (grep the CLI/
-source) β€” this is where the reviewer is strongest.
-
-- Documented commands, component names, props, CLI flags β€” do they exist on this
- branch? (Real catch: a post cited `astryx gap-report` after it was removed.)
+- Documented commands, component names, props, CLI flags β€” do they exist **on
+ this branch**? Grep the CLI and the source rather than trusting the prose.
+ (Real catch: a post cited `astryx gap-report` after it was removed.)
- Numbers stated as fact β€” check against an in-repo source; flag figures that
need a citation and have none.
- Links resolve; code samples are correct.
-**One confirmed verifiable error caps the grade at C** and is marked
-**β›” blocking: do not publish until corrected**. Multiple/misleading errors cap
-at D. A claim that simply can't be verified from the repo does **not** gate β€”
-mark it "needs author/maintainer confirmation."
-
-## 3. Score the five categories (out of each type's weight)
-
-- **Substance & purpose** β€” does the post have a clear reason to exist and deliver
- on it (a gratitude/PR post with no point beyond "thanks" is thin)? Are
- takeaways *earned* to the profile's standard, not just asserted? Does
- title/description match the payload?
-- **Accuracy** β€” how much verifiable surface it got right (the gate above is the
- teeth).
-- **Information efficiency** β€” flag repetition (the same fact in intro + middle +
- conclusion is a *structural* problem, name where it belongs), padding (the
- "sounds nice, deletes clean" sentence), and dead clichΓ©s (Orwell: cut every
- word you can). Judge information *per word*.
-- **Craft** β€” observable quality, **signal not ban**, never dock for one token.
- Tells: editorial labels as praise ("robust," "seamless," "powerful"); hollow
- hedging ("can help," "plays a key role"); over-signposting ("It's worth noting
- that"); defensive framing ("it's not X, it's Y"); self-labeled significance
- ("Key insight:"); puffery/peacock ("stands as a testament," "rich tapestry");
- false range ("from X to Y" bounding nothing); vague authority ("studies show").
- **Structure (Gopen & Swan):** old-before-new (open with context, land the new
- point in the sentence's stress position); topic position (a sentence should
- name what it's about up front). Antidotes that raise the score: concrete
- numbers, named people/tools, real anecdotes, admitted trade-offs, a specific
- opinion, dry humor.
-- **Voice & fit** β€” **do not homogenize.** Aim community-forward (warm, direct,
- credits people, invites participation) while preserving the author's register.
- **Read-it-aloud test:** sounds like a marketing page or school essay β†’ flag;
- sounds like explaining it to a coworker β†’ right. **Relax on clearly human,
- distinctive posts** β€” a strong idiosyncratic voice outranks the rubric.
-
-Grade: A 90+, B 75+, C 60+, D 40+, F <40 (after the gate).
-
-## 4. Reader reflection (unscored β€” a mirror for the author)
+Consequences are the wiki's: **one confirmed verifiable error caps the grade at
+C** and is marked **β›” blocking: do not publish until corrected**. A claim that
+simply cannot be verified from the repo does **not** gate β€” mark it "needs
+author/maintainer confirmation."
-Never changes the score. Two candid, descriptive lines:
-- **How a reader might feel** after one pass (energized, informed, included,
- impressed, confused, sold-to, bored).
-- **What actually sticks** β€” the one thing they take away. If it *differs* from
- what the post intended to land, name the gap β€” that's the most useful signal an
- author can get.
+## Frontmatter and authors
-## Reporting
+Posts are Markdown under `src/content/blog/posts/` with validated YAML
+frontmatter (`title`, `description`, `date`, `type`, `authors`, `tags`). New
+authors register in `src/content/blog/authors.ts`; drafts (`draft: true`) are
+excluded from production output. See
+[`src/content/blog/README.md`](../../apps/docsite/src/content/blog/README.md).
-Post: type + profile, letter grade (+ β›” if gated), the reader-reflection mirror,
-a scorecard (score / this type's weight per category), findings with quoted lines
-(accuracy first), and prioritized concrete fixes. **Never a full rewrite β€” respect
-the author's voice.**
+The `type` field is what selects the rubric profile and weights β€” read it before
+scoring, and say which profile you applied.
diff --git a/.github/instructions/docsite.instructions.md b/.github/instructions/docsite.instructions.md
index 9614b8c8c0..20789bfe2d 100644
--- a/.github/instructions/docsite.instructions.md
+++ b/.github/instructions/docsite.instructions.md
@@ -1,20 +1,25 @@
---
-applyTo: "apps/docsite/**"
+applyTo: 'apps/docsite/**'
---
# Docsite review instructions
The docsite (`apps/docsite/`) is a Next.js + StyleX app that documents Astryx.
-Its defining constraint is **how it handles data** β€” review against
-[`apps/docsite/README.md`](../../apps/docsite/README.md), specifically the
-"How It Works" and "The Rule" sections.
+It ships app code, not published packages, so consumer-breaking API changes
+aren't the concern here β€” the data pipeline, idiomatic composition, and mobile
+behavior are.
+
+The design-system rules are not restated here β€” see the
+[Component Audit Rubric](https://github.com/facebook/astryx/wiki/Component-Audit-Rubric)
+for the bar (StyleX usage, tokens, accessibility, and their check ids) and
+[`copilot-instructions.md`](../copilot-instructions.md) for severity and the
+review signal.
## Step 0 β€” Triage first
-Fast triage before depth. The docsite ships app code (not published packages),
-so consumer-breaking API changes aren't the concern β€” **blast radius** is:
+Fast triage before depth. The question is **blast radius**:
-- **Shared component / util** (e.g. a `components/blog/BlogCard`, a shared layout)
+- **Shared component / util** (e.g. `components/blog/BlogCard`, a shared layout)
β†’ higher stakes: a change ripples across pages. Check every call site, and
that a new prop is **optional** (additive) so existing usages don't break.
- **Single page / one-off** β†’ lower stakes, contained.
@@ -22,47 +27,42 @@ so consumer-breaking API changes aren't the concern β€” **blast radius** is:
Then pick depth: **fast path** for a contained single-page or copy tweak (verify
the data rule + accuracy, approve); **standard path** for a shared-component or
layout/structural change (full data-rule + idiomatic + mobile review below).
-State it briefly, e.g. `Triage: shared BlogCard, additive optional prop β†’ standard`.
+State it briefly, e.g. `Triage: shared BlogCard, additive optional prop β†’
+standard`.
## The data rule (primary review focus)
**All data comes from the build-time pipeline. Never hardcode package names,
-component lists, or theme objects in page code.**
-
-`scripts/generate-data.mjs` scans the monorepo and writes typed registries into
-`src/generated/` (which is gitignored). Pages import from those registries and
-render whatever the pipeline found. If a change needs data about the monorepo,
-it belongs in `generate-data.mjs` and is consumed from a registry β€” not inlined
-in a page.
+component lists, or theme objects in page code.** The rule, the pipeline it
+comes from, and its worked examples are in
+[`apps/docsite/README.md`](../../apps/docsite/README.md) β€” the "How It Works"
+and "The Rule" sections. Read them; that page is the source of truth, including
+how a new theme or package gets auto-discovered by `pnpm generate` rather than
+wired into a page by hand.
-Flag as violations:
+What that means when reading a diff β€” flag any of these as violations:
-- Importing a built theme directly in a page (e.g.
+- A built theme imported directly in a page (e.g.
`import {fooTheme} from '@astryxdesign/theme-foo/built'`). Use `themeObjects`
- from the generated `themeRegistry` instead.
-- Hand-maintained arrays of component names. Use `componentRegistry`.
-- Package-name switches like `if (pkg === '@astryxdesign/core')`. Let the
+ from the generated `themeRegistry`.
+- A hand-maintained array of component names. Use `componentRegistry`.
+- A package-name switch like `if (pkg === '@astryxdesign/core')`. Let the
pipeline classify packages.
-- Any hardcoded package/version/description that duplicates what
- `packageRegistry`, `blockRegistry`, `templateRegistry`, `docsRegistry`, or
- `showcaseRegistry` already provide.
-
-New source? The registries auto-discover it: a new theme package or a new
-`packages/<name>/` is picked up by `pnpm generate` after it's added to
-`apps/docsite/package.json` dependencies β€” no manual page wiring.
+- Any hardcoded package/version/description duplicating what `packageRegistry`,
+ `blockRegistry`, `templateRegistry`, `docsRegistry`, or `showcaseRegistry`
+ already provides.
## Blog content
-Blog posts are human-authored Markdown under `src/content/blog/posts/` with
-validated YAML frontmatter (`title`, `description`, `date`, `type`, `authors`,
-`tags`). Follow
-[`src/content/blog/README.md`](../../apps/docsite/src/content/blog/README.md);
-new authors register in `src/content/blog/authors.ts`. Drafts
-(`draft: true`) are excluded from production output.
+Blog posts are human-authored Markdown under `src/content/blog/posts/` β€” they
+match this file's `applyTo` but are reviewed as prose, not code. See
+[`blog.instructions.md`](./blog.instructions.md) for the review protocol and
+[`src/content/blog/README.md`](../../apps/docsite/src/content/blog/README.md)
+for the frontmatter contract.
## Idiomatic Astryx (nudge, don't block)
-The docsite is Astryx's own showcase β€” it should be built *with* Astryx, not
+The docsite is Astryx's own showcase β€” it should be built _with_ Astryx, not
around it. When a change reaches for raw HTML/CSS where an Astryx primitive
exists, **nudge** toward the idiomatic path (a suggestion, not a hard block β€”
the docsite has real app-specific needs the component set won't always cover):
@@ -71,16 +71,14 @@ the docsite has real app-specific needs the component set won't always cover):
`HStack`/`Grid`/`Center`/`Card` over `<div>`, `Text`/`Heading` over text tags,
`Button`/`Link`, `Table`, `List`, `Icon` (never raw `<svg>` as an icon).
- Style through props + semantic tokens (`xstyle`, `gap`, `padding`, `variant`),
- not custom CSS or raw color/spacing values. Prefer attaching behavior via the
- system's hooks/props over adding a wrapper element (see the packages reviewer's
- "avoid unnecessary wrappers" guidance β€” it applies here too).
+ not custom CSS or raw color/spacing values.
- If the docsite genuinely needs something the component set lacks, that's a
signal worth surfacing: note it as a possible gap to file upstream, rather than
quietly forking a bespoke pattern in page code.
The bar is lighter than for `packages/**` β€” the docsite ships app code, not
published components β€” so frame these as "here's the idiomatic way" nudges, and
-reserve firm flags for raw CSS/hardcoded tokens that have a clear Astryx
+reserve firm flags for raw CSS or hardcoded tokens that have a clear Astryx
equivalent.
## Mobile-friendliness
@@ -104,7 +102,7 @@ for how it degrades on mobile, and flag the common failure modes:
should scroll within its container, not blow out the page width. Interactive
targets should stay comfortably tappable (~44px) at mobile sizes.
- **Prefer CSS-first responsiveness.** The docsite leans on `useMediaQuery` /
- `isMobile` JS in places; for *layout* that CSS can express, prefer
+ `isMobile` JS in places; for _layout_ that CSS can express, prefer
`@container` queries, `Grid` `minChildWidth`, `flex-wrap`, and
`clamp()`/`min()`/`max()` over JS breakpoint branching (fewer hydration/SSR
mismatches, no layout flash). JS breakpoints are fine when the change is
@@ -119,4 +117,4 @@ asserting it works from the diff.
Docsite-only or CLI-docs-only changes are a light review overall β€” the
data-from-pipeline rule is the primary gate, plus the idiomatic-Astryx and
-mobile checks above. Keep code comments minimal.
+mobile checks above.
diff --git a/.github/instructions/packages.instructions.md b/.github/instructions/packages.instructions.md
index 58f1813f99..0a5850235d 100644
--- a/.github/instructions/packages.instructions.md
+++ b/.github/instructions/packages.instructions.md
@@ -4,8 +4,23 @@ applyTo: 'packages/**'
# Package review instructions
-These paths ship as published `@astryxdesign/*` packages, so review them
-against Astryx's API guidance and component review protocol.
+These paths ship as published `@astryxdesign/*` packages, so review them against
+Astryx's API guidance and component review protocol.
+
+**Read first, and don't restate here:**
+
+- [Component Audit Rubric](https://github.com/facebook/astryx/wiki/Component-Audit-Rubric)
+ β€” the bar: every rule as a numbered check with its severity and exceptions,
+ the bar per change type, and the trigger table mapping what a diff touches to
+ the checks it earns. Cite check ids in findings.
+- [`copilot-instructions.md`](../copilot-instructions.md) β€” severity, the review
+ signal line, summary-vs-inline, the labels, same bar for every author.
+- [CONTRIBUTING β†’ Code Style](../../CONTRIBUTING.md#code-style) β€” what this repo
+ enforces mechanically: TS strict, ref-as-prop, `'use client'`, JSDoc
+ `@example` fences.
+
+What follows is what is specific to **published package code** and lives
+nowhere else.
## Step 0 β€” Triage first: categorize, assess risk, pick a path
@@ -13,6 +28,12 @@ Before reviewing in depth, do a fast triage. It decides _how hard_ to look and
in what order, so effort lands where the risk is β€” and so the risk checks
(especially breaking changes) happen **up front**, not as an afterthought.
+This is the triage the rubric points at; it is stated here and only here. The
+**bar** each change type has to clear is in
+[the rubric's bar per change type](https://github.com/facebook/astryx/wiki/Component-Audit-Rubric#reviewing-a-change),
+and the **specific checks** a diff earns come from the rubric's trigger table.
+Triage sets depth; those two set content.
+
**1. Categorize the PR** (by what it changes, not just the title prefix):
| Category | Signals |
@@ -30,11 +51,9 @@ in what order, so effort lands where the risk is β€” and so the risk checks
consumers may depend on. (The tell for an _accidental_ breaking change:
unrelated tests/examples/call sites had to be edited β€” see the silent-breaking
rule in Judgment.) A real breaking change must be **intentional and signalled
- with a `[breaking]` changeset category** (pre-1.0 that means a `minor` bump;
- every other category is `patch`, and `major` is never used), and for a
- removed/renamed/changed public API, a **codemod** under `astryx upgrade`.
- Flag a breaking change with no `[breaking]` changeset (and no codemod where one
- is warranted) as blocking.
+ with a `[breaking]` changeset category**, and for a removed/renamed/changed
+ public API, a **codemod** under `astryx upgrade`. Flag a breaking change with
+ no `[breaking]` changeset (and no codemod where one is warranted) as blocking.
- **What's the blast radius?** A core primitive many components build on, or a
shared type/context, is higher-stakes than a leaf component or a docsite tweak.
@@ -45,91 +64,66 @@ in what order, so effort lands where the risk is β€” and so the risk checks
the referenced API exist / does the fix match the described bug), confirm the
test/changeset, and approve. Don't manufacture findings on a clean small PR.
**A standalone test PR is not automatically fast-path** β€” it still has to clear
- the test-quality bar under "Calibrate to the PR type" (a test existing and
- passing is necessary, not sufficient).
+ the test-quality bar under "Calibrate to the PR type".
- **Standard path** β€” a normal bug fix or a contained prop/behavior change. Run
- the full Mechanical checklist + convergence + Judgment below.
+ the checks the diff triggers, plus Judgment below.
- **Deep path** β€” new API surface, a breaking change, a plugin/hook that extends
- a host, or a high-blast-radius core change. Do the full review **and** route
- the API-design decision to a human (see "When to flag for engineering / human
- judgment"); note it should be spec'd + vibe-tested. Do not verdict the API
- yourself.
+ a host, or a high-blast-radius core change. Run every automatable check **and**
+ route the API-design decision to a human (see "When to flag for engineering /
+ human judgment"); note it should be spec'd + vibe-tested. Do not verdict the
+ API yourself.
> **Hard stop β€” new props / API changes from a contributor need human judgment.**
-> If a PR adds a **new prop** or otherwise changes API surface (a new
-> component, variant, exported hook/type, or a changed/removed signature) and the
-> author is in the **contributor bucket** (see Review buckets in the root
-> instructions β€” not in `.github/ENGOWNERS` or `.github/DESIGNOWNERS`), the AI
-> reviewer must **not**
-> approve or merge it β€” even if it's clean, additive, and passing CI. Flag it as
-> **⚠️ Needs human/maintainer judgment on the API surface** and leave the
-> approve/merge decision to a human. "Additive and non-breaking" is _not_
-> sufficient to auto-approve API surface β€” whether the API _should exist_ and
-> take this shape is a human call. Behavior-only fixes, tests, docs, and chores
-> from contributors can still take the fast/standard path.
-
-State the category, the risk (breaking? blast radius?), and the chosen path at
-the top of the review, e.g. `Triage: bug fix Β· non-breaking Β· low blast radius β†’
-fast path`. This makes the depth of review legible and ensures the
-breaking-change question is answered on every PR.
-
-## Review Signal β€” high-risk triggers for this scope
-
-The shared **Review buckets** and **Review Signal** model lives in the root
-`copilot-instructions.md` β€” apply it. This section defines what counts as
-**high-risk** _within `packages/**`_, which is what drives the signal:
-
-A change in this scope is **high-risk** when it involves any of:
+> If a PR adds a **new prop** or otherwise changes API surface (a new component,
+> variant, exported hook/type, or a changed/removed signature) and the author is
+> in the **contributor bucket** (not in `.github/ENGOWNERS` or
+> `.github/DESIGNOWNERS`), the AI reviewer must **not** approve or merge it β€”
+> even if it's clean, additive, and passing CI. Flag it as **⚠️ Needs
+> human/maintainer judgment on the API surface** and leave the approve/merge
+> decision to a human. "Additive and non-breaking" is _not_ sufficient to
+> auto-approve API surface β€” whether the API _should exist_ and take this shape
+> is a human call. Behavior-only fixes, tests, docs, and chores from
+> contributors can still take the fast/standard path.
+
+State the category, the risk, the path, and the checks you ran at the top of the
+review, e.g. `Triage: bug fix Β· non-breaking Β· low blast radius β†’ fast path Β·
+checks: Β§1 A4/A5, Β§7 C1`.
+
+## What counts as high-risk in this scope
+
+The shared review-signal model lives in `copilot-instructions.md`. Within
+`packages/**`, a change is **high-risk** when it involves any of:
- **Public API change** β€” a new/changed/removed export, prop, variant, hook,
- type, or signature; a changed default; changed DOM/class/ARIA output (see Step
- 0 breaking-change scan and "Adding a new prop").
+ type, or signature; a changed default; changed DOM/class/ARIA output.
- **New component or module** β€” a net-new component directory, especially added
directly to `core` (skipped `lab`) β€” see Lifecycle & promotion.
-- **New package** β€” a net-new `@astryxdesign/*` package β€” see Lifecycle &
- promotion. Always human-judgment.
+- **New package** β€” a net-new `@astryxdesign/*` package. Always human-judgment.
- **Suspected regression** β€” an unintended behavior/logic change or a silent
breaking change to a shared type/context (see Judgment).
-Anything else in this scope is **low-risk** for signal purposes. The one
-explicitly low-risk _area_ inside `packages/**` is **`packages/themes/**`**
-(theme values); a theme-only change does not trip the high-risk gate β€” though
-still apply the design blast-radius check in Judgment (a token change can
-regress everywhere it composites).
-
-The high-risk determination is also computed deterministically by
-`.github/workflows/review-signal.yml`, which applies the **`needs:code-review`**
-label and disables auto-merge on high-risk PRs. If the PR carries that label,
-lead with πŸ”΄ and focus on the high-risk surface (see the label note in the root
-instructions). Frame the review by bucket β€” the bucket sets _tone_, the area
-sets the _gate_:
-
-- **Contributor** β†’ your review is the _initial pass_ that tells a code owner
- where to focus. For a new prop / API change / new component / new package, add
- the explicit **⚠️ Needs human/maintainer judgment on the API surface** note β€”
- additive and passing CI is _not_ sufficient to imply approval.
-- **Design owner** β†’ same checks, framed for a designer: name what crosses into
- engineering territory and needs an engineer's eye.
-- **Eng team** β†’ assistant framing: surface the same findings as input to the
- author's own judgment.
+Anything else in this scope is low-risk for signal purposes. The one explicitly
+low-risk _area_ inside `packages/**` is **`packages/themes/**`** (theme values);
+a theme-only change does not trip the high-risk gate β€” though still apply the
+design blast-radius check in Judgment, since a token change can regress
+everywhere it composites.
## Calibrate to the PR type
-Once triaged, weight the review by what the PR is trying to do:
+Once triaged, weight the review by what the PR is trying to do. The evidence
+each type owes is in
+[the rubric's bar per change type](https://github.com/facebook/astryx/wiki/Component-Audit-Rubric#reviewing-a-change);
+these are the package-specific reading notes on top of it.
-- **Bug fixes** β€” require **evidence in the description**. A fix should
- demonstrate the bug first (a failing test, a reproduction, or another
- detection method), apply the fix, then demonstrate success (the test now
- passes). Flag a bug-fix PR that changes behavior with no failing-test-then-
- passing evidence and ask for it β€” a fix without a regression test can silently
- break again.
+- **Bug fixes** — the red→green evidence belongs **in the PR description**. Flag
+ a bug-fix PR that changes behavior without it and ask; a fix with no
+ regression test can silently break again.
- **Tests** β€” a test PR must earn its merge by testing the **contract, not the
implementation**. A passing test that exists is necessary but _not_ sufficient
- to approve; judge it against the bar below and, if it's implementation-coupled
- or padding, request changes (kindly) naming the specific assertions to cut or
- refocus. The one-line test: _does this protect a promise a consumer relies on,
- or does it just mirror the code?_ If it would break on a harmless refactor yet
- survive a real bug, it's slop.
+ to approve. The one-line test: _does this protect a promise a consumer relies
+ on, or does it just mirror the code?_ If it would break on a harmless refactor
+ yet survive a real bug, it's slop β€” request changes (kindly), naming the
+ specific assertions to cut or refocus.
- **βœ… Worth testing** β€” the public behavioral contract (state transitions,
controlled/uncontrolled, callbacks fire with the right args, documented edge
cases: empty / boundary / overflow); each meaningful branch of a pure
@@ -143,37 +137,34 @@ Once triaged, weight the review by what the PR is trying to do:
with no logic between); trivial padding ("renders without crashing" as the
_only_ assertion, or `it.each` explosions with no distinct risk per case);
and computed style/token/pixel assertions (that's brittle design territory).
-- **Docs** β€” validate against reality. Check that the documentation is actually
- correct (matches the code/API/behavior on this branch). When a claim is a
- matter of best practice or judgment rather than fact, **call it out for a
- maintainer** rather than asserting it's right or wrong.
+- **Docs** β€” validate against reality: does the documentation match the
+ code/API/behavior **on this branch**? When a claim is a matter of best practice
+ or judgment rather than fact, call it out for a maintainer rather than
+ asserting it's right or wrong.
- **New features / new components** β€” whether this is the _right way to expose
the functionality_ is a human judgment call. **Do not render a verdict on the
- API design here.** You may still run the mechanical, convention, and
- convergence checks below, but explicitly **flag that maintainers should review
- the API surface carefully** (and that new surface should be spec'd and
- vibe-tested) rather than approving the design yourself.
+ API design.** Run the mechanical, convention, and convergence checks, then
+ explicitly flag that maintainers should review the API surface (and that new
+ surface should be spec'd and vibe-tested).
## When to flag for engineering / human judgment
Many Astryx contributions come from designers building with an AI assistant.
The assistant is good at composition and convention, but some changes cross into
territory where **engineering review and human judgment are required** β€” and the
-review should **say so explicitly** rather than quietly approving. If you (the
-reviewer) find yourself uncertain, that uncertainty is itself the signal: name
-it, don't paper over it.
+review should **say so explicitly** rather than quietly approving. If you find
+yourself uncertain, that uncertainty is itself the signal: name it.
Add an explicit **"⚠️ Needs engineering / human judgment"** note when the change
involves any of:
- **New public API surface or an API-shape decision** β€” a new component, a new
- prop/variant, or changing an existing prop's contract. (The _right_ shape is a
- human call β€” see New features above.)
+ prop/variant, or changing an existing prop's contract.
- **New runtime complexity** β€” effects, refs, observers
(`MutationObserver`/`ResizeObserver`/`IntersectionObserver`), imperative DOM
work, event listeners, timers, async coordination, or anything touching a hot
- path (see the complexity/perf smell in Judgment). Designers should not land
- this class of change without an engineer confirming it's the right mechanism.
+ path. Designers should not land this class of change without an engineer
+ confirming it's the right mechanism.
- **Accessibility semantics** β€” ARIA roles/states, focus management, keyboard
interaction, live regions/announcements. Getting these subtly wrong is worse
than omitting them.
@@ -194,64 +185,47 @@ _why_ (e.g. "the `ResizeObserver` in `X.tsx` is a runtime-complexity + perf
decision β€” an engineer should confirm a container query wouldn't do"), so the
designer knows exactly what to hand off.
-## API guidance (the review protocol)
+## API guidance
-The authoritative rules live in the Contributing wiki β€” apply them and cite the
-specific rule when something conflicts:
+The rules themselves are on the wiki β€” apply them and cite the specific rule
+when something conflicts:
- **[API Conventions](https://github.com/facebook/astryx/wiki/API-Conventions)** β€”
naming (`<Namespace><Variant><Type><Postfixes>`, unprefixed: `Button`, not
- `AstryxButton`), prop patterns, and composition rules. Key principles to
- enforce:
- - **Guidance over enforcement** β€” components provide capability, not design
- guardrails; if a consumer passes a prop value, render it.
- - **Prop independence** β€” one prop must not suppress another prop's output;
- variants affect styling, never whether sibling props appear (narrow physical
- exceptions like `isTruncated`/`maxLines`).
- - **Orthogonal axes** β€” each prop controls one dimension of variation; if you
- can't name the axis without describing a use case, it's a design recipe, not
- a primitive.
- - **Composition vs config** β€” utility primitives may expose granular knobs;
- high-level compositions (`AppShell`, `Table`, `CommandPalette`) customize
- through composition (slots, children, render props), not prop explosion.
- - **Match existing siblings** β€” mirror the API shape of comparable components;
- don't invent a new convention when one already exists.
+ `AstryxButton`), the prop-surface contract, and the principles a review leans
+ on most: guidance over enforcement, prop independence, orthogonal axes,
+ composition over config for high-level components, and matching existing
+ siblings.
- **[Component Specification Protocol](https://github.com/facebook/astryx/wiki/Component-Specification-Protocol)** β€”
- the process new components must follow.
+ the evidence-backed 9-phase process new components must follow.
- **[API Arbitration](https://github.com/facebook/astryx/wiki/API-Arbitration)** β€”
- how API design questions get resolved.
+ where naming and shape disputes get resolved instead of in the PR.
### Adding a new prop β€” converge, don't diverge
-When a diff **adds a new prop** (or a new variant/enum value) to a component,
-don't evaluate it in isolation. First check whether other components already
-express the same capability, and push to converge on the existing shape:
-
-- **Search for prior art.** Look for existing components with a prop of similar
- _purpose_ or _behavior_ β€” the same axis of variation, even under a different
- name (e.g. `size` vs `scale`, `isLoading` vs `busy`, `tone` vs `variant` vs
- `color`, `density` vs `compact`). Comparable components should already be
- siblings in the same family; check those first, then the wider system.
-- **Prefer the established name and value shape.** If the capability exists
- elsewhere, reuse that prop name, type, default, and value vocabulary. Flag a
- new prop that reinvents an existing one under a different name or a different
- value shape (booleans following `is`/`has`; validation via
- `status={type, message?}`), and suggest converging on the existing convention.
-- **Flag near-duplicates that should unify.** If the new prop and an existing
- one are ~80% the same intent, call that out β€” the right outcome is often one
- shared prop across both components, not two subtly-different ones. Divergent
- sibling APIs are exactly the drift these conventions exist to prevent.
-- **When no prior art exists,** the prop is genuinely new API surface β€” hold it
- to the API Conventions principles above (orthogonal axis, prop independence,
- guidance-over-enforcement) and note that new API should be spec'd and
- vibe-tested rather than settled in the PR (route naming disputes to
- [API Arbitration](https://github.com/facebook/astryx/wiki/API-Arbitration)).
+When a diff **adds a new prop** (or a new variant/enum value), don't evaluate it
+in isolation. Check whether other components already express the same
+capability, and push to converge:
+
+- **Search for prior art.** Look for an existing prop with the same _axis of
+ variation_ under a different name (`size` vs `scale`, `isLoading` vs `busy`,
+ `tone` vs `variant` vs `color`, `density` vs `compact`). Check sibling
+ components in the same family first, then the wider system.
+- **Prefer the established name and value shape** β€” reuse the existing prop
+ name, type, default, and vocabulary. Flag a new prop that reinvents an
+ existing one under a different name or value shape.
+- **Flag near-duplicates that should unify.** If the new prop and an existing one
+ are ~80% the same intent, the right outcome is often one shared prop across
+ both, not two subtly-different ones.
+- **When no prior art exists,** it is genuinely new API surface β€” hold it to the
+ API Conventions principles, and note that it should be spec'd and vibe-tested
+ rather than settled in the PR.
### Plugins & hooks that extend a host component
-Some components expose a plugin/hook surface (e.g. `Table` with
-`useTable*` plugins). These extend a host, so review them for consistency _with
-that host_, not in isolation β€” recurring issues seen in real review:
+Some components expose a plugin/hook surface (e.g. `Table` with `useTable*`
+plugins). These extend a host, so review them for consistency _with that host_,
+not in isolation β€” recurring issues seen in real review:
- **Mirror the host's API shape, in and out.** A plugin should accept and return
the same shapes the host already uses. If `Table` accepts `idKey` (a key that
@@ -259,20 +233,17 @@ that host_, not in isolation β€” recurring issues seen in real review:
should accept the same rather than forcing a bespoke callback β€” and should
**name its outputs to match the host's props** so they compose directly.
Prefer `const {idKey} = usePlugin(); <Table idKey={idKey} />` over exporting
- `getRowKey` that the caller has to remember maps to `idKey`. Flag renamed
- or reshaped equivalents.
+ `getRowKey` that the caller has to remember maps to `idKey`. Flag renamed or
+ reshaped equivalents.
- **Semantic values first, arbitrary as the escape hatch.** When a plugin/prop
takes a visual value (color, status, tone), the first-class API is the
system's **semantic tokens** (`color: 'accent'` / `'success'`), not raw values.
- Allowing arbitrary values is fine as an escape hatch, but the _default_ shape
- should be system semantics β€” flag an API where the raw/arbitrary form is the
- primary one.
+ Arbitrary values are fine as an escape hatch, but flag an API where the
+ raw/arbitrary form is the primary one.
- **Decide host-level vs plugin-level deliberately** β€” especially for
accessibility. If an option affects host semantics (e.g. a row `startFrom`
index that changes `aria-rowindex`), it likely belongs on the **host** so the
- semantics are correct even when nothing visible renders. Flag a11y-affecting
- config buried in a plugin when the host is the right owner (and note
- interactions like pagination).
+ semantics are correct even when nothing visible renders.
### Hook stability & reuse of existing data
@@ -281,67 +252,35 @@ For hooks (plugins or otherwise), watch two things that bit real Table PRs:
- **Dependency-set stability.** A hook whose memoized output depends on a
frequently-changing value (e.g. the whole `data` array) will re-compute and
hand consumers a new reference on every update, destabilizing everything
- downstream. Flag dependency sets that make the return value churn; prefer
- stable keys/refs.
+ downstream. Flag dependency sets that make the return value churn.
- **Don't re-derive what's already available.** If the host or the DOM already
exposes a value, read it instead of recomputing. Real case: a row-index plugin
looped over `data` to compute indices the table row already carried as
- `aria-rowindex` β€” the loop (and the extra API surface) was avoidable. Flag
- redundant full-collection loops and per-item rescans when an existing
- value/source would do (ties into the complexity/perf smell in Judgment).
+ `aria-rowindex` β€” the loop (and the extra API surface) was avoidable.
## Design review
-Some package changes are also _design_ changes. When a diff affects how a
-component **looks or behaves visually**, review it against
-**[Design Conventions](https://github.com/facebook/astryx/wiki/Design-Conventions)** β€”
-the design-side sibling of API Conventions β€” in addition to the checks below.
-
-**When to apply (detect a design review is needed).** Treat a change as
-design-affecting when it touches any of: `.stylex.ts` files or `stylex.*`
-styling; token usage (color, spacing, radius, shadow, typography, motion,
-elevation/z-index); a new component, variant, or `size`/`density` prop; visual
-state handling (rest/hover/focus/active/disabled/loading, selected, or
-`status`); layout/structure, borders, or overlays/popovers. Pure logic, types,
-tests, or docs with no visual effect do **not** need a design pass β€” say so and
-move on.
-
-When it does apply, evaluate against the Design Conventions foundations and
-flag the concrete "smells" that page names:
-
-- **Tokens, not raw values** β€” every visual value references a token; a raw
- color/space/radius/shadow in core is fixed by using the right token, never by
- swapping one raw value for another.
-- **Spacing (relationship hierarchy)** β€” 4px grid; gaps step up with grouping
- (`label→input < fields < groups < sections`); flag monotonous spacing,
- inverted nesting (child gap wider than parent), off-grid values, nested cards.
-- **Concentric radius** β€” `r_inner β‰ˆ r_outer βˆ’ gap`; radius from a role token;
- flag non-concentric nesting, thick accent borders / side-tab stripes on
- rounded corners.
-- **Vertical rhythm (size/density)** β€” fixed-height (`size`) and variable-height
- (`density`) controls tuned together to share a baseline; ~44px hit area
- without inflating the visual; flag off-scale heights (not 28/32/36) and
- cramped padding.
-- **Elevation** β€” shadow tier matches stacking order (base < dropdown < sticky <
- overlay/modal < toast < tooltip); popovers escape `overflow:hidden`; flag
- arbitrary z-index and hairline-border-plus-diffuse-shadow or colored glows.
-- **Typography** β€” role tokens; hierarchy β‰₯1.25 size ratio; body β‰₯12px; leading
- β‰₯1.3; flag flat hierarchy, all-caps/justified/gradient body, lines >~75ch.
-- **Color** β€” every fg/bg pair passes WCAG AA in light _and_ dark; interaction
- tints are alpha overlays (not opaque); status pairs color with an icon (never
- color alone); one clear primary action; no pure `#000`/`#fff`.
-- **Motion** β€” duration matches the change's weight; only `transform`/`opacity`
- animate (never layout props); `--ease-standard`, no bounce/elastic; honor
- `prefers-reduced-motion`.
-- **State representation** β€” reuse an existing approved representation for a
- state before inventing a new one; every relevant state (rest/hover/focus/
- active/disabled/loading/status/selected) is designed.
-
-Run the objectively-checkable items (tokens, grid, concentric radius, contrast,
-z-index, motion properties) as pass/fail; treat proportions, density, and
-composition as judgment. This mirrors Hardening Layer 3 β€” where a review
-resolves a genuinely new design question, note that it should be recorded back
-into the Design Conventions page rather than decided ad hoc in the PR.
+Some package changes are also _design_ changes. The design rules are
+**[Design Conventions](https://github.com/facebook/astryx/wiki/Design-Conventions)**
+β€” spacing and the 4px grid, concentric radius, vertical rhythm, elevation,
+typography, color and contrast, motion, and the approved state
+representations. Apply that page; don't re-derive it here.
+
+**When it applies.** Treat a change as design-affecting when it touches any of:
+`.stylex.ts` files or `stylex.*` styling; token usage (color, spacing, radius,
+shadow, typography, motion, elevation/z-index); a new component, variant, or
+`size`/`density` prop; visual state handling (rest/hover/focus/active/disabled/
+loading, selected, or `status`); layout/structure, borders, or overlays/popovers.
+Pure logic, types, tests, or docs with no visual effect do **not** need a design
+pass β€” say so and move on.
+
+**How to run it.** Score the objectively-checkable items (tokens, grid,
+concentric radius, contrast, z-index, motion properties) as pass/fail; treat
+proportions, density, and composition as judgment, and judge those from
+**rendered screenshots**, not from reading CSS. This mirrors Hardening Layer 3 β€”
+where a review resolves a genuinely new design question, note that it should be
+recorded back into the Design Conventions page rather than decided ad hoc in the
+PR.
## Lifecycle & promotion
@@ -360,148 +299,72 @@ high-attention (post a note rather than hard-blocking β€” this is advisory).
**lab β†’ core after hardening**.
**Flag a diff that adds a brand-new component directory under
-`packages/core/src/<Name>/` with no prior presence in `packages/lab/src/`.**
-That's a component skipping the staging step. (A lab→core _promotion_ — a delete
-under `packages/lab/src/**` paired with the add in core β€” is the healthy path
-and is fine; the concern is the _net-new_ component that was never in lab.)
-
-When you see a net-new core component, ask the author to confirm either that it
-went through lab, or that it genuinely meets the core bar that lab explicitly
-does _not_ guarantee:
-
-- Full keyboard + a11y (ARIA contracts, focus, `:hover` guarded by
- `@media (hover: hover)`)
-- Theming story + `themeProps`, semantic tokens throughout, status states
- (error/warning/success) where it's an input
-- Spec compliance with an approved spec issue, and **vibe-tested** API
-- Complete surface (see Mechanical checklist below)
+`packages/core/src/<Name>/` with no prior presence in `packages/lab/src/`.** A
+lab→core _promotion_ — a delete under `packages/lab/src/**` paired with the add
+in core β€” is the healthy path; the concern is the _net-new_ component that was
+never in lab. Ask the author to confirm it went through lab, or that it meets
+the core bar lab does not guarantee (full keyboard + a11y, a theming story with
+`themeProps`, spec compliance, a complete surface).
**Require a linked spec issue.** A new component's PR description must link to a
tracking issue that clearly ran the
-[Component Specification Protocol](https://github.com/facebook/astryx/wiki/Component-Specification-Protocol)
-(the evidence-backed 9-phase process: research, use-case enumeration, drafted
-API with rationale, surface-area audit, spec review, API arbitration). Flag a
-new-component PR whose description has **no linked spec issue**, or links an
-issue that is just a feature request / "add X" with none of the protocol's
-evidence β€” and ask for the spec before the API is reviewed on its merits. The
-spec is the contract; a new component without one isn't ready.
+[Component Specification Protocol](https://github.com/facebook/astryx/wiki/Component-Specification-Protocol).
+Flag a new-component PR with **no linked spec issue**, or one linking a bare
+"add X" feature request with none of the protocol's evidence, and ask for the
+spec before the API is reviewed on its merits. The spec is the contract.
Small additions and deliberately spec-approved direct-to-core work do happen β€”
-this isn't an automatic rejection β€” but a new core component that skipped lab
-should be called out so a human confirms it was intentional and hardened.
+this isn't an automatic rejection β€” but call it out so a human confirms it was
+intentional.
### New package (net-new `@astryxdesign/*`)
-A brand-new package is a bigger commitment than a new component β€” it adds a
-published surface the project maintains and versions indefinitely. **Flag a diff
-that adds a new top-level `packages/<name>/` directory** (a new `package.json`
-with an `@astryxdesign/*` name, new `exports`, its own build/release wiring).
-This is always a high-risk trigger β€” route it to human/maintainer judgment
-regardless of author, and confirm:
+A brand-new package is a bigger commitment than a new component β€” a published
+surface the project maintains and versions indefinitely. **Flag a diff that adds
+a new top-level `packages/<name>/` directory.** Always route to human/maintainer
+judgment regardless of author, and confirm:
- **The package should exist as its own package** (vs. living in an existing
- one) β€” a deliberate, maintainer-level decision, not an incidental add.
+ one) β€” a deliberate, maintainer-level decision.
- **Publish posture is intentional** β€” `private: true` + `astryx.canaryOnly` for
- staging vs. a stable public package; the `"exports"` are generated
- (`scripts/sync-exports.js`), not hand-written; versioning joins the `fixed`
+ staging vs. a stable public package; `"exports"` generated by
+ `scripts/sync-exports.js`, not hand-written; versioning joins the `fixed`
group.
- **A tracking/spec issue is linked** establishing the need and scope.
-Never approve a net-new package on convention-cleanliness alone; whether it
-_should exist_ is a human call.
+Never approve a net-new package on convention-cleanliness alone.
### New template added already-visible (not `hidden`)
CLI templates/blocks are authored **hidden** and revealed only after they clear
-the template design bar. The CLI reads `hidden: true` and
-`hiddenComponents: ['Name', ...]` from a template's `.doc.mjs`; hidden entries
-are skipped from `--list`.
-
-**Flag a diff that adds a _new_ template/block whose `.doc.mjs` is not
-`hidden: true`** (i.e. it's publicly listed from the moment it lands). A new
-template appearing already-visible skipped the hidden-staging step and may not
-be hardened yet. Ask the author to confirm it meets the template design bar
-(component/token purity, layout, realistic mock data, and the design-judge
-visual axes; target grade B or above β€” see
-[Contributing Templates](https://github.com/facebook/astryx/wiki/Contributing-Templates)
-and the Design review section above), or to add `hidden: true` until it does.
+the template design bar β€” see
+[`templates.instructions.md`](./templates.instructions.md) for the full rule.
+Flag a diff that adds a _new_ template/block whose `.doc.mjs` is not
+`hidden: true`.
## Mechanical checklist
+The design-system rules (StyleX-only, semantic tokens, no style-only wrappers,
+the shared a11y primitives, `useLinkComponent()`) are numbered checks on the
+[Component Audit Rubric](https://github.com/facebook/astryx/wiki/Component-Audit-Rubric);
+what this repo enforces mechanically is in
+[CONTRIBUTING β†’ Code Style](../../CONTRIBUTING.md#code-style). What is specific
+to a published package:
+
- **Full component surface.** A component under `packages/*/src/<Name>/` should
ship `<Name>.tsx`, a colocated `<Name>.test.tsx`, `<Name>.doc.mjs`, and an
`index.ts` export, plus a Storybook story at
`apps/storybook/stories/<Name>.stories.tsx` (stories are not colocated β€”
`apps/storybook/.storybook/main.ts` only discovers
`../stories/**/*.stories.@(js|jsx|mjs|ts|tsx)`). Flag missing pieces.
-- **`ref` declared as a prop + `displayName`**, `export interface <Name>Props`,
- and exported types alongside the component. React 19 ref-as-prop is the
- convention: `forwardRef` is rejected by `@eslint-react/no-forward-ref`, and
- `@astryx/require-ref-prop` requires `ref?: React.Ref<T>` on a publicly
- exported props interface.
-- **`'use client'` first.** A file that imports a React client API from `react`
- must have `'use client';` as its first statement (only comments and blank
- lines may precede it) β€” enforced by `pnpm check:use-client`, part of
- `pnpm check:repo`.
+- **`export interface <Name>Props`** extending `BaseProps`, with types exported
+ alongside the component.
- **Never hand-edit the `"exports"` field in a package `package.json`.** It is
auto-generated from `src/` by `scripts/sync-exports.js` and committed on
`main`. Editing it by hand is a review-reject.
-- **StyleX only** β€” no raw CSS, no JS workarounds for CSS StyleX supports;
- verify against `internal/stylex-capabilities/CAPABILITIES.md`. Guard `:hover`
- with `@media (hover: hover)`. Use component-scoped `stylex.defineMarker()` for
- form controls β€” never `stylex.defaultMarker()`.
-- **Semantic tokens only** β€” no hardcoded color/spacing/radius/shadow;
- theme-agnostic output.
-- **Avoid unnecessary wrapper elements β€” prefer props and hooks.** Astryx favors
- attaching behavior/style to existing elements over adding a new wrapper node.
- Flag an added wrapper when a lighter path exists:
- - _Styling:_ components extend `BaseProps` (they take `xstyle`), so apply style
- directly β€” `<Divider xstyle={hasOutline && styles.titleDivider} />` β€” instead
- of wrapping the component in a styled `<div>`. This is the shape that shipped
- the off-center pagination carets (#4752): the mirror span put an extra
- element between the button's flex centering and the `Icon`, and moving the
- same style onto `<Icon xstyle={rtlStyles.mirror} />` fixed it. `@astryx/no-style-only-wrapper`
- reports the mechanical cases (a `div`/`span` whose only attributes are
- styles, wrapping a single Astryx component); it is a warning while the
- existing sites are migrated, so treat a **new** one as a review finding
- rather than assuming lint blocks it. The wrapper is legitimate when it does
- something the child cannot: establishing a flex/grid **container** (moving
- `display: flex` onto the child would restyle the child's own content),
- padding around the child's border box, or carrying semantics/behavior
- (`role`, `aria-*`, a `ref`, an event handler). Say which one applies rather
- than deleting the node reflexively.
- - _Behavior:_ reach for the behavior **hook** or **prop** the system already
- exposes rather than a wrapper component. E.g. a tooltip is available via the
- `tooltip` prop / `useTooltip` hook, and there are hooks for many behaviors
- (`useHoverCard`, `useClickableContainer`, `useCollapsible`, `useFocusTrap`,
- `useEntryAnimation`, `useInteractiveRole`, …). Prefer composing the hook onto
- the real element over introducing a wrapper that exists only to host the
- behavior. A wrapper adds a DOM node, can break layout/flex/grid parent-child
- relationships, and often complicates focus/ARIA β€” call it out when a hook or
- prop would avoid it.
-- **Navigation** uses `useLinkComponent()`, never a hardcoded `<a>`.
-- **Reuse the existing accessibility primitives β€” don't hand-roll.** Astryx
- ships shared a11y building blocks; new accessibility work should compose them
- rather than reinvent the behavior inline. Flag hand-rolled equivalents and
- point at the primitive:
- - Screen-reader-only content β†’ the **`VisuallyHidden`** component, not a custom
- `sr-only`/clip-rect style or an off-screen `<span>`.
- - Live-region announcements β†’ **`useAnnounce`**, not an ad-hoc `aria-live` node
- wired up by hand.
- - Roving focus / arrow-key navigation β†’ **`useListFocus`**, **`useGridFocus`**,
- or **`useTreeFocus`**; typeahead β†’ **`useTypeahead`**; a keyboard-shortcut
- hint β†’ **`useKeyboardHint`**; focus trapping β†’ **`useFocusTrap`**; interactive
- role/state wiring β†’ **`useInteractiveRole`**.
- These already implement the WAI-ARIA APG patterns and are tested, so reusing
- them keeps behavior consistent across the system. A genuinely new a11y pattern
- with no existing primitive is fine β€” but call it out for careful review (see
- "When to flag for engineering / human judgment") rather than landing a bespoke
- implementation quietly.
- **Docs in sync** β€” JSDoc file headers, `SYNC:` reminders, and `.doc.mjs`.
`@example` fences in JSDoc must be plain ` ``` ` (never language-tagged), or
Storybook autodocs won't render them.
-- **Changeset** present for consumer-visible changes, with `[category]` +
- `@handle`; pre-1.0 bumps are `patch`, except `[breaking]`, which is `minor`.
## Judgment
@@ -525,10 +388,8 @@ checks, flag it.
content is noisy, and reserving `assertive` for genuinely urgent messages.
- **`useEffect` is a smell.** Treat a new/changed Effect as something to justify,
not accept by default. Most UI logic doesn't need one β€” look for whether it
- belongs in an **event handler / callback** (logic that responds to a user
- action), a **ref** (imperative work that shouldn't trigger re-render), or
- plain **derivation during render / `useMemo`** (values computed from props or
- state). Use React's own guidance as the bar:
+ belongs in an **event handler / callback**, a **ref**, or plain **derivation
+ during render / `useMemo`**. Use React's own guidance as the bar:
[You Might Not Need an Effect](https://react.dev/learn/you-might-not-need-an-effect)
and [Synchronizing with Effects](https://react.dev/learn/synchronizing-with-effects).
Genuine Effects synchronize with an _external_ system (subscriptions, the DOM,
@@ -538,20 +399,16 @@ checks, flag it.
`MutationObserver` / `ResizeObserver` / `IntersectionObserver`, imperative DOM
measurement, event listeners, or a `useEffect` sync loop introduced to achieve
something CSS (or a token/prop) already does. Watch for observers or
- measurement in hot paths (per-row, per-keystroke, per-frame, large lists) that
- risk performance regressions, and for reintroducing work the platform handles
- natively (`:hover`/`@media (hover: hover)`, `@container`, `:nth-child`,
- `@starting-style`, `position-try`, `stylex.when.*`). Ask: could this be a CSS
- key, a container query, or a prop instead of JS observing the DOM? Prefer the
- simpler mechanism; call out the complexity and the regression risk when the
- heavy approach isn't justified.
+ measurement in hot paths (per-row, per-keystroke, per-frame, large lists), and
+ for reintroducing work the platform handles natively
+ (`:hover`/`@media (hover: hover)`, `@container`, `:nth-child`,
+ `@starting-style`, `position-try`, `stylex.when.*`).
- **Silent breaking changes to shared types/context.** Adding a **required**
field to a shared type, context value, or component API is a breaking change
for every existing consumer β€” even when the PR's own feature doesn't need them
to change. The **tell**: unrelated tests, examples, or call sites had to be
- updated just to satisfy the new field. When you see that, flag it and ask
- whether the field should be **optional** (applied internally with a default)
- instead β€” and whether the breaking change is worth it. (Real case: a new
+ updated just to satisfy the new field. Flag it and ask whether the field should
+ be **optional** (applied internally with a default) instead. (Real case: a new
required `aria-controls` id on a mobile-nav context forced edits to surfaces
that didn't otherwise need it.)
- **Unintended behavior/logic change.** Compare what the diff _actually changes_
@@ -562,28 +419,21 @@ checks, flag it.
change is _inside_ the area the author was working on, so it's easy to miss.
Watch especially for:
- **Design/token changes β€” judge by presentation impact, not the token type.**
- When a change touches a token, theme value, or style, reason about **how it
- renders and where that could break**, not just that a value changed. Ask:
- does this alter contrast, legibility, or emphasis? Does it change how a value
- _composites_ over other surfaces or in a different theme/mode (a change that
- looks fine on the one screen the author checked but regresses elsewhere)?
- Does it shift layout, spacing rhythm, or elevation order? Does it hold in
- both light and dark, and against every surface the token appears on? The
- canonical trap: a color that reads fine in isolation but was relied on to
- layer over other content, so the change silently degrades every place it
- composites. (One real instance: a theme edit that made a color opaque when
- other UI depended on it being translucent β€” fine where the author looked,
- broken where they didn't.) The principle is general: a design value rarely
- lives in one place, so weigh the change across everywhere it presents.
+ Reason about **how it renders and where that could break**: does it alter
+ contrast, legibility, or emphasis? Does it change how a value _composites_
+ over other surfaces or in a different theme/mode? Does it shift layout,
+ spacing rhythm, or elevation order? Does it hold in both light and dark, and
+ against every surface the token appears on? The canonical trap: a color that
+ reads fine in isolation but was relied on to layer over other content, so the
+ change silently degrades every place it composites. (One real instance: a
+ theme edit that made a color opaque when other UI depended on it being
+ translucent β€” fine where the author looked, broken where they didn't.)
- **Changed defaults / conditionals** β€” a default prop value, a comparison
(`>=` vs `>`), an early-return, or a guard that changed as a byproduct.
- **Generated-output drift** β€” a regenerated theme CSS / registry / token file
whose diff contains changes beyond the intended one.
- When you spot this, don't assume malice or intent β€” surface it as a question:
- "this also changes X (was `a`, now `b`) β€” does that hold everywhere it's used?"
- Naming it lets the author confirm or revert. The author being unaware, and
- having checked only the surface they were working on, is exactly why the
- reviewer checks the blast radius of a design change.
+ Surface these as a question β€” "this also changes X (was `a`, now `b`) β€” does
+ that hold everywhere it's used?" β€” so the author can confirm or revert.
- **Other smells.** State expressed by unmounting focusable elements (toggle
visibility so focus/a11y survive), unnecessary `useState` (prefer derived
values or refs, especially from interaction handlers), and excessive comments.
diff --git a/.github/instructions/templates.instructions.md b/.github/instructions/templates.instructions.md
index 637e3bc0a3..025b8ad782 100644
--- a/.github/instructions/templates.instructions.md
+++ b/.github/instructions/templates.instructions.md
@@ -4,24 +4,53 @@ applyTo: 'packages/cli/assets/templates/**'
# Template review instructions
-These are Astryx **templates** β€” page templates (`templates/pages/<name>/page.tsx`
-
-- `template.doc.mjs`) and block templates (`templates/blocks/.../[Name].tsx` +
- `[Name].doc.mjs`). They are copy-paste examples, so they carry design
- responsibility beyond any single component.
+These are Astryx **templates** β€” page templates
+(`templates/pages/<name>/page.tsx` + `template.doc.mjs`) and block templates
+(`templates/blocks/.../[Name].tsx` + `[Name].doc.mjs`). They are copy-paste
+examples, so they carry design responsibility beyond any single component.
> **Scope note.** These files also match `packages.instructions.md`. For
> template files, the component-authoring checklist there (the `ref` prop,
> sync-exports, colocated `.test.tsx`, etc.) does **not** apply β€” templates are
-> examples, not published components. Review them by the rubric below (and the
-> shared design and StyleX rules).
+> examples, not published components. Review them by the rubric below, plus the
+> shared design and StyleX rules on the
+> [Component Audit Rubric](https://github.com/facebook/astryx/wiki/Component-Audit-Rubric).
+
+## The grading rubric
Grade every changed template against the
-**[Template Grading Rubric](https://github.com/facebook/astryx/wiki/Contributing-Templates#template-grading-rubric)**
-in [Contributing Templates](https://github.com/facebook/astryx/wiki/Contributing-Templates).
-**Every template in the gallery should score B (75) or above.** Flag anything
-that would land below B; post findings as a scorecard (advisory β€” comment, don't
-hard-block).
+**[Template Grading Rubric](https://github.com/facebook/astryx/wiki/Contributing-Templates#template-grading-rubric)**,
+which carries the full criteria, the per-condition point tables, and the output
+format. **Every template in the gallery should score B (75) or above.** Flag
+anything that would land below B; post findings as a scorecard (advisory β€”
+comment, don't hard-block).
+
+The seven categories and their weights, as an index of what you are scoring:
+component purity (30) Β· icon purity (15) Β· custom CSS (15) Β· layout & structure
+(15) Β· doc metadata (10) Β· image handling (5) Β· code quality (10).
+
+Two of those have repo-specific detail the wiki page does not carry β€” apply
+these:
+
+- **Layout & structure.** Page templates root in `Layout` or `Center`, never
+ `AppShell` or a raw `<div>` β€” **exception:** `Shell -` category templates must
+ root in `AppShell` with global `TopNav`/`SideNav`. No global app chrome
+ otherwise (in-page nav β†’ `LayoutPanel` start slot; page header β†’
+ `LayoutHeader`). Navigation links are inert (`href="#"` / `onClick`) since a
+ template is a single page. Block templates are not wrapped in `AppShell`,
+ keep a single-pattern focus, and run ~20–100 lines.
+- **Image handling.** Demo imagery is referenced by a **root-relative path under
+ `/template-assets/<asset>.png`**, self-hosted in this repo under
+ `apps/docsite/public/template-assets/` and mirrored into the sandbox preview
+ at generate time. To use an existing image, browse that directory and
+ reference it by name with an asset-name comment; to add one, drop the file in
+ the same directory and reference it the same way. On scaffold,
+ `stripTemplateAssetRefs` swaps these paths for an inline placeholder so a
+ generated project renders with zero setup. Flag external URLs
+ (unsplash/placehold/picsum), expiring signed CDN URLs, and inline data URIs.
+ Image-backed `Thumbnail` examples are the one exception: they inline a
+ same-origin, samplable `data:` URI, required by `useImageMode` β€” see
+ `scripts/check-demo-media.mjs`.
## Step 0 β€” Triage first
@@ -33,81 +62,31 @@ Quick triage before grading. Two questions:
existing template is scoped to what changed.
- **Content-only vs. structural?** A copy/mock-data tweak is a fast grade
(purity + metadata); a layout/root/`AppShell` change needs the full Layout &
- Structure pass. State it briefly, e.g. `Triage: edit to existing template,
-layout change β†’ full structure pass`.
-
-## Score the 7 categories (100 pts)
-
-1. **Astryx component purity (30)** β€” count JSX tags; every raw lowercase HTML
- tag (`div`, `span`, `button`, `nav`, `ul`, `p`, `h1`–`h6`, `form`, `input`,
- `table`, `img`, …) is a flag unless it has no Astryx equivalent. Use
- `VStack`/`HStack`/`Grid`/`Card`/`Center` over `<div>`, `Text`/`Heading` over
- text tags, `Button`/`Link`, `List`/`ListItem`, `Table`, `FormLayout`,
- `Divider`, `Dialog`, `Collapsible`. Necessary exceptions (don't penalize):
- `<img>` with an astryx CDN src, `<form>` wrapping `FormLayout`,
- `<input type="hidden">`. Fragments and local PascalCase helpers don't count.
-2. **Icon purity (15)** β€” icons via `<Icon icon={X} />` or an `icon={X}` prop.
- Flag raw `<svg>`/`<path>`/etc., inline SVG components, and heroicons rendered
- without the `Icon` wrapper.
-3. **Custom CSS (15)** β€” style through Astryx props (`gap`, `padding`,
- `variant`, `size`, `color`, `level`, `minChildWidth`, `height`), not custom
- CSS. Count each declaration in `stylex.create`/`style={{}}`, and each
- `className`/`stylex.props()` usage. Token-valued Astryx props do **not**
- count.
-4. **Layout & structure (15)** β€”
- - _Page templates:_ root is `Layout` or `Center`, never `AppShell` or a raw
- `<div>` β€” **exception:** `Shell -` category templates must root in
- `AppShell` with global `TopNav`/`SideNav`. No global app chrome otherwise
- (in-page nav β†’ `LayoutPanel` start slot; page header β†’ `LayoutHeader`).
- Responsive grids use `Grid` + `minChildWidth`; centering uses `Center`.
- Single page only β€” navigation links inert (`href="#"` / `onClick`).
- - _Block templates:_ not wrapped in `AppShell`, single-pattern focus,
- ~20–100 lines.
-5. **Doc metadata (10)** β€” read the `.doc.mjs`. Pages need
- `type:'page'`, `name`, `description`, `isReady`. Blocks need `type:'block'`,
- `name`, `description`, `isReady`, `aspectRatio` (matching component shape β€”
- wide `16/4`, square `1`, tall `3/4`, content/form `4/3`), and
- `componentsUsed` listing **every** Astryx component actually used. Flag
- missing fields, a wrong `aspectRatio`, `componentsUsed` drift, and missing
- `scale` for tiny components (Badge/StatusDot/single Icon/Spinner β†’ `2` or
- `3`).
-6. **Image handling (5)** β€” demo imagery is referenced by a root-relative path
- under `/template-assets/<asset>.png`, self-hosted in the repo under
- `apps/docsite/public/template-assets/` (mirrored into the sandbox preview at
- generate time). To use an existing image, browse that directory and reference
- it by name with an asset-name comment; to add a new one, drop the file into
- that same directory and reference it the same way. On scaffold,
- `stripTemplateAssetRefs` swaps these paths for an inline placeholder so a
- generated project renders with zero setup. Flag external URLs
- (unsplash/placehold/picsum), expiring signed `scontent…fbcdn.net` URLs, and
- inline data URIs. Image-backed Thumbnail examples are the one exception: they
- inline a same-origin, samplable `data:` URI (required by `useImageMode` β€” see
- `scripts/check-demo-media.mjs`).
-7. **Code quality (10)** β€” `'use client';` first line; `export default`;
- self-contained imports (`@astryxdesign/core/*`, `@heroicons/react/*`, or
- local only); realistic mock data (real names/values, never
- "Lorem ipsum"/"Item 1"/"foo"); no dead code.
+ Structure pass.
+
+State it briefly, e.g. `Triage: edit to existing template, layout change β†’ full
+structure pass`.
## Reporting
-When a template diff is substantial (new template, or material change), post the
-rubric's scorecard: per-category points, a letter grade, the specific findings
-(raw HTML lines, raw SVG lines, custom-CSS declarations, layout/doc/image/quality
-issues), and the **top 3 fixes**. For small tweaks, just flag any category that
-now dips below B rather than re-grading the whole file.
+When a template diff is substantial (a new template, or a material change), post
+the rubric's scorecard: per-category points, a letter grade, the specific
+findings (raw HTML lines, raw SVG lines, custom-CSS declarations,
+layout/doc/image/quality issues), and the **top 3 fixes**. For small tweaks,
+just flag any category that now dips below B rather than re-grading the whole
+file.
-Also apply the shared **Design review** rules (see `packages.instructions.md`):
-templates are judged on the same visual axes β€” layout fidelity, visual
-hierarchy, spacing/alignment, component fidelity, and color/theming in light +
-dark.
+Templates are also judged on the shared design axes β€” see the Design review
+section of [`packages.instructions.md`](./packages.instructions.md), which
+points at [Design Conventions](https://github.com/facebook/astryx/wiki/Design-Conventions).
## Lifecycle note
-Templates are authored **hidden** and revealed only after they clear this bar
-(`hidden: true` / a `hiddenComponents` entry in the `.doc.mjs` keeps a template
-out of `--list`). The thing to catch is a template that **skips hidden-staging**:
-**flag a diff that adds a _new_ template/block whose `.doc.mjs` is not
-`hidden: true`** β€” it's publicly listed the moment it lands and may not be
-hardened yet. Ask the author to confirm it grades **B or above**, or to add
-`hidden: true` until it does. See
+Templates are authored **hidden** and revealed only after they clear this bar.
+The CLI reads `hidden: true` and `hiddenComponents: ['Name', ...]` from a
+template's `.doc.mjs`; hidden entries are skipped from `--list`. The thing to
+catch is a template that **skips hidden-staging**: **flag a diff that adds a
+_new_ template/block whose `.doc.mjs` is not `hidden: true`** β€” it's publicly
+listed the moment it lands and may not be hardened yet. Ask the author to
+confirm it grades **B or above**, or to add `hidden: true` until it does. See
[Component Lifecycle](https://github.com/facebook/astryx/wiki/Component-Lifecycle#promotion-gates).
diff --git a/.github/workflows/review-signal.yml b/.github/workflows/review-signal.yml
index fd974d0b15..8a16fc8815 100644
--- a/.github/workflows/review-signal.yml
+++ b/.github/workflows/review-signal.yml
@@ -26,8 +26,9 @@
# most component styling here is an inline stylex.create
# edit in a .tsx, which no path pattern can see.
#
-# Either label DISABLES auto-merge so the PR can't merge unattended, and is
-# cleared when an entitled owner approves (code β†’ CODEOWNER; design β†’ DESIGNOWNER
+# The CODE label DISABLES auto-merge so the PR can't merge unattended (the
+# design label is advisory and does not). Both are cleared when an entitled
+# owner approves (code β†’ CODEOWNER; design β†’ DESIGNOWNER
# or CODEOWNER). Code detection is path-based and deterministic; design adds a
# content-based diff score (deterministic too β€” same diff, same score). The
# Copilot reviewer reads these labels to focus its review (see
diff --git a/CLAUDE.md b/CLAUDE.md
index c35364089e..fa8649a5f7 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -70,7 +70,9 @@ Documentation lives in two places:
## Quick Reference
-- **Package manager**: pnpm 11 (via corepack β€” see CONTRIBUTING.md)
+- **Package manager**: pnpm 11, pinned by the `packageManager` field (see
+ CONTRIBUTING.md for install options β€” Corepack is one of several, and Node
+ 25+ no longer bundles it)
- **Testing**: Vitest (colocated tests)
- **Components**: `packages/core/`
- **Storybook**: `apps/storybook/`
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index ae8a02a2f7..1a97e87a9e 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -312,9 +312,10 @@ export * from './MyComponent';
Every new component β€” and any change to an interactive one β€” must clear the
**[Accessibility Checklist](https://github.com/facebook/astryx/wiki/Accessibility-Checklist)**
(wiki) before review. The checklist lives on the wiki so accessibility
-experts can refine it without a code PR; reviewers block on it (see the
-blocking criteria in `.github/copilot-instructions.md`), and it is a hard
-requirement for a lab β†’ core promotion (see `packages/lab/README.md`).
+experts can refine it without a code PR; reviewers block on it (it is `A1`–`A16`
+on the [Component Audit Rubric](https://github.com/facebook/astryx/wiki/Component-Audit-Rubric)),
+and it is a hard requirement for a lab β†’ core promotion (see
+`packages/lab/README.md`).
Two repo-side rules worth restating here:
@@ -324,11 +325,12 @@ Two repo-side rules worth restating here:
WAI-ARIA APG patterns and are tested once; a bespoke reimplementation of
one is a review reject.
- CI is the enforcement layer, not a replacement for the checklist: the
- `pr-a11y` workflow runs an axe audit on every PR, a weekly workflow scans
- the full component surface, and the `useAnnounce` lint rule rejects
- hand-wired `aria-live` regions. axe only catches static, DOM-level issues β€”
- keyboard behavior, focus management, and announcement timing are exactly
- what the checklist and the component's unit tests cover.
+ `pr-a11y` job in `ci.yml` runs an axe audit on every PR that touches
+ components, a weekly workflow scans the full component surface, and the
+ `useAnnounce` lint rule rejects hand-wired `aria-live` regions. axe only
+ catches static, DOM-level issues β€” keyboard behavior, focus management, and
+ announcement timing are exactly what the checklist and the component's unit
+ tests cover.
## Working on the `astryx` CLI
@@ -542,11 +544,67 @@ Labels signal what's open for contribution:
For **pull requests**, use GitHub's native **Draft** state to signal "not ready to review/merge
yet" β€” open the PR as a draft and mark it ready for review when it's done.
+## What's expected of a change
+
+The bar β€” what a change has to carry, and what blocks β€” lives on the
+**[Component Audit Rubric](https://github.com/facebook/astryx/wiki/Component-Audit-Rubric)**.
+It is stated there once, so it cannot drift between this file, the reviewer
+instructions, and the wiki. Read it before you open a PR: it is the same page
+the reviewer applies to your change, and every check carries an id
+(`A8`, `T1`, `P2`…) so a finding always points back to the rule behind it.
+
+What you will find there:
+
+- **[The bright lines that block](https://github.com/facebook/astryx/wiki/Component-Audit-Rubric#the-checks)** β€”
+ hardcoded colors (`T1`, `T3`) Β· removing a themeable surface (`T2`) Β· raw CSS
+ where StyleX suffices (`T8`) or raw HTML where a primitive exists (`T29`) Β· a
+ broken accessible path (`A8`) and the accessibility bright lines (`A1`, `A3`,
+ `A14`) Β· hardcoded user-facing strings (`I1`, `I2`, `A16`) Β· public
+ API-convention violations (`P1`–`P10`) Β· dropped passthroughs and breaking
+ changes (`P2`, `P11`, `P12`) Β· a public-repo leak (`L15`) Β· a missing
+ changeset (`X20`). Severity is set by **what breaks if it ships**, not by how
+ likely the trigger is β€” the rubric states each rule, its exceptions, and how
+ it is judged.
+- **[The bar for your kind of change](https://github.com/facebook/astryx/wiki/Component-Audit-Rubric#reviewing-a-change)** β€”
+ a bug fix owes evidence it was broken before and is fixed now; a new feature
+ runs the automatable checks plus whatever the diff touches; a new component in
+ `core` gets a full audit; a new component in `lab` is deliberately lax, with
+ the audit as the **promotion gate** rather than an entry fee.
+- **[Which checks your diff earns](https://github.com/facebook/astryx/wiki/Component-Audit-Rubric#reviewing-a-change)** β€”
+ a trigger table from what you touched to the checks that fire, so a two-line
+ fix is not reviewed like a new component.
+- **[Recorded component grades](https://github.com/facebook/astryx/wiki/Component-Audit-Rubric#recording-an-audit)** β€”
+ audited components have a score and an open-blocker count in the wiki's
+ `component-scores.json` ledger, which is useful context on what shape a
+ component is in before you change it. Most components are unaudited, which
+ means "no evidence", not "fine". **No PR is gated on a score**, and you are
+ never asked to fix problems you inherited by touching a file.
+
+### Before you push
+
+These are this repo's mechanical gates. A reviewer stops at a red one rather
+than spending judgment on a PR that doesn't build.
+
+```bash
+pnpm lint:strict # CI severity, not the local warn tier β€” a warn-tier-green PR is not lint-clean
+pnpm test # the full suite, locally; CI is not your test runner
+pnpm build
+```
+
+`pnpm lint:strict` runs `pnpm check:repo` first, which covers `check:sync`,
+`check:package-boundaries`, `check:changesets`, `check:demo-media`,
+`check:executable-bits`, `check:cli-structure`, and `check:use-client` β€” so a
+green `lint:strict` also clears the changeset and `'use client'` gates.
+
+Also attach **before/after screenshots for any visual change**, and update the
+Storybook story for anything you added or altered.
+
## Pull Request Guidelines
1. Create a feature branch from `main`
2. Make your changes with tests
-3. Run `pnpm test` and `pnpm lint`
+3. Clear [Before you push](#before-you-push): `pnpm lint:strict`, `pnpm test`,
+ `pnpm build`
4. Add a changeset if needed: `pnpm changeset:new`
5. Open a PR with a clear description
6. **Leave "Allow edits by maintainers" enabled** (it's checked by default when
@@ -563,12 +621,21 @@ yet" β€” open the PR as a draft and mark it ready for review when it's done.
## Code Style
+The design-system rules β€” StyleX usage, semantic tokens, theming, API
+conventions, accessibility β€” are on the wiki and indexed from the
+[Component Audit Rubric](https://github.com/facebook/astryx/wiki/Component-Audit-Rubric).
+What this repo enforces mechanically:
+
- TypeScript strict mode
- Functional components that declare `ref` as a prop (React 19 β€” no
`forwardRef`; `@eslint-react/no-forward-ref` rejects it, and
`@astryx/require-ref-prop` requires `ref?: React.Ref<T>` on a publicly
exported props interface)
-- JSDoc comments for AI-assisted development
+- `'use client';` as the first statement of any file importing a React client
+ API β€” only comments and blank lines may precede it (`pnpm check:use-client`,
+ part of `pnpm check:repo`)
+- JSDoc comments for AI-assisted development, with `@example` fences left
+ untagged (plain ` ``` `) or Storybook autodocs won't render them
- Export types alongside components
## Troubleshooting