UI: Implement elevation prop for Box component

[Suhel-Shaikh-Mohammad]

What

Added elevation support to the Box component by introducing a new elevation prop that allows developers to apply shadow effects using design tokens from the theme package.

Why

The Box component is a foundational primitive that provides design system-based styling for layouts. Elevation (shadows) are a critical visual tool for creating depth, hierarchy, and visual distinction in UI interfaces. This addresses GitHub issue #72784, which outlined the need for elevation support as part of the Box component's comprehensive token integration.

Without elevation support, developers would need to manually apply box-shadow styles, bypassing the design system's centralized token management. This change ensures consistency across the application and maintains a single source of truth for all elevation styling.

How

The implementation leverages the existing elevation tokens defined in packages/theme/tokens/elevation.json, which provides four elevation levels:

• x-small: For subtle shadows on grouped content
• small: For contextual feedback without being intrusive (tooltips, snackbars)
• medium: For components offering additional actions (menus, command palette)
• large: For components requiring attention (modals, dialogs)

The elevation prop directly maps to CSS variables following the pattern --wpds-elevation-{level}, ensuring consistency with the design token naming convention.

Testing

Unit Tests

• All tests passing - Verified with npm run test:unit

Storybook Verification

• Visual testing in Storybook

Story: WithElevation

• Display: Flex container showing all four elevation levels side-by-side
• Visual Properties:
  • Light neutral background to show shadow depth
  • Consistent padding and border-radius for fair comparison
  • Gap spacing (24px) for clear visual separation
• Purpose: Allows manual verification of shadow rendering and depth hierarchy

Integration Points Tested

• Elevation with other Box props:
• Elevation + backgroundColor (test confirms shadows are visible against backgrounds)
• Elevation + padding (confirms prop isolation, no conflicts)
• Elevation + borderRadius (confirms visual consistency)
• Elevation alone (confirms functionality without dependencies)

CSS Variable Resolution

• Design token integration:
• Elevation props correctly reference --wpds-elevation-{level} CSS variables
• CSS variables are defined in theme package's elevation.json
• Fallback behavior: Browser uses defined token values; if variable not found, browser defaults apply

Related Issues

Addresses: #72784 - Component: Box

Related PRs

• UI: Implement Box component as part of new UI package #72984 - UI: Implement Box component as part of new UI package
• UI: Add border support to Box component #73530 - UI: Add border support to Box component

Checklist

• Type definitions added/updated
• Component implementation complete
• Unit tests added and passing
• Storybook story added for visual verification
• JSDoc comments added
• All tests passing (npm run test:unit)
• No breaking changes to existing Box functionality
• Follows existing code patterns and conventions

[github-actions]

The following accounts have interacted with this PR and/or linked issues. I will continue to update these lists as activity occurs. You can also manually ask me to refresh this list by adding the props-bot label.

If you're merging code through a pull request on GitHub, copy and paste the following into the bottom of the merge commit message.

Co-authored-by: Suhel-Shaikh-Mohammad <suhel5047@git.wordpress.org>
Co-authored-by: ciampo <mciampini@git.wordpress.org>

To understand the WordPress project's expectations around crediting contributors, please review the Contributor Attribution page in the Core Handbook.

[github-actions]

👋 Thanks for your first Pull Request and for helping build the future of Gutenberg and WordPress, @Suhel-Shaikh-Mohammad! In case you missed it, we'd love to have you join us in our Slack community.

If you want to learn more about WordPress development in general, check out the Core Handbook full of helpful information.

[Suhel-Shaikh-Mohammad]

Hi @aduth and @jameskoster! 👋

I've implemented elevation support for the Box component as discussed in #72784. This PR adds:

• Four elevation levels (x-small, small, medium, large) using design tokens
• Storybook story for visual verification
• Comprehensive unit tests

Since you both discussed this feature in the issue, I'd really appreciate your review and feedback!

Label Suggestion

This PR requires a [Type] label to merge. I suggest: [Type] Feature since this adds new elevation functionality to the Box component. Feel free to adjust if you prefer [Type] Enhancement or another label that better fits the project's classification.

[ciampo]

Thank you for the work, @Suhel-Shaikh-Mohammad !

As the @wordpress/ui package is still very much a WIP, we're still evaluating our approach to exposing Design Tokens, and we may actually soon try to remove Box in favour of using DS tokens directly in the CSS. (apologies for not reflecting this in #72784 earlier , this is all very much recent and in flux — but we did now).

Should we instead decide to move forward with the Box component, we'll surely take a look at this PR!

[Suhel-Shaikh-Mohammad]

@ciampo Hii, Thanks a lot for the follow-up, totally appreciate it.

I would like to know if the discussion regarding this is held in Slack community?
Since I am very interested about this issue (as it was my first PR), I would like to catch up with the discussion. Looking forward to it!
Also apologies for my Naiveness!

[ciampo]

@Suhel-Shaikh-Mohammad see #72784 (comment)