Research CSS Style Guides

[noahmanger]

Goal: See if we can find examples of a CSS/Sass styleguide that we could either copy whole cloth or fork.

Steps:

• Research links to other companies' style guides
• Drop links and comments on them here.

Keep in mind:

• Specificity rules
• File structure
• Units (rems / px)
• Built in linter?
• Naming conventions

@msecret @shawnbot @meiqimichelle @noahmanger

[meiqimichelle]

Hi team! FYI, I'm in the process of looking at these styleguides:

• ThinkUp
• Github
• Mapbox
• css:guidelines
• sass:guidelines
• Mailchimp
• Wordpress

To-read next: http://engineering.lonelyplanet.com/2014/05/18/a-maintainable-styleguide.html

For the record: http://styleguides.io/ (all the things)

[meiqimichelle]

Thoughts after reading A Maintainable Styleguide from Lonely Planet:

This article talks about Lonely Planet's development of what sounds like a pattern API. Its developers can call different bits of website and pass certain variables. The code is then able to be maintained in one place and propagate across parts of the site.

Reflections:

• At first I liked this idea, but then started thinking about how one would maintain something like that across multiple sites. We are building many things with many partners that will rely on many flavors of frameworks, so perhaps not so much. Updating the API would risk breaking too many things.
• HOWEVER...we do need a solution for keep styles in line across 18F repos (the work that the dashboard and hub teams started [using one github repo to power the data for several others] needs to be expanded somehow to styles). So, maybe there is a grain of a way forward to be pulled from that article.
• A great final note from the article: I believe that the difference between Rizzo [their component api system] and our previous two Style Guides, in terms of their successfulness, is that with Rizzo we didn't focus on the Style Guide as the deliverable. Instead we focused on reducing complexity and increasing reusability.

Thinking about that final note -- I wonder what would do that for us? Perhaps some sort of atomic components based in Jekyll/Sass, since so many of our sites live there (...but then again, some don't so is it worth our time?).

After (lightly) reviewing the guidelines in my previous comment, perhaps something like Mailchimp's pattern library is the closest to what we were talking about on our call today. The structure is clear, there are notes on all the usage and decisions. I could imagine those being components that are copy-and-pasteable from a website as well as available in a grab-and-go entire simple site website template (like we talked about).

HOWEVER...this does not get at the list of 'things to keep in mind' at the top of this issue. Out of the more nuts-and-bolts CSS grammar styleguides I looked at, I did not agree with many of the choices in http://cssguidelin.es/ and so stopped reading part-way through (tl;dr syndrome). I liked bits of ThinkUp, Github and Mapbox, but wouldn't want to go with any of them whole-cloth. You may not be surprised since I already started doing this in Google docs, but I still say we'll need to stitch a CSS/Sass styleguide together from others to meet our preferences. I am happy to revise this opinion if y'all find something we like and want to recommend :)

That's all for now!

[meiqimichelle]

Latest draft available here. It will follow guild process described in our README for becoming a final (although always living) document.

[meiqimichelle]

Closed with #15