Skip to content
Draft
Show file tree
Hide file tree
Changes from 29 commits
Commits
Show all changes
31 commits
Select commit Hold shift + click to select a range
8a44474
test(theme): media surfaces keep scheme tokens after light-dark() low…
cixzhang Nov 9, 2026
454fcee
fix(theme): media surfaces re-declare scheme-dependent root tokens
cixzhang Nov 9, 2026
36ce1c4
chore(changeset): media surfaces keep their colors after light-dark()…
cixzhang Nov 9, 2026
70cdb3f
docs(theme-compilation): media surfaces resolve scheme values under t…
cixzhang Nov 9, 2026
02ba71a
Merge remote-tracking branch 'origin/main' into lane2/10863
cixzhang Nov 12, 2026
7224a91
fix(theme): a media surface keeps the root's value for a reference to…
cixzhang Nov 12, 2026
310077e
Merge remote-tracking branch 'origin/main' into lane2/10863
cixzhang Nov 12, 2026
e7bec93
fix(theme): media surfaces follow adaptations, and skip references th…
cixzhang Nov 13, 2026
c42a7ff
docs(theme-compilation): INV12 covers adaptation queries and referenc…
cixzhang Nov 13, 2026
e74628c
Merge remote-tracking branch 'origin/main' into lane2/10863
cixzhang Nov 14, 2026
6e762b4
test(theme): a surface resolves a reference as the root does under tw…
cixzhang Nov 14, 2026
b5ccd1d
fix(theme): a surface inherits where overlapping rules resolve a toke…
cixzhang Nov 14, 2026
6df9563
Merge remote-tracking branch 'origin/main' into fix/media-surface-low…
cixzhang Nov 15, 2026
2f9ffd3
test(theme): a surface takes the theme's value for a scheme-independe…
cixzhang Nov 15, 2026
126fdf6
fix(theme): a media surface takes the theme's value for a scheme-inde…
cixzhang Nov 15, 2026
962f6fd
docs(theme): INV12 names which unset token stops a surface re-declara…
cixzhang Nov 15, 2026
23c7625
test(theme): a surface value refers to the root's alias of a token th…
cixzhang Nov 15, 2026
7b23455
fix(theme): a surface refers to the root's alias of a token the theme…
cixzhang Nov 15, 2026
b0f094a
test(theme): a root alias reference keeps the call's fallback
cixzhang Nov 15, 2026
ae7f6c0
fix(theme): a root alias reference keeps the call's fallback
cixzhang Nov 15, 2026
7848f0f
test(theme): a surface value refers to the root alias of a theme toke…
cixzhang Nov 15, 2026
d546cdd
fix(theme): a surface refers to the root alias of a theme token it ca…
cixzhang Nov 15, 2026
f4d8e12
test(theme): alias spellings, and references to a token the surface i…
cixzhang Nov 16, 2026
5d26ec4
fix(theme): every reference a surface does not hold goes through the …
cixzhang Nov 16, 2026
4eea7fe
test(theme): a media surface keeps its secondary text and icons under…
cixzhang Nov 16, 2026
b7668f9
test(theme): the root-mapping contrast check measures against the sur…
cixzhang Nov 16, 2026
dee9f10
docs(changeset): a media surface also ignores a value an app sets on …
cixzhang Nov 16, 2026
f3b9c57
docs(theme-compilation): INV12 names a value set on the theme root too
cixzhang Nov 16, 2026
2576aad
Merge remote-tracking branch 'origin/main' into fix/media-surface-low…
cixzhang Nov 17, 2026
13e4ee1
Merge remote-tracking branch 'origin/main' into fix/media-surface-low…
cixzhang Nov 19, 2026
42d7286
fix(theme): a card a dark page flips keeps its own side's values unde…
cixzhang Nov 19, 2026
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 7 additions & 0 deletions .changeset/media-surface-lowered-scheme-tokens.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
---
'@astryxdesign/core': patch
---

