[Mohamed Mansour (mohamedmansour)]

Press consumers currently have to duplicate theme CSS generation, pre-paint preference restoration, and header customization to support multiple design families. This adds a shared appearance integration without coupling Press to a particular component library.

Approach

• Compile independent light/dark theme sources into deterministic shared CSS using a baseline and grouped deltas. Preserve literal initial values, missing-token resets, and consumer stylesheet precedence.
• Share one document preference owner across pre-paint initialization, controls, and the exported @microsoft/webui-press/appearance.js API. Keep family and System/Light/Dark preferences independent, synchronize OS and cross-tab changes, and use native view transitions for user changes while respecting reduced motion and forced colors.
• Publish the required initializer as one fingerprinted same-origin static script, loaded synchronously before stylesheet links and hydration. It needs no inline-script exception or per-request nonce; missing or denied required assets remain explicit deployment/CSP errors.
• Add a palette-triggered native Appearance popover with a customizable native family select and labeled System/sun/moon buttons. Present the same controls inline in a full-height mobile navigation drawer that covers the header, slides in with native CSS transitions, and respects reduced motion. Preserve focus restoration across slotted shadow roots.
• Add nested header regions with explicit fallback ownership. Replacing a parent suppresses descendant state/scripts/assets; single-family builds omit the family picker and its assets entirely.

Compatibility and migration

Legacy theme configuration remains a single-family integration; do not combine it with appearance. Render metadata is namespaced under webuiPress.appearance to avoid collisions with component properties. Existing data-theme CSS remains usable, and content-only builds continue following the OS without consuming shell preferences or emitting the initializer.

Deploy the generated initialization asset with the rest of the site and authorize it in the site's CSP. The site's other generated scripts still require their own CSP authorization; this does not claim that script-src 'self' alone authorizes all existing inline hydration payloads.

The companion consumer migration must follow a release containing this feature and matching compiler/framework packages. Its local preview package links are not included in this PR.

CSS size

Measured with the same three official theme snapshots and exact token-parity assertions. The previous generator was reconstructed from frozen source rather than a preserved build directory.

Generated theme CSS	Previous consumer generator	Press integration	Reduction
Raw	390,294 B	303,086 B	22.3%
Gzip-9	42,616 B	37,871 B	11.1%

Initialization moves 2,218 bytes into one shared asset (866 bytes gzip), replacing the repeated inline initializer in each page. This adds one cacheable request on a cold load.

Validation

• cargo xtask check, including documentation and example builds.
• 126 Press/docs browser and native integration tests covering native controls, responsive layout, full-height drawer geometry and motion, focus, pre-paint/no-JS behavior, storage failures, cross-tab synchronization, token precedence, transitions, and deterministic output.
• Browser-enforced CSP coverage with no inline-bootstrap authorization: saved preferences, controls, reload, OS changes, delayed initialization, first-paint appearance, and hydration scripts disabled. Genuine initialization-load failures are surfaced explicitly.
• Cold Rust test execution without generated projection output or TypeScript incremental cache. Pure CSS inventory checks stay in Rust; full-shell build coverage runs in the native integration suite after its JavaScript prerequisites are built.
• Real MAI consumer integration, including exact token parity across all six family/mode combinations and 15 targeted saved-preference/deferred-hydration regressions against the updated native artifact.
• Desktop and mobile documentation screenshots remain byte-identical after the initialization delivery change.
• Updated public documentation and architectural boundaries.

Screenshots

Only this repository's /docs site is shown. It has one configured theme family, so the family select is intentionally omitted while System/Light/Dark controls remain available.

Desktop

Mobile

[mddinbox]

Target: 6ceba63...8a75fa8 | Coverage: complete; CI: PR Checks, CodeQL, Docs, FFI, E2E (Ubuntu), Test, Build (Linux/macOS/Windows) — success
Challenge: 1 confirmed; Compatibility: strict-script-src deployments lose interactive appearance controls
Action: COMMENT | The CSP initialization failure is detailed inline.