Tags: styleguide



Fractal ways

24 Ways is back! That’s how we web nerds know that the Christmas season is here. It kicked off this year with a most excellent bit of hardware hacking from Seb: Internet of Stranger Things.

The site is looking lovely as always. There’s also a component library to to accompany it: Bits, the front-end component library for 24 ways. Nice work, courtesy of Paul. (I particularly like the comment component example).

The component library is built with Fractal, the magnificent tool that Mark has open-sourced. We’ve been using at Clearleft for a while now, but we haven’t had a chance to make any of the component libraries public so it’s really great to be able to point to the 24 Ways example. The code is all on Github too.

There’s a really good buzz around Fractal right now. Lots of people in the design systems Slack channel are talking about it. There’s also a dedicated Fractal Slack channel for people getting into the nitty-gritty of using the tool.

If you’re currently wrestling with the challenges of putting a front-end component library together, be sure to give Fractal a whirl.

Code refactoring for America

Here at Clearleft, we’ve been doing some extra work with Code for America following on from our initial deliverables. This makes me happy for a number of reasons:

  1. They’re a great client—really easy-going and fun to work with.
  2. We’ve got Anna back in the office and it’s always nice to have her around.
  3. We get to revisit the styleguide we provided, and test our assumptions.

That last one is important. When we provide a pattern library to a client, we hope that they’ve got everything they need. If we’ve done our job right, then they’ll be able to combine patterns in ways we haven’t foreseen to create entirely new page types.

For the most part, that’s been the case with Code for America. They have a solid set of patterns that are serving them well. But what’s been fascinating is to hear about what it’s like for the people using those patterns…

There’s been a welcome trend in recent years towards extremely robust, maintainable CSS. SMACSS, BEM, OOCSS and other methodologies might differ in their details, but their fundamental approach is pretty similar. The idea is that you apply a very specific class to every element you want to style:

<div class="thingy">
    <ul class="thingy-bit">
        <li class="thingy-bit-item"></li>
        <li class="thingy-bit-item"></li>
    <img class="thingy-wotsit" src="" alt="" />

That allows you to keep your CSS selectors very short, but very specific:

.thingy {}
.thingy-bit {}
.thingy-bit-item {}
.thingy-wotsit {}

There’s little or no nesting, and you only ever use class selectors. That keeps your CSS nice and clear, and you avoid specificity hell. The catch is that your HTML is necessarily more verbose: you need to explicitly add a class to whatever you want to style.

For most projects—particularly product work (think Twitter, Facebook, etc.)—that’s a completely acceptable trade-off. It’s usually the same developers editing the CSS and the HTML so there’s no problem moving complexity out of CSS and into the markup templates. Even if other people will be entering the actual content into the system, they’ll probably be doing that mediated through a Content Management System, rather than editing HTML directly.

So nine times out of ten, making the HTML more verbose is absolutely the right choice in order to make the CSS more manageable and maintainable. That’s the way we initially built the pattern library for Code for America.

Well, it turns out that the people using the markup patterns aren’t necessarily the same people who would be dealing with the CSS. Also, there isn’t necessarily a CMS involved. Instead, people (volunteers, employees, anyone really) create new pages by copying and pasting the patterns we’ve provided and then editing them.

By optimising on the CSS side of things, we’ve offloaded a lot of complexity onto their shoulders. While it’s fair enough to expect them to understand basic HTML, it’s hardly fair to expect them to learn a whole new vocabulary of thingy and thingy-wotsit class names just to get things to look they way they expect.

Here’s a markup pattern that makes more sense for the people actually dealing with the HTML:

<div class="thingy">
    <img src="" alt="" />

Much clearer. But now the CSS looks like this:

.thingy {}
.thingy ul {}
.thingy li {}
.thingy img {}

Actually it’s probably going to look more complicated than that: more nesting, more element selectors, more “defensive” rules trying to anticipate the kind of markup that might be used in a particular pattern.

