Skip to content

Fix elevation tint hiding consumer backgrounds on Paper components - #319

Open
zoharma wants to merge 2 commits into
mainfrom
zma/elevation-review
Open

zoharma wants to merge 2 commits into
mainfrom
zma/elevation-review

Conversation

@zoharma

@zoharma zoharma commented Sep 17, 2026

Copy link
Copy Markdown
Contributor

Summary

Fixes #318: sx background colours on Card, Accordion, and other elevated Paper components had no visible effect. DiamondDS paints elevation as an opaque background-image, which always paints above background-color, so no consumer colour could show through.

Fix

  • MuiPaper: paint tonal elevation as backgroundColor instead of backgroundImage, guarded to elevation > 0 so Alert(elevation={0}) keeps its own background
  • MuiAutocomplete: same change, routed through the same surface.elevated() helper as MuiPaper instead of a duplicated token string
  • surface.elevated() now rounds before clamping, so a fractional elevation degrades to the nearest valid step instead of silently dropping the tint
  • Token values unchanged, only how the tint is painted

Moving the tint to background-color gives exact, computable surface colours, similar to M3's elevation direction.

Examples

Before (#318 bug: background-image painted over the colour)
image

After (fix: background-color, consumer colour wins)
Following Material 3 style.
image

For comparison (translucent tint over the same colour)
Mirrors MUI / Material 2 dark-mode overlay direction, in light mode. Elevation keeps a visible effect even with a custom colour set, and provides a "dirty" colour.
image

Testing

  • Regression tests for the new override shape
  • New render-based tests (jsdom can't catch paint-order bugs, but can catch cascade-order ones): a consumer sx background wins over the tint, Alert keeps its own background at elevation={0}, Autocomplete's listbox gets its own elevation tier over MuiPaper's default, and a slotProps.paper.sx background (NavMenu) still wins
  • Verified in a real browser for the paint-order bug itself: red sx background was invisible pre-fix, renders correctly post-fix in both light and dark

Storybook

  • Added a CustomBackground story to Paper (elevation + a custom colour). No existing Paper/Card/Accordion story exercised this
  • Bumped a couple of stories off elevation={1}/2 where the tonal tint was too subtle to actually see

)

- Paint tonal elevation as background-color instead of backgroundImage,
  guarded to elevation > 0 so Alert's elevation={0} stays untouched
- Update MuiAutocomplete's listbox background to match, via the shared
  surface.elevated() helper instead of duplicated token strings
- Round elevation before clamping so a fractional value degrades to the
  nearest valid step instead of silently dropping the tint
- Add regression tests for the override shape and for real rendered
  cascade order (Paper + sx, Alert, Autocomplete, Menu)
- Add a Paper story for a custom background at elevation, and bump
  low-visibility elevation values in existing stories
@zoharma
zoharma force-pushed the zma/elevation-review branch from 434b1fa to 89c2123 Compare September 17, 2026 20:09
@zoharma
zoharma marked this pull request as ready for review September 17, 2026 20:15
@zoharma
zoharma requested a review from a team September 17, 2026 20:15
@zoharma zoharma added this to the 0.7.2 milestone Sep 17, 2026
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.

Bug: sx background not applied on Card/Accordion: Theme paints an opaque background-image

1 participant