Skip to content

[Admin UI]: Move to CSS modules and implement logical properties #77088

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
yogeshbhutkar wants to merge 10 commits into
base: trunk
Choose a base branch
from
+46 −43
Open

[Admin UI]: Move to CSS modules and implement logical properties #77088

Show file tree
Hide file tree
Changes from 9 commits
Commits
Show all changes
10 commits
Select commit Hold shift + click to select a range
63843a5
Update tsconfig.json to include compilerOptions for type definitions
yogeshbhutkar Apr 7, 2026
8ff22d4
Migrate Breadcrumb styles to SCSS modules and adjust BEM definitions
yogeshbhutkar Apr 7, 2026
5621cf8
Migrate admin UI styles for Page to SCSS modules
yogeshbhutkar Apr 7, 2026
915452e
Refactor to use logical properties
yogeshbhutkar Apr 7, 2026
0225799
Fix margin properties for breadcrumb separator in SCSS
yogeshbhutkar Apr 7, 2026
6d3fbf2
Remove unintended changes to other modules
yogeshbhutkar Apr 7, 2026
804cc0e
Update README.md
yogeshbhutkar Apr 7, 2026
1acd2af
Fix linting errors
yogeshbhutkar Apr 7, 2026
5bb85d5
Remove build-style from package.json files and exports
yogeshbhutkar Apr 7, 2026
0992bff
Update README.md
yogeshbhutkar Apr 7, 2026
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
5 changes: 2 additions & 3 deletions packages/admin-ui/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,7 @@ npm install @wordpress/admin-ui --save

## Setup

This package requires CSS from this package and from multiple dependency packages.
This package requires CSS from multiple dependency packages.

### Within WordPress

Expand All @@ -31,10 +31,9 @@ npm install @wordpress/admin-ui @wordpress/theme @wordpress/components
```js
import '@wordpress/theme/design-tokens.css';
import '@wordpress/components/build-style/style.css';
import '@wordpress/admin-ui/build-style/style.css';
```

RTL versions of the stylesheets are available in the same paths, but with `-rtl` appended to the filename (`style-rtl.css`). The design tokens stylesheet is universal and does not have a separate RTL version.
The design tokens stylesheet is universal and does not have a separate RTL version.

## API

