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 |
|
CSS Cleanup |
Start with Stark and cross-browser test. | Modules |
|
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
Well, I can throw some basic ideas into the pot to get things rolling:
Just some ideas :)
Thanks!
Thanks for getting this started. :)
I think we can combine #1 and #2. Looks good otherwise.
Idk, I think #1 is just the
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...
$classes
and$attributes
where applicable, e.g. doesn't apply to forms.Just a comment on the Lint
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...
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....
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.
<div>
and<span>
should be your last choice for markup. Pick a semantic tag if possible.other themes would go in this file. It’s where all design assumptions
like backgrounds, borders, colors, fonts, margins, padding, etc, would
go.
What's the rationale behind
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!
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:
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
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,
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:
I'm glad to see movement on
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
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
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
, andaside
should be used sparingly;div
s are perfectly acceptable for creating anonymous divisions intended for styling hooks.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
, andaside
) are meant to create a document outline.div
andspan
are still legitimate wrapping elements for non-semantic document structure.Suggestions welcome.
Looks good to me. I like the
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,
@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
orspan
. 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 tosection
tags."Themer: "But a
section
tag isn't semantic in all cases! Sometimes, an element has no semantic value and adiv
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
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
andspan
, 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
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
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:
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.
PINGV | Strategy • Design • Drupal Development
I agree. I would love it if
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
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?
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.