[policy] Finally agree on CSS coding standards

Thanks for filing the issue John! (That was me-Jen, not one of many other Jen people in the Drupal project.)

These will only apply to D8 since they involve rewriting the CSS:

CSS architecture (selector guidelines) http://drupal.org/node/1887918

CSS grouping (file and aggregation guidelines) http://drupal.org/node/1887922

edit: Woooooooo!! Let's get this in!

Add note about coder.module.

I'm ready to have this be a reality!

Update issue summary

This looks pretty solid all over - rtbs & stfu ;)

I like this. It fits with what much of the non-Drupal front-end community does.
I didn't like the "draft" from four years ago. Which is why Bartik didn't follow it.
Many Drupal front-end developers didn't like it. Which is why it never came out of draft.
Thanks John for keeping on this, and making progress. This is good.

Let's do this thing! :D

Added Jen Hodgdon's surname to the 'summary-problem-motivation' section

I added an issue to the Coder module's queue: http://drupal.org/node/1922066, which should take care of task #5.

Explain what to do to old page.

I'd like to have a more in-depth look at the proposed draft.

Are the changes compared to now outlined somewhere? I.e.:

1) Compared to our current CSS coding standards

2) Compared to existing proposals that went through more elaborate discussion already?

In general, I'd really prefer to move in smaller steps (like #1270218: [policy] CSS coding standards: Vertical spacing between selectors), because it is very hard to review + discuss + agree on a full-blown proposal.

RE #10/11: +1000 on the process used for this update. It was well-publicized, well thought out, and carefully executed (and it also respected our old process by filing this issue so that people who follow the "coding standards" tag could take notice). The existing "process" for coding standards is broken (especially, as noted in #11, for big changes), and until we have another policy/process for coding standards, and/or a working committee to govern them, I think this worked very well. It obviously had way more participation that we ever get on coding standards issues.

+1 to the new draft and -1000 to splitting this out into a bunch of tiny micro issues to discuss each point ad nauseam.

JohnAlbin knows about my reservations in the proposed standards. I'm not so reserved about these issues that I would prefer no standard at all to more debate. Having a standard at least means we have something we can revision over time, which of course will happen as practice evolves with the underlying technology.

Everyone's going to have a few things to nitpick. It's easier to nitpick in small chunks than to continue to hash out details without a whole to ground the discussion.

John has really thought this proposal through. He's sought input from numerous channels over a long period of time. He's done his best to incorporate feedback from many, many sources.

I may be personally cranky about a few of the changes, but I'll get over it with time and experience.

Let's set this back to RTBC, get something solid under our feet and some calluses on our fingers putting it into action. That, more than anything, will let us know if the proposal works.

I’ve re-read the three parts of the new standards, and I’m getting excited all over again. I really think they are a step forward. It’s true that we’ll need to keep re-evaluating them, especially the Architecture and Grouping parts, as we apply them to Drupal 8 (and longer-term, as best practices evolve). That said, I am happy to support RTBC-ing this as our official CSS standards.

the css standards that have been worked out by john albin and others involved in the effort are really up-to-date with what i conceive to be frontend development best-practices established in the wider web communities from the conversations that i'm following.

i understand sun's #10 reasoning, that working on smaller steps is easier. but as explained in the following comments, i think the standards play out their strength in their entirety. splitting them up into separate junks could be a show-stopper for what i conceive as a very positive momentum amongst front-end developers regarding drupal core (this feeling might also be related to Proposal: A Style Guide for Seven and all the work around twig:) ).

i therefore share the excitement and am really eager to see how they are put into practice.

Okay, so what's the next step here? Just remove the "Draft" label and start using them?

Finally had a minute to look over the pages. Overall, this looks good. A few issues though:

All pages:

1. The pages should be rewritten to use RFC/web standards specification language everywhere; i.e., MUST, SHOULD, MAY, MUST NOT, SHOULD NOT, MAY NOT, etc. (in uppercase letters)
2. Some chapters start with elaborate explanations or do-not-do-this, instead of a summary of do-this / what to do. The commanding summary should always come first, ideally including code snippet/example. Elaborate explanations only after.

