Rethinking WordPress Admin

After having tackled customizing wp-admin with happytables, I’ve once again had the opportunity to go through the motions with an exciting project in a new vertical. The good news is that it’s completely doable:

Custom admin look for a new project.
Custom admin work in progress

The bad; it’s time consuming, hacky and leaves a bad taste in your mouth (similar to doing responsive web design in a rush). Both projects have had me wondering what opportunities exist and what sort of barriers of entry could be lowered with regards to how wp-admin is managed.

14,000 Lines

The first challenge and pain point you’ll encounter when trying to change the way wp-admin looks is the amount of CSS you run into. The core wp-admin styling adds up to at least 13,306 lines (14,000 with the random bits that get loaded in too). Considering the language doesn’t require any structure, that’s a LOT of code. What makes it worse, is that an editor viewport will only display the CSS properties for a fraction of elements at any given time (mine shows 50 lines, or 0.4%). This makes it quite hard to get a feeling for the general inheritance and specificity that governs the overall style (especially at 14,000 lines).

Plain CSS is so forgiving and detached that it becomes exponentially harder to manage with size. Now imagine trying to customize wp-admin away from the “one size fits all” approach, to something that actually speaks to the requirements in front of you. It’s mind-numbing. You can stop wp-admin.css from being loaded and throw in your own custom style, but are then in a very bad spot when an update comes around. So you’re left doing a lot of !important, border:none and display:none on an additional CSS layer. Like said, functional, but hacky.

Static CSS

The amount of lines aside, could the admin area ever become responsive? I do believe so, but not with the current CSS. Whilst I’m not advocating a mobile first approach or complete reorganization, some form of drastic measure will be necessary to make it all work. The reasons for this go beyond size, let’s backtrack a little to understand.

Admin in WordPress 1.5 used to be styled through over 500 lines. The overall DOM structure was also far simpler. In short, the CSS was fine as it was then:

WordPress Admin 1.5 – 3D view of DOM structure

Through the versions, the DOM grew and styling was added where necessary. The WordPress UI changed a few times too, getting us here:

WordPress Admin 3.5 – 3D view of DOM structure

Today, a number of elements will have issues such as containing relative positioning (example: top:-3px) or absolute values (example: font-size:14px).  This sort of immobile scaffolding means that in order to go responsive, you’d need to create an equal amount of responsive declarations simply to counter the existing code. That’s hard to justify.

Way Forward for the WordPress Admin

It’s painful to imagine that we would have to wait another 5+ years before the benefits of  CSS preprocessors would make their way into standard CSS. In that time, WordPress will certainly grow further, have new features added and become even more complex. New CSS would just be tacked on to the old, band-aids (top:-3px) would be applied to make things fit and the CSS files would burst the 20,000 line marker. It’s always been easier to gain weight then to build muscle. Trying to lose said weight later on is even worse. We have an opportunity for an easy win here.

In short, a preprocessor needs to replace the current CSS structure. Assuming we use the designer-friendly LESS, there is zero impact in migrating from .css to .less files tomorrow. The files simply need to be renamed (as preprocessors support standard CSS just fine) and best practices need to be established for compiling and minification (compilers exist for OSX, Windows, Linux, etc.). From there, work can be broken down into the following initial passes:

  • Variables & Mixins (1-2 days)
  • Nesting (5-10 days depending on accuracy)
  • File Segregation (1-2 days)

I wish I could have provided smaller and more tangible suggestions (fitting the trac mindset), but the problems are larger than that. The challenge here is also less likely to be one of technology, but rather of culture. The large majority of front-end developers, agencies, startups have all made the switch for reasons relating to productivity, workflow, clarity and so forth. We should too.

