跳转至

包样式表分发系统规范

{
  "paths": [
    "packages/build/src/next.js",
    "packages/build/src/next-postcss.js",
    "packages/build/src/source-stylesheet.js",
    "packages/build/src/turbopack-loader.js",
    "packages/build/src/next.turbopack.test.mjs",
    "packages/build/src/source-stylesheet.test.mjs",
    "packages/build/scripts/turbopack-speed.mjs",
    "packages/build/__fixtures__/next-app.mjs",
    "packages/build/__fixtures__/next-turbopack/src/app/globals.css",
    "packages/build/__fixtures__/next-turbopack/src/app/page.tsx"
  ]
}

意图

使用 Astryx 的产品会加载预构建样式表:@astryxdesign/core/astryx.css、它使用的每个其他 Astryx 包的样式表,以及一个主题样式表。这些文件构成了 Astryx 组件 CSS 的全部,加载它们就是默认设置。产品也可以改用 @astryxdesign/build 编译 Astryx 包源码,可以是包的每个模块,或只编译产品实际发布的那些模块;该构建会生成预构建样式表所持有的规则,并放在同一层中。Next.js 产品通过 withAstryx() 在 webpack 或 Turbopack 下完成此操作,适用于它使用的每个带样式的 Astryx 包,并且产品自己的 CSS 仍然优先于每一条 Astryx 规则。

每个包样式表都将其规则放在同一层叠层中,并遵循相同的层顺序。因此,无论哪个包为元素提供了样式,也无论哪个样式表先加载,主题覆盖都会优先于每个包的基础样式。

非目标

  • 主题样式表包含什么内容,由 architecture:theme-compilation、spec:AST-034 和 spec:AST-050 负责。
  • 包样式表包含哪些 StyleX 变量组,由 spec:AST-066 FR3 负责。
  • 产品如何编译自己的代码,包括它为自己的样式或通过 astryx swizzle eject 的组件所使用的任何 StyleX 设置;但若 swizzle 后的副本的规则落在 @astryxdesign/build 之下,则除外(FR5、FR7)。
  • @astryxdesign/build 如何通过除 withAstryx()(FR9)之外的方式接入打包器,以及源码构建如何选择包中要编译的模块子集。
  • 压缩或缩小样式表。
  • 满足此契约的等效内部实现仍然有效。

需求

  • FR1 — 每个已发布的包都提供一个预构建样式表。 每个已发布的、其模块带有样式的 @astryxdesign/* 包 MUST 从包的某个 .css 子路径导出一个预编译样式表。该样式表包含其模块使用的每条规则。一个包在其首个带有样式的已发布版本中随附其样式表。各包的样式表如下:

    包 样式表
    @astryxdesign/core @astryxdesign/core/astryx.css
    @astryxdesign/lab @astryxdesign/lab/lab.css
    @astryxdesign/richtext @astryxdesign/richtext/richtext.css
    @astryxdesign/charts @astryxdesign/charts/charts.css,从其首个已发布版本开始

主题包不属于此要求;它们的样式表遵循非目标中提到的主题记录。

  • FR2 — 预构建样式表在无编译器的情况下也完整。 加载包的样式表以及 astryx.css 和一个主题样式表时,MUST 在包支持的每个状态、配色方案和文本方向下,为包渲染的每个元素提供样式,且产品的构建中不需要 StyleX 编译器。非 Core 样式表依赖 astryx.css 来提供其声明的 Core 定义,例如变量组和关键帧,并且不重复 astryx.css 已声明的定义。astryx.css 根据 spec:AST-066 FR3 省略的某个 Core 组,由读取该组的包的样式表来承载。

  • FR3 — 每个包样式表都只有一个层和一个层顺序。 每个包样式表中的每条规则,以及 Core 的 reset.css 中的每条规则,MUST 位于其唯一的 Astryx 层内:包样式表使用 astryx-base,reset.css 使用 reset。这些文件中的任何一个都不得输出未分层规则或其他层。每个文件都以主题输出在 spec:AST-066 FR7 下携带的相同顺序注册开头:

@layer reset, astryx-base, astryx-theme;

因此,无论哪个 Astryx 样式表先加载,reset < astryx-base < astryx-theme 都成立,并且作者编写的主题覆盖优先于每个包的基础规则。产品的未分层 CSS 保持在所有 Astryx 层之上。

  • FR4 — 样式表在打包后仍然有效。 每个包的 exports MUST 在其打包后的包中解析其样式表子路径,并且其 sideEffects 声明 MUST 覆盖该文件,以便打包器保留产品的 import '@astryxdesign/<package>/<name>.css'。

  • FR5 — 文档中的默认设置会默认加载预构建样式表。 文档中的每条默认消费者设置路径(纯 CSS、Tailwind,以及编译自己的 StyleX 的产品,包括已 eject 的组件)MUST 加载产品所使用的每个 Astryx 包的预构建样式表,除了在 FR9 下从源码编译的包——其规则来自产品的编译输出,且构建既不导入也不打包该包的预构建样式表——外加一个主题样式表;文档 MUST 将这些路径呈现为默认设置。默认设置如下:

@layer reset, astryx-base, astryx-theme;

@import '@astryxdesign/core/reset.css';
@import '@astryxdesign/core/astryx.css';
@import '@astryxdesign/richtext/richtext.css'; /* each package used */
@import '@astryxdesign/theme-neutral/theme.css';

