Skip to content

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

TypeScript

spec(AST-080): prebuilt stylesheets stay the default; a source build compiles the same way (#7624)

Cindy Zhangccf1a1cfc84f
diff --git a/docs/specs/AST-080-package-stylesheets/spec.md b/docs/specs/AST-080-package-stylesheets/spec.md
index 777957b480..65920d94de 100644
--- a/docs/specs/AST-080-package-stylesheets/spec.md
+++ b/docs/specs/AST-080-package-stylesheets/spec.md
@@ -7,7 +7,7 @@ authority: current
archive_reason: null
superseded_by: null
approved_by: cixzhang
-approved_at: 2026-10-15
+approved_at: 2026-10-16
phase: accepted
owners: [cixzhang]
affects_architecture: []
@@ -24,8 +24,10 @@ affects_consumer_docs: [styling-overview, getting-started, migration-setup]
A product that uses Astryx loads prebuilt stylesheets: `@astryxdesign/core/astryx.css`,
the stylesheet of each other Astryx package it uses, and a theme stylesheet.
-Those files are the whole of Astryx's component CSS. The product never compiles
-Astryx package source to get it.
+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.
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
@@ -40,8 +42,8 @@ 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`.
-- Loading part of a package stylesheet.
-- The source-build composition that the `@astryxdesign/build` package provides.
+- How `@astryxdesign/build` plugs into each bundler, and how a source build
+ chooses which modules to compile.
- Minifying or compressing stylesheets.
- Equivalent internal implementations remain valid when they satisfy this
contract.
@@ -93,13 +95,12 @@ first.
declaration MUST cover that file, so a bundler keeps the product's
`import '@astryxdesign/<package>/<name>.css'`.
-- **FR5 — Every documented setup loads prebuilt stylesheets.** Each 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.
- No documented setup omits a package stylesheet, adds Astryx package source to
- a compiler's inputs, or presents compiling Astryx package source as a way to
- get component styles. A documented setup looks like:
+- **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
+ default setup looks like:
```css
@layer reset, astryx-base, astryx-theme;
@@ -110,17 +111,39 @@ first.
@import '@astryxdesign/theme-neutral/theme.css';
```
+ 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
+ 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
+ compiles Astryx source any other way, such as adding Astryx package source to
+ the product's own StyleX compiler inputs.
+
- **FR6 — Every package documents its import.** Each package's README and the
styling overview MUST name the package's stylesheet and show the import beside
`astryx.css`.
+- **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
+ 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
+ variable groups and keyframes. Product rules stay outside `astryx-base`. A
+ source build needs no data beyond the package's own source, and holds in
+ development builds as in production builds.
+
### 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 and FR3. FR1, FR4, FR5,
- and FR6 are proven at the package, bundler, and documentation layer.
+- Browser evidence: real-browser computed styles for FR2, FR3, and FR7. FR1, FR4,
+ FR5, and FR6 are proven at the package, bundler, and documentation layer.
## Current-state impact
@@ -134,11 +157,18 @@ first.
places `reset` above `astryx-base`.
- Lab, Rich Text, and Charts declare `sideEffects: false`, which does not cover
their stylesheets (FR4). Core already covers `**/*.css`.
-- The styling overview's "StyleX from source" path tells a product to omit
- `astryx.css` and compile component styles from source, and the getting-started
- examples list two setups that compile Astryx source and load no `astryx.css`
- (`Next.js Source` and `Vite`). These conflict with FR5;
- the setup becomes "load `astryx.css`; compile only your own code."
+- 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
+ priority layers inside `astryx-base`; it compiles Astryx modules with an
+ `astryx` class-name prefix where the prebuilt stylesheets use StyleX's default
+ `x`; its Vite build's Lightning CSS pass and its PostCSS helper's Autoprefixer
+ pass add `-webkit-` declarations the prebuilt stylesheets lack; its Vite plugin
+ 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.
+
- Lab, Rich Text, and Charts document their stylesheet only in their READMEs;
the styling overview's import table lists only Core (FR6).
- The `styling-overview`, `getting-started`, and `migration-setup` consumer docs
@@ -146,13 +176,14 @@ 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 setup omits `astryx.css` or a used package stylesheet; a setup compiles Astryx source; a package import is missing |
+| 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 |
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
@@ -160,19 +191,24 @@ theme's colors in every load order.
## Decision log
-### DEC-1 — Products load prebuilt stylesheets and never compile Astryx source
+### DEC-1 — Prebuilt stylesheets are the default; a source build compiles the same way
**Reference:** `spec:AST-080/DEC-1`
**Decider:** `cixzhang`, `2026-10-15`
-A second compile of Astryx package source emits a second copy of the same rules,
-with an order and layer that depend on the product's compiler setup. Beside the
-prebuilt stylesheet that copy outranks theme overrides, so a themed component
-shows its base colors. One prebuilt file per package gives every product the
-cascade the package ships and tests.
-
-Rejected: documenting a source compile as an equal setup path, because its
-cascade varies with each product's build.
+Most products need no compiler for Astryx, so the prebuilt stylesheets stay the
+default and every default setup works without one. A product that wants
+only the CSS of the modules it ships can compile Astryx source through
+`@astryxdesign/build`. A second compile breaks theme overrides when it adds a
+second copy of the rules beside the prebuilt stylesheet, or compiles them with
+other settings or into another layer. A source build replaces the package's
+stylesheet and compiles it the way the prebuilt stylesheet is compiled, into the
+same single layer, so the cascade the package ships and tests holds.
+
+Rejected: forbidding a source build, which leaves a product no way to load only
+the CSS it uses; and removing rules from a prebuilt stylesheet with data shipped
+beside it, which adds a format to maintain and a second way to build the same
+rules.
### DEC-2 — Every package shares one layer and one order registration