An open source design system that's fully customizable and agent ready
TypeScript
docs: define template authoring architecture (#5942)
Joeyd8f5d2761d4b
diff --git a/docs/architecture/template-authoring.md b/docs/architecture/template-authoring.mdnew file mode 100644index 0000000000..bffc302d8f--- /dev/null+++ b/docs/architecture/template-authoring.md@@ -0,0 +1,297 @@+---+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, visual-design guidance, or the grading+rubric. Those facts have separate owners under [Delegated authority](#delegated-authority).++## 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;+ programmatic `init` uses 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 | 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.+- `init` selects every named built-in page.+- The docsite overview selects ready pages not marked `scaffold` or+ `isHiddenFromOverview`.+- 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. `name` and `displayName` may 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.tsx` the 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+ own `AppShell` and 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 are replaced during copy so the+ scaffold does not depend on Astryx preview hosting. 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+ `template` command, 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 public [Contributing Templates](https://github.com/facebook/astryx/wiki/Contributing-Templates)+ guide owns contributor workflow, naming and description guidance, implementation+ recipes, grading rules, rubric versioning, and the score-ledger procedure. Its+ current statement that renaming is breaking is superseded by+ `spec:AST-017/DEC-2`.+- `design:template-composition` owns shared human visual, hierarchy, responsive, and+ interaction intent. It remains a candidate record while its authority is `draft`.+- 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-2` owns the compatibility split between mutable catalog values+ and the stable surrounding CLI operation.+- `TemplateDoc` types and `parseTemplate()` 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 increments the rubric version and updates the score-ledger+ contract. 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/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.+- `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 |+| 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`; `blank` is 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`, positive+ `aspectRatio`, and non-empty `componentsUsed`. 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, while `parseTemplate()` 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 `name` values;+ 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`, and+ `componentsUsed` are required. The parser also accepts `preview`, which the+ TypeScript type does not declare. They must be aligned before this record becomes+ `current`.++## Decision log++### Recovered draft — 2026-09-02++This record recovers the architecture half of [#5915](https://github.com/facebook/astryx/pull/5915)+without copying the rubric or changing `design:template-composition`. It replaces+that draft's proposed stable-slug invariant with the accepted+`spec:AST-017/DEC-2` boundary.++### 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?