Problem/Motivation

The default_admin theme (the Gin contrib theme brought into core) shipped with several overlapping CSS custom-property systems inherited from its Seven → Claro → Gin lineage: a Claro layer (--color-*, --space-*, --font-size-*, --input-*, …) and a Gin layer (--gin-*) that cross-referenced each other. Many tokens were duplicated with diverging values, a large share were dead, dark mode was driven by class-based overrides on only part of the system, and component stylesheets reached straight into raw primitive values.

The goal is a single, documented, canonical token API for the theme (and for contrib that builds on it), with first-class light/dark support.

Proposed resolution

Consolidate everything into one --admin-* namespace, organised in three tiers:

  • Primitives — the raw palette (gray/blue/red ramps) and base scales. Not intended for use in components.
  • Semantic tokens — the public API components consume: text, surfaces/backgrounds, borders, status families, link/primary, focus, etc.
  • Component tokens — per-component values, seeded from the semantic layer.

Mode-aware tokens are expressed as a single light-dark() declaration driven by the color-scheme property, replacing the previous class-based dark-mode override blocks. The accent-color system continues to drive the --admin-color-primary* tokens.

What changed

  • Split the monolithic variables file into category files under css/_variables/ (color, color-accent, spacing, typography, components, misc).
  • Color: consolidated the Claro and Gin color layers into one --admin-color-* system; moved dark mode onto light-dark(); composed the semantic layer from the primitive ramps where they align.
  • Spacing: one canonical spacing scale plus a density-aware scale tied to the layout-density setting; layout dimensions namespaced to avoid collision with core navigation tokens.
  • Radius, typography, motion, icon sizes and misc tokens migrated to --admin-*, merging the duplicate Claro/Gin pairs.
  • Routed component stylesheets off raw primitives and onto the semantic tokens.
  • Fixed a class of dark-mode bugs where a fixed white was used for surfaces that should adapt.
  • Pruned dead custom properties (keeping those that are live cross-module contracts).

The migration was kept value-preserving wherever practical, so the visual output is unchanged apart from a small number of deliberate, signed-off adjustments. The legacy --gin-* custom-property surface has been removed.

Remaining tasks

  • Scope the component-level tokens to their component selectors rather than the global root (follow-up).
  • Remove the remaining gin- prefixes from class and attribute names (separate task; also touches JS and Twig).
  • Accessibility pass on the consolidated tokens (e.g. contrast review of a couple of static link/text colors in dark mode).

Notes

  • Source of truth for the token definitions: core/themes/default_admin/css/_variables/. Edit the *.pcss.css sources, never the compiled *.css.
  • This was accomplished with Claude code and I both doing planning, Claude doing the grunt-work, and me doing testing, cleaning up, etc.

Issue fork drupal-3599680

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

Title: Consolidate, merge, and refactor Gin's CSS variable's into Claro's original variables. » Consolidate, merge, and refactor Gin's CSS variable's into Admin theme's original variables.
mherchel’s picture

Assigned: Unassigned » mherchel

godotislate’s picture

Issue tags: +11.4.0 release target
mherchel’s picture

Issue summary: View changes
Status: Active » Needs review

This is in a good place. In fact, way better place (although not perfect). I think this is good to make the theme beta.

mherchel’s picture

Issue summary: View changes
mherchel’s picture

Issue summary: View changes
mherchel’s picture

Issue summary: View changes
StatusFileSize
new89.26 KB

Note that this was accomplished with Claude code and I both doing planning, Claude doing the grunt-work, and me doing testing, cleaning up, etc.

jurgenhaas’s picture

Status: Needs review » Reviewed & tested by the community

I went through almost all pages and couldn't find any regressions. Looks like another great job.

bernardm28’s picture

I just looked into it and not only does it seem to work as well as before, but it solve some small bugs.

For example on:
/admin/structure/menu/link/system.admin_structure/edit?destination=/admin/structure/menu/manage/admin

Before

before code

After

after code image

All that to say this looks ready to go.

mherchel’s picture

Yeah, because of the rush of this (to get into 11.4 as beta), I fixed a few dark mode things.

The fix above was a CSS specificity fix, although the selectors and styles for the toggles are ripe for refactoring.

mherchel’s picture

Assigned: mherchel » Unassigned
dharizza’s picture

Hi team,
I want to note I do see a couple of differences between this branch and main, nothing major but there's things like this:

In this case the icons from the sidebar look bolder than in main:

Before:
Manage fields screen for Articles as it looks like in the main branch

After:
Manage fields screen for Articles as it looks like in this branch. It display icons in bold.

Another case related to the buttons, here the "Delete" button shows the text in blue instead of red.
Before:
Modal for editing a field as it looks like in the main branch

After:
Modal for editing a field as it looks like in this branch

mherchel’s picture

Great catches @dharizza!

Just pushed the fixes. Note that the action link fix is a change to the libraries.yml file. So when testing, be sure to clear the cache.

dharizza’s picture

Perfect! This fixed it! I think in main there was a regression in terms of padding and tabs border but it is now looking good in this branch (just as in the latest version of Gin). Thanks Mike!

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

  • lauriii committed c7c5112e on main
    task: #3599680 Consolidate, merge, and refactor Gin's CSS variable's...

  • lauriii committed 58faa910 on 11.x
    task: #3599680 Consolidate, merge, and refactor Gin's CSS variable's...

  • lauriii committed c3639bbc on 11.4.x
    task: #3599680 Consolidate, merge, and refactor Gin's CSS variable's...
lauriii’s picture

Status: Reviewed & tested by the community » Fixed

Besides the small nit that I pushed as a commit, this looks solid!

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.