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.mdindex 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: currentarchive_reason: nullsuperseded_by: nullapproved_by: cixzhang-approved_at: 2026-10-15+approved_at: 2026-10-16phase: acceptedowners: [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 thesame 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 forits 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 thiscontract.@@ -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 thestyling 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 requiredby 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 covertheir 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 basecolors, 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