An open source design system that's fully customizable and agent ready
TypeScript
docs: define theme-compilation architecture (#5712)
Cindy Zhang6fa5b2f8ea18
diff --git a/docs/architecture/theme-compilation.md b/docs/architecture/theme-compilation.mdnew file mode 100644index 0000000000..ca22686b3d--- /dev/null+++ b/docs/architecture/theme-compilation.md@@ -0,0 +1,126 @@+---+schema_version: 1+template_version: 1+kind: architecture+id: architecture:theme-compilation+authority: current+archive_reason: null+superseded_by: null+approved_by: cixzhang+approved_at: 2026-08-30+owners: [cixzhang, imdreamrunner]+applies_to:+ [+ packages/core/src/theme/generateThemeRules.ts,+ packages/core/src/theme/derivedVarRegistry.ts,+ packages/core/src/theme/Theme.tsx,+ packages/cli/api/theme/build/build.mjs,+ packages/build/,+ ]+verified_by:+ [+ packages/core/src/theme/generateThemeRules.test.ts,+ packages/core/src/theme/derivedVarRegistry.test.ts,+ packages/cli/api/theme/build/build.test.mjs,+ packages/cli/api/theme/build/build.public-component-vars.test.mjs,+ ]+deciding_specs: []+---++# Theme compilation++This record defines how one theme definition becomes usable styles.++## Purpose++A theme author defines a theme once. On the web, using the theme at runtime and+building it ahead of time must produce the same CSS behavior.++Other platforms may need different output. For example, a future native compiler+may produce style objects instead of CSS. It should still start from the same+theme definition.++## System model++The compiler receives a `DefinedTheme` from the theme-authoring system.++The current web compiler works like this:++1. `generateThemeRules` turns tokens and component overrides into CSS rules.+2. The same code adds state rules, media-surface rules, scopes, and layers.+3. The `Theme` provider mounts those rules when a theme was not built ahead of+ time.+4. The CLI saves those rules into CSS and packages the related JavaScript and+ types.+5. A built theme is marked so the provider does not compile or inject it again.++A future platform compiler may turn the same theme into a different output type.+Platform-specific details stay inside that compiler.++## Boundaries and invariants++- **INV1 — One definition can have many outputs.** Authors do not maintain+ separate definitions for the same shared theme intent.+- **INV2 — Web has one compiler.** Runtime and static builds call the same code to+ turn a theme into CSS.+- **INV3 — Mounting and saving do not change the rules.** The provider mounts+ compiled CSS. The CLI saves and packages it. Neither creates different theme+ behavior.+- **INV4 — Web uses one cascade contract.** Runtime and built CSS use the same+ scopes, `astryx-theme` layer, component overrides, and consumer precedence.+- **INV5 — Common property expansion happens once.** A public theme property may+ set several private component variables. That mapping lives in the checked+ compiler registry, not in each component or output path.+- **INV6 — Private variables stay private.** Theme authors use public properties+ and targets. Direct private `--_*` values are rejected.+- **INV7 — Platform details stay out of shared authoring.** CSS selectors, layers,+ scopes, and custom properties belong to the web compiler. A native compiler+ may use native style objects.+- **INV8 — Shared intent keeps the same meaning.** A token or supported component+ override means the same thing across outputs. Platform-only features have an+ explicit support boundary.++This record does not own:++- token names and defaults;+- `DefineThemeInput`, inheritance, or authoring precedence;+- which component parts and properties are public theme APIs; or+- provider nesting, root synchronization, and DOM observation after compilation.++## Change coupling++- Any change to how a web theme becomes CSS belongs in the shared compiler and+ is tested through both runtime mounting and CLI-built output. The Theme+ provider and CLI may mount or package compiled rules; they must not implement+ their own theme-to-CSS transformations.+- Adding a public-property expansion updates the checked registry, compiler+ tests, component metadata checks, and representative runtime/built output.+- Changing scope or layer output tests both source and distribution builds.+- Adding a platform compiler names the shared concepts it supports and tests+ that they keep the same meaning. Unsupported concepts fail clearly instead of+ disappearing.+- Build packaging may change without changing compiled theme behavior.++## Owning code++- `generateThemeRules.ts` owns the web compiler and canonical CSS output.+- `derivedVarRegistry.ts` owns checked mappings from public properties to private+ component variables.+- `Theme.tsx` mounts compiled CSS for themes that were not built ahead of time.+- `packages/cli/api/theme/build/build.mjs` saves and packages compiled CSS.+- Future platform compilers consume the same `DefinedTheme` behind this boundary.++## Deciding specs++None. The system owner selected one definition with platform-specific outputs+while this record was drafted.++## Verification++| Invariant | Evidence | Failure signal |+| ---------------- | ------------------------------------------------------------------ | --------------------------------------------------------------------------------- |+| INV1, INV2, INV3 | Compiler imports and runtime/build comparison fixtures | Runtime and build use different theme-to-CSS logic or produce different web rules |+| INV4 | `generateThemeRules.test.ts` and source/distribution cascade tests | Scope or layer order differs by output path |+| INV5, INV6 | Registry and CLI public-variable tests | Expansion is duplicated, or private variables become authorable |+| INV7, INV8 | Platform compiler tests when another compiler ships | CSS details enter shared authoring, or shared theme intent silently disappears |+| Built themes | Theme and CLI build tests | Runtime recompiles a built theme, or built output omits canonical rules |