Consolidate, refactor, remove and untangle Claro's CSS from Default Admin theme [#3582833]

Parent issue: #3582351: [Meta] Clean up CSS

Problem

The Default Admin theme is basically Gin renamed. Gin used Claro as a base theme, and that structure was flattened when it was added to core. To do this, Claro's CSS was copied en masse to the new theme.

Plan

This plan consolidates two parallel CSS trees in Drupal core's default_admin admin theme:

css/ — Original Claro styles (base, component, layout, theme layers)
migration/css/ — Gin overrides/enhancements (base, components, layout, theme)

The goal: one CSS file per component (or at most two where justified). The final structure lives in css/ with migration/ eventually removed.

Process

Add a comment on what you're working on
Do the work
Verify that linting passes by running yarn lint:css from the core/ directory. Note you can pass in --fix to automatically fix some issues.
Verify there are no visual changes by using the visual regression tool https://github.com/mherchel/ddev-drupal-admin-vrt. You can also use the https://www.drupal.org/project/theming_tools module to test out specific components.
Commit the changes to the MR. Be verbose and granular in your commit message
When completed, add a comment and update the issue summary by marking the line item as completed by replacing the square (🔲) with a checkbox (✅)

2. File Mapping Table

2a. Foundation files (`migration/css/base/` and `migration/css/theme/`)

	Migration file	Merge target	Type	Complexity	Notes
✅	`base/media-queries`	`css/base/variables` (or new `css/base/media-queries`)	Additive	Low	24 `@custom-media` definitions. Claro has none. Add to top of variables file or create dedicated file.
✅	`theme/variables`	`css/base/variables`	Override + Additive	High	~250 lines. Adds all `--gin-` properties, density variants, dark mode overrides. Claro variables already reference some `--gin-` vars. Must carefully merge `:root` blocks.
✅	`theme/font`	New: `css/base/font`	Standalone	Trivial	`@font-face` declaration only. Just move.
✅	`theme/accent`	New: `css/theme/accent`	Standalone	Trivial	Accent color theming. Just move.
🔲	`theme/dialog`	`css/components/dialog`	Override	Medium	‼️Lets save this one for later when we refactor dialog‼️ Third dialog file (see risk areas). Dark mode, backdrop blur.

2b. Gin base overrides (`migration/css/base/gin-*.pcss.css`)

All loaded in global-styling library at theme weight.

	Migration file	Merge target	Type	Complexity	Notes
