跳转至

排版保持归主题所有的系统规范

{
  "paths": ["packages/core/src/**", "packages/lab/src/**", "packages/themes/**"]
}

意图

设置了自身文本大小的人,会在每个 Core 和 Lab Web 组件中看到该设置,无论使用什么主题;未设置的人则看到主题所选的字族和大小。没有任何组件会换成平台字体或自己的文本大小。当某个随附的 Astryx 主题没有用于正文的品牌字体时,它可以使用平台自带的正文文本字体,使文本读起来与该用户设备上的其余文本一致。

非目标

  • 品牌主题使用哪种字体;品牌保留自己的字体。
  • 字体层级本身:design:typography-hierarchy 和 design:mobile-typography 负责角色、大小和移动端阅读基准。

需求

  • FR1 — 组件绝不覆盖排版。 任何 Core 或 Lab Web 组件都不会为其渲染的文本设置字体族、字体大小或行高,除非通过主题的排版 token;从周围文本继承的值视为合规。这包括平台字体关键字(如 -apple-system-body)和系统字体栈:组件绝不在任何指针设备上直接应用它们。一个仅用于测量平台文本样式的隐藏内部元素不渲染任何文本,因此合规。用于给图标设置大小的字体大小(例如 spec:AST-087 FR10 大小下的 1em 图标)不属于文本排版。原生组件遵循平台自身的文本设置(spec:AST-082 FR11)。组件设置的值只能来自主题。唯一的例外是当前 family 记录要求的大小下限,例如 family:input-fields FR9 的 iOS 16 px 文本输入下限。
  • FR2 — 无品牌的随附主题可以使用系统正文字体。 正文未使用品牌字体的 Astryx 随附主题可以将其正文字体 token 设置为平台的系统正文字体族,例如 system-ui 或 Apple 的系统字体。品牌主题则在正文中保留其品牌字体。该选择存在于主题的 token 值中,因此组件无需修改即可采用(FR1)。

  • FR3 — 用户设置的文本大小优先;否则使用主题的。 当用户通过 iOS Dynamic Type、浏览器默认字体大小或缩放设置了文本大小时,Core 和 Lab 的 Web 文本在每种主题下都会跟随该设置,包括品牌主题:主题的大小从用户设置的大小按比例缩放,每个角色保持其顺序,字族仍是主题的。当用户未设置,或平台没有给出信号时,文本使用的正是主题的字族和大小。跟随该设置不会增加任何公开主题选项、prop 或文档属性,也不会改变文档根的字体大小(design:mobile-typography DR4)。用户设置的大小会替代 design:mobile-typography DR1 的移动端阅读基准,无论更小还是更大,且 DR2 的固定值不适用:每个角色都从该大小缩放;未设置时适用 DR1 和 DR2,而 family:input-fields FR9 的 iOS 文本输入下限仍然成立。在 Android 上,Core 从 env(preferred-text-scale) 读取系统字体缩放比例,并按该比例缩放每个字体大小,因此整个字体层级无需切换即可跟随(DEC-3、DEC-4)。带有 <meta name="text-scale" content="scale"> 的页面已经在其根字体大小上带有系统字体缩放比例,Astryx 从该比例出发,因此 Core 不再额外添加(在 Android 上的 Chromium 159.0.8142.0 中,根字体大小跟随该 meta;带该 meta 的 Android 版 Chrome 在当前稳定版中未经验证)。

  • FR4 — 更大的文本保持可用。 在主题大小的 200% 以内,每个组件都保留其全部内容和功能(WCAG 2.2 成功标准 1.4.4)。超过 200% 时,阅读文本继续增大;密集控件(如标签页、徽章、表格单元格或分段控件)中的标签可以在 200% 处停止增大。控件应随其文本增长,而不是保持固定高度,因此其高度绝不会裁剪标签;组件记录已定义的截断(如 component:Badge FR3、component:Button FR5 或 component:Token FR7 的省略号)仍然适用。

