Skip to content

fix(theme): media surfaces keep their colors when a bundler lowers light-dark() - #10863

Draft
cixzhang wants to merge 31 commits into
mainfrom
fix/media-surface-lowered-scheme-tokens
Draft

cixzhang wants to merge 31 commits into
mainfrom
fix/media-surface-lowered-scheme-tokens

Conversation

@cixzhang

@cixzhang cixzhang commented Nov 9, 2026 •

Copy link
Copy Markdown
Contributor

User impact

An app whose bundler lowers light-dark() for older browsers (for example Vite with lightningcss and older browser targets) gets the wrong colors inside every MediaTheme surface, in every theme that uses light-dark(). Accent text, secondary text, borders, backgrounds and icons keep the page's color scheme instead of the surface's. In a light page, Neutral's accent link on a dark media band renders #1b1b1b on the dark band, so people can barely see it. Media surfaces now resolve those colors under their own scheme. Apps whose CSS keeps light-dark() see no change, 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 such a token on the theme root for its page no longer changes a media surface's color.

Every release from v0.1.0, whose MediaTheme surfaces already re-declare only three tokens over light-dark() values, through the current release carries the defect.

Known issue (for release notes)

In releases v0.1.0 through the release before this fix, apps whose bundler lowers light-dark() for older browsers (for example Vite with lightningcss) can show the page's colors inside MediaTheme surfaces, so accent text, secondary text, borders and backgrounds can be hard to read on a media band. Upgrade to the release that contains this fix. Until then, keep light-dark() unlowered (target browsers that support it), or set the affected color explicitly inside the surface (for example color="inherit" on a link).

Cause

A lowering bundler writes each light-dark(a, b) as var(--lightningcss-light, a) var(--lightningcss-dark, b) and toggles those switches wherever color-scheme changes. A custom property resolves its var() references on the element that declares it, so the theme root fixes every scheme-dependent token in the page's scheme. A media surface sets color-scheme and re-declares only --color-text-primary, --color-icon-primary and --color-accent; every other token keeps the root's resolved value.

Fix

generateOnMediaCSS (shared by the runtime Theme and astryx theme build) re-declares, in each [data-astryx-media] block, every token the theme root declares whose value is scheme-dependent: it holds light-dark(), or refers through var() to a token that does. Each takes the root's value.

  • In a re-declared value, a reference to a token the surface declares itself is replaced with the theme's value of that token. When the theme does not declare that token, its value comes from an ancestor theme or Core, so the surface does not re-declare the referring token and keeps inheriting it. Without lowering, the root resolves that reference and the surface inherits the result, so CSS that keeps light-dark() resolves as before; after lowering, the replaced value resolves under the surface's scheme.
  • In a re-declared value, a reference to a theme token that does not depend on the scheme (so the surface does not re-declare it) is replaced with the theme's value too. Without this, the surface would resolve that reference itself, so a value an app sets for the token on an element between the theme root and the surface would reach the band, while every other descendant keeps the root's result. References to scheme-dependent tokens stay references, so they resolve under the surface's scheme. A reference to a token the theme does not declare, such as a Core default, refers to a private alias the theme root declares for it (--_theme-root-<name>: var(<name>)), keeping the reference's var() fallback (var(--x, fb) becomes var(--_theme-root-x, fb), so where the token is unset the band takes the same fallback as the root). The root resolves the alias, so the band reads the value every other descendant reads. Only a theme with such a reference declares an alias; no published theme does (+113 B, +22 B gzip, for a probe theme with one).
  • References and cycles come from the declaration scanner and the existing cycle check, not a regex. substituteVarReferences, beside analyzeDeclarationValue, writes the replaced values, so a comment or a string never counts as a reference.
  • A token the surface re-declares does not take a value set for it on the theme root, or on an element between it and the surface. CSS cannot avoid this for any re-declaration; INV12 and the Changeset state it. For an app that maps a scheme-dependent token on the theme root for its page, this is the fix: the page's value no longer lands on an inverted surface (see the root-mapping case under Evidence).
  • Tokens the surface sets itself (onDark/onLight and its status roles) win, as before.
  • One rule covers every remaining reference: a re-declared value's reference 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 that token's root alias, with the same fallback, under the base rules, each adaptation's query and where two rules overlap. Under a query where the surface inherits a token, a value that refers to it is restated with the alias. The alias call is built from the parsed reference, so any spelling of var() gets a declared alias.
  • A re-declaration that would close a var() cycle with the surface's own values is skipped, so that token keeps its inherited value as today.
  • Under each adaptation query, the surface takes every value the root resolves there: it restates each base re-declaration whose value the rule changes (for example a token that refers to an accent the rule sets), re-declares a token the rule makes scheme-dependent, and writes inherit for a base re-declaration that no longer applies.
  • Where an earlier and a later adaptation rule match together, the root resolves a reference with both rules' values. When the later rule's restatement differs from that value, a block under both queries, after the later rule's block, makes the surface inherit the token, which is the value the root resolves. For example, one rule sets --color-accent: #ff0000 and another sets --color-border-emphasized: var(--color-accent): under both, the dark surface now shows #ff0000, as the root does, instead of the base accent.
  • A token that depends on the scheme only through tokens the theme does not declare, such as --color-border-emphasized: var(--color-text-secondary) where Core supplies the secondary text color, is not re-declared. Core resolves its defaults on the page root, so such a re-declaration changes nothing after lowering; it would only let a value set between the theme root and the surface reach the surface.
  • Core defaults stay in Core's stylesheet; theme CSS gains no canonical defaults, and the generator no longer reads them.

Evidence

  • Red first: build.media-lowered-scheme.test.mjs builds every published theme with themeBuild and lowers the output with lightningcss (Chrome 100, Safari 15). For each surface in a light and a dark page, it checks that every scheme-dependent token resolves under the surface's scheme. Before the fix, 12 of 28 cases failed: every light-dark theme, in a light page's dark surface and a dark page's light surface (a page and a surface that share a scheme cannot fail) (for example --color-text-accent: #1b1b1b instead of #f1f1f1). After the fix, all pass.
  • A reference to a surface token keeps the root's value (red first): an onMediaTokens.test.ts case and a built-and-lowered case in build.media-lowered-scheme.test.mjs (a root --color-border-emphasized: var(--color-accent) with a surface accent of #123456). Before this head, the surface showed its own #123456; now it shows the root's accent, as un-lowered CSS does. declarationBoundary.test.ts covers substituteVarReferences (fallbacks, nested calls, comments and strings).
  • Un-lowered output is unchanged: onMediaTokens.test.ts checks that each re-declared value equals the root's declared value, that tokens independent of the scheme and core defaults aren't written, that the surface's own tokens still win, and that an adaptation's value is restated under its query.
  • Real Chromium (a cloud node; measured at 70cdb3f, an earlier head, before the reference rule above), core CSS plus each built theme, as written and as lowered, before and after, 7 themes × 2 page modes × 2 surfaces × 8 tokens:
Values that differ from un-lowered main
Un-lowered, after the fix 0 of 224
Lowered, before the fix 84 of 224
Lowered, after the fix 0 of 224