Formatting guidelines

1. The chapter about "Section comments" should be removed. The exemplary coding style in there violates Drupal coding standards on all fronts. There's a dedicated issue that discusses possible coding standards for groups/sections.
2. The first two sections in 3. Format (Rulesets and Properties) should have an example code snippet, each.
3. The third section in 3. Format (Blank lines) duplicates the entire main chapter 1. Whitespace. It should be moved and merged entirely into that first chapter.
4. 3. Format: "Declaration order": The initial comment about previously/formerly existing guidelines should be removed.
5. The exception on multiple vendor-prefixed properties should be removed. Vertical alignment is known to fail in the long run, to produce unnecessary large diffs, and to defunct git blame.
6. Neither CSS code nor documentation text should use backticks (`) anywhere. Always use single-quotes (').
7. Instead of numbered chapter headings, the headings should be jump targets, and there should be a TOC at the top of the page.

Architecture

1. Variant classes should use a single hyphen to separate the variant name from the base class.
2. Elements within a component ("sub-components") should use a single underscore.
3. Further comments here: #1921610: [Meta] Architect our CSS

File organization

1. No concrete issues here, but I am quite a bit concerned that the proposed aggregation and component-izing changes may not account for D8's architecture and rendering pipeline. I almost fear that we'll have to unconditionally load dozens of separate CSS files, which aren't aggregated, since the aggregates contain too many varying/request-specific files. I wonder whether these changes were sufficiently discussed from an architectural + technical perspective...?

I removed backticks (`) from all docs as per comment #19, and replaced them with single quotes (').

I disagree with removing -- and __ from variants and sub-components as stated in Architecture 1. & 2., they help to clearly set them apart when visually scanning a document.

The usefulness of double hyphens and underscores has been touched on thoroughly elsewhere, so I don't feel I have to re-hash their importance here:
http://nicolasgallagher.com/about-html-semantics-front-end-architecture/
http://csswizardry.com/2013/01/mindbemding-getting-your-head-round-bem-s...

@sun It would have been great to get your feedback earlier on this. John timeboxed this so we could move on it. Marking back to RTBC, we can still improve the docs even as they are official.

Can you explain or link to why aligning the values of vendor-prefixed properties leads to version control trouble? In all other respects it is a win for development, so I want to understand the drawbacks.

I strongly concur with #20. Double hyphens distinguish between a component name like 'button-group' and variant like 'button--primary'. Double underscores simply follow that pattern.

@JohnAlbin moved the draft into actual/official handbook pages already, so RTBC seems wrong, and I think needs review for the concerns I've outlined in #19 is most appropriate.

1. re: #20:
   The concrete examples that are showcased in the coding standards pages are showing button--primary selectors. However, exactly that specific example cannot be found in any front-end framework.

   Perhaps it's merely the example that is wrong? — That said, that example clearly is a variant.

2. Speaking of "button" — the current coding standards page does not clearly state yet that abbreviations/acronyms are discouraged; e.g. as in this concrete case, "btn" vs. "button".

3. Lastly, I forgot to mention that I'm also very concerned about using a custom CSS class {prefix} for Modernizr.

   That library has emerged into a standard tool over the past years, and you can easily find soft-to-hard dependencies in all kind of other CSS/JS front-end libraries across the board. Therefore, I do not see why using custom prefixes is a good idea in any way.

   That's a typical case of library adoption vs. Drupalism/pedantic-purity. The gains of just using the defaults (like everyone else) have a true impact on more than just Drupal-specific code. We should stick to the defaults.

That said,

4. The code examples for sub__components are too abstract to make sense of. Do we really have no single example case for that in core already that people can relate to?

   If not, can we think of any trivial no-brainer case/issue that we can quickly convert?

@sun I’m happy with ‘needs review’.

- I agree we should add the no-abbreviations recommendation
- The modernizr prefix is a good idea in theory (disambiguation), but in practice may cause issues with external libraries as you point out. I'd like to discus it further.
- The -- and __ naming conventions are from BEM.

