An open source design system that's fully customizable and agent ready
schema_version: 1 template_version: 1 kind: architecture id: architecture:template-authoring authority: draft archive_reason: null superseded_by: null approved_by: null approved_at: null owners: [josephfarina, cixzhang] applies_to: [ packages/cli/assets/templates/, packages/cli/authoring/doctypes/template/, packages/cli/foundation/discovery/template-adapter.mjs, packages/cli/foundation/config/project.mjs, packages/cli/api/template/, apps/docsite/src/components/templateComponents.ts, apps/docsite/scripts/generate-data.mjs, scripts/sync-templates.js, ] verified_by: [ packages/cli/authoring/doctypes/template/parse.test.mjs, packages/cli/foundation/discovery/template-adapter.test.mjs, packages/cli/foundation/config/project.test.mjs, packages/cli/api/init/init.test.mjs, packages/cli/api/template/template.test.mjs, packages/cli/api/template/template-integration.test.mjs, packages/cli/api/template/template-suffix.test.mjs, packages/cli/clients/cli/e2e-smoke.test.mjs, apps/docsite/src/tests/data-extraction.test.ts, ]
deciding_specs: [spec:AST-017/DEC-2]
Template authoring architecture
Purpose
Astryx templates are copyable starting points. Page templates scaffold complete content surfaces. Block templates provide focused patterns and component examples. This record owns their source shapes, catalog identity, validation boundary, consumer projections, and copy semantics.
It does not copy contributor instructions or internal audit-publication workflow. The shipped template-quality guide owns the public grading rubric, and the public contributor guide links to that source.
System model
Shipped state
Astryx ships two template kinds. A showcase is a role held by a block, not a third kind.
| Kind or role | Current source shape | Current identity and use |
|---|---|---|
| Built-in page | pages/<slug>/page.tsx plus template.doc.mjs |
The directory slug is the CLI id. The page is a complete route starting point. |
| Built-in block | Paired <Name>.tsx and <Name>.doc.mjs under blocks/ |
The file stem is the CLI id. The block is a focused example or reusable pattern. |
| External block | The same paired files under a package declared through astryx.blocks |
The package, type, and file stem identify the entry. |
| Integration template | Paired <id>.tsx and <id>.template.* or legacy <id>.doc.* under a configured integration templates root |
The package, type, and root-relative id identify the entry. Nested ids are supported. |
| Primary showcase | A block with isShowcase: true |
Supplies the hero example for its exampleFor target. |
| Secondary showcase | A block naming targets in alsoShowcaseFor |
Reuses the same source as the hero example for additional component or hook pages. |
| Additional example | A block naming targets in alsoExampleFor |
Reuses the same source in additional Examples sections. |
name and displayName are human-facing labels, not catalog identity. They may
repeat. The resolvable identity is (package, type, id); callers narrow an id that
exists across packages or kinds.
The shipped loaders do not yet share one validation boundary:
- Built-in pages load metadata directly and default some absent values.
- Built-in and external blocks require a paired source file but otherwise load metadata directly and default some absent values.
- Integration templates pass through
parseTemplate()and report missing source, load, or envelope errors.
The shipped consumers also collect different sets:
discoverAll()supplies the template API, search, and layout.Project.templates()independently re-collects integration templates for project diagnostics and deduplication.listTemplates()returns every built-in page directory without reading metadata; programmaticinituses that list when applying a named starter page.- The sandbox and docsite generate metadata/source registries independently.
- The docsite overview reads generated metadata, while live page previews depend on
the separate hand-maintained lazy map in
templateComponents.ts.
Copying emits source into the adopting project. It does not keep a live relationship to the catalog, and later template releases do not rewrite copied projects.
Normalized catalog contract
Before this record can become current, every source must normalize into one catalog
entry and pass one validation boundary. That boundary uses these requirements:
| Scope | Required | Optional or conditional |
|---|---|---|
| Every entry | id, package, type, name, displayName, non-empty description, explicit isReady, and an existing source file |
keywords; source-specific provenance and diagnostics |
| Page | Everything above; category when eligible for the overview |
scaffold, isHiddenFromOverview; a hidden special-purpose page may omit category |
| Block | Everything above plus exampleFor, positive aspectRatio, and complete componentsUsed |
scale, isShowcase, alsoExampleFor, alsoShowcaseFor |
| Primary showcase | Block requirements plus isShowcase: true; at most one resolved primary showcase per (package, target) |
The same block may serve additional targets through alsoShowcaseFor |
| Additional placement | A valid block and a valid target named by alsoExampleFor or alsoShowcaseFor |
Placement does not create another template identity |
Page and block metadata may be authored with richer first-party types or a narrower integration envelope. Source adapters translate those source-specific shapes into the common entry. A projection is a filtered view of that catalog for one consumer; it does not discover another membership list.
The converged projections are:
- CLI template and search surfaces select all eligible pages and blocks.
- Layout selects blocks only.
initselects every named built-in page.- The docsite overview selects ready pages not marked
scaffoldorisHiddenFromOverview. - Docsite live previews select the same eligible page entries and import their catalog source.
- Component and hook docs select ordinary examples, primary showcases, and explicit secondary placements from block metadata.
- Project diagnostics consume the same catalog errors instead of re-collecting integration membership.
Invalid required data produces a diagnostic. It is not repaired with an implicit default or skipped silently. TypeScript checking remains an additional first-party authoring check; it does not replace runtime catalog validation.
Boundaries and invariants
- INV1 — Pages and blocks are the only template kinds. Showcase and additional example placements are block roles, not separate source kinds or identities.
- INV2 — Identity is separate from labels.
(package, type, id)resolves a template.nameanddisplayNamemay change or repeat without becoming identity. - INV3 — Role requirements are explicit. Every accepted entry satisfies the normalized field matrix above. Source pairing and projection metadata are validated before a consumer receives the entry.
- INV4 — Source-specific authoring converges at one boundary. Built-in, external, and integration sources may have different adapters, but none bypasses normalized validation.
- INV5 — One catalog owns membership. CLI, search, layout, project,
init, sandbox, and docsite differences come from declared projections, not independent filesystem scans or hand-maintained membership lists. - INV6 — Preview source is shipped source. A page preview imports the same
page.tsxthe catalog serves. A generated lazy-loading map may implement the projection, but it does not decide membership. - INV7 — Pages remain host-composable. A normal page owns page content, not the
host application's global chrome. A page in the explicit
Shell -category may ownAppShelland global navigation because demonstrating that chrome is its purpose. The contributor guide owns the exact root-component recipe. - INV8 — Copying is a self-contained snapshot. The emitted source belongs to the
adopting project. Repository-only demo assets and demo-content elements are
replaced with generic placeholders, and docs-only presentation wrappers are
removed, during copy;
template copyand the docsite's shadcn Install item are copies.template showreturns the same source a copy writes. Other example source handed out without a copy replaces only demo-content elements and removes docs-only presentation wrappers. Live previews render the originals. Later catalog updates do not mutate copied projects. - INV9 — Catalog values may evolve. Template ids, labels, metadata, categories,
example data, and starter source are mutable catalog data under
spec:AST-017/DEC-2. - INV10 — The operation surrounding the catalog remains contractual. The
templatecommand, supported options, exit behavior, and machine-readable response schema remain governed by the CLI contract. - INV11 — Shared behavior requires a shared contract. Similar templates do not implicitly form a family. Shared states, interactions, responsive behavior, and constraints require an approved family, design, or system record.
- INV12 — Evidence is revision-specific. A rubric score identifies the exact template commit and rubric version it measured. It can support review but cannot grant Design approval, implementation approval, or current-record authority.
Delegated authority
This record does not absorb adjacent facts:
- The shipped
authoring/building-blocks/templates/write-good-templatesguides own the public grading rules, rubric version, grade bands, categories, weights, and agent workflow. The public Contributing Templates guide owns contributor workflow and the score-ledger publication procedure, and links to the shipped rubric instead of copying it. Its current statement that renaming is breaking is superseded byspec:AST-017/DEC-2. design:template-compositionowns shared human visual, hierarchy, responsive, and interaction intent. It remains a candidate record while its authority isdraft.- Component, module, and family records own the behavior of components composed by a template. A good rubric score does not override those contracts.
spec:AST-017/DEC-2owns the compatibility split between mutable catalog values and the stable surrounding CLI operation.TemplateDoctypes andparseTemplate()implement the authoring envelope. They must converge on this record's field requirements; neither silently becomes policy when the two disagree.
Change coupling
- A template source or metadata change re-runs its source adapter, normalized validation, and every affected projection check.
- A change to required metadata or a template role updates the TypeScript type, runtime parser, contributor field tables, generators, API response, and active records together. A material shape change follows the repository's schema-version and migration rule.
- A page addition, removal, or projection-flag change updates generated sandbox and docsite data and proves live-preview coverage for every admitted page.
- A showcase or example-placement change validates one resolved primary showcase per target and regenerates the showcase/example registries.
- A visual or interaction change follows applicable current design, family, and component records. One review does not substitute for another.
- A rubric scoring change updates the shipped template-quality guide's version and score-ledger contract together. It changes this architecture only when it moves a system boundary.
- A proposal to share behavior across several templates updates the relevant family, design, or system record rather than inferring a contract from similarity.
Owning code
packages/cli/assets/docs/tree/template-quality.doc.mjsand its child guides — the canonical public rubric and agent grading workflow.scripts/template-score-ledger.mjs— rubric score persistence; imports the canonical version, grade bands, categories, and weights from the guide.packages/cli/assets/templates/— built-in page and block source plus metadata.packages/cli/authoring/doctypes/template/— first-party authoring types and the runtime template envelope.packages/cli/foundation/discovery/template-adapter.mjs— current source loaders, normalization, projections, and shared template IO.replaceDemoMediaintemplate-adapter.mjs— the INV8 replacement step that copy and displayed code share. It replaces/template-assets/media URLs. In motion and gesture examples, where a real Astryx component wraps docs-only contents, such as<Card><PlayingCardContents /></Card>, it also replaces each demo-content element with a generic placeholder and keeps the outer component. A demo-content element is an element imported from the one repository-only demo-content module; the step drops that import. The module and the import rule are internal mechanism, not a public contract (architecture:knowledge-contracts/INV18);spec:AST-028FR13 states the outcome.template copy,template show, and the docsite's shadcn Install item run both passes; the copy receipt and thetemplate showresponse report the element count asdemoContentReplaced. The docsite Code tab, Open in Playground, the Sandbox code view, the docsite MCP server'sget(), andastryx component <Name> --showcaserun only the element pass, so they keep their fixture media (spec:AST-033FR23). Implementation gap: the demo-content module, the element pass, anddemoContentReplacedare not built, and the shadcn Install item runs neither pass.packages/cli/foundation/config/project.mjs— project diagnostics and current integration-template re-collection.packages/cli/api/template/— list, show, skeleton, and copy operations.scripts/sync-templates.js— current sandbox registries and preview routes.apps/docsite/scripts/generate-data.mjs— current docsite page, block, example, and showcase registries.apps/docsite/src/components/templateComponents.ts— current hand-maintained page preview loader; its independent membership is a migration gap.
Deciding specs
spec:AST-017/DEC-2— template identity, metadata, and starter source are mutable catalog data; the surrounding CLI operation remains contractual.
Verification
| Scope | Current evidence | Missing before current |
|---|---|---|
| Source shapes and integration parsing | parse.test.mjs, template-suffix.test.mjs, template-integration.test.mjs |
One corpus check that runs every shipped page and block through the normalized boundary |
| Catalog membership and diagnostics | template-adapter.test.mjs, project.test.mjs |
One catalog implementation; no duplicate collection; every invalid source reported consistently |
init projection |
init.test.mjs |
Selection of every named built-in page from the catalog instead of a directory scan |
| Docsite and sandbox projections | data-extraction.test.ts, generated registry checks |
Membership parity and live-preview coverage derived from catalog metadata |
| Copy boundary | template.test.mjs, template-suffix.test.mjs |
Mutation coverage for preview-only asset removal and snapshot independence |
| Demo-content replacement | None; not built | Copy, template show, shadcn Install item, Code-tab, Open in Playground, Sandbox code-view, MCP get(), and --showcase output contain no demo-content element or demo-content import; copy receipt and template show count the elements; the shadcn Install item contains no /template-assets/ reference; the surfaces that only hand out source keep their fixture media; a live preview renders the original |
| Rubric evidence | Versioned scorecards carrying commit and rubricVersion |
None for architecture; scores remain audit evidence rather than authority |
Shipped-catalog audit
An exact-source audit at 067b176 found:
- 53 page source/metadata pairs. All pass the current
parseTemplate()boundary. Forty are ready, non-scaffold pages visible in the overview projection. One of those,work-item-detail, lacks a live-preview loader. - All forty overview-visible pages preserve the host-chrome boundary. The only
source-shape exception is the unfinished
messaging-shell;blankis an intentional minimal scaffold rather than a gallery page. - 644 block source/metadata pairs with no orphaned source or metadata files. Every
block declares
type,name,displayName,isReady,exampleFor, positiveaspectRatio, and non-emptycomponentsUsed. The audit did not prove that every array names every component imported by its source; that completeness still needs an executable check. - 158 primary showcase blocks resolve to 158 distinct primary targets. Fourteen blocks add secondary showcase targets and twenty add secondary example targets; the 174 expanded showcase targets have no collisions.
- Thirty-five primary showcases omit
description. Current built-in discovery turns that into an empty string, whileparseTemplate()rejects it. This is a metadata backfill gap, not an intentional showcase exception. - Core block file-stem ids are unique. Three pairs share human-facing
namevalues; that is allowed by INV2 and creates no CLI ambiguity. - The TypeScript type, runtime parser, and contributor field tables disagree about
whether
displayName,description,isReady,exampleFor,aspectRatio, andcomponentsUsedare required. The parser also acceptspreview, which the TypeScript type does not declare. They must be aligned before this record becomescurrent.
Decision log
Catalog convergence direction — 2026-09-05
One validated catalog owns template membership. Source-specific authoring shapes may
remain different, but each source normalizes through the same validation boundary.
CLI, init, project, sandbox, and docsite behavior become explicit metadata-driven
projections. Parallel collectors and hand-maintained membership are migration gaps.
Corpus audit — 2026-09-09
Every shipped page and block was enumerated at 067b176. The audit added the role
matrix above and identified enforcement, metadata, and preview-registration gaps.
Those gaps block promotion to current; they do not make the inventory disappear or
turn existing audit scores into architecture authority.
Open questions
- OQ1 — Approval routing. Which repository owners must approve a change that
crosses both template visual intent and authoring/runtime behavior before this
record can become
current? - OQ2 — Rubric home. Should the versioned grading rubric move into its own repository record while the wiki becomes a contributor-facing reference, or should the wiki remain its authority?