Expand Down
7 changes: 2 additions & 5 deletions packages/admin-ui/package.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -26,7 +26,6 @@
"src",
"build",
"build-module",
"build-style",
"build-types",
"*.md"
],
Expand All @@ -38,14 +37,12 @@
"import": "./build-module/index.mjs",
"require": "./build/index.cjs"
},
"./package.json": "./package.json",
"./build-style/": "./build-style/"
"./package.json": "./package.json"
},
"react-native": "src/index",
"types": "build-types",
"sideEffects": [
"build-style/**",
"src/**/*.scss"
"src/**/*.module.scss"
],
"dependencies": {
"@wordpress/base-styles": "file:../base-styles",
Expand Down
3 changes: 2 additions & 1 deletion packages/admin-ui/src/breadcrumbs/index.tsx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,6 +12,7 @@ import {
* Internal dependencies
*/
import type { BreadcrumbsProps } from './types';
import styles from './style.module.scss';

/**
* Renders a breadcrumb navigation trail.
Expand Down Expand Up @@ -56,7 +57,7 @@ export const Breadcrumbs = ( { items }: BreadcrumbsProps ) => {
<nav aria-label={ __( 'Breadcrumbs' ) }>
<HStack
as="ul"
className="admin-ui-breadcrumbs__list"
Copy link
Copy Markdown
Contributor Author

@yogeshbhutkar yogeshbhutkar Apr 7, 2026 •
edited
Loading

Choose a reason for hiding this comment

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

With component-scoped styles using modules, we are no longer required to follow the BEM pattern, and the classnames can be simplified.

Question: Do we also keep the existing classnames for back-compat?

Copy link
Copy Markdown
Member

@mirka mirka Apr 8, 2026

Choose a reason for hiding this comment

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

This package is new and bundled, so I think we can drop the existing class names. Let's just note it in the changelog.

className={ styles.list }
spacing={ 0 }
justify="flex-start"
alignment="center"
Expand Down
5 changes: 3 additions & 2 deletions packages/admin-ui/src/breadcrumbs/style.scss → ...dmin-ui/src/breadcrumbs/style.module.scss
View file
Open in desktop
Copy link
Copy Markdown
Member

@mirka mirka Apr 8, 2026

Choose a reason for hiding this comment

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

Let's also change these from scss to css, since we're not using Sass features. This will also enable the stylelints for safer RTL support.

gutenberg/.stylelintrc.js

Line 58 in b0a4da8

files: [ '**/*.module.css' ],

(I'll add **/*.module.scss to that matcher anyway though.)

Copy link
Copy Markdown
Member

@mirka mirka Apr 8, 2026

Choose a reason for hiding this comment

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

Matcher broadened in #77140

Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
@use "@wordpress/base-styles/variables";

.admin-ui-breadcrumbs__list {
.list {
// @TODO: use Text component from UI when available.
font-family: var(--wpds-font-family-heading);
font-size: var(--wpds-font-size-lg);
Expand All @@ -15,7 +15,8 @@

li:not(:last-child)::after {
content: "/";
margin: 0 variables.$grid-unit-10;
Copy link
Copy Markdown
Member

@mirka mirka Apr 8, 2026

Choose a reason for hiding this comment

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

Once the stylelints for CSS modules are working, you'll notice that lines like this won't get marked as invalid. This is because 2-value shorthand is safe for RTL. We don't have to split these properties into two.

margin-block: 0;
margin-inline: variables.$grid-unit-10;
Copy link
Copy Markdown
Member

@mirka mirka Apr 8, 2026

Choose a reason for hiding this comment

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

Let's change this to a design token.

}

h1 {
Expand Down
11 changes: 6 additions & 5 deletions packages/admin-ui/src/page/header.tsx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,7 @@ import { Stack } from '@wordpress/ui';
* Internal dependencies
*/
import { SidebarToggleSlot } from './sidebar-toggle-slot';
import styles from './style.module.scss';

export default function Header( {
headingLevel = 2,
Expand All @@ -29,19 +30,19 @@ export default function Header( {
return (
<Stack
direction="column"
className="admin-ui-page__header"
className={ styles.header }
render={ <header /> }
>
<Stack direction="row" justify="space-between" gap="sm">
<Stack direction="row" gap="sm" align="center" justify="start">
{ showSidebarToggle && (
<SidebarToggleSlot
bubblesVirtually
className="admin-ui-page__sidebar-toggle-slot"
className={ styles[ 'sidebar-toggle-slot' ] }
/>
) }
{ title && (
<HeadingTag className="admin-ui-page__header-title">
<HeadingTag className={ styles[ 'header-title' ] }>
{ title }
</HeadingTag>
) }
Expand All @@ -52,14 +53,14 @@ export default function Header( {
direction="row"
gap="sm"
style={ { width: 'auto', flexShrink: 0 } }
className="admin-ui-page__header-actions"
className={ styles[ 'header-actions' ] }
align="center"
>
{ actions }
</Stack>
</Stack>
{ subTitle && (
<p className="admin-ui-page__header-subtitle">{ subTitle }</p>
<p className={ styles[ 'header-subtitle' ] }>{ subTitle }</p>
) }
</Stack>
);
Expand Down
10 changes: 8 additions & 2 deletions packages/admin-ui/src/page/index.tsx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,6 +9,7 @@ import clsx from 'clsx';
import Header from './header';
import NavigableRegion from '../navigable-region';
import { SidebarToggleFill } from './sidebar-toggle-slot';
import styles from './style.module.scss';

function Page( {
headingLevel,
Expand All @@ -35,7 +36,7 @@ function Page( {
hasPadding?: boolean;
showSidebarToggle?: boolean;
} ) {
const classes = clsx( 'admin-ui-page', className );
const classes = clsx( styles.page, className );
const effectiveAriaLabel =
ariaLabel ?? ( typeof title === 'string' ? title : '' );

Expand All @@ -53,7 +54,12 @@ function Page( {
/>
) }
{ hasPadding ? (
<div className="admin-ui-page__content has-padding">
<div
className={ clsx(
styles.content,
styles[ 'has-padding' ]
) }
>
{ children }
</div>
) : (
Expand Down
33 changes: 19 additions & 14 deletions packages/admin-ui/src/page/style.scss → packages/admin-ui/src/page/style.module.scss
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
.admin-ui-page {
.page {
display: flex;
height: 100%;
// @TODO: Revisit page background color. Consider using
Expand All @@ -13,16 +13,17 @@
text-wrap: pretty;
}

.admin-ui-page__header {
padding: var(--wpds-dimension-padding-md) var(--wpds-dimension-padding-2xl);
border-bottom: var(--wpds-border-width-xs) solid var(--wpds-color-stroke-surface-neutral-weak);
.header {
padding-block: var(--wpds-dimension-padding-md);
padding-inline: var(--wpds-dimension-padding-2xl);
border-block-end: var(--wpds-border-width-xs) solid var(--wpds-color-stroke-surface-neutral-weak);
background: var(--wpds-color-bg-surface-neutral-strong);
position: sticky;
top: 0;
inset-block-start: 0;
z-index: 1;
}

.admin-ui-page__header-title {
.header-title {
// @TODO: use Text component from UI when available.
font-family: var(--wpds-font-family-heading);
font-size: var(--wpds-font-size-lg);
Expand All @@ -34,35 +35,39 @@
white-space: nowrap;
}

.admin-ui-page__sidebar-toggle-slot:empty {
.sidebar-toggle-slot:empty {
display: none;
}

.admin-ui-page__header-subtitle {
.header-subtitle {
padding-block-end: var(--wpds-dimension-padding-xs);
color: var(--wpds-color-fg-content-neutral-weak);
font-size: var(--wpds-font-size-md);
line-height: var(--wpds-font-line-height-md);
margin: 0;
}

.admin-ui-page__content {
.content {
flex-grow: 1;
overflow: auto;
display: flex;
flex-direction: column;

&.has-padding {
padding: var(--wpds-dimension-padding-lg) var(--wpds-dimension-padding-2xl);
padding-block: var(--wpds-dimension-padding-lg);
padding-inline: var(--wpds-dimension-padding-2xl);
}
}

// Show button text labels when preference is enabled.
.show-icon-labels {
.admin-ui-page__header-actions {
.components-button.has-icon {
/* stylelint-disable-next-line selector-pseudo-class-no-unknown -- :global is a CSS Modules construct, not a standard pseudo-class */
:global(.show-icon-labels) {
.header-actions {
/* stylelint-disable-next-line selector-pseudo-class-no-unknown -- :global is a CSS Modules construct, not a standard pseudo-class */
:global(.components-button.has-icon) {
Comment on lines +66 to +67
Copy link
Copy Markdown
Contributor Author

@yogeshbhutkar yogeshbhutkar Apr 7, 2026 •
edited
Loading

Choose a reason for hiding this comment

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

":global" will be required to target the class correctly. Therefore, we may need to disable the lint rule here or in the config.

Copy link
Copy Markdown
Member

@mirka mirka Apr 7, 2026

Choose a reason for hiding this comment

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

First, with the new dedicated IconButton component, I think it's now feasible to officially bake in the show-icon-labels feature into the IconButton component itself, to be controlled by the theming system (#61763, cc @WordPress/gutenberg-components).

Second, for the scope of this PR, I'm wondering if we can just leave this out. @yogeshbhutkar can you check whether we really need this .show-icon-labels support at the admin-ui level, at least in how we currently use this package in Gutenberg? Ideally it should live at a higher level, closer to how it's done in the edit-post and edit-site packages.

Copy link
Copy Markdown
Member

@aduth aduth Apr 7, 2026

Choose a reason for hiding this comment

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

First, with the new dedicated IconButton component, I think it's now feasible to officially bake in the show-icon-labels feature into the IconButton component itself, to be controlled by the theming system

Are you imagining this being configurable on the ThemeProvider component and passed down to be considered by the IconButton via React context? I could see that making sense, maybe needing a dedicated implementation ticket related to #61763.

Copy link
Copy Markdown
Contributor Author

@yogeshbhutkar yogeshbhutkar Apr 8, 2026

Choose a reason for hiding this comment

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

Can you check whether we really need this .show-icon-labels support at the admin-ui level, at least in how we currently use this package in Gutenberg?

I did a brief audit and found that internal consumers of the Admin UI do rely on the show-icon-labels styles. Specifically, I identified the following:

gutenberg/packages/edit-site/src/components/page-patterns/actions.js

Lines 30 to 32 in 0992bff

<DropdownMenu
icon={ moreVertical }
label={ __( 'Actions' ) }

gutenberg/packages/edit-site/src/components/sidebar-global-styles/index.js

Lines 35 to 37 in 0992bff

<Button
isPressed={ isStyleBookOpened }
icon={ seen }

gutenberg/routes/styles/stage.tsx

Lines 59 to 62 in 0992bff

<Button
size="compact"
isPressed={ isStyleBookOpened }
icon={ seen }

Here’s an example screenshot illustrating the impact of removing the show-icon-labels styles:

Before After
before after

Note: The "show button text labels" property was enabled from editor preferences.

As per your suggestion, should we migrate these to a higher level—such as the corresponding component stylesheets?

Copy link
Copy Markdown
Member

@mirka mirka Apr 8, 2026

Choose a reason for hiding this comment

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

Are you imagining this being configurable on the ThemeProvider component and passed down to be considered by the IconButton via React context? I could see that making sense, maybe needing a dedicated implementation ticket related to #61763.

Yes. That won't solve layout issues (like overflow) automatically, but the basic "hide icon and show text label" part could be handled through the theming system.

Copy link
Copy Markdown
Member

@mirka mirka Apr 8, 2026

Choose a reason for hiding this comment

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

As per your suggestion, should we migrate these to a higher level—such as the corresponding component stylesheets?

Yes, admin-ui itself doesn't add the show-icon-labels class so it shouldn't even know about it. routes/styles doesn't add the class either by the way, so I don't think it's applied there (I'm guessing your screenshot is not from ?page=site-editor-v2).

So that leaves us the two specific instances from edit-site, and I'd say it's reasonable for those call sites to handle the show-icon-labels concerns themselves. I don't think it's safe to handle it globally anyway, given the overflow risks.

Could we perhaps execute this show-icon-labels move in a separate PR first?

width: auto;
padding: 0 var(--wpds-dimension-padding-xs);
padding-block: 0;
padding-inline: var(--wpds-dimension-padding-xs);

// Hide the button icons when labels are set to display...
svg {
Expand Down
2 changes: 0 additions & 2 deletions packages/admin-ui/src/style.scss
View file
Open in desktop

This file was deleted.

3 changes: 3 additions & 0 deletions packages/admin-ui/tsconfig.json
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,9 @@
{
"$schema": "https://json.schemastore.org/tsconfig.json",
"extends": "../../tsconfig.base.json",
"compilerOptions": {
"types": [ "style-imports" ]
},
"references": [
{ "path": "../components" },
{ "path": "../element" },
Expand Down
1 change: 0 additions & 1 deletion packages/boot/src/style.scss
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,4 @@
@use "@wordpress/theme/src/prebuilt/css/design-tokens.css" as *;
@use "@wordpress/admin-ui/build-style/style.css" as *;
@use "@wordpress/base-styles/mixins" as *;
@use "@wordpress/base-styles/variables" as *;

Expand Down
1 change: 0 additions & 1 deletion packages/edit-post/src/style.scss
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,7 +1,6 @@
@use "@wordpress/base-styles/default-custom-properties";
@use "@wordpress/base-styles/mixins" as *;
@use "@wordpress/base-styles/variables" as *;
@use "@wordpress/admin-ui/build-style/style.css" as *;
@use "./components/back-button/style.scss" as *;
@use "./components/layout/style.scss" as *;
@use "./components/meta-boxes/meta-boxes-area/style.scss" as *;
Expand Down
1 change: 0 additions & 1 deletion packages/edit-site/src/style.scss
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,7 +1,6 @@
@use "@wordpress/base-styles/colors" as *;
@use "@wordpress/base-styles/mixins" as *;
@use "@wordpress/base-styles/default-custom-properties";
@use "@wordpress/admin-ui/build-style/style.css" as admin-ui;
@use "@wordpress/dataviews/build-style/style.css" as dataviews;
@use "@wordpress/fields/build-style/style.css" as fields;
@use "@wordpress/global-styles-ui/build-style/style.css" as global-styles-ui;
Expand Down
1 change: 0 additions & 1 deletion packages/interface/src/style.scss
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,3 @@
@use "@wordpress/admin-ui/build-style/style.css" as *;
@use "./components/complementary-area-header/style.scss" as *;
@use "./components/complementary-area/style.scss" as *;
@use "./components/fullscreen-mode/style.scss" as *;
Expand Down
1 change: 0 additions & 1 deletion storybook/package-styles/admin-ui-ltr.lazy.scss
View file
Open in desktop

This file was deleted.

1 change: 0 additions & 1 deletion storybook/package-styles/admin-ui-rtl.lazy.scss
View file
Open in desktop

This file was deleted.

6 changes: 2 additions & 4 deletions storybook/package-styles/config.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -17,8 +17,6 @@ import fieldsLtr from '../package-styles/fields-ltr.lazy.scss?inline';
import fieldsRtl from '../package-styles/fields-rtl.lazy.scss?inline';
import mediaFieldsLtr from '../package-styles/media-fields-ltr.lazy.scss?inline';
import mediaFieldsRtl from '../package-styles/media-fields-rtl.lazy.scss?inline';
import adminUiLtr from '../package-styles/admin-ui-ltr.lazy.scss?inline';
import adminUiRtl from '../package-styles/admin-ui-rtl.lazy.scss?inline';
import designTokens from '../package-styles/design-tokens.lazy.scss?inline';

/**
Expand Down Expand Up @@ -77,8 +75,8 @@ const CONFIG = [
},
{
componentIdMatcher: /^admin-ui-/,
ltr: [ designTokens, componentsLtr, adminUiLtr ],
rtl: [ designTokens, componentsRtl, adminUiRtl ],
ltr: [ designTokens, componentsLtr ],
rtl: [ designTokens, componentsRtl ],
},
{
componentIdMatcher: /^design-system-/,
Expand Down
Loading