[fix] Media surfaces keep their colors when a bundler lowers `light-dark()`. A bundler that targets older browsers (for example Vite with lightningcss) resolved the theme's scheme-dependent tokens on the theme root, so inside a `MediaTheme` surface accent text, secondary text, borders and backgrounds kept the page's color scheme: in a light page, Neutral's accent text on a dark surface was #1b1b1b. Each media surface now re-declares those tokens so they resolve under its own scheme. CSS that keeps `light-dark()` renders as before, with one exception: a value set for one of those tokens on the theme root, or on an element between it and a media surface, no longer reaches the surface. So an app that maps a scheme-dependent token on the theme root for its page no longer changes a media surface's color.

@cixzhang
1 change: 1 addition & 0 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -60,6 +60,7 @@ internal/vibe-tests/.fixture-runs/
.tmp-theme-app-types-*/
tmp-swizzle-*-test/
packages/cli/.tmp-component-icons-*/
packages/themes/*/.tmp-media-lowered-*/
packages/themes/*/.tmp-media-accent-*/
apps/sandbox/.next/
apps/sandbox/out/
Expand Down
30 changes: 29 additions & 1 deletion docs/architecture/theme-compilation.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,6 +12,7 @@ owners: [cixzhang, imdreamrunner]
applies_to:
[
packages/core/src/theme/generateThemeRules.ts,
packages/core/src/theme/declarationBoundary.ts,
packages/core/src/theme/themeAdaptations.ts,
packages/core/src/theme/derivedVarRegistry.ts,
packages/core/src/theme/Theme.tsx,
Expand All @@ -29,6 +30,8 @@ verified_by:
packages/core/src/theme/defineTheme.test.ts,
packages/core/src/theme/themeAdaptations.test.ts,
packages/core/src/theme/onMediaTokens.test.ts,
packages/cli/api/theme/build/build.media-lowered-scheme.test.mjs,
packages/core/src/theme/declarationBoundary.test.ts,
packages/core/src/theme/Theme.test.tsx,
packages/core/src/theme/derivedVarRegistry.test.ts,
packages/cli/clients/cli/commands/build-theme.adaptations.test.mjs,
Expand Down Expand Up @@ -163,7 +166,31 @@ Platform-specific details stay inside that compiler.
- **INV12 — Adaptation order is observable.** Root declarations emit first,
adaptation blocks remain separate in authored order, and media-surface overrides
emit last. Duplicate conditions and later root-restoring writes are preserved
exactly; runtime and static output use the same blocks.
exactly; runtime and static output use the same blocks. A media surface
re-declares every scheme-dependent value the theme root declares, under the
base rules and under each adaptation's query, so it resolves under the
surface's color scheme even when a consumer's bundler lowers `light-dark()`.
In a re-declared value, a reference to a token the surface declares itself
takes the theme's value of that token, and so does a reference to a theme
token that does not depend on the scheme, so CSS that keeps `light-dark()`
resolves as before. Any other reference in a re-declared value, to a token
the surface does not hold with a value of its own (its own tokens, or a
re-declaration other than `inherit`), refers to the theme root's private
alias of it (`--_theme-root-<name>`), with the reference's fallback, which
the root resolves, so the surface reads the value every other descendant
reads. Under a query where the surface inherits a token, a value that refers
to it is restated with the alias. When the theme does not declare a token the
surface declares itself, the surface does not re-declare a token that refers
to it.
A token that depends on the color scheme only through tokens the theme does
not declare is not re-declared.
Where two adaptation queries match together and a surface's re-declared
value differs from the value the root resolves under both, the surface
inherits that token there. A token the surface re-declares does
not take a value set for it on the theme root, or on an element between
the theme root and the surface. `substituteVarReferences` in `declarationBoundary.ts` writes those
values with the declaration scanner, so a comment or a string never counts as
a reference.

- **INV13 — A declaration stays inside its boundary.** The web compiler rejects
only an authored property name or value that would escape or invalidate its CSS
Expand Down Expand Up @@ -379,6 +406,7 @@ tiers.
| INV9, INV10 | Platform compiler tests when another compiler ships | CSS details enter shared authoring, or shared theme intent silently disappears |
| INV11 | `defineTheme.test.ts` and `build.test.mjs` local-token fixtures | Runtime/static output rewrites a local name, disagrees, or leaves partial output after failure |
| INV12 | `themeAdaptations.test.ts` and CLI adaptation build fixtures | Rule blocks merge/reorder/drop, surfaces lose precedence, or runtime/static CSS diverges |
| INV12 | `build.media-lowered-scheme.test.mjs` (every published theme built and lowered by lightningcss) and the `onMediaTokens.test.ts` scheme-dependent replay cases | A token inside a light or dark media surface keeps the page's scheme after `light-dark()` lowering, a re-declared value differs from the root's, or a reference to a surface token takes the surface's value |
| INV18 | `colorModeBlocks.test.ts` output tests, `build-theme.color-mode-blocks.test.mjs` (CLI-built CSS), and `colorModeBlocks.a11y.chromium.spec.ts` (the ColorModeBlocks story: the Theme's mode, system preference, a mode that is neither, nested Theme, media surfaces one and more deep, explicit Text and Heading props alike at the root and on a surface, a press, Pagination's current page and a text field's status border kept in the other mode) | A mode block applies in the other mode, overrides a base-layer rule there, or changes CSS for a theme without blocks |
| INV19 | `generateThemeRules.test.ts` (the scope-root font rule), `reset.test.ts` (the `html` rule, none on `body`), and `reset.font.a11y.chromium.spec.ts` (a label measured in a span in `body` has its drawn width in the theme root; a page with no token keeps its font) | Text measured or drawn in `body` uses a different font from the token at the page root, or a page with no token changes font |
| INV13, INV14 | Declaration scanner, generator, Theme mounting, CLI receipt tests, and the existing theme-family Chromium guard | One unsafe declaration corrupts neighbors, valid CSS changes, legacy token generation crashes, or reporting changes CSS |
Expand Down
30 changes: 20 additions & 10 deletions packages/cli/api/theme-edit/theme-accent-lift.test.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -40,24 +40,34 @@ it('keeps the official secondary text lift on a new accent while it reads', asyn
}
await themeEditNew('t', {cwd, like: 'neutral'});
// The lifted rules, not the base theme's own coloured-card secondary
// text, which its card rule sets for each card colour.
// text, which its card rule sets for each card colour. A media surface
// restates the root's scheme-dependent values; those copies are not lifts
// of their own.
const MEDIA_BLOCK = /\[data-astryx-media="(?:dark|light)"\] \{[^}]*\}/g;
/** @param {string} css */
const lifts = css =>
[
...css.matchAll(
/\n {2}([^{\n]+) \{\s*--color-text-secondary: (light-dark\([^;]*\));/g,
),
...css
.replace(MEDIA_BLOCK, '')
.matchAll(
/\n {2}([^{\n]+) \{\s*--color-text-secondary: (light-dark\([^;]*\));/g,
),
]
.filter(m => !/^\.astryx-card\[data-variant=/.test(m[1]))
.map(m => m[2]);
const before = lifts(
fs.readFileSync(path.join(cwd, 'themes/t/t.css'), 'utf8'),
);
/** @param {string} css */
const mediaCopies = css =>
(css.match(MEDIA_BLOCK) ?? []).filter(block =>
block.includes('--color-text-secondary:'),
).length;
const beforeCss = fs.readFileSync(path.join(cwd, 'themes/t/t.css'), 'utf8');
const before = lifts(beforeCss);
expect(before.length).toBe(5);
expect(mediaCopies(beforeCss)).toBe(2);
const r = await themeEditSet('t', 'accent', '#E11D48', {cwd});
const after = lifts(
fs.readFileSync(path.join(cwd, 'themes/t/t.css'), 'utf8'),
);
const afterCss = fs.readFileSync(path.join(cwd, 'themes/t/t.css'), 'utf8');
const after = lifts(afterCss);
expect(after).toEqual(before);
expect(mediaCopies(afterCss)).toBe(2);
expect(r.data.styled.filter(x => /color-text-secondary/.test(x))).toEqual([]);
}, 240_000);
Loading