Problem/Motivation

The Default Admin theme was forked from Gin and still contains implementation-facing gin and claro names. These occur in CSS classes and selectors, JavaScript files, behaviors and object identifiers, once() IDs, settings and local-storage keys, PHP and Twig output, comments, documentation, filenames, and test fixtures.

This issue is the canonical implementation issue for removing or deliberately retaining those references. This is not a blind text replacement: identifiers and selectors may be coupled to rendered markup, persisted browser state, contributed code, accessibility behavior, and compiled CSS.

Related work

  • #3576494 remains the active tracking meta.
  • #3576496 transfers its remaining Claro requirements here before becoming a duplicate.
  • #3611446 transfers its top-bar, breadcrumb, accessibility, high-contrast, and visual-regression requirements here before becoming a duplicate.
  • !14967, !15233, and !16340 are reference inventories and must not be cherry-picked wholesale.

Proposed resolution

Create a new MR from current main. Use the related issues and MRs as inventories of prior work, decisions, and contributors, then implement and test the cleanup against current code.

Adopt a consistent Default Admin namespace for theme-owned identifiers. Before renaming anything externally consumable or persisted in a browser, determine its compatibility surface and provide an appropriate transition. This may include a temporary alias, reading and migrating an old local-storage value, supporting an old settings key during a defined transition, or retaining an intentionally documented name.

Maintain an explicit reviewed allowlist of legitimate remaining Gin and Claro references. Every entry must state why it remains, such as an upstream project name or URL, historical attribution, compatibility identifier, or required external reference. Remove or rename every non-allowlisted implementation reference.

Remaining tasks

  • ☑ Create a fresh branch and MR from current main; do not cherry-pick !14967, !15233, or !16340 wholesale.
  • ☐ Preserve contribution credit for substantive investigation, design, review, and implementation from the related issues and MRs.
  • ☑ Inventory gin and claro across source, generated assets, tests, fixtures, comments, and documentation.
  • ☑ Add an allowlist with a rationale for every legitimate remaining reference.
  • ☑ Audit and rename JavaScript files, behavior names, Drupal objects/classes, once() IDs, event identifiers, selectors, and comments that are Default Admin implementation details.
  • ☑ Audit JavaScript settings and local-storage keys; implement migration or compatibility behavior for persisted or externally consumed values.
  • ☑ Update PHP preprocess output and Twig markup together with coupled JavaScript and CSS selectors.
  • ☐ Preserve top-bar and breadcrumb presentation while replacing inherited implementation hooks with semantic or Default Admin hooks.
  • ☑ Confirm correct landmark semantics and accessible names.
  • ☐ Confirm breadcrumb labeling, keyboard behavior, focus treatment, and semantics.
  • ☑ Update PCSS sources and compiled CSS together.
  • ☑ Audit keyframes, custom properties, classes, attributes, selectors, and selectors used by PHP, Twig, or JavaScript.
  • ☑ Update PHP classes/methods, settings labels, defaults, Twig templates, libraries, filenames, comments, and documentation where appropriate.
  • ☑ Review public or semi-public names before changing them; document compatibility or intentional retention.
  • ☐ Add or update tests for PHP, Twig, JavaScript behavior, settings, and migration/compatibility paths.
  • ☐ Update VRT baselines only after confirming intended presentation is unchanged.
  • ☐ Test high-contrast modes, focus indicators, borders, contrast, and top-bar/breadcrumb rendering.
  • ☐ Test common administrative pages and interactions, including autocomplete, details, tableselect, tabledrag, media selection, sticky actions, navigation, top bar, and breadcrumbs.
  • ☐ Verify landmarks, labels, focus order, keyboard operation, and contrast.
  • ☐ Run relevant linting, unit/functional tests, JavaScript tests, and VRT.

User interface changes

No intentional visual regression is expected. Internal hooks may change, but presentation and interaction behavior must remain stable. Revised semantic markup or Default Admin hooks for the top bar and breadcrumbs must preserve their appearance, high-contrast support, and accessible navigation experience.

