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:cssfrom thecore/directory. Note you can pass in--fixto 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. |
Followup issue is at #3590364: Part 2 of Consolidate, refactor, remove and untangle Claro's CSS from Default Admin theme
Testing instructions:
To properly test, you'll want to visit the theme's pages and navigate throughout, while looking for regressions manually.
Note: This is not a 1:1 match with the current main branch. A couple changes that have been made that cause differences in the visual regression testing include:
- Removal of some extra spacing around main container when navigation tray is open. This was an obvious bug when we looked at the code.
- Proper support for admin theme's layout density setting within table-cells. Previously these were not responding as expected, and it was easier to fix this.
To properly test, you'll want to visit the theme's pages and navigate throughout, while looking for regressions manually.
Issue fork drupal-3582833
Show commands
Start within a Git clone of the project using the version control instructions.
Or, if you do not have SSH keys set up on git.drupalcode.org:
Comments
Comment #2
mherchelPostponing on #3582826: Untangle gin.css
Comment #3
mherchelStill postponed on #3583057: Convert the compiled CSS in default_admin's components, layout, and theme to modern PostCSS
Comment #4
mherchelComment #5
mherchel#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
mherchelComment #7
mherchelComment #8
mherchelComment #9
mherchelI'm working on moving
base/media-queriesover.Comment #11
mherchelCompleted base/media-queries .
Updated IS
Comment #12
mherchelAlso worked on moving theme/variables to css/base/variables.
Verified no visual regressions.
Comment #13
mherchelWorking on moving theme/font to css/base/font and theme/accent to css/theme/accent
Comment #14
mherchelCompleted work on moving theme/font to css/base/font and theme/accent to css/theme/accent. VRT passing.
Comment #15
mherchelWorking on gin-icons
Comment #16
mherchelCompleted moving gin-icons.
Comment #17
mherchelStarting gin-body
Comment #18
mherchelMoved gin-body into elements.
Comment #19
mherchelRefactored out gin-color-overrides. VRT passed
Comment #20
mherchelComment #21
mherchelGetting started on gin-views-unwrapped and gin-regions
Comment #22
mherchelWithin gin-views-unwrapped, there's a
.show-6CSS 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
mherchelComment #24
mherchelCompleted 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
mherchelCompleted gin-layers. It was more complicated than expected, and also had to remove unnecessary specificity from the views-exposed-form
Comment #26
mherchelWorking on gin-title
Comment #27
mherchelCompleted gin-title
Comment #28
mherchelWorking on gin-extend
Comment #29
mherchelCompleted refactoring out gin-extend.
Comment #30
mherchelWorking on gin-claro-improvements
Comment #31
mherchelCompleted gin-claro-improvements
Comment #32
mherchelWorking on gin-views
Comment #33
dharizza commentedWorking on gin-table.
Comment #34
mherchelWent 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.
Comment #35
mherchelCompleted tabledrag
Comment #36
mherchelI'll start work on gin-form (likely tomorrow)
Comment #37
dharizza commentedFinalized gin-table.
Getting started on gin-button.
Comment #38
bernardm28 commentedGetting started on gin-admin-item
Comment #39
mherchelFinished refactoring out gin-form. It was a pain.
Moving on to gin-action-link
Comment #40
mherchelRefactored out gin-action-link. Moving on to gin-pager.
Comment #41
mherchelCompleted gin-pager.
Moving on to gin-help.
Comment #42
mherchelcompleted gin-help
Comment #43
dharizza commentedRefactoring of gin-button and gin-dropbutton is done.
Comment #44
catchComment #45
dharizza commentedCurrently working on gin-system-report and gin-status-report.
Comment #46
dharizza commentedCompleted gin-system-report and gin-system-themes. Still working on gin-status-report.
Comment #47
mherchelFixed a regression with the action links rendered as a button.
Grabbing gin-messages.
Comment #48
mherchelCompleted gin-messages.
Moving on to gin-field-ui
Comment #49
mherchelCompleted gin-field-ui.
On to gin-card
Comment #50
mherchelCompleted gin-card.
On to gin-elements
Comment #51
mherchelgin-elements was the easiest of all.
On to gin-admin-item
Comment #52
mherchelCompleted gin-admin-item
Onto gin-focus
Comment #54
mukeysh commentedCompleted gin-system-modules
Comment #55
mukeysh commentedComment #56
mherchelYay! New contributor to this issue (Thanks @mukeysh!)
Finished gin-focus
On to gin-system-diff
Comment #57
mherchelgin-system-diff CSS extends the diff module.
I removed the CSS, and created #3589928: Special styles for "Default Admin" theme in Drupal 12 for that module to move the CSS there.
Moving on to gin-update
Comment #58
mherchelCompleted gin-update
On to gin-status-report
Comment #59
mherchelRefactored out support for upgrade-status module. Opened #3590168: Special styles for "Default Admin" theme in Drupal 12 in that queue.
Comment #60
mherchelCompleted gin-status-report
On to gin-divider
Comment #61
mherchelCompleted gin-divider and gin-progress
On to gin-insert
Comment #62
mukeysh commentedCompleted gin-performance
Comment #63
mukeysh commentedComment #65
nitinkumar_7 commentedComment #66
nitinkumar_7 commentedCompleted gin-blocks
Comment #67
nitinkumar_7 commentedComment #68
nitinkumar_7 commentedCompleted gin-batch
Comment #69
nitinkumar_7 commentedCompleted gin-maxlength
Comment #70
mherchelThanks for working on this @nitinkumar_7.
Comment #71
mherchelOpened #3590316: Special styles for "Default Admin" theme in Drupal 12 for the Insert module (to move styles there).
Comment #72
mherchelRemoved gin-insert
Moving on to gin-panel
Comment #73
mherchelCompleted gin-panel.
Moving to gin-local-actions
Comment #74
mherchelCompleting removing gin-local-actions, and also removed gin-tour.
Moving to gin-quotation and gin-image-preview
Comment #75
mherchelRefactored out gin-image-preview and gin-quotation.
Moving on to gin-permissions and gin-taxonomy
Comment #76
mherchelI was able to just remove gin-taxonomy (the styles weren't applying to anything) and gin-toolbar (for the gin-toolbar module).
We're all done with base. This is a good stopping point. I'm going to create another issue for the rest of the CSS files under
core/themes/default_admin/migration/cssComment #77
mherchelComment #78
mherchelComment #79
mherchelI'm going to spend some time doing additional QA with the visual regression testing tool, and fixing stuff over the weekend
Comment #80
mherchelThis is ready for testing.
Testing instructions:
To properly test, you'll want to visit the theme's pages and navigate throughout, while looking for regressions manually.
Note: This is not a 1:1 match with the current
mainbranch. A couple changes that have been made that cause differences in the visual regression testing include:To properly test, you'll want to visit the theme's pages and navigate throughout, while looking for regressions manually.