Defining a Drupal 8 markup gate

We encourage users to post events happening in the community to the community events group on https://www.drupal.org.
You are viewing a wiki page. You are welcome to join the group and then edit it. Be bold!

Hi there, design team! :)

Back at DrupalCon Chicago, Dries outlined a strategy for Drupal 8 involving a series of "gates" that would help ensure core code quality in a number of different categories: Documentation, Performance, Accessibility, Usability, and Testing. The purpose of gates is to define essentially a set of "checkboxes" which outline the most important aspects to each category, and does so in a way that is both not overwhelming to core developers (list of hoops to jump through is kept as small as possible) and also creates very little additional burden on the team in question (contains sample links to documentation/resources so developers/reviewers can help themselves).

While markup was not on the "official" list, several people pointed out that there would be a lot of value in defining a checklist for markup, too. I totally agree. So let's doo eet!

Since we have already traditionally had requirements around documentation, it made sense to start there. Jennifer Hodgdon and some other folks from the documentation team have put together the Documentation gate, which is available at http://drupal.org/node/1203498. What we need is a similar table for each of the other gate areas. And that's where you come in! :D

So I'd love to kick off a brain-storm about what the top gates might be (please, no more than 5 if possible), with the goal being to fill out the following table. (This is a wiki page, so be bold!)

Description When is this needed? Details Resources
Always use a semantic element unless there isn't one available and don't use more markup than necessary. Always <div> and <span> should be your last choice for markup. Pick a semantic tag if possible.
Don't over-specify CSS or use ID's as selectors. Modules CSS code that resides in modules should be written in a way that's easily overridable.
Put CSS in the proper file. Modules
module.base.css
Hold structural and behavior related styling. CSS should be coded against the Stark theme. The absolute bare minimum CSS required for the module to function should go here. If there is no CSS required, this file should be omitted.
module.theme.css
Generic design-related styles that could be used with Stark and
other themes would go in this file. It’s where all design assumptions
like backgrounds, borders, colors, fonts, margins, padding, etc, would
go.
module.admin.css
Holds styles that are only applicable to administrative pages.
CSS Cleanup
Start with Stark and cross-browser test. Modules
  1. "Design" markup and CSS for the Stark theme.
  2. If applicable, adapt the styles to match the core themes afterward.
  3. Finally, test the changes in all supported browsers and ensure no regressions are introduced.
Supported browsers
Use existing theme functions. Always Get familiar with the existing theme function, such as theme_mark(), theme_more_link(), theme_date(), theme_container(), etc. Reuse them wherever possible. Default theme implementations

Comments

Well, I can throw some basic

Jeff Burnz's picture

Well, I can throw some basic ideas into the pot to get things rolling:

  1. Adhere to Drupal coding standards
  2. Validate, check with Lint tool
  3. Always use an appropriate semantic element over non-semantic elements (e.g. use em not span, article not div etc)
  4. Don't over specify selectors and never use ID's as styling hooks (e.g. do not do div.class where .class gets the job done)
  5. Never use more markup than is required, avoid excessive redundancy

Just some ideas :)

Thanks!

Jacine's picture

Thanks for getting this started. :)

I think we can combine #1 and #2. Looks good otherwise.

Idk, I think #1 is just the

ericduran's picture

Idk, I think #1 is just the de-facto standard for every drupal patch so we don't need to cover that.

2 I agree with Jacine, its a tool and shouldn't be a requirement for getting a patch in. I mean the css should be clean, but thats should be the same for all code.

So I say #3 to #5 should be in the table. Nice list :)

Here are some more to discuss...

Jacine's picture
  • Ensure that CSS is in the proper file (*.admin.css, etc.)
  • Cross-theme and browser test markup and CSS changes to ensure that you have not caused any unwanted regressions.
  • Don't forget to test for RTL support and add any needed CSS for that as well.
  • Make sure existing theme functions are used for consistency instead of hard-coding markup for things like, theme_mark(), theme_more_link(), theme_date(), theme_container(), etc.
  • If creating a new template or theme function, ensure the wrapper attributes are pluggable using $classes and $attributes where applicable, e.g. doesn't apply to forms.

Just a comment on the Lint

KrisBulman's picture

Just a comment on the Lint thing, i am all for keeping CSS DRY & following coding standards, however I think CSS Lint should not be taken too seriously

see this article:
http://mattwilcox.net/archive/entry/id/1054/

Just a tool...

Jacine's picture

The article you linked misses the point and gets it wrong on a few counts IMO. It's a tool, not a bible to be blindly followed and I think most people get that. The overly specific selectors and ID use all over Drupal's CSS files are the biggest issues IMO, and CSS Lint can help with this.

