主题可扩展的 Heading 视觉角色系统规范¶
意图¶
产品主题有时需要在 Astryx 的三个内置展示角色之外使用具名的标题处理方式。主题可能需要 hero 处理方式、紧凑的小节标题,或其他本地命名的视觉角色,同时仍渲染正确的 h1–h6 元素。作者可能还需要在不创建新视觉角色的情况下,更改某一次 Heading 使用的字重。
Astryx 已经支持主题定义的 Text 类型,并在 astryx theme build 期间生成其 TypeScript 增强。Heading 没有提供相同的扩展点:其 type 是封闭联合类型,且没有 weight 属性。本规范使 Heading 视觉角色可主题扩展,保持文档语义与外观相互独立,并为生成的主题 CSS 和生成的类型提供一份可靠的契约。
非目标¶
- 向 Astryx 在每个主题中提供的选项中添加产品特定的标题名称。
- 从视觉类型名称或字号推断
h1–h6级别。 - 允许视觉样式修复不正确的文档大纲。
- 在没有主题声明或本地来源的情况下添加任意 Heading 尺寸。
- 替换
Text、排版令牌或现有的字号阶梯生成器。 - 定义额外排版值的计算方式;主题本地字号阶梯扩展的编写仍是一个单独的提案。
- 在此变更中扩展每个主题可用的字重选项。
术语¶
- 语义级别: 选择
h1–h6的Heading.level值,以及该元素在文档大纲中的位置。 - 视觉类型: 一种具名的处理方式,控制字号、行高、字体族、字重或其他已批准的视觉属性,而不改变语义级别。
- 内置类型:
display-1、display-2或display-3。 - 自定义类型: 通过 Heading 组件覆盖声明的主题自有视觉类型,并通过可增强的映射暴露给 TypeScript。
- 字重覆盖: 针对单个渲染标题的显式
Heading.weight值;它优先于视觉类型或语义级别的默认值,而不改变两者中的任何一个。
当前限制¶
HeadingType 目前是封闭的字面量联合类型 'display-1' | 'display-2' | 'display-3'。TypeScript 模块增强无法拓宽类型别名。因此,主题构建器在生成 .variants.d.ts 时会跳过类似 heading['type:hero'] 这样的主题规则;生成一个全新的无关接口并不会改变 HeadingProps.type。
浏览器可以匹配生成的 data-type="hero" 选择器,但应用源码无法在不产生类型错误的情况下传入 type="hero"。如果绕过该错误,Heading 也没有为该名称定义基线 StyleX 条目。因此,当前系统允许存在其公共组件 API 无法安全使用的 CSS。
需求¶
可扩展的视觉类型¶
- FR1 — Heading 暴露真实的增强点。 公共 Heading 子路径 MUST 导出一个接口,其键构成
HeadingType的自定义部分。内置类型在无需增强的情况下仍然可用。生成的声明 MUST 拓宽HeadingProps.type所消费的同一个接口;针对仅在 barrel 文件中导出或未被使用的接口的声明无效。 - FR2 — 主题构建登记声明的自定义类型。 当主题包含自定义的
heading['type:<name>']覆盖时,astryx theme buildMUST 生成相应的类型增强,并从生成的主题声明中引用它。如果无法生成或加载该增强,构建 MUST 失败并给出可操作的指导,而不是生成类型化源码无法使用的 CSS。 - FR3 — 自定义类型归主题所有,但 TypeScript 可用性是全程序范围的。 消费者导入所属主题的生成声明后,自定义名称即变为类型安全的。TypeScript 模块增强适用于整个编译过程,因此无法证明在某个调用点存在匹配的 Theme 处于活动状态。文档 MUST 说明这一区别。对于未导入它的应用程序,自定义名称 MUST NOT 扩大 Heading 的内置类型集合。
- FR4 — 运行时样式是确定性的。 有效的自定义类型 MUST 通过与内置类型相同的主题选择器路径体现其名称。在主题 CSS 生效之前,它 MUST 保留所选语义级别的安全基线,而不是失去样式或继承无关的环境文本字号。如果应用源码在使用某个主题时使用了已导入的自定义名称,而该主题并未定义此名称,则采用安全基线。开发工具在能够确定活动主题及不匹配情况时应当发出警告,且不增加生产环境运行时成本。
- FR5 — 自定义类型允许部分定义。 自定义 Heading 类型 MUST 至少包含一个有意义的视觉声明。字号、行高、字体族、字重、字间距、颜色及其他受支持的属性可以独立更改;省略的属性继承所选语义级别的基线。空的或完全无效的自定义类型在输出之前会失败。
- FR6 — 现有类型不会改变。 未声明自定义 Heading 类型的主题 MUST 保留其当前的类型、运行时输出和生成的产物。现有的
display-1到display-3行为保持兼容。
单次使用的字重¶
- FR7 — Heading 接受可选的字重覆盖。
HeadingMUST 接受与Text相同的具名TextWeight值:normal、medium、semibold和bold。省略时,当前的级别或类型派生默认值保持不变。 - FR8 — 显式字重具有明确的优先级。 提供的
weight属性 MUST 优先于内置或自定义视觉类型的默认字重。它 MUST NOT 改变level、accessibilityLevel或所选 HTML 元素。Heading MUST 通过其主题目标体现所选字重,并且生成的级联 MUST 保证以下顺序,无论编写的规则顺序如何:显式字重,然后是视觉类型默认值,最后是语义级别默认值。 - FR9 — 主题值仍然具有权威性。 具名字重属性通过现有的字重令牌解析,因此主题可以更改
bold或semibold的含义,而无需更改组件源码。第一个版本不会将原始数字或任意字重字符串添加到组件属性中。
语义与作者指南¶
- FR10 — 级别与类型保持独立。 每个自定义类型示例 MUST 包含显式的语义
level。工具和文档 MUST NOT 从hero、title或display等名称推断级别。 - FR11 — 视觉复用不构成跳过级别的理由。 指南 MUST 告诉作者先从文档大纲中选择标题级别,然后再选择视觉类型。它 MUST NOT 建议仅为了获得不同大小而更改
level。 - FR12 — 非标题文本继续使用 Text。 如果内容不是章节或页面标题,即使需要相同的视觉处理,编写指南 MUST 使用
Text。可以分别为两个组件声明共享的视觉名称,但这不会使非标题内容具有语义。
验证与生成产物¶
- FR13 — 源代码、运行时与构建保持一致。 自定义 Heading 类型 MUST 通过 TypeScript 检查,渲染所请求的
h1–h6,暴露其data-type,接收生成的声明,并在运行时注入和静态构建的主题模式下计算出预期的 CSS。 - FR14 — 缺失声明时须明显失败。 使用自定义类型但未导入所属主题声明的消费者 MUST 收到 TypeScript 错误。文档 MUST 展示所需主题产物的导入方式,并说明导入该产物无法证明运行时哪个 Theme 处于活动状态。
- FR15 — 无障碍行为保持不变。 添加视觉类型或字重 MUST NOT 改变无障碍名称、标题角色、语义级别、截断行为或
aria-level处理。现有 Heading 无障碍测试仍然适用。
已接受的 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;
}
主题随后可声明并构建本地角色:
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)',
},
},
},
});
导入构建后的主题产物后,应用源代码可在不改变语义级别的情况下使用该视觉角色:
<Heading level={1} type="hero">
Product overview
</Heading>
<Heading level={2} type="hero" weight="bold">
Featured report
</Heading>
当前状态影响¶
已接受的规范本身不会改变任何运行时或公共 API。其实现将把 Heading 的封闭类型别名替换为基于公共映射的联合类型,让主题构建器能够扩充该映射,为自定义类型提供语义级别基线,并将既有的具名字重词汇添加到 HeadingProps。
仅使用三种内置 display 类型的主题和应用无需迁移。当前,已经输出 heading['type:<custom>'] CSS 的主题拥有一个无法使用的类型化选择器;在实现并重新构建后,其生成的声明将使该既有本地名称对导入主题产物的消费者可用。该扩充在整个 TypeScript 程序中可用,而自定义样式仍由活动主题持有。不会有任何自定义名称成为每个 Astryx 应用都必须支持的选项。
验证¶
| 契约 | 验证方式 | 代表性失败 |
|---|---|---|
| FR1–FR3 | 公共子路径扩充与生成声明的类型测试 | CSS 构建成功但 type="hero" 仍然失败,或文档声称 TypeScript 知道哪个 Theme 处于活动状态。 |
| FR4–FR6 | Heading 单元测试与前后 CSS 快照 | 自定义类型丢失其级别基线,有意的部分角色失败,或内置主题改变了输出。 |
| FR7–FR9 | 针对级别、内置类型和自定义类型的字重目标与级联测试 | weight="bold" 输给类型默认值、依赖于编写规则顺序,或绕过主题字重令牌。 |
| FR10–FR12 | 文档与编写夹具 | 工具从 hero 推断出 h1,为了大小跳过级别,或将 Heading 用于非标题文本。 |
| FR13–FR15 | 消费者类型检查、运行时/静态构建一致性、DOM 与无障碍测试 | 构建产物未加载,选择器因构建路径而异,或视觉属性改变了标题语义。 |
完成标准¶
仅当满足以下条件时,本规范才会从 accepted 变为 shipped:
- Heading 暴露并使用一个可扩充的公共类型映射;
- 主题构建输出并加载自定义 Heading 类型声明;
- 自定义类型具有安全的语义级别基线和至少一条有效的视觉声明;
- Heading 接受既有的具名字重值并记录其优先级;
- 显式字重能够在运行时和构建的主题级联中胜出,且不依赖编写规则顺序;
- 运行时和静态主题构建产生等效的自定义类型样式;
- 内置 Heading 行为和没有自定义类型的主题保持不变;以及
- 示例和测试保持语义级别与视觉处理相互独立。
开放问题¶
无。
决策日志¶
DEC-1 — 通过公共映射使 Heading 类型可扩展¶
参考: spec:AST-024/DEC-1
决策者: rubyycheung,2026-09-04
与其他可扩展组件属性一样,使用经过验证的基于映射的模块扩充模型。封闭类型别名无法扩展,而生成不相关的接口会在不改变 HeadingProps 的情况下虚假地暗示类型安全。
DEC-2 — 将语义层级与视觉类型分离¶
参考: spec:AST-024/DEC-2
决策者: rubyycheung, 2026-09-04
自定义名称仅控制外观。作者继续根据文档结构选择 level。这样可以在不同有效层级中使用相同的视觉角色,而不会将排版与无障碍语义耦合。
DEC-3 — 与 Text 保持字重一致¶
参考: spec:AST-024/DEC-3
决策者: rubyycheung, 2026-09-04
将现有的命名 TextWeight 词汇表添加到 Heading,并让显式 prop 能覆盖类型或层级的默认值。在首次变更中不要添加第二套字重词汇表或原始数值。
DEC-4 — 按组件独立登记视觉角色¶
参考: spec:AST-024/DEC-4
决策者: rubyycheung, 2026-09-04
视觉角色名称不会自动同时适用于 Text 和 Heading。作者需要在其打算使用语义的每个组件上登记该名称。底层的主题本地排版值可以共享,编写工具也可以提供同时创建两个映射的选项,但必须展示并确认每次使用。
这可以防止某个 Text 文本样式在不知不觉中变成标题样式,同时仍能避免重复的值定义。
DEC-5 — 保持组件字重选择在各主题间一致¶
参考: spec:AST-024/DEC-5
决策者: rubyycheung, 2026-09-04
Heading.weight 和 Text.weight 在每个主题中继续使用相同的命名选项。当前主题决定 bold 等名称解析为 700、750 还是其他受支持的值。自定义视觉类型也可以在主题源码中声明精确字重。
未采纳:直接在每个组件调用处接受任意数值,这会使应用源码与某种字体耦合,并绕过主题的所有权。
DEC-6 — 明确说明主题生成的 TypeScript 的局限性¶
参考: spec:AST-024/DEC-6
决策者: rubyycheung, 2026-09-04
导入主题生成的声明后,该主题的自定义 Heading 名称在整个 TypeScript 程序中可用。但这并不能证明每次使用周围都有匹配的 Theme 处于激活状态。运行时样式仍以主题为作用域;不匹配时保留语义层级基线;开发工具在能可靠识别时发出警告。
未采纳:承诺提供可感知 Provider 的静态类型,而 TypeScript 模块扩充无法保证这一点。
DEC-7 — 允许部分视觉角色¶
参考: spec:AST-024/DEC-7
决策者: rubyycheung, 2026-09-04
自定义 Heading 类型可以有意识地只更改一个受支持的视觉属性,并从其语义层级继承其余属性。它必须至少包含一条有效声明,但不必重新声明字体大小和行高。
未采纳:要求每个自定义类型都成为完整的排版替代方案,这会让细微的主题变化变得不必要的重复。
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 as/astryx