WordPress Custom Admin Color Scheme: Register with wp_admin_css_color() and Set as Default

WordPress ships with nine built-in admin color schemes (Default/Fresh, Light, Modern, Blue, Coffee, Ectoplasm, Midnight, Ocean, Sunrise) that users can select under Users → Profile. Developers can register additional custom color schemes using wp_admin_css_color() — providing a CSS file that defines the colour variables for the scheme, and an array of representative colours shown as swatches in the Profile screen. Custom color schemes are useful for: agency-branded admin panels, accessibility-focused high-contrast variants, dark mode admin themes, and multi-site networks where each site needs a distinct admin identity. The color scheme CSS file must define all relevant CSS custom properties and class-based colour overrides that WordPress admin uses — the simplest approach is to start from an existing scheme’s stylesheet and customise it.

Problem: An agency builds white-label WordPress sites and needs a custom "Brand Dark" admin color scheme with the agency's dark navy and gold palette. The scheme should appear in the Profile color picker with correct swatches, and be set as the default for all new users automatically.

Solution: Register the scheme with wp_admin_css_color() in an admin_init hook, provide a CSS file with the colour overrides, and set it as the default for new users via the user_register hook.

<?php
// ── 1. Register the custom admin color scheme ─────────────────────────
add_action( 'admin_init', function () {
    wp_admin_css_color(
        'brand-dark',                                          // unique slug
        __( 'Brand Dark', 'textdomain' ),                     // display name
        plugin_dir_url( __FILE__ ) . 'css/admin-brand-dark.css', // CSS URL
        [                                                      // swatch colours (4 representative)
            '#0a2342',   // primary background (dark navy)
            '#f5c842',   // accent (gold)
            '#1a3a5c',   // secondary background
            '#ffffff',   // text/icon colour
        ]
    );
} );

// ── 2. Set as default for new user registrations ──────────────────────
add_action( 'user_register', function ( int $user_id ) {
    update_user_meta( $user_id, 'admin_color', 'brand-dark' );
} );

// ── 3. Force the color scheme for ALL users (network-wide) ───────────
// Overrides user's personal selection
add_filter( 'get_user_metadata', function ( $value, int $user_id, string $meta_key ) {
    if ( 'admin_color' === $meta_key ) {
        return [ 'brand-dark' ]; // always return brand-dark
    }
    return $value;
}, 10, 3 );

// ── 4. Remove built-in color schemes you don't want users to see ──────
add_action( 'admin_init', function () {
    global $_wp_admin_css_colors;
    // Remove all built-in schemes except 'fresh' (default) and our brand scheme
    $keep = [ 'fresh', 'brand-dark' ];
    foreach ( array_keys( $_wp_admin_css_colors ?? [] ) as $slug ) {
        if ( ! in_array( $slug, $keep, true ) ) {
            unset( $_wp_admin_css_colors[ $slug ] );
        }
    }
}, 20 ); // priority 20 — after registration at priority 10

/* css/admin-brand-dark.css — minimal custom admin color scheme */
/* Start from wp-admin/css/colors/midnight/colors.css and customise */

:root {
    --wp-admin-theme-color: #f5c842;
    --wp-admin-theme-color-darker-10: #d4a800;
    --wp-admin-theme-color-darker-20: #b38e00;
}

/* Admin menu background */
#adminmenu,
#adminmenuback,
#adminmenuwrap {
    background: #0a2342;
}

/* Menu item text */
#adminmenu a {
    color: #c8d8e8;
}

/* Active/current menu item */
#adminmenu .wp-has-current-submenu .wp-submenu,
#adminmenu .current a.menu-top,
#adminmenu li.wp-has-current-submenu a.wp-has-current-submenu {
    background: #f5c842;
    color: #0a2342;
}

/* Admin bar */
#wpadminbar {
    background: #0a2342;
}

/* Button hover colour */
.wp-core-ui .button-primary {
    background: #f5c842;
    border-color: #d4a800;
    color: #0a2342;
}

NOTE: The CSS file registered with wp_admin_css_color() is loaded in addition to the default admin CSS — it does not replace it. Your colour scheme CSS only needs to override the properties that differ from the base. The get_user_metadata filter approach (forcing a scheme for all users) bypasses each user's personal preference — use this only in controlled environments like agency client sites where brand consistency is required, not on multi-user sites where different people may have accessibility requirements. WordPress stores the selected scheme in the admin_color user meta key — you can set it in bulk with update_metadata('user', 0, 'admin_color', 'brand-dark') (0 = all users) if you want to apply it to existing accounts.