As much as I think it would be helpful for developers to refer to it as a "tool," I agree that it can't be a hard requirement for a gate like this, at this point, even if the rules are customizable. The validation aspect is part of our coding standards already, so that's why I say combine #1 and #2.

There is an issue to discuss how we use CSS Lint here if you're interested: http://drupal.org/node/1190252.

Wrapping this up....

Jacine's picture

Here's a completely filled in table with the best of both Jeff and my suggestions. If this is okay with everyone, we can wrap this up.

Description When is this needed? Details Resources
Always use a semantic element unless there isn't one available and don't use more markup than necessary. Always <div> and <span> should be your last choice for markup. Pick a semantic tag if possible.
Don't over-specify CSS or use ID's as selectors. Modules CSS code that resides in modules should be written in a way that's easily overridable.
Put CSS in the proper file Modules
module.base.css
Hold structural and behavior related styling. CSS should be coded against the Stark theme. The absolute bare minimum CSS required for the module to function should go here. If there is no CSS required, this file should be omitted.
module.theme.css
Generic design-related styles that could be used with Stark and
other themes would go in this file. It’s where all design assumptions
like backgrounds, borders, colors, fonts, margins, padding, etc, would
go.
module.admin.css
Holds styles that are only applicable to administrative pages.
CSS Cleanup
Start with Stark and cross-browser test Modules
  1. "Design" markup and CSS for the Stark theme.
  2. If applicable, adapt the styles to match the core themes afterward.
  3. Finally, test the changes in all supported browsers and ensure no regressions are introduced.
Supported browsers
Use existing theme functions Always Get familiar with the existing theme function, such as theme_mark(), theme_more_link(), theme_date(), theme_container(), etc. Reuse them wherever possible. Default theme implementations

What's the rationale behind

mason@thecodingdesigner.com's picture

What's the rationale behind always using EM over SPAN, and ARTICLE over DIV? I skimmed the articles and didn't see that argument there.

Unless I'm missing something a better way to phrase that is to "always use a semantic element unless there is none available." I know you mention avoiding extraneous markup (YAY!) but I wouldn't want anyone to just start swapping elements.

Guidelines like these are tough to spell out, I know.

--
d.o: canarymason
twitter @canarymason

Thanks for the feedback!

Jacine's picture

Jeff suggested these in the first comment, and I get what he means. Basically, he's saying: use the right elements for the job and nothing more. I searched around for almost 2 hours last night looking for resources that clearly communicate this, in a way that's helpful, but came up short. There's a lot out there on this topic, but none of it really seems right for this. It's just supposed to be a quick sort of checklist to skim before committing patches to make sure everything is on the up and up.

Are you suggesting this be changed to:

  • Description: Always use a semantic element unless there is none available and don't use more markup than necessary.
  • Details: Use headings appropriately, use lists for navigation, etc.

It's not entirely clear. Personally, I don't think anyone is going to start swapping elements, but I'm happy to completely change this line if you (or someone else) can come up with something that's clear and concise. I agree it's not great right now. We only get 5 lines though, so keep that in mind.

I wouldn't expect anyone to

mason@thecodingdesigner.com's picture

I wouldn't expect anyone to swap elements either, unless we tell them to. That's kind of how that read to me. I think the best end-solution would be to for a site builder to choose semantic elements in many cases once they know the context. But I know that's not what this is.

I didn't realize what the format of the document was, but considering that:

I like this description, as for the Details:

Use headings appropriately, use lists for navigation, use the HEADER and FOOTER elements, Nodes are nearly always ARTICLES

as for resources, I like these:
http://developers.whatwg.org/
http://diveintohtml5.org/semantics.html#new-elements

--
d.o: canarymason
twitter @canarymason

I considered those resources,

Jacine's picture

I considered those resources, but was kinda on the fence because this isn't just about HTML5. We'll likely have most of the say when it comes to major template structure, and this will probably be used for other random smaller parts. I'll add them, but it would be good to get some others that deal with text-level semantics, without actually pointing to the spec itself.

I linked this page, which is pretty outdated: http://drupal.org/node/44072. It would be awesome to see some updates there. There's also these, which got started and never finished:

It'd be great to see some updates there, if anyone is willing to take that on.

BTW, JohnAlbin suggested much better "details" text, which I've added to the table above:

<div> and <span> should be your last choice for markup. Pick a semantic tag if possible.

I'm glad to see movement on

mike stewart's picture

I'm glad to see movement on this and really appreciate the thought that's gone into it. I agree with Mason that it read that way to me too. To the point it caught my attention, and made me wonder what this whole thread was about in my in-box ;-). I suspect it'd read that way even more so for a beginner.

I think Mason's wording on both counts is an improvement. Both are a bit more generally worded, yet still define the goal.

I'm going to think about this more before adding babble to the conversation, but generally would like to see the checklist be even more succinct and with clear references.