✅	`gin-icons`	New: `css/base/icons`	Standalone	Trivial	Icon mask-image utilities. No Claro equivalent.
✅	`gin-body`	`css/base/elements`	Override	Medium	Body, html, selection styles. Overlaps with Claro elements.
✅	`gin-color-overrides`	`css/theme/colors`	Override	Medium	Overrides Claro color variables with Gin values.
✅	`gin-views-unwrapped`	`css/components/views-exposed-form`	Additive	Low	Views wrapper styling. Minimal overlap.
✅	`gin-regions`	`css/layout/layout`	Override + Additive	Medium	Layout region overrides + new region styles.
✅	`gin-layers`	New: `css/base/layers`	Standalone	Low	Gin layering system (z-index management). No Claro equivalent.
✅	`gin-title`	`css/components/page-title`	Override	Low	Page title overrides.
✅	`gin-extend`	New: `css/base/extend`	Standalone	Low	Utility/helper classes. No Claro equivalent.
✅	`gin-claro-improvements`	Distribute across targets	Override	High	Catch-all file with improvements to various Claro components. Must be split and merged into respective component files.
✅	`gin-views`	`css/components/views-exposed-form`	Override	Medium	Views form/filter overrides.
✅	`gin-table`	`css/components/tables`	Override	Medium	Table styling overrides. Dark mode, sticky headers.
✅	`gin-tabledrag`	`css/components/tabledrag`	Override	Medium	Tabledrag overrides.
✅	`gin-form`	`css/components/form`	Override	High	Large file. Form element overrides across many selectors.
🔲	`gin-button`	`css/components/button`	Override	High	Button overrides. Multiple states, variants, dark mode.
🔲	`gin-dropbutton`	`css/components/dropbutton`	Override	Medium	Dropbutton overrides.
✅	`gin-action-link`	`css/components/action-link`	Override	Low	Action link overrides.
✅	`gin-pager`	`css/components/pager`	Override	Low	Pager overrides.
✅	`gin-help`	`css/components/help`	Override	Low	Help text overrides.
🔲	`gin-system-report`	`css/components/system-status-report`	Override	Low	Status report overrides.
🔲	`gin-messages`	`css/components/messages`	Override	Medium	Message overrides. Multiple message types.
🔲	`gin-field-ui`	`css/theme/field-ui.admin`	Override	Low	Field UI page overrides.
🔲	`gin-card`	`css/components/card`	Override	Medium	Card component overrides. Dark mode.
🔲	`gin-elements`	`css/base/elements`	Override	Medium	Additional element overrides (links, lists, etc.).
🔲	`gin-admin-item`	New: `css/components/admin-item`	Standalone	Trivial	Admin item component. No Claro equivalent.
🔲	`gin-focus`	New: `css/base/focus`	Standalone	Low	Focus ring styles. Complements Claro's focus but uses `--gin-*` vars.
🔲	`gin-system-modules`	`css/components/modules-page`	Override	Low	Modules page overrides.
🔲	`gin-system-diff`	New: `css/components/system-diff`	Standalone	Trivial	Diff module styling. No Claro equivalent.
🔲	`gin-update`	New: `css/components/update`	Standalone	Trivial	Update module styling.
🔲	`gin-status-report`	`css/components/system-status-report`	Override	Low	Additional status report styles. Note: both `gin-status-report` and `gin-system-report` target status reports.
🔲	`gin-divider`	`css/components/divider`	Override	Trivial	Divider overrides.
🔲	`gin-progress`	`css/components/progress`	Override	Low	Progress bar overrides.
🔲	`gin-insert`	New: `css/components/insert`	Standalone	Trivial	Insert module styling.
🔲	`gin-system-themes`	New: `css/components/system-themes`	Standalone	Trivial	Themes admin page.
🔲	`gin-panel`	`css/components/system-admin--panel`	Override	Low	Panel overrides.
🔲	`gin-performance`	New: `css/components/performance`	Standalone	Trivial	Performance page styling.
🔲	`gin-blocks`	New: `css/components/blocks`	Standalone	Trivial	Block admin page styling.
🔲	`gin-batch`	New: `css/components/batch`	Standalone	Trivial	Batch operations styling.
🔲	`gin-maxlength`	New: `css/components/maxlength`	Standalone	Trivial	Maxlength counter styling.
🔲	`gin-local-actions`	`css/layout/local-actions`	Override	Low	Local actions overrides.
🔲	`gin-tour`	New: `css/components/tour`	Standalone	Trivial	Tour module styling.
🔲	`gin-quotation`	New: `css/base/quotation`	Standalone	Trivial	Blockquote styling.
🔲	`gin-image-preview`	`css/components/image-preview`	Override	Low	Image preview overrides.
🔲	`gin-permissions`	New: `css/components/permissions`	Standalone	Trivial	Permissions page styling.
🔲	`gin-taxonomy`	New: `css/components/taxonomy`	Standalone	Trivial	Taxonomy admin styling.
🔲	`gin-toolbar-icons`	`css/theme/toolbar.icons.theme`	Override	Medium	Toolbar icon overrides. Many icon definitions.

2c. Migration components (`migration/css/components/`)

	Migration file	Merge target	Type	Complexity	Notes
🔲	`ajax`	`css/components/ajax-progress.module`	Override	Low	Ajax throbber overrides.
🔲	`autocomplete`	`css/components/autocomplete-loading.module`	Override	Low	Autocomplete dropdown overrides.
🔲	`breadcrumb`	`css/components/breadcrumb` + `css/layout/breadcrumb`	Override	Medium	Breadcrumb component + layout overrides.
🔲	`ckeditor5`	`css/components/ckeditor5`	Override	Medium	CKEditor 5 overrides.
🔲	`contextual_links`	New: `css/components/contextual-links`	Standalone	Low	Contextual links styling. No Claro equivalent.
🔲	`description_toggle`	New: `css/components/description-toggle`	Standalone	Low	Help icon toggle. No Claro equivalent.
🔲	`dialog`	`css/components/dialog`	Override	High	Dialog overrides. Must merge with both `css/components/dialog` and `migration/css/theme/dialog`. Three source files total.
🔲	`edit_form`	New: `css/components/edit-form`	Standalone	Low	Edit form layout (sidebar/content regions).
🔲	`maintenance_page`	`css/theme/maintenance-page`	Override	Medium	Maintenance page overrides.
🔲	`media_library`	`css/components/media-library.ui` + `css/theme/media-library`	Override	High	Large file (~525 lines). Overlaps with two Claro files. Grid, modal, dark mode.
🔲	`more_actions`	New: `css/components/more-actions`	Standalone	Low	More actions dropdown.
🔲	`node_preview`	`css/components/node-preview`	Override	Medium	Node preview overrides. Backdrop blur, dark mode.
🔲	`revisions`	New: `css/components/revisions`	Standalone	Low	Revisions page styling.
🔲	`settings_tray`	New: `css/components/settings-tray`	Standalone	Low	Settings tray (off-canvas) styling.
🔲	`settings_tray_edit`	New: `css/components/settings-tray-edit`	Standalone	Low	Settings tray edit mode styling.
🔲	`settings`	New: `css/components/settings`	Standalone	Low	Gin settings panel.
🔲	`sidebar`	New: `css/components/sidebar`	Standalone	Medium	Sidebar component. Responsive, transitions.
🔲	`status`	New: `css/components/status`	Standalone	Low	Status message enhancements.
🔲	`tableselect`	`css/components/tableselect`	Override	Medium	Tableselect/VBO overrides. Sticky, animations.
🔲	`tabs`	`css/components/tabs` + `css/components/vertical-tabs`	Override	High	~500 lines. Horizontal tabs, vertical tabs, details/summary, dark mode, responsive, forced-colors.
🔲	`toolbar`	`css/components/toolbar.module`	Override	High	Large toolbar component overrides. Many icons, responsive, dark mode.
🔲	`tooltip`	New: `css/components/tooltip`	Standalone	Trivial	Tooltip component. No Claro equivalent.

