Skip to content

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

TypeScript

spec(template-authoring): motion and gesture examples swap docs-only showcase elements for generic ones when distributed (#9419)

Cindy Zhang3f19de5d3276
diff --git a/docs/architecture/template-authoring.md b/docs/architecture/template-authoring.md
index 86317b9391..ad20fbdd18 100644
--- a/docs/architecture/template-authoring.md
+++ b/docs/architecture/template-authoring.md
@@ -150,9 +150,12 @@ authoring check; it does not replace runtime catalog validation.
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.
+ adopting project. Repository-only demo assets and demo-content elements are
+ replaced with generic placeholders during copy; `template copy` and the
+ docsite's shadcn Install item are copies. `template show` returns the same
+ source a copy writes. Other example source handed out without a copy
+ replaces only demo-content elements. 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`.
@@ -218,6 +221,23 @@ This record does not absorb adjacent facts:
runtime template envelope.
- `packages/cli/foundation/discovery/template-adapter.mjs` — current source loaders,
normalization, projections, and shared template IO.
+- `replaceDemoMedia` in `template-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-028` FR13 states the
+ outcome. `template copy`, `template show`, and the docsite's shadcn Install
+ item run both passes; the copy receipt and the `template show` response
+ report the element count as `demoContentReplaced`. The docsite Code tab, Open
+ in Playground, the Sandbox code view, the docsite MCP server's `get()`, and
+ `astryx component <Name> --showcase` run only the element pass, so they keep
+ their fixture media (`spec:AST-033` FR23). Implementation gap:
+ the demo-content module, the element pass, and `demoContentReplaced` are 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.
@@ -234,14 +254,15 @@ This record does not absorb adjacent facts:
## 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 |
+| 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
diff --git a/docs/specs/AST-028/spec.md b/docs/specs/AST-028/spec.md
index c7acbdee15..66bed95096 100644
--- a/docs/specs/AST-028/spec.md
+++ b/docs/specs/AST-028/spec.md
@@ -34,7 +34,10 @@ not production content or a supported consumer asset library.
This contract owns static demonstration assets used by templates, including
images, posters, and videos. It covers their authored references, maintainer
-previews, copied output, and fallbacks.
+previews, copied output, and fallbacks. It also owns demo-content elements:
+repository-only elements that stand in for docs-only demo contents, such as a
+playing-card face, that a real Astryx component wraps in a motion or gesture
+example.
It does not own icons. Icons may be component props, registry values, imported
modules, inline symbols, or product assets, and their conversion and portability
@@ -113,6 +116,34 @@ concerns require a separate contract.
tell the consumer when Astryx demonstration media was replaced and identify the
generated file or replacement points they need to customize. The receipt MUST
not imply that production-ready media was installed.
+- **FR13 — Demo-content elements are replaced during copy.** In a motion or
+ gesture example, a real Astryx component MAY wrap docs-only demo contents,
+ such as `<Card><PlayingCardContents /></Card>`. A demo-content element is a
+ repository-only element that stands in for those contents. Every copy MUST
+ replace repository-only demo assets (FR7–FR10) and every demo-content element
+ with generic placeholders, keeping the outer component and its props, and the
+ copied source MUST NOT reference the repository-only code that defines a
+ demo-content element. The copies are `template copy` and the docsite's shadcn
+ Install item, which writes the example into the consumer's project. The copy
+ receipt (FR11) MUST count the replaced elements as `demoContentReplaced`; the
+ shadcn Install item's receipt is the `.astryx/<item>.json` file it already
+ installs, which MUST carry `demoMediaReplaced` and `demoContentReplaced`.
+ `template show` returns the same source a copy writes and MUST report
+ `demoContentReplaced` in its response, as it reports `demoMediaReplaced`.
+ Surfaces other than these copies and `template show` that hand out example
+ source without writing it into a project replace only demo-content elements
+ and keep their fixture media:
+ `astryx component <Name> --showcase`, which prints the component's showcase
+ source, and the docsite surfaces of `spec:AST-033` FR23. Live previews render
+ the originals (FR4). A check MUST fail when copied, shown, or handed-out
+ output still references a demo-content element or the code that defines it.
+ How a demo-content element is marked and replaced belongs to
+ `architecture:template-authoring`. Implementation gap: the element
+ replacement and `demoContentReplaced` in the copy receipt and the
+ `template show` response are not built; `--showcase` prints the showcase file
+ as read from disk; the shadcn Install item installs block source as read from
+ disk, with its fixture media, and discloses no replacement (Current-state
+ impact).
### Boundary with icons
@@ -138,20 +169,28 @@ previously unwritten requirements for why assets are fixtures, which references
may be transformed, what a safe fallback means, how unsupported formats fail,
and why icons are separate.
+Demo-content elements (FR13) are not built: the copy and show paths replace no
+elements, and neither the copy receipt nor the `template show` response has a
+`demoContentReplaced` count. `astryx component <Name> --showcase` prints the
+showcase file as read from disk. The shadcn Install item installs block source
+as read from disk, so it writes `/template-assets/` references into the
+consumer's project and discloses no replacement.
+
This specification-only change alters no package, template, asset, preview,
runtime, or public CLI behavior. Remaining implementation and verification
follow separately.
## Verification
-| Contract | Verification | Representative cases | Failure expectation |
-| -------- | ---------------------------------------------- | ------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------- |
-| FR1–FR3 | Template-source and copy-boundary tests | built-in page, block, integration template; Astryx fixture; consumer path; third-party URL | Copied source retains a preview runtime dependency or rewrites consumer-owned content |
-| FR4–FR6 | Real preview request and rendered-media checks | local, docsite, main sandbox, PR preview; image and video; missing fixture | Representative media 404s, resolves to another file, or silently uses the wrong kind |
-| FR7–FR8 | End-to-end CLI copy tests | image-only, video-only, and no-media template | Generated source retains `/template-assets/` or does not parse/render without setup |
-| FR9–FR10 | Classifier and mixed-source mutation tests | upper/lower case; multi-dot filename; image poster plus video; unknown suffix | Last suffix is misread, image data enters video, or an unsupported kind is guessed |
-| FR11 | Human and structured copy-receipt tests | no replacement; one image; mixed media | The consumer is not told what must be replaced or is told assets were installed |
-| FR12 | Scope guard tests and review | Icon prop, registry icon, imported SVG component, static hero image | Icon behavior is silently folded into the static-fixture transformer |
+| Contract | Verification | Representative cases | Failure expectation |
+| -------- | -------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| FR1–FR3 | Template-source and copy-boundary tests | built-in page, block, integration template; Astryx fixture; consumer path; third-party URL | Copied source retains a preview runtime dependency or rewrites consumer-owned content |
+| FR4–FR6 | Real preview request and rendered-media checks | local, docsite, main sandbox, PR preview; image and video; missing fixture | Representative media 404s, resolves to another file, or silently uses the wrong kind |
+| FR7–FR8 | End-to-end CLI copy tests | image-only, video-only, and no-media template | Generated source retains `/template-assets/` or does not parse/render without setup |
+| FR9–FR10 | Classifier and mixed-source mutation tests | upper/lower case; multi-dot filename; image poster plus video; unknown suffix | Last suffix is misread, image data enters video, or an unsupported kind is guessed |
+| FR11 | Human and structured copy-receipt tests | no replacement; one image; mixed media | The consumer is not told what must be replaced or is told assets were installed |
+| FR12 | Scope guard tests and review | Icon prop, registry icon, imported SVG component, static hero image | Icon behavior is silently folded into the static-fixture transformer |
+| FR13 | End-to-end CLI copy, show, and `--showcase` tests, a shadcn install test, and a real preview check | a motion or gesture example whose `Card` wraps one demo-content element; one with two; an example with none; its `template show` response; its `--showcase` output; its shadcn install into a project and its `.astryx/<item>.json` receipt; its live preview | Copied, shown, or installed output still references a demo-content element, the code that defines it, or `/template-assets/`; `--showcase` output references a demo-content element or changes its fixture media; the outer component or its props change; the copy receipt or the `template show` response omits or miscounts `demoContentReplaced`; the live preview stops rendering the original; or the shadcn install receipt lacks `demoMediaReplaced` or `demoContentReplaced` |
### Completion criteria
@@ -162,7 +201,9 @@ This spec moves from `accepted` to `shipped` only when:
- copied templates retain no Astryx preview-only media reference;
- image, poster, and video fallbacks are kind-safe and covered end to end;
- unsupported static fixture formats fail with an actionable reference;
-- copy receipts identify replaced demonstration media; and
+- copy receipts identify replaced demonstration media;
+- copied and installed templates retain no demo-content element or reference
+ to the code that defines it, and the receipt counts the replaced elements; and
- icon sources are proven outside this transform and linked to a separate
contract before any icon conversion is introduced.
@@ -201,12 +242,33 @@ repository-only fixture URLs in generated projects.
**Decider:** `cixzhang`, `2026-09-04`
-This contract covers static image and video fixtures only. Icons have distinct
+This contract covers static image and video fixtures and the demo-content
+elements of DEC-4; it does not cover icons. Icons have distinct
semantic, import, registry, and conversion concerns; grouping them with demo
media would silently decide another public boundary.
Rejected: classifying every SVG or image-like source as a template fixture.
+### DEC-4 — Demo-content elements are fixtures that copy replaces
+
+**Reference:** `spec:AST-028/DEC-4`
+
+**Decider:** `cixzhang`, `2026-11-01`
+
+Motion and gesture examples can show docs-only demo contents, such as a
+playing-card face, inside a real Astryx component without a second copy of each
+example to maintain. Those contents are fixtures in the DEC-1 sense: copy
+replaces each demo-content element with a generic placeholder and keeps the
+outer component, and previews render the originals (DEC-2). The shadcn Install
+item writes the example into the consumer's project, so it is a copy and
+replaces fixture media and demo-content elements as `template copy` does.
+`template show` returns the same source a copy writes; other surfaces that
+only hand out source replace demo-content elements alone. Examples without
+demo-content elements keep their source, except that their shadcn install
+replaces fixture media like any copy (FR7).
+
+Rejected: a docs-only duplicate of each example, which adds documents to keep in sync.
+
## Open questions
None.
diff --git a/docs/specs/AST-033/spec.md b/docs/specs/AST-033/spec.md
index 4f07c6fd94..8c53d10c12 100644
--- a/docs/specs/AST-033/spec.md
+++ b/docs/specs/AST-033/spec.md
@@ -275,6 +275,29 @@ for each bug.
examples. Test fixture posts under `src/content/blog/fixtures/` are served
on the canary only and never listed in the blog index, feed, or sitemap.
+### Example code
+
+- **FR23 — Example source replaces demo contents the way copy does.** In a
+ motion or gesture example, a real Astryx component may wrap docs-only demo
+ contents, such as `<Card><PlayingCardContents /></Card>`. The live example
+ renders the original. Every surface that hands out the example's source
+ carries it after the demo-content element replacement of `spec:AST-028`
+ FR13: each demo-content element becomes a generic placeholder, the source
+ keeps no reference to the code that defines it, and the outer component keeps
+ its props and behavior. Surfaces that only hand out source run that
+ replacement alone, so each keeps its fixture media:
+ the Code tab and its copy action; Open in Playground, which opens and runs
+ that replaced source, so the playground shows the placeholder; the Sandbox
+ code view and its Copy source action; and the MCP server's `get()`, whose
+ component result carries the showcase example's source and one more
+ example's source and whose template result carries the template's example
+ sources or, without them, its page source. The shadcn Install item writes
+ the example into the consumer's project, so it is a copy under
+ `spec:AST-028` FR13 and its registry item carries the source with fixture
+ media and demo-content elements both replaced. Implementation gap: not
+ built; each surface carries block source as read from disk (Current-state
+ impact).
+
### Authority routing
`architecture:knowledge-contracts` owns public-delta routing and change disposition.
@@ -325,7 +348,11 @@ Known conformance gaps remain implementation work:
source, type, tab, view, and toggle-value fields, and nested template-preview
activation can reach the same semantic action twice;
- existing interaction tests do not yet cover the complete primary-selection,
- Back/Forward, close, cancellation, and supersession matrix.
+ Back/Forward, close, cancellation, and supersession matrix; and
+- the Code tab, Open in Playground, the Sandbox code view, the MCP server's
+ `get()`, and the shadcn Install item carry block source as read from disk,
+ with no demo-content element replacement, and the shadcn Install item also
+ keeps its fixture media (FR23).
Stable Storybook and Sandbox currently use a split deployment: pull-request
previews are staged inside the Vercel Docsite, while stable main is rebuilt and
@@ -340,16 +367,17 @@ exact source already serving those public surfaces.
## Verification
-| Contract | Verification | Representative states | Mutation or failure expectation |
-| --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| FR1–FR3 | generator/data-extraction tests plus cross-projection inventory; search endpoint parity with `astryx search --json` | package, component, template, theme; gallery, sidebar, search, direct route, preview, playground | a local map changes membership or a canonical item fact, or availability and visibility collapse into one projection |
-| FR4–FR6 | latest/canary generation and projection tests | stable package, canary-only package, ready/unready item, overview-hidden item, invalid integration metadata | latest exposes canary package docs, workspace-backed content is called release-pinned, a second readiness state appears, or projections disagree |
-| FR7–FR9 | navigation-family checks plus real-browser navigation/history tests | direct link, modified click, new tab, deep link, primary selection, secondary tab/filter, canonicalization, Back/Forward | Docsite misclassifies a destination, canonical identity diverges, primary selections replace one another, or secondary state clutters history |
-| FR10–FR12 | selection/transition tests plus real-browser visible-content checks | initial open, reopen, deep link, direct selection, pending previous/next, close, supersede, reject, unmount | header/body/actions disagree, stale content paints without its owning pending state, or obsolete selection work commits after supersession |
-| FR13–FR15 | analytics schema and interaction tests with transport spies | navigation intent, successful/failed copy, cancel, URL restoration, render/effect, duplicate activation | event names/properties drift, free-form/high-cardinality data is logged, a passive lifecycle emits, success logs on failure, or one action emits twice |
-| FR16 | production-browser playground isolation and recovery tests | direct load, reload, hostile navigation, storage and parent-DOM denial | preview code reaches parent/storage or trusted recovery restores stale source/theme |
-| FR17–FR21 | exact-head Vercel build, route/asset probes, metadata checks, and Pages landing contract | production and PR Preview; Storybook manager/frame; Sandbox route/embed; old root/deep path; desktop/mobile; light/dark | one app is absent or stale, a direct asset/route fails, metadata claims the wrong owner, identity drifts, or Pages hosts more than the compatibility page |
-| FR22 | `e2e/blog-live-examples.spec.ts` (real-browser post, plain-text route, feed, sitemap, and index checks) and `blog-live-examples.test.tsx` (fence rule, static fallback, fixture listing, runner) | a post with a `tsx live` block; that post's plain-text route; a block importing a post-local asset; a block that fails to compile or throws; live fences in a blockquote, a list item, and quoted inside a longer fence | the live block does not run in the browser, the text route shows anything but the source fallback for a fence the page runs, a post-local import fails to resolve, a broken example breaks the page outside its frame, or the feed, sitemap, or index lists the fixture |
+| Contract | Verification | Representative states | Mutation or failure expectation |
+| --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| FR1–FR3 | generator/data-extraction tests plus cross-projection inventory; search endpoint parity with `astryx search --json` | package, component, template, theme; gallery, sidebar, search, direct route, preview, playground | a local map changes membership or a canonical item fact, or availability and visibility collapse into one projection |
+| FR4–FR6 | latest/canary generation and projection tests | stable package, canary-only package, ready/unready item, overview-hidden item, invalid integration metadata | latest exposes canary package docs, workspace-backed content is called release-pinned, a second readiness state appears, or projections disagree |
+| FR7–FR9 | navigation-family checks plus real-browser navigation/history tests | direct link, modified click, new tab, deep link, primary selection, secondary tab/filter, canonicalization, Back/Forward | Docsite misclassifies a destination, canonical identity diverges, primary selections replace one another, or secondary state clutters history |
+| FR10–FR12 | selection/transition tests plus real-browser visible-content checks | initial open, reopen, deep link, direct selection, pending previous/next, close, supersede, reject, unmount | header/body/actions disagree, stale content paints without its owning pending state, or obsolete selection work commits after supersession |
+| FR13–FR15 | analytics schema and interaction tests with transport spies | navigation intent, successful/failed copy, cancel, URL restoration, render/effect, duplicate activation | event names/properties drift, free-form/high-cardinality data is logged, a passive lifecycle emits, success logs on failure, or one action emits twice |
+| FR16 | production-browser playground isolation and recovery tests | direct load, reload, hostile navigation, storage and parent-DOM denial | preview code reaches parent/storage or trusted recovery restores stale source/theme |
+| FR17–FR21 | exact-head Vercel build, route/asset probes, metadata checks, and Pages landing contract | production and PR Preview; Storybook manager/frame; Sandbox route/embed; old root/deep path; desktop/mobile; light/dark | one app is absent or stale, a direct asset/route fails, metadata claims the wrong owner, identity drifts, or Pages hosts more than the compatibility page |
+| FR22 | `e2e/blog-live-examples.spec.ts` (real-browser post, plain-text route, feed, sitemap, and index checks) and `blog-live-examples.test.tsx` (fence rule, static fallback, fixture listing, runner) | a post with a `tsx live` block; that post's plain-text route; a block importing a post-local asset; a block that fails to compile or throws; live fences in a blockquote, a list item, and quoted inside a longer fence | the live block does not run in the browser, the text route shows anything but the source fallback for a fence the page runs, a post-local import fails to resolve, a broken example breaks the page outside its frame, or the feed, sitemap, or index lists the fixture |
+| FR23 | Output checks for each surface plus real-browser live-example check | a motion or gesture example whose `Card` wraps a demo-content element; its Code tab and copied text; its Open in Playground source; its Sandbox code view and copied source; its MCP `get()` component and template results; its shadcn registry item and the `.astryx/<item>.json` receipt it installs; an example with fixture media; its live preview | any of those surfaces still references a demo-content element or the code that defines it; the outer component or its props change; fixture media changes on a surface that only hands out source; the shadcn registry item still references `/template-assets/`, or its installed receipt lacks `demoMediaReplaced` or `demoContentReplaced`; or the live preview stops rendering the original |
## Decision log
@@ -475,6 +503,22 @@ and outside every package and catalog.
Rejected: a second blog-only renderer that would need its own isolation.
+### DEC-10 — Example code replaces demo contents the way copy does
+
+**Reference:** `spec:AST-033/DEC-10`
+**Decider:** `cixzhang`, `2026-11-01`
+
+Motion and gesture examples may show docs-only demo contents, such as a
+playing-card face, inside a real Astryx component, without a second copy of
+each example to maintain. Every surface that hands out example source runs the
+CLI copy's demo-content element replacement (`spec:AST-028/DEC-4`), so the demo
+contents a person or agent reads, copies, opens, or installs are the generic
+placeholders a CLI copy writes. Surfaces that only hand out source run no other
+copy step. The shadcn Install item writes into the consumer's project, so it is
+a copy and also replaces fixture media.
+
+Rejected: a docs-only duplicate of each example, which adds documents to keep in sync.
+
## Open questions
None.