Neutral's accent text in a light page's dark surface reads rgb(27, 27, 27) lowered before the fix, and rgb(241, 241, 241) after, the same as un-lowered.

  • Red first at this head: three onMediaTokens.test.ts cases (an adaptation that sets --color-accent with another root token referring to it; a reference to an accent the theme leaves unset; a token an adaptation makes scheme-dependent) fail on the previous generator.

  • Red first for the latest commit (6e762b4, on the previous generator): two overlapping adaptation rules (a dark surface showed the base accent light-dark(#111111, #eeeeee) where the root shows #ff0000), and a token that depends on the scheme only through a Core default (re-declared on every surface). Both pass at this head, and each rule alone still restates the value the root resolves.

  • Red first for round 3 (2f9ffd3, on the previous generator): an onMediaTokens.test.ts case with --color-border-emphasized: color-mix(in srgb, var(--color-text-secondary) 50%, var(--color-background-muted)) and a constant muted background expects each surface to write color-mix(in srgb, var(--color-text-secondary) 50%, #00ff00); it failed (the surface kept var(--color-background-muted)) and passes at 962f6fd. A second case covered a reference to a token the theme leaves unset; round 4 replaced its expectation with the root alias.

  • Red first for round 4 (23c7625, on the previous generator): an onMediaTokens.test.ts case where the color-mix's muted background is a Core default expects each surface to write var(--_theme-root-color-background-muted) and the root to declare that alias; it failed and passes at 7b23455. A second case checks that a theme referring only to its own tokens declares no alias. Two build.media-lowered-scheme.test.mjs cases build a Core-mix theme with themeBuild and check that the alias appears only in the theme CSS (not in the receipt or any other output), and that no published theme writes one.

  • Red first for round 5 (b0f094a, on the previous generator): an onMediaTokens.test.ts case with var(--brand-muted, #00c000) expects the surface to write var(--_theme-root-brand-muted, #00c000); it failed (the fallback was dropped) and passes at ae7f6c0. In real Chrome, a fallback probe's band border matches main as written in every row (token unset, with and without an override, as written and lowered); the previous head showed the text colour.

  • Red first for round 7 (f4d8e12, on the previous generator): three onMediaTokens.test.ts cases: a reference spelled var( --x) or VAR(--x) to an undeclared token (the root must declare its alias and the band must refer to it), a rule that makes the band inherit a token (a value referring to it must take the alias under that query), and two overlapping rules that do the same. All three failed and pass at 5d26ec4. In real Chrome, probes for each spelling, a nested fallback and both inherit paths, with and without a wrapper override, match main as written in every row; across all probes 76 of 80 rows do, and the other 4 (a token that refers to the surface's own accent the theme leaves unset, lowered) equal main lowered, the INV12 limit.

  • Red first for round 6 (7848f0f, on the previous generator): an onMediaTokens.test.ts case where --color-border: var(--color-border-emphasized) and emphasized mixes in the unset --color-accent expects the surface to write var(--_theme-root-color-border-emphasized) and the root to declare that alias; it failed and passes at d546cdd. In real Chrome, two chain probes (that case, and --color-border: var(--color-text-secondary)) under a wrapper override match main as written in every row; the previous head showed the override in the first. Across every probe the band equals main as written in 40 of 40 rows.

  • The accent-lift CLI test (theme-accent-lift.test.mjs, from main) counts the root's secondary-text lifts. It now skips the media surfaces' copies of the root value, still asserts the 5 root lifts, and asserts that both surfaces carry one copy, so a lost lift still fails it.

  • At 5d26ec4: core theme tests 1,827 pass (31 files); the lowered-scheme and accent-lift files 35 pass (at 7b23455, with two more theme CLI files, 668); the declaration-counting theme-edit files 753 pass (7 files); tsc and check:knowledge pass. Neutral's and the overlap probe's generated CSS, as written and lowered, is byte-identical to the previous head.

  • Earlier, after merging main: core theme tests and the CLI theme build tests pass (onMediaTokens.test.ts, themeAdaptations.test.ts and the lowered-scheme suite: 148 tests), with tsc and check:knowledge. Two link-path cases in build-stable10.test.mjs and one in build.test.mjs fail on this machine's checkout path and do not touch theme CSS; CI runs them.

  • First-party themes: the media-surface CSS of every published theme (butter, chocolate, gothic, matcha, neutral, stone, y2k) is byte-identical to the previous head's generator, with no overlapping-rule blocks, so their rendered colors match the previous head. Only the private probe theme drops four re-declarations (--color-syntax-added and --color-syntax-removed on each surface) that depend on Core defaults alone.

  • An app's root mapping of secondary text and icons (red first): an app bridge that sets --color-text-secondary and --color-icon-secondary on the theme root with a per-mode value (!important, not a light-dark() pair) no longer reaches a media surface. An onMediaTokens.test.ts case checks that each surface re-declares both tokens itself (52 of 52 pass). mediaSurfaceRootMapping.a11y.chromium.spec.ts measures each surface's secondary text and icon against the surface's own background, in real Chromium under Neutral (text 4.5:1, SC 1.4.3; icons 3:1, SC 1.4.11):

Case main (text / icon) this head (text / icon)
Dark surface, light page 2.67 / 2.67, fails 5.65 / 5.65
Light surface, light page 5.67 / 5.67 9.29 / 5.41
Dark surface, dark page 7.20 / 7.20 5.65 / 5.65
Light surface, dark page 2.10 / 2.10, fails 9.29 / 5.41

The OnLight story nests a dark-mode theme around its light surface, so both light-surface rows measure a light surface inside a dark page; the inverted case that fails on main is that one.

On main the page's grey reaches the surface: it happens to read on a surface of the page's own scheme and fails on an inverted one. At this head every case passes, because the surface resolves both tokens itself.

Before and after (real Chrome)

Theme CSS from the generator on main and at this head (b5ccd1d), as written and lowered by lightningcss for Chrome 100 / Safari 15. Each frame shows a light page with a dark media band and a dark page with a light media band: a caption in secondary text, an accent link and a button with the emphasized border. The probe theme has two adaptation rules: contrast more sets the accent to #ff0000, and a narrow viewport makes the emphasized border refer to the accent. Full sheet with every computed color: README.

  • As written, every computed color is the same on main and here, for Neutral and the probe theme under each rule and both rules.
  • Lowered, main shows the page's scheme inside the band (Neutral's accent link #1b1b1b on the dark band); here every color matches the as-written value.
  • Both rules together, lowered or not: the band's border is #ff0000, the value the root resolves.
Frame main This head
Neutral, lowered main head
Neutral, as written main head
Probe theme, both rules, lowered main head
Probe theme, both rules, as written main head

A mixed value under an app override (round 3)

A probe theme mixes the scheme-dependent secondary text with a constant muted background in --color-border-emphasized, and an app sets --color-background-muted: #ff00ff on a wrapper between the theme root and the band. On the previous head the band's border picked up the override (#d455d4); at this head it matches main as written (#55d455 in a light page's dark band), lowered or not, like every other descendant of the wrapper. Full table: README.

main previous head this head
App override, lowered main previous head

Core-default references under an app override (round 4)

The same probe with the muted background left to Core (#777777 on :root): on the previous head the band's border picked up the wrapper's override (#d455d4 in a light page's dark band); at this head it matches main as written (#919191), lowered or not. The theme-declared rows from round 3 are unchanged. Full table: README.

main previous head this head
Core default, app override, lowered main previous head

Size

The CSS generateThemeCSS writes per published theme (what astryx theme build puts in theme.css), main → this head, raw and gzip level 9:

Theme Raw gzip
butter 72,911 → 97,659 B (+24,748) 6,270 → 7,585 B (+1,315)
chocolate 27,063 → 51,555 B (+24,492) 3,613 → 3,903 B (+290)
gothic 29,970 → 29,970 B (+0) 3,916 → 3,916 B (+0)
matcha 23,075 → 47,583 B (+24,508) 3,480 → 3,773 B (+293)
neutral 29,805 → 56,653 B (+26,848) 3,998 → 4,321 B (+323)
stone 35,686 → 60,354 B (+24,668) 4,234 → 4,521 B (+287)
y2k 62,733 → 87,105 B (+24,372) 5,159 → 6,434 B (+1,275)

The growth is the fix itself: each band re-declares every scheme-dependent root token, and a theme whose cards flip side on a dark page writes each band's rules for its light-page, dark-preference and dark-page copies. Gothic authors single values, so it has nothing to re-declare. A runtime theme's injected CSS grows by the same amount. Writing each side's re-declarations once in a shared selector list saves about 5.4 KB raw per theme but only about 40 B gzip, and reorders the dark-page rules, so this change keeps the per-copy blocks.

Record change

architecture:theme-compilation INV12, at this head:

  • 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. 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.

applies_to adds declarationBoundary.ts and verified_by its test. A verification row names build.media-lowered-scheme.test.mjs and the onMediaTokens.test.ts replay cases, and verified_by adds the new test. It makes architecture:theme-application INV8 (a media surface switches its surface tokens) explicit for lowered CSS.

Writing rubric results

  • Present tense, system description only; no history or PR references in the record: pass.
  • The INV12 sentences match the generator's behavior and the tests, including the overlapping-rule and Core-only cases: pass.
  • The verification row names the evidence, its states, and its failure signal: pass.
  • It extends the existing INV12 instead of adding an owner: pass.
  • The exported helper is named with why it exists: pass.

Out of scope

  • A single-value accent on the wrong surface (Gothic on a light surface) is a different cause and has its own fix in fix(theme-gothic): accent text and icons stay readable on a light media surface #10852.
  • Core's own default tokens, which a bundler also resolves on :root, live in Core's stylesheet and aren't touched here. The same root mapping in an app with no theme package (Core's defaults alone) is a separate fix that follows this one.

Scope

  • One defect: media surfaces under light-dark() lowering, with its red-first test, unit cases, and patch Changeset.
  • Public text and artifacts contain no internal Meta context.

Owner and land path

Owner: the Astryx fix loop, lane 2. Land path: Specs approval of the INV12 change, then the automated review approves the exact head, then ready for review and green CI; the drain merges.

…ering

Builds each published theme, lowers its CSS with lightningcss for older browser targets, and checks that every scheme-dependent token inside each media surface resolves under the surface's scheme in a light and a dark page. Fails for every light-dark theme: in a light page, neutral's accent text on a dark surface is #1b1b1b instead of #f1f1f1.
A bundler that lowers light-dark() writes each value as var() switches, and a custom property resolves those where it is declared, so the theme root fixed every scheme-dependent token in the page's scheme and a media surface inherited it: accent text, secondary text, borders and backgrounds stayed in the page's scheme. Each media surface now re-declares the theme root's scheme-dependent tokens with the same values, after skipping the tokens the surface sets itself and any re-declaration that would close a var() cycle; adaptation queries restate their own values the same way. CSS that keeps light-dark() resolves exactly as before.
@vercel

vercel Bot commented Nov 9, 2026 •

Copy link
Copy Markdown

The latest updates on your projects. Learn more about Vercel for GitHub.

Project Deployment Actions Updated
astryx Ready Ready Preview Nov 19, 2026 9:23pm UTC

Request Review

@meta-cla meta-cla Bot added the CLA Signed This label is managed by the Meta Open Source bot. label Nov 9, 2026
@github-actions github-actions Bot added the needs:spec-owner-review Current knowledge records await owner approval label Nov 9, 2026
@cixzhang

cixzhang commented Nov 9, 2026

Copy link
Copy Markdown
Contributor Author

/approve-spec 70cdb3f

@github-actions github-actions Bot removed the needs:spec-owner-review Current knowledge records await owner approval label Nov 9, 2026
@github-actions

github-actions Bot commented Nov 9, 2026 •

Copy link
Copy Markdown
Contributor

PR Analysis Report

Current run: The current CI run concluded skipped. Current analysis is unavailable.


Generated by PR Enrichment workflow | View current CI run

@astracat-bot

astracat-bot Bot commented Nov 9, 2026 •

Copy link
Copy Markdown
Contributor

AI review status for this pull request.

Review status Updated
🟡 Reviewed (for maintainers only) Nov 19, 2026, 9:38 PM UTC

@astracat-bot astracat-bot Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Requesting changes. The re-declaration fixes MediaTheme surface colours for apps that lower light-dark() in every first-party theme, and those themes resolve exactly as before when light-dark() is kept. Two things need fixing first:

  • With light-dark() kept, a token that refers to a token the surface declares now resolves to the surface's value, for example --color-border-emphasized: var(--color-accent) on a dark surface going from #eeeeee to #ffffff, or a root token that refers to an onDark override; a token override set on an element above a surface no longer reaches it either; so "CSS that keeps light-dark() renders as before" in the changeset and the new INV12 sentence is not true, and either un-lowered resolution needs to be kept for references to surface tokens with the override effect stated, or the claims need rewording (a reworded record sentence needs a fresh spec-owner approval).
  • schemeDependentEntries and withoutDeclarationCycles parse var() references with a new regex and walk cycles on their own, unlike the comment- and string-aware tokenizer that alias generation uses, so please reuse analyzeDeclarationValue(value).references and tokenValuesWouldHaveCycleWithValue, which the same file already uses for status aliases.

Smaller points: two new comments in generateThemeRules.ts run past INV29's sentence length, and the description's "24 of 28 cases failed" should read 12 of 28, because cases where the page and the surface share a scheme cannot fail.

[Automated review]

Comment thread docs/architecture/theme-compilation.md Resolved
@cixzhang
cixzhang marked this pull request as ready for review November 9, 2026 20:18
… a surface token; references come from the declaration scanner

A re-declared root token that refers to a token the surface declares itself
now takes the root's value of that token. Without lowering, the root
resolves the reference and the surface inherits the result, so CSS that
keeps light-dark() renders as before; after lowering, the value resolves
under the surface's scheme. INV12 also states that a value set for a
re-declared token on an element between the theme root and the surface no
longer reaches the surface.

Scheme dependence and cycles now use the declaration scanner and the
existing cycle check instead of a regex. substituteVarReferences, beside
analyzeDeclarationValue, writes the replaced values, so a comment or a
string never counts as a reference.
# Conflicts:
#	packages/core/src/theme/generateThemeRules.ts
@cixzhang
cixzhang marked this pull request as draft November 12, 2026 20:50
@github-actions github-actions Bot added the needs:spec-owner-review Current knowledge records await owner approval label Nov 12, 2026
@cixzhang

Copy link
Copy Markdown
Contributor Author

/approve-spec 310077e

@github-actions github-actions Bot removed the needs:spec-owner-review Current knowledge records await owner approval label Nov 12, 2026

@astracat-bot astracat-bot Bot left a comment •

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Requesting changes. The lowered-CSS fix works: in every first-party theme, a MediaTheme surface in lowered CSS now resolves exactly as CSS that keeps light-dark(), and the earlier description points (the 12 of 28 count, the stated exception and the record text) are fixed. These still need changes:

  • With light-dark() kept, an adaptation that changes a surface-declared token such as --color-accent no longer reaches root tokens that refer to it inside a media surface (#ff0000 becomes #eeeeee), because each rule's surface block restates only the rule's own tokens (generateThemeRules.ts:1963-1972); please restate the affected re-declarations under the rule's query and add a test where an adaptation sets --color-accent and another root token refers to it.
  • Miss: when a theme refers to a surface token it does not declare, the surface re-declaration writes Core's default instead of the inherited value, so a nested theme inside a theme with accent #00aa00 shows #0171e3 in its media surfaces even with light-dark() kept (generateThemeRules.ts:1879); please replace references only from values the theme declares and skip the re-declaration otherwise.
  • Miss: a root token that becomes scheme-dependent only under an adaptation, such as --color-border: var(--color-text-secondary) when a contrast: more rule sets the secondary text to a light-dark() value, is not re-declared under that query, so lowered CSS still shows the page's scheme there (generateThemeRules.ts:1952-1958).
  • The description's affected range "through v0.7.11 … along with main's 0.7.12", and the same range in the Known issue text, ends too early: this head already declares 0.7.15 and main declares 0.7.16.
  • Miss: the description's start of the range, "since media surfaces shipped (#3280, v0.1.3)", is off: MediaTheme and the media-surface CSS are already in the 0.1.2 release, and #3280 is the config and integration API.
Claims and files checked
  • Changeset: lowered media surfaces keep their colours — verified (lowered suite passes on this head; Neutral's band accent moves from #1b1b1b to #f1f1f1 in Chromium).
  • Changeset: before the fix, Neutral's accent on a dark surface in a light page was #1b1b1b — verified (Chromium on the base).
  • Changeset: each surface re-declares the scheme-dependent tokens — verified for root values; not under an adaptation that creates the dependence (third bullet).
  • Changeset: CSS that keeps light-dark() renders as before with one exception — false (first two bullets).
  • Description: every light-dark() theme is affected inside media surfaces — verified (six themes fail on the base; Gothic does not).
  • Description: Neutral's accent link reads #1b1b1b on a dark band in a light page — verified.
  • Description: apps that keep light-dark() see no change apart from the stated exception — false (first two bullets).
  • Description: affected releases run from v0.1.3 (#3280) to v0.7.11 / main's 0.7.12 — false (last two bullets).
  • Description: cause (lowering writes var() switches, the root resolves them, the surface re-declares three tokens) — verified in the base output.
  • Description: one generator serves the runtime Theme and astryx theme build — verified (runtime and built CSS grow by the same 13,424 characters for Neutral).
  • Description: every scheme-dependent root token is re-declared with the root's value — verified for root values; false under adaptations (first and third bullets).
  • Description: a reference to a surface token takes the root's value — verified when the theme root declares the token; false when it inherits it (second bullet).
  • Description: references and cycles come from the shared scanner and cycle check — verified in the code.
  • Description: a value set between the theme root and a surface no longer reaches the surface — verified (stated in the record and changeset).
  • Description: the surface's own tokens still win — verified (unit test and output order).
  • Description: re-declarations that would close a var() cycle are skipped — verified (shared cycle check; existing cycle cases pass).
  • Description: a base re-declaration never hides an adapted value — false (first bullet).
  • Description: Core defaults stay in Core's stylesheet — false (second bullet).
  • Description: red-first count 12 of 28, all passing after the fix — verified.
  • Description: the reference case is red first and passes — verified on this head; the built case fails on the base.
  • Description: un-lowered output is unchanged — verified for first-party themes; false for the consumer cases in the first two bullets.
  • Description: Chromium table measured at an earlier head — partly verified (Neutral's sampled tokens match on this head).
  • Description: Core theme tests, the lowered suite, tsc and the knowledge check pass — verified.
  • Description: size table and runtime growth — verified (raw deltas match; Gothic +0).
  • Description: record change (INV12 text, applies_to, verified_by, verification row) — verified.
  • Description: writing rubric says the new sentence matches the generator — false (first two bullets); the other rubric items verified.
  • Files: .changeset/media-surface-lowered-scheme-tokens.md (first two bullets), .gitignore (clear), docs/architecture/theme-compilation.md (clear; the code should conform), packages/cli/api/theme/build/build.media-lowered-scheme.test.mjs (clear; cannot see query blocks), packages/core/src/theme/declarationBoundary.test.ts (clear), packages/core/src/theme/declarationBoundary.ts (clear), packages/core/src/theme/generateThemeRules.ts (first three bullets), packages/core/src/theme/onMediaTokens.test.ts (clear; no adapted surface-token case).

Automated review (maintainer link)

Comment thread docs/architecture/theme-compilation.md Resolved
@cixzhang
cixzhang marked this pull request as ready for review November 12, 2026 21:47
…e theme cannot resolve

Under an adaptation's query, a media surface now restates every base
re-declaration whose value the rule changes, for example a token that
refers to the accent an adaptation sets, and re-declares a token the rule
makes scheme-dependent. A re-declared value takes references to surface
tokens only from values the theme declares; when the theme does not declare
one, the surface does not re-declare the token and keeps inheriting it, and
under a query that no longer re-declares a base replay it writes `inherit`.
@cixzhang
cixzhang marked this pull request as draft November 13, 2026 04:46
@github-actions github-actions Bot added the needs:spec-owner-review Current knowledge records await owner approval label Nov 13, 2026
@cixzhang

Copy link
Copy Markdown
Contributor Author

/approve-spec 5d26ec4

@github-actions github-actions Bot removed the needs:spec-owner-review Current knowledge records await owner approval label Nov 16, 2026

@astracat-bot astracat-bot Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Approved pending CI: CI has not run on this draft head yet. INV12 as amended has an engineering owner's approval for this exact head, both earlier generator findings are fixed (alias spelling, and values that refer to a token a band inherits under a rule or an overlap), and lowered Neutral now matches the un-lowered page in real Chromium.

Non-blocking: a reference written with a CSS escape, such as var(--color-background-mut\65 d), still skips the root alias because rootAliasCall returns null (generateThemeRules.ts:1932), so a value set above a band for that token reaches it; building the alias call from the scanner's name offset would cover it. The earlier notes on uppercase LIGHT-DARK( and one long comment still apply.

Claims and files checked

Review mode: full; reason: spec-record

  • Claim: apps whose bundler lowers light-dark() see the page's colours inside media bands in every light-dark() theme. Verified (Neutral lowered on the base in Chromium; the lowered-build suite on every published theme).
  • Claim: in a light page, Neutral's accent link on a dark band reads #1b1b1b before the fix. Verified (rgb(27, 27, 27), lowered, on the base).
  • Claim: bands now resolve those colours under their own scheme. Verified (the head's lowered Neutral frame is pixel-identical to the un-lowered page on the base).
  • Claim: CSS that keeps light-dark() sees no change apart from values set between the theme root and a band. Verified for every spelling covered by the tests and probes; an escaped custom-property name is the exception (non-blocking).
  • Claim: every release from v0.1.0 carries the defect, with bands re-declaring only three tokens. Consistent with the base generator; v0.1.0 itself was not re-read.
  • Claim: the workarounds are keeping light-dark() unlowered or setting the colour inside the band. Verified (the as-written page is correct on the base).
  • Claim: the cause is lowered switches resolving on the theme root while a band re-declares three tokens. Verified (base band blocks hold only the band's own tokens).
  • Claim: one generator serves the runtime Theme and astryx theme build. Verified (both reach generateOnMediaCSS).
  • Claim: each scheme-dependent root token is re-declared with the root's value. Verified (unit cases); uppercase LIGHT-DARK( is not detected (non-blocking).
  • Claim: a reference to a band token takes the theme's value, and one the theme leaves unset stops the re-declaration. Verified (unit cases).
  • Claim: a reference to a scheme-independent theme token takes the theme's value. Verified (unit case).
  • Claim: a reference to an undeclared token goes through a root alias with its fallback. Verified (unit cases; the var( --x) probe); an escaped name skips it (non-blocking).
  • Claim: only a theme with such a reference declares an alias, and no published theme does. Verified for the published themes; the probe theme's byte cost was not measured.
  • Claim: references and cycles come from the declaration scanner, not a regex. Verified for the rewrite; alias names are still read from the generated text with a regex (non-blocking).
  • Claim: a re-declared token no longer takes a value set for it between the theme root and the band. Verified.
  • Claim: band-own tokens win, and a cycle-closing re-declaration is skipped. Verified (unit cases; cycle filter).
  • Claim: a value that refers to a theme token the band does not re-declare uses its root alias under the base rules, each query and the overlap comparison. Verified (chain case; rule-inherit probe).
  • Claim: adaptation queries restate changed values, re-declare newly scheme-dependent tokens and inherit dropped ones. Verified (unit cases).
  • Claim: with two overlapping rules the band shows the root's value. Verified (unit case).
  • Claim: a token that depends on the scheme only through undeclared tokens is not re-declared, and Core defaults stay out of theme CSS. Verified (unit cases).
  • Claim: the lowered-build suite fails 12 of 28 theme cases before the fix and passes after. Verified (on the base, 12 of the 28 theme cases fail: every light-dark() theme in a light page's dark band and a dark page's light band; all 34 cases pass on the head).
  • Claim: the three newest unit cases fail on the previous generator. Verified (3 of 51 fail there, all pass here).
  • Claim: red-first results for the earlier rounds. Not re-run against those generators.
  • Claim: one rule now covers every remaining reference, and any spelling of var() gets a declared alias. Verified for case, spaces and comments in the call; an escaped name is not covered (non-blocking).
  • Claim: the accent-lift test skips band copies and still asserts 5 root lifts. Verified (passes; it also asserts 2 band copies).
  • Claim: core theme tests (1,827 in 31 files), the lowered-scheme and accent-lift files, the typecheck and the knowledge check pass. Verified for the 31 core theme files, the CLI theme files run here and the knowledge check; the typecheck passed as part of Core's build.
  • Claim: two build test files fail only on the author's machine. Not checked (CI did not run).
  • Claim: published themes' band CSS is unchanged by the later reference rules. Consistent (no alias in any published theme; raw size deltas equal the size table).
  • Claim: the before and after screenshots and the override probes. Consistent with this review's Neutral, rule-inherit and space probes.
  • Claim: the size table. Verified (raw deltas identical).
  • Claim: the Record change block is INV12 at this head. Verified (word for word).
  • Claim: applies_to, verified_by and the new verification row. Verified.
  • Claim: the writing rubric says the INV12 sentences match the generator. Verified, apart from the escaped spelling (non-blocking).
  • Claim: the out-of-scope items (a separate single-value accent fix; Core defaults untouched). Verified.
  • Changeset: a Core patch describing the fix with one exception. Verified, apart from escaped names (non-blocking).
  • File .changeset/media-surface-lowered-scheme-tokens.md: clear.
  • File .gitignore: clear (matches the lowered suite's temporary folders).
  • File docs/architecture/theme-compilation.md: clear (INV12 approved for this head by an engineering owner).
  • File packages/cli/api/theme-edit/theme-accent-lift.test.mjs: clear.
  • File packages/cli/api/theme/build/build.media-lowered-scheme.test.mjs: clear.
  • File packages/core/src/theme/declarationBoundary.test.ts: clear.
  • File packages/core/src/theme/declarationBoundary.ts: clear.
  • File packages/core/src/theme/generateThemeRules.ts: non-blocking (escaped names at line 1932, uppercase LIGHT-DARK( at line 1907, one long comment at lines 2373-2377).
  • File packages/core/src/theme/onMediaTokens.test.ts: clear.

Automated review (maintainer link)

*/
function rootAliasCall(reference: string, call: string): string | null {
const head = VAR_CALL_HEAD.exec(call)?.[0] ?? '';
if (!call.startsWith(reference, head.length)) {

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Non-blocking: when the call text does not start with the parsed name, this returns null and the reference keeps var() on the band. A theme value written with a CSS escape, var(--color-background-mut\65 d) (that is, --color-background-muted), gets no alias. So with light-dark() kept, a wrapper's --color-background-muted: #ff00ff reaches the band's --color-border: in Chromium it shows color(srgb 0.833 0.333 0.833) where main shows grey. Carrying the name's end offset in VarCall from the scanner and building the alias call from it would cover every spelling. An escaped-name case in onMediaTokens.test.ts would pin it.

… an app's root token mapping

An app that maps --color-text-secondary or --color-icon-secondary on the
theme root to a grey chosen for the page must not pass that grey to a media
surface of the other luminance. A unit case checks that each surface
declares both tokens itself. A Chromium case maps both on the theme root,
per page mode, and checks that dark and light surfaces on light and dark
pages keep text at 4.5:1 and icons at 3:1 or more.
…face's own background

The OnDark story's backdrop follows the page, so on a dark page the dark
surface sat on white and the check measured against the wrong color. The
check now reads --color-background-surface inside the media element, which
resolves under the surface's own color scheme.
@cixzhang

Copy link
Copy Markdown
Contributor Author

/approve-spec b7668f9

@astracat-bot astracat-bot Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Changes requested: one release-note sentence. The lowered light-dark() fix holds at this head. Neutral's lowered media band now matches the un-lowered page in real Chromium, the lowered-build suite and the media-surface unit cases pass, and INV12 as amended has an engineering owner's spec approval for this head.

Blocking

  • Miss: the changeset (.changeset/media-surface-lowered-scheme-tokens.md:5) and the description say CSS that keeps light-dark() renders as before apart from a value set between the theme root and a band, but this head's new tests assert that bands also ignore a value an app sets on the theme root itself (in Neutral's dark band on a light page, the app's #65676b at 2.67:1 becomes #9e9e9e at 5.65:1), so please write "on the theme root or on an element between it and a media surface" in both.

Non-blocking: the new Chromium spec's "light surface on a light page" case measures a dark page, because the OnLight story nests a dark-mode Theme. The earlier notes on escaped names, uppercase LIGHT-DARK( and one long comment still apply.

Claims and files checked

Review mode: incremental; reason: none

  • changed rules (0): none
  • Claim: apps whose bundler lowers light-dark() see the page's colours inside media bands in every light-dark() theme. Verified (real Chromium on the base with Neutral lowered; the lowered-build suite).
  • Claim: in a light page, Neutral's accent link on a dark band reads #1b1b1b before the fix. Verified (rgb(27, 27, 27) lowered on the base).
  • Claim: bands now resolve those colours under their own scheme. Verified (the head's lowered frame is pixel-identical to the un-lowered page).
  • Claim: CSS that keeps light-dark() sees no change, with one exception (a value set between the theme root and a band). False: an app's value on the theme root itself no longer reaches bands either (blocking).
  • Claim: every release from v0.1.0 carries the defect, with bands re-declaring three tokens. Consistent with the base generator (the base band block holds only its own tokens); v0.1.0 was not re-read.
  • Claim: the workarounds are keeping light-dark() unlowered or setting the colour inside the band. Verified (the un-lowered page is correct on the base).
  • Claim: the cause is lowered switches resolving on the theme root while a band re-declares three tokens. Verified (base band block).
  • Claim: one generator serves the runtime Theme and astryx theme build. Verified (both reach generateOnMediaCSS).
  • Claim: each scheme-dependent root token is re-declared with the root's value. Verified (unit cases); uppercase LIGHT-DARK( is not detected (non-blocking).
  • Claim: a reference to a band token takes the theme's value, and one the theme leaves unset stops the re-declaration. Verified (unit cases).
  • Claim: a reference to a scheme-independent theme token takes the theme's value. Verified (unit case).
  • Claim: a reference to an undeclared token goes through a root alias with its fallback, and no published theme writes one. Verified (unit cases; the lowered-build suite); an escaped name skips it (non-blocking).
  • Claim: the alias costs about 113 B (22 B gzip) for a probe theme. Not measured.
  • Claim: references and cycles come from the declaration scanner, not a regex. Verified for the rewrite; alias names are read back with a regex (non-blocking).
  • Claim: a re-declared token no longer takes a value set between the theme root and the band, as INV12 and the changeset state. Verified, but the same holds for a value on the theme root itself, which neither text names (blocking, release note only).
  • Claim: band-own tokens win, and a cycle-closing re-declaration is skipped. Verified (unit case; cycle filter).
  • Claim: every other reference to a token the band does not hold uses its root alias, under the base rules, each query and overlaps, in any var() spelling. Verified (unit cases); escaped names are not covered (non-blocking).
  • Claim: adaptation queries restate changed values, re-declare newly scheme-dependent tokens and inherit dropped ones. Verified (unit cases).
  • Claim: with two overlapping rules the band shows the root's value. Verified (unit case).
  • Claim: a token that depends on the scheme only through undeclared tokens is not re-declared, and Core defaults stay in Core. Verified (unit cases).
  • Claim: the lowered-build suite and the earlier red-first rounds fail on the previous generators. Not re-run here; the generator and those tests are unchanged since the last review measured them.
  • Claim: the accent-lift test skips band copies and still asserts 5 root lifts. Verified (passes; it also asserts 2 band copies).
  • Claim: the core theme tests, the lowered-scheme and accent-lift files, the typecheck and the knowledge check pass. Verified for the tests (33 files, 1,863 tests at this head, one more than reported because of the new case); the typecheck and the knowledge check were not re-run.
  • Claim: two build test files fail only on the author's machine. Not checked (CI did not run).
  • Claim: published themes' band CSS is unchanged by the later reference rules. Consistent (the generator is unchanged since the last review).
  • Claim: the before and after screenshots and the override probes. Consistent with this run's Neutral and root-mapping frames.
  • Claim: the size table. Verified for Neutral (+13,424 B raw).
  • Claim: the Record change block is INV12 at this head. Verified (word for word).
  • Claim: applies_to, verified_by and the new verification row. Verified.
  • Claim: the writing rubric results. Verified; INV12 claims no exclusivity for its "between" sentence.
  • Claim: the out-of-scope items (a separate single-value accent fix; Core defaults untouched). Verified.
  • Changeset: a Core patch whose CSS that keeps light-dark() renders as before with one exception. False for a theme-root mapping (blocking).
  • File .changeset/media-surface-lowered-scheme-tokens.md: blocking (the one-exception sentence).
  • File .gitignore: clear (matches the lowered suite's temporary folders).
  • File docs/architecture/theme-compilation.md: clear (INV12 approved for this head).
  • File packages/cli/api/theme-edit/theme-accent-lift.test.mjs: clear.
  • File packages/cli/api/theme/build/build.media-lowered-scheme.test.mjs: clear.
  • File packages/core/src/theme/__tests__/mediaSurfaceRootMapping.a11y.chromium.spec.ts: non-blocking (the OnLight story's light-page case measures a dark page).
  • File packages/core/src/theme/declarationBoundary.test.ts: clear.
  • File packages/core/src/theme/declarationBoundary.ts: clear.
  • File packages/core/src/theme/generateThemeRules.ts: non-blocking (escaped names at line 1932, uppercase LIGHT-DARK( at line 1907, one long comment at lines 2374-2377).
  • File packages/core/src/theme/onMediaTokens.test.ts: clear (the new root-mapping case passes here).

Automated review (maintainer link)

test(`a ${surface} media surface on a ${pageMode} page keeps readable secondary text and icons under an app's root mapping`, async ({
page,
}) => {
const story = `core-themes-mediatheme--on-${surface}`;

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Non-blocking: core-themes-mediatheme--on-light always nests <Theme mode="dark"> (MediaTheme.stories.tsx:91), so the case named "a light media surface on a light page" measures a dark page. Without the fix that case passes (5.67:1), as does the dark surface on a dark page (7.2:1). Only two of the four cases guard the change. Consider naming each case for the page it actually measures, or dropping the duplicate.

@cixzhang

Copy link
Copy Markdown
Contributor Author

/approve-spec f3b9c57

@github-actions github-actions Bot added needs:spec-owner-review Current knowledge records await owner approval and removed needs:spec-owner-review Current knowledge records await owner approval labels Nov 16, 2026

@astracat-bot astracat-bot Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Changes requested: one sentence in the pull request description. The lowered light-dark() fix holds at this head: Neutral's lowered media band matches the un-lowered page in Chromium, the lowered-build suite fails 12 of 28 theme cases on the previous generator and passes here, and INV12 as amended has an engineering owner's spec approval for this head.

Blocking

  • The description's User impact paragraph says CSS that keeps light-dark() changes only for a value set on an element between the theme root and a media surface, but this head also stops a value set on the theme root itself (Neutral's dark band: an app's #65676b becomes the theme's #9e9e9e), so please write "on the theme root, or on an element between it and a media surface" there, as the changeset now does.

Non-blocking: the new Chromium spec's "light surface on a light page" case measures a dark page, because the OnLight story nests a dark-mode Theme; the earlier notes on escaped names, uppercase LIGHT-DARK( and one long comment still apply.

Claims and files checked

Review mode: full; reason: spec-record

  • Claim: apps whose bundler lowers light-dark() get the page's colours inside media bands in every light-dark() theme. Verified: the lowered-build suite fails 12 of 28 theme cases on the previous generator (only the single-valued theme passes).
  • Claim: in a light page, Neutral's accent link on a dark band reads #1b1b1b before the fix. Verified (lowered Neutral fixture on the base).
  • Claim: bands now resolve those colours under their own scheme. Verified: the lowered-build suite passes, and the head's lowered fixture frame is pixel-identical to the as-written frame.
  • Claim: CSS that keeps light-dark() sees no change, with one exception (a value set between the theme root and a band). False: a value set on the theme root itself no longer reaches the band either (blocking).
  • Claim: every release from 0.1.0 carries the defect, its bands re-declaring three tokens. Verified (the 0.1.0 release's default band tokens; the base's built Neutral band).
  • Claim: the workarounds are keeping light-dark() unlowered or setting the colour inside the band. Verified (as-written frames are correct on the base; Link takes an inherit colour).
  • Claim: the cause is lowered switches resolving on the theme root while a band re-declares three tokens. Verified.
  • Claim: one generator serves the runtime Theme and astryx theme build. Verified (both reach generateOnMediaCSS).
  • Claim: each scheme-dependent root token is re-declared with the root's value. Verified (unit cases; 114 declarations per band in built Neutral); uppercase LIGHT-DARK( is not detected (non-blocking).
  • Claim: a reference to a band token takes the theme's value, and one the theme leaves unset stops the re-declaration. Verified (unit cases; built and lowered case).
  • Claim: a reference to a scheme-independent theme token takes the theme's value. Verified (unit case).
  • Claim: other references go through a root alias with their fallback, no published theme writes one, and the alias costs about 113 B (22 B gzip). Verified (unit cases; built themes); measured 112 B raw and 26 B gzip on the media CSS alone.
  • Claim: references and cycles come from the declaration scanner, not a regex. Verified for the rewrite; alias names are read back with a regex (non-blocking).
  • Claim: a re-declared token does not take a value set on the theme root or between it and the band. Verified (root-mapping fixture; unit case).
  • Claim: band-own tokens win, and a cycle-closing re-declaration is skipped. Verified (unit case; cycle filter).
  • Claim: every reference to a token the band does not hold uses its alias under the base rules, each query and overlaps, in any var() spelling. Verified (unit cases); escaped names are not covered (non-blocking).
  • Claim: adaptation queries restate changed values, re-declare newly scheme-dependent tokens and inherit dropped ones, and two overlapping rules show the root's value. Verified (unit cases).
  • Claim: a token that depends on the scheme only through undeclared tokens is not re-declared, and Core defaults stay in Core. Verified (unit cases).
  • Claim: the red-first rounds. Verified for the lowered-build suite (15 of 34 fail on the previous generator); the per-round unit cases pass here and were not re-run on their earlier generators.
  • Claim: the accent-lift test skips band copies and still asserts 5 root lifts. Verified (passes; also asserts 2 band copies).
  • Claim: core theme tests, the lowered-scheme and accent-lift files, the typecheck and the knowledge check pass. Verified (1,828 tests in 31 files; 35 tests; Core typecheck and knowledge check pass).
  • Claim: two build test files fail only on the author's machine. Not checked (CI did not run).
  • Claim: the root-mapping contrast table and the 52 media unit cases. Verified (2.67:1 to 5.65:1 and 2.10:1 to 9.29:1 in the fixture; 52 of 52 pass).
  • Claim: the earlier Chromium tables and screenshots. Consistent with this run's Neutral frames, which were measured afresh.
  • Claim: the size table. Verified for Neutral (+13,424 B raw).
  • Claim: the Record change block is INV12 at this head, with the listed applies_to, verified_by and verification row. Verified (word for word).
  • Claim: the writing rubric results and the out-of-scope items. Verified.
  • Changeset: a Core patch; lowered bands keep their colours; CSS that keeps light-dark() renders as before except that a value set on the theme root or between it and a band no longer reaches the band. Verified.
  • File .changeset/media-surface-lowered-scheme-tokens.md: clear.
  • File .gitignore: clear (the lowered suite's temporary folders).
  • File docs/architecture/theme-compilation.md: clear (INV12 approved for this head).
  • File packages/cli/api/theme-edit/theme-accent-lift.test.mjs: clear.
  • File packages/cli/api/theme/build/build.media-lowered-scheme.test.mjs: clear.
  • File packages/core/src/theme/__tests__/mediaSurfaceRootMapping.a11y.chromium.spec.ts: non-blocking (the OnLight case measures a dark page).
  • File packages/core/src/theme/declarationBoundary.test.ts: clear.
  • File packages/core/src/theme/declarationBoundary.ts: clear.
  • File packages/core/src/theme/generateThemeRules.ts: non-blocking (escaped names, uppercase LIGHT-DARK(, regex read-back, one long comment).
  • File packages/core/src/theme/onMediaTokens.test.ts: clear.
  • Pull request description: blocking (the User impact sentence).

Automated review (maintainer link)

@astracat-bot astracat-bot Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Approved pending CI: CI has not run on this draft head yet.

The lowered light-dark() fix holds: Neutral's lowered media band matches the un-lowered page in Chromium, the lowered-build suite passes for every published theme (it fails 12 of 28 theme cases on the previous generator), and INV12 as amended has an engineering owner's spec approval for this head. The description's User impact paragraph now names the theme-root case, which was the last open item.

Non-blocking: the new Chromium spec's "light surface on a light page" case measures a dark page because the OnLight story nests a dark-mode Theme, and the earlier notes on escaped names, uppercase LIGHT-DARK( and one long comment in the generator still apply.

Claims and files checked

Review mode: same-head; reason: none

  • Claim: apps whose bundler lowers light-dark() get the page's colours inside media bands in every light-dark() theme. Verified: the lowered-build suite fails 12 of 28 theme cases on the previous generator and passes 34 of 34 here.
  • Claim: lowered, Neutral's accent link on a light page's dark band reads #1b1b1b before the fix. Verified (lowered Neutral fixture on the base).
  • Claim: bands now resolve those colours under their own scheme. Verified: the lowered-build suite passes, and the head's lowered frame is pixel-identical to the as-written frame.
  • Claim: CSS that keeps light-dark() sees no change, except that a value set on the theme root, or between it and a band, no longer reaches the band. Verified (root-mapping fixture; band unit case for secondary text and icon).
  • Claim: every release from the first carries the defect, its bands re-declaring three tokens. Verified (the base generator writes only those band tokens and the status roles).
  • Claim: the workarounds are keeping light-dark() unlowered or setting the colour inside the band. Verified (as-written frames are correct on the base).
  • Claim: the cause is lowered switches resolving on the theme root while a band re-declares three tokens. Verified.
  • Claim: one generator serves the runtime Theme and astryx theme build. Verified (both call generateOnMediaCSS).
  • Claim: each scheme-dependent root token is re-declared with the root's value. Verified (unit cases); uppercase LIGHT-DARK( is not detected (non-blocking).
  • Claim: a reference to a band token takes the theme's value, and one the theme leaves unset stops the re-declaration. Verified (unit cases; built and lowered case).
  • Claim: a reference to a scheme-independent theme token takes the theme's value. Verified (unit case).
  • Claim: other references go through a private root alias with their fallback, no published theme writes one, and the cost is about 110 B. Verified (unit cases; the lowered-build suite checks every published theme).
  • Claim: references and cycles come from the declaration scanner, not a regex. Verified for the rewrite; alias names are read back with a regex (non-blocking).
  • Claim: a re-declared token ignores a value set on the theme root or between it and the band, band-own tokens win, and a cycle-closing re-declaration is skipped. Verified (unit cases; cycle filter).
  • Claim: every reference to a token the band does not hold uses its alias under the base rules, each query and overlaps, in any var() spelling. Verified (unit cases); escaped names are not covered (non-blocking).
  • Claim: adaptation queries restate changed values, re-declare newly scheme-dependent tokens and inherit dropped ones, and two overlapping rules show the root's value. Verified (unit cases).
  • Claim: a token that depends on the scheme only through undeclared tokens is not re-declared, and Core defaults stay in Core. Verified (unit cases).
  • Claim: the red-first rounds. Verified for the lowered-build suite; the per-round unit cases pass here.
  • Claim: the accent-lift test skips band copies and still asserts five root lifts. Verified (passes; also asserts two band copies).
  • Claim: core theme tests, the lowered-scheme and accent-lift files, the typecheck and the knowledge check pass. Verified.
  • Claim: two build test files fail only on the author's checkout path. Verified: both pass in this review's tree.
  • Claim: the root-mapping contrast table and the 52 band unit cases. Verified (2.67:1 to 5.65:1 and 2.10:1 to 9.29:1; 52 of 52 pass).
  • Claim: the earlier Chromium tables, screenshots and size table. Consistent with this review's Neutral frames and Neutral size.
  • Claim: the Record change block is INV12 at this head, with the listed applies_to, verified_by and verification row. Verified (word for word).
  • Claim: the writing rubric results and the out-of-scope items. Verified.
  • Changeset: a Core patch; lowered bands keep their colours; CSS that keeps light-dark() renders as before except that a value set on the theme root or between it and a band no longer reaches the band. Verified.
  • File .changeset/media-surface-lowered-scheme-tokens.md: clear.
  • File .gitignore: clear (the lowered suite's temporary folders).
  • File docs/architecture/theme-compilation.md: clear (INV12 approved for this head).
  • File packages/cli/api/theme-edit/theme-accent-lift.test.mjs: clear.
  • File packages/cli/api/theme/build/build.media-lowered-scheme.test.mjs: clear.
  • File packages/core/src/theme/__tests__/mediaSurfaceRootMapping.a11y.chromium.spec.ts: non-blocking (the OnLight case measures a dark page).
  • File packages/core/src/theme/declarationBoundary.test.ts: clear.
  • File packages/core/src/theme/declarationBoundary.ts: clear.
  • File packages/core/src/theme/generateThemeRules.ts: non-blocking (escaped names, uppercase LIGHT-DARK(, regex read-back, one long comment).
  • File packages/core/src/theme/onMediaTokens.test.ts: clear.
  • Pull request description: clear.

Automated review (maintainer link)

…ered-scheme-tokens

# Conflicts:
#	packages/cli/api/theme-edit/theme-accent-lift.test.mjs
@cixzhang

Copy link
Copy Markdown
Contributor Author

/approve-spec 2576aad

@astracat-bot astracat-bot Bot left a comment •

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Approved pending CI: this is a draft, so CI has not run on this head yet; marking it ready for review starts its run.

The lowered light-dark() fix holds: Neutral's lowered media band matches the un-lowered page in Chromium, the lowered-build suite passes for every published theme (also when merged with today's main), and INV12 as amended has an engineering owner's spec approval for this head.

Non-blocking:

  • The description's Size table understates the gzip cost for butter and y2k (about +1.2 KB each, not about +200 B), because their base CSS grew on main; the raw sizes and the other rows still hold.
  • The Chromium spec's "light surface on a light page" case measures a dark page, so only two of its four cases guard the change.
  • A reference written with a CSS escape gets no root alias (generateThemeRules.ts:1932), uppercase LIGHT-DARK( is not detected (:1907), and the comment at :2373 is long.
Claims and files checked

Review mode: same-head; reason: none

  • Claim: apps whose bundler lowers light-dark() get the page's colours inside media bands in every light-dark() theme. Verified: the lowered-build suite passes for every published theme at this head and merged with today's main; it failed 12 of 28 theme cases on the previous generator.
  • Claim: lowered, Neutral's accent link in a light page's dark band reads #1b1b1b before the fix. Verified (lowered Neutral fixture on the base).
  • Claim: bands now resolve those colours under their own scheme. Verified: the head's lowered frame is pixel-identical to the as-written frame.
  • Claim: CSS that keeps light-dark() sees no change, except that a value set on the theme root, or between it and a band, no longer reaches the band. Verified (root-mapping fixture; band unit case for secondary text and icon).
  • Claim: every release from the first carries the defect, its bands re-declaring three tokens. Verified (the base generator writes only those band tokens and the status roles).
  • Claim: the workarounds are keeping light-dark() unlowered or setting the colour inside the band. Verified (as-written frames are correct on the base).
  • Claim: the cause is lowered switches resolving on the theme root while a band re-declares three tokens. Verified.
  • Claim: one generator serves the runtime Theme and astryx theme build. Verified (both call generateOnMediaCSS).
  • Claim: each scheme-dependent root token is re-declared with the root's value. Verified (unit cases); uppercase LIGHT-DARK( is not detected (non-blocking).
  • Claim: a reference to a band token takes the theme's value, and one the theme leaves unset stops the re-declaration. Verified (unit cases; built and lowered case).
  • Claim: a reference to a scheme-independent theme token takes the theme's value. Verified (unit case).
  • Claim: other references go through a private root alias with their fallback, and no published theme writes one. Verified (unit cases; the lowered suite's alias check for every published theme); the probe theme's byte cost is carried from an earlier head.
  • Claim: references and cycles come from the declaration scanner, not a regex. Verified for the rewrite; alias names are read back with a regex (non-blocking).
  • Claim: a re-declared token ignores a value set on the theme root or between it and the band, band-own tokens win, and a cycle-closing re-declaration is skipped. Verified (unit cases; cycle filter).
  • Claim: every reference to a token the band does not hold uses its alias under the base rules, each query and overlaps, in any var() spelling. Verified (unit cases); escaped names are not covered (non-blocking).
  • Claim: adaptation queries restate changed values, re-declare newly scheme-dependent tokens and inherit dropped ones, and two overlapping rules show the root's value. Verified (unit cases).
  • Claim: a token that depends on the scheme only through undeclared tokens is not re-declared, and Core defaults stay in Core. Verified (unit cases; the generator reads only the theme's own values).
  • Claim: the red-first rounds. Verified for the lowered-build suite; each round's unit cases pass at this head.
  • Claim: the accent-lift test skips band copies and still asserts five root lifts. Verified: it asserts five root lifts and two band copies, and passes.
  • Claim: Core's theme tests, the lowered-scheme and accent-lift files, the typecheck and the knowledge check pass. Verified at this head; the theme tests and both files also pass merged with today's main.
  • Claim: two build test files fail only on the author's checkout path. The whole theme build test folder passes here, at this head and merged with today's main.
  • Claim: every published theme's band CSS matches the previous generator's and Gothic writes nothing new. Verified (generator unchanged since the head that claim measured; Gothic's built CSS is identical to the base).
  • Claim: the root-mapping contrast table and the band unit cases. Verified (2.67:1 to 5.65:1 and 2.10:1 to 9.29:1 in this review's fixture; all band cases pass).
  • Claim: the earlier Chromium tables and screenshots. Consistent with this review's Neutral frames.
  • Claim: the Size table. Raw growth matches for all seven themes; gzip growth is about +1.2 KB for butter and y2k, not about +200 B (non-blocking).
  • Claim: the Record change block is INV12 at this head, with the listed applies_to, verified_by and verification row. Verified (word for word).
  • Claim: the writing rubric results and the out-of-scope items. Verified.
  • Changeset: a Core patch; lowered bands keep their colours; CSS that keeps light-dark() renders as before except that a value set on the theme root or between it and a band no longer reaches the band. Verified.
  • File .changeset/media-surface-lowered-scheme-tokens.md: clear.
  • File .gitignore: clear (the lowered suite's temporary folders).
  • File docs/architecture/theme-compilation.md: clear (INV12 approved for this head; merges cleanly with main's edits to the same record).
  • File packages/cli/api/theme-edit/theme-accent-lift.test.mjs: clear.
  • File packages/cli/api/theme/build/build.media-lowered-scheme.test.mjs: clear.
  • File packages/core/src/theme/__tests__/mediaSurfaceRootMapping.a11y.chromium.spec.ts: non-blocking (the OnLight case measures a dark page).
  • File packages/core/src/theme/declarationBoundary.test.ts: clear.
  • File packages/core/src/theme/declarationBoundary.ts: clear.
  • File packages/core/src/theme/generateThemeRules.ts: non-blocking (escaped names, uppercase LIGHT-DARK(, regex read-back, one long comment).
  • File packages/core/src/theme/onMediaTokens.test.ts: clear.
  • Pull request description: non-blocking (the Size table's butter and y2k gzip rows).

Automated review (maintainer link)

…ered-scheme-tokens

# Conflicts:
#	docs/architecture/theme-compilation.md
#	packages/core/src/theme/generateThemeRules.ts
@cixzhang

Copy link
Copy Markdown
Contributor Author

/approve-spec 13e4ee1

@astracat-bot astracat-bot Bot left a comment •

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Changes requested: merging main's first-paint rule for toast cards that flip side on a dark page (INV21) left three problems in this fix.

  • Regression: build.media-lowered-scheme.test.mjs fails 6 of 34 cases, because lightningcss merges each light band with its identical dark-page copy into one selector list and blocks() (line 96) only reads a rule whose whole selector is [data-astryx-media="light"].
  • Regression: each adaptation rule's band restatements are written only for the plain side selector, after the dark-page copy (generateThemeRules.ts:2470 and :2199), so a toast card's first paint on a dark page takes its light-page side's restated value over its own onLight token (#000000 instead of the theme's #333333 under a narrow-width rule, with light-dark() kept).
  • Regression: the description's Size section says later heads are no larger than its table, but each light-dark() theme now grows 24.4–26.8 KB raw (Neutral 30,305 → 57,153 B), because a flipping theme writes the band block four times.

INV12 as amended has an engineering owner's approval for this head, and the lowered fix still holds in Chromium for Neutral. For the second point, the status-role restorations already write a dark-page copy under each query, which is the pattern to follow. Earlier non-blocking notes still stand: the Chromium spec's light-page case measures a dark page, escaped names get no root alias, and uppercase LIGHT-DARK( is not detected.

Claims and files checked

Review mode: same-head; reason: none

  • Claim: apps whose bundler lowers light-dark() get the page's colours inside media bands. Verified: the base's lowered Neutral band shows the page's surface and text.
  • Claim: lowered, Neutral's accent link on a light page's dark band reads #1b1b1b before the fix. Verified (rgb 27, 27, 27 on the base).
  • Claim: bands now resolve those colours under their own scheme. Verified: Neutral's lowered frame matches its as-written frame.
  • Claim: CSS that keeps light-dark() sees no change except that a value set on the theme root or between it and a band no longer reaches the band. False for a toast card that flips on a dark page under an adaptation rule; verified otherwise (Neutral as-written frames identical).
  • Claim: every release from the first carries the defect, its bands re-declaring three tokens. Verified (the base generator writes only those band tokens and the status roles).
  • Claim: the workarounds are keeping light-dark() unlowered or setting the colour inside the band. Verified.
  • Claim: the cause is lowered switches resolving on the theme root. Verified.
  • Claim: one generator serves the runtime Theme and astryx theme build. Verified (both call generateOnMediaCSS).
  • Claim: each scheme-dependent root token is re-declared with the root's value. Verified (unit cases); uppercase LIGHT-DARK( is missed (non-blocking).
  • Claim: a reference to a band token takes the theme's value, and one the theme leaves unset stops the re-declaration. Verified (unit cases).
  • Claim: a reference to a scheme-independent theme token takes the theme's value. Verified (unit case).
  • Claim: other references use a private root alias with their fallback, and no published theme writes one. Verified (unit cases and the lowered-build alias cases).
  • Claim: references and cycles come from the declaration scanner, not a regex. Verified for the rewrite; alias names are read back with a regex (non-blocking).
  • Claim: a re-declared token ignores a value set on the theme root or between it and the band. Verified (unit case; app-mapping frames).
  • Claim: tokens the band sets itself win, as before. False for a flipped toast card's first paint under an adaptation rule.
  • Claim: every other reference uses its alias under the base rules, each query and overlaps, in any var() spelling. Verified (unit cases); escaped names are not covered (non-blocking).
  • Claim: a cycle-closing re-declaration is skipped. Verified.
  • Claim: adaptation queries restate changed values, re-declare newly scheme-dependent tokens, inherit dropped ones, and overlapping rules show the root's value. Verified for plain bands (unit cases); not for a flipped surface.
  • Claim: a token that depends on the scheme only through undeclared tokens is not re-declared, and Core defaults stay in Core. Verified (unit cases).
  • Claim: the red-first rounds and their tests pass. The unit cases pass; the lowered-build suite fails 6 of 34 at this head.
  • Claim: the accent-lift test skips band copies and still asserts five root lifts. Verified (passes).
  • Claim: the theme test tallies, typecheck and knowledge check. Theme unit files, typecheck and knowledge check pass; the lowered-build file has the six failures above.
  • Claim: published themes' band CSS matches the previous generator's. Stale at this head: each flipping theme now writes its band four times (see the Size point).
  • Claim: the root-mapping contrast table. Verified (2.67:1 to 5.65:1 dark band, 2.10:1 to 9.29:1 light band).
  • Claim: the earlier Chromium tables and screenshots. Consistent with the frames at this head.
  • Claim: the Size table and that later heads are no larger. False (about twice the table's raw growth).
  • Claim: the Record change block is INV12 at this head, with the listed applies_to, verified_by and verification row. Verified (word for word).
  • Claim: the writing rubric results and the out-of-scope items. Verified.
  • Changeset: a Core patch; lowered bands keep their colours; CSS that keeps light-dark() renders as before with one exception. False for the flipped-toast case above.
  • File .changeset/media-surface-lowered-scheme-tokens.md: its "renders as before" sentence fails for flipped toast cards.
  • File .gitignore: clear.
  • File docs/architecture/theme-compilation.md: clear (INV12 approved for this head).
  • File packages/cli/api/theme-edit/theme-accent-lift.test.mjs: clear.
  • File packages/cli/api/theme/build/build.media-lowered-scheme.test.mjs: blocking (fails 6 of 34).
  • File packages/core/src/theme/__tests__/mediaSurfaceRootMapping.a11y.chromium.spec.ts: non-blocking (the light-page case measures a dark page).
  • File packages/core/src/theme/declarationBoundary.test.ts: clear.
  • File packages/core/src/theme/declarationBoundary.ts: clear.
  • File packages/core/src/theme/generateThemeRules.ts: blocking (adaptation restatements on flipped surfaces); non-blocking (escaped names, uppercase LIGHT-DARK(, regex read-back, one long comment).
  • File packages/core/src/theme/onMediaTokens.test.ts: clear.
  • Pull request description: blocking (Size section).

Automated review (maintainer link)

…r an adaptation rule

A restatement under a query is written for a side's own selector, which also
reaches a card that a dark page flips to the other side. Each side a dark page
flips a card to now writes dark-page copies under the query: its restatements,
and its own value for a token the other side restates. The lowered-build test
reads a band rule that lightningcss joins with its dark-page copy.
@cixzhang

Copy link
Copy Markdown
Contributor Author

/approve-spec 42d7286

@astracat-bot astracat-bot Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Changes requested: the red lowered-build test, the flipped toast card's own-token override and the Size section from the last review are fixed, but the new dark-page copies under adaptation rules still let one side's restatement reach a toast card that a dark page flips.

  • Regression: darkPageRestatements (generateThemeRules.ts:2419-2426) copies only the tokens the flipped side restates or holds, so in a theme whose onDark holds --color-border-emphasized, whose onLight holds --color-border and whose narrow-width rule changes the first, the card's --color-background-muted computes color(srgb 0.6 0.1 0.1) instead of the 0.7 0.2 0.2 that main and a plain light surface show, with light-dark() kept (INV21, and the changeset's single exception).

Writing the light-page side's restatements with its @unflipped selectors, as the base rules do, or copying this side's value for every token the other side restates would close it, with an onMediaTokens.test.ts case for a token only the light-page side restates. INV12 as amended has an engineering owner's approval for this head, and no published theme meets the case, since their adaptation rules change only the type scale. Earlier non-blocking notes still stand: the Chromium spec's light-page case measures a dark page, escaped names get no root alias, and uppercase LIGHT-DARK( is not detected.

Claims and files checked

Review mode: incremental; reason: none

  • changed rules (0): none
  • Claim: apps whose bundler lowers light-dark() get the page's colours inside every media surface of a light-dark() theme. Verified: the base's lowered Neutral dark band computes a white surface under white text.
  • Claim: lowered, Neutral's accent text on a light page's dark band is near-black before the fix. Not re-measured here; consistent with the base frame.
  • Claim: surfaces now resolve those colours under their own scheme. Verified: the head's lowered Neutral bands compute their own surface, text and border; the lowered-build suite passes 34 of 34.
  • Claim: CSS that keeps light-dark() sees no change apart from values set on the theme root or between it and a surface. False for a toast card a dark page flips under a colour adaptation rule (probe: 0.7 0.2 0.2 on the base, 0.6 0.1 0.1 on the head).
  • Claim: every release from the first carries the defect. Verified: the base generator re-declares only primary text, primary icon and accent on a surface.
  • Claim: the known-issue workarounds. Verified by the cause.
  • Claim: the cause is lowered switches resolving on the theme root. Verified.
  • Claim: one generator serves the runtime Theme and astryx theme build. Verified (both call generateOnMediaCSS).
  • Claim: surface-token and scheme-independent references take the theme's value, an unset surface token stops the re-declaration, other references use a root alias with their fallback. Verified (unit cases pass).
  • Claim: the alias costs about 113 B for a probe theme, and no published theme writes one. The second part verified (lowered-build alias case); the size not re-measured.
  • Claim: references and cycles come from the declaration scanner, not a regex. Verified for the rewrite; alias names are read back with a regex (non-blocking).
  • Claim: a re-declared token ignores a value set on the theme root or between it and the surface. Verified (unit case).
  • Claim: tokens the surface sets itself win, as before. Verified, including on a flipped toast card under an adaptation rule.
  • Claim: every other reference uses its alias under base rules, queries and overlaps, in any var() spelling. Verified (unit cases); escaped names are not covered (non-blocking).
  • Claim: a cycle-closing re-declaration is skipped. Verified (code and unit cases).
  • Claim: under each adaptation query the surface takes every value the root resolves there, and overlapping rules show the root's value. Verified for plain surfaces; false for a flipped toast card (the probe above).
  • Claim: a token that depends on the scheme only through undeclared tokens is not re-declared, and Core defaults stay in Core. Verified (unit cases).
  • Claim: the red-first rounds and their named tests. The named tests exist and pass at this head; the red runs were not repeated.
  • Claim: the earlier Chromium tables and before/after frames. Measured at earlier heads as labelled; consistent with this run's Neutral frames.
  • Claim: the accent-lift test skips surface copies, still asserts five root lifts and two surface copies. Verified (passes).
  • Claim: published themes' surface CSS matches the previous generator. Verified for the latest commit: no published theme writes surface restatements under an adaptation query.
  • Claim: the root-mapping case and its contrast table. The unit case passes; the count is now 54 cases, not 52 (non-blocking); the Chromium spec was not run.
  • Claim: the Size table. Verified: each theme's raw growth matches this run's built theme.css exactly (Neutral +26,848 B); gzip within a few bytes.
  • Claim: a shared selector list would save about 5.4 KB raw and 40 B gzip. Not measured.
  • Claim: the Record change block is INV12 at this head, with its applies_to, verified_by and verification row. Verified (word for word).
  • Claim: the writing rubric results. Verified, except that INV12's "resolves as before" fails for the flipped-card case.
  • Changeset: a Core patch; lowered surfaces keep their colours; CSS that keeps light-dark() renders as before with one exception. The exception sentence is false for the flipped-card case.
  • File .changeset/media-surface-lowered-scheme-tokens.md: its single exception fails for the flipped-card case (same finding).
  • File .gitignore: clear.
  • File docs/architecture/theme-compilation.md: clear (INV12 approved for this head).
  • File packages/cli/api/theme-edit/theme-accent-lift.test.mjs: clear.
  • File packages/cli/api/theme/build/build.media-lowered-scheme.test.mjs: clear (34 of 34 pass).
  • File packages/core/src/theme/__tests__/mediaSurfaceRootMapping.a11y.chromium.spec.ts: non-blocking (its light-page case measures a dark page).
  • File packages/core/src/theme/declarationBoundary.test.ts: clear.
  • File packages/core/src/theme/declarationBoundary.ts: clear.
  • File packages/core/src/theme/generateThemeRules.ts: blocking (dark-page copies under adaptation rules); non-blocking (escaped names, uppercase LIGHT-DARK(, alias regex, two long comments).
  • File packages/core/src/theme/onMediaTokens.test.ts: clear; no case covers a token only the light-page side restates.
  • Pull request description: the "no change" sentence fails for the flipped-card case; one stale test count (non-blocking).

Automated review (maintainer link)

Comment on lines +2419 to +2426
const kept = (restatedBySide.get(other) ?? []).flatMap(
([name]): [string, string][] => {
const value = own.get(name);
return value === undefined || restatedNames.has(name)
? []
: [[name, value]];
},
);

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Regression (INV21): kept adds this side's own value only for a token it holds, so a token that only the other side restates under the rule is never copied, and the plain [data-astryx-media="dark"] restatement still lands on a card a dark page flips. Probe with light-dark() kept: onDark holds --color-border-emphasized, onLight holds --color-border, a narrow-width rule sets --color-border-emphasized: light-dark(#ff0000, #aa0000), and the root has --color-background-muted: color-mix(in srgb, var(--color-border-emphasized) 50%, var(--color-border)). At 800 px on a dark page the dark side restates the muted background with var(--color-border), the light copy writes only the emphasized border, and the card computes color(srgb 0.6 0.1 0.1); main and a plain light surface show 0.7 0.2 0.2. Writing the light-page side's restatements with its @unflipped selectors (as the base rules do), or copying this side's value (restatement, own value, base re-declaration or inherit) for every token the other side restates, would close it. The overlap blocks reuse this copier (line 2220).

Comment on lines +2404 to +2406
* flips to the other side. So, for each side a dark page flips a surface to,
* the copy writes that side's restatements and, for a token the other side
* restates but this side holds, this side's own value.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Non-blocking (INV29): this sentence runs 33 words over two topics. Suggested: "A side's restatement also reaches a surface that a dark page flips to the other side. The copy writes the flipped side's restatements. For a token only the other side restates, it writes this side's own value."

This branch was successfully deployed

1 active deployment
Preview — 42d72862 Deployed Nov 19, 2026 by vercel[bot]
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

CLA Signed This label is managed by the Meta Open Source bot.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant