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

  1. Add a comment on what you're working on
  2. Do the work
  3. Verify that linting passes by running yarn lint:css from the core/ directory. Note you can pass in --fix to automatically fix some issues.
  4. 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.
  5. Commit the changes to the MR. Be verbose and granular in your commit message
  6. 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

Command icon 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

mherchel created an issue. See original summary.

mherchel’s picture

Status: Active » Postponed
mherchel’s picture

mherchel’s picture

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
mherchel’s picture

mherchel’s picture

Issue summary: View changes
mherchel’s picture

Issue summary: View changes
mherchel’s picture

Issue summary: View changes
mherchel’s picture

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

mherchel’s picture

Issue summary: View changes

Completed base/media-queries .

Updated IS

mherchel’s picture

Issue summary: View changes

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

Verified no visual regressions.

mherchel’s picture

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

mherchel’s picture

Issue summary: View changes

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

mherchel’s picture

Working on gin-icons

mherchel’s picture

Issue summary: View changes

Completed moving gin-icons.

mherchel’s picture

Starting gin-body

mherchel’s picture

Issue summary: View changes

Moved gin-body into elements.

mherchel’s picture

Issue summary: View changes

Refactored out gin-color-overrides. VRT passed

mherchel’s picture

Issue summary: View changes
mherchel’s picture

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

mherchel’s picture

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.

mherchel’s picture

Issue summary: View changes
mherchel’s picture

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...

mherchel’s picture

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

mherchel’s picture

Working on gin-title

mherchel’s picture

Issue summary: View changes

Completed gin-title

mherchel’s picture

Working on gin-extend

mherchel’s picture

Issue summary: View changes

Completed refactoring out gin-extend.

mherchel’s picture

Working on gin-claro-improvements

mherchel’s picture

Issue summary: View changes

Completed gin-claro-improvements

mherchel’s picture

Working on gin-views

dharizza’s picture

Working on gin-table.

mherchel’s picture

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.

mherchel’s picture

Issue summary: View changes

Completed tabledrag

mherchel’s picture

I'll start work on gin-form (likely tomorrow)

dharizza’s picture

Issue summary: View changes

Finalized gin-table.
Getting started on gin-button.

bernardm28’s picture

Getting started on gin-admin-item

mherchel’s picture

Issue summary: View changes

Finished refactoring out gin-form. It was a pain.

Moving on to gin-action-link

mherchel’s picture

Issue summary: View changes

Refactored out gin-action-link. Moving on to gin-pager.

mherchel’s picture

Issue summary: View changes

Completed gin-pager.

Moving on to gin-help.

mherchel’s picture

Issue summary: View changes

completed gin-help

dharizza’s picture

Issue summary: View changes

Refactoring of gin-button and gin-dropbutton is done.

catch’s picture

dharizza’s picture

Currently working on gin-system-report and gin-status-report.

dharizza’s picture

Issue summary: View changes

Completed gin-system-report and gin-system-themes. Still working on gin-status-report.

mherchel’s picture

Fixed a regression with the action links rendered as a button.

Grabbing gin-messages.

mherchel’s picture

Issue summary: View changes

Completed gin-messages.

Moving on to gin-field-ui

mherchel’s picture

Issue summary: View changes

Completed gin-field-ui.

On to gin-card

mherchel’s picture

Issue summary: View changes

Completed gin-card.

On to gin-elements

mherchel’s picture

Issue summary: View changes

gin-elements was the easiest of all.

On to gin-admin-item

mherchel’s picture

Issue summary: View changes

Completed gin-admin-item

Onto gin-focus

mukeysh made their first commit to this issue’s fork.

mukeysh’s picture

Completed gin-system-modules

mukeysh’s picture

Issue summary: View changes
mherchel’s picture

Issue summary: View changes

Yay! New contributor to this issue (Thanks @mukeysh!)

Finished gin-focus

On to gin-system-diff

mherchel’s picture

Issue summary: View changes

gin-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

mherchel’s picture

Issue summary: View changes

Completed gin-update

On to gin-status-report

mherchel’s picture

Refactored out support for upgrade-status module. Opened #3590168: Special styles for "Default Admin" theme in Drupal 12 in that queue.

mherchel’s picture

Issue summary: View changes

Completed gin-status-report

On to gin-divider

mherchel’s picture

Issue summary: View changes

Completed gin-divider and gin-progress

On to gin-insert

mukeysh’s picture

Completed gin-performance

mukeysh’s picture

Issue summary: View changes

nitinkumar_7 made their first commit to this issue’s fork.

nitinkumar_7’s picture

Issue summary: View changes
nitinkumar_7’s picture

Completed gin-blocks

nitinkumar_7’s picture

Issue summary: View changes
nitinkumar_7’s picture

Completed gin-batch

nitinkumar_7’s picture

Issue summary: View changes

Completed gin-maxlength

mherchel’s picture

Thanks for working on this @nitinkumar_7.

mherchel’s picture

Opened #3590316: Special styles for "Default Admin" theme in Drupal 12 for the Insert module (to move styles there).

mherchel’s picture

Issue summary: View changes

Removed gin-insert

Moving on to gin-panel

mherchel’s picture

Issue summary: View changes

Completed gin-panel.

Moving to gin-local-actions

mherchel’s picture

Issue summary: View changes

Completing removing gin-local-actions, and also removed gin-tour.

Moving to gin-quotation and gin-image-preview

mherchel’s picture

Issue summary: View changes

Refactored out gin-image-preview and gin-quotation.

Moving on to gin-permissions and gin-taxonomy

mherchel’s picture

I 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/css

mherchel’s picture

Issue summary: View changes
mherchel’s picture

Issue summary: View changes
mherchel’s picture

Assigned: Unassigned » mherchel
Status: Active » Needs work

I'm going to spend some time doing additional QA with the visual regression testing tool, and fixing stuff over the weekend

mherchel’s picture

Issue summary: View changes
Status: Needs work » Needs review

This 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 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.