Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

docs(theme): define declaration boundaries and warning collection (#6493)

Cindy Zhangb333c3981ae2
diff --git a/docs/architecture/theme-compilation.md b/docs/architecture/theme-compilation.md
index c8dae4a3cf..e80d9edfaf 100644
--- a/docs/architecture/theme-compilation.md
+++ b/docs/architecture/theme-compilation.md
@@ -7,7 +7,7 @@ authority: current
archive_reason: null
superseded_by: null
approved_by: cixzhang
-approved_at: 2026-08-30
+approved_at: 2026-09-23
owners: [cixzhang, imdreamrunner]
applies_to:
[
@@ -140,6 +140,29 @@ Platform-specific details stay inside that compiler.
emit last. Duplicate conditions and later root-restoring writes are preserved
exactly; runtime and static output use the same blocks.
+- **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
+ declaration/rule boundary. It drops that declaration and continues generating the
+ rest of the theme, including inherited and conditional surfaces. The boundary
+ check preserves valid authored CSS bytes, including quoted semicolons/braces,
+ data URLs, escapes, closed comments, nested functions, vendor-prefixed names, and
+ `!important`. It is not a property-value grammar validator. Legacy unenrolled
+ token values retain their historical string interpolation; this check must not
+ introduce a crash for values such as `null`. Existing construction validation,
+ including atomic enrolled local-token validation, remains separate and unchanged.
+- **INV14 — Reporting does not change compilation.** Dropped declarations produce
+ runtime warnings and appear in the existing static-build receipt's `warnings`.
+ The existing `generateThemeRules`, `generateThemeRulesSplit`, `generateThemeCSS`,
+ `generateOnMediaCSS`, and `generateAdaptationCSS` operations may accept one
+ optional `warnings?: string[]` collector. Supplying it only appends warning text
+ instead of writing that text to the console; it does not change generated CSS,
+ clear existing array entries, change validation, or mutate the theme. Omission
+ retains normal runtime warning behavior. This transport does not introduce a
+ callback API, exported diagnostics/options types, theme metadata, or a structured
+ diagnostics schema. A CLI paired with an older core retains that core's existing
+ compilation behavior; it does not pretend to detect drops the older core cannot
+ report.
+
This record does not own:
- token names and defaults, including the meanings of theme-local names;
@@ -198,6 +221,11 @@ This record does not own:
- Adding a platform compiler names the shared concepts it supports and tests
that they keep the same meaning. Unsupported concepts fail clearly instead of
disappearing.
+- Declaration-boundary changes verify positive and negative scanner cases, local
+ dropping with surviving neighbors, legacy token generation, and runtime/build
+ parity across tokens, local tokens, variants, pseudo states, media surfaces,
+ adaptations, inheritance, and Heading fallback rules. Collector tests verify
+ append-only text, unchanged CSS with/without a collector, and build receipts.
- Build packaging may change without changing compiled theme behavior.
## Owning code
@@ -233,20 +261,25 @@ tiers.
## Verification
-| Invariant | Evidence | Failure signal |
-| ---------------- | ------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------- |
-| INV1, INV2, INV3 | Compiler imports and runtime/build comparison fixtures | Runtime and build use different theme-to-CSS logic or produce different web rules |
-| INV4 | `generateThemeRules.test.ts` and source/distribution cascade tests | Scope or layer order differs by output path |
-| INV5 | Existing per-property fixtures (partial; gap below) | A guaranteed property compiles but does not produce its promised observable effect |
-| INV6, INV7 | Existing registry and CLI public-variable tests (partial) | Private variables become authorable, or a reviewed public semantic variable fails build/runtime |
-| INV8 | Component target metadata and compatibility review | Successful generic emission is treated as a guaranteed public behavior |
-| 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 |
-| Built themes | Theme and CLI build tests | Runtime recompiles a built theme, or built output omits canonical rules |
+| Invariant | Evidence | Failure signal |
+| ---------------- | --------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
+| INV1, INV2, INV3 | Compiler imports and runtime/build comparison fixtures | Runtime and build use different theme-to-CSS logic or produce different web rules |
+| INV4 | `generateThemeRules.test.ts` and source/distribution cascade tests | Scope or layer order differs by output path |
+| INV5 | Existing per-property fixtures (partial; gap below) | A guaranteed property compiles but does not produce its promised observable effect |
+| INV6, INV7 | Existing registry and CLI public-variable tests (partial) | Private variables become authorable, or a reviewed public semantic variable fails build/runtime |
+| INV8 | Component target metadata and compatibility review | Successful generic emission is treated as a guaranteed public behavior |
+| 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 |
+| 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 |
+| Built themes | Theme and CLI build tests | Runtime recompiles a built theme, or built output omits canonical rules |
## Known conformance and verification gaps
+Declaration-boundary enforcement and the warnings-array collector in INV13–INV14
+are accepted but not yet shipped. Their verification obligations above describe
+implementation acceptance, not existing enforcement.
+
Prefix-independent `localTokens` key acceptance is accepted but unshipped. The current
compiler still requires the original theme-derived prefix and uses that prefix to
classify local references. Until implementation lands, INV11's prefix-independent