在 @astryxdesign/build 下,某个 swizzled 副本的文件夹中若包含 astryx-swizzle.json 标记,该副本将通过 library pass 构建,因此其规则会落入 astryx-base,位于 astryx-theme 之下(spec:AST-110 FR5);原版 StyleX 插件没有 library pass。

文档也可以将源码构建作为默认设置之外的一种替代方案:在 FR7(以及针对 withAstryx() 的 FR9)下,通过 @astryxdesign/build 编译一个或多个包的源码,各自替代该包的预构建样式表,而产品继续加载 Core 的 reset.css、一份主题样式表,以及所有未做源码构建的包的预构建样式表。任何文档化的设置都不会同时加载某个包的预构建样式表和编译该包的源码,也不会以任何其他方式编译 Astryx 源码(例如将 Astryx 包源码加入产品自身的 StyleX 编译器输入)。

  • FR6 — 每个包都记录其导入方式。 每个包的 README 和样式概述 MUST 指明该包的样式表,并在 astryx.css 旁边展示该导入。

  • FR7 — 源码构建产出与预构建样式表相同的内容。 包的源码构建对于其编译的模块 MUST 生成与预构建样式表相同的规则、相同的选择器和相同的顺序,所有规则都位于一个 @layer astryx-base 内,且没有嵌套层。源码构建发出的每个包块都以 FR3 的顺序注册开头,因此无论哪个 Astryx 文件或分块最先加载,顺序都能保持,并且绝不依赖产品编写的一行代码。编译包的每个模块会复现其预构建样式表的规则;只编译子集则产生这些模块所使用的规则。Core 的源码构建始终包含其他包的预构建样式表在 FR2 下所依赖的 Core 定义,例如变量组和关键帧。产品规则保持在 astryx-base 之外,但 swizzled 副本的规则除外:位于包含 astryx-swizzle.json 标记的文件夹下的模块,会在 library pass 中编译进 astryx-base(spec:AST-110 FR5)。源码构建除了包自身源码之外不需要任何数据,并且在开发构建和生产构建中同样成立。

  • FR8 — 样式表增长按组件汇报并设定预算。 每个加载包预构建样式表的产品都会加载该表的全部内容(FR1),因此组件新增的 CSS 会到达每个这样的产品,包括从不渲染该组件的产品。每个修改包中样式化模块的拉取请求 MUST 以 base 对 head 的方式,报告其更改的每个包样式表的 gzip 大小,以及每个发生更改的组件的 gzip CSS 增量。仅在粗指针设备上运行且为单个组件增加超过 1 KB gzip CSS 的功能会被标记,其拉取请求需说明该成本;这些 CSS 仍保留在包样式表中(FR1、FR2)。大小按默认压缩级别下的 gzip 计算,1 KB 为 1,024 字节。组件的 CSS 增量是 head 处其模块贡献给包样式表的规则的 gzip 大小减去 base 处的同一大小。对应的 JavaScript 报告与预算,以及共享值表只交付组件所使用的行的规则,属于 architecture:component-style-authoring INV6。

  • FR9 — withAstryx() 按顺序从源码编译每个带样式的包。 来自 @astryxdesign/build/next 的 withAstryx() MUST 在 webpack 和 Turbopack 下,从源码构建产品所使用的每个带有样式化模块的已发布 Astryx 包:即 FR1 包、Core、Rich Text、Lab 和 Charts(从其第一个发布版本开始)。主题包保留其预构建主题样式表。

    • 真正的源码。 每个经源码构建的包的规则,都来自在产品构建中编译该包自身源码,并使用其预构建样式表所采用的编译设置(FR7);产品自身的 StyleX 设置绝不应用于 Astryx 源码。该构建既不导入也不打包其从源码编译的包的预构建样式表,并且宁可失败,也绝不从该样式表取用任何规则。

    • 顺序。 每条 Astryx 规则都位于 @layer reset, astryx-base, astryx-theme 内:Core 的 reset.css 在 reset 层,每个包的编译块在 astryx-base 层,主题在 astryx-theme 层。每个编译块都以 FR3 的顺序注册开头(FR7)。产品 CSS(包括产品自身的 StyleX 输出,但带标记的 swizzled 副本除外(FR7))保持无层,并且无论任何分块或加载顺序,都能胜过每条 Astryx 规则。非 Core 块按 FR2 依赖 Core 的变量和关键帧。

    • 样式表入口(Turbopack)。 产品在其 PostCSS 配置中列出 PostCSS 插件 @astryxdesign/build/next/postcss,并在其全局样式表中放入一条 @astryx; 规则。在 Turbopack 下,该插件 MUST 用每个经源码构建的包的块替换该规则,按包顺序排列。

    • 快速路径(Turbopack 目标,已知差距)。 目标是让 Astryx 模块在 Turbopack 的原生管线中完成编译:不通过 turbopack.rules JavaScript 加载器、Babel 或 PostCSS 步骤编译任何 Astryx 模块,并且 Astryx 规则通过 Turbopack 自身的 CSS 处理到达页面。该管线内目前没有受维护的 StyleX 编译器在运行,因此在这样的编译器出现之前,Turbopack 构建可以(MAY)通过运行带 StyleX Babel 插件的 Babel 的 turbopack.rules JavaScript 加载器来编译 Astryx 模块。该路线上的其他所有 FR9 规则仍然成立。

    • 速度预算(Turbopack)。 与未进行源码编译(加载预构建样式表)的同一应用相比,五次运行的中位数为:next dev 冷启动至多 +15%,热更新至多 +10%,next build 至多 +20%。每次对 build 包做出更改时都会测量并报告这些数值。在加载器路线使用期间,该预算不构成阻塞;一旦原生路线存在,它就成为一项要求。

    • Webpack。 webpack 源码构建满足真正的源码和顺序规则;快速路径目标和速度预算仅适用于 Turbopack。

