feat(core): add elevation prop to configurable surfaces#4251
Open
kentonquatman wants to merge 1 commit into
Open
feat(core): add elevation prop to configurable surfaces#4251kentonquatman wants to merge 1 commit into
kentonquatman wants to merge 1 commit into
Conversation
Add an `elevation` prop to the configurable surfaces from the elevation system proposal (#4146). Card, ClickableCard, SelectableCard, Button, IconButton, ButtonGroup, Thumbnail, and Banner take the full `'none' | 'low' | 'med' | 'high'` scale; ChatComposer takes the narrowed `'none' | 'low'`. Levels map to the existing `--shadow-low/-med/-high` tokens; `none` is a flat literal. Defaults preserve today's appearance — `none` everywhere except ChatComposer, which defaults to `low` to keep its raised look. Composition is preserved rather than clobbered: Card routes elevation and SelectableCard's inset selection ring through separate box-shadow slots so a selected card keeps its shadow, and Thumbnail's resting elevation coexists with its hover-shadow bump. Button elevation is skipped inside a ButtonGroup, where the group owns the shared surface's shadow. Also documents the elevation prop layer in the elevation foundation doc.
kentonquatman
requested review from
cixzhang,
ejhammond,
imdreamrunner and
josephfarina
as code owners
July 23, 2026 07:44
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
meta-cla
Bot
added
the
CLA Signed
github-actions
Bot
added
the
needs:code-review
Contributor
PR Analysis Report📚 Storybook PreviewView Storybook for this PR 🧪 Sandbox PreviewView Sandbox for this PR Modified ComponentsBanner · View in Storybook
Button · View in Storybook
ButtonGroup · View in Storybook
Card · View in Storybook
Chat · View in Storybook
ClickableCard · View in Storybook
IconButton · View in Storybook
SelectableCard · View in Storybook
Thumbnail · View in Storybook
Bundle Size Summary
Accessibility AuditStatus: 6 accessibility violation(s) found — 6 serious. Banner - 1 issue(s)
Card - 1 issue(s)
Chat - 1 issue(s)
ClickableCard - 1 issue(s)
SelectableCard - 1 issue(s)
Thumbnail - 1 issue(s)
Generated by PR Enrichment workflow | Storybook | Sandbox | View full report |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Implements the Elevation prop (configurable surfaces) table from the elevation system proposal (#4146). Adds a single
elevationprop to every configurable surface, narrowed per component to the steps it needs.'none' | 'low' | 'med' | 'high''none''none' | 'low' | 'med' | 'high''none''none' | 'low' | 'med' | 'high''none''none' | 'low''low''none' | 'low' | 'med' | 'high''none''none' | 'low' | 'med' | 'high''none''none' | 'low' | 'med' | 'high''none''none' | 'low' | 'med' | 'high''none''none' | 'low' | 'med' | 'high''none'Levels map to the existing
--shadow-low/-med/-hightokens;noneis the flatbox-shadow: noneliteral. No new tokens.No breaking changes
Every prop defaults to today's behavior, so nothing changes unless a consumer opts in:
'none'.'low'(low at rest, bumping to med on hover / focus, exactly as before). Setelevation="none"to flatten it.'none'default.Composition, not clobbering
box-shadowis a single CSS property, so a few surfaces needed care so elevation coexists with an existing shadow rather than overwriting it:--_card-ring,--_card-elevation). SelectableCard now drives its inset selection ring through--_card-ring, so a selected card keeps its resting elevation.--_thumbnail-elevation, which the existing:hover → medbump reads, so a raised tile still bumps on hover.elevationfor free by composing Button; ClickableCard/SelectableCard forward it to Card.Intrinsic overlays (Dialog, Popover, Tooltip, Toast, HoverCard, DropdownMenu, …) are unchanged — they bake elevation in and expose no prop.
What's included
elevationprop on all 9 configurable-surface components, with a sharedElevationtype inutils/types..doc.mjs— English, 中文, and dense variants) soastryx component <Name>reflects the new prop.elevationcontrols on each component's stories plus dedicated stories (CardElevations, ButtonElevations, BannerFloating, ChatComposerFlat).Interaction-driven elevation (drag/reorder lift) is intentionally out of scope per the proposal's appendix.
Checks
build,test(154 passing across the touched files),lint/check:repo, core + docs + template-docs + storybook typechecks,sync-exports --check, andcheck:changesetsall pass locally.Implements the first-PR scope of #4146 (the
elevationprop + foundation doc). The proposal's lint/review guard for rawbox-shadowis a separate follow-up.