A sandbox have been created for POC https://www.drupal.org/sandbox/cottser/2297653
Drupal themers are a diverse bunch of folks. After completing a survey of themers, we can divide them into 2 camps:
- Want sensible markup with sensible default classes so they can apply CSS with minimal markup overrides. Roughly 2/3 of themers fall in this camp. We will refer to them as the "sensible 2/3".
- Want minimal markup with no default classes so they can add their own classes and override the markup when necessary. Roughly 1/3 of themers fall in this camp. We will refer to them as the "clean 1/3".
The goals and requirements of these 2 groups is difficult to reconcile in a single set of "default templates" that are provided by Drupal core. Currently, we solve for the 2/3 camp and when faced with a tough decision, we should continue to side with that camp. However, it would be very nice if we could cater to both groups.
Additional tangential problems: (that will become relevant when discussing the solution)
All Drupal themers have difficulty in finding the template files in the various places in /core/modules. A previous suggestion was that all template files should be moved to a single directory in core, but that solution had bad DX for module developers.
In Drupal 6/7, we mistakenly advised that all logic should go into preprocess functions and not in template files. This was partly because PHP code in templates is just fugly, but also because we didn't understand that it is perfectly fine to put all design decisions (including "design logic") together into the template file (e.g. the first item in this list has a special design, so we treat it differently.) Due to that mis-step, many themers (across both camps) have difficulty altering the classes added by preprocess functions in order to implement their design.
brief tl;dr description
Create a new core theme (code name "classy") that contains a copy of the all current core template files; this is for the "sensible 2/3" camp. And then modify all of the core/modules template files to contain minimal classes (only those needed for functionality); this would be for the "clean 1/3" camp. To ensure that Seven and Bartik continue to function properly, they should use "classy" as their base theme.
- Move classes out of the preprocess functions into the top of the corresponding twig files. Note: we will not be removing the classes preprocess variables, so modules (like RDF) will still be able to add classes from preprocess if they really need to.
- Make a "classy" base theme.
- Copy all twig files into the new theme.
- Core themes (except Stark) use "classy" for base theme.
- Remove classes (that are not necessary for module functionality) from twig templates in core/modules.
- Any CSS that is orphaned by the removal of classes will need to be moved to "classy". (Note: Yes, CSS files can be attached by "classy" via preprocess and a fugly hack until [ # ???? need issue number from Crell ] lands.)
- Simplify the markup in twig templates in core/modules.
All of this will need to be done by Drupal 8.0-rc1 when we hit "markup freeze". But if we fail to complete the full list, the ones already completed can stand on their own (i.e. we don't have to roll anything back.)
What it solves
- For the first time, the clean 1/3 get catered to (with core/modules), while, at the same time, the sensible 2/3 are catered to (with "classy".)
- Easy to investigate and view both sets of markup. Use "classy" to see its markup and use Stark to see core/modules.
- We finally have a proper base theme in core. (NO, Stark was never a base theme.)
- The "template findability" problem: having the "classy" theme contain a copy of all core/modules templates would give a centralized location for discovery by the sensible 2/3. The docblocks of the "classy" templates would also point at the location of the core/modules original which would help the clean 1/3.
- It's hard to modify classes that are created in a preprocess function. Modifying Twig logic is much easier.
- Even if contrib modules only build "classy" versions of their default templates, having the classes specified in the twig files will make it much easier for the clean 1/3 to clean up those contrib twig files. And vice versa if the contrib module only provides clean 1/3 versions of their templates.
- It makes it easier to implement a theme using the "cool new framework" of the moment. Want a Bootstrap theme? Or an announced-just-this-week Web Starter Kit theme? Either fork "classy" and start tweaking classes or copy twig files from core/modules and start adding classes, which ever fits better with your goals.
- We would have 2 themes in core that basically have no design, Stark and "classy". JohnAlbin would argue that they serve 2 different audiences and front-end developers would understand the dichotomy. Even with "classy" in core, Stark would continue to be a window into what the core/modules provide (which has always been its purpose.) However, if this becomes a show-stopper, "classy" is better to have in core than Stark.
- We would have 2 different versions of every template in core. It does suck a little, but we already have that issue with some template files. For templates in Bartik and Seven, we are already having to remember to edit both the core/themes one and the core/modules one. In fact, we often forget and end up with regressions in core themes. If we add classy, it would actually make it harder to forget; since all templates have a dupe in core/themes, it would become a habit to look in both places when making a change to a twig file.
- Because core/modules and core/themes/classy have different purposes, it will be harder for back-end developers to figure out how to edit any template file in core. Yes, agreed. Which is why a front-end developer should be consulted when editing a template file. Communication, ftw!
@see [meta] phase 2 @todo
User interface changes
New "classy" base theme on the Appearances page.
Little stuff. Like all the markup.