Controlling CSS Classes with the Classy Theme in Drupal 8

Note: For up-to-date, detailed information about using the Classy theme and Drupal 8 theming, take a look at our base theme tutorials in the Drupal 8 Theming Guide.

You may have heard some news about the fact that a new theme has been added to Drupal, named Classy. But what kind of theme is it exactly? Is it a pretty new look for Drupal 8? Well, no. You will still see Bartik as the default theme on your Drupal 8 site, so why another theme? Classy is a new base theme in core, which Bartik and Seven will then use as their bases. The idea here is to provide more flexibility to themers when it comes to choosing default CSS classes.

If you download Drupal 8 beta 2, you will indeed see the new Classy folder in the core themes directory. If you open it up though, all you get is an info.yml file. No templates, nothing else. What's the point of that? Well, Classy's info.yml file is just one part in a big change. We're only half way through the story. Let me step back a minute and give a little history for how we got to this place.

The Consensus Banana

At DrupalCon Austin there was a discussion about a big conflict in the Drupal theming world: Drupal's default CSS classes. For a detailed explanation of what decisions came out of that discussion, you can read the [meta] Results of Drupalcon Austin's Consensus Banana issue. In summary, they identified two main camps of attitude about Drupal core classes, and came up with a plan to accommodate both camps. The two camps are, roughly:

• "I love Drupal default classes because it gives me lots of stuff to work with right off the bat, making my job easier."
• "I hate Drupal default classes because they are messy and unnecessary, and they add extra work for me to clean it all up the way I want it."

The way they decided to solve this problem is to make Drupal core classes very clean and minimal going forward, while providing a core base theme that provides more default classes out of the box, if you want them. Classy is the new base theme which is going to provide this.

By the way, what's this have to do with a banana? Well, during the discussion a banana was used as a pointer stick to ask for agreement on points. It became the symbol of getting the group to come to a consensus.

Phase One

In order to implement this change, there are a number of technical things that need to happen. The community decided on a two-phase approach. The first phase requires that all of the class definitions get moved out of the preprocessors and into the template files so that it isn't "baked into" the core code. It moves the classes up into a theme's template files instead. If you look in the core template files (e.g. core/modules/node/templates or core/modules/system/templates) right now, you will notice lines like this at the top of the template code (under the comment which lists the available variables):

{%
set classes = [
    'node',
    'node--type-' ~ node.bundle|clean_class,
    node.isPromoted() ? 'node--promoted',
    node.isSticky() ? 'node--sticky',
    not node.isPublished() ? 'node--unpublished',
    view_mode ? 'node--view-mode-' ~ view_mode|clean_class,
  ]
%}

Not all of the templates have these yet, but the idea is to get them all moved over in phase one. The list of remaining tasks is actually pretty small right now. You can see the full task list and how to help with it in the [meta] Consensus Banana Phase 1, move CSS classes from preprocess to twig templates issue.

Phase Two

So that's great, but where does Classy come in? Well, in phase two of the project, all of those template files are going to get moved into Classy. Classy will be the base theme that provides the most commonly needed default classes. This is why the minimum Classy theme that you see in beta 2 was added. Bartik and Seven will use Classy as their base theme, thereby inheriting Classy's classes. Then those themes can each add and override what they need to be the special snowflakes that they are. You can check out the phase two process in the [meta] Consensus Banana Phase 2, transition templates to the Classy theme issue.

Deciding on Classes for Your Theme

Once all of these classes are in Classy, and not in the preprocess functions you, as a themer, can easily decide if you want Drupal default classes. If you want everything to remain nice and clean, like a blank CSS slate, then you simply ignore Classy. If you want all those default classes to give you a boost, you can use Classy as your base theme, and away you go.

Getting from Point A to Point B

This all leads us back to the initial question of why Classy looks weird right now. This is because we are currently at the later stages of phase one work. Most of the classes have been moved in to template files, but there are still quite a few that remain. Classy is slowly going to grow as the community begins moving the templates into the new theme. You can actually already see this in progress if you look at the latest development version of Drupal 8, instead of beta 2. As you can see there is still a lot of work to do, but it is very clear and well organized, so if this kind of flexibility with CSS classes is something that gets you excited, I recommend hopping on the wagon and helping get the transition completed sooner rather than later.