Introduced terminology

  • Default Admin namespace: identifiers owned by the Default Admin theme rather than inherited Gin or Claro names.
  • Allowlist: reviewed legitimate remaining Gin or Claro references and the reason each remains.

API changes

Potentially. JavaScript behaviors and objects, settings, local-storage keys, CSS classes, and Twig markup may be consumed externally. Assess each before renaming. Any externally consumable name that changes needs documented compatibility handling or an approved breaking-change decision.

Data model changes

None expected.

Browser local storage is persisted client-side state, not configuration. Renamed keys must be migrated, read compatibly, or intentionally reset with documented reasoning.

Release notes snippet

None expected.

CommentFileSizeAuthor
#15 3605702-nr-bot_8tzrc7u0.txt91 bytesneeds-review-queue-bot
#8 3605702-nr-bot_c40p3vnt.txt91 bytesneeds-review-queue-bot

Issue fork drupal-3605702

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:

About issue forks

Comments

mherchel created an issue. See original summary.

quietone’s picture

quietone commented
Parent issue: » #3576488: [meta] Admin theme: path to beta and stable
quietone’s picture

quietone commented
Parent issue: #3576488: [meta] Admin theme: path to beta and stable » #3582351: [Meta] Clean up CSS within Admin theme

Sorry, wrong parent

jurgenhaas’s picture

jurgenhaas
he/him
Primary language German
Location Gottmadingen
commented
Title: Remove any gin namespacing from CSS classes, including CSS selectors used in PHP and template files. » Remove remaining Gin and Claro implementation names from Default Admin theme
Assigned: Unassigned » jurgenhaas
Issue summary: View changes
Status: Active » Needs work

I've updated the IS and will now start implementing this.

jurgenhaas opened merge request !16863

jurgenhaas’s picture

jurgenhaas
he/him
Primary language German
Location Gottmadingen
commented
Issue summary: View changes

This is a massive MR with 173 changed files. But all within default_admin only. And a first manual test doesn't show any regressions. If anyone wants to cross-check, this is the time to get started. I'll continue with tests and the likes in the meantime.

mherchel’s picture

mherchel
he/him
Primary language English
Location Gainesville, FL, US
commented
Status: Needs work » Needs review

I'm guessing this should be set to NR?

I'll be taking a quick look at this in a bit.

needs-review-queue-bot’s picture

needs-review-queue-bot commented
Status: Needs review » Needs work
StatusFileSize
new 3605702-nr-bot_c40p3vnt.txt91 bytes

The Needs Review Queue Bot tested this issue. It no longer applies to Drupal core. Therefore, this issue status is now "Needs work".

This does not mean that the patch necessarily needs to be re-rolled or the MR rebased. Read the Issue Summary, the issue tags and the latest discussion here to determine what needs to be done.

Consult the Drupal Contributor Guide to find step-by-step guides for working with issues.

jurgenhaas’s picture

jurgenhaas
he/him
Primary language German
Location Gottmadingen
commented
Status: Needs work » Needs review

Fixed the merge conflicts. Setting back to NR as @mherchel did before the bot switched it back. However, before you move this even further, there are still outstanding tasks in the IS that I'm going to address asap. Mainly tests and cleanup.

mherchel’s picture

mherchel
he/him
Primary language English
Location Gainesville, FL, US
commented
Status: Needs review » Needs work

Just went through and left a bunch of comments. The gist is that in most of it, we can remove the default-admin prefix.

The reasoning is that Gin had to worry about namespace conflicts in places that we do not. I'd like to err on the side of simplicity.

jurgenhaas’s picture

jurgenhaas
he/him
Primary language German
Location Gottmadingen
commented
Assigned: jurgenhaas » Unassigned
Status: Needs work » Needs review

@mherchel I've implemented your suggested changes. I took your "the gist is that in most of it ..." was meant to not only your specific suggestions should be updated, but that there's a pattern to follow. That's what I've done. Please have another look.

After that, let's discuss the list of remaining tasks in the IS, and what part of the incomplete ones should be done here vs. in follow-ups.

mherchel’s picture