2d. Migration layout (`migration/css/layout/`)

	Migration file	Merge target	Type	Complexity	Notes
🔲	`navigation`	New: `css/layout/navigation`	Standalone	Medium	Navigation layout. Responsive, many breakpoints.
🔲	`toolbar`	`css/theme/toolbar.theme`	Override + Additive	High	Toolbar layout. Major overrides to Claro toolbar layout. Responsive, dark mode.
🔲	`top_bar`	New: `css/layout/top-bar`	Standalone	Medium	Top bar layout. Responsive.

Cleanup and Final Audit

	#	Task
🔲	5.1	Remove `migration/css/` directory entirely
🔲	5.2	Remove `migration/css/base/media-queries.pcss.css` (already merged in Phase 1)
🔲	5.3	Audit `default_admin.libraries.yml` — verify no references to `migration/` paths remain
🔲	5.4	Rename any remaining underscore-named files to hyphen convention
🔲	5.5	Remove the `gin-` prefix from any moved standalone files if desired
🔲	5.6	Full visual regression test suite across all admin pages
🔲	5.7	Verify CSS compilation succeeds with `core/scripts/css/compile.js`
🔲	5.8	Check for orphaned `@import` statements
🔲	5.9	Search for any remaining `--gin-*` variable references that lack definitions

Summary Statistics

	Category	Count
🔲	Total migration `.pcss.css` files	55
🔲	Standalone (move only)	32
🔲	Simple overrides (merge, low complexity)	20
🔲	Complex merges (high complexity)	18
🔲	Foundation (must do first)	5

Issue fork drupal-3582833

Show commands

Start within a Git clone of the project using the version control instructions.

Add & fetch this issue fork’s repository

Or, if you do not have SSH keys set up on git.drupalcode.org:

Add & fetch this issue fork’s repository

3582833-consolidate-refactor-remove changes, plain diff MR !15520
Check out this branch for the first time

Check out existing branch, if you already have it locally

About issue forks

Comments

Comment #1

2 April 2026 at 12:45

mherchel created an issue. See original summary.

Comment #2

mherchel

he/him

English

Gainesville, FL, US

commented 2 April 2026 at 12:46

Status:

Active

» Postponed

Postponing on #3582826: Untangle gin.css

Comment #3

mherchel

he/him

English

Gainesville, FL, US

commented 9 April 2026 at 13:21

Still postponed on #3583057: Convert the compiled CSS in default_admin's components, layout, and theme to modern PostCSS

Comment #4

mherchel

he/him

English

Gainesville, FL, US

commented 9 April 2026 at 13:23

Title:	Remove, refactor, and untangle Claro's CSS from Default Admin theme	» Consolidate, refactor, remove and untangle Claro's CSS from Default Admin theme
Issue summary:	View changes

Comment #5

mherchel

he/him

English

Gainesville, FL, US

commented 20 April 2026 at 19:48

Status:

Postponed

» Active

#3583057: Convert the compiled CSS in default_admin's components, layout, and theme to modern PostCSS is fixed. This can be worked on

Comment #6

mherchel

he/him

English

Gainesville, FL, US

commented 21 April 2026 at 14:52

Issue summary:

View changes

Comment #7

mherchel

he/him

English

Gainesville, FL, US

commented 21 April 2026 at 17:31

Issue summary:

View changes

Comment #8

mherchel

he/him

English

Gainesville, FL, US

commented 21 April 2026 at 17:50

Issue summary:

View changes

Comment #9

mherchel

he/him

English

Gainesville, FL, US

commented 21 April 2026 at 18:17

I'm working on moving base/media-queries over.

Comment #10

21 April 2026 at 18:21

mherchel opened merge request !15520

Comment #11

mherchel

he/him