--
mike stewart { twitter: @MediaDoneRight | IRC nick: mike stewart }

I updated the table a week or

Jacine's picture

I updated the table a week or so ago, per the comments and feedback I've received in this thread and in IRC. It's all here: http://groups.drupal.org/node/160254#comment-573629

Can you guys please take a look and let me know if it's all good? It would be really nice to wrap this up.

sectioning elements should be used conservatively

jessebeach's picture

The first heuristic to be semantic scares me a little because I can see developers going nuts with this directive. Sectioning elements like section, article, and aside should be used sparingly; divs are perfectly acceptable for creating anonymous divisions intended for styling hooks.

“The section element is not a generic container element. When an element is needed for styling purposes or as a convenience for scripting, authors are encouraged to use the div element instead. A general rule is that the section element is appropriate only if the element’s contents would be listed explicitly in the document’s outline.”

The HTML5 Spec

Stubbornella wrote up a nice discussion of this issue earlier in the week: http://www.stubbornella.org/content/2011/09/06/style-headings-using-html...

So, in the spirit of code is gold, here's what I would suggest as a revision of the first row:

description
Prefer semantic elements; don't use more markup than necessary.

details
Sectioning elements (section, article, and aside) are meant to create a document outline. div and span are still legitimate wrapping elements for non-semantic document structure.

Suggestions welcome.

Looks good to me. I like the

mike stewart's picture

Looks good to me. I like the changes that have been made. issue queue can always be used to handle future changes ;-)

@jessebeach -- I agree some people could go nuts. and maybe I'm missing your point? but I feel the current wording is clear and "always use semantic elements" leads to better structure. Incorrect use of elements (as you point out) is simply incorrect.

--
mike stewart { twitter: @MediaDoneRight | IRC nick: mike stewart }

@mike_stewart, yes yes,

jessebeach's picture

@mike_stewart, yes yes, totally agree. Incorrect use is incorrect (and happy oven is happy!).

My fear is that a directive to always use semantic markup can be interpreted as a command not to use non-semantic markup like div or span. Here's an example conversation:

Themer: "Why are all the wrapping elements in this module's output rendered as section tags?"
Module developer: "You said that I should always use semantic markup. So I did a find/replace and changed all my div tags to section tags."
Themer: "But a section tag isn't semantic in all cases! Sometimes, an element has no semantic value and a div tag is perfectly valid."
Module developer: "Then you shouldn't have said always when you meant when appropriate."

Am I being paranoid here?

It's tough to communicate

Jacine's picture

It's tough to communicate semantics in one sentence for sure. I think that if we say "prefer semantic elements" and then mention section, article, aside, div and span, we sort of bypass all heading and phrasing stuff, which is just as important. I'm not sure how, but the wording could probably be improved, and the word "always" can be removed.

What would be even better though, is to provide real details behind what is being talked about here in the links provided. This page desperately needs updating, but would be a perfect place to put this information: Making your theme semantically correct.

haza! Examples are the best

jessebeach's picture

haza! Examples are the best way to get the point across. You're right, trying to boil down best practice into one sentence and then expect someone to unpack that meaning later is a foolhardy task.

This is fabulous

laura s's picture

One other thing that might be worth mentioning is to be aware of elements that have been redefined in HTML5. Some that might be relevant in some use cases:

  • dl has a broader definition than just definition list.
  • address is not tied to postal address.
  • em has a broader application, and can be nested for added emphasis.
  • strong is now for importance, not emphasis (subtle difference, I know), and also can be nested.
  • i is used for "alternative voice or mood", not italics or emphasis.
  • b is to designate text to be treated different stylistically, but with no implied emphasis.
  • small is for "small print" as in disclaimers, copyrights, etc.
  • hr is for a kind of thematic break between paragraphs, not a horizontal rule.

There are some others, too. How these end up being adopted and embraced as best practices months/years from now, who knows?

I've found one resource on these differences, and several chatty blog posts on it. Anyone know of others? Better ones?

Anyway, I thought this was worth mentioning for the benefit of those who are not as familiar with HTML5 yet.

Laura Scott
PINGV | Strategy • Design • Drupal Development

I agree. I would love it if

Jacine's picture

I agree.

I would love it if someone would take on updating this document, which is currently linked as a resource there: http://drupal.org/node/44072

I moved the table into the OP

Jacine's picture

Since there haven't been anymore responses, I assume this is good for now and I've added the current version to the initial post.

Would this be a useful addition at this point?

ry5n's picture

It seems this thread has gone inactive, but hey, I’m new :)

This flowchart from HTML5doctor may be a useful reference for picking the right element, and it or a tweaked version /could/ be added to make the first checkbox in this Gate specific and objective.