mherchel
he/him
Primary language English
Location Gainesville, FL, US
commented
Status: Needs review » Needs work

Did another pass, and still needs some work. Haven't visually tested yet.

jurgenhaas’s picture

jurgenhaas
he/him
Primary language German
Location Gottmadingen
commented
Status: Needs work » Needs review

Here is another round of cleanup.

mherchel’s picture

mherchel
he/him
Primary language English
Location Gainesville, FL, US
commented

Spent over an hour looking at this, and it's good. Although I don't want to RTBC (so I can commit).

Note there are some differences when running visual regression, but they actually fix the bugs!

The CSS had in it #block-gin-content, but of course when Gin was renamed, this no longer applied. Now that the CSS is being changed to #block-default-admin-content, it now applies and removes some annoying spacing on some of it's sub-selectors.

So, we need some other folks to take a look at this and RTBC.

needs-review-queue-bot’s picture

needs-review-queue-bot commented
Status: Needs review » Needs work
StatusFileSize
new 3605702-nr-bot_8tzrc7u0.txt91 bytes

The Needs Review Queue Bot tested this issue. It no longer applies to Drupal core. Therefore, this issue status is now "Needs work".

This does not mean that the patch necessarily needs to be re-rolled or the MR rebased. Read the Issue Summary, the issue tags and the latest discussion here to determine what needs to be done.

Consult the Drupal Contributor Guide to find step-by-step guides for working with issues.

bernardm28’s picture

bernardm28 commented
Status: Needs work » Reviewed & tested by the community

Looks good, I could not find any issues with it. After comparing the before and after.
But if there is I'm sure a followup will be coming.

  • mherchel committed 35bbc4e3 on main 
    task: #3605702 Remove remaining Gin and Claro implementation names from...
mherchel’s picture

mherchel
he/him
Primary language English
Location Gainesville, FL, US
commented
Status: Reviewed & tested by the community » Patch (to be ported)

Committed and pushed 35bbc4e3bdc to main. Thanks!

  • mherchel committed 93790bd3 on 11.x 
    task: #3605702 Remove remaining Gin and Claro implementation names from...

  • mherchel committed 877c222e on 11.4.x 
    task: #3605702 Remove remaining Gin and Claro implementation names from...
mherchel’s picture

mherchel
he/him
Primary language English
Location Gainesville, FL, US
commented
Status: Patch (to be ported) » Fixed

Now that this issue is closed, review the contribution record.

As a contributor, attribute any organization that helped you, or if you volunteered your own time.

Maintainers, credit people who helped resolve this issue.

  • godotislate committed d1a55583 on 11.4.x 
    Revert "task: #3605702 Remove remaining Gin and Claro implementation...
godotislate’s picture

godotislate
he/him
commented
Version: main » 11.x-dev
Status: Fixed » Needs work

Reverted from 11.4.x because Drupal\Tests\default_admin\Unit\ImplementationNameTest is failing: https://git.drupalcode.org/project/drupal/-/jobs/12022625

