Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

spec(AST-080): source builds under webpack and Turbopack for every styled package (#9405)

Cindy Zhang0941aba9ec1e
diff --git a/docs/specs/AST-080-package-stylesheets/spec.md b/docs/specs/AST-080-package-stylesheets/spec.md
index 0f0e5d7c1a..dedd032d05 100644
--- a/docs/specs/AST-080-package-stylesheets/spec.md
+++ b/docs/specs/AST-080-package-stylesheets/spec.md
@@ -28,6 +28,9 @@ Those files are the whole of Astryx's component CSS, and loading them is the
default setup. A product can instead compile Astryx package source with
`@astryxdesign/build`, for every module of a package or only the ones it ships;
that build produces the rules the prebuilt stylesheets hold, in the same layer.
+A Next.js product does this with `withAstryx()` under webpack or Turbopack, for
+every styled Astryx package it uses, and its own CSS still wins over every
+Astryx rule.
Every package stylesheet places its rules in the same cascade layer under the
same layer order. A theme override therefore wins over the base styles of every
@@ -42,8 +45,9 @@ first.
`spec:AST-066` FR3.
- How a product compiles its own code, including any StyleX settings it uses for
its own styles or for components it ejects with `astryx swizzle`.
-- How `@astryxdesign/build` plugs into each bundler, and how a source build
- chooses which modules to compile.
+- How `@astryxdesign/build` plugs into a bundler other than through
+ `withAstryx()` (FR9), and how a source build chooses a subset of a package's
+ modules to compile.
- Minifying or compressing stylesheets.
- Equivalent internal implementations remain valid when they satisfy this
contract.
@@ -98,8 +102,11 @@ first.
- **FR5 — Documented setups load prebuilt stylesheets by default.** Each
default consumer setup path in the documentation (plain CSS, Tailwind, and a
product that compiles its own StyleX, including ejected components) MUST load
- the prebuilt stylesheet of every Astryx package the product uses, plus a theme
- stylesheet, and the documentation MUST present those paths as the default. A
+ the prebuilt stylesheet of every Astryx package the product uses, except a
+ package compiled from source under FR9, whose rules come from the product's
+ compiled output and whose prebuilt stylesheet the build neither imports nor
+ bundles, plus a theme stylesheet, and the documentation MUST present those
+ paths as the default. A
default setup looks like:
```css
@@ -113,7 +120,8 @@ first.
The documentation MAY also present a source build as an alternative to a default
setup: the source of one or more packages compiled through `@astryxdesign/build`
- under FR7, each in place of that package's prebuilt stylesheet, while the
+ under FR7 (and FR9 for `withAstryx()`), each in place of that package's
+ prebuilt stylesheet, while the
product keeps loading Core's `reset.css`, a theme stylesheet, and the prebuilt
stylesheet of every package it does not source-build. No documented setup loads
a package's prebuilt stylesheet and also compiles that package's source, or
@@ -127,9 +135,10 @@ first.
- **FR7 — A source build produces what the prebuilt stylesheet holds.** A source
build of a package MUST produce, for the modules it compiles, the same rules
with the same selectors in the same order as that package's prebuilt stylesheet,
- every one inside one `@layer astryx-base` with no nested layer. A source build
- emits no layer-order registration of its own; Core's `reset.css` and the theme
- stylesheet the product loads carry it (FR3). Compiling every module of a package
+ every one inside one `@layer astryx-base` with no nested layer. Each package
+ block a source build emits begins with the FR3 order registration, so the order
+ holds whichever Astryx file or chunk loads first and never depends on a line
+ the product writes. Compiling every module of a package
reproduces its prebuilt stylesheet's rules; compiling a subset produces the
rules those modules use. A source build of Core always includes the Core
definitions other packages' prebuilt stylesheets rely on under FR2, such as
@@ -153,12 +162,49 @@ first.
rule that a shared value table ships only the rows a component uses, are
`architecture:component-style-authoring` INV6.
+- **FR9 — `withAstryx()` compiles every styled package from source, in order.**
+ `withAstryx()` from `@astryxdesign/build/next` MUST build from source, under
+ webpack and under Turbopack, every published Astryx package with styled
+ modules that the product uses: the FR1 packages, Core, Rich Text, Lab, and
+ Charts (from its first published release). Theme packages keep their prebuilt
+ theme stylesheets.
+ - **Real source.** Each source-built package's rules come from compiling that
+ package's own source in the product's build, with the settings its prebuilt
+ stylesheet is compiled with (FR7); the product's own StyleX settings never
+ apply to Astryx source. The build neither imports nor bundles the prebuilt
+ stylesheet of a package it compiles from source, and it fails rather than
+ take a rule from that stylesheet.
+ - **Ordering.** Every Astryx rule sits inside
+ `@layer reset, astryx-base, astryx-theme`: Core's `reset.css` in `reset`,
+ each package's compiled block in `astryx-base`, and the theme in
+ `astryx-theme`. Each compiled block begins with the FR3 order registration
+ (FR7). Product CSS, including the product's own StyleX output, stays
+ unlayered and wins over every Astryx rule in any chunk or load order. A
+ non-Core block relies on Core's variables and keyframes as under FR2.
+ - **Fast path (Turbopack goal, known gap).** The goal is that Astryx modules
+ compile inside Turbopack's native pipeline: no `turbopack.rules`
+ JavaScript loader, no Babel, and no PostCSS step compiles an Astryx module,
+ and Astryx rules reach the page through Turbopack's own CSS handling. No
+ maintained StyleX compiler runs inside that pipeline, so until one exists the
+ Turbopack build MAY compile Astryx modules through a `turbopack.rules`
+ JavaScript loader that runs Babel with the StyleX Babel plugin. Every other
+ FR9 rule holds on that route.
+ - **Speed budget (Turbopack).** Against the same app built without source
+ compilation (loading the prebuilt stylesheets), median of five runs:
+ `next dev` cold start at most +15%, a hot update at most +10%, and
+ `next build` at most +20%. The figures are measured and reported on every
+ change to the build package. The budget does not block while the loader
+ route is in use; it becomes a requirement once a native route exists.
+ - **Webpack.** The webpack source build meets the real-source and ordering
+ rules; the fast-path goal and the speed budget apply to Turbopack only.
+
### Platform support
- Supported feature/engine floor: unchanged; cascade layers are already required
by the theme and reset stylesheets.
- Unsupported behavior: none added.
-- Browser evidence: real-browser computed styles for FR2, FR3, and FR7. FR1, FR4,
+- Browser evidence: real-browser computed styles for FR2, FR3, FR7, and FR9.
+ FR1, FR4,
FR5, and FR6 are proven at the package, bundler, and documentation layer. FR8
is proven by the pull-request size report.
@@ -169,12 +215,11 @@ first.
groups `astryx.css` declares. Core's prebuilt stylesheet carries the canonical
data-token group; Lab relies on that stylesheet and adds no copy, under
`spec:AST-066` FR3.
-- No package stylesheet and not `reset.css` carries the FR3 order registration
- today. The order holds only when the product writes the registration line
- itself; a product that loads `reset.css` after a package stylesheet without it
- places `reset` above `astryx-base`.
-- Lab, Rich Text, and Charts declare `sideEffects: false`, which does not cover
- their stylesheets (FR4). Core already covers `**/*.css`.
+- `reset.css` and every package stylesheet (`astryx.css`, `lab.css`,
+ `richtext.css`, `charts.css`) begin with the FR3 order registration, so the
+ prebuilt files hold the order in any load order.
+- Core, Lab, Rich Text, and Charts each declare `sideEffects` covering
+ `**/*.css` (FR4).
- The styling overview documents only the prebuilt path. A source build through
`@astryxdesign/build` is not yet documented there (FR5).
- `@astryxdesign/build` conflicts with FR7: it processes Astryx rules into nested
@@ -185,7 +230,17 @@ first.
injects its own layer-order registration, with a `product` layer, into each
page; and nothing makes a Core source build carry the Core definitions that
prebuilt `lab.css` relies on. Conforming changes the class names and layers it
- emits for its current users. Its Next.js integration runs only under webpack.
+ emits for its current users.
+- `withAstryx()` does not yet meet FR9 (implementation gaps): it refuses
+ Turbopack builds; under webpack it source-builds Core and Lab, while Rich Text
+ and Charts stay on their prebuilt stylesheets; and a source build emits no
+ order registration in its own output (FR7), relying on `reset.css`, the theme,
+ or the product's line. No fixture checks FR9 and no speed figures are
+ reported. Rich Text and Charts already publish `source` export conditions.
+- Under Turbopack no maintained StyleX compiler runs in the native pipeline, so
+ the FR9 fast path is a goal with a known gap: the Turbopack route compiles
+ Astryx modules through a JavaScript loader running Babel and the StyleX Babel
+ plugin, and the speed budget is reported rather than enforced.
- Lab, Rich Text, and Charts document their stylesheet only in their READMEs;
the styling overview's import table lists only Core (FR6).
@@ -199,15 +254,16 @@ first.
## Verification
-| Contract | Verification | Representative states | Mutation or failure expectation |
-| -------- | ---------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| FR1 | package manifest and stylesheet build tests | every published package with styled modules; a module's rules in its package stylesheet | a styled published package has no `.css` export; a rule a module uses is missing |
-| FR2 | real-browser computed styles with no StyleX compiler | a representative component from each package; default, hover, focus, disabled, dark, and right-to-left | removing the package stylesheet changes a computed style; a non-Core stylesheet repeats a group `astryx.css` declares |
-| FR3 | stylesheet structure tests and real-browser cascade | each package stylesheet and `reset.css`; theme first and last; package stylesheets in either order; `reset.css` last; a theme override | an unlayered rule or another layer; a missing or reordered registration; the theme override loses in any load order |
-| FR4 | packed-package and bundler fixtures | each package's stylesheet import in a production bundle | the subpath does not resolve from the packed package; the bundle drops the stylesheet |
-| FR5–FR6 | consumer-doc checks | every setup snippet in the styling overview, getting started, and migration setup; each package README | a default setup omits `astryx.css` or a used package stylesheet; a setup loads a prebuilt stylesheet and compiles the same package's source; a package import is missing |
-| FR7 | build-package compile tests and real-browser cascade | every Core module compiled through the build package; a subset of modules; a development build; Core source-built beside a prebuilt Lab stylesheet; a source-built component under a theme override | the every-module compile differs from the prebuilt rules or order; an Astryx rule sits in a nested or other layer; the theme override loses |
-| FR8 | pull-request size report against base | a component whose styles change; a touch-only feature adding 0.9 KB and 1.1 KB gzip CSS to one component; a pull request with no styled change | a changed package stylesheet or component with no base-against-head gzip figure; a touch-only feature over 1 KB gzip CSS per component that is not flagged |
+| Contract | Verification | Representative states | Mutation or failure expectation |
+| -------- | ------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| FR1 | package manifest and stylesheet build tests | every published package with styled modules; a module's rules in its package stylesheet | a styled published package has no `.css` export; a rule a module uses is missing |
+| FR2 | real-browser computed styles with no StyleX compiler | a representative component from each package; default, hover, focus, disabled, dark, and right-to-left | removing the package stylesheet changes a computed style; a non-Core stylesheet repeats a group `astryx.css` declares |
+| FR3 | stylesheet structure tests and real-browser cascade | each package stylesheet and `reset.css`; theme first and last; package stylesheets in either order; `reset.css` last; a theme override | an unlayered rule or another layer; a missing or reordered registration; the theme override loses in any load order |
+| FR4 | packed-package and bundler fixtures | each package's stylesheet import in a production bundle | the subpath does not resolve from the packed package; the bundle drops the stylesheet |
+| FR5–FR6 | consumer-doc checks | every setup snippet in the styling overview, getting started, and migration setup; each package README | a default setup omits `astryx.css` or a used package stylesheet; a setup loads a prebuilt stylesheet and compiles the same package's source; a package import is missing |
+| FR7 | build-package compile tests and real-browser cascade | every Core module compiled through the build package; a subset of modules; a development build; Core source-built beside a prebuilt Lab stylesheet; a source-built component under a theme override | the every-module compile differs from the prebuilt rules or order; an Astryx rule sits in a nested or other layer; the theme override loses |
+| FR8 | pull-request size report against base | a component whose styles change; a touch-only feature adding 0.9 KB and 1.1 KB gzip CSS to one component; a pull request with no styled change | a changed package stylesheet or component with no base-against-head gzip figure; a touch-only feature over 1 KB gzip CSS per component that is not flagged |
+| FR9 | Next.js fixture app under Turbopack and webpack, real-browser computed styles, build trace and timings | a fixture app importing Core, Rich Text, Lab, and Charts, built with `next dev` and `next build` under each bundler; per package, a product class and a product StyleX rule over a base rule, and a theme over a base rule; chunk order reversed and the product's order line removed; every prebuilt package stylesheet deleted from the installed packages before the build; speed against the same app on prebuilt stylesheets | a product override or a theme loses; a deleted prebuilt stylesheet breaks the build or changes a computed style; the emitted selectors differ from the source compile; a package's compiled block lacks the order registration; speed figures are missing (exceeding the budget fails only once a native Turbopack route exists, and the loader count on Astryx files is reported) |
The real-browser cascade check uses a component whose theme changes its base
colors, such as a theme that restyles the destructive Button, and asserts the
@@ -289,6 +345,22 @@ supersedes DEC-4's lazy-load remedy; its reporting and budget stand.
Rejected: lazy loading inside each component, and an app-installed module.
+### DEC-6 — Source builds cover Turbopack and every styled package; the fast path is the goal
+
+**Reference:** `spec:AST-080/DEC-6`
+**Decider:** `cixzhang`, `2026-11-01`
+
+Next.js builds with Turbopack by default, so `withAstryx()` supports it as well
+as webpack, for every styled package including Rich Text and Charts. Support
+means a real compile of package source with Astryx ordering guaranteed against
+product styles, not a wrapper around the prebuilt stylesheets. Ideally the
+Turbopack build stays on Turbopack's native pipeline; no maintained StyleX
+compiler runs there, so a loader route is accepted with that gap recorded and
+the speed budget reported until a native route exists.
+
+Rejected: keeping Turbopack unsupported, which leaves products on the default
+bundler without a source build.
+
## Open questions
None.