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.mdindex 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 doesnot 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 themethat exports only part of that pair, or none of it, stays packable when everypath it exports resolves, and `integration verify` warns about what is missingor 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 firstfor 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 questionsNone.