平台支持

  • 支持的功能/引擎基线:未改变;主题和重置样式表已经要求使用级联层(cascade layers)。
  • 不支持的行为:未新增。
  • 浏览器证据:FR2、FR3、FR7 和 FR9 有真实浏览器的计算样式验证。FR1、FR4、FR5 和 FR6 在包、打包器和文档层面得到验证。FR8 由拉取请求大小报告验证。

当前状态影响

  • Core、Lab、Rich Text 和 Charts 各自已导出一份样式表,所有规则都在 @layer astryx-base 内部。非 Core 样式表省略了 astryx.css 声明的 Core 变量组。Core 的预构建样式表携带规范 data-token 组;Lab 依赖该样式表且不添加副本,依据 spec:AST-066 FR3。
  • reset.css 和每个包样式表(astryx.css、lab.css、richtext.css、charts.css)都以 FR3 顺序注册开头,因此预构建文件在任何加载顺序下都能保持该顺序。
  • Core、Lab、Rich Text 和 Charts 各自声明了 sideEffects,覆盖 **/*.css(FR4)。
  • 样式概述只记录了预构建路径。通过 @astryxdesign/build 的源码构建尚未在该处记录(FR5)。
  • @astryxdesign/build 与 FR7 冲突:它将 Astryx 规则处理为 astryx-base 内的嵌套优先级层;它在编译 Astryx 模块时使用 astryx 类名前缀,而预构建样式表使用 StyleX 默认的 x;其 Vite 构建的 Lightning CSS 阶段和 PostCSS 辅助工具的 Autoprefixer 阶段会添加预构建样式表所没有的 -webkit- 声明;其 Vite 插件会向每个页面注入自己的层序注册(包含 product 层);并且没有任何机制让 Core 源码构建带上预构建 lab.css 所依赖的 Core 定义。要符合相关要求,需要改变它为当前用户生成的类名和层。
  • 在 Turbopack 下,withAstryx() 会源码构建 Core、Lab、Rich Text 和 Charts;每个编译后的块都以 FR3 顺序注册开头(FR7),当产品导入其所编译包的预构建样式表时,构建会失败。@astryxdesign/build/next/postcss 会用这些块替换应用样式表里的 @astryx; 标记,并以与加载器相同的方式,用 Babel 和 StyleX 插件对每个包的模块进行第二次编译。一个 Next.js fixture 在 Turbopack 下检查 FR9,@astryxdesign/build 中的一个脚本则测量速度数据。
  • 在 webpack 下,withAstryx() 尚未满足 FR9(存在实现缺口):它使用上述 @astryxdesign/build 设置源码构建 Core 和 Lab,而 Rich Text 和 Charts 仍使用其预构建样式表;该源码构建在其自身输出中不发出顺序注册(FR7),而是依赖 reset.css、主题或产品中的那一行。关闭这些缺口会改变现有 webpack 输出。
  • 针对 swizzled 副本的 FR7 例外适用于 Babel、PostCSS 和 Vite 集成。Turbopack 下的 withAstryx() 不读取 astryx swizzle 写出的 astryx-swizzle.json 标记(FR5、FR7)。在 webpack 下,withAstryx() 使每个应用模块依赖其上方的标记路径,因此当某个副本的标记出现或消失时,缓存的构建会重新编译该副本(FR7)。
  • 在 Turbopack 下,没有受维护的 StyleX 编译器在本机流水线中运行,因此 FR9 快速路径是一个存在已知缺口的目標:Turbopack 路由通过运行 Babel 和 StyleX Babel 插件的 JavaScript 加载器编译 Astryx 模块,速度预算是报告而不是强制执行。

  • Lab、Rich Text 和 Charts 仅在各自的 README 中记录其样式表;样式概述的导入表只列出 Core(FR6)。

  • 拉取请求大小报告不测量任何样式表,因此不报告 CSS 大小或增量,也不会标记仅涉及改动的 CSS(FR8)。其 JavaScript 数值是组件的 re-export 文件,而不是其 import 实际引入的内容;其 before 和 delta 列始终为空,且没有任何机制标记仅涉及改动的 JavaScript(architecture:component-style-authoring INV6)。
  • styling-overview、getting-started 和 migration-setup 消费者文档会变更。除此之外,包样式表规则和类名保持不变。

验证

契约 验证 代表性状态 变异或失败预期
FR1 包清单和样式表构建测试 每个带有样式模块的已发布包;模块的规则位于其包样式表中 带样式的已发布包没有 .css 导出;某个模块使用的规则缺失
FR2 不使用 StyleX 编译器的真实浏览器计算样式 每个包中的一个代表性组件;默认、悬停、聚焦、禁用、暗色和从右到左 移除包样式表会改变计算样式;非 Core 样式表重复了 astryx.css 声明的分组
FR3 样式表结构测试和真实浏览器级联 每个包样式表和 reset.css;主题在最前和最后;包样式表按任意顺序;reset.css 在最后;一个主题覆盖 一条未分层规则或另一分层;注册缺失或顺序改变;主题覆盖在任何加载顺序下失效
FR4 打包后的包和打包器测试夹具 生产打包产物中每个包的样式表导入 子路径无法从打包后的包中解析;打包产物丢弃样式表
FR5–FR6 使用者文档检查 样式概述、入门和迁移设置中的每个设置片段;每个包的 README 默认设置省略了 astryx.css 或某个已使用的包样式表;某个设置加载预构建样式表并编译同一包的源码;缺少包导入
FR7 构建包编译测试与真实浏览器级联 每个 Core 模块均通过构建包编译;模块子集;开发构建;Core 源码构建与预构建的 Lab 样式表并存;在主题覆盖下的源码构建组件 全模块编译与预构建的规则或顺序不一致;某条 Astryx 规则位于嵌套或其他层中;主题覆盖失效
FR8 针对基线的拉取请求体积报告 一个样式发生变化的组件;一个仅触控特性为一个组件增加 0.9 KB 和 1.1 KB gzip CSS;一个没有样式变更的拉取请求 变更后的包样式表或组件没有 base 对比 head 的 gzip 数值;一个仅触控特性每个组件超过 1 KB gzip CSS 但未被标记
FR9 在 Turbopack 和 webpack 下使用 Next.js 夹具应用,进行真实浏览器计算样式、构建跟踪与耗时检查 一个引入 Core、Rich Text、Lab 和 Charts 的夹具应用,在每种打包器下通过 next dev 和 next build 构建;按包分别有一个产品 class 和覆盖基础规则的产品 StyleX 规则,以及一个覆盖基础规则的主题;chunk 顺序被反转且产品的顺序行被移除;构建前从已安装包中删除所有预构建包样式表;与基于预构建样式表的同一应用进行速度对比 产品覆盖或主题覆盖失效;删除的预构建样式表破坏构建或改变计算样式;产出的选择器与源码编译结果不同;某包的编译块缺少顺序注册;缺少速度数据(只有在存在原生 Turbopack 路径时,超出预算才会失败,并且会报告 Astryx 文件上的加载器数量)

真实浏览器级联检查使用一个主题会改变其基础颜色的组件,例如一个重新设置 destructive Button 样式的主题,并在每种加载顺序下断言该主题的颜色。

决策日志

DEC-1 — 预构建样式表为默认;源码构建以相同方式编译

Reference: spec:AST-080/DEC-1 Decider: cixzhang, 2026-10-15

大多数产品不需要为 Astryx 使用编译器,因此预构建样式表仍是默认,所有默认设置无需编译器即可工作。只想加载其发布模块的 CSS 的产品,可以通过 @astryxdesign/build 编译 Astryx 源码。第二次编译会在预构建样式表旁添加第二份规则副本,或以其他设置编译、或将其编译到另一层,从而破坏主题覆盖。源码构建会替换包的样式表,并以与预构建样式表相同的方式编译到同一个单一层中,因此包所发布并测试的级联得以保持。

已拒绝的方案:禁止源码构建,这会让产品无法只加载其使用的 CSS;以及从预构建样式表中移除规则并在其旁边附带数据,这会增加一种需要维护的格式,并形成构建相同规则的另一种方式。

DEC-2 — 每个包共享同一个层和同一顺序注册

Reference: spec:AST-080/DEC-2 Decider: cixzhang, 2026-10-15

主题覆盖针对的是组件,而不是发布该组件的包,因此每个包的基础规则都位于 astryx-base 中。每个样式表自行注册顺序,从而永远不依赖产品的第一行。

已否决:每个包一层,因为主题层的顺序将取决于产品加载了哪些包。

DEC-3 — 每个包提供一个完整样式表

引用: spec:AST-080/DEC-3 决策者: cixzhang,2026-10-15

每个包一个文件,让接入只需每个包一次导入,并且适用于所有框架。

已否决:由组件模块导入样式表,因为有些框架不会加载依赖模块导入的样式表。

DEC-4 — 每次变更都报告组件体积,并为触控专用工作设定预算

引用: spec:AST-080/DEC-4 决策者: cixzhang,2026-10-24

由于每个包的预构建样式表整体发布(DEC-3),并且是默认配置(DEC-1),仅触控设备使用的功能的 CSS 仍然会让该配置下的每个桌面产品承担成本,而且除非每次变更都报告,否则没有人能看到这一成本。每个 pull request 上按组件报告让增长可见,既包括组件导入所引入的 JavaScript,也包括其 CSS。超过每个组件 2 KB(gzip)JavaScript 或 1 KB(gzip)CSS 的触控专用工作会被标记:JavaScript 可以懒加载(仅在粗指针需要时),或者给出合理说明;而 CSS 因为留在样式表中,必须给出合理说明。共享的 JavaScript 值表只向组件发送它用到的行,因此一个组件的调优不会随其他所有导入一起被捎带。

已否决:将触控专用 CSS 拆分成单独样式表,因为这会破坏 DEC-3 保持的一次导入配置。

DEC-5 — 触控 JavaScript 来自共享的内部触控模块

引用: spec:AST-080/DEC-5 决策者: cixzhang,2026-10-26

超出预算的触控原语来自组件导入的共享内部触控模块(architecture:react-component-runtime INV13),页面只携带一次;或者其成本已给出合理说明;组件不会自行懒加载。没有安装步骤:这些模块始终存在。这取代了 DEC-4 的懒加载补救方案;其报告机制和预算仍然有效。

已否决:在每个组件内部懒加载,以及由应用安装模块。

DEC-6 — 源码构建覆盖 Turbopack 和所有带样式的包;快速路径是目标

引用: spec:AST-080/DEC-6 决策者: cixzhang,2026-11-01

Next.js 默认使用 Turbopack 构建,因此 withAstryx() 在支持 webpack 的同时也支持 Turbopack,适用于所有带样式的包,包括 Rich Text 和 Charts。支持意味着对包源码进行真实编译,并相对于产品样式保证 Astryx 的排序,而不是包装预构建样式表。理想情况下,Turbopack 构建保持使用 Turbopack 的原生流水线;目前没有受维护的 StyleX 编译器能在那里运行,因此接受 loader 路线,并记录这一差距,同时报告速度预算,直到出现原生路径。

已否决:继续不支持 Turbopack,这会让默认打包器上的产品缺少源码构建。

开放问题

无。

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