Skip to content

Navigation Menu

Sign in
Sign up

docs(Heading): explain when to use roles or themes #6081

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.

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

Open
rubyycheung wants to merge 1 commit into codex/heading-weight-implementation
base: codex/heading-weight-implementation
Choose a base branch
Loading
from codex/document-heading-role-guidance
Open
Show file tree
Hide file tree
Changes from all commits
Commits
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
24 changes: 24 additions & 0 deletions docs/specs/AST-024/spec.md
View file Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -201,6 +201,30 @@ role without changing its semantic level:
</Heading>
```

## 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
Expand Down
7 changes: 6 additions & 1 deletion packages/cli/assets/theme.template.ts
View file Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -287,8 +287,13 @@ export const myTheme = defineTheme({
padding: 'var(--spacing-6)',
},
},
// The same mechanism adds custom Text types: <Text type="hero" />.
// 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'}},
},

// ───────────────────────────────────────────────────────────────────────
Expand Down
4 changes: 2 additions & 2 deletions packages/core/src/Text/Heading.doc.mjs
View file Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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',
Expand Down Expand Up @@ -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.',
Expand Down

AltStyle によって変換されたページ (->オリジナル) /