English

Gainesville, FL, US

commented 21 April 2026 at 18:23

Issue summary:

View changes

Completed base/media-queries .

Updated IS

Comment #12

mherchel

he/him

English

Gainesville, FL, US

commented 21 April 2026 at 19:54

Issue summary:

View changes

Also worked on moving theme/variables to css/base/variables.

Verified no visual regressions.

Comment #13

mherchel

he/him

English

Gainesville, FL, US

commented 21 April 2026 at 20:18

Working on moving theme/font to css/base/font and theme/accent to css/theme/accent

Comment #14

mherchel

he/him

English

Gainesville, FL, US

commented 21 April 2026 at 20:39

Issue summary:

View changes

Completed work on moving theme/font to css/base/font and theme/accent to css/theme/accent. VRT passing.

Comment #15

mherchel

he/him

English

Gainesville, FL, US

commented 22 April 2026 at 11:53

Working on gin-icons

Comment #16

mherchel

he/him

English

Gainesville, FL, US

commented 22 April 2026 at 11:55

Issue summary:

View changes

Completed moving gin-icons.

Comment #17

mherchel

he/him

English

Gainesville, FL, US

commented 22 April 2026 at 11:56

Starting gin-body

Comment #18

mherchel

he/him

English

Gainesville, FL, US

commented 22 April 2026 at 12:12

Issue summary:

View changes

Moved gin-body into elements.

Comment #19

mherchel

he/him

English

Gainesville, FL, US

commented 22 April 2026 at 12:36

Issue summary:

View changes

Refactored out gin-color-overrides. VRT passed

Comment #20

mherchel

he/him

English

Gainesville, FL, US

commented 22 April 2026 at 12:39

Issue summary:

View changes

Comment #21

mherchel

he/him

English

Gainesville, FL, US

commented 23 April 2026 at 12:12

Getting started on gin-views-unwrapped and gin-regions

Comment #22

mherchel

he/him

English

Gainesville, FL, US

commented 23 April 2026 at 12:29

Within gin-views-unwrapped, there's a .show-6 CSS class. This isn't a Drupal class, and is likely a utility class.

I pinged @saschaeggi on it at https://drupal.slack.com/archives/C012J63GVB8/p1776946926935409 just to be sure.

Going to yank it for now. We can always put it back if we find something using it.

Comment #23

mherchel

he/him

English

Gainesville, FL, US

commented 23 April 2026 at 12:46

Issue summary:

View changes

Comment #24

mherchel

he/him

English

Gainesville, FL, US

commented 23 April 2026 at 16:52

Issue summary:

View changes

Completed refactoring out gin-regions.

Note there's some differences in the visual regression test:

If the navigation toolbar is open, the body:not(.toolbar-tray-open) .layout-container { was taking precedence, which adjusted the inline margin. This rule was likely unintended as if the Toolbar module is not enabled (which it won't be in D12), the CSS should not take effect. https://git.drupalcode.org/project/drupal/-/merge_requests/15520/diffs?c...

Comment #25

mherchel

he/him

English

Gainesville, FL, US

commented 24 April 2026 at 16:22

Issue summary:

View changes

Completed gin-layers. It was more complicated than expected, and also had to remove unnecessary specificity from the views-exposed-form

Comment #26

mherchel

he/him

English

Gainesville, FL, US

commented 24 April 2026 at 16:23

Working on gin-title

Comment #27

mherchel

he/him

English

Gainesville, FL, US

commented 24 April 2026 at 16:41

Issue summary:

View changes

Completed gin-title

Comment #28

mherchel

he/him

English

Gainesville, FL, US

commented 24 April 2026 at 16:43

Working on gin-extend

Comment #29

mherchel

he/him

English

Gainesville, FL, US

commented 24 April 2026 at 17:51

Issue summary:

View changes

Completed refactoring out gin-extend.

Comment #30

mherchel

he/him

English

Gainesville, FL, US

commented 26 April 2026 at 18:00

Working on gin-claro-improvements

Comment #31

mherchel

he/him

English

Gainesville, FL, US

commented 26 April 2026 at 18:55

Issue summary:

View changes

Completed gin-claro-improvements

Comment #32

mherchel

he/him

English

Gainesville, FL, US

commented 26 April 2026 at 18:55

Working on gin-views

Comment #33

dharizza commented 27 April 2026 at 00:55

Working on gin-table.

Comment #34

mherchel

he/him

English

Gainesville, FL, US

commented 27 April 2026 at 13:01

Issue summary:

View changes

Went deep into a rabbit hole on gin-views. There were 4(!!!) Views files that were arranged in a very non-componenty way. They're all now consolidated into one (views-ui.pcss.css).

In the future, we might want split it up in a more logical manor. It's 1500+ lines.