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.mdindex 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 thedefault 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 thesame 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 forits 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 thiscontract.@@ -98,8 +102,11 @@ first.- **FR5 — Documented setups load prebuilt stylesheets by default.** Eachdefault consumer setup path in the documentation (plain CSS, Tailwind, and aproduct 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. Adefault setup looks like:```css@@ -113,7 +120,8 @@ first.The documentation MAY also present a source build as an alternative to a defaultsetup: 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 theproduct keeps loading Core's `reset.css`, a theme stylesheet, and the prebuiltstylesheet of every package it does not source-build. No documented setup loadsa 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 sourcebuild of a package MUST produce, for the modules it compiles, the same ruleswith 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 packagereproduces its prebuilt stylesheet's rules; compiling a subset produces therules those modules use. A source build of Core always includes the Coredefinitions 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 requiredby 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. FR8is proven by the pull-request size report.@@ -169,12 +215,11 @@ first.groups `astryx.css` declares. Core's prebuilt stylesheet carries the canonicaldata-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 eachpage; and nothing makes a Core source build carry the Core definitions thatprebuilt `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 basecolors, 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 questionsNone.