There are three major Drupal initiatives that change the markup:
- Mobile and HTML initiatives - CSS clean up #1921610: [Meta] Architect our CSS and #1089868 CSS Cleanup
- Twig initiative - Drupal 8 Twig Sandbox
- Seven theme in D8 - Seven theme Sandbox
Current Issue list:
- #1854346: breadcrumb markup & twig file
- #1912516: menu markup idea
- #1912536: User picture markup
- #1912608: Pagination markup idea
- #1842140: Remove title and wrapper div from theme_item_list
Twig: Completed templates
#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.
#id
If you decide to remove an ID from an element, make sure it's not used, or see if it can be replaced with a class name without killing functionality. #id is still the fastest way to select elements either in CSS or JS, let's not remove them without good cause.
"Good cause" is HTML that won't validate, having two nodes in different view modes on the same page would cause validation failure since there would be two elements with #node-1, so things like node IDs should be removed.
Markup
Keep in mind that one of our principles is to sart from nothing. That means using as few HTML elements as possible in core. If Bartik needs a div around something for it's own purposes, that div tag needs to be added in the Bartik theme, not in core.
However, be very careful removing markup elements. Sometimes wrappers are used in module & theme work, and sometimes CSS is tied to the structure of the HTML elements on the page. Consider suggesting replacements (especially HTML5 tags) instead of using classed divs everywhere.
Headers
For the headers try to keep the meaning of header number (e.g. h1 for page header, h2 for content header, h3 for content sections). Menu title, or breadcrumb titles for example don't fall into that list, so can either have h4/h5 or <span> wrapper. Don't use headers for elements that are by default hidden. For these purposes use span elements. [? needs review by accessibility team]
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).
In the 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 number.
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