README

A dark mode theme for the Magento 2 admin panel with a companion toggle module.

Status: v0.8.0 — functional, community collaboration welcome. Core palette coverage is solid and WCAG 2.1 AA-validated. Several areas remain incomplete; see Known Issues below.

What it is

AdminDark recolors the Magento 2 admin panel using a carefully tuned dark palette. It is implemented as a LESS-based child theme of Magento/backend, compiled into a single styles-dark.css stylesheet.

The companion module AdminDark_Toggle injects a sun/moon button into the admin header. Clicking it dynamically swaps stylesheets and persists the preference to localStorage. The active Magento admin theme remains Magento/backend — AdminDark's stylesheet is loaded as a second layer that overrides colors only, so Magento routing, layout, and JavaScript are unaffected.

What the palette covers

• Page structure: header rail, sidebar nav, footer
• Data grids: headers, row striping, hover states, loading mask
• Form fields: inputs, selects, textareas, checkboxes, multiselects
• Modal dialogs and overlay panels
• System messages and admin notifications
• Product image gallery cards and role labels
• Customizable Options and dynamic-row accordions
• System → Configuration left sidebar and section accordions
• Category tree (jstree), including connector lines and node icons
• Dashboard store-stats tabs

The palette uses WCAG 2.1 contrast ratios validated across all text and background token pairs. A Python script (scripts/palette-contrast.py) regenerates the full matrix after palette changes.

Installation

Requirements

• Magento 2.4.x CE or EE
• PHP 8.1+
• Composer 2.x

Install

composer require icon-gallery/magento2-admin-dark:^0.8
bin/magento module:enable AdminDark_Toggle
bin/magento setup:upgrade
bin/magento setup:di:compile
bin/magento setup:static-content:deploy adminhtml

Activate the theme

1. Log in to the Magento admin
2. Go to Content → Design → Configuration
3. Edit the Admin row
4. Set Applied Theme to AdminDark
5. Save

The toggle button (moon icon) appears in the admin header. Clicking it switches to dark mode; clicking again switches back. Preference persists across sessions via localStorage.

Note: The theme must be the active admin theme for styles-dark.css to exist at the path the toggle script expects. Running setup:static-content:deploy adminhtml with a different active theme will not compile AdminDark's LESS.

Disable the toggle without uninstalling

bin/magento module:disable AdminDark_Toggle
bin/magento cache:flush

How it works

Theme (LESS)

AdminDark is a child theme of Magento/backend. Its single LESS entry point (web/css/styles-dark.less):

1. Imports Magento's standard admin LESS stack via theme inheritance
2. Overrides LESS variables in web/css/source/_theme.less (the palette layer)
3. Imports selector-level carve-outs from web/css/source/_dark-overrides.less for cases where Magento's source uses literal color values rather than remappable variables

Magento's LESS lazy-loading ensures variable redefinitions flow through all inherited rules at compile time. Each carve-out rule includes a specificity and cascade audit comment explaining why it cannot be expressed as a variable override.

Toggle module

AdminDark_Toggle loads dark-mode.js on every admin page via layout XML. The script:

1. Reads localStorage for the saved preference (admindark_mode)
2. Injects a <link> for styles-dark.css, deriving the URL from existing admin stylesheet <link> tags (inherits CDN prefix and cache-bust segments automatically)
3. Inserts a sun/moon <button> next to the admin notification bell
4. Persists the preference on click

Palette tool

python3 scripts/palette-contrast.py

Prints the WCAG 2.1 contrast matrix for all text and accent tokens against all background tokens. Update the hex values in the script to match _theme.less after any palette change, then paste the output into the matrix block at the top of _theme.less.

Known issues

1. Flash of Unstyled Content (FOUC)

Dark-mode users see a brief flash of the light theme (~50–100 ms) on each page load before dark-mode.js fires and swaps stylesheets.

Root cause: The stylesheet is injected at DOMContentLoaded, after the browser has already parsed and applied the light-mode CSS.

Fix (not yet implemented): An inline <script> in <head> that synchronously reads localStorage and injects the dark <link> before any CSS parses. AdminDark_Toggle is the right place for this — it needs a layout XML block that emits an inline script in the admin <head>.

2. Uncatalogued styling gaps (~6 areas)

Approximately six pages or components were identified in testing where dark mode is not correctly applied. These were not formally catalogued before this release.

If you encounter a page that renders incorrectly in dark mode, please open an issue with a screenshot and the admin URL.

Contributing

Issues and pull requests are welcome. Priority areas:

• FOUC fix — inline <script> in <head> via AdminDark_Toggle layout XML
• Styling gaps — open an issue for any page that does not render correctly (screenshot + admin URL)
• Pre-compiled CSS — ship a pre-built styles-dark.css so installation does not require setup:static-content:deploy
• Magento version coverage — tested on 2.4.9 CE / PHP 8.3 only

License

MIT