A week or so ago I built a demo/proof-of-concept for the new CSS Architecture standards, which is rough but should provide a more complete example.

CSS Architecture Proof-of-Concept:

Demo
Code (Github)

The -- and __ naming conventions are from BEM.

Thanks for pointing me to a Google Search result. According to those results, that claim is straight-out wrong though.

BEM introduces the double-underscore syntax for sub-components, but uses single hyphens even in its very own examples of elements/components that seemingly look like "variants."

Consequently, someone of us seems to have a pushed forward the double-underscore pattern much further into a space it was not intended for. Quite potentially to achieve artificial consistency.

This looks wrong to me. I'm happy to be convinced otherwise, but so far, I do not see any kind of evidence that double-hyphens for variants are used by anyone anywhere on this planet**.

** Obviously excluding Drupal's very own machine-based HTML ID/class generator functions, which .happen--to---produce-----weird-stuff----at-times.

@sun You are correct about BEM not being the originator of the double-dash notation: for some reason I was not aware of that. It seems that Nicolas Gallagher modified them, which is where I learned about the idea. So, two things:

1. regardless of wether this a well-know pattern (yet), I would argue it is objectively better to disambiguate our selectors if we are going to embrace the conceptual distinction (which I think we should) between a component and a variant.
2. the double-dash notation *is* a real thing. These are the sources quoted in the new standards and the ones I am familiar with

Nicolas Gallagher’s article: http://nicolasgallagher.com/about-html-semantics-front-end-architecture/
…and his framework (early stages): https://github.com/necolas/suit

Harry Roberts: http://csswizardry.com/2013/01/mindbemding-getting-your-head-round-bem-s...
…and his framework, which he wants to move to this notation: https://gist.github.com/csswizardry/3822990

Philip Walton: http://engineering.appfolio.com/2012/11/16/css-architecture/

And, this from just 4 hours ago :) : https://twitter.com/stubbornella/status/305094843464568832

I agree with @sun about the examples being less than perfect. Maybe a good way to test some theories is with some actual Drupal markup that we can consider being a "component" with some variations and sub-components as @sun suggests. Also the point about Drupal's class generator functions .producing-weird--stuff-----at-times is a good one, although perhaps that will need to be a separate issue once these new coding standards are committed.

I don't have the time at the moment to search for some exquisite example of Drupal markup to use for this, but I understand where @ry5n and @KrisBulman are coming from. So here's a completely made-up one, that for various reasons, probably shouldn't be real. Please don't judge me for this :P

.form-item {}
.form-item__password {}
.form-item__password--visible-text {}
.form-item__email {}
/* maybe something like this makes sense too though */
.form-item--text__password {}

The idea there being:

.component-name {}
.component-name--variant {}
.component-name--variant__sub-thing {}
.component-name--variant__sub-thing--variant-of-subthing {}

If that (admittedly poor) example doesn't make sense, then maybe I could use more clarification on the actual usage we might get out of this naming pattern within Drupal as well, or maybe a better example is needed (I didn't try very hard). Something else to consider is that if it turns out that this pattern doesn't work for Drupal, we probably shouldn't try to force it to. As much as I respect Harry Roberts, Nicholas Gallagher, et al -- they aren't mystical front-end messiahs. We've gotta be pragmatic.

For the record, I quite like BEM and it's variations.

