From 198e02b0353de419b5d87da894b9fb7a28520ca4 Mon Sep 17 00:00:00 2001
From: rubyycheung <254546175+rubyycheung@users.noreply.github.com>
Date: Sat, 5 Sep 2026 22:35:08 -0500
Subject: [PATCH] docs(Heading): explain visual role boundaries
---
docs/specs/AST-024/spec.md | 24 ++++++++++++++++++++++++
packages/cli/assets/theme.template.ts | 7 ++++++-
packages/core/src/Text/Heading.doc.mjs | 4 ++--
3 files changed, 32 insertions(+), 3 deletions(-)
diff --git a/docs/specs/AST-024/spec.md b/docs/specs/AST-024/spec.md
index 4a7a23f3d1b21..0ba4c884527af 100644
--- a/docs/specs/AST-024/spec.md
+++ b/docs/specs/AST-024/spec.md
@@ -201,6 +201,30 @@ role without changing its semantic level:
```
+## Choosing a visual role or a separate theme
+
+Use a custom Heading type when the name describes a reusable typography job
+inside one design language, such as `hero`, `editorial`, or `sectionTitle`.
+Several roles may coexist on the same page, and `level` continues to follow the
+document outline. Use `weight` when one Heading needs only a named weight change;
+do not create another visual role for that single-property override.
+
+Use a separate theme when the surrounding visual context changes as a system,
+such as a different brand, palette, type family, density, or coordinated styling
+across several components. Apply that theme at the appropriate provider boundary
+so the page or product subtree changes together.
+
+Do not create a separate page theme solely to obtain one Heading treatment, and
+do not use a growing set of Heading types to imitate a broader brand or page
+theme. Keep role names semantic and reusable rather than encoding presentation
+details in names such as `hero64` or creating overlapping names such as `hero`,
+`heroLarge`, and `marketingHero`.
+
+Generated TypeScript declarations make a custom name available throughout the
+program that imports them; they cannot prove that the owning theme is active at a
+particular render site. Applications must still render the custom role under the
+theme that defines its runtime styles.
+
## Current-state impact
The accepted spec changes no runtime or public API by itself. Its implementation
diff --git a/packages/cli/assets/theme.template.ts b/packages/cli/assets/theme.template.ts
index 4215ef4c1715f..c89bcaf6ae3bf 100644
--- a/packages/cli/assets/theme.template.ts
+++ b/packages/cli/assets/theme.template.ts
@@ -287,8 +287,13 @@ export const myTheme = defineTheme({
padding: 'var(--spacing-6)',
},
},
- // The same mechanism adds custom Text types: .
+ // The same mechanism adds reusable visual roles to Text and Heading. Use a
+ // role when one typography treatment must coexist with others in this theme;
+ // use a separate theme when brand, palette, type family, density, or several
+ // components change together. Keep Heading.level tied to document structure,
+ // and use Heading.weight for a one-property emphasis change.
text: {'type:hero': {fontSize: 'var(--font-size-4xl)', lineHeight: '1.05'}},
+ // heading: {'type:hero': {fontSize: 'var(--font-size-4xl)', lineHeight: '1.05'}},
},
// ───────────────────────────────────────────────────────────────────────
diff --git a/packages/core/src/Text/Heading.doc.mjs b/packages/core/src/Text/Heading.doc.mjs
index daf20cdd25f92..371de248a16ca 100644
--- a/packages/core/src/Text/Heading.doc.mjs
+++ b/packages/core/src/Text/Heading.doc.mjs
@@ -28,7 +28,7 @@ export const docs = {
name: 'type',
type: "'display-1' | 'display-2' | 'display-3'",
description:
- 'Display type variant. Overrides the visual styling from `level` with display-scale sizing (larger, lighter weight, tighter line-height). Themes may add custom visual types. The `level` still determines the HTML element for accessibility. Use for hero banners, marketing headlines, and data callouts.',
+ 'Display type variant. Overrides the visual styling from `level` with display-scale sizing (larger, lighter weight, tighter line-height). Themes may add reusable custom visual roles such as hero or editorial; use a separate theme instead when the brand, palette, type family, density, or several components change together. The `level` still determines the HTML element for accessibility.',
},
{
name: 'weight',
@@ -223,7 +223,7 @@ export const docsDense = {
propDescriptions: {
level:
'Heading level; determines HTML element + styling from theme (unless type is set).',
- type: 'Display variant (display-1/2/3 or a theme-owned custom type); overrides visual styling from level.',
+ type: 'Display variant (display-1/2/3 or a theme-owned custom role); use a custom role for a reusable Heading treatment and a separate theme for broader visual-system changes.',
weight:
'Explicit font weight; wins over the visual type or heading-level default.',
children: 'Heading content.',