Skip to content

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

TypeScript

[Spec] AST-050: a theme module may load its own styles (#7707)

Joey80d2f411c2db
diff --git a/docs/specs/AST-050-app-themes/spec.md b/docs/specs/AST-050-app-themes/spec.md
index f070f92212..c21327f07e 100644
--- a/docs/specs/AST-050-app-themes/spec.md
+++ b/docs/specs/AST-050-app-themes/spec.md
@@ -137,7 +137,13 @@ described.
`integration add theme` MUST write these exports, and `integration verify`
MUST fail when an exported theme module, stylesheet, or font stylesheet does
not resolve from the packed tarball, or when a theme exports both its built
- module and its stylesheet and either one does not match its source. A theme
+ module and its stylesheet and either one does not match its source. The
+ exported module matches its source when it is the module `theme build` writes
+ from that source, or when it only loads the theme's own styles (DEC-10): each
+ of its statements imports the theme's exported stylesheet or font stylesheet
+ for its side effects, except one, which re-exports from the module
+ `theme build` writes either everything or only its theme, under the theme's
+ export name. A theme
that exports only part of that pair, or none of it, stays packable when every
path it exports resolves, and `integration verify` warns about what is missing
or does not match.
@@ -288,19 +294,19 @@ unchanged.
## Verification
-| Contract | Verification | Representative states | Mutation or failure expectation |
-| -------- | --------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| FR1, FR2 | Theme command tests and a real consumer | first import; repeat import; a slug imported again from another owner; the module's exports; `--import` with a target path or `--overwrite`; hand-written file at the module home; no TypeScript; no `src` folder; `src` added later | Source is copied, app code changes, a repeat import changes files, a second owner's import keeps the old owner, `--import` with a copy option writes anything, an export is missing or renamed, the theme record is exported, a user file is replaced, or an existing module moves |
-| FR3, FR4 | Theme record tests | import, remove, use; removing the default; using a theme not added; a hand-edited module; two modules; no module with `astryx.theme`; `ASTRYX_THEME` set | The default is not an added theme, a hand-edited or second module is overwritten, theme state is written outside the module, `astryx.theme` stops resolving, or `ASTRYX_THEME` changes which theme a command reads |
-| FR5 | Response type and text field tests | every command; first import | An import emits `theme.add`, a field has no text projection, or the first import shows no wiring |
-| FR6 | Eject tests against the copy fixtures | bundled, integration, and nested-file themes; eject then list | Copied source bytes or copy receipt fields differ from the copying `theme add`, the descriptor is missing, or the ejected theme is not listed as local |
-| FR7, FR8 | Integration verify and real provider-to-consumer tests | multi-theme package; single-theme package; missing export; font stylesheet missing from the tarball; stale build; partial export set; a local theme sharing a package theme's slug; local themes in a project with no `src` folder | A theme without a resolvable built module is imported, verify passes a stale complete pair or an unresolved export, verify fails a partial export set whose exports resolve, a shared slug imports the package theme without `--package`, the copying `theme add` resolves a local theme, or local themes are looked for outside `src/themes` |
-| FR9 | Generated module tests | package and local themes | The module imports source |
-| FR10 | List tests | added, default, bundled, package, local | A listed theme lacks its app fields |
-| FR11 | Doctor tests, one planted fault per check | each of the ten faults; a correct app | A check passes on its fault, or passes without positive evidence |
-| FR12 | Lifecycle tests against the latest stable CLI, migration tests on a project it made, and docs tests | plain `theme add`; the cleanup build; a copy made by the latest stable `theme add`; the upgrade codemod run twice; no theme module | Before the cleanup, plain `theme add` stops copying, changes its exit status, stdout, or `theme.add` fields, omits the deprecation id, or warns more than once; after it, plain `theme add` copies; a theme command or doctor fails on an unmigrated copy; the codemod changes more than the descriptor or changes anything on its second run; a copy is moved or deleted; or doctor fails a project with no theme module |
-| FR13 | Docs and agent-docs tests | theme guide, integration guide, agent block, init next steps | A surface teaches copying as the way to use a theme, or names a different import command than the current lifecycle stage |
-| FR14 | Search tests and CLI runs | bundled and integration themes; `--type theme` and an open search outside an app; a word only in a theme's description, such as `focus`; an exact slug or display name; a CLI with and without `--import`; help and the manifest | A theme `theme list` shows is missing from search, a theme result lacks a field or names another command than its FR12 stage, a word only in a theme's description ranks it as a name or keyword match or above a result matching that word by name, title, or keyword, a themes-only search needs Core, or help, the manifest, or the API reference omits the domain |
+| Contract | Verification | Representative states | Mutation or failure expectation |
+| -------- | --------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| FR1, FR2 | Theme command tests and a real consumer | first import; repeat import; a slug imported again from another owner; the module's exports; `--import` with a target path or `--overwrite`; hand-written file at the module home; no TypeScript; no `src` folder; `src` added later | Source is copied, app code changes, a repeat import changes files, a second owner's import keeps the old owner, `--import` with a copy option writes anything, an export is missing or renamed, the theme record is exported, a user file is replaced, or an existing module moves |
+| FR3, FR4 | Theme record tests | import, remove, use; removing the default; using a theme not added; a hand-edited module; two modules; no module with `astryx.theme`; `ASTRYX_THEME` set | The default is not an added theme, a hand-edited or second module is overwritten, theme state is written outside the module, `astryx.theme` stops resolving, or `ASTRYX_THEME` changes which theme a command reads |
+| FR5 | Response type and text field tests | every command; first import | An import emits `theme.add`, a field has no text projection, or the first import shows no wiring |
+| FR6 | Eject tests against the copy fixtures | bundled, integration, and nested-file themes; eject then list | Copied source bytes or copy receipt fields differ from the copying `theme add`, the descriptor is missing, or the ejected theme is not listed as local |
+| FR7, FR8 | Integration verify and real provider-to-consumer tests | multi-theme package; single-theme package; missing export; font stylesheet missing from the tarball; stale build; partial export set; a local theme sharing a package theme's slug; local themes in a project with no `src` folder; a module that loads its own styles; a theme whose name differs from its slug | A theme without a resolvable built module is imported, verify passes a stale complete pair, an unresolved export, or a module that adds more than its own stylesheet imports and a re-export of the built module, verify fails a partial export set whose exports resolve or a module that only loads its own styles, a shared slug imports the package theme without `--package`, the copying `theme add` resolves a local theme, or local themes are looked for outside `src/themes` |
+| FR9 | Generated module tests | package and local themes | The module imports source |
+| FR10 | List tests | added, default, bundled, package, local | A listed theme lacks its app fields |
+| FR11 | Doctor tests, one planted fault per check | each of the ten faults; a correct app | A check passes on its fault, or passes without positive evidence |
+| FR12 | Lifecycle tests against the latest stable CLI, migration tests on a project it made, and docs tests | plain `theme add`; the cleanup build; a copy made by the latest stable `theme add`; the upgrade codemod run twice; no theme module | Before the cleanup, plain `theme add` stops copying, changes its exit status, stdout, or `theme.add` fields, omits the deprecation id, or warns more than once; after it, plain `theme add` copies; a theme command or doctor fails on an unmigrated copy; the codemod changes more than the descriptor or changes anything on its second run; a copy is moved or deleted; or doctor fails a project with no theme module |
+| FR13 | Docs and agent-docs tests | theme guide, integration guide, agent block, init next steps | A surface teaches copying as the way to use a theme, or names a different import command than the current lifecycle stage |
+| FR14 | Search tests and CLI runs | bundled and integration themes; `--type theme` and an open search outside an app; a word only in a theme's description, such as `focus`; an exact slug or display name; a CLI with and without `--import`; help and the manifest | A theme `theme list` shows is missing from search, a theme result lacks a field or names another command than its FR12 stage, a word only in a theme's description ranks it as a name or keyword match or above a result matching that word by name, title, or keyword, a themes-only search needs Core, or help, the manifest, or the API reference omits the domain |
## Decision log
@@ -465,6 +471,28 @@ keywords.
Rejected: reading every description word as a keyword, which ranks a theme first
for any word its description happens to use.
+### DEC-10 — A theme module may load its own styles
+
+**Reference:** `spec:AST-050/DEC-10`
+**Decider:** `josephfarina`, `2026-10-20`
+
+A package can make importing a theme's module the whole integration: the module
+imports the theme's stylesheet and font stylesheet, then re-exports the built
+theme, and consumers rely on that import to load the styles. `integration
+verify` accepts that module when those imports and one re-export of the built
+theme are its only statements. The re-export may give the built theme the
+theme's export name, because `theme build` names the built module and its
+export after the theme's own name, which can differ from the slug the package
+exports it under. The re-exported module is still exactly what `theme build`
+writes, and the stylesheet and font stylesheet stay separate exports, so the
+generated module imports all three as before and a bundler loads each
+stylesheet once.
+
+Rejected: requiring the exported module to be the built module itself, which
+makes such a package choose between passing verify and keeping its consumers'
+imports working; and accepting any module that exports the theme, which lets
+verify pass a module that no longer matches its source.
+
## Open questions
None.