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.mdindex 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`; excludestests/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 samename 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 onediff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.mdindex 748baf7e90..66f7b6949b 100644--- a/.github/copilot-instructions.md+++ b/.github/copilot-instructions.md@@ -1,63 +1,30 @@# Copilot instructions for AstryxAstryx 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 ontest-only scaffolding unless it makes production behavior worse.-## Blocking criteria β score the failure, not its likelihood+## Severity β score the failure, not its likelihoodA finding's severity is set by **what breaks if it ships**, not by how likelythe 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 intoadvisory. 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 signalline.+**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 brokenaccessible path is a blocker either way. Do not soften a finding because of whowrote 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 aglance:- π΄ **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 andthe 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 inThumbnail.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 youA 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 anentitled owner's approval clears them. One-way: the workflow informs you; younever gate the merge.diff --git a/.github/instructions/blog.instructions.md b/.github/instructions/blog.instructions.mdindex 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 thatneed 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.mdindex 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 instructionsThe 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, andthat 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 (verifythe data rule + accuracy, approve); **standard path** for a shared-component orlayout/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 thepipeline 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, notaround it. When a change reaches for raw HTML/CSS where an Astryx primitiveexists, **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 asignal worth surfacing: note it as a possible gap to file upstream, rather thanquietly forking a bespoke pattern in page code.The bar is lighter than for `packages/**` β the docsite ships app code, notpublished 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 Astryxequivalent.## 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. Interactivetargets 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/SSRmismatches, 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 β thedata-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.mdindex 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 andin 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 checksconsumers may depend on. (The tell for an _accidental_ breaking change:unrelated tests/examples/call sites had to be edited β see the silent-breakingrule 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 ashared 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 checksthe referenced API exist / does the fix match the described bug), confirm thetest/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 addeddirectly 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 silentbreaking 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 theimplementation**. 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 edgecases: 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 exposethe 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 judgmentMany Astryx contributions come from designers building with an AI assistant.The assistant is good at composition and convention, but some changes cross intoterritory 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 changeinvolves 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 DOMwork, 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, keyboardinteraction, live regions/announcements. Getting these subtly wrong is worsethan omitting them.@@ -194,64 +185,47 @@ _why_ (e.g. "the `ResizeObserver` in `X.tsx` is a runtime-complexity + perfdecision β an engineer should confirm a container query wouldn't do"), so thedesigner 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 returnthe 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/proptakes a visual value (color, status, tone), the first-class API is thesystem'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 foraccessibility. 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 afrequently-changing value (e.g. the whole `data` array) will re-compute andhand 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 alreadyexposes a value, read it instead of recomputing. Real case: a row-index pluginlooped 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 atracking 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>/` shouldship `<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 isauto-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), orStorybook 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 DOMmeasurement, event listeners, or a `useEffect` sync loop introduced to achievesomething 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 changefor every existing consumer β even when the PR's own feature doesn't need themto 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 newrequired `aria-controls` id on a mobile-nav context forced edits to surfacesthat 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 filewhose 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 (togglevisibility so focus/a11y survive), unnecessary `useState` (prefer derivedvalues or refs, especially from interaction handlers), and excessive comments.diff --git a/.github/instructions/templates.instructions.md b/.github/instructions/templates.instructions.mdindex 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 rubricGrade 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.ymlindex 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 (seediff --git a/CLAUDE.md b/CLAUDE.mdindex 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.mdindex 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 ofone 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/mergeyet" β 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 Guidelines1. 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 description6. **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 publiclyexported 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