It feels really strange for Anna and myself to work with these kind of patterns. All of our experience screams “Don’t do that! Why would you that?” …but in this case, it’s the right thing to do for the people building the actual website.

So please don’t interpret this as me saying “Hey, everyone, this is how you should write your CSS.” I’m not saying this is better or worse than adding lots of classes to your HTML. If anything, this illustrates that there is no one right way to do this.

It’s worth remembering why we’re aiming for maintainability in what we write. It’s not for any technical reason. It’s for people. If those people find it better to deal with simplified CSS with more complex HTML, than the complexity should be in the HTML. But if the priority for those people is to have simple HTML, then more complex CSS may be an acceptable price to pay.

In other words, it depends.

Pattern sharing

Mike has written about the Code for America alpha website that we collaborated on:

We chose to work with ClearLeft because they develop a pattern portfolio (a pattern/style library) which would allow us to scale our work to our Brigades. This unique approach has aligned perfectly with our work style and decentralized organizational structure.

Thankfully, I think the approach of delivering a pattern portfolio (instead of just pages) isn’t so unique these days. Mind you, it still seems to be more common with in-house teams than agencies. The Mailchimp pattern library is a classic example.

But agencies like Paravel are—like Clearleft—delivering systems, not pages. Dave wrote about providing responsive deliverables:

Responsive deliverables should look a lot like fully-functioning Twitter Bootstrap-style systems custom tailored for your clients’ needs.

I think that’s a good way of looking at it: a Bootstrap for every project.

Here’s the front-end style guide for Code for America.

Usually these front-end deliverables will be password-protected on the Clearleft extranet for the client’s eyes only, but Code for America are all about openness, so they’re more than willing to let us share it with the world. That makes me very happy. I remember encouraging the guys at Starbucks to publish their front-end style guide and I’ve written about this spirit of sharing before:

These style guides and pattern libraries aren’t being published in an attempt to provide ready-made solutions—every project should have its own distinct pattern library. Instead, these pattern libraries are being published in a spirit of openness and sharing …a way of saying “Hey, this is what worked for us in these particular circumstances.”

If you’re poking around the Code for America style guide, you’ll notice that it borrows some ideas from the pattern primer idea I published a while back. But in this iteration, the markup is available via a toggle—a nice variation. There’s also a patchwork page that provides a nice glance-able uninterrupted view of the same patterns.

Every project is a learning experience and each front-end style guide gives us ideas about how to do the next one better. In fact, Mark is busy working on better internal tools for creating these kinds of deliverables—something we’ll definitely be sharing. In the meantime, I’ll be encouraging other clients to be as open as Code for America have been in allowing us to share these deliverables.

For more on the usefulness of front-end style guides, be sure to read Paul’s article on style guides for the web, Anna’s classic 24 Ways article, and of course, Anna’s pocket guide from Five Simple Steps.

Coding for America

Back when I was wandering around America in August, I mentioned that I met up with Mike Migurski in San Francisco:

I played truant from UX Week this morning to meet up with Mike for a coffee and a chat at Cafe Vega. We were turfed out when the bearded, baseball-capped, Draplinesque barista announced he had to shut the doors because he needed to “run out for some milk.” So we went around the corner to the Code For America office.

It wasn’t just a social visit. Mike wanted to chat about the possibility of working with Clearleft. The Code for America site was being overhauled. The new site needed to communicate directly with volunteers, rather than simply being a description of what Code for America does. But the site also needed to be able to change and adapt as the organisation’s activities expanded. So what they needed was not a set of page designs; they needed a system of modular components that could be assembled in a variety of ways.

This was music to my ears. This sort of systems-thinking is exactly the kind of work that Clearleft likes to get its teeth into. I showed Mike some of the previous work we had done in creating pattern libraries, and it became pretty clear that this was just what they were looking for.

