An open source design system that's fully customizable and agent ready
TypeScript
docs: consolidate agent guidance in AGENTS.md (#6033)
Cindy Zhang7409f9f2faaa
diff --git a/.github/ENGOWNERS b/.github/ENGOWNERSindex 561994f5b2..4af060e2b9 100644--- a/.github/ENGOWNERS+++ b/.github/ENGOWNERS@@ -1,19 +1,14 @@# Engineering owners for the Astryx repository#-# The Astryx engineering team. The Copilot reviewer reads this list to frame its-# review as assistance to the author's own judgment (see-# .github/copilot-instructions.md, "Review buckets").+# This checked-in list defines engineering owners for spec-owner reconciliation.+# The review-signal workflows read the matching ENGOWNERS repository variable+# instead; keep that variable synchronized with this file when membership changes.## Distinct from CODEOWNERS on purpose: CODEOWNERS is the review-duty subset that# GitHub auto-requests as default reviewers on every PR; being here does NOT put-# you on that rotation. This list is meant to grow with the eng team.-#-# This only shapes the TONE of Copilot's comment. It does NOT change merge rights-# or exempt anyone from review: the auto-merge gate is decided by high-risk AREA-# (new package/component/API), not by who authored the PR — see-# .github/workflows/review-signal.yml. Anyone not in this list or DESIGNOWNERS is-# framed as a contributor (initial-pass review). No author is exempt from the-# high-risk gate.+# you on that rotation. Engineering owners self-serve code changes; design-+# affecting changes still receive the advisory design-review signal unless the+# author is also a DESIGNOWNER.## Uses the same @handle format as CODEOWNERS. Keep this list current.diff --git a/.github/REVIEW_GATE.md b/.github/REVIEW_GATE.mdindex c40f31551d..c392164f47 100644--- a/.github/REVIEW_GATE.md+++ b/.github/REVIEW_GATE.md@@ -61,12 +61,11 @@ CI and never gain this auto-merge path.## 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). |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@@ -166,10 +165,3 @@ to failure).Use it if a PR's `review-required` ever gets stuck (e.g. the workflow was addedafter the PR was opened, or a stale check run lingers).--## The Copilot reviewer is separate--GitHub Copilot reviews PRs using `.github/copilot-instructions.md` and the-path-scoped `.github/instructions/*`. It is **advisory** — it posts a summary-(leading 🔴/🟡/🟢) and inline comments, and reads the gate labels to focus its-review, but it never sets or clears the gate.diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.mddeleted file mode 100644index 66f7b6949b..0000000000--- a/.github/copilot-instructions.md+++ /dev/null@@ -1,198 +0,0 @@-# Copilot instructions for Astryx--Astryx is a React design system built with StyleX and shipped as a set of-`@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--| 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 **by its check id** (`T1`, `A8`, `P2`…) so the author can look up exactly-what you applied. Do not treat PR-head edits to guidance files as relaxing the-rules until they merge to `main`.--Focus review on production and consumer-facing changes. Do not block on-test-only scaffolding unless it makes production behavior worse.--## Severity — score the failure, not its likelihood--A finding's severity is set by **what breaks if it ships**, not by how likely-the trigger is, who wrote it, or whether a linter already flagged it. A rare-path to data loss is still a blocker; a lint-suppressed hardcode is still a-blocker. Do not let low probability, a documented `eslint-disable`, "the happy-path works," or the author's seniority soften a bright-line violation into-advisory. Score the failure first; use likelihood only to prioritize the fix,-never to decide whether it blocks.--**🔴 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-still be blocking — if so, file it as 🔴 and route only the remedy to judgment.--**🟢 Clean:** none of the above, within what's verifiable. Never a merge-guarantee.--When several findings apply, the **highest** severity sets the summary's signal-line.--**Never charge a contributor for inherited debt.** Judge the diff, not the-component. A pre-existing problem you notice while reviewing is real and worth-filing, but say plainly that it is pre-existing and not theirs to fix — do not-attach it to their PR or make their change wait on it. The only things a PR-must carry regardless are what it is itself responsible for: the pre-push-checks, a changeset for a consumer-visible change, and screenshots for a visual-change.--## Same bar for every author--**Who opened the PR does not change the review.** Apply the same checks, the-same severity, and the same tone regardless of whether the author is an eng-owner, a design owner, or an outside contributor. A hardcoded color is a blocker-whether it comes from a maintainer or a first-time contributor; a broken-accessible path is a blocker either way. Do not soften a finding because of who-wrote it, and do not treat an owner's PR as pre-vetted.--What the bucket _does_ change is framing, not severity:--- **Contributor** → your review is the _initial pass_ that tells a code owner- where to focus.-- **Design owner** → same checks, framed for a designer: name what crosses into- engineering territory and needs an engineer's eye.-- **Eng owner** → assistant framing: the same findings, as input to the author's- own judgment.--> **The merge gate is a separate, workflow-driven mechanism.** The-> `review-signal` workflow applies two labels from the changed paths and 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_ = 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-design gate is not area-gated (a theme or template edit is exactly where design-review matters).--## Review Signal — put it at the top of every summary--Open the summary comment with one signal line so posture is scannable at a-glance:--- 🔴 **Blocking** — either a blocking finding from- [Blocking criteria](#severity--score-the-failure-not-its-likelihood)- is present, or a review-signal label is (`needs:code-review` and/or- `needs:design-review`). Name the specific trigger(s) — the rule violated and- the file, or the label. A content blocker counts even on a PR the workflow- left unlabeled (e.g. a hardcoded color in a low-risk docsite change).-- 🟡 **Maintainer judgment recommended** — no blocker, but something crosses- into human-judgment territory (see the per-file "engineering / human judgment"- notes). Advisory.-- 🟢 **No review blockers found** — clean within what the reviewer can verify.- Not a guarantee, and never merge permission.--State the reason on the same line, e.g. `🔴 Blocking — hardcoded color in-Thumbnail.tsx (colors must be a token or derived from one)` or `🔴 Blocking —-new component in packages/core (needs:code-review)`.--Also state the **triage line** at the top of the review, so the depth you chose-is legible and the breaking-change question is answered on every PR:--`Triage: bug fix · non-breaking · low blast radius → fast path · checks: §1 A4/A5, §7 C1`--The category × risk → path mechanic is in-[`instructions/packages.instructions.md`](./instructions/packages.instructions.md);-what each kind of change has to carry is in-[the rubric's bar per change type](https://github.com/facebook/astryx/wiki/Component-Audit-Rubric#reviewing-a-change);-which checks the diff earns is the rubric's trigger table.--## Summary comment vs. inline comments--- **Summary comment** carries the Review Signal, the triage line, the- verdict/recommendation, and cross-cutting judgment (design blast radius,- API-shape concerns, "needs human judgment" notes). One per review.-- **Inline comments** anchor to a specific line/hunk and are reserved for- concrete, localized findings: a convention violation on _this_ line, a risky- diff hunk, a specific fix. Keep them actionable and few — don't restate the- summary inline, and don't inline-comment a point that is really one- cross-cutting concern. If a finding isn't tied to a specific line, it belongs- in the summary.--## The review-signal labels are signals to you--A deterministic workflow (`.github/workflows/review-signal.yml`) applies two-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), 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 detection can't see (e.g. an- unintended behavior change) even on an _unlabeled_ PR.-- **You do not set or remove these labels.** The workflow applies them and an- entitled owner's approval clears them. One-way: the workflow informs you; you- never gate the merge.diff --git a/.github/instructions/blog.instructions.md b/.github/instructions/blog.instructions.mddeleted file mode 100644index c68a7654a4..0000000000--- a/.github/instructions/blog.instructions.md+++ /dev/null@@ -1,56 +0,0 @@-----applyTo: 'apps/docsite/src/content/blog/posts/**'------# Blog post review instructions--These are Astryx blog posts — **human-authored prose** (per the blog folder-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.--> **The rubric is the wiki page.** Read-> [Blog Review Rubric](https://github.com/facebook/astryx/wiki/Blog-Review-Rubric)-> 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 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.--## The accuracy gate — this is the part that needs the checkout--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.--- Documented commands, component names, props, CLI flags — do they exist **on- this branch**? Grep the CLI and the source rather than trusting the prose.- (Real catch: a post cited `astryx gap-report` after it was removed.)-- Numbers stated as fact — check against an in-repo source; flag figures that- need a citation and have none.-- Links resolve; code samples are correct.--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."--## Frontmatter and authors--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).--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.mddeleted file mode 100644index 22fa6f2dfa..0000000000--- a/.github/instructions/docsite.instructions.md+++ /dev/null@@ -1,125 +0,0 @@-----applyTo: 'apps/docsite/**'------# Docsite review instructions--The docsite (`apps/docsite/`) is a Next.js + StyleX app that documents Astryx.-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 question is **blast radius**:--- **Shared component / util** (e.g. `components/blog/BlogCard`, a shared layout)- → higher stakes: a change ripples across pages. Check every call site, and- that a new prop is **optional** (additive) so existing usages don't break.-- **Single page / one-off** → lower stakes, contained.--Then pick depth: **fast path** for a contained single-page or copy tweak (verify-the data rule + accuracy, approve); **standard path** for a shared-component or-layout/structural change (full data-rule + idiomatic + mobile review below).-State it briefly, e.g. `Triage: shared BlogCard, additive optional prop →-standard`.--## 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.** 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.--What that means when reading a diff — flag any of these as violations:--- A built theme imported directly in a page (e.g.- `import {fooTheme} from '@astryxdesign/theme-foo/built'`). Use `themeObjects`- from the generated `themeRegistry`.-- A hand-maintained array of component names. Use `componentRegistry`.-- A package-name switch like `if (pkg === '@astryxdesign/core')`. Let the- pipeline classify packages.-- Any hardcoded package/version/description duplicating what `packageRegistry`,- `blockRegistry`, `templateRegistry`, `docsRegistry`, or `showcaseRegistry`- already provides.--## Blog content--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-around it. When a change reaches for raw HTML/CSS where an Astryx primitive-exists, **nudge** toward the idiomatic path (a suggestion, not a hard block —-the docsite has real app-specific needs the component set won't always cover):--- Compose from Astryx components/primitives over raw elements — `VStack`/- `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.-- If the docsite genuinely needs something the component set lacks, that's a- signal worth surfacing: note it as a possible gap to file upstream, rather than- quietly forking a bespoke pattern in page code.--The bar is lighter than for `packages/**` — the docsite ships app code, not-published components — so frame these as "here's the idiomatic way" nudges, and-reserve firm flags for raw CSS or hardcoded tokens that have a clear Astryx-equivalent.--## Mobile-friendliness--Docsite pages must hold up on small screens. Review any layout/structural change-for how it degrades on mobile, and flag the common failure modes:--- **Side panels / multi-column layouts.** A `start`/`end` `LayoutPanel`, a- sidebar, or a two-pane split should collapse to an **inline / stacked**- treatment on small screens (panel becomes a top section, a drawer, or a- disclosure) — not sit as a squeezed column or push content off-screen. Flag a- new side panel or column split with no small-screen story.-- **Min-widths that don't shrink.** A fixed `width`/`minWidth` (or a- `min-content` grid track) that exceeds a phone viewport causes horizontal- overflow. Prefer `Grid` with `minChildWidth` (reflows automatically),- `max-width` over fixed `width`, and `minWidth: 0` on flex/grid children that- must be allowed to shrink (the classic fix for a child refusing to shrink- inside a flex row). Flag fixed widths on content that needs to fit narrow- screens.-- **Overflow & target sizes.** Wide content (tables, code blocks, long rows)- should scroll within its container, not blow out the page width. WCAG 2.2- [criterion 2.5.8](https://www.w3.org/WAI/WCAG22/Understanding/target-size-minimum.html)- (Level AA) requires targets to be at least 24×24 CSS px, or to satisfy its- spacing or other exceptions. The 44×44 CSS px threshold belongs to enhanced- [criterion 2.5.5](https://www.w3.org/WAI/WCAG22/Understanding/target-size-enhanced.html)- (Level AAA). Do not substitute the AAA threshold when evaluating or reporting- AA conformance.-- **Prefer CSS-first responsiveness.** The docsite leans on `useMediaQuery` /- `isMobile` JS in places; for _layout_ that CSS can express, prefer- `@container` queries, `Grid` `minChildWidth`, `flex-wrap`, and- `clamp()`/`min()`/`max()` over JS breakpoint branching (fewer hydration/SSR- mismatches, no layout flash). JS breakpoints are fine when the change is- genuinely structural (swapping a panel for a drawer), but flag JS used for what- a media/container query would handle.--If verifying a responsive claim needs a real viewport (does this actually reflow-at 375px?), say so and route it to human/preview verification rather than-asserting it works from the diff.--## Everything else--Docsite-only or CLI-docs-only changes are a light review overall — the-data-from-pipeline rule is the primary gate, plus the idiomatic-Astryx and-mobile checks above.diff --git a/.github/instructions/packages.instructions.md b/.github/instructions/packages.instructions.mddeleted file mode 100644index 80bb79b69c..0000000000--- a/.github/instructions/packages.instructions.md+++ /dev/null@@ -1,445 +0,0 @@-----applyTo: 'packages/**'------# Package review instructions--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--Before reviewing in depth, do a fast triage. It decides _how hard_ to look and-in what order, so effort lands where the risk is — and so the risk checks-(especially breaking changes) happen **up front**, not as an afterthought.--This is the triage the rubric points at; it is stated here and only here. The-**bar** each change type has to clear is in-[the rubric's bar per change type](https://github.com/facebook/astryx/wiki/Component-Audit-Rubric#reviewing-a-change),-and the **specific checks** a diff earns come from the rubric's trigger table.-Triage sets depth; those two set content.--**1. Categorize the PR** (by what it changes, not just the title prefix):--| Category | Signals |-| ----------------------- | ----------------------------------------------------------------------------------------- |-| **test / docs / chore** | only `*.test.tsx`, `*.doc.mjs`, stories, CI, build config — no shipped runtime/API change |-| **bug fix** | behavior change to existing code, no new public surface |-| **new API surface** | new component, new prop/variant, new exported hook/type, changed signature |-| **refactor / internal** | behavior-preserving restructure, shared-util migration |--**2. Assess risk — the two questions that gate everything:**--- **Is it a breaking change?** Scan for: a removed/renamed public export, prop,- or variant; a **new required** field on a public type/context/props; a changed- default; a changed function signature; or changed DOM/class/ARIA output- consumers may depend on. (The tell for an _accidental_ breaking change:- unrelated tests/examples/call sites had to be edited — see the silent-breaking- rule in Judgment.) A real breaking change must be **intentional and signalled- with a `[breaking]` changeset category**, and for a removed/renamed/changed- public API in a **published** package, a **codemod** under `astryx upgrade`.- Flag a breaking change with no `[breaking]` changeset (and no codemod where one- is warranted) as blocking. **`lab` is exempt**: it is private and never- published, so it has no consumers to migrate and is allowed to break freely —- never ask for a codemod for a lab-only change, and promoting a component out of- lab into core is additive from the published side.-- **What's the blast radius?** A core primitive many components build on, or a- shared type/context, is higher-stakes than a leaf component or a docsite tweak.--**3. Pick the review path** (depth follows category × risk):--- **Fast path** — docs/chore, or a small behavior-only bug fix with a- regression test, no breaking change, low blast radius. Verify accuracy (does- the referenced API exist / does the fix match the described bug), confirm the- test/changeset, and approve. Don't manufacture findings on a clean small PR.- **A standalone test PR is not automatically fast-path** — it still has to clear- the test-quality bar under "Calibrate to the PR type".-- **Standard path** — a normal bug fix or a contained prop/behavior change. Run- 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. 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** (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.-- **New component or module** — a net-new component directory, especially added- directly to `core` (skipped `lab`) — see Lifecycle & promotion.-- **New package** — a net-new `@astryxdesign/*` package. Always human-judgment.-- **Suspected regression** — an unintended behavior/logic change or a silent- breaking change to a shared type/context (see Judgment).--Anything else in this scope is low-risk for signal purposes. The one explicitly-low-risk _area_ inside `packages/**` is **`packages/themes/**`** (theme values);-a theme-only change does not trip the high-risk gate — though still apply the-design blast-radius check in Judgment, 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. 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** — the red→green evidence belongs **in the PR description**. Flag- a bug-fix PR that changes behavior without it and ask; a fix with no- regression test can silently break again.-- **Tests** — a test PR must earn its merge by testing the **contract, not the- implementation**. A passing test that exists is necessary but _not_ sufficient- to approve. The one-line test: _does this protect a promise a consumer relies- on, or does it just mirror the code?_ If it would break on a harmless refactor- yet survive a real bug, it's slop — request changes (kindly), naming the- specific assertions to cut or refocus.- - **✅ Worth testing** — the public behavioral contract (state transitions,- controlled/uncontrolled, callbacks fire with the right args, documented edge- cases: empty / boundary / overflow); each meaningful branch of a pure- function; the accessibility contract (roles, ARIA wiring, keyboard- interaction — first-class for a design system); and regression tests pinned- to a real reported bug (red → green).- - **🚫 Test slop — don't merge as-is** — asserting internal state, private- helpers, or DOM/class structure that isn't a public contract- (change-detector tests); snapshot dumps with no behavioral assertion;- re-testing React or the library ("useState updates", "prop passed through"- 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: does the documentation match the- code/API/behavior **on this branch**? When a claim is a matter of best practice- or judgment rather than fact, call it out for a maintainer rather than- asserting it's right or wrong.-- **New features / new components** — whether this is the _right way to expose- the functionality_ is a human judgment call. **Do not render a verdict on the- API design.** Run the mechanical, convention, and convergence checks, then- explicitly flag that maintainers should review the API surface (and that new- surface should be spec'd and vibe-tested).--## When to flag for engineering / human judgment--Many Astryx contributions come from designers building with an AI assistant.-The assistant is good at composition and convention, but some changes cross into-territory where **engineering review and human judgment are required** — and the-review should **say so explicitly** rather than quietly approving. If you find-yourself uncertain, that uncertainty is itself the signal: name it.--Add an explicit **"⚠️ Needs engineering / human judgment"** note when the change-involves any of:--- **New public API surface or an API-shape decision** — a new component, a new- prop/variant, or changing an existing prop's contract.-- **New runtime complexity** — effects, refs, observers- (`MutationObserver`/`ResizeObserver`/`IntersectionObserver`), imperative DOM- work, event listeners, timers, async coordination, or anything touching a hot- path. Designers should not land this class of change without an engineer- confirming it's the right mechanism.-- **Accessibility semantics** — ARIA roles/states, focus management, keyboard- interaction, live regions/announcements. Getting these subtly wrong is worse- than omitting them.-- **State, data flow, or lifecycle** — anything beyond presentational styling:- controlled/uncontrolled state, deriving state, memoization, render behavior.-- **Escape hatches / breaking the system** — raw CSS, non-token values,- `swizzle`d source, or overriding a system default; these need a documented- rationale an engineer signs off on.-- **Anything the change _asserts_ works but can't be verified from the diff** —- performance claims, cross-browser/RTL/theme behavior, SSR/hydration.--Pure presentational work well within the system — composing existing components,-using tokens and documented props, adding a story or realistic mock data — does-**not** need this flag. Reserve it for the cases above so it stays meaningful.--When you raise it, be specific: name _what_ in the diff needs the deeper look and-_why_ (e.g. "the `ResizeObserver` in `X.tsx` is a runtime-complexity + perf-decision — an engineer should confirm a container query wouldn't do"), so the-designer knows exactly what to hand off.--## API guidance--The 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`), 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 evidence-backed 9-phase process new components must follow.-- **[API Arbitration](https://github.com/facebook/astryx/wiki/API-Arbitration)** —- 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), 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:--- **Mirror the host's API shape, in and out.** A plugin should accept and return- the same shapes the host already uses. If `Table` accepts `idKey` (a key that- may be a string _or_ a getter, so callers avoid writing callbacks), a plugin- 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.-- **Semantic values first, arbitrary as the escape hatch.** When a plugin/prop- takes a visual value (color, status, tone), the first-class API is the- system's **semantic tokens** (`color: 'accent'` / `'success'`), not raw values.- Arbitrary values are fine as an escape hatch, but flag an API where the- raw/arbitrary form is the primary one.-- **Decide host-level vs plugin-level deliberately** — especially for- accessibility. If an option affects host semantics (e.g. a row `startFrom`- index that changes `aria-rowindex`), it likely belongs on the **host** so the- semantics are correct even when nothing visible renders.--### Hook stability & reuse of existing data--For hooks (plugins or otherwise), watch two things that bit real Table PRs:--- **Dependency-set stability.** A hook whose memoized output depends on a- frequently-changing value (e.g. the whole `data` array) will re-compute and- hand consumers a new reference on every update, destabilizing everything- downstream. Flag dependency sets that make the return value churn.-- **Don't re-derive what's already available.** If the host or the DOM already- exposes a value, read it instead of recomputing. Real case: a row-index plugin- looped over `data` to compute indices the table row already carried as- `aria-rowindex` — the loop (and the extra API surface) was avoidable.--## Design review--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--Astryx components and templates move through a staging lifecycle-([Component Lifecycle](https://github.com/facebook/astryx/wiki/Component-Lifecycle),-[Component Hardening Protocol](https://github.com/facebook/astryx/wiki/Component-Hardening-Protocol)).-The thing to catch is **new work that skips staging** — landing directly in its-final, publicly-visible home without being hardened first. Flag these as-high-attention (post a note rather than hard-blocking — this is advisory).--### New component added directly to `core` (skipped `lab`)--`@astryxdesign/lab` is the canary-only staging area (`private: true` +-`astryx.canaryOnly`) where new components develop and harden;-`@astryxdesign/core` ships to stable consumers. The expected path is-**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/`.** A-lab→core _promotion_ — a delete under `packages/lab/src/**` paired with the add-in core — is the healthy path; the concern is the _net-new_ component that was-never in lab. Ask the author to confirm it went through lab, or that it meets-the core bar lab does not guarantee (full keyboard + a11y, a theming story with-`themeProps`, spec compliance, a complete surface).--**Require a linked spec issue.** A new component's PR description must link to a-tracking issue that clearly ran the-[Component Specification Protocol](https://github.com/facebook/astryx/wiki/Component-Specification-Protocol).-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 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 — 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.-- **Publish posture is intentional** — `private: true` + `astryx.canaryOnly` for- 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.--### New template added already-visible (not `hidden`)--CLI templates/blocks are authored **hidden** and revealed only after they clear-the template design bar — see-[`templates.instructions.md`](./templates.instructions.md) for the full rule.-Flag a diff that adds a _new_ template/block whose `.doc.mjs` is not-`hidden: true`.--## Mechanical checklist--The design-system rules (StyleX-only, semantic tokens, no style-only wrappers,-the shared a11y primitives, `useLinkComponent()`) are numbered checks on the-[Component Audit Rubric](https://github.com/facebook/astryx/wiki/Component-Audit-Rubric);-what this repo enforces mechanically is in-[CONTRIBUTING → Code Style](../../CONTRIBUTING.md#code-style). What is specific-to a published package:--- **Full component surface.** A component under `packages/*/src/<Name>/` should- ship `<Name>.tsx`, a colocated `<Name>.test.tsx`, `<Name>.doc.mjs`, and an- `index.ts` export, plus a Storybook story at- `apps/storybook/stories/<Name>.stories.tsx` (stories are not colocated —- `apps/storybook/.storybook/main.ts` only discovers- `../stories/**/*.stories.@(js|jsx|mjs|ts|tsx)`). Flag missing pieces.-- **`export interface <Name>Props`** extending `BaseProps`, with types exported- alongside the component.-- **Never hand-edit the `"exports"` field in a package `package.json`.** It is- auto-generated from `src/` by `scripts/sync-exports.js` and committed on- `main`. Editing it by hand is a review-reject.-- **Docs in sync** — JSDoc file headers, `SYNC:` reminders, and `.doc.mjs`.- `@example` fences in JSDoc must be plain ` ``` ` (never language-tagged), or- Storybook autodocs won't render them.--## Judgment--Conventions passing is necessary, not sufficient. Weigh the **end-user-experience** of the change, not just whether it compiles and follows the rules.-When something would degrade real usage even though it passes the mechanical-checks, flag it.--- **Accessibility & alerting.** Scrutinize anything that announces, focuses, or- interrupts — live regions (`role="alert"`/`aria-live`), toasts, focus moves,- and notification triggers. Look for ways the mechanism could:- - **Double-fire** — re-run on re-render, fire once per item in a loop, or- re-announce unchanged content (a common `useEffect`-without-correct-deps- bug). Assistive tech will read it twice.- - **Interrupt or bury** — steal focus mid-interaction, stack overlapping- announcements, or clobber a more important message. `assertive` regions- especially should be rare and deliberate.- - **Worsen the experience it's trying to help** — e.g. announcing on every- keystroke, or moving focus in a way that traps or disorients.- Prefer announcing on a real state transition, debouncing/coalescing where the- 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**, 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,- network, non-React widgets) — those are fine; call out the ones that don't.-- **Overly complex behavior for a simple need.** Flag heavy runtime machinery- added where a simpler, declarative solution exists — the classic being a- `MutationObserver` / `ResizeObserver` / `IntersectionObserver`, imperative DOM- measurement, event listeners, or a `useEffect` sync loop introduced to achieve- something CSS (or a token/prop) already does. Watch for observers or- measurement in hot paths (per-row, per-keystroke, per-frame, large lists), and- for reintroducing work the platform handles natively- (`:hover`/`@media (hover: hover)`, `@container`, `:nth-child`,- `@starting-style`, `position-try`, `stylex.when.*`).-- **Silent breaking changes to shared types/context.** Adding a **required**- field to a shared type, context value, or component API is a breaking change- for every existing consumer — even when the PR's own feature doesn't need them- to change. The **tell**: unrelated tests, examples, or call sites had to be- updated just to satisfy the new field. Flag it and ask whether the field should- be **optional** (applied internally with a default) instead. (Real case: a new- required `aria-controls` id on a mobile-nav context forced edits to surfaces- that didn't otherwise need it.)-- **Unintended behavior/logic change.** Compare what the diff _actually changes_- against what the PR says it does. Flag behavior the author likely didn't mean- to touch — a value, default, condition, or output that changed as a side effect- of the intended edit and that the description never mentions. This is different- from scope contamination (unrelated _files_ bundled in); here the collateral- 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.**- Reason about **how it renders and where that could break**: does it alter- contrast, legibility, or emphasis? Does it change how a value _composites_- over other surfaces or in a different theme/mode? Does it shift layout,- spacing rhythm, or elevation order? Does it hold in both light and dark, and- against every surface the token appears on? The canonical trap: a color that- reads fine in isolation but was relied on to layer over other content, so the- change silently degrades every place it composites. (One real instance: a- theme edit that made a color opaque when other UI depended on it being- translucent — fine where the author looked, broken where they didn't.)- - **Changed defaults / conditionals** — a default prop value, a comparison- (`>=` vs `>`), an early-return, or a guard that changed as a byproduct.- - **Generated-output drift** — a regenerated theme CSS / registry / token file- whose diff contains changes beyond the intended one.- Surface these as a question — "this also changes X (was `a`, now `b`) — does- that hold everywhere it's used?" — so the author can confirm or revert.-- **Other smells.** State expressed by unmounting focusable elements (toggle- visibility so focus/a11y survive), unnecessary `useState` (prefer derived- values or refs, especially from interaction handlers), and excessive comments.--Behavioral or agent-facing changes should come with vibe-test evidence.diff --git a/.github/instructions/templates.instructions.md b/.github/instructions/templates.instructions.mddeleted file mode 100644index 025b8ad782..0000000000--- a/.github/instructions/templates.instructions.md+++ /dev/null@@ -1,92 +0,0 @@-----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.--> **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, plus the-> shared design and StyleX rules on the-> [Component Audit Rubric](https://github.com/facebook/astryx/wiki/Component-Audit-Rubric).--## The grading rubric--Grade every changed template against the-**[Template Grading Rubric](https://github.com/facebook/astryx/wiki/Contributing-Templates#template-grading-rubric)**,-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--Quick triage before grading. Two questions:--- **New template vs. edit to an existing one?** A _new_ template that lands- already-visible (its `.doc.mjs` isn't `hidden: true`) skipped hidden-staging —- flag it (see Lifecycle note) and hold it to the full B+ bar. An edit to an- 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`.--## Reporting--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.--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.-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 3950a3fa7a..af5d4d4b56 100644--- a/.github/workflows/review-signal.yml+++ b/.github/workflows/review-signal.yml@@ -30,9 +30,7 @@# design label is advisory and does not). Both are cleared when an entitled# owner approves (code → CODEOWNER; design → DESIGNOWNER# or CODEOWNER). Code detection is path-based and deterministic; design adds a-# content-based diff score (deterministic too — same diff, same score). The-# Copilot reviewer reads these labels to focus its review (see-# .github/copilot-instructions.md).+# content-based diff score (deterministic too — same diff, same score).## HARD GATE (code review only): this emits a "review-required" COMMIT STATUS.# When code review is needed it's set to `pending`, which blocks a required@@ -492,9 +490,9 @@ jobs:}}- // No explanatory comment is posted here on purpose. The label is the- // mechanical signal; the Copilot reviewer reads it and explains why- // review is needed with actual judgment — better than a static one.+ // No explanatory comment is posted here on purpose. The label and+ // status are the mechanical signals; reviews provide judgment+ // separately rather than through a static workflow comment.// --- The blocking gate: a "review-required" COMMIT STATUS. ---// We use a commit STATUS (not a check run) for two reasons:diff --git a/AGENTS.md b/AGENTS.mdindex 967974f1cb..193ee5970a 100644--- a/AGENTS.md+++ b/AGENTS.md@@ -4,6 +4,13 @@ Astryx is a public design-system repository. Never commit internal links,identifiers, service names, private operational instructions, or otherMeta-only context.+## Instruction surface++This `AGENTS.md` is the canonical, tool-agnostic instruction surface for the+repository. Add or change shared agent guidance here rather than duplicating it+in tool-specific instruction files. Put genuinely path-specific guidance in a+nested `AGENTS.md`.+## Start here- Product builders: use `astryx docs`, component `{Name}.doc.mjs` files, anddiff --git a/apps/docsite/src/content/blog/README.md b/apps/docsite/src/content/blog/README.mdindex 8c013aaaba..6afdf292af 100644--- a/apps/docsite/src/content/blog/README.md+++ b/apps/docsite/src/content/blog/README.md@@ -190,7 +190,5 @@ It's type-aware (a changelog `update`, an `engineering` deep-dive, and a`perspective` essay are judged by different profiles), gates on accuracy(verifiable claims — commands, APIs, numbers — are checked against the codebase,and a confirmed error blocks publish), and checks substance, efficiency, craft,-and voice **without homogenizing your voice**. The same rubric powers the Copilot-reviewer at `.github/instructions/blog.instructions.md`, so a blog-post PR gets-the check automatically. Reading it before you write is the fastest way to land-an A.+and voice **without homogenizing your voice**. Reading it before you write is+the fastest way to land an A.