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:

Remaining tasks

Needs change notice

Patches (please review / revise)

TODO (please write patches)

Discuss (please decide what todo)

User interface changes

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

API changes

TBD

#1843798: [meta] Refactor Render API to be OO
#1804614: [meta] Consolidate theme functions 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 9
#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)
#1842140: Remove title and wrapper div from theme_item_list
#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

Comments

Issue summary:View changes

links fixed.

Issue summary:View changes

Steps added

Issue summary:View changes

markup change

Issue summary:View changes

code fix.

Issue tags:+theme system cleanup

Tagging

Issue summary:View changes

Twig templates section added

Issue summary:View changes

twig rtbc link added.

Issue summary:View changes

Twig templates meta issue link added

Issue summary:View changes

markup changed :) it's a markup issue.

Issue summary:View changes

Formatting

Issue summary:View changes

Clarify

Issue summary:View changes

Issue list items added.

Issue summary:View changes

markup fix.

Issue summary:View changes

expand

#id is still the fastest way to select elements either in CSS or JS, let's not remove them without good cause.

The CSS coding standards advises never using id as a CSS hook. The performance difference between id and class is basically nonexistent, and selector performance in general is near the bottom of the list of bang-for-buck performance optimisations. I’d like to stick to the new CSS standards and use single classes as much as possible.

The example given of the new selector style is not great: .menu__list-item__link. A better replacement for the original selector .menu li a would be .menu__link. I need to add some clarifications to the standards based on what I’ve learned in the sandbox, but my rule of thumb is to make a class name only as ’ugly’ as needed for clarity. Class names do not need to encode markup structure, they only need to name things unambiguously. In general, prefer .menu__link over .menu__item__link.

Don't use headers for elements that are by default hidden

I believe many of the hidden headings in use by Drupal are there for accessibility reasons, which means the heading tags supply import semantic information to screen readers. I would hesitate to change this pattern unless we get the OK from our accessibility team.

BTW +100 to this issue. Thanks @oresh for creating it.

Issue summary:View changes

item list

Thanks ry5n! I've changed the description.
I was thinking that the class name was kinda ugly, but decided to stick to DOM structure. Your variant is cleaner and more readable.
I'll try to post an article about this issue to Drupal planet - hope to get some more attention to it.
While 'more back-end' front-end developers are involved in Twig initiative, we should try to make the Markup in parallel asap if we want it to be in core until the release.

Issue summary:View changes

Changed class names.

Fantastic. Thanks @oresh. I’ll be working on this again too and giving it everything I’ve got.

Just a quick note: please, do not remove any hidden content from the markup.

Anything wrapped in a div/span/heading which the "element-invisible" class is assigned to is there to improve Drupal pages acessibility. Unfortunately I am in a hurry right now, but I'll provide more detailed feedback as soon as possible.

What @falcon3 said, but also not changing the tag either. Basically we should not touch that screen-reader markup except with a firm understanding of the a11y implications.

About the ‘start from nothing’ principle: this is really important. However, it applies most to core markup, i.e. the markup coming out of core modules and libraries, and of course the Stark theme, since it is designed to simply present raw core output. However, base themes (if ever in core) might want/need to provide additional markup/CSS/JS to fulfill their goals as something more convenient to build on. Finally, purpose-built core themes such as Seven will need to do the most building-up from the lean base markup envisioned for core modules.

My point is that not all core markup should be stripped down to ’nothing’. The more generic and extensible the markup needs to be, the more basic and clean. The more specific, the more it should simply be well-architected for that purpose.

Issue summary:View changes

grammatical error fix.

Issue summary:View changes

Fixed a minor typo.

Issue summary:View changes

video

Issue summary:View changes

video ifrmae

Issue summary:View changes

image instead of iframe

Issue summary:View changes

ohhh those images :(

Issue summary:View changes

Attribution

Issue summary:View changes

new list added.

Issue summary:View changes

Added new issues.

Issue summary:View changes

steps improved.

Issue summary:View changes

link fixed.

Upon visitting #1843774: Convert views/views_ui/templates/views-ui-display-tab-setting.tpl.php to Twig I noticed the usage of non-breaking space without any explicit reason for it. Grepping for nbsp showed up quite a few uses, including form.inc and theme.inc (not to mention js plugins and vendored PHP). Shouldn't we think about nbsp usage? What is the rationale to add it or avoid it?

On the invisible headers topic: it builds the document layout which is quite important for accessibility and semantics. See http://www.netmagazine.com/features/truth-about-structuring-html5-page for more on it.

Also, when it comes to clashing element ids, we can always use drupal_html_id to avoid the clashes... althought I'm not sure what's the use of an id attribute if you can't rely on its value. Maybe for javascript behaviors, passing the generated id as a setting -- although I didn't see that pattern around.

Issue summary:View changes

user name fail

@barraponto, thanks for the review. the article is just amazing.
I've removed the 'header' section, cause I don't find it necessary at all now.

About the ID's - they are used by JavaScript, and sometimes by CSS (yep, sometimes it is).
Secondly i like to keep the representation of unique elements on the page by their id attribute, so you can define - 'ok, this element should only be used once', or something like that. Anyway leaving or deleting ID is not critic for most of the time, so we provide them by default, but themers decide themselves to use or not the id :)

Issue summary:View changes

removing header section

Issue summary:View changes

Update instruction sections for id and markup to clarify stance on ids (their purpose, when to remove, recommendation to not use in CSS). Corrected some punctuation and typos.

Issue summary:View changes

add link to node markup

We discussed our approach for each one of these issues. We think we can commit each patch separately, without sandboxing.

  1. Improve the theme function markup
  2. Check Seven and Bartik to see if the reduced markup breaks either theme
  3. Move the old theme functions and template into the broken themes so we don't have the change the CSS right now.

I created #1854344: [meta] Goals for core themes: Make Stark as semantic as possible; Make Bartik a better prospective base theme before we started talking about dreammarkup; it's possible that it may be a duplicate and we should combine these. Thoughts?

Issue summary:View changes

wrong issue # for node.html.twig

@c4rl We should probably merge them. I think #1854344: [meta] Goals for core themes: Make Stark as semantic as possible; Make Bartik a better prospective base theme has a really good overview of the goals. This issue is more focused on the particulars of implementation. Should this one be made a sub-issue of that? Or should Dream Markup be a sub-section in 1854344?

Issue summary:View changes

add related issues

Issue summary:View changes

added link to page.html.twig

@c4rl these issues look to like duplicates to me. I think combining them makes sense.

Issue summary:View changes

Remove link to Twig sandbox now that the templates are in core :)

Issue summary:View changes

Issue summary:View changes

related issues too

Since there are already a bunch of people following this issue, I closed #1854344: [meta] Goals for core themes: Make Stark as semantic as possible; Make Bartik a better prospective base theme as dupe.

I did also move over the summary, so everything we need should be here now. :)

Issue summary:View changes

add title

Issue summary:View changes

comment

Issue summary:View changes

meter, ha

Issue summary:View changes

Remove dupe breadcrumb issue

Issue summary:View changes

added in links to proposed patches

Issue summary:View changes

added more issues

Issue summary:View changes

up

Issue summary:View changes

up

Issue summary:View changes

up

Issue summary:View changes

up

Issue summary:View changes

update

Issue summary:View changes

up

Issue summary:View changes

more

Issue summary:View changes

more link

Issue summary:View changes

dedupe

Issue summary:View changes

up

Issue summary:View changes

Updated issue summary.

Issue summary:View changes