Skip to content

Experiment: restyle wp-admin notices from design system tokens - #83072

Open
jasmussen wants to merge 3 commits into
trunkfrom
poc/wpds-admin-notices
Open

Experiment: restyle wp-admin notices from design system tokens#83072
jasmussen wants to merge 3 commits into
trunkfrom
poc/wpds-admin-notices

Conversation

@jasmussen

@jasmussen jasmussen commented Sep 17, 2026

Copy link
Copy Markdown
Contributor

Stacked on #82425 and part of the same off-by-default experiment.

This PR updates WordPress notices to use WPDS tokens: colour spacing, radius. The goal is the same: reduce the surface area of WordPress, and in the process discovering inconsistencies, bugs, regressions, and issues to fix in both directions.

The parent PR is the main part of the experiment that leverages the benefits of a single set of tokens for maintainabillity. This builds upon the same, but makes slight visual changes. Where an existing notice has a left border, this is a tinted surface with a border all around.

image

In this notice effort, a few improvements to do were found along the way:

  • Notice text contrast rises from 10.3:1 to over 15:1 in every tone.
  • A single-line notice no longer carries 13px of extra height: paragraph margins stacked on top of the notice's padding.
  • The dismiss button follows the notice's tone and gets an outline focus ring instead of a box-shadow.

What this is not

  • No markup changes.
  • Not a change to margins or position, which WordPress sets by context. The three deliberately tighter paddings are kept: the file editor sidebar, plugin dependency cards and inline-edit errors.

Testing instructions

  • Enable Admin design tokens under Gutenberg → Experiments.
  • Open Tools → WPDS Parity and scroll to the notices: every tone, the legacy classes, and a dismissible notice.
  • See real ones in context: save Settings → General for a success notice, or activate a plugin.

Use of AI Tools

Claude Opus 5.

@jasmussen jasmussen self-assigned this Sep 17, 2026
@jasmussen jasmussen added the [Type] Code Quality Issues or PRs that relate to code quality label Sep 17, 2026
@github-actions

github-actions Bot commented Sep 17, 2026 •
edited
Loading

Copy link
Copy Markdown

🤖 PR meta 🤖

🎉 Props

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: jasmussen <joen@git.wordpress.org>

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

Updated as activity occurs, without notifying anyone named here. Add the props-bot label to refresh.

📦 Bundle size

Size Change: 0 B

Total Size: 8.3 MB

54bf498 Run

⚡ Performance

Show the results

Client side metrics exclude the server response time.

front-end-block-theme

Metric 68b7bff trunk % Change
timeToFirstByte 56.85 ms +12.75% -2.73% 58.85 ms +10.96% -5.1% -3.4%
largestContentfulPaint 92 ms +13.04% -2.17% 96 ms +6.25% -6.25% -4.17%
lcpMinusTtfb 35.85 ms +4.46% -6.69% 34.05 ms +23.2% -5.14% 5.29%
wpBeforeTemplate 28.11 ms +16.47% -1.14% 28.7 ms +16.34% -1.67% -2.06%
wpTemplate 24.64 ms +1.87% -3.53% 24.47 ms +4.54% -3.15% 0.69%
wpTotal 53.34 ms +11.92% -3.22% 54.94 ms +9.85% -5.39% -2.91%
wpMemoryUsage 7.66 MB +0% -0% 7.63 MB +0% -0% 0.45%
wpDbQueries 17 +0% -0% 17 +0% -0% 0%

front-end-classic-theme

Metric 68b7bff trunk % Change
timeToFirstByte 48.25 ms +13.06% -2.8% 43.55 ms +7.58% -4.02% 10.79%
largestContentfulPaint 108 ms +1.85% -5.56% 92 ms +4.35% -4.35% 17.39%
lcpMinusTtfb 56.4 ms +3.55% -4.79% 47.35 ms +3.06% -1.69% 19.11%
wpBeforeTemplate 26.56 ms +17.09% -2.33% 26.43 ms +5.56% -2.65% 0.49%
wpTemplate 18.13 ms +6.56% -1.82% 13.97 ms +4.22% -3.94% 29.78%
wpTotal 45.21 ms +12.36% -2.72% 40.78 ms +7.28% -4.17% 10.86%
wpMemoryUsage 6.29 MB +0% -0% 6.11 MB +0% -0% 2.9%
wpDbQueries 14 +0% -0% 10 +0% -0% 40%

media-processing

Metric 68b7bff trunk % Change
mediaProcessingJpeg 401.04 ms +0.89% -1.08% 401.7 ms +0.26% -0.79% -0.16%
mediaProcessingAvif 6064.64 ms +0.44% -0.28% 6040.41 ms +0.14% -0.17% 0.4%
mediaProcessingJpegToAvif 4194.97 ms +0.08% -0.2% 4171.82 ms +0.12% -0.31% 0.55%

media-upload

