WordPress Style Guide

When working on custom solutions for others – be it for themes, plugins, or some other extension for WordPress – one of the things I think is important is to make sure the Dashboard has the same look and feel as the rest of the native components of WordPress.

That is, I dislike and I disagree when developers and designers deviate from the core WordPress look and feel.

But even for those who try to adhere to using the right elements in the right place and for those who try to stick with laying out dashboard pages using the natural patterns as defined by WordPress, is our best place of reference actually using other pages that exist throughout the dashboard?

When it comes to so many other things – that is, in the field of software or not – there are normally patterns we follow to help make our lives easier. It’s not that they are an attempt do “dumb down” anything or take the originality away from us.

Instead, they are meant to help guide us on principles that have been tried, true, and proven in the context of whatever industry we’re talking about. And the same can be said for the WordPress user interface.

The WordPress Style Guide

Specifically, check out the WordPress Style Guide (also called the WordPress Admin Pattern Library).

WordPress Style Guide

From the GitHub repository:

This is a plugin that is meant to serve as a development ground for WordPress admin UI components, such as one might find in front end development frameworks such as Twitter Bootstrap or Zurb Foundation.

It’s admittedly incomplete, but once you’ve installed it in your development version of WordPress, you’ll find it has most the stuff you may want when creating dashboard pages, parts of dashboard pages, or just adding new UI components to an existing page.

But how does it work? Easy – since it’s a plugin, it creates a new menu item along the dashboard menu that contains subpages for various elements that go into making up part of the WordPress admin experience.

Specifically, it provides examples for jQuery UI components, for forms, for helper classes (as in class attributes, not object-oriented classes) and so on.

Anyway, if you’re a WordPress developer and find yourself often creating dashboard pages for your users and/or clients, then I recommend this plugin:

  • it’s a reference that lives within the Dashboard itself
  • it’s easy to look at the code via an inspector
  • and it’s easy to implement the results in your own work

If we had more developers following these types of guidelines, perhaps third-party plugins and tools wouldn’t feel so terribly disjointed from the rest of the core application.

But I digress.

Category:
Resources
Tags:

Join the conversation! 12 Comments

  1. It seems a bit out of date for a reference. It recommends mp6 classes which don’t appear to be used in the admin area. I suppose these were in use during the new UI feature-plugin’s development phase. The jQueryUI page is broken. So there’s only some basic form elements to go on.

    It’s a great idea. I wonder if Helen is still interested in pushing forward with it. I could probably create a few PRs, but I think she’s wrangling the admin CSS code at the moment, so it will probably see some fluctuation over the next few versions.

    • It seems a bit out of date for a reference. It recommends mp6 classes which don’t appear to be used in the admin area.

      Sure, sure. But that doesn’t mean we can’t use the inspector tools to look at similar elements in the admin to see what classes they’re using now.

      We can also issue pull requests, though I know we’re all busy with our own work right now, too ;).

      The jQueryUI page is broken. So there’s only some basic form elements to go on.

      Not completely – I’ve had some success with getting certain elements working fine; however, I’m more concerned with things like form fields and the like.

      Regardless, these are all important points that I’m glad you’ve raised. There’s certainly improvements that can be made, but this definitely improves on not having anything at all, IMHO.

  2. Totally agree with how important this kind of thing is – always hate using plugins that have their own custom UI elements that just don’t match up with WP at all.

    There’s a very similar plugin for this that has been around for some time that I’ve been using: https://github.com/bueltge/WordPress-Admin-Style – looks like it’s effectively the same kind of thing and it’s been super useful over the last few years.

  3. I know this might be slightly off the topic of what you wrote about but what is your take on this in regard to WordPress as an app?

    I learned about Pickle and Aesop story engine from here and they don’t use the dashboard but (from what I can see) they seem to follow the guidelines of the customizer. Do you think people that go that route can or should be able to customize outside of the normal look and feel of WordPress?

    • I know this might be slightly off the topic of what you wrote about but what is your take on this in regard to WordPress as an app?

      WordPress is an app – that’s why I consider it an application foundation rather than an application framework.

      And I see the style guide here as being something strictly related to those tools that are being built for WordPress. Anything being built as an app on top of it may follow different guidelines (though I’d argue they need some type of style guide).

      I learned about Pickle and Aesop story engine from here Both of which are really neat implementations of their respective ideas.

      and they don’t use the dashboard but (from what I can see) they seem to follow the guidelines of the customizer.

      I’ve written a good bit about the customizer and my opinions are pretty strong about it :).

      Do you think people that go that route can or should be able to customize outside of the normal look and feel of WordPress?

      Depends on what you’re aiming to build :). If it’s a theme, plugin, or something of the like, then stick with the style guide; otherwise, you may go elsewhere.

  4. Totally agree with these points. Whenever i see a plugin or a theme using a custom ui that doesn’t fit within the WP UI, I skip it straight away.

    • Whenever i see a plugin or a theme using a custom ui that doesn’t fit within the WP UI, I skip it straight away.

      Personally, I’m not that legalistic about it. Sure, I wish the UI looked different, but if it offers functionality that I’d really like or really need then I’m willing to deal with it for the sake of the end result :).

  5. I agree.. and disagree.

    I agree on the point that the UI should use the WordPress look and feel. This is to maintain consistency. There is nothing worse then getting to a plugin admin screen and then thinking… what now!?

    WordPress has a lot of styling built in. As a developer it’s fantastic to tap into this and make my plugins look clean and neat. But these styles are built with purpose. Particularly WordPress’ UI.

    And this is where I disagree. When making a plugin that extends WordPress functionality, these styles are not always enough since they were built for what the admin already has. The very nature of plugins is to extend. And I think this is also true to styling. Just as a plugin needs to confirm to how WordPress works, but extend functionality, so to should the UI. My form builder has a drag and drop grid builder. WordPress doesn’t have any styling for a drag and drop grid, but it does have a styles for panels. you can see these in metaboxes, media library and all over the place. I took these design styles and used them for the columns within a grid. So its using the style only extending it to elements that don’t exist.

    At the end of the day, The UI of your plugin should look like it belongs in WordPress, not a window into another world. I have seen some plugins that pull in Bootstrap for everything (and the default theme at that!). The clash is enough to make my eyes bleed.

    Using WordPress styles “as is” to achieve something it was not built for can make the UI harder to use rather than easier.

    If you’re going to make a custom UI, keep the paradigm but enhance and progress. not ignore and reinvent.

    • I agree on the point that the UI should use the WordPress look and feel. This is to maintain consistency. There is nothing worse then getting to a plugin admin screen and then thinking… what now!?

      Definitely. 

      Just as a plugin needs to confirm to how WordPress works, but extend functionality, so to should the UI.

      I think this would make for a good talk or a good discussion. I mean, we only have a finite set of elements with which to work and using them to represent our data is key.

      Each type is intended to represent something or to afford some type of functionality. Personally, I don’t think we should deviate too far from that. 

      So its using the style only extending it to elements that don’t exist.

      A good strategy :).

      I have seen some plugins that pull in Bootstrap for everything (and the default theme at that!).

      :(

      If you’re going to make a custom UI, keep the paradigm but enhance and progress. not ignore and reinvent.

      On point.

Leave a Reply

This site uses Akismet to reduce spam. Learn how your comment data is processed.