Skip to content

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.md
index 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 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>`.
+- **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 local
surface tokens and optional surface-specific component rules. It keeps the
active 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.md
index 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