跳转至

主题适配

{
  "scope": "global",
  "triggers": {
    "theming": ["FR4", "FR5", "FR6", "FR7"]
  }
}

意图

主题应当表达针对环境条件的选择加入(opt-in)式 token 与组件适配,而无需第二个主题、手写媒体查询 CSS 或 React state。该系统命名为 adaptations,而不是 responsive,因为条件可能涵盖宽度、指针精度、对比度偏好、动画偏好,以及未来经评审的环境轴。

defineTheme({
  adaptations: {
    widthBreakpoints: {
      sm: 640,
      md: 768,
      lg: 1024,
      xl: 1280,
      '2xl': 1536,
    },
    rules: [
      {
        when: {
          width: {from: 'lg', below: 'xl'},
          pointer: 'coarse',
          contrast: 'more',
        },
        value: {
          components: {/* overrides */},
        },
      },
    ],
  },
});

widthBreakpoints 是命名点,表示宽度档位的起始位置。width.from 包含该点,width.below 不包含该点,因此 {from: 'lg', below: 'xl'} 正好是 lg 区间。when 中的字段按 AND 关系组合。

单独一个断点映射不会生成任何 CSS。只有包含适配值的规则才会生成 CSS。

非目标

  • 向捆绑主题中添加适配规则,或选择产品特定的值。
  • 为 FormLayout、布局原语或产品布局定义响应式策略。
  • 接受原始媒体查询字符串、用户定义的条件字段或用户定义的断点名称。新的环境轴仍然是显式的 API 扩展。
  • 更改颜色模式解析,或 MediaTheme 的 surface 检测及其含义。
  • 让响应式组件消费主题适配规则;组件可以解析共享的宽度点,但其行为仍由各自独立拥有。
  • 适配 canvas、数据可视化或其他 JavaScript 消费者使用的非 CSS token 读取;这些读取继续解析根主题值。