Metric 68b7bff trunk % Change
jpegUploadProcessing 1427.27 ms +1.64% -1.26% 1413.31 ms +0.82% -1.06% 0.99%
pngUploadProcessing 205.15 ms +5.56% -15.51% 209.87 ms +5.3% -14.78% -2.25%
largeJpegUploadProcessing 1405.11 ms +1.1% -0.98% 1417.07 ms +0.76% -1.06% -0.84%
multipleImageUploadProcessing 1548.18 ms +0.64% -0.33% 1546.14 ms +12.22% -0.29% 0.13%

post-editor

Metric 68b7bff trunk % Change
serverResponse 414.47 ms +3.23% -7.05% 420.31 ms +7.12% -7.86% -1.39%
firstPaint 204.25 ms +28.96% -7.03% 273.29 ms +15.36% -30.34% -25.26%
domContentLoaded 1071.07 ms +1.41% -1.26% 1107.36 ms +1% -0.55% -3.28%
loaded 1072.4 ms +1.38% -1.27% 1108.8 ms +0.99% -0.57% -3.28%
firstContentfulPaint 453.53 ms +1.47% -13.46% 477.14 ms +1.13% -1.67% -4.95%
firstBlock 3156.92 ms +0.65% -0.73% 3275.57 ms +1.09% -0.7% -3.62%
type 18.72 ms +4.65% -2.78% 18.64 ms +5.63% -2.47% 0.43%
typeWithoutInspector 19.74 ms +2.13% -4.51% 18.88 ms +5.4% -3.07% 4.56%
typeWithTopToolbar 24.62 ms +8.77% -4.43% 23.6 ms +6.4% -4.41% 4.32%
typeContainer 8.81 ms +15.55% -4.77% 8.66 ms +7.51% -4.85% 1.73%
focus 108.02 ms +11.2% -1.13% 114.95 ms +3.45% -2.38% -6.03%
firstFocus 215.34 ms +0% -0% 222.37 ms +0% -0% -3.16%
selectAll 508.03 ms +0.95% -1.86% 561.32 ms +0.58% -2.97% -9.49%
listViewOpen 78.3 ms +5.47% -7.41% 78.61 ms +1.28% -4.54% -0.39%
inserterOpen 38.81 ms +8.5% -5.39% 38.08 ms +10.03% -3.65% 1.92%
inserterHover 12.27 ms +7.01% -7.99% 12.74 ms +9.42% -5.89% -3.69%
inserterSearch 8.62 ms +3.71% -9.98% 8.97 ms +5.24% -5.69% -3.9%
loadPatterns 643.9 ms +7.55% -9.53% 662.99 ms +2.74% -3.7% -2.88%
wpTotal 403.42 ms +3.27% -7.24% 409.43 ms +7.21% -8.2% -1.47%
wpMemoryUsage 13.22 MB +0% -0% 13.19 MB +0% -0% 0.25%
wpDbQueries 54 +0% -1.85% 54 +0% -1.85% 0%

site-editor

Metric 68b7bff trunk % Change
serverResponse 280.17 ms +3% -4.06% 291.11 ms +2.19% -5.14% -3.76%
firstPaint 188.87 ms +20.98% -7.6% 197.64 ms +56.22% -16.35% -4.44%
domContentLoaded 787.92 ms +5.62% -2.15% 772.13 ms +3.44% -4.41% 2.04%
loaded 788.79 ms +5.63% -2.17% 772.94 ms +3.43% -4.4% 2.05%
firstContentfulPaint 330.54 ms +4.26% -4.33% 328.3 ms +2.79% -2.66% 0.68%
firstBlock 2893.49 ms +3.59% -0.55% 2855.4 ms +2.07% -1.28% 1.33%
type 16.37 ms +2.99% -5.8% 15.62 ms +8.77% -3.52% 4.8%
navigate 87.52 ms +14.9% -7.48% 92.02 ms +9.89% -3.17% -4.89%
loadPatterns 943.82 ms +6.15% -3.7% 901.14 ms +23.68% -5.58% 4.74%
loadPages 990.5 ms +1.19% -3.03% 1027.69 ms +6.11% -3.24% -3.62%
wpTotal 272.77 ms +3.01% -4.14% 283.74 ms +2.26% -5.21% -3.87%
wpMemoryUsage 12.26 MB +0% -0% 12.23 MB +0% -0% 0.3%
wpDbQueries 43.5 +1.15% -1.15% 43.5 +1.15% -1.15% 0%

54bf498 Run

🏁 Flaky tests

Some tests passed with failed attempts. The failures may not be related to this commit but are still reported for visibility. See the documentation for more information.

pushes earlier threads above the canvas to keep the selected one aligned in /test/e2e/specs/editor/various/block-notes-floating.spec.js, passed after 1 failed attempt. 
Error: expect(locator).toBeVisible() failed

Locator: getByRole('region', { name: /^(Notes|Editor settings)$/ }).getByRole('treeitem', { name: 'Note: One: Comprehensive considerations regarding extraordinarily sophisticated implementation characteristics notwithstanding.' })
Expected: visible
Timeout: 5000ms
Error: element(s) not found