平台支持

  • 支持的功能/引擎下限:该包支持的浏览器(spec:AST-013 FR1, FR3)。引擎无法识别的平台字体关键字会回退到主题字体栈的其余部分。
  • 不支持的行为:除上述字体回退外没有其他。
  • 浏览器证据(spec:AST-013 FR10):iOS 上的 Safari 证明 FR2 主题在系统正文字体下的正文文本,以及 FR3 在各类 Dynamic Type 大小下的行为;Android 上的 Chromium 159.0.8142.0(模拟器)证明 FR3 在系统字体缩放比例下、有和没有 text-scale meta 时的 Android 行为;Android 17 上的 Chrome 156 在 Pixel 8 设备上证明在没有该 meta 时、系统字体缩放比例为 1.0、1.3 和 2.0 下的行为;桌面浏览器证明 FR3 在其默认字体大小和缩放下,以及 FR4 在 200% 及以上的行为;token 和源码检查证明 FR1。

当前状态影响

  • Core 的默认正文字体是系统字体栈,这是 FR2 允许的无品牌值。每个随附的主题包都设置一种品牌正文字体并保留它。
  • 目前有些组件在主题之外设置排版,例如 Lab 的 Sankey 标签直接使用 system-ui,以及一些 Core 和 Lab 组件自行设置大小或行高;根据 FR1,这些是合规性差距。
  • architecture:theme-tokens:在每个第一方主题中,文本大小 token 均保持 rem。当设置了用户文本大小时,间距和元素大小 token 保持其值;控件在 FR4 下随文本增长。
  • FR3 和 FR4 下的缺陷:
    • iPhone 上的 Safari 在每种主题下都跟随 Dynamic Type,这一点已在当前实现的 iOS 模拟器中记录。iPad 上的 Safari 和其他 iOS 浏览器未经验证,macOS Safari 在其默认文本大小下的行为是已记录的后续验证。
    • 控件保持固定高度,例如 40 px 元素、component:Badge FR1 的块大小、component:Token FR1 的元素大小,以及 family:input-fields 中 InputGroup 的行高,因此更大的标签可能溢出;这些记录在 FR4 下将其大小视为最小值。

验证

契约 验证 代表性状态 变异或失败预期
FR1 对 Core 和 Lab 组件样式进行源代码检查,并对 token 进行审查。 组件样式中渲染文本的字体族、字号和行高;一个继承值;1em 图标大小;粗指针和细指针;平台字体关键字;iOS 文本输入下限 Core 或 Lab Web 组件在排版 token 之外且非通过继承的方式设置其渲染文本的字体族、字号或行高,或直接应用平台字体关键字;图标大小、字体族下限,以及仅用于测量平台文本样式的隐藏内部元素不属于失败情况。
FR2 主题 token 审查,以及在 iOS 上 Safari 对顶级文档的检查。 一个使用系统正文字体族的随产品发布的无品牌主题;一个品牌主题;默认主题 品牌主题的正文字体被系统字体替换,或组件应用系统正文字体而不是主题 token。
FR3 iOS 上 Safari 横跨各 Dynamic Type 类别;Android 模拟器中 Chromium 159.0.8142.0,系统字体缩放 1.3,带有 <meta name="text-scale" content="scale">(实测根字号 21 px;rem 大小随之缩放)、不带该 meta(根字号 16 px),以及不带该 meta 且默认缩放 133%(根字号 16 px,页面缩放);Pixel 8 硬件设备上 Android 17 中的 Chrome 156,不带 text-scale meta,系统字体缩放 1.0、1.3 和 2.0,并搭配无品牌主题和有品牌主题(无品牌 body 分别为 16 px、20.8 px 和 32 px,缩放一次;在 1.0 时文本保持主题大小);Android 上当前稳定版 Chrome 未验证该 meta;dynamicType.test.ts(引擎没有 -apple-system-body 时,每个缩放级别都会读取 env(preferred-text-scale);在带 text-scale meta 的页面上则均不读取);Android 上系统字体缩放 1.3 时的 Chromium 159.0.8142.0,结合 Core 的读取:不带 meta 时,根字号 16 px,body 20.8 px,display-1 54.6 px;带 meta 时,根字号 21 px,body 21 px,display-1 55.125 px,无双重缩放;在 1.0 时,无论是否带 meta,尺寸都与 main 一致;桌面浏览器使用较大默认字号并进行缩放;主题审查;scripts/check-theme-text-size-units.test.mjs(没有任何第一方主题以 px 设置文本大小或字号) 一个有品牌主题和一个无品牌主题;未设置大小;默认类别;在每个平台上设置大小;Android 带和不带 text-scale meta;macOS Safari 使用默认文本大小,其固定的 13 px Body 不命名任何类别,因此每个缩放级别都保持为 1(dynamicType.test.ts;浏览器读取为已记录的后续工作) 忽略用户设置大小的文本;当未设置任何大小时,与主题字族或大小不一致的文本(family:input-fields FR9 iOS 文本输入下限除外);主题字族被替换;公开选项、prop 或文档属性;根字号被更改
FR4 桌面浏览器在 200%、250% 和 300% 文本大小下,外加 iOS 上的 Safari 在辅助功能类别下 阅读文本;按钮、文本输入、标签页、徽章、表格单元格和分段控件 在 200% 或更低时丢失内容或功能;标签在任何大小下被其控件高度裁剪;控件保持固定高度而文本增长

