History / Contributing Templates

Template rubric 1.3 — stop scoring slug length The 16-character page slug ceiling added in 1.1 was the wrong call, for two reasons the same vibe test already supplied. The name axis is inert. Ablating name entirely changed 0 of 36 battery results, and a full rename of all 51 page templates left 35 of 36 rankings identical. A ceiling that pushes contributors to rename buys essentially nothing on natural-language retrieval. And every slug past the line belongs to a family. All seven are dashboard-* or documentation-*, where the shared prefix groups the family in template --list. That legibility is worth more than the substring reach a long slug forfeits. Renaming is also a genuine breaking change: astryx template resolves by exact match on the directory name, there is no alias, deprecation or redirect mechanism anywhere, and the codemod system cannot cover it — a copied page.tsx holds no reference to its own slug, and upgrade selects transforms by @astryxdesign/core version while templates ship in the CLI. The rubric should not push anyone toward that for a signal that does not move. §5c no longer scores length, so a long slug can earn the naming point. Length survives as guidance under Naming a Template. Point values, category maxima and the 100-point total are unchanged. Co-authored-by: Cursor <cursoragent@cursor.com>

Use American spelling in the description lens table Co-authored-by: Cursor <cursoragent@cursor.com>

Template rubric 1.2 — describe templates by structure, not by their sample data Review feedback on the description convention: the differentiator was leaning on content-type nouns, and data is interchangeable. Swap customers for invoices and it is the same template, so the data cannot be what distinguishes one from another — and a fixture-led description locks the template to the sample it ships with. Someone building an invoice or a job record needs detail-page exactly and matched none of its order vocabulary. Writing the description now asks for four structural lenses — layout, container, data shape, behavior — with domain nouns demoted to interchangeable examples, and adds the sibling comparison as the most discriminating sentence usually available. Worked example carries all three versions of detail-page, including the noun-led wrong turn, since that is the easy mistake to make. Also documents that -able adjectives and verb forms never match each other under the stemmer: resizable never answers a query for resize. Minor bump rather than patch because §5b now caps a description at 2 when sample-data nouns are doing the separating, which can change a score. Point values, category maxima and the 100-point total are unchanged. Measured over the same 36-query battery: structure-led descriptions scored 32/36 top-1 against 23/36 noun-led. Co-authored-by: Cursor <cursoragent@cursor.com>

Template rubric 1.1 — score the naming and description conventions Doc Metadata (10) now splits into fields present and accurate (6), description convention (3), and naming convention (1). Previously all 10 graded field presence and naming was an explicit non-scored soft signal, so a template could score 10/10 on a three-word description like "Data table with actions" — the single worst thing you can do for retrieval. The weighting follows what each is measured to be worth. A 36-query field ablation found `description` the only metadata field whose removal degrades retrieval (top-1 15->9, top-3 25->18), while the name axis decided 0 of 36 queries and removing auto-extracted keywords or category actually improved precision. Also adds to Naming a Template: the 16-character page-slug ceiling (build only substring-matches a name when the shorter side covers >=50% of the longer, so a 16-char slug needs an 8-letter query word), and the four-slot description shape with the five rules the scorer forces. Category set, category maxima and the 100-point total are unchanged, so existing ledger rows stay schema-valid. Doc Metadata subscores are not comparable across 1 and 1.1; per-row rubricVersion is left alone so existing audits keep their v1 provenance. Source: internal/vibe-tests/template-naming-test/PLAN.md Co-authored-by: Cursor <cursoragent@cursor.com>

Contributing Templates: add template naming convention Name templates for the component/pattern archetype (data-table, dashboard), keep domain nouns and synonyms in category/description, and drop dead-weight -page/-view suffixes. Documents the slug/metadata split that build's search rewards, with a rationale pointer to the API Arbitration that chose it. Added as guidance plus an unscored note in the Doc Metadata rubric category — no rubric weights change, so no version bump.

Add template rubric version history

Document template audit recording workflow

Templates: images are checked-in assets referenced root-relative, not CDN URLs

Correct the CLI asset paths: templates and docs live under packages/cli/assets

Correct the .doc.mjs type import: @astryxdesign/cli/authoring, not a relative docs-types path

Contributing-Templates: remove internal-only tool references The 'How to find and use an image' section previously referenced an internal-only CLI (`meta assets.group list`, `meta assets.file list`) that doesn't exist for external contributors. Replaced with a pointer to the Template-Assets manifest page, and dropped the internal-only extension-check snippet (all astryx images are .png).

Add Template-Assets manifest page New browsable listing of every image and video in the astryx asset set, organized by style/category. Meant as a stopgap reference until the CLI grows an assets listing command. Also updates Contributing-Templates > What's available to link out to the new page and refresh the count (~80 -> ~140 images plus one video).

Fix asset browse URL to lookaside form Step 1's "browse" link should be a lookaside URL like the other asset URLs, not the internalfb set-browser UI. Restore the original lookaside.facebook.com/assets/{set}/{IMAGE_NAME} form with the set renamed xds_oss → astryx, keeping it consistent with the permanent lookaside image URLs in Step 2. Co-authored-by: Cursor <cursoragent@cursor.com>

Update wiki for XDS → Astryx rename Refresh outdated references across all wiki articles to match the current codebase after the XDS → Astryx rebrand: - Package scope @xds/* → @astryxdesign/* (theme-default/theme-daily → theme-neutral; ESLint rule → @astryx/*) - CLI command xds → astryx; fix stale commands (build-theme → theme build, agent-docs folded into init) - CSS/layers: xds.css → astryx.css, @layer xds → @layer astryx-base, @layer xds.theme → @layer astryx-theme - Config key "xds" → "astryx"; env var XDS_THEME → ASTRYX_THEME - Repo facebookexperimental/xds → facebook/astryx; versions 0.0.15 → 0.1.1 - Swizzle output dir components/xds/ → components/astryx/ - API rename xdsThemeProps → themeProps (verified against source) - Asset set xds_oss → astryx (browse via internalfb.com/assets/set/astryx) - Correct component-purity docs: components are unprefixed (no "Astryx" prefix) Co-authored-by: Cursor <cursoragent@cursor.com>

Templates rubric: Shell category uses AppShell as root Carve out the `Shell -` category as the exception to the content-only rule: Shell templates must use AppShell as their root (with global TopNav/SideNav), while every other category stays content-only with a Layout (or Center) root. Updated the rule, the page-root table, the background notes, and the Layout & Structure scoring criteria. Co-authored-by: Cursor <cursoragent@cursor.com>

Astryx design system wiki Documentation for the Astryx design system: API conventions, component authoring, theming, RSC utilities, Night Watch automation, and contribution guides.