When I got back to Brighton, Clearleft assembled as small squad to work on the project. Jon would handle the visual design, with the branding work of Dojo4 as a guide. For the front-end coding, we brought in some outside help. Seeing as the main deliverable for this project was going to be a front-end style guide, who better to put that together than the person who literally wrote the book on front-end style guides: Anna.

I’ll go into more detail about the technical side of things on the Clearleft blog (and we’ll publish the pattern library), but for now, let me just say that the project was a lot of fun, mostly because the people we were working with at Code for America—Mike, Dana, and Cyd—were so ridiculously nice and easy-going.

Anna and Jon would start the day by playing the unofficial project theme song and then get down to working side-by-side. By the end of the day here in Brighton, everyone was just getting started in San Francisco. So the daily “stand up” conference call took place at 5:30pm our time; 9:30am their time. The meetings rarely lasted longer than 10 or 15 minutes, but the constant communication throughout the project was invaluable. And the time difference actually worked out quite nicely: we’d tell them what we had been working on during our day, and if we needed anything from them; then they could put that together during their day so it was magically waiting for us by the next morning.

It’ll be a while yet before the new site rolls out, but in the meantime they’ve put together an alpha site—with a suitably “under construction” vibe—so that anyone can help out with the code and content by making contributions to the github repo.

Sharing pattern libraries

I’ve been huffduffing talks from this year’s South by Southwest, revisiting some of the ones I saw and catching up with some of the ones I missed.

There are some really design and development resources in there that I didn’t get to see in person:

One talk I did get to see was Andy’s CSS for Grown Ups: Maturing Best Practices.

CSS for Grown Ups: Maturing Best Practices on Huffduffer

It was excellent.

You can have a look through the slides.

He talks about different approaches to creating maintainable CSS for large-scale projects. He touches on naming conventions for classes, something that Nicolas Gallagher wrote about recently. And while he makes reference to SASS and Compass, Andy makes the compelling point that’s what more interesting than powerful tools is the arrival of powerful approaches like SMACSS and OOCSS.

Over and over again, Andy makes the point that we must think in terms of creating design systems, not simply styling individual pages—something that Paul has also spoken about. One of the most powerful tools for making that change in thinking is in the creation of style guides for the web and Paul has even created blog dedicated to the BBC’s style guide.

Andy referenced the BBC GEL style guide in his talk but pointed out that because it’s published as a PDF rather than markup, it isn’t as powerful as it could be—there’s inevitably a loss of signal when the patterns are translated into HTML and CSS. Someone from the BBC was in the audience, and in the Q and A portion, acknowledged that that was a really good point.

After the talk I got chatting with Lincoln Mongillo who worked on the recent responsive redesign of Starbucks.com. He mentioned that they created a markup and CSS style guide for the project. “You know what would be really cool?” I said. “If you published it!”

Here it is. It’s a comprehensive library of markup patterns; exactly the kind of resource that Anna wrote about in 24 Ways.

In my experience, creating a pattern library for any project is immensely valuable, whether you’re working in a team of two or a team of two hundred. I’ve found they work well as the next step after Style Tiles: a way of translating the visual vocabulary of a site into markup and CSS without getting bogged down in the specifics of page structure or layout (very handy for a Content First approach). The modularity of a pattern library enforces a healthy .

I’m really pleased to see more and more pattern libraries being made public. That’s one of the reasons why I shared my pattern primer and Dan shared his Pears theme for Wordpress:

Breaking interfaces down into patterns has been immensely helpful in learning and re-evaluating the best possible code to implement them.

But Pears isn’t about how I code these patterns—it’s a tool for creating your own.

I love that. These style guides and pattern libraries aren’t being published in an attempt to provide ready-made solutions—every project should have its own distinct pattern library. Instead, these pattern libraries are being published in a spirit of openness and sharing …a way of saying “Hey, this is what worked for us in these particular circumstances.”

For that, I am very grateful.