决策日志

DEC-1 — 排版属于主题;无品牌随附主题可以使用系统正文字体

参考: spec:AST-102/DEC-1 决策者: cixzhang, 2026-10-24

组件若换成平台字体或自己的文本字号,就会破坏该表面的主题排版,而且产品无法查看或调整它。将组件文本的字族、字号和行高保留在主题令牌中,意味着由主题为该文本做决定。当某个随附主题没有品牌字体时,系统正文字体对阅读者来说是最熟悉的选择,因此这些主题可以通过自己的令牌使用它;品牌则保留自己的字体。

已拒绝:组件直接应用诸如 -apple-system-body 之类的平台字体。

DEC-2 — 用户设置的文本字号在所有主题中优先

参考: spec:AST-102/DEC-2 决策者: cixzhang, 2026-10-25

设置了文本字号的人希望在处处都看到该字号;未设置的人则期望看到应用选择的字体。因此,每个主题(包括品牌主题)都遵循用户设置的字号,同时保留自己的字族和相对于该字号的缩放比例;当未设置字号时,则使用主题自身的精确字号。大字号文本在任何地方都应保持可用至 200%,密集控件可以在 200% 处停止缩放,但不能截断文本。

已拒绝:仅让无品牌或选择加入(opt-in)的主题遵循用户设置的字号。

DEC-3 — 遵循用户设置的字号不增加公共接口面

参考: spec:AST-102/DEC-3 决策者: cixzhang, 2026-10-25

用户设置的字号默认生效,因此产品无需任何开关来开启它。Core 在平台仅通过系统文本样式暴露该字号的地方读取它(如在 iOS 上),并在其他环境中让根字体大小承载它;这两种读取方式都不是主题选项、prop 或文档属性。

已拒绝:为该字号提供公共的选择加入选项或文档属性。

DEC-4 — Android 的系统字体缩放以相同方式读取

参考: spec:AST-102/DEC-4 决策者: 规范一致性裁定,2026-11-09,应用 DEC-3

当平台仅通过 env(preferred-text-scale) 暴露用户设置的字号时(如 Android 上的 Chromium),Core 也会在那里读取它,因此产品仍然无需开关;带有 <meta name="text-scale" content="scale"> 的页面已经在其根字体大小上承载了该字号,所以 Core 不会额外添加。与 DEC-3 的读取方式一样,它不是主题选项、prop 或文档属性。

待解决问题

无。

本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 as/astryx