Recommended Reading

  • Brian Krogsgard

    I’ve always been afraid to do much customization to the dashboard, because I’ve seen what happens to a custom UI when WordPress has a big UI overhaul (I had some clients using the Fluency Admin plugin pre-WordPress 3.2. It was ugly). You’re brave to take these projects to such an extreme : )

    I think it’d be great to have an easier way to theme the admin and customize it to meet different needs, or verticals. Whether that’s a preprocessor or some other method – anything that can make it easier to theme the dashboard would be great.

    Your recommendations to break the CSS into multiple LESS or SASS files, I think, is a good one. It won’t affect the average user, but will help developers extend the platform. And we could do quite a bit with look and feel, without hours upon hours of painstaking work, just with variables from a preprocessor. Imagine how easy it would be to do the green / blue / whatever admins, then?

  • The tiniest bit of discussion happened pretty recently:

  • Thanks for that Helen. Missed that convo, but seems a bit out there for trac without specific implementation (as correctly pointed out). Not too fussed between Sass & LESS either (LESS certainly doesn’t use some different syntax as incorrectly stated though). My main idea is to make sense of the amount of code we’ve accumulated, so that we can further refactor and find wins in the areas of fluid/responsive design as well as a consistent structure.

  • Agreed on all counts. Nobody is going to deny that wp-admin.css is a giant mess, I don’t think :) There’s a lot of legacy, a lot of hacky workarounds to accommodate either legacy or crazy browser inconsistencies, and even the occasional back-compat. I did a little thinking-out-loud here about the back-compat stuff:

    I would really love if we could identify what’s necessary in order to create a generalized fluid grid for use in the admin, as a part of my larger desire for reusable components and class-based CSS (which I like to think is a shared desire). I think it’d also be good to not make a pre-processor a requirement for that implementation, but definitely point out in what ways specifically it makes it easier.

  • As you can see in the trac ticket, I’ve presented the same concerns and I think the best approach for now is to literally port the existing CSS over to LESS or SASS as a first step. Then in subsequent releases, refactor bits and pieces as they come up. We can, at the very least, organize the CSS into separate pre-processed files and form a game plan for how the files should be structured.

    I think this approach appeases both camps. The pre-processor camp gets to use their precious SASS/LESS variables and whatnot and the “small steps” camp doesn’t have to worry about breaking the entirety of WordPress because we decided to refactor CSS throughout the admin.

    One of the primary arguments @helenyhou:disqus brought up was the fact that it makes it harder for folks to contribute to WordPress that are just recommending quick CSS fixes. I disagree and argue that it actually opens WordPress contribution up to a large-and-growing group of legit front-end developers that are already using CSS pre-processors in their jobs every day.

    Thanks for writing this post as it sheds more light on this issue and I’d love to see something come to fruition in the next couple releases.

  • I have to agree on all of this. I actually have been using SASS for exactly this. It’s a lot easier to refactor smaller defined chunks of code than an entire code base. Also, it is very easy for most to get setup with the processor needed. A minute or 2 for setup on most OS’s.
    I love the idea.
    I am actually rebuilding my base theme with SASS for the same type of reasons.

  • This post appears to present the status quo, then a solution. What’s missing is a breakdown of the problem. And more to the point, I don’t see an explanation of how exactly the solution solves your problem.

    So, what’s the defined problem? Is it just that it is 14,000 lines? What’s wrong with 14,000 lines? Is it that it is difficult to grok and maintain? If were to adopt a preprocessor, how many lines do we expect to eliminate? What’s the goal? Is it 10,000? 5,000? At what point does the weight of a preprocessor outweigh the savings?

    Second, how would a preprocessor solve your problem? A preprocessor might cut down on the number of lines, and might make it more maintainable in core (something I am not sure about), but how does it help a plugin in implementing an admin theme? How does it prevent you from being stuck when there is an update, or from having a bunch of display: none, border: none definitions?

    I just feel like the one thing I am missing is a two-page memo (or something) that clearly explains the reasons why WordPress should switch to a preprocessor, along with a full accounting of costs and benefits — for core contributors, and for plugin developers. I’ve read quite a bit on this subject, and I’m sure the right arguments exist out there, but I’ve yet to see them laid out together.

    Pardon the 20 questions. I’m just prodding to force the best arguments to the surface, so I can understand the big picture, and ideally develop an opinion on it all.

  • but will help developers extend the platform.

    How? I understand how it would be easier to create and maintain core’s colors stylesheets, but I don’t see how it would help with customizing any other aspect of the admin. Could you elaborate?

  • Thanks Nacin, those are all good and valid questions. I think the next step would be for me to put that doc/memo together, which then gives a better understanding of problem, solution, costs, value added, etc. You’re spot on when you say “I’m sure the right arguments exist out there, but I’ve yet to see them laid out together”, let’s see what I can put together, I’d like to help in turning this from theory into practice.

  • Imagine you’re making a custom control based on the style of an existing admin item, you just include the appropriate LESS/SASS file from the admin and use the appropriate mixin. “surprise! major UI overhaul occurs next day”. You rebuild your CSS file from the new dependencies and hey presto you’ve inherited all the new additions. Whereas at the moment one would have to duplicate it all and manually go in and update the parts that need changing else it looks strange…

  • That’s correct Tom, that’s essentially part of the end goal. I think the bigger challenge is conveying the benefits beyond mixins/variables (such as nesting) to the core team; whereby relationships between elements are felt and opportunities are more easily recognizable. For people like us (using a preprocessor), we can race through a project, continually refactoring/optimizing without worrying about bloat whilst always understanding the underlying style guide of the document (even if none is defined). Standard CSS today just isn’t there unfortunately.

  • Franz Josef Kaiser

    Just my 2 cents: My first attempt on making the admin UI styling simpler, was to move the login, lost pass, etc. styling out of the admin style sheets [1]. I still think this should be the first step before doing anything else.
    In my opinion the second step should be an in-depth analysis of the existing elements and pages in the admin UI. After that it shouldn’t be too hard to come up with a set of classes (avoiding IDs completely) that follow a naming guide and treat modules (like in OOCSS) instead of whole pages). This would make maintaining and extending the interface much easier. I strongly recommend to think of preprocessors like SASS or LESS as a last step and instead start thinking of how we could try to move in a parallel, well thought set of classes that serve as a base for a complete rework of the stylesheets.

    [1] (and yes, that one would need an overhaul.)

  • Thanks Franz, those are good comments.I think I have the “reverse” view on your proposed workflow, whereby we move to a preprocessor in order to have a better understanding of our “inventory”. In other words, nest as much as we can, streamline common functions and then from there, do an in-depth analysis of what sort of naming guide and modular structure we can move towards. This opinion is based on the assumption that it’s an easier win to move towards a preprocessor first, then it is to perform an overhaul of the CSS flow.

  • Andrey Savchenko

    I am no front-end wizard but from my perspective there are two core features of preprocessors that make their workflow massive improvement for [large volume of] CSS.

    Variables. Variables make two important things possible – make massive skinning changes by changing them alone (not actual CSS rules) and refer to variables instead of hardcoded values. See Bootstrap for example ( ) you can completely recolor it without touching a line of code and you don’t need to hunt for exact shade or size of anything when you want to use it in your own rules.

    Mixins. Simply put mixins replace massive amounts of re-creation, that tends to happen in CSS, with genuine re-use. Look at current state of style guide for buttons for example – . Recreating WordPress buttons will currently take considerable block of CSS. That block will get instantly out of sync if any single property in core changes. Reducing it to single mixin eliminates all the code, as well as issue of updates.

    This doesn’t make preprocessors some silver bullet, but it is massive and practical improvement to the part of CSS workflow that is historically dead weight on it – copy/paste all the things.

  • So, while I understand how that’s faster for developers, it doesn’t help with the issue of breaking things on upgrades. You and users still have to do updates for plugins/themes, yes? I think the troubles I’ve seen/heard are equally that of how difficult it is to customize the admin and what happens when the admin UI changes (back-compat, basically), so I guess a pre-processor might not help so much with the latter besides making it faster to adapt.

  • There is absolutely nothing current or complete about that style guide, ESPECIALLY buttons. They just got re-done, and not just a little, but completely. In a separate sheet and everything. I know it’s an example, but why would you need to recreate them?

  • I think it depends on the use-case, but lets take some examples. Assuming we segregate variables into variables.less (for colors, font stacks, baselines, etc.). We could easily recompile on an WP upgrade with minimal (if no) changes to variables.less. This, compared to running a diff on wp-admin.css today. A variables.less file is literally a list of variables, i.e. @white: #fff;

    There are further use-cases, but I’ll try and keep it short within the two page memo Nacin mentions above.

  • I guess that’s my understanding – that it still requires recompile/update. Not a bad thing, just want to make sure I understand. Excited for a memo :)

  • Thiago Senna


    is it not possible with just a plugin disable all default admin styles and load your own? Maybe a good start point would be the possibility to easily start a new admin css from scratch and package them as plugin. This will give to the community opportunity to test this ideas, pre-processor, different css structures with SMACSS ou OOCSS, for example.

    Once people start using this plugins (or just re-creating all the css from scratch) we will see what is the facto better solution.

    In my opinion I really don’t like the idea about including css pre-processors in WordPress core. CSS is the standard. Choosing between SASS, LESS or Stylus and force developers to just using this pre-processor is bad, in my humble opinion. Anyway, imagine if suddenly someone launch a new pré processor better than SASS or LESS?

    IMHO, for wp-admin styles, it’s important to follow the standard. Who knows.. and if CSS guys add variables support?

    Thiago Senna

  • Andrey Savchenko

    I just grabbed “Buttons”, could be anything there really. Button is probably too contained component for reuse example (slap on a class in markup, done). The point is – current state of admin is resistant to customization and what customization you do – code rots at alarming speed (constantly pitiful state of style guide kinda proving that :)

    CSS is prone to bloat and while maintaining pure CSS is possible, in my opinion, that is quickly becoming technically inferior approach.

  • Andrey Savchenko

    Just for perspective WP had no problem committing to libraries. SimplePie, jQuery, recently Backbone – just to name a few. It has quite a few library commitments as well as history of changing them (SimplePie replaced earlier Magpie, Prototype was deprecated).

    This is not an argument to go smash preprocessor in core right now, but that choosing and bundling libraries is nothing extreme – just a normal development process for large and multi-faceted project like WP.

  • That’s a good point. Furthermore, the actual end result is still minified CSS with no dependencies, which is not always the case with other libraries/tools.

  • Where’s the best place to curate a list of the modules in admin? Eg. Menu, metaboxes, title, screen options, help sections, post lists, term lists. Github gist?

    Even though I like my preprocessors I agree that the admin CSS needs to be made modular, OOCSS style, before even a preprocessor can help with plugins styling the admin. You have to be careful with preprocessors because even though the source is fewer lines the compiled CSS can end up much bigger than the original vanilla CSS if nesting is over used.

    As a starting point though there’s no harm in getting a preprocessor involved early on to take advantage of variables and basic mixins for simplifying the use of vendor prefixed CSS.

  • Create a github gist maybe? I can add some technical notes based on my experiences writing the wp-less and wp-sass plugins.

  • As a developer who builds products around WordPress I’d appreciate any step in the direction to make customization easier or to have the admin.css broken up in modules/partials at least.

    As someone who relies on the worldwide, well known brand “WordPress”, I don’t like the idea that, if it gets easier, more people / agencies will rollout their own backend design.and dilute the brand over time. Every Themef…Theme will come with it’s own design….don’t think this is desirable.

    my 2 cents..

  • Thiago Senna

    How you said, jQuery, prototype and SimplePie are libraries, while SASS and LESS are not. They are a DSL, a new language that needs to be compiled and are not supported by default in my browser. Learn a new language, how to compile it or what tools are needed to make my life easier with the pre-processor is all bureaucracy that I need to learn before changing admin styles.

    I agree that pre-processors give many benefits to us, but I think that in this case specifically would be better to keep things simple. Adding more modularised/organized styles would be better.

  • Andrey Savchenko

    Are jQuery plugins/code supported in your browser without jQuery library? :)

    On learning curve – two points:

    (1) valid CSS is valid LESS (I am fuzzy on others, since I mostly use LESS so using it as example). I think people imagine preprocessor to be like jumping between distinct programming languages. It’s not – it’s pretty much same CSS plus extras.

    (2) preprocessor workflow is not necessarily more complicated than CSS workflow. What is easier – to point person to change color once in variables file or find and change every instance of it in whole CSS source? What is easier – instruct person how to use one line of mixin or ten lines of horrible CSS, packed full off vendor prefixes?

    In a nutshell as for me preprocessors are not working to replace CSS, they are working to fix its shortcomings. I remember people hacking variables and stuff into CSS (generating through PHP, etc) for about as long as I’ve been online. Preprocessors are just good at it.

  • Franz Josef Kaiser

    This argument shouldn’t be missed. +1