需求

  • FR1 — 宽度断点是固定的起始点。 每个主题都具有有效的 widthBreakpoints 映射 sm: 640、md: 768、lg: 1024、xl: 1280、2xl: 1536 CSS 像素,除非它为这些固定名称覆盖了值。这些值 MUST 是有限的、正数且严格递增。根值是 sm 之下的隐式基础;不存在可配置的 xs: 0 点。仅定义或覆盖该映射 MUST NOT 生成 CSS。
  • FR2 — 条件是命名、封闭且可组合的。 when 对象可以包含 width、height、pointer、contrast 和 motion;这些字段按 AND 关系组合。width 接受使用五个固定名称的 from 和 below,且 MUST 包含其中一个或全部。from 是包含的,below 是排他的;任一边界都可以省略,但不能同时省略两边,且有界的宽度 MUST 解析为 from < below。height 仅接受 {below: 500}:视口高度低于 500(不含 500),这是 FR9 紧凑定义的高度边界。pointer 接受 coarse | fine;contrast 接受 more | less | no-preference;motion 接受 reduce | no-preference。未来的环境字段需要显式扩展这个封闭词汇。
  • FR3 — 规则是命名对象。 adaptations.rules 包含 {when, value} 对象,而不是位置元组。空的 when 无效。若某个值在先前的规则之后必须在每个宽度下都生效,则由后续规则分别覆盖 {width: {below: 'sm'}} 和 {width: {from: 'sm'}} 来表达。没有改变任何值的规则可以不生成 CSS。
  • FR4 — 规则使用主题值契约。 value 可以包含 typography、color、radius、motion、tokens、components 和 localTokens 的覆盖。rules[].value.localTokens 不是登记表面:只有根 localTokens 或已登记的确切基础对象才能声明名称。规则只能替换已经在有效谱系中登记的准确名称,并使用 AST-006 的 TokenValue 规范化与校验。身份、继承、语法、图标、指示器、媒体表面字段、adaptations 以及 motion.reducedMotion(spec:AST-108 FR5)仍归根所有。在同一条规则内,值使用根的展开、深度合并和种类优先级。生成式轴会依据根轴元数据展开,并且每个生成的叶子都算作该规则的一次写入,除非是在有效根 components 上已声明的精确叶子路径处的不变形类型比例组件默认值。生成的 token 和由规则撰写的组件叶子仍然算是写入。缺失的必需比例字段 MUST 被显式提供,而不能由近似的内置默认值合成。规则中的组件写入 MUST 与根 components 使用相同的目标、轴、值域和扩展校验;adaptations 不定义单独的组件值校验策略。规则 MAY 为内置值或某个权威开放原语域所接受的值设置样式,即使有效根没有针对该目标或值的样式规则。其有效性依赖主题登记的值 MUST 已经登记在有效根 components 表面上;规则 MUST NOT 有条件地引入该值。来自共享根校验的未解析结果会原样带入 adaptation 校验。它既不是永久性的 adaptation 豁免,也不是该轴可扩展的证据。状态归组件所有,绝不会由主题生成。
  • FR5 — 媒体表面仍具有更高特异性。 适配值在根主题之上解析。当 onDark 或 onLight 覆盖与某个适配写入同一解析叶子时,媒体表面值获胜。adaptations 不会创建嵌套的媒体表面语法。
  • FR6 — 规则顺序决定优先级。 根值先于 adaptation 规则应用,但媒体表面覆盖除外,它们按 FR5 在规则之后应用。规则按声明顺序级联,每个解析后的 token 或组件叶子的最后一次匹配写入获胜。条件形状不会产生独立的特异性(specificity)分数。重复的 when 对象是有效的。重排有重叠的规则是有意的行为变更。当某个较早撰写的组件叶子的精确路径存在于根中时,后续的仅比例规则会保留该叶子;当该路径在根中不存在时,生成的组件叶子仍是一次写入,并且如果两条规则都匹配,则后者获胜。
  • FR7 — 主题扩展保留级联顺序。 子主题继承基础的宽度断点覆盖和有序规则。断点按名称合并。继承的规则保持其相对顺序,并根据子主题的有效映射解析;子主题规则追加在它们之后。没有移除操作符:空的子主题值是 no-op,继承的行为只能被后续写入受影响叶子的子主题规则抵消。子主题的根值永远不会覆盖匹配的继承规则,因为根值先于 adaptation 规则应用。
  • FR8 — AppShell 共享宽度点。 mobileNav.breakpoint 接受五个宽度断点名称以及 none。对于选定的名称,移动模式仅在 width < effectiveWidthBreakpoints[name] 时生效;相等时属于更宽的一侧。none 永不会匹配。AppShell 读取最近的 Theme 上下文;在没有 provider 上下文时,它遵循 architecture:theme-application 中的根主题回退;在没有活动主题时,它使用 FR1 默认值。defaultIsMobile 仍然是一个 SSR 提示;客户端查询在 hydration 后使用有效映射。
  • FR9 — Compact 在每个平台上只有同一个定义。 当屏幕的视口宽度低于有效的 md 点(FR1)或视口高度低于 500 时,该屏幕为 compact。这些数值在每个平台上都相同:Web 上是 CSS 像素,iOS 上是 point,Android 上是密度无关像素;原生展示不会将 compact 映射到平台尺寸类别。主题导出这唯一定义,所有按屏幕尺寸选择展示形式的解析器都使用它,包括 web 触控展示解析器、Selector 的 adaptive 展示以及 @astryxdesign/native;没有任何解析器保留自己的尺寸数值。还需要粗指针的解析器会将粗指针条件与 compact 进行 AND。Compact 只决定展示形式的选择,例如用 sheet 代替 popover;调用方选择的布局宽度,例如 AppShell 的 mobileNav.breakpoint(FR8),不是 compact。主题 adaptations 仅限 Web(spec:AST-082 FR18);原生端从可移植主题读取 compact 数值。
  • IR1 — 原子化地规范化并拒绝。 对于 defineTheme 和 astryx theme build,在任一者产生部分输出之前,同一条路径会校验宽度断点、命名条件字段、宽度范围、主题扩展、已登记的 local-token 名称以及具体展开值。defineTheme 在每个有效的 DefinedTheme 上保留规范化的生成式轴元数据;静态构建在 IR4 下保留相同的元数据。
  • IR2 — 适配值以 CSS 为先。 一旦主题样式表被应用,适配值仅从 CSS 解析,无需 JavaScript 重渲染、resize 监听器或 hydration 修正。运行时 Theme 注入和静态构建使用相同的规范化规则、作用域和级联。根值在规则之前生成;规则块保持声明顺序;在两者都适用时,媒体表面覆盖在规则之后生成。若合并、重排或丢弃规则块会改变级联,则输出 MUST NOT 合并、重排或丢弃规则块,包括重复的 when 对象以及在后续规则中恢复根值的情况。每个组件叶子都降级到与其根等价项相同的声明目标,包括派生的私有变量展开。useTheme token 读取和服务端安全的 token 辅助函数仍然是根值读取。
  • IR3 — 工具链能够看到仅存在于规则中的值。 校验、组件诊断、私有变量检查、字体提示以及 light-dark() 配色方案检测 MUST 检查仅声明在规则中的值。规则中的组件写入 MUST 与根组件写入通过相同的共享校验路径。adaptation 只增加“禁止条件登记”检查:仅通过主题登记而被接受的值 MUST 已经存在于有效根组件表面上。内置的有限值和被权威开放原语域接受的值不需要匹配的根样式声明。规则校验 MUST 自动继承未来对根校验的改进;工具链 MUST NOT 维护针对 adaptation 的白名单、未解析域例外或域推断路径。
  • IR4 — 构建后的主题保留扩展语义。 构建后主题的 JavaScript 模块保留实现源等价 extends 所需的有效宽度断点映射、规范化生成式轴元数据、已登记 local-token 谱系以及有序的规范化规则;它不嵌入生成的 CSS 文本。子主题从已构建的基础主题继承并解析 adaptations 的方式,与从源基础主题继承并解析完全相同。

