[spec] AST-080: every Astryx package ships one prebuilt stylesheet in the shared layers

[cixzhang]

Exact decision needed

Should Astryx record, as one system contract, how it distributes component CSS: every published package ships one prebuilt stylesheet, every package stylesheet sits in the same astryx-base layer under the same layer order, and every documented setup loads those files instead of compiling Astryx source?

Who it affects: anyone building a product on Astryx. Today the setup docs offer a path that compiles Astryx source and drops astryx.css. Mixed with a prebuilt stylesheet, that path emits a second copy of component rules that outranks theme overrides, so a themed component shows its base colors. Example: a theme that restyles the destructive Button as a light red fill with dark red text instead renders the base solid red with white text.

Existing authority searched

• spec:AST-066 (current) owns StyleX data-token ownership. FR3 already makes package CSS extraction dependency-aware, and FR7 requires theme output to register @layer reset, astryx-base, astryx-theme;. It does not own package stylesheets as a distribution surface, and its non-goals exclude source-build composition.
• architecture:theme-compilation and architecture:theme-application own theme CSS, not component stylesheets.
• architecture:component-style-authoring owns how component styles are written, not how they ship.
• architecture:cli-surface INV19 requires integration theme packages to keep CSS side effectful; that is the precedent for FR4, scoped to themes.
• Open draft "stylesheet subsets" (AST-076) builds on whole package stylesheets but assumes rather than requires them. It can cite this record; no collision.
• Inspected: scripts/build-css.mjs (each package stylesheet wraps every rule in @layer astryx-base; non-Core stylesheets omit Core groups), package exports/sideEffects, reset.css, the styling overview, getting started, migration setup, package READMEs, and the example apps.

No current record owns this fact, so this is a new record rather than an amendment. Folding it into AST-066 would stretch a data-token record into a packaging contract.

Decision

AST-080 (authority: current, owner cixzhang, approved 2026-10-15):

• FR1: each published @astryxdesign/* package with styled modules exports one prebuilt stylesheet (astryx.css, lab.css, richtext.css, and charts.css from its first published release; any future package ships one with its first styled release).
• FR2: a package stylesheet plus astryx.css plus a theme styles everything the package renders with no StyleX compiler in the product.
• FR3: every package stylesheet and reset.css keeps all rules in its one Astryx layer and begins with @layer reset, astryx-base, astryx-theme;, so theme overrides win across packages in any load order.
• FR4: the stylesheet subpath resolves from the packed package and sideEffects covers it.
• FR5: every documented setup (plain, Tailwind, and a product compiling its own StyleX) loads the prebuilt stylesheets and never compiles Astryx package source.
• FR6: each package README and the styling overview show the package's import.

Rejected alternatives

• Documenting a source compile as an equal setup path: its cascade depends on each product's compiler setup.
• A layer per package: theme layer order would depend on which packages a product loads.
• Stylesheets imported by component modules: some frameworks don't load stylesheets that dependency modules import.

Claim scope and non-goals

Only how Astryx distributes component CSS. Not covered: how a product configures its own compiler (including StyleX settings for its own code or ejected components), theme stylesheet contents, which variable groups a stylesheet holds (AST-066 FR3), subsets, minification, and the @astryxdesign/build source-build package. This PR does not decide that package's future.

Evidence and implementation relationship

Spec only; no implementation here. Conflicts with the current state that a follow-up implementation PR would fix:

1. No package stylesheet and not reset.css carries the FR3 order registration. Loading reset.css after a package stylesheet without the product's own registration line places reset above astryx-base.
2. Lab, Rich Text, and Charts declare sideEffects: false, which does not cover their stylesheets (FR4).
3. The styling overview's "StyleX from source" path says to omit astryx.css and compile component styles from source, and the getting-started examples list a "Next.js Source" setup that imports Astryx from source (FR5).
4. Lab and Rich Text document their stylesheet only in READMEs; the styling overview's import table lists only Core (FR6).

The repository's StyleX example app already follows FR5: it loads astryx.css and compiles only its own code.

Writing rubric results

• R1 narration: none. Intent and requirements are present tense; Current-state impact describes today's state, as the template asks.
• R2 research in the record: none; the setup inventory stays in this description.
• R3 evidence naming a change: none; verification names package, bundler, doc, and real-browser checks.
• R4 rejected alternatives over one line or outside a decision: three, one line each, inside DEC-1–DEC-3.
• R5 pull request or issue references remaining: none.
• R6 ruled open questions still listing options: none; no open questions.

Scope

• This PR contains specification records only.
• It records observable behavior and preserves equivalent internal implementations.
• Any named internal mechanism is intentionally public (the layer names and order registration are what themes and products cascade against).
• Verification states the evidence layer and failure signal without prescribing CI job/workflow topology.
• It records one intentional durable decision.
• The canonical owner, affected current claims, and overlapping open work are named.
• Adjacent facts remain outside scope.
• Public text contains no internal context.

Validation

• pnpm check:knowledge: aligned
• Prettier: clean
• git diff --check: clean

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated
astryx	Ready	Preview	Oct 15, 2026 3:48pm UTC

[astracat-bot]

AI review status for this pull request.

Review status	Updated
🔄 In progress (for maintainers only)	Oct 15, 2026, 3:50 PM UTC

[github-actions]

PR Analysis Report

View Storybook for this PR · View Sandbox for this PR

Current run: The current change has no visual or preview-producing scope. Visual checks are not applicable; preview links are not shown.

---

_{Generated by PR Enrichment workflow | View current CI run}

[cixzhang]

/approve-spec ba087a4

[github-actions]

That /approve-spec comment did not change spec-owner-approval: it named ba087a4, which is not the current head.

The gate only accepts the exact current head, so post this instead:

/approve-spec c851e3552643a07bcf8bbb08d004d5334f23d7a2

A new commit invalidates the command, so repeat it after any push.

[cixzhang]

/approve-spec c851e35

[astracat-bot]

Requesting one wording fix before this record lands: the Current-state impact says non-Core stylesheets already omit the Core variable groups they read, but lab.css carries Core's data-token group because astryx.css omits it, as spec:AST-066 FR3 requires. Please qualify that bullet, FR2's last sentence, and FR2's failure row so they cover only groups astryx.css declares; read literally, they would let a follow-up strip the group and leave Lab's candlestick colors undeclared. It would also help to name both source-compiling getting-started examples (Next.js Source and Vite) and Charts' README in the Current-state impact.

[Automated review]

[astracat-bot]

lab.css does not omit every Core variable group it reads: built at this head it declares all 56 of Core's --color-data-* defaults, because only Lab's ChartCandlestick reads dataVars and astryx.css omits the group. That is what spec:AST-066 FR3 requires. Suggest: "non-Core stylesheets omit the Core variable groups astryx.css declares; Lab's keeps Core's data-token group, which astryx.css omits (spec:AST-066 FR3)."

[astracat-bot]

Read literally, this says a non-Core stylesheet takes Core variable groups from astryx.css and never carries one. Lab must carry Core's data-token group (spec:AST-066 FR3), or its candlestick colors are undeclared in a prebuilt setup. Suggest ending with "…and does not repeat a definition astryx.css declares."

[astracat-bot]

Same qualifier here: "a non-Core stylesheet repeats a Core group" would fail today's lab.css, which correctly carries the data-token group. Suggest "a non-Core stylesheet repeats a group astryx.css declares".

[astracat-bot]

Optional: the getting-started list has two source-compiling setups, Next.js Source and Vite; both compile Core source through @astryxdesign/build and load no astryx.css. Naming both keeps the follow-up from missing the Vite example.

[cixzhang]

/approve-spec c78ee8a