An open source design system that's fully customizable and agent ready
TypeScript
docs: define theme-application architecture (#5716)
Cindy Zhanga2909669199e
diff --git a/docs/architecture/theme-application.md b/docs/architecture/theme-application.mdnew file mode 100644index 0000000000..6a971469b6--- /dev/null+++ b/docs/architecture/theme-application.md@@ -0,0 +1,140 @@+---+schema_version: 1+template_version: 1+kind: architecture+id: architecture:theme-application+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/Theme.tsx,+ packages/core/src/theme/MediaTheme.tsx,+ packages/core/src/theme/useTheme.ts,+ packages/core/src/theme/themeRegistry.ts,+ ]+verified_by:+ [+ packages/core/src/theme/Theme.test.tsx,+ packages/core/src/theme/MediaTheme.dom.test.tsx,+ packages/core/src/theme/useTheme.test.tsx,+ packages/core/src/theme/themeRegistry.test.ts,+ ]+deciding_specs: []+---++# Theme application++This record defines how a compiled theme becomes active for a React tree and the+browser document.++## Purpose++People should see the same theme in normal content, nested theme regions,+portals, and non-CSS consumers. Mounting more than one provider must not create+duplicate styles or let one provider remove styles another provider still uses.++## System model++`Theme` receives a `DefinedTheme`, a color mode, and children.++- It registers the theme by name.+- For a theme that was not built ahead of time, it asks the web compiler for CSS+ and mounts that CSS in the document.+- For a built theme, it assumes the consumer loaded the stylesheet and does not+ compile or inject it again.+- It wraps children with the theme name and color mode.+- The root provider also writes the active theme name and explicit light/dark mode+ to `<html>`. Nested providers do not change `<html>`.++`useTheme` normally reads the nearest provider through React context.++When there is no provider context—such as content rendered into a separate React+root or a fallback viewport—it can follow only the root theme through one shared+fallback path:++1. The root `Theme` writes its theme name and explicit light/dark mode to+ `<html>`.+2. `useTheme` reads those attributes and shares one observer per document.+3. It looks up the theme object by name in the shared registry.+4. Every no-provider consumer reuses that path instead of creating its own+ observer.++A normal React portal keeps provider context and does not need this fallback.+The fallback cannot recover a nested provider for a separate React root. Content+that needs a nested theme must keep that provider context in the same React tree.++`MediaTheme` marks a local surface as dark, light, automatically detected, or+off. Compiled theme CSS uses that marker to switch surface tokens while keeping+the parent theme's component rules.++## Boundaries and invariants++- **INV1 — The nearest provider wins.** Children read the closest Theme context+ and CSS scope.+- **INV2 — Only the root provider changes `<html>`.** Nested providers stay local+ and cannot change browser chrome or portal-wide theme identity.+- **INV3 — Detached consumers share one root-theme store.** A separate React+ root or fallback viewport reads root attributes and the theme registry through+ one internal store with one observer per document. A normal React portal keeps+ provider context. The fallback cannot recover a nested provider.+- **INV4 — Built themes are not compiled again.** A theme marked as built uses its+ loaded stylesheet and skips runtime style generation and injection.+- **INV5 — Runtime styles are shared safely.** Multiple providers using the same+ unbuilt theme share one document-level style set. Styles are removed only when+ no mounted provider still needs them.+- **INV6 — Provider consumers avoid document observation.** `useTheme` under a+ provider reads context directly. Shared document observers exist only for+ no-provider consumers and are disconnected when unused.+- **INV7 — System mode follows the platform.** `system` resolves to the active+ light/dark preference without writing a forced mode to `<html>`.+- **INV8 — Media surfaces do not replace the theme.** `MediaTheme` changes local+ surface tokens and optional surface-specific component rules. It keeps the+ active theme and does not remount children when switched off.+- **INV9 — Application does not change compiled rules.** The provider may mount,+ share, and remove compiler output. It must not create different theme-to-CSS+ behavior from the build path.++This record does not own theme authoring, token definitions, compiler output, or+which component parts are public theme targets.++## Change coupling++- A provider nesting change tests root, nested, portal, and cleanup behavior.+- A style-lifetime change tests two providers using the same theme and confirms+ that unmounting one does not break the other.+- A root-attribute change tests browser mode, portal reach, and no-provider hooks+ together.+- A `useTheme` fallback change tests provider and no-provider paths and confirms+ that provider consumers do not create document observers.+- A MediaTheme change tests dark, light, auto, off, fallback, and unchanged child+ identity.+- A change to runtime compilation belongs first in the shared compiler and is+ checked against the static build path.++## Owning code++- `Theme.tsx` owns provider scope, runtime style lifetime, and root document sync.+- `themeRegistry.ts` owns server-safe lookup by theme name.+- `useTheme.ts` owns provider access and the shared root fallback used by+ detached consumers. Its observation and subscription logic stays+ single-owned; extracting another module is not part of this contract.+- `MediaTheme.tsx` owns local light/dark surface context.+- `architecture:theme-compilation` owns the CSS that Theme mounts.++## Deciding specs++None. This record captures the approved Theme provider and hook behavior.++## Verification++| Invariant | Evidence | Failure signal |+| ---------------- | ----------------------------------------- | -------------------------------------------------------------------------------------------------- |+| INV1, INV2, INV3 | `Theme.test.tsx` and portal/root fixtures | A nested provider changes `<html>`, or portal content cannot find the root theme |+| INV4, INV5 | Runtime injection and cleanup tests | A built theme injects CSS, duplicate providers duplicate CSS, or one unmount removes shared styles |+| INV6, INV7 | `useTheme.test.tsx` | Provider consumers observe the DOM, fallback observers leak, or system mode resolves incorrectly |+| INV8 | `MediaTheme.dom.test.tsx` | Surface mode replaces the theme, loses parent component rules, or remounts children |+| INV9 | Runtime/build compiler comparison | Provider-mounted CSS differs from built CSS for the same theme |