Change record status: 
Project: 
Introduced in branch: 
8.0.x
Description: 

Themers will be able to choose between two base themes in Drupal 8 core that maintain backwards compatibility.

  • Classy: A base theme that provides default classes that can be used for styling.
  • Stable: A base theme with minimal markup and very few classes.

The Stable theme will function as a backwards compatibility layer for Drupal 8's core markup, CSS and JS. A theme will use Stable as the base theme if no base theme is set in its .info.yml file.

Classy can also be relied on to maintain backwards compatibility throughout the Drupal 8 cycle.

This change allows core markup, CSS and JS to further evolve throughout Drupal 8, while still allowing themes to have a stable base for the clean, minimal markup provided by Drupal 8 core. This is especially useful for front-end developers who would prefer to add in their own classes to markup where needed, rather than remove Drupal's default classes. Front-end framework implementations like Bootstrap or Foundation might find this particularly useful.

A theme can still directly extend core by setting the following key in the .info.yml file:

base theme: false

Themes that do this will need to be continually updated throughout Drupal 8, as core markup can continue to change, which could break a theme with base theme set to false.

Please note that Bartik and Seven are considered internal and can continue to change markup, CSS and JS throughout Drupal 8. Setting Bartik or Seven as a base theme could also result in disruption during the Drupal 8 cycle.

UPDATE:

As of November 11, 2015, all templates and CSS files have been copied to Stable. Library overrides have been put in place to use the CSS provided by Stable. Also, Classy has been changed to use Stable as its base theme.

If you use Twig extends or library overrides based on core modules in your theme you should update those to point to the assets in Stable instead.

Twig extends example:

Before:

{% extends "@block/block.html.twig" %}

After:

{% extends "@stable/block/block.html.twig" %}

Note that @stable just maps to core/themes/stable/templates. If you just use the Twig registry loader ({% extends "block.html.twig" %}) nothing needs to be changed.

Libraries-override example

Before:

  node/drupal.node.preview:
    css:
      theme:
        css/node.preview.css: css/node-preview.css

After:

  node/drupal.node.preview:
    css:
      theme:
        /core/themes/stable/css/node/node.preview.css: css/node-preview.css
Impacts: 
Themers
Updates Done (doc team, etc.)
Online documentation: 
Not done
Theming guide: 
Not done
Module developer documentation: 
Not done
Examples project: 
Not done
Coder Review: 
Not done
Coder Upgrade: 
Not done
Other: 
Other updates done

Comments

thamas’s picture

Could you provide some examples of possible changes which would break a theme without using Stable as base and info how will Stable resolve these problems?

mortendk’s picture

examplate theme a pager:
using "base theme: false" - that means this templates (core/modules/system/pager.html.twig) is the one your relying on.

We have figured out that we never got around to clean that template up, and it spits out all this stuff that is not needed or whatever, it neds to be changed.
the markup you are relying on from pager.html.twig
<nav class="pager">...
your css:

.pager {
  border:1px solid red;
}

Now all classes gets removed from the core templates. the selector ( .pager ) that you were relying on isnt there anymore, and client go apeshit cause the want that red border on the pager.

Had you been using base theme: stable instead (core/themes/templates/pager.html.twig) then the template wont change - your theme wont break when changes are made in core, by using stable or classy as basethemes.

thamas’s picture

Thanks for the example, @mortendk!

askibinski’s picture

Correct me if I'm wrong, but it probably should be noted that until #2575737: Copy templates, CSS, and related assets to Stable and override core libraries' CSS gets done, stable is still an almost empty folder and the behaviour in the example is not functional.

Also, I believe in Mortens example "core/themes/templates/pager.html.twig" then becomes "core/themes/stable/templates/pager.html.twig"

Albert Skibinski - ezCompany