平台支持

  • 适配在 Astryx 的浏览器支持底线内使用 viewport-width、viewport-height、primary-pointer、contrast-preference 和 reduced-motion 查询;没有 JavaScript 样式回退。
  • 真实 Chromium MUST 验证条件、嵌套、AppShell 一致性以及首次绘制。真实 Safari MUST 验证独占宽度边界和 primary-pointer 分类;仅靠 Playwright WebKit 不能作为 Safari 证据。

当前状态影响

当前的 main 没有主题适配 API。AppShell 仅导出 sm | md | lg | none,硬编码了前三个断点,并将相等视为移动端。本提案新增 xl 和 2xl,通过活动主题解析所有名称,并使上边界成为独占。AppShell 联合类型的扩展是增量的;相等性变更属于破坏性行为变更,实施时需附带相应的发布说明。

此变更影响 architecture:component-theming-surface、architecture:public-component-api、architecture:theme-authoring-contract、architecture:theme-compilation 和 architecture:theme-application。在本草案被接受并实施之前,它们当前的契约仍然具有权威性。

5543 的公开层 API 已被 DEC-1 和 DEC-2 取代,MUST NOT 按原样落地。其值解析器、显式值保留、CSS 生成/构建对等性以及扩展元数据仍然是有用的实施证据。

该主题不导出紧凑定义,且 when 没有 height 字段。Selector、MultiSelector、ContextMenu 和 DropdownMenu 的 adaptive 呈现(MoreMenu 转发到 DropdownMenu)以及 DropdownMenu 的紧凑触控子菜单决策使用 (max-width: 768px) and (pointer: coarse),而 ContextMenu 和 MoreMenu 的消费方文档将其描述为"768px 及以下":一个恰好 768 像素宽且高度至少 500 的粗指针屏幕被视为紧凑;而一个宽度超过 768 像素但高度低于 500 的横屏手机则不被视为紧凑。在 FR9 下,前者打开 popover,后者打开 bottom sheet;该变更的发布说明将 presentation 列为保持 surface 的方式。PortableTheme 不携带紧凑定义,@astryxdesign/native 也还没有紧凑解析器;它获得解析器后将采用 FR9。

验证

