Skip to content

feat(theme): add semantic container color prop to Surface - #5121

Open
hristototov wants to merge 1 commit into
mainfrom
hristototov/surface-semantic-container-color
Open

hristototov wants to merge 1 commit into
mainfrom
hristototov/surface-semantic-container-color

Conversation

@hristototov

Copy link
Copy Markdown
Collaborator

Motivation

Surface derives its background from the numeric elevation prop, so a component cannot express "this container is surfaceContainerLow, and elevation only controls the shadow" without passing a raw color. This adds a first-class semantic API for it:

  • New container prop on Surface accepting a surface-family color role (surface, surfaceDim, surfaceBright, surfaceVariant, surfaceContainerLowest-Highest, inverseSurface), resolved from the theme. Precedence: backgroundColor > container > elevation-derived color.
  • When container is set, elevation only affects the shadow. Animated elevation no longer interpolates the background.
  • Default behaviour is unchanged; no migration needed for existing consumers.
  • Menu (surfaceContainer, per MD3 spec) and Banner (surfaceContainerLow) migrated onto it. Pixel-identical at their default elevations since elevation.level1-5 map to the same tones. Consumers using non-default elevations now get only a shadow change (noted in the migration guide).
  • New public SurfaceRole type.

Related issue

Fixes #5119.

Screenshots / Videos

light-mode.mov
dark-mode.mov

Test plan

  • yarn typecheck, yarn lint, yarn test — all green (55 suites, 693 tests; no snapshot diffs, confirming the Menu/Banner migrations are visually unchanged).
  • New Surface tests

@hristototov
hristototov requested review from JKobrynski, adrcotfas and satya164 and removed request for JKobrynski and satya164 September 14, 2026 12:29
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Surface: first-class semantic container color API independent of elevation

1 participant