Skip to content

docs: define template governance boundaries #5915

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
cixzhang wants to merge 1 commit into from
Closed

docs: define template governance boundaries #5915

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
107 changes: 107 additions & 0 deletions docs/architecture/template-authoring.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,107 @@
---
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,
apps/docsite/src/components/templateComponents.ts,
]
verified_by:
[
packages/cli/authoring/doctypes/template/parse.test.mjs,
packages/cli/foundation/discovery/template-adapter.test.mjs,
packages/cli/api/template/template.test.mjs,
]
deciding_specs: []
---

# Template authoring architecture

> Draft: the governance rules below require exact-head owner approval before
> this record can become `current`.

## Purpose

Define the durable authoring, ownership, evidence, and compatibility contract
for page templates and blocks. This uses the existing `architecture` kind.

## System model

- A template unit is its [source and metadata](../../packages/cli/assets/templates/),
[authoring type](../../packages/cli/authoring/doctypes/template/type.ts),
[discovery](../../packages/cli/foundation/discovery/template-adapter.mjs), and
required [docsite registration](../../apps/docsite/src/components/templateComponents.ts).
Those parts ship together at one head.
- Design owns human visual and interaction intent. `josephfarina`, the existing
`packages/cli` owner, owns authoring, runtime/generation, package correctness,
discovery, and CLI integration. Changes crossing both boundaries need both
approvals.
- Every page and block is evaluated against the current
[Template Grading Rubric](https://github.com/facebook/astryx/wiki/Contributing-Templates#template-grading-rubric).
Rubric revisions follow their own review/versioning process and do not require
this record to change unless ownership or governance semantics change.
- Every scorecard or ledger row pins the exact template head and exact rubric
commit or revision used. Scores and artifacts are evidence, not approval, and
later rubric revisions do not silently change prior scores.

## Boundaries and invariants

- **INV1 — Complete unit.** Source, metadata, discovery, and required registration
MUST agree at one head.
- **INV2 — Separate approvals.** Design and implementation approval are distinct;
neither substitutes for the other.
- **INV3 — Local behavior.** Membership, states, interactions, and constraints
stay local unless a separate shared contract is approved.
- **INV4 — No implicit wizard family.** [#5797](https://github.com/facebook/astryx/pull/5797)
and [#5798](https://github.com/facebook/astryx/pull/5798) remain independent;
`design:template-composition` supplies only shared composition intent.
- **INV5 — Compatible identity.** A template ID is a public lookup key. Rename or
removal requires an explicit compatibility and migration plan.
- **INV6 — Exact-head evidence.** Validation, scorecards, artifacts, and approvals
identify the exact template head; scorecards also identify the rubric revision.

## Change coupling

- Source or metadata changes require local behavior, current-rubric, package, and
CLI validation; visual or interaction changes also require Design review.
- Authoring, discovery, registration, runtime, or CLI changes require focused
implementation-owner review and tests.
- Shared behavior or membership requires a separately approved contract.
- Rubric changes follow rubric governance and preserve prior pinned scores.

## Owning code

- [Template source and metadata](../../packages/cli/assets/templates/)
- [`TemplateDoc` authoring contract](../../packages/cli/authoring/doctypes/template/type.ts)
- [Template discovery](../../packages/cli/foundation/discovery/template-adapter.mjs)
- [Template CLI](../../packages/cli/api/template/template.mjs)
- [Docsite registration](../../apps/docsite/src/components/templateComponents.ts)
- [Template Grading Rubric](https://github.com/facebook/astryx/wiki/Contributing-Templates#template-grading-rubric)
- [Design composition intent](../design/template-composition.md)

## Deciding specs

### Proposed owner-review direction — 2026-09-02

Proposed by `cixzhang`: require separate Design and `josephfarina` approvals when
both boundaries change; treat scores only as pinned evidence; keep #5797/#5798
behavior local. This draft does not record approval or create a schema kind.

## Verification

| Rule | Evidence | Failure signal |
| ---------------- | ------------------------------------------------- | ------------------------------------------------ |
| INV1 | Metadata, discovery, CLI, and docsite checks | A template is missing or registered only once |
| INV2, INV3, INV4 | Exact-head owner review and template-local source | One approval is waived or a family is presumed |
| Current rubric | Scorecard pins template head and rubric revision | Evidence cannot be reproduced or claims approval |
| INV5, INV6 | Lookup/migration tests and exact-head review | An ID breaks or evidence points at another head |
113 changes: 35 additions & 78 deletions docs/design/template-composition.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,12 +11,7 @@ approved_at: null
owners: [ernestt, cixzhang]
review_triggers: [visual, layout, theming, responsive]
verified_by: []
architecture:
[
architecture:component-theming-surface,
architecture:container-padding,
architecture:theme-tokens,
]
architecture: [architecture:template-authoring]
components: []
families: [family:layout-primitives, family:layout-regions]
deciding_specs: []
Expand All @@ -26,108 +21,70 @@ deciding_specs: []

## User intent

A page template or reusable block should look like an intentional product
surface, not merely a valid collection of components. It should establish a
clear reading order, coherent regions, and theme-safe emphasis while leaving
product content and application chrome to the adopting product.
Templates should communicate purpose through composition, not just valid components.

## Design principles

- **DR1 — Layout communicates purpose.** Structural regions, grid, and stacking
MUST make the page's primary task apparent before individual content is read.
- **DR2 — Visual hierarchy directs the eye.** Size, weight, and placement MUST
establish an intentional path from page context to primary content and action.
- **DR3 — Spacing and alignment express relationships.** Repeated edges, gaps,
and grouping tiers MUST remain coherent across the whole composition.
- **DR4 — Components preserve their affordances.** A template MUST choose
components and variants whose visual language matches the intended action,
navigation, data, or status role.
- **DR5 — Color and theming preserve hierarchy.** Surface and accent choices MUST
retain meaning and emphasis in every supported theme and color mode.
Sourced from public
[Design Conventions](https://github.com/facebook/astryx/wiki/Design-Conventions):

- **DR1 — Purpose.** Layout MUST make the primary task clear.
- **DR2 — Attention.** Visual hierarchy MUST guide attention.
- **DR3 — Relationships.** Spacing and alignment MUST express grouping.
- **DR4 — Affordance.** Components MUST visually match their roles.
- **DR5 — Themes.** Themes and color modes MUST preserve meaning and emphasis.

## Anatomy and hierarchy

| Role | Purpose | Required relationship |
| ------------------ | --------------------------------------------------------------- | ------------------------------------------------------------------ |
| page context | Establishes where the person is and what the surface is for | Leads the visual hierarchy without competing with the primary task |
| structural region | Groups navigation, controls, content, or supporting information | Uses layout boundaries and spacing that match its role |
| primary content | Carries the page's main task or information | Receives the strongest sustained hierarchy |
| primary action | Offers the most important local next step | Remains singular and easy to identify within its action group |
| supporting content | Adds explanation, metadata, or secondary action | Remains available without flattening hierarchy |
| repeated item | Forms a list, grid, table, or card collection | Preserves alignment and rhythm across realistic content variation |
No anatomy is universal. Each template owns its roles and membership; Design
reviews whether they form a coherent composition.

## State representation

| State | Required representation | Allowed variation |
| ------------------ | --------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- |
| populated | Regions and hierarchy remain clear with realistic content | Content length and collection size may vary within the template's purpose |
| sparse | Empty space preserves intentional grouping rather than collapsing structure | Optional supporting regions may disappear |
| constrained | Regions reflow without losing reading order or primary action | Navigation and secondary content may move or collapse according to family contracts |
| light or dark mode | Surface hierarchy, contrast, and accent meaning remain intact | Theme controls palette and visual personality |
| interactive | Component states remain recognizable inside the larger composition | Components retain their family-owned treatments |
No state matrix is universal; each template owns and preserves its required states.

## Responsive and input behavior

- **DR6 — Reflow preserves reading order.** Responsive changes MUST retain the
relationship among page context, primary content, supporting regions, and
actions.
- **DR7 — Collections adapt without arbitrary clipping.** Repeated content MUST
use a layout strategy that remains coherent across supported widths and
realistic item lengths.
- **DR8 — Input modes keep the same task hierarchy.** Keyboard, pointer, and
touch paths MUST reach the same primary task and actions without relying on
hover-only discovery.
No responsive/input matrix is universal; each template owns its supported modes
and preserves reading order and task hierarchy.

## Accessibility intent

Visual hierarchy should agree with semantic reading and focus order. Reflow must
not separate labels, explanations, errors, or actions from the content they
serve. Theme variation must preserve legibility and state meaning, and realistic
content must not expose inaccessible overflow or truncation.

Semantic markup, component APIs, focus management, and responsive implementation
belong to components, layout families, and consumer guidance.
Visual hierarchy should agree with semantic reading, focus order, and relationships.

## Representative examples

- A dense data page still exposes one clear title, control region, primary data
region, and action hierarchy when viewed at a glance.
- A card collection retains alignment and grouping with realistic titles,
metadata, and missing optional content.
- A narrow layout moves supporting regions without changing reading order or
hiding the primary action.
- [#5797](https://github.com/facebook/astryx/pull/5797) keeps active and completed
steps visible.
- [#5798](https://github.com/facebook/astryx/pull/5798) uses a constrained dialog
for a short flow.

They are independent templates, not members of a shared wizard family.

## Visual references

No normative assets are included in this seed draft. Representative full-page
and block examples should be added under
`docs/design/assets/template-composition/` in light, dark, wide, and constrained
states before promotion.
The current
[Template Grading Rubric](https://github.com/facebook/astryx/wiki/Contributing-Templates#template-grading-rubric)
governs evaluation. Exact-commit scores and artifacts are evidence, not Design or
implementation approval.

## Component contract links

No component contract links are asserted. The listed layout-family relationships
are candidates for review; consumer templates remain responsible for using the
public contracts those families expose.
Templates must follow the public contracts of the components they compose.

## Decision log

No repository design decision has approved this record yet. This draft migrates
only the human visual-quality axes from the public Design Conventions wiki; it
deliberately excludes authoring mechanics and audit grading.
### Proposed owner-review direction — 2026-09-02

Proposed by `cixzhang`: Design owns human intent; the separate
[authoring architecture](../architecture/template-authoring.md) owns implementation.
Behavior stays local absent an approved shared contract; #5797/#5798 create no
wizard family. This draft does not record approval.

## Open questions

- **OQ1 — Representative templates.** Which page templates and blocks should be
normative examples for each composition requirement?
- **OQ2 — Product chrome boundary.** Which structural regions belong to a
reusable page template versus the host application?
- **OQ3 — Evidence.** How should screenshot review demonstrate hierarchy and
composition without turning subjective judgment into a misleading score?
None.

## Content boundary

This file defines human visual intent for template composition. It does not
define required React components, raw-HTML policy, icon plumbing, styling
mechanics, mock-data sources, documentation metadata, line-count targets, audit
grades, or consumer instructions.
Owns shared intent, not implementation, local behavior, rubric, or approval.
Loading