[meta] Creating Dream Markup

Problem/Motivation

Default core markup (aka Stark) is messy. For example, theme_item_list() includes:

  $output = '<div class="item-list">';
  if (isset($title) && $title !== '') {
    $output .= '<h3>' . $title . '</h3>';
  }

which is arguably unnecessary and superfluous. Given that we are converting the entire core markup to Twig in the new theme system, this presents an opportunity to remove things that may not be necessary. Whether Twig makes it into D8 or not, we'd like to see a big clean-up in Stark, and improvement of Bartik.

We've been using the "theme system cleanup" tag to track things like this in general, but this issue could establish some directions and goals for the themes.

Proposed resolution

Goals for core themes: Make Stark as semantic as possible; Make Bartik a better prospective base theme

After some discussion at the 2012 BADCamp Twig Sprint we expressed a desire to have core default markup (i.e. what Stark provides) to be as barebones as possible. Thus, the target audience for using stark would be those themers who truly want to start with a clean slate, and don't wish to have to work backwards to reach that slate.

Accordingly, we'd like to see Bartik become a better prospect for a base theme so that it is easy to start with and build from.

For example, move some of the functionality from theme.inc to Bartik's template.php. Or have stark contain no regions (aside from content) by default.

An amazing inspirational video from mortendk.
http://www.youtube.com/embed/2LwMn9oHOx8

There are three major Drupal initiatives that change the markup:

• Mobile and HTML initiatives - CSS/Architecture clean up #1921610: [Meta] Architect our CSS →
• Twig initiative - all template files in core are now .html.twig files
• Seven theme in D8 - Seven theme Sandbox

Remaining tasks

Needs change notice

• #2011578: Markup for Stark's page.html.twig + maintenance-page.html.twig →

Patches (please review / revise)

• #1982256: Clean up html.html.twig markup →
• 📌 Remove title and wrapper div from item-list.html.twig Needs work
• #2041793: install-page.html.twig markup and CSS →
• #1982256: Clean up html.html.twig markup →
• #1982214: Markup for: theme_breadcrumb() →
• #2004252: node.html.twig template →
• #1982230: Modernize markup for the locale module →
• 📌 Markup for: block module Needs review
• 📌 Markup for: link module Postponed: needs info

TODO (please write patches)

• Assigned to: vollepeer #1912536: Remove all references to the (removed) user-picture.html.twig file →
• #1982202: Markup for: theme_status_messages() →
• #1982220: Markup for: theme_progress_bar() →
• #1912516: Markup for menus →
• #1912608: Update pagination markup for new CSS standards and improved accessibility →
• 📌 Markup for: custom_block module Postponed: needs info
• #1189806: Convert aggregator-item.html.twig to HTML5 →

Discuss (please decide what todo)

• #2099289: Do we need a div around a more link? →
• #2031883: Markup for: comment.html.twig →
• 📌 Replace indentation theme hook/indentation.html.twig with data attributes Closed: outdated
• 📌 Markup for: theme_feed_icon() Closed: outdated
• 📌 Markup for: book module Closed: outdated
• #1982248: Markup for: views/templates/views-view-list.tpl.php →
• #1982270: Markup for: overlay module →
• 📌 details.html.twig should include .description class Active

User interface changes

None, at the moment. Regions may disappear in Stark.

API changes

TBD

Related Issues

#1843798: [meta] Refactor Render API to be OO →
#1804614: [meta] Consolidate similar twig templates and properly use theme suggestions in core →
#1804488: [meta] Introduce a Theme Component Library →
#1499460: [meta] New theme system →
#1087784: Add new theme to Drupal 8.1.x or another minor version →
#1854344: [meta] Goals for core themes: Make Stark as semantic as possible; Make Bartik a better prospective base theme →
#1854672: remove seven_node_add_list() from core (update the markup in theme_node_add_list() instead) →
📌 Remove title and wrapper div from item-list.html.twig Needs work
#912458: Design Initiative: Core theme selection and development process →
#737136: Put together a list of must-have features for new core themes and set a final deadline for implementing them →

#dreammarkup

One of the goals of the Twig initiative is to improve the markup in core. Many contributors are still involved continuing to converting templates to Twig, and now for the completed templates we can begin to improve the markup according to following principles.

Markup principles

Class names

Class name convention is based on CSS architecture (for Drupal 8) documentation. One of the pitfalls of current CSS is that we have something like .menu li a but for the new convention is should be .menu__link. This will reduce the weight of the selector and will make themes cleaner.

The id attribute

It is recommended to avoid the id attribute for styling purposes. Classes should be used instead to apply styles to an element. However, the id attribute is needed for other purposes. In general, avoid removing ids from the markup itself unless you are sure they were only used for CSS.

Markup

Keep in mind that one of our principles is to start from nothing. That means using as few HTML elements and attributes as possible in core. If Bartik needs a div around something for its own purposes, that div tag should be added in the Bartik theme, not in core.

When re-writing markup try to be aware of the repercussions on other code, but don’t let them stop you. See the action steps below for how to deal with changes that affect existing CSS, JS, etc.

Action steps

1. Find a file.

Either choose one of the completed Twig templates (from the list above) that you wish to improve. Search for existing issues tagged "dreammarkup" that pertain to the template file.

2. File an issue (if none exist).

Add your issue to Twig sandbox. In issue summary provide the path to the file, link to this meta issue and a code proposal ( optionally with a patch ) for a better markup. Add dreammarkup tag. Also update this issue summary above with your issue id.

3. Add link to your issue here under 'Issue list' section.

In addition to the tag, this is a good way for us to monitor progress via this meta issue.

4. Write and post a patch.

Mark your issue needs review if you have a patch or idea, or needs work if you need to work on it or it is in progress. Make sure to justify your changes.

5. Check for related CSS and Markup changes.

If (and probably because) markup changes can break all the CSS - check files in which this markup is used, and if possible provide patch for CSS fix specific for your changes. Do not fix spaces or tabs - that is the job of CSS cleanup initiative: #1921610: [Meta] Architect our CSS →