契约 验证 代表性状态 失败信号
FR1–FR3 宽度断点与条件矩阵以及浏览器边界 默认/覆盖;from/below/range;pointer/contrast/motion;多字段 AND;空/无规则 某个断点充当上界、区间出现间隔/重叠、字段以 OR 组合,或未使用的映射生成了 CSS。
FR4–FR7 共享解析器、surface、级联顺序和扩展测试 已注册/未注册的本地 token;不完整的缩放;有限内建项;根中缺失的开放原始值;根注册与仅规则的自定义值;未解析的共享结果;后生成的与先前的显式叶子;surface 冲突 规则注册了本地或组件值、有效开放值需要虚拟根规则、适配验证偏离根验证、未解析结果成为永久豁免,或继承顺序丢失。
FR8 Theme/AppShell 集成 所有名称/none;SSR 提示;无/最近/根/嵌套主题;精确边界 AppShell 使用了错误的映射、相等性或作用域。
FR2 (height)、FR9 条件矩阵加 web 和 native 上的解析器测试 高度 800 时宽度 767/768;宽度 1024 时高度 499/500;被覆盖的 md;Selector adaptive;web 触控解析器;native 解析器 解析器自带尺寸数值或包含性边界、native 解析器使用平台尺寸类别或不同数值,或接受了除 below: 500 以外的 height 值
IR1–IR3 运行时/构建与 CLI 正负样例 无效映射/范围/字段;源轴元数据;重复 when;恢复根规则的规则;有限/开放/未解析组件域;声明目标;根注册与仅规则自定义值;非 CSS token 读取 无效输入写出输出、根与适配组件验证不一致、独立有效的值被强制写入根、适配条件性地注册自定义值,或工具遗漏仅规则值。
IR4 生成模块的导入与体积测试 无规则/有规则;源码/构建的父级与子级;生成式/本地 Token 元数据 断点、规则、顺序或元数据丢失;扩展出现偏差;CSS 文本进入模块;或已解析的层重复。

决策日志

以下决策由 cixzhang 批准,作为当前已接受规范的一部分。

DEC-1 — 使用宽度特定断点的适配

参考: spec:AST-012/DEC-1 决策者: cixzhang,2026-09-02

使用 adaptations 而非 responsive 或 responsiveness,因为系统涵盖多个环境轴。宽度断点位于 widthBreakpoints 下,而非通用的 breakpoints 字段,从而为未来独立的 heightBreakpoints 命名空间预留空间。Astryx 拥有 sm、md、lg、xl 和 2xl,默认值分别为 640、768、1024、1280 和 1536。宽度断点标记层级的起点,在没有规则时不输出任何 CSS。

已拒绝:仅响应式命名、通用断点存储、自定义宽度名称,以及按上限命名的层级。

DEC-2 — 使用带有嵌套宽度条件的命名规则

参考: spec:AST-012/DEC-2 决策者: cixzhang,2026-09-02

规则使用 {when, value} 对象。width: {from, below} 表示包含下界和不包含上界。when 中的环境字段是平级的,并通过 AND 逻辑组合。

已拒绝:位置元组、扁平化的 minWidth / maxWidth、嵌套的字面量 @media 键,以及任意的原始查询。

DEC-3 — 将声明的规则顺序作为优先级

参考: spec:AST-012/DEC-3 决策者: cixzhang,2026-09-02

规则遵循层叠顺序。根值首先应用,继承的规则保持其顺序,子规则追加在后。在任何匹配的环境中,最后写入已解析叶节点的规则胜出。重复条件是有效的,重叠规则的重排属于有意的行为特性。

已拒绝:根据条件形状推断优先级,或对不可比较的条件进行冲突拒绝。

DEC-4 — 通过构建扩展保留适配

参考: spec:AST-012/DEC-4 决策者: cixzhang,2026-09-02

构建产物和源码主题为 extends 保留等价的宽度断点和规范化规则数据,而输出的 CSS 仍然是独立的产物。

已拒绝:从构建基底中编译掉编写意图,以及静默收窄现有的主题扩展契约。

DEC-5 — 复用根组件校验;为注册保留根

参考: spec:AST-012/DEC-5 决策者: cixzhang,2026-09-08

适配规则中的组件写入使用与根 components 相同的目标、轴、值域和扩展校验。内置的有限值或由权威开放基元域接受的值可以仅出现在规则中,不需要匹配的根样式声明。有效根要求仅当值的有效性来自主题注册时才适用。未解析的共享结果原样带入适配,未来对根校验的改进将自动收紧适配。

已拒绝:适配专属的值解析器、白名单、未解析域异常,以及为独立有效值设置的虚拟根规则。

DEC-6 — Compact 在每个平台上只有一个定义

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

手机、小平板以及较矮的横屏窗口都缺少容纳锚定表面的空间,因此 compact 定义为宽度低于 md 断点或高度低于 500。每个平台上使用相同的数值,可使同一组件在 Web 和原生代码中以相同方式呈现;单一导出的定义可防止解析器产生分歧。

已拒绝:将 compact 映射到各平台的尺寸类别,因为这样会使同一屏幕在一个平台上是紧凑模式,而在另一个平台上不是。

开放问题

无。

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