An open source design system that's fully customizable and agent ready
TypeScript
docs: add Copilot template reviewer (template grading rubric) (#3783)
Cindy Zhang7aef8d3b0876
diff --git a/.github/instructions/templates.instructions.md b/.github/instructions/templates.instructions.mdnew file mode 100644index 0000000000..da4330f6d6--- /dev/null+++ b/.github/instructions/templates.instructions.md@@ -0,0 +1,92 @@+---+applyTo: "packages/cli/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 (forwardRef,+> 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).++Grade every changed template against the+**[Template Grading Rubric](https://github.com/facebook/astryx/wiki/Contributing-Templates#template-grading-rubric)**+in [Contributing Templates](https://github.com/facebook/astryx/wiki/Contributing-Templates).+**Every template in the gallery should score B (75) or above.** Flag anything+that would land below B; post findings as a scorecard (advisory — comment, don't+hard-block).++## 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)** — images only from the astryx CDN via the permanent+ lookaside URL (`https://lookaside.facebook.com/assets/astryx/<asset>.png`)+ with an asset-name comment. Flag external URLs (unsplash/placehold/picsum),+ checked-in image files, data URIs, and expiring signed `scontent…fbcdn.net`+ URLs.+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.++## 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.++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.++## 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+[Component Lifecycle](https://github.com/facebook/astryx/wiki/Component-Lifecycle#promotion-gates).