Skip to content

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

TypeScript

docs: expand package Copilot review (PR-type calibration, convergence, design, lifecycle, complexity) (#3784)

Cindy Zhang1b1f2c2427ed
diff --git a/.github/instructions/packages.instructions.md b/.github/instructions/packages.instructions.md
index 60d3ad6c3c..3519b99955 100644
--- a/.github/instructions/packages.instructions.md
+++ b/.github/instructions/packages.instructions.md
@@ -7,6 +7,27 @@ applyTo: "packages/**"
These paths ship as published `@astryxdesign/*` packages, so review them
against Astryx's API guidance and component review protocol.
+## Calibrate to the PR type
+
+Weight the review by what the PR is trying to do:
+
+- **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.
+- **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.
+- **New features / new components** — whether this is the *right way to expose
+ the functionality* is a human judgment call. **Do not render a verdict on the
+ API design here.** You may still run the mechanical, convention, and
+ convergence checks below, but explicitly **flag that maintainers should review
+ the API surface carefully** (and that new surface should be spec'd and
+ vibe-tested) rather than approving the design yourself.
+
## API guidance (the review protocol)
The authoritative rules live in the Contributing wiki — apply them and cite the
@@ -34,6 +55,138 @@ specific rule when something conflicts:
- **[API Arbitration](https://github.com/facebook/astryx/wiki/API-Arbitration)** —
how API design questions get resolved.
+### 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)).
+
+## 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.
+
+## 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/`.**
+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)
+
+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.
+
+### 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.
+
## Mechanical checklist
- **Full component surface.** A component under `packages/*/src/<Name>/` should
@@ -87,6 +240,18 @@ checks, flag it.
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) 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.
- **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.