An open source design system that's fully customizable and agent ready
TypeScript
spec(theme-application): record the typed mode and its system fallback (backfill) (#9386)
Cindy Zhang844f28bbc3ab
diff --git a/docs/architecture/theme-application.md b/docs/architecture/theme-application.mdindex d7c38f99d5..3b7b65449a 100644--- a/docs/architecture/theme-application.md+++ b/docs/architecture/theme-application.md@@ -111,8 +111,14 @@ standard width map.- **INV6 — Provider consumers avoid document observation.** `useTheme` under aprovider reads context directly. Shared document observers exist only forno-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>`.+- **INV7 — System follows the platform, and so does any unknown mode.**+ `Theme`'s mode values and default are owned by `component:Theme`. `system`+ resolves to the active light/dark preference without writing a forced mode to+ `<html>`. Any other runtime value, such as a stale stored preference or an+ untyped caller's string, is treated as `system`: the root provider writes no+ forced mode to `<html>`, and consumers resolve it through the platform+ preference. `useTheme().mode` is always the resolved `'light'` or `'dark'`,+ never `system` and never the raw value.- **INV8 — Media surfaces do not replace the theme.** `MediaTheme` changes localsurface tokens and optional surface-specific component rules. It keeps theactive theme and does not remount children when switched off.@@ -165,12 +171,13 @@ which component parts are public theme targets.## 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 |-| INV10 | `AppShell.test.tsx` | A named point ignores the nearest theme or treats equality as mobile |-| INV11 | SSR and hydration icon fixtures | A server-rendered icon differs from the hydrated icon for the same theme |+| 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 | `useTheme.test.tsx` | Provider consumers observe the DOM, or fallback observers leak |+| INV7 | `useTheme.test.tsx` "modes outside light\|dark\|system": `"banana"` under a light and a dark platform preference, `"DARK"` and `""` under a light preference only; `Theme.test.tsx` "removes data-theme from `<html>` for root provider in system mode". Evidence gap: no test covers a provider in `system` mode through `useTheme`, or what an unknown value does to `<html>` (read from source). | System mode resolves incorrectly, `useTheme().mode` returns anything but `'light'` or `'dark'` (such as the raw unknown value), or a root provider in `system` or an unknown mode writes a forced mode to `<html>` |+| 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 |+| INV10 | `AppShell.test.tsx` | A named point ignores the nearest theme or treats equality as mobile |+| INV11 | SSR and hydration icon fixtures | A server-rendered icon differs from the hydrated icon for the same theme |diff --git a/docs/specs/components/theme/Theme.spec.md b/docs/specs/components/theme/Theme.spec.mdindex effbb764d1..7b9c26f2de 100644--- a/docs/specs/components/theme/Theme.spec.md+++ b/docs/specs/components/theme/Theme.spec.md@@ -68,18 +68,18 @@ Consumer migration instructions belong in consumer docs and release notes.## Public concepts-| Concept | Closed values or states | Meaning | Availability by variant/orientation/state | Default | Owner | Stability | Invalid-value behavior |-| ------- | ------------------------- | ------------------------------------------ | ----------------------------------------- | -------- | ----------------- | --------- | -------------------------------- |-| Mode | `light`, `dark`, `system` | Forces a color mode or follows the system. | Every Theme. | `system` | `component:Theme` | Stable | TypeScript rejects other values. |+| Concept | Closed values or states | Meaning | Availability by variant/orientation/state | Default | Owner | Stability | Invalid-value behavior |+| ------- | ------------------------- | ------------------------------------------ | ----------------------------------------- | -------- | ----------------- | --------- | --------------------------------------------------------------------------------------------------------------------------- |+| Mode | `light`, `dark`, `system` | Forces a color mode or follows the system. | Every Theme. | `system` | `component:Theme` | Stable | TypeScript rejects other values; at runtime any other value is treated as `system` (`architecture:theme-application` INV7). |## Behavioral and layout contract-| ID | Invariant | Basis |-| --- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------ |-| FR1 | Theme renders one wrapper with `display: contents`, so it adds no layout box, carrying `data-astryx-theme` with the theme's name and the primary text color and body font. | Current source and tests |-| FR2 | `mode="light"` or `"dark"` sets that `data-theme` and color scheme on the wrapper; `system` sets no `data-theme` and a `light dark` color scheme. A nested Theme sets its own wrapper's mode. | Current source and tests |-| FR3 | Descendants read the theme and mode through Theme context; the nearest Theme wins (`architecture:theme-application` INV1). | Current source and tests |-| FR4 | The outermost Theme writes the theme name and any forced mode to `<html>` and removes them on unmount; a nested Theme never changes `<html>` (`architecture:theme-application` INV2, INV7). | Current source and tests |+| ID | Invariant | Basis |+| --- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------ |+| FR1 | Theme renders one wrapper with `display: contents`, so it adds no layout box, carrying `data-astryx-theme` with the theme's name and the primary text color and body font. | Current source and tests |+| FR2 | `mode="light"` or `"dark"` sets that `data-theme` and color scheme on the wrapper; `system` sets no `data-theme` and a `light dark` color scheme. A nested Theme sets its own wrapper's mode. A Theme given any other value still writes it unchanged to its own wrapper's `data-theme`, with the `light dark` color scheme, though nothing reads that attribute. | Current source and tests |+| FR3 | Descendants read the theme and mode through Theme context; the nearest Theme wins (`architecture:theme-application` INV1). | Current source and tests |+| FR4 | The outermost Theme writes the theme name and any forced mode to `<html>` and removes them on unmount; a nested Theme never changes `<html>` (`architecture:theme-application` INV2, INV7). | Current source and tests |### Allowed variation@@ -131,7 +131,8 @@ Theme renders no themable part of its own, so no anatomy-theming map applies.Read from source, with no focused test yet:- FR1: `display: contents`, the text color, and the body font.-- FR2: the color scheme for each mode.+- FR2: the color scheme for each mode, and the wrapper's `data-theme` for a+ value outside the three.- FR3: descendants reading the nearest Theme's context.## Decision log