@carwin a real-world example, with several components (see also #24 in this thread): https://github.com/ry5n/drupalui

@ry5n Yep, I saw both the things you mentioned, I just didn't see a lengthy example that used both "--" and "__", which I think is what @sun was partially after when suggesting we look for a "no-brainer" case we could convert in #23. Can you help us come up with an example that might use both? That would be great for documentation.

At any rate, the examples you posted are nice, thanks for sharing.

@carwin Oh, sorry. I thought maybe you had missed the example, and I also didn’t read closely enough – I get it now, you’re looking for a single case where we have both -- and __. That *should* be infrequent. I’ll see if I can think of an example and post it here.

OK, here’s an example: the progress bar from the proposed Seven style guide:

Here’s what we’d probably need (at minimum) for the full-size Progress component:

.progress {}
.progress__label {}
.progress__cancel {}
.progress__track {}
.progress__bar {}

When it comes time to create the small variant, we won’t need to write much actual CSS, but we’ll likely need to apply a few rules to each of the label, cancel, track and bar. To do this, there are basically two options, the first of which uses the combined -- and __.

Option A (modifier classes all the way down):

.progress--small {}
.progress--small__label {}
.progress--small__cancel {}
.progress--small__track {}
.progress--small__bar {}

Option B (top-level modifier + descendent selectors):

.progress--small {}
.progress--small .progress__label {}
.progress--small .progress__cancel {}
.progress--small .progress__track {}
.progress--small .progress__bar {}

The real difference here is in the HTML they would pair with. With option A, the markup for the progress track would look like this: <div class="progress__track progress--small__track"></div>, and similarly for each child element. That’s verbose, but we get to use single class selectors for the variant’s child objects, and if we ever needed a small progress track outside of a Progress component, it would just work. However, our goals may be just as well served by switching to option B, even though we’re doing the “scoping” thing that we usually want to avoid. In this case, however, we have already avoided overly-generic class names by namespacing our child objects within the Progress component. By the same token, we really shouldn’t ever need a Progress track outside of the Progress element, since it’s by definition “attached” to that component. So, we’re still serving most of our goals well, and we greatly simplify the required markup: we only need to add the variant class to the component itself: <div class="progress progress--small"><!-- all internals remain the same --></div>.

I think these are both acceptable strategies. Yes, we should try to be consistent, but I also think we need to start implementing this stuff before we’ll know for sure which works better in practice.

Finally, I hope this example clarifies how these naming conventions interact, how they can help (imagine how much more confusing this example would be with only single dashes) and also what we still need to figure out.

I'm really don't like BEM. Interesting in who (open source projects) using it now ?

I'm in agreement that BEM looks a bit ugly. I have seen very little about it in design communities, and don't see it being any kind of industry standard (I could be wrong, but I doubt it).

It makes CSS seem more annoying, and 'programmer-ese', with all the double-dashes, and underscores especially.

@ry5n, thanks for your efforts and explanation, I think you've covered the options well -- I'm marking this back to RTBC now.

My stance on this is that we need to go into this expecting to see some issues arise, but to keep from stagnating it's important that we push forward. I would rather have a standard I have minor disagreements with than absolutely no standard at all. We've gotta have something to work with.

I'd also like to tie up the loose ends that we can in this thread and break out those that require heavy brain lifting into their own issues.

concerns from #19

All pages

• These seem to be in motion, and although it's not perfect, I'm sure the writing will improve with iterations.

Formatting guidelines

1. I removed this section from the document. If anyone has strong feelings about it, feel free to comment over there.
2. I added some extra examples to the document.
3. This is a to-do item, but I don't think this should necessarily block us from "committing" this.
4. This is gone.
5. Killed it with fire.
6. I took this to mean that all backticks should be replaced by single quotes within the Formatting guidelines document. @KrisBulman was kind enough to take care of this in #20.
7. This was a great idea. Done. Now this document matches other coding standard docs more closely in style.

Architecture

• I don't think I'm going to touch these. At this point, these topics have been discussed at length and there seems to be some general consensus and/or resignation to using the styles as they're currently defined. For now. *queue dramatic music*

File organization

1. This is one of those areas where we'll probably just wait and see. The concern is valid, but until we start really using this I don't think we'll have enough data to go one way or the other. At the very worst, down the road someone points out a problem and we revise our strategy. Perhaps I'm being a bit overly-optimistic -- shall we open this up as a separate issue?

concerns from #22

1. I think @ry5n came up with some pretty nice examples related to this in #31.
2. I actually do not know whether or not it IS discouraged. Can someone post a link to where this was discussed? As long as I have a paper-trail on it, I'm fine with adding a "this is a no-no" section to the formatting doc.
3. Ditto for sticking with defaults -- this seems like it could be it's own issue as well. (only 3 so far, not bad)

Non-Lethal To-Do:

1. Merge the Blank Lines section of the CSS formatting doc into the Whitespace chapter.
2. Create an issue to go over file organization with a fine-toothed comb.
3. Create an issue to discuss modernizr prefixing

I think ry5n has done a great job of explaining the BEM style naming convention so far. Aside from the benefit of being able to clearly see the function of a class from only its name, following naming conventions like this (and the "l-" prefix described in SMACSS) makes the developer think about architecture. This is a great way of enforcing many of the other important architectural concepts described in the guidelines.

As for examples, I've just finished overriding most of core CSS and markup for Omega 4 and one of the big goals was to implement these D8 standards, including BEM, which should provide many Drupal specific examples.

When I read the BEM article, I feel good. But..

Going Open Source (2010)
In 2010, we had published some code on our GitHub account to continue growing as an open source project.

I did some research and found only ONE project using it: inuit.css.
the creator is the BEM article writer:
http://csswizardry.com/2013/01/mindbemding-getting-your-head-round-bem-s...

Another article:
http://coding.smashingmagazine.com/2012/04/16/a-new-front-end-methodolog...

At least, this concept has been introduced to front-end developer ONE and more than ONE year. Why no other projects using it?

Futhermore, I try to find a real exmaple. This is Yandex who created BEM
http://company.yandex.com/
http://images.yandex.com/
http://images.yandex.com/yandsearch?text=flowering%20cherry%20tree

I'm TOTALLY lost in it when I look at the source code. Extremely ugly and bad coding.
some concepts I agreed in this article go away from my head.

Thanks, @carwin!

AFAICS, these are the remaining tasks:

#19:
All pages

1. Use RFC/W3C spec keywords everywhere to clarify what MUST be done (rules) and what SHOULD or MAY be done (recommendations).
2. Ensure that MUST/SHOULD/MAY + summary + example always comes before MUST NOT/SHOULD NOT/MAY NOT and possible elaborations.

Formatting guidelines

3. Merge 3.3. Format (Blank lines) into 1. Whitespace.

Architecture

1. Needs better example, as provided by @ry5n.
2. @todo We need to discuss BEM variants/components some more.

#22:

2. Recommend to (SHOULD) use self-descriptive names and identifiers, instead of abbreviations. (.button vs .btn)

   This is a generic coding standard that applies to all code in Drupal. You cannot (or should not be able to) find any obscure function or variable names anywhere in Drupal that haven't been intentionally abbreviated (t() and l() are the most well-known exceptions).

3. Use Modernizr default prefix and classes.

@sun, I created a gist containing a quick re-write of what we have so far to use the RFC documentation spec: https://gist.github.com/carwin/5093583
So far, you're the only one who has had a comment on this subject, so I wanted to get your approval on that before modifying the document on d.o. Please feel free to fix or comment on any errors you see there.

Also, is this the latest RFC styleguide? http://www.rfc-editor.org/rfc-style-guide/rfc-style?

I’ve made a number of clarifications and additions to the CSS standards to address #37:

In the Formatting Guidelines:
- Moved “blank lines” section from Formatting into Whitespace

In CSS Architecture:
- Added the progress bar example from above as a new Case Study section;
- Added the recommendation to use dasherized full words for class names and no abbreviations.
- Removed the recommendation for custom Modernizr classes. Modernizr is no longer mentioned in the docs.

I don’t think there’s anything more to discuss about using Nicolas Gallagher’s modified BEM conventions (component, component__element, component--variant). The mobile initiative meetings discussed the idea of using the newer Montage style as an alternative, but decided against.

I’m not convinced we need to re-write this with RFC language. @carwin, thanks for making a start on it; if we decide to make the change it will come in handy.
IMO The RFC language is really the only thing left; unless someone wants to push for that, I want to mark this RTBC again.

Great work @ry5n! Since everything but RFC has been completed, I am throwing my vote in for RTBC. I see no reason for RFC language to be a blocker here.

+1 for not letting this be blocked by RFC re-write. We're 6 months into this issue and I really don't think there's any more to it at this time. RTBC - let's commit this thing.

Are there other places within the Drupal documentation where RFC is being used?