An open source design system that's fully customizable and agent ready
schema_version: 4 template_version: 1 kind: system-spec id: spec:AST-024 authority: current archive_reason: null superseded_by: null approved_by: cixzhang approved_at: 2026-09-04 phase: accepted 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–h6level 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; theme-local scale extension authoring remains a separate proposal.
- Expand the font-weight choices available in every theme in this change.
Terms
- Semantic level: the
Heading.levelvalue that selectsh1–h6and 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, ordisplay-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.weightvalue 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 byHeadingProps.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 buildMUST 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-1throughdisplay-3behavior remains compatible.
Per-use weight
- FR7 — Heading accepts an optional weight override.
HeadingMUST accept the same namedTextWeightvalues asText:normal,medium,semibold, andbold. When omitted, the current level- or type-derived default remains. - FR8 — Explicit weight has clear precedence. A supplied
weightprop MUST win over the default weight of either a built-in or custom visual type. It MUST NOT changelevel,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
boldorsemiboldmeans 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 ashero,title, ordisplay. - 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
levelmerely 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
Texteven 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 itsdata-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-levelhandling. Existing Heading accessibility tests remain applicable.
Accepted API
// 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:
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:
<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 accepted 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.