Skip to content

Theme: Update elevation tokens to use abbreviated size names #75103

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
aduth wants to merge 1 commit into
base: trunk
Choose a base branch
from
Open

Theme: Update elevation tokens to use abbreviated size names #75103

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
65 changes: 37 additions & 28 deletions packages/theme/CHANGELOG.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,47 +2,56 @@

## Unreleased

### Breaking changes

- Renamed elevation tokens to use abbreviated size names for consistency with other tokens:
- `--wpds-elevation-x-small`: use `--wpds-elevation-xs` instead.
- `--wpds-elevation-small`: use `--wpds-elevation-sm` instead.
- `--wpds-elevation-medium`: use `--wpds-elevation-md` instead.
- `--wpds-elevation-large`: use `--wpds-elevation-lg` instead.

## 0.6.0 (2026-01-29)

## 0.5.0 (2026-01-16)

### Breaking changes

- Renamed border tokens to remove the `surface` segment from token names ([#74617](https://github.com/WordPress/gutenberg/pull/74617)):
- `--wpds-border-radius-surface-xs`: use `--wpds-border-radius-xs` instead.
- `--wpds-border-radius-surface-sm`: use `--wpds-border-radius-sm` instead.
- `--wpds-border-radius-surface-md`: use `--wpds-border-radius-md` instead.
- `--wpds-border-radius-surface-lg`: use `--wpds-border-radius-lg` instead.
- `--wpds-border-width-surface-xs`: use `--wpds-border-width-xs` instead.
- `--wpds-border-width-surface-sm`: use `--wpds-border-width-sm` instead.
- `--wpds-border-width-surface-md`: use `--wpds-border-width-md` instead.
- `--wpds-border-width-surface-lg`: use `--wpds-border-width-lg` instead.
- `--wpds-border-width-interactive-focus`: use `--wpds-border-width-focus` instead.

Copy link
Member Author

@aduth aduth Jan 30, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The existing formatting is pretty messed up:

https://github.com/WordPress/gutenberg/blob/6f2c7aa4f663fa797fd770ec1b8c86d51fc81e15/packages/theme/CHANGELOG.md

The extra newline here is strange, but I use Prettier format-on-save, and it insists on it for some reason. My friend Claude seems to think it's something to do with how long the preceding line is.

- `--wpds-border-radius-surface-xs`: use `--wpds-border-radius-xs` instead.
- `--wpds-border-radius-surface-sm`: use `--wpds-border-radius-sm` instead.
- `--wpds-border-radius-surface-md`: use `--wpds-border-radius-md` instead.
- `--wpds-border-radius-surface-lg`: use `--wpds-border-radius-lg` instead.
- `--wpds-border-width-surface-xs`: use `--wpds-border-width-xs` instead.
- `--wpds-border-width-surface-sm`: use `--wpds-border-width-sm` instead.
- `--wpds-border-width-surface-md`: use `--wpds-border-width-md` instead.
- `--wpds-border-width-surface-lg`: use `--wpds-border-width-lg` instead.
- `--wpds-border-width-interactive-focus`: use `--wpds-border-width-focus` instead.

- Removed the following tokens ([#74470](https://github.com/WordPress/gutenberg/pull/74470)):
- `--wpds-color-bg-interactive-neutral`: use `--wpds-color-bg-interactive-neutral-weak` instead.
- `--wpds-color-bg-interactive-neutral-active`: use `--wpds-color-bg-interactive-neutral-weak-active` instead.
- `--wpds-color-bg-interactive-neutral-disabled`: use `--wpds-color-bg-interactive-neutral-weak-disabled` instead.
- `--wpds-color-bg-interactive-brand`: use `--wpds-color-bg-interactive-brand-weak` instead.
- `--wpds-color-bg-interactive-brand-active`: use `--wpds-color-bg-interactive-brand-weak-active` instead.
- `--wpds-color-bg-interactive-brand-disabled`: use `--wpds-color-bg-interactive-neutral-weak-disabled` instead.
- `--wpds-color-bg-interactive-brand-strong-disabled`: use `--wpds-color-bg-interactive-neutral-strong-disabled` instead.
- `--wpds-color-bg-interactive-brand-weak-disabled`: use `--wpds-color-bg-interactive-neutral-weak-disabled` instead.
- `--wpds-color-bg-interactive-error-disabled`: use `--wpds-color-bg-interactive-neutral-weak-disabled` instead.
- `--wpds-color-bg-interactive-error-strong-disabled`: use `--wpds-color-bg-interactive-neutral-strong-disabled` instead.
- `--wpds-color-bg-interactive-error-weak-disabled`: use `--wpds-color-bg-interactive-neutral-weak-disabled` instead.
- `--wpds-color-fg-interactive-brand-disabled`: use `--wpds-color-fg-interactive-neutral-disabled` instead.
- `--wpds-color-fg-interactive-brand-strong-disabled`: use `--wpds-color-fg-interactive-neutral-strong-disabled` instead.
- `--wpds-color-fg-interactive-error-disabled`: use `--wpds-color-fg-interactive-neutral-disabled` instead.
- `--wpds-color-fg-interactive-error-strong-disabled`: use `--wpds-color-fg-interactive-neutral-strong-disabled` instead.
- `--wpds-color-bg-thumb-brand-disabled`: use the newly added `--wpds-color-bg-thumb-neutral-disabled` instead.
- `--wpds-color-bg-interactive-neutral`: use `--wpds-color-bg-interactive-neutral-weak` instead.
- `--wpds-color-bg-interactive-neutral-active`: use `--wpds-color-bg-interactive-neutral-weak-active` instead.
- `--wpds-color-bg-interactive-neutral-disabled`: use `--wpds-color-bg-interactive-neutral-weak-disabled` instead.
- `--wpds-color-bg-interactive-brand`: use `--wpds-color-bg-interactive-brand-weak` instead.
- `--wpds-color-bg-interactive-brand-active`: use `--wpds-color-bg-interactive-brand-weak-active` instead.
- `--wpds-color-bg-interactive-brand-disabled`: use `--wpds-color-bg-interactive-neutral-weak-disabled` instead.
- `--wpds-color-bg-interactive-brand-strong-disabled`: use `--wpds-color-bg-interactive-neutral-strong-disabled` instead.
- `--wpds-color-bg-interactive-brand-weak-disabled`: use `--wpds-color-bg-interactive-neutral-weak-disabled` instead.
- `--wpds-color-bg-interactive-error-disabled`: use `--wpds-color-bg-interactive-neutral-weak-disabled` instead.
- `--wpds-color-bg-interactive-error-strong-disabled`: use `--wpds-color-bg-interactive-neutral-strong-disabled` instead.
- `--wpds-color-bg-interactive-error-weak-disabled`: use `--wpds-color-bg-interactive-neutral-weak-disabled` instead.
- `--wpds-color-fg-interactive-brand-disabled`: use `--wpds-color-fg-interactive-neutral-disabled` instead.
- `--wpds-color-fg-interactive-brand-strong-disabled`: use `--wpds-color-fg-interactive-neutral-strong-disabled` instead.
- `--wpds-color-fg-interactive-error-disabled`: use `--wpds-color-fg-interactive-neutral-disabled` instead.
- `--wpds-color-fg-interactive-error-strong-disabled`: use `--wpds-color-fg-interactive-neutral-strong-disabled` instead.
- `--wpds-color-bg-thumb-brand-disabled`: use the newly added `--wpds-color-bg-thumb-neutral-disabled` instead.

### Enhancements

- Tweaked the values of the following tokens ([#74470](https://github.com/WordPress/gutenberg/pull/74470)):
- `--wpds-color-bg-interactive-neutral-strong-disabled` from `#d2d2d2` to `#e2e2e2`.
- `--wpds-color-bg-interactive-neutral-weak-disabled` from `#e2e2e2` to `#00000000`.
- `--wpds-color-fg-interactive-neutral-strong-disabled` from `#6d6d6d` to `#8a8a8a`.
- `--wpds-color-bg-interactive-neutral-strong-disabled` from `#d2d2d2` to `#e2e2e2`.
- `--wpds-color-bg-interactive-neutral-weak-disabled` from `#e2e2e2` to `#00000000`.
- `--wpds-color-fg-interactive-neutral-strong-disabled` from `#6d6d6d` to `#8a8a8a`.

### New Features

Expand Down
12 changes: 6 additions & 6 deletions packages/theme/docs/tokens.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -133,12 +133,12 @@ Do not edit directly.

### Elevation

| Variable name | Description |
| -------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
| `--wpds-elevation-x-small` | For sections and containers that group related content and controls, which may overlap other content. Example: Preview Frame. |
| `--wpds-elevation-small` | For components that provide contextual feedback without being intrusive. Generally non-interruptive. Example: Tooltips, Snackbar. |
| `--wpds-elevation-medium` | For components that offer additional actions. Example: Menus, Command Palette |
| `--wpds-elevation-large` | For components that confirm decisions or handle necessary interruptions. Example: Modals. |
| Variable name | Description |
| --------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
| `--wpds-elevation-xs` | For sections and containers that group related content and controls, which may overlap other content. Example: Preview Frame. |
| `--wpds-elevation-sm` | For components that provide contextual feedback without being intrusive. Generally non-interruptive. Example: Tooltips, Snackbar. |
| `--wpds-elevation-md` | For components that offer additional actions. Example: Menus, Command Palette |
| `--wpds-elevation-lg` | For components that confirm decisions or handle necessary interruptions. Example: Modals. |

### Typography

Expand Down
8 changes: 4 additions & 4 deletions packages/theme/src/prebuilt/css/design-tokens.css
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -112,13 +112,13 @@
--wpds-dimension-padding-surface-md: 24px; /* Medium spacing for surfaces */
--wpds-dimension-padding-surface-sm: 16px; /* Small spacing for surfaces */
--wpds-dimension-padding-surface-xs: 8px; /* Extra small spacing for surfaces */
--wpds-elevation-large: 0 5px 15px 0 #00000014, 0 15px 27px 0 #00000012,
--wpds-elevation-lg: 0 5px 15px 0 #00000014, 0 15px 27px 0 #00000012,
0 30px 36px 0 #0000000a, 0 50px 43px 0 #00000005; /* For components that confirm decisions or handle necessary interruptions. Example: Modals. */
--wpds-elevation-medium: 0 2px 3px 0 #0000000d, 0 4px 5px 0 #0000000a,
--wpds-elevation-md: 0 2px 3px 0 #0000000d, 0 4px 5px 0 #0000000a,
0 12px 12px 0 #00000008, 0 16px 16px 0 #00000005; /* For components that offer additional actions. Example: Menus, Command Palette */
--wpds-elevation-small: 0 1px 2px 0 #0000000d, 0 2px 3px 0 #0000000a,
--wpds-elevation-sm: 0 1px 2px 0 #0000000d, 0 2px 3px 0 #0000000a,
0 6px 6px 0 #00000008, 0 8px 8px 0 #00000005; /* For components that provide contextual feedback without being intrusive. Generally non-interruptive. Example: Tooltips, Snackbar. */
--wpds-elevation-x-small: 0 1px 1px 0 #00000008, 0 1px 2px 0 #00000005,
--wpds-elevation-xs: 0 1px 1px 0 #00000008, 0 1px 2px 0 #00000005,
0 3px 3px 0 #00000005, 0 4px 4px 0 #00000003; /* For sections and containers that group related content and controls, which may overlap other content. Example: Preview Frame. */
--wpds-font-family-body: -apple-system, system-ui, 'Segoe UI', 'Roboto',
'Oxygen-Sans', 'Ubuntu', 'Cantarell', 'Helvetica Neue', sans-serif; /* Body font family */
Expand Down
8 changes: 4 additions & 4 deletions packages/theme/src/prebuilt/js/design-tokens.mjs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -113,10 +113,10 @@ export default [
'--wpds-dimension-gap-md',
'--wpds-dimension-gap-lg',
'--wpds-dimension-gap-xl',
'--wpds-elevation-x-small',
'--wpds-elevation-small',
'--wpds-elevation-medium',
'--wpds-elevation-large',
'--wpds-elevation-xs',
'--wpds-elevation-sm',
'--wpds-elevation-md',
'--wpds-elevation-lg',
'--wpds-font-family-heading',
'--wpds-font-family-body',
'--wpds-font-family-mono',
Expand Down
8 changes: 4 additions & 4 deletions packages/theme/tokens/elevation.json
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
{
"wpds-elevation": {
"$type": "shadow",
"x-small": {
"xs": {
"$value": [
{
"color": {
Expand Down Expand Up @@ -50,7 +50,7 @@
],
"$description": "For sections and containers that group related content and controls, which may overlap other content. Example: Preview Frame."
},
"small": {
"sm": {
"$value": [
{
"color": {
Expand Down Expand Up @@ -99,7 +99,7 @@
],
"$description": "For components that provide contextual feedback without being intrusive. Generally non-interruptive. Example: Tooltips, Snackbar."
},
"medium": {
"md": {
"$value": [
{
"color": {
Expand Down Expand Up @@ -148,7 +148,7 @@
],
"$description": "For components that offer additional actions. Example: Menus, Command Palette"
},
"large": {
"lg": {
"$value": [
{
"color": {
Expand Down
2 changes: 1 addition & 1 deletion packages/ui/src/tooltip/style.module.css
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -15,6 +15,6 @@
font-size: var(--wpds-font-size-sm);
line-height: 1.4; /* TODO: use DS token for line height */
color: var(--wpds-color-fg-content-neutral);
box-shadow: var(--wpds-elevation-small);
box-shadow: var(--wpds-elevation-sm);
}
}
2 changes: 1 addition & 1 deletion packages/ui/src/utils/css/item-popup.module.css
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,7 @@
max-width: var(--available-width);
border-radius: var(--wpds-border-radius-md);
border: 1px solid var(--wpds-color-stroke-surface-neutral);
box-shadow: var(--wpds-elevation-medium);
box-shadow: var(--wpds-elevation-md);
background-color: var(--wpds-color-bg-surface-neutral-strong);
font-family: var(--wpds-font-family-body);
font-size: var(--wpds-font-size-md);
Expand Down
Loading