Implementation Name (Drupal\Tests\default_admin\Unit\ImplementationName)
     ✔ Reviewed default admin prefixes
     ✘ Implementation names
       ┐
       ├ src/Hook/ThemeHooks.php:125: $gin_info = $this->themeHandler->listInfo()['default_admin']->info;
       ├ src/Hook/ThemeHooks.php:127: $gin_toolbar_overrides = $gin_info['libraries-override']['toolbar/toolbar'];
       ├ src/Hook/ThemeHooks.php:128: foreach ($gin_toolbar_overrides['css'] as $concern => $overrides) {
       ├ src/Hook/ThemeHooks.php:129: foreach ($gin_toolbar_overrides['css'][$concern] as $key => $value) {
       ├ src/Hook/ThemeHooks.php:135: $gin_toolbar_menu_overrides = $gin_info['libraries-override']['toolbar/toolbar.menu'];
       ├ src/Hook/ThemeHooks.php:136: foreach ($gin_toolbar_menu_overrides['css'] as $concern => $overrides) {
       ├ src/Hook/ThemeHooks.php:137: foreach ($gin_toolbar_menu_overrides['css'][$concern] as $key => $value) {
       ├ css/theme/toolbar.theme.pcss.css:4: * If Claro is the admin theme, this stylesheet will be used by the active theme
       ├ css/theme/toolbar.theme.pcss.css:5: * even if the active theme is not Claro.
       ├ css/theme/toolbar.theme.css:10: * If Claro is the admin theme, this stylesheet will be used by the active theme
       ├ css/theme/toolbar.theme.css:11: * even if the active theme is not Claro. 
       ├ css/theme/toolbar.icons.theme.pcss.css:5: * If Claro is the admin theme, this stylesheet will be used by the active theme
       ├ css/theme/toolbar.icons.theme.pcss.css:6: * even if the active theme is not Claro.
       ├ css/theme/toolbar.icons.theme.css:12: * If Claro is the admin theme, this stylesheet will be used by the active theme
       ├ css/theme/toolbar.icons.theme.css:13: * even if the active theme is not Claro.
       ├ css/state/toolbar.menu.pcss.css:4: * If Claro is the admin theme, this stylesheet will be used by the active theme
       ├ css/state/toolbar.menu.pcss.css:5: * even if the active theme is not Claro.
       ├ css/state/toolbar.menu.css:10: * If Claro is the admin theme, this stylesheet will be used by the active theme
       ├ css/state/toolbar.menu.css:11: * even if the active theme is not Claro.  
       ├ Failed asserting that two arrays are identical.                          
       ┊ ---·Expected
       ┊ +++·Actual
       ┊ @@ @@
       ┊ -Array·&0·[]
       ┊ +Array·&0·[
       ┊ +····0·=>·'src/Hook/ThemeHooks.php:125:·$gin_info·=·$this->themeHandler->listInfo()['default_admin']->info;',
       ┊ +····1·=>·'src/Hook/ThemeHooks.php:127:·$gin_toolbar_overrides·=·$gin_info['libraries-override']['toolbar/toolbar'];',
       ┊ +····2·=>·'src/Hook/ThemeHooks.php:128:·foreach·($gin_toolbar_overrides['css']·as·$concern·=>·$overrides)·{',
       ┊ +····3·=>·'src/Hook/ThemeHooks.php:129:·foreach·($gin_toolbar_overrides['css'][$concern]·as·$key·=>·$value)·{',
       ┊ +····4·=>·'src/Hook/ThemeHooks.php:135:·$gin_toolbar_menu_overrides·=·$gin_info['libraries-override']['toolbar/toolbar.menu'];',
       ┊ +····5·=>·'src/Hook/ThemeHooks.php:136:·foreach·($gin_toolbar_menu_overrides['css']·as·$concern·=>·$overrides)·{',
       ┊ +····6·=>·'src/Hook/ThemeHooks.php:137:·foreach·($gin_toolbar_menu_overrides['css'][$concern]·as·$key·=>·$value)·{',
       ┊ +····7·=>·'css/theme/toolbar.theme.pcss.css:4:·*·If·Claro·is·the·admin·theme,·this·stylesheet·will·be·used·by·the·active·theme',
       ┊ +····8·=>·'css/theme/toolbar.theme.pcss.css:5:·*·even·if·the·active·theme·is·not·Claro.',
       ┊ +····9·=>·'css/theme/toolbar.theme.css:10:·*·If·Claro·is·the·admin·theme,·this·stylesheet·will·be·used·by·the·active·theme',
       ┊ +····10·=>·'css/theme/toolbar.theme.css:11:·*·even·if·the·active·theme·is·not·Claro.',
       ┊ +····11·=>·'css/theme/toolbar.icons.theme.pcss.css:5:·*·If·Claro·is·the·admin·theme,·this·stylesheet·will·be·used·by·the·active·theme',
       ┊ +····12·=>·'css/theme/toolbar.icons.theme.pcss.css:6:·*·even·if·the·active·theme·is·not·Claro.',
       ┊ +····13·=>·'css/theme/toolbar.icons.theme.css:12:·*·If·Claro·is·the·admin·theme,·this·stylesheet·will·be·used·by·the·active·theme',
       ┊ +····14·=>·'css/theme/toolbar.icons.theme.css:13:·*·even·if·the·active·theme·is·not·Claro.',
       ┊ +····15·=>·'css/state/toolbar.menu.pcss.css:4:·*·If·Claro·is·the·admin·theme,·this·stylesheet·will·be·used·by·the·active·theme',
       ┊ +····16·=>·'css/state/toolbar.menu.pcss.css:5:·*·even·if·the·active·theme·is·not·Claro.',
       ┊ +····17·=>·'css/state/toolbar.menu.css:10:·*·If·Claro·is·the·admin·theme,·this·stylesheet·will·be·used·by·the·active·theme',
       ┊ +····18·=>·'css/state/toolbar.menu.css:11:·*·even·if·the·active·theme·is·not·Claro.',
       ┊ +]
       │
       │ /builds/core/themes/default_admin/tests/src/Unit/ImplementationNameTest.php:207
       ┴
    
    FAILURES!
    Tests: 2, Assertions: 2, Failures: 1.

It looks like it's at least partially because #3614955: Move library overrides for Toolbar from Claro and Default Admin to Toolbar was not backported to 11.4.x.

longwave’s picture

longwave
he/him
Primary language English
Location UK
commented

As a refactoring I'm not sure this is worth backporting to a patch release? Maybe we just mark this fixed in 11.5/12.0 and be done?

godotislate’s picture

godotislate
he/him
commented

+1 to #25.

mherchel’s picture

mherchel
he/him
Primary language English
Location Gainesville, FL, US
commented

my thought process was

1) This is experimental
2) When people test their modules, they might want to use one of the CSS classes in their contrib modules
3) Keeping the codebase in sync makes things easier going forward (we have a number of other accessibility releases coming down the wire).

Thoughts?

godotislate’s picture

godotislate
he/him
commented

I think a backport to 11.4.x is OK in theory, but given issues like #3614955: Move library overrides for Toolbar from Claro and Default Admin to Toolbar that won't go to 11.4.x, the codebases have already drifted. Also D12 beta is scheduled to be out in a couple weeks, before the next patch release window, so module maintainers could conceivably start testing using the beta soon.

Anyway, I think the options are:

  1. No backport
  2. Backport without the specific unit test
  3. Refactor unit test to work with 11.4.x
mherchel’s picture

mherchel
he/him
Primary language English
Location Gainesville, FL, US
commented

That makes sense. FYI, I'm OOO for most of the week. But will work on this as I can.

quietone’s picture

quietone commented
Issue tags: +Needs followup

Looks like follow up work is neede because there are still instances of Claro

(main)$ git grep -ni claro | grep core/themes/default_admin
core/themes/default_admin/css/theme/accent.css:41:[data-admin-focus="claro"] {
core/themes/default_admin/css/theme/accent.pcss.css:37:[data-admin-focus="claro"] {
core/themes/default_admin/images/core/README.md:3:should be removed before moving Claro to Drupal core. See
core/themes/default_admin/images/core/README.md:4:https://www.drupal.org/project/claro/issues/3045216 for details.
core/themes/default_admin/src/Settings.php:295:        'claro' => $this->t('Legacy green'),
core/themes/default_admin/tests/fixtures/implementation-name-allowlist.json:14:    "pattern": "'claro' =>",
core/themes/default_admin/tests/fixtures/implementation-name-allowlist.json:19:    "pattern": "data-admin-focus=\"claro\"",
core/themes/default_admin/tests/fixtures/implementation-name-allowlist.json:24:    "pattern": "data-admin-focus=\"claro\"",
core/themes/default_admin/tests/fixtures/implementation-name-allowlist.json:49:    "pattern": "Claro",
core/themes/default_admin/tests/fixtures/implementation-name-allowlist.json:54:    "pattern": "project/claro",
core/themes/default_admin/tests/fixtures/implementation-name-allowlist.json:104:    "pattern": "(?:gin|claro)",
core/themes/default_admin/tests/fixtures/implementation-name-allowlist.json:109:    "pattern": "(?:Gin|Claro)",
core/themes/default_admin/tests/src/Unit/ImplementationNameTest.php:145:    $name_pattern = '/(?:\b(?:gin|Gin|claro|Claro)\b'
core/themes/default_admin/tests/src/Unit/ImplementationNameTest.php:146:      . '|(?<![A-Za-z])(?:gin|claro)(?=[._-]|[A-Z])'
core/themes/default_admin/tests/src/Unit/ImplementationNameTest.php:147:      . '|(?<![A-Za-z])(?:Gin|Claro)(?=[A-Z]))/';
core/themes/default_admin/tests/src/Unit/ImplementationNameTest.php:166:      if (preg_match('/(?:gin|claro)/i', $file->getFilename())) {

core/themes/default_admin/css/theme/accent.pcss.css - Should the be data-accent.pcss.css
core/themes/default_admin/images/core/README.md - This states the core/themes/default_admin/images/core can be deleted. Is that a followup?

quietone’s picture

quietone commented

And also instances of gin.

(main)$ grep -iwlR claro core/themes/default_admin
core/themes/default_admin/tests/fixtures/implementation-name-allowlist.json
core/themes/default_admin/tests/src/Unit/ImplementationNameTest.php
core/themes/default_admin/css/theme/accent.pcss.css
core/themes/default_admin/css/theme/accent.css
core/themes/default_admin/src/Settings.php
core/themes/default_admin/images/core/README.md
(main)$ grep -iwlR gin core/themes/default_admin
core/themes/default_admin/tests/fixtures/implementation-name-allowlist.json
core/themes/default_admin/tests/src/Unit/ImplementationNameTest.php
core/themes/default_admin/tests/src/FunctionalJavascript/LegacyStorageTest.php
core/themes/default_admin/tests/src/Functional/AdminTest.php
core/themes/default_admin/migration/js/init.js
core/themes/default_admin/src/Hook/FormHooks.php
core/themes/default_admin/src/Hook/ThemeHooks.php
core/themes/default_admin/src/Settings.php
core/themes/default_admin/config/install/default_admin.settings.yml
core/themes/default_admin/logo.png
core/themes/default_admin/font/inter.woff2

mherchel changed the visibility of the branch 3605702-remove-gin-naming-11-4-x to hidden.

mherchel changed the visibility of the branch 3605702-remove-gin-naming-11-4-x to active.

mherchel opened merge request !17103

mherchel’s picture

mherchel
he/him
Primary language English
Location Gainesville, FL, US
commented
Status: Needs work » Needs review

Tests are passing. Code looks good for 11.4.x

godotislate’s picture

godotislate
he/him
commented
Issue tags: -Needs followup

Added the follow-up per #30/31: #3623097: Remove remaining Gin and Claro implementation names from Default Admin theme, part 2

jurgenhaas’s picture

jurgenhaas
he/him
Primary language German
Location Gottmadingen
commented

I've reviewed this and found 3 noteable things:

  1. The divergance on the ImplementationNameTest is deliberate and OK
  2. As #3604071: Change default to auto for light/dark mode did not land on 11.4.x, it's now included by MR!17103, which is OK. We may want to leave a note there, that this happened
  3. Also #3617875: Better Dark Mode Support for Disabled Elements did not land on 11.4.x but should probably now be done so that we have parity and get proper test results and feedback from users

Apart from that, I'd RTBC this.

mherchel’s picture

mherchel
he/him
Primary language English
Location Gainesville, FL, US
commented
Status: Needs review » Reviewed & tested by the community

Per #37

  • mherchel committed 7425089d on 11.4.x 
    task: #3605702 Remove remaining Gin and Claro implementation names from...
mherchel’s picture

mherchel
he/him
Primary language English
Location Gainesville, FL, US
commented
Status: Reviewed & tested by the community » Fixed

Committed and pushed 7425089d862 to 11.4.x. Thanks!

Now that this issue is closed, review the contribution record.

As a contributor, attribute any organization that helped you, or if you volunteered your own time.

Maintainers, credit people who helped resolve this issue.