An open source design system that's fully customizable and agent ready
TypeScript
docs(spec): define extensible Heading visual roles (#6024)
rubyycheungf613dcb64e32
diff --git a/docs/specs/AST-024/spec.md b/docs/specs/AST-024/spec.mdnew file mode 100644index 0000000000..20f88ce0da--- /dev/null+++ b/docs/specs/AST-024/spec.md@@ -0,0 +1,328 @@+---+schema_version: 1+template_version: 1+kind: system-spec+id: spec:AST-024+authority: draft+archive_reason: null+superseded_by: null+approved_by: null+approved_at: null+phase: proposed+owners: [rubyycheung]+affects_architecture: [architecture:theme-authoring-contract]+affects_families: []+affects_contributing: []+affects_consumer_docs: [theme, typography]+---++# Theme-extensible Heading visual roles system spec++## Intent++Product themes sometimes need named heading treatments beyond Astryx's three+built-in display roles. A theme may need a hero treatment, a compact section+heading, or another locally named visual role while still rendering the correct+`h1`–`h6` element. Authors may also need to change the weight of one Heading use+without creating a new visual role.++Astryx already supports theme-defined `Text` types and generates their TypeScript+augmentation during `astryx theme build`. `Heading` does not provide the same+extension point: its `type` is a closed union and it has no `weight` prop. This spec+makes Heading visual roles theme-extensible, keeps document semantics independent+from appearance, and gives generated theme CSS and generated types one dependable+contract.++## Non-goals++- Add product-specific heading names to the options Astryx provides in every+ theme.+- Infer an `h1`–`h6` level from a visual type name or font size.+- Allow visual styling to repair an incorrect document outline.+- Add arbitrary Heading sizes without a theme declaration or local source.+- Replace `Text`, typography tokens, or the existing type-scale generator.+- Define how additional typography values are calculated; scale-extension+ authoring is covered separately by+ [AST-023](https://github.com/facebook/astryx/pull/6010).+- Expand the font-weight choices available in every theme in this change.++## Terms++- **Semantic level:** the `Heading.level` value that selects `h1`–`h6` and the+ element's place in the document outline.+- **Visual type:** a named treatment that controls size, line height, font family,+ weight, or other approved visual properties without changing semantic level.+- **Built-in type:** `display-1`, `display-2`, or `display-3`.+- **Custom type:** a theme-owned visual type declared through a Heading component+ override and exposed to TypeScript through an augmentable map.+- **Weight override:** an explicit `Heading.weight` value for one rendered heading;+ it wins over the visual type or semantic-level default without changing either.++## Current limitation++`HeadingType` is currently the closed literal union+`'display-1' | 'display-2' | 'display-3'`. TypeScript module augmentation cannot+widen a type alias. The theme builder therefore skips a theme rule such as+`heading['type:hero']` when generating `.variants.d.ts`; emitting a new unrelated+interface would not change `HeadingProps.type`.++The browser can match the generated `data-type="hero"` selector, but application+source cannot pass `type="hero"` without a type error. If the error is bypassed,+Heading also has no defined baseline StyleX entry for that name. The current system+therefore permits CSS that its public component API cannot use safely.++## Requirements++### Extensible visual types++- **FR1 — Heading exposes a real augmentation point.** The public Heading subpath+ MUST export an interface whose keys form the custom portion of `HeadingType`.+ Built-in types remain available without augmentation. A generated declaration+ MUST widen the same interface consumed by `HeadingProps.type`; a declaration+ against a barrel-only or unused interface is invalid.+- **FR2 — Theme build enrolls declared custom types.** When a theme contains a+ custom `heading['type:<name>']` override, `astryx theme build` MUST emit the+ corresponding type augmentation and reference it from the generated theme+ declaration. If the augmentation cannot be generated or loaded, the build MUST+ fail with actionable guidance rather than emit CSS that typed source cannot use.+- **FR3 — Custom types are theme-owned but TypeScript availability is+ program-wide.** A custom name becomes type-safe after a consumer imports the+ owning theme's generated declarations. TypeScript module augmentation applies to+ the whole compilation, so it cannot prove that a matching Theme is active at one+ call site. Documentation MUST state that distinction. A custom name MUST NOT+ enlarge Heading's built-in type set for applications that do not import it.+- **FR4 — Runtime styling is deterministic.** A valid custom type MUST reflect its+ name through the same theming selector path as a built-in type. Before theme CSS+ applies, it MUST retain the selected semantic level's safe baseline rather than+ becoming unstyled or inheriting an unrelated ambient text size. If application+ source uses an imported custom name under a theme that does not define it, the+ safe baseline applies. Development tooling SHOULD warn when it can determine the+ active theme and mismatch without adding production runtime cost.+- **FR5 — Partial custom types are valid.** A custom Heading type MUST contain at+ least one meaningful visual declaration. Font size, line height, font family,+ weight, letter spacing, color, and other supported properties MAY be changed+ independently; omitted properties inherit from the selected semantic level's+ baseline. An empty or wholly invalid custom type fails before output.+- **FR6 — Existing types do not change.** Themes that declare no custom Heading+ type MUST retain their current types, runtime output, and generated artifacts.+ Existing `display-1` through `display-3` behavior remains compatible.++### Per-use weight++- **FR7 — Heading accepts an optional weight override.** `Heading` MUST accept the+ same named `TextWeight` values as `Text`: `normal`, `medium`, `semibold`, and+ `bold`. When omitted, the current level- or type-derived default remains.+- **FR8 — Explicit weight has clear precedence.** A supplied `weight` prop MUST win+ over the default weight of either a built-in or custom visual type. It MUST NOT+ change `level`, `accessibilityLevel`, or the selected HTML element. Heading MUST+ reflect the selected weight through its theming target, and the emitted cascade+ MUST guarantee this order regardless of authored rule order: explicit weight,+ then visual-type default, then semantic-level default.+- **FR9 — Theme values remain authoritative.** Named weight props resolve through+ the existing font-weight tokens, so a theme may change what `bold` or `semibold`+ means without changing component source. Raw numeric or arbitrary weight strings+ are not added to the component prop in the first version.++### Semantics and author guidance++- **FR10 — Level and type remain independent.** Every custom-type example MUST+ include an explicit semantic `level`. Tooling and documentation MUST NOT infer a+ level from names such as `hero`, `title`, or `display`.+- **FR11 — Visual reuse does not justify skipped levels.** Guidance MUST tell+ authors to choose heading levels from the document outline, then choose a visual+ type. It MUST NOT recommend changing `level` merely to obtain a different size.+- **FR12 — Non-heading text keeps using Text.** If content is not a section or page+ heading, authoring guidance MUST use `Text` even when the same visual treatment is+ desired. A shared visual name MAY be declared separately for both components, but+ does not make non-heading content semantic.++### Verification and generated artifacts++- **FR13 — Source, runtime, and build agree.** A custom Heading type MUST pass+ TypeScript, render the requested `h1`–`h6`, expose its `data-type`, receive the+ generated declarations, and compute the expected CSS in both runtime-injected+ and statically built theme modes.+- **FR14 — Missing declarations fail visibly.** A consumer that uses a custom type+ without importing the owning theme declarations MUST receive a TypeScript error.+ Documentation MUST show the required theme artifact import and explain that+ importing it cannot prove which Theme is active at runtime.+- **FR15 — Accessibility behavior is unchanged.** Adding a visual type or weight+ MUST NOT alter accessible name, heading role, semantic level, truncation behavior,+ or `aria-level` handling. Existing Heading accessibility tests remain applicable.++## Proposed API++```ts+// Excerpt from @astryxdesign/core/Heading+export interface HeadingTypeMap {+ 'display-1': true;+ 'display-2': true;+ 'display-3': true;+}++export type HeadingType = keyof HeadingTypeMap;++export interface HeadingProps {+ level: 1 | 2 | 3 | 4 | 5 | 6;+ type?: HeadingType;+ weight?: TextWeight;+}+```++A theme may then declare and build a local role:++```ts+defineTheme({+ name: 'product',+ localTokens: {+ '--astryx-theme-product-text-hero-size': '4.5rem',+ '--astryx-theme-product-text-hero-leading': '1.05',+ },+ components: {+ heading: {+ 'type:hero': {+ fontSize: 'var(--astryx-theme-product-text-hero-size)',+ lineHeight: 'var(--astryx-theme-product-text-hero-leading)',+ },+ },+ },+});+```++After importing the built theme artifacts, application source can use the visual+role without changing its semantic level:++```tsx+<Heading level={1} type="hero">+ Product overview+</Heading>++<Heading level={2} type="hero" weight="bold">+ Featured report+</Heading>+```++## Current-state impact++The accepted spec changes no runtime or public API by itself. Its implementation+will replace Heading's closed type alias with a public map-backed union, teach the+theme builder to augment that map, give custom types a semantic-level baseline,+and add the existing named weight vocabulary to `HeadingProps`.++Themes and applications that use only the three built-in display types require no+migration. A theme that already emits `heading['type:<custom>']` CSS currently has+an unusable typed selector; after implementation and rebuild, its generated+declarations will make that existing local name available to consumers that import+the theme artifact. The augmentation is available throughout that TypeScript+program, while the custom styling remains owned by the active theme. No custom name+becomes an option that every Astryx application must support.++## Verification++| Contract | Verification | Representative failure |+| --------- | ---------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- |+| FR1–FR3 | Public-subpath augmentation and generated-declaration type tests | The CSS builds but `type="hero"` still fails, or docs claim TypeScript knows which Theme is active. |+| FR4–FR6 | Heading unit tests and before/after CSS snapshots | A custom type loses its level baseline, an intentional partial role fails, or a built-in theme changes output. |+| FR7–FR9 | Weight target and cascade tests for level, built-in type, and custom type | `weight="bold"` loses to a type default, depends on authored rule order, or bypasses theme weight tokens. |+| FR10–FR12 | Docs and authoring fixtures | Tooling infers `h1` from `hero`, skips a level for size, or uses Heading for non-heading copy. |+| FR13–FR15 | Consumer typecheck, runtime/static build parity, DOM and accessibility tests | The built artifact is not loaded, the selector differs by build path, or visual props alter heading semantics. |++### Completion criteria++This spec moves from `proposed` to `shipped` only when:++- Heading exposes and consumes one public augmentable type map;+- theme build emits and loads custom Heading type declarations;+- a custom type has a safe semantic-level baseline and at least one valid visual+ declaration;+- Heading accepts the existing named weight values with documented precedence;+- explicit weight wins through the runtime and built theme cascade, independent of+ authored rule order;+- runtime and static theme builds produce equivalent custom-type styling;+- built-in Heading behavior and themes without custom types remain unchanged; and+- examples and tests keep semantic level independent from visual treatment.++## Open questions++None.++## Decision log++### DEC-1 — Make Heading type extensible through a public map++**Reference:** `spec:AST-024/DEC-1`+**Decider:** `rubyycheung`, `2026-09-04`++Use the same proven map-based module-augmentation model as other extensible+component props. A closed type alias cannot be widened, and generating an unrelated+interface would falsely suggest type safety without changing `HeadingProps`.++### DEC-2 — Keep semantic level separate from visual type++**Reference:** `spec:AST-024/DEC-2`+**Decider:** `rubyycheung`, `2026-09-04`++Custom names control appearance only. Authors continue to choose `level` from the+document structure. This permits the same visual role at different valid levels+without coupling typography to accessibility semantics.++### DEC-3 — Add weight parity with Text++**Reference:** `spec:AST-024/DEC-3`+**Decider:** `rubyycheung`, `2026-09-04`++Add the existing named `TextWeight` vocabulary to Heading and make an explicit prop+override the type or level default. Do not add a second weight vocabulary or raw+numeric values in the first change.++### DEC-4 — Enroll visual roles independently by component++**Reference:** `spec:AST-024/DEC-4`+**Decider:** `rubyycheung`, `2026-09-04`++A visual-role name does not automatically become available to both `Text` and+`Heading`. Authors enroll it on each component whose semantics they intend to use.+The underlying theme-local typography values may be shared, and authoring tooling+may offer to create both mappings together, but it must show and confirm each use.++This prevents a Text treatment from silently becoming a heading treatment while+still avoiding duplicate value definitions.++### DEC-5 — Keep component weight choices consistent across themes++**Reference:** `spec:AST-024/DEC-5`+**Decider:** `rubyycheung`, `2026-09-04`++`Heading.weight` and `Text.weight` continue to use the same named choices in every+theme. The active theme decides whether a name such as `bold` resolves to 700, 750,+or another supported value. A custom visual type may also declare an exact weight+in theme source.++Rejected: accepting arbitrary numeric values directly at each component call site,+which would couple application source to one font and bypass theme ownership.++### DEC-6 — State the limit of theme-generated TypeScript clearly++**Reference:** `spec:AST-024/DEC-6`+**Decider:** `rubyycheung`, `2026-09-04`++Importing a theme's generated declaration makes its custom Heading names available+throughout that TypeScript program. It does not prove that the matching Theme is+active around every use. Runtime styling remains theme-scoped, mismatches retain the+semantic-level baseline, and development tooling warns when it can identify one+reliably.++Rejected: promising provider-aware static typing that TypeScript module augmentation+cannot enforce.++### DEC-7 — Permit partial visual roles++**Reference:** `spec:AST-024/DEC-7`+**Decider:** `rubyycheung`, `2026-09-04`++A custom Heading type may intentionally change only one supported visual property+and inherit the rest from its semantic level. It must contain at least one valid+declaration, but it does not have to restate font size and line height.++Rejected: requiring every custom type to be a complete typography replacement,+which would make small theme variations unnecessarily repetitive.