Call log:
  - Expect "toBeVisible" getByRole('region', { name: /^(Notes|Editor settings)$/ }).getByRole('treeitem', { name: 'Note: One: Comprehensive considerations regarding extraordinarily sophisticated implementation characteristics notwithstanding.' }) with timeout 5000ms
  - waiting for getByRole('region', { name: /^(Notes|Editor settings)$/ }).getByRole('treeitem', { name: 'Note: One: Comprehensive considerations regarding extraordinarily sophisticated implementation characteristics notwithstanding.' })

    at /home/runner/work/gutenberg/gutenberg/test/e2e/specs/editor/various/block-notes-floating.spec.js:551:4

54bf498 Run

@jasmussen
jasmussen force-pushed the poc/wpds-admin-notices branch from 16ff0e9 to 50a4473 Compare September 17, 2026 11:40
@jasmussen jasmussen mentioned this pull request Sep 17, 2026
Merged
@jasmussen
jasmussen force-pushed the poc/wpds-admin-notices branch from 50a4473 to d61a3e1 Compare September 28, 2026 11:49
@jasmussen
jasmussen force-pushed the poc/wpds-admin-restyle branch 2 times, most recently from b2e2cbd to 053a2fc Compare September 29, 2026 07:27
@jasmussen
jasmussen force-pushed the poc/wpds-admin-restyle branch from 053a2fc to ed52ab4 Compare September 29, 2026 09:03
@jasmussen
jasmussen force-pushed the poc/wpds-admin-notices branch 2 times, most recently from c4ddfb2 to 2c8393f Compare October 1, 2026 11:04
@jasmussen
jasmussen force-pushed the poc/wpds-admin-restyle branch from 8ffb370 to 49cccdf Compare October 1, 2026 11:04
Base automatically changed from poc/wpds-admin-restyle to trunk October 1, 2026 12:37
@jasmussen
jasmussen force-pushed the poc/wpds-admin-notices branch from 2c8393f to e41af0a Compare October 6, 2026 09:30
jasmussen and others added 3 commits October 7, 2026 09:35
@jasmussen @claude
Restyle admin notices from design system tokens
9dace38 
Maps admin notices onto the React `Notice`, whose styles are already expressed
entirely in tokens. The admin's tone classes correspond one to one with its
variants, so `.notice-success` takes the success surface, border and text
colours, and so on for warning, error and info. A notice with no tone class takes
the neutral surface.

The visible change is how tone is carried. WordPress signals it with a 4px bar on the
leading edge over a white or near-white background; the design system uses a full
hairline border, a tinted surface and tinted text, with a rounded corner. That is
a change of idiom rather than a value swap, and the bar is the most recognisable
part of a WordPress notice today.

`.updated` and `.error` are covered alongside `.notice`, matching what WordPress does,
because a great many plugins still emit them. `div.error` is qualified by element
exactly as WordPress qualifies it, so a bare `.error` used for field validation is not
caught.

Notice paragraphs no longer add their own outer margins. WordPress gives them
`margin: 0.5em 0`, which stacks on the notice's padding and makes a single-line
notice 13px taller than the padding asks for. Removing the first and last margins
lets the padding alone define the box, matching the design system; margins
between paragraphs are kept, since a notice with two paragraphs still needs them.

The dismiss button now inherits the notice's tone rather than being fixed black,
and takes an outline focus ring in place of the box-shadow one. Its glyph is a
dashicons font character rather than an image, so colour applies directly and no
masking is needed.

Margin and position are left to WordPress, which sets them contextually. Padding is
set here as part of the notice's appearance, so the three contextual padding
overrides outside the Customizer are repeated to keep them from being flattened:
the file editor sidebar, plugin dependency cards, and inline-edit errors are all
deliberately tighter than a standalone notice.

The parity harness gains every tone, the legacy classes, and a dismissible notice.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
@jasmussen @claude
Point the notice stylesheet at the renamed overrides file
1ec7909 
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
@jasmussen @claude
Balance dismissible notices
54bf498 
A dismissible notice was 7px taller than a plain one, with its text off
centre. The dismiss button is appended after the last paragraph, so that
paragraph was no longer `:last-child` and kept its bottom margin. It is
now matched when it is followed only by the button.

The notice's padding also flattened common.css's `padding-right: 48px`
on dismissible notices, which would let long text run under the button.
The same room is now reserved from the notice's own padding.

The button is centred on the first line of text, which keeps it aligned
at every size common.css gives it, and inset so the space right of the
glyph matches the space left of the text.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
@jasmussen
jasmussen force-pushed the poc/wpds-admin-notices branch from e41af0a to 54bf498 Compare October 7, 2026 07:48

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@spacedmonkey spacedmonkey Awaiting requested review from spacedmonkey spacedmonkey is a code owner
@manzoorwanijk manzoorwanijk Awaiting requested review from manzoorwanijk

At least 1 approving review is required to merge this pull request.

Assignees

@jasmussen jasmussen

Labels

[Type] Code Quality Issues or PRs that relate to code quality

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@jasmussen