The inaugural Clarity, hosted at the lovely new Alamo Drafthouse in San Francisco, just recently wrapped up. Jina Bolton did a wonderful job of wrangling the whole thing together, so huge thanks to her, the volunteers, and sponsors.

I was invited to be the Emcee of the event, the resident on-stage jackass charged with introducing the event and the speakers. I also got a chance to chat with each of the speakers and ask them a few questions at the end of their talks.

I thought I'd write up this wrap-up, which is some mixture of notes, my thoughts, and other people's thoughts from the event. As in, these aren't comprehensive notes, just a smattering.

Brad Frost told us the time for design systems is now.

"Show, don't tell."

That's what Brad recommends for selling a higher-up on the need for a design system. If you ask if you can spend time doing an "interface inventory" you might get a no, but a small time investment in bringing together examples of a broken design system might get you a yes for a more meaningful job.

Button styles are a pattern that can easily get out of control.

This "buttons" problem was corroborated by Maya in her talk:

What is a "style guide"?

The term "style guide" is tricky. It doesn't have any 100% defined meaning. Or, if it does, people ignore it. Here's just some examples:

  • Brand Identity Guidelines
  • Design Language documents that provide a set of principals organizations use to guide design choices
  • Voice and Tone guides, like MailChimp has
  • Writing guides (spelling, grammar, etc.)
  • Coding guides (syntax choices, naming conventions, etc)
  • Pattern libraries

They are all useful, so maybe it doesn't matter much?

Death By 1,000 Cuts

An overused metaphor, perhaps, but only because it's so darn applicable. As I was preparing for the conference and discussing the why of it with Miranda Mulligan, she brought this up.

Maybe there is no one big thing that a style guide does for you, one big thing the the lack of one will take from you. Maybe it's lots and lots of little things.

  • Not having a style guide makes development slower
  • Not having a style guide leads to inconsistent design
  • Not having a style guide makes it harder to hire and onboard
  • Not having a style guide leads to CSS bloat
  • Not having a style guide leads to performance problems
  • Not having a style guide slows down communication

Even those feel big. There are likely a lot more small things that happen. On the opposite side.

  • A style guide can speed up development
  • A style guide makes for faster and more high fidelity prototyping
  • A style guide can help new employees be productive more quickly
  • A style guide can fight stylesheet growth over time
  • A style guide provides common ground for design discussion

Perhaps it's death-by-500 cuts and life-by-500 band-aids. That metaphor adjustment could use some workshopping.

Atomic Design

Brad is known, in part, for a thing he calls Atomic Design. It's a metaphor (Clarity was huge on metaphors) that goes like this:

atoms > molecules > organisms > templates > pages

He is part of a team that works on a tool called Pattern Lab, where you can learn more about Atomic Design. He's also writing a book on it.

Isaak Hayes and Donna Chan told us that research is key to a successful style guide

In my experience, it wasn't that long ago when the refrain around style guides was: "Sure, sounds like a nice dream, but style guides never work." Isaak and Donna agree: they can fail, and they can fail for lots of different reasons:

  • They can fail because style guides are cross-team endeavors and those teams might be mis-aligned.
  • They can fail because the style guide was created in a silo.
  • They can fail because there is no motivation or incentive to adopt the style guide.

Those are just a few. Failed style guides aren't just sad in and of themselves, they are also a tremendous waste of time.

A team snake-bitten by a failed style guide is a real bummer.


Avoid failure through research

Before you're designing or writing code, "discovery" is an important step.

  • What products/projects will be effected by this style guide?
  • What is coming down the pipeline that will be effected?
  • What is product-specific and what is universal? Can the style guide be themeable in which to adapt?

Interviewing people is key. They told us doing it face to face is best. Get information, pull out the most useful nuggets and synthesize them into a whole.

Measuring Success

This was my favorite part, because I haven't heard much talk about this. How do you measure the success of a style guide? Simply having one might feel like a success, but is it? How could you actually measure success?

  • Fewer JIRA tickets? Support requests having to do with design problems?
  • Shorter code reviews?
  • Fewer version control commits?
  • Faster development time? Faster sprints? Faster time-to-production?

Nathan Curtis talked to us about the people behind a design system.

It's actually three things: Parts, Products, and People. It starts with the people though: it's the people who are defining the parts (everyone will have different opinions) and what products they apply to.

Google's Material Design is a pretty awesome example of a design system. Still, total cohesion is hard.


Even when you have total support from the top (which they did):


Some things can be one-offs

The home page is a classic example of this. It can be a major distraction. The home page is often very different from the rest of the site, so maybe don't use it as a starting point.

Building from the inside out is likely a better use of time. As in, focus on the core product (like a "listings" page) and "radiate influence" outward.


A job title might make all the difference

A successful style guide serves multiple people. Multiple groups of people. For example: both designers and developers. Facilitating a conversation around both of the groups is paramount to the style guides success. But it's possible those conversations feel lopsided (e.g. one side feeling like things are being pushed on them, rather than an equal-footing discussion).

Jina had her job title changed at Salesforce.


Senior Product Designer


Senior Designer, Design Systems

Jina liked it, but perhaps more importantly, it might frame conversations between her and other groups more effectively. Rather than a job title that places her in a particular group, it places her in the middle. A facilitator.

Miriam Suzanne told us if something isn't documented, it doesn't exist.

In a direct sense, she was talking about her experience with Susy. In the beginning, The most useful bits of Susy weren't documented in an easy-to-find way in the README. Thus, there were barely used.

In a broad sense, it applies to any style guide.

Make documentation the lazy option.

A different possible style guide deliverable.

I was fascinated by the idea that a (web) style guide deliverable could take different forms. I normally think of them as: USE THIS HTML (The CSS assumes it, and does its thing.)

But the deliverable could be something else, like robust preprocessing functions. Just like Susy delivered on-demand grids:

  $susy: (
  columns: 12,
  gutters: .25,
  math: fluid,

@include layout($susy float inside);

You could deliver that same kind of thing for any other design pattern/component. Who knows, maybe like

  @include tabs("flexbox", 5, $mapOfColors);

That's just the kind of company Oddbird is, what they are good at, what their customers need.


What did you think classes were for?

Classes are design patterns. The "SS" in CSS is "Style Sheets", after all.

I found myself thinking about this a lot. CSS is a style guide. It just happens to not be that simple. You need to have a plan to make it truly effective, and that plan gets more complicated the bigger projects get.

Stephanie Rewis & Brandon Ferrua walked us through Lightning Design System.

GET IT?! Oh right, you would need to know the title of their talk was "Crawl, Walk, Run".

I very much liked that metaphor for the creation and implementation of a style guide. They had very specific mappings of those terms to their own work on LDS, but I think they could be remapped to any similar journey.

There was a good amount of talk about failed implementations of style guides, and perhaps there would be less of that if we crawled a bit longer.

Who is it for?

LDS is a major, major effort. There is a whole large team on it, it's very publicly visible. But it's not really for you and me. It's for Salesforce, and for people who build things for Salesforce. While it's presented a bit like Bootstrap or Foundation, that's not the audience, the expected user, or who is actually using it.

THEO: More Meta than Sass

In the early days of LDS, it was more about serving mobile apps than it was the web. CSS isn't useful for native apps. So rather than starting with CSS, they started with, essentially, JSON. I guess THEO is the thing that processes the JSON into other stuff.

  • JSON > Salesforce's special internal CSS syntax
  • JSON > Sass
  • JSON > Less/Stylus probably?
  • JSON > iOS whatnot
  • JSON > Android whatnot

A strategy for deprecation

Style guides evolve. The tendency is for them to grow, which for anyone concerned with web performance, maintainable code bases, and design consistency (everybody ever), that's not a good thing.

A lot of people use LDS, so they can't just ship a new version that rips stuff out. That would break people's stuff. Enough of that, and adoption could fail and lead to one of those failed style guide stories.

But because nobody is perfect, design evolves, needs change, and new decisions are made, sometimes code does need to be ripped out. They have a strategy for that. Rather than ripping it out in the very next version, they wrap it in a Sass thing like:

  @include deprecate('2.0.0', 'Use .button-new instead') {
  .button { background: red; }
.button-new { background: red; border: 3px solid blue; }

My first thought would be: but do people actually look at their console when they compile stuff?

But that's an advantage of the limited consumer scope of LDS: it's for Salesforce stuff, so I suppose they can teach/train people to use the tools in such a way they will see these messages.

Also how about this mindsploder:


Fun fact: they maintain 3 or 4 different versions of LDS at all times.

Anna Pickard told us that they don't ever use puns at Slack.


She made it make sense though. Not everybody gets puns, particularly across cultures. Not getting a pun makes you feel left out (dumb?). Why make anybody feel like that? They do say they like literary references though, I wonder if that is at-odds with that? I dunno, I guess we'll have to cut them some slack.

The Slack style guide is a work-in-progress.

A "living document" exists, but it wasn't ready for public consumption. I kinda like that, in a way, as I don't think style guides need to be big public efforts all the time. They should serve the teams that need them.

Anna does words at Slack.

Meaning: microcopy, release notes, error messages, tweets, marketing, documentation... Apps need lots of words. Words have tone, and tone affects how people feel about a product.

Slack does have some rules. They don't say "bae", for example. But they allow for and encourage individuality. Slack isn't a single voice, but a group of unique humans forming a cohesive whole. I bet Anna would not like that last sentence. Too business-wordy.

Rachel Nabors showed us that animation is an integral part of style guides.

Which, I think the first time you hear that, is a little surprising. Don't you just sprinkle animation in here and there where it assists in UX or sprinkles in a little sunshine? Nah, it's as much a part of design as anything else and is a first class citizen in a style guide.

Just as you can have color-creep on a project (e.g. "we have 39 shades of blue?!") you can have animation-creep, which might be even more insidious and awkward/damaging to a site/brand.

Documentation for how to handle animation inside a design system is really new, there aren't a lot of go-to examples. Designers do want this though. They like systems and like adhering to theory.

There is some difficulty in communication between Motion Designers (an apparently well-established job title, but one that I rarely come across, which may be telling) and devs. Motion designers don't love working with established prototypes and devs don't love getting a GIF to build from. Storyboarding might be the best way to go.


There are some pretty good rules of thumb for easings.

Easing, as in, the rate of change of an animation over time. can show you all the major ones.


Both Chrome and Firefox have easing visualizers built-in these days. Careful with the bouncy ones — that can be pretty cartoony.

We learned we're all the Julia Childs of our own design systems from Cordelia McGee-Tubb.

Accessibility is often an after thought. Something that is applied later in a project rather than being a first class citizen from the beginning. Which sucks just about as bad as a blueberry muffin where you push the blueberries into the muffin after it's baked. What a good metaphor.


The cooking metaphors don't stop there. Lots of people copy and paste code (not a day goes by that I don't). Those code chunks are like recipes. We should be baking accessibility into those code chunks, so when they are copy/pasted, that comes along for the ride.

What are those ingredients? Things like proper use of <button>, explicit <label>s, alt text for images, making sure you have :focus styles, ARIA roles, etc.

ARIA roles can be tricky... thankfully there are some resources, like the 18F style guide:


And others, like Heydon's Practical ARIA Examples.

Every type of user

Accessibility isn't just for the blind. There are lots of reasons someone might be a keyboard user. Good advice:

Make keyboard interactions as rich as mouse interactions.

Facebook recently dropped new "emotional reactions" to posts (more options than just the thumbs-up "like"). It's a pretty good example of a well-working keyboard interaction. You can navigate to all the options via the keyboard and they even have the same animations.

The button trick

I dug the little CSS trick Cordelia dropped. Instead of:

  .button { } 

You could do

  button.button { }

which has a tiny bit higher specificity, but ensure that button styles aren't mis-applied to non-button elements.


Jeremy Perez-Cruz told us that people who work in branding are part magicians.

Part psychologist, part designer, part magician. It's about making people feel how you want them to feel and then how they retell that experience.

There is no such thing as bulletproof branding guidelines.

A logo might live for decades, but the design systems around it will change.


Speaking of change...

Jeremy told us how brand guides can breathe. They can move and flex. Sometimes it's OK to even break them in order to make something look good. That's OK. That's essentially feedback on how useful the design system is. This was a nice echo to Nathan's reminder that the homepage is often something that breaks rules and is more of a one-off.

Any given pattern has an anatomy, and there are a number of different patterns, says Claudina Sarahe.


  • Name
  • Context
  • Problem
  • Solution(s)
  • Related Patterns

This could be for any pattern. You could think of these as sheets in a three-ring binder, to be added/removed/changed/rearranged.

There are lots of patterns specifically for front end. Front end patterns could even be sub categorized. Like:

  1. Global Patterns (e.g. how do we approach accessibility?)
  2. Process Patterns (e.g. how do we name things? how do we document things?)
  3. Workspace Patterns (e.g. what code editors do we use? what are we using for version control?)
  4. Project Patterns (e.g. what build tools are we going to use? what CSS methodology?)

Static FTW

Claudina was was into the idea of using static site generation techniques for front end teams. As in, using build tools and preprocessors to ultimately produce a static .html and .css site.

The advantages to static front ends have been well extolled: faster! safer! easier to scale! simpler server requirements! But Claudina added to that it was easier to onboard new team members. The backend environment they were on at Casper was much harder to get started on than the static stuff they are moving to. Now it's more like, pull this repo, npm install, go.

HTML Preprocessing

Like Miriam, Claudia showed us there is a lot of value in HTML preprocessing. A surprise to me, in a way, as I always thought there was the least value to be found in HTML preprocessing (compared to CSS or JS), but I think I'm pretty convinced.

Imagine instead of dropping preformatted HTML of what a design pattern needs into a template, you call a HTML preprocessing function with parameters. That function outputs the necessary HTML markup. That gives you an abstraction in which to change the HTML output as needed for that pattern, without having to revisit your whole code base. Makes sense to me.

Nunjucks templates/macros seemed to be the way to go.

Per-pattern folders

Claudina showed us a directory structure in which components were the directories. As in, all the HTML, CSS, and JS for a component were grouped together. Rather than (what I'd think is more common) grouping by areas of the site and/or by the type of file.

I've been seeing this more and more.

Wanna make a huge impact with your design work? How about designing for 320 million Americans on IT projects with a combined budget of 86 billion dollars.

That's what Maya Benari talked with us about. And of that 86 billion? 94% of those projects are over budget and behind schedule (!). Also, 40% of them are scraped (!!). She wasn't afraid to be critical about this. Maya told us the government buys IT like it buys bulk pencils. Kind of like a commodity product, which leads to silos of development and waterfall-city, which I think we've all learned isn't a workable strategy for successful tech projects.

Maya worked on the U.S. Web Design Standards, a huge effort by 18F. A huge effort might be an understatement.

  1. They had to pitch it (they call it The Great Pitch) to the government and get approval and a budget. It was approved and they had four months to do it.
  2. They had to do a ton of research to make sure what they built was on target and accommodated for the different types of web workers they found (e.g. "the clock racer", "the master builder", etc.)
  3. Accessibility isn't just a good idea for it, it's mandated by law.
  4. It needed to be consumed in any way people wanted to consume it
    1. Use the design and code patterns
    2. Use the code patterns, bring-your-own design
    3. Use the design, bring-your-own code

The final product is beautiful. Both outwardly, it's aesthetically very nice and feels appropriate for The United States, and inwardly with all it's baked-in accessibility and welcoming tone.

It it working?

It looks like it. Use of this style guide by government projects isn't mandatory, but lots of projects are picking it up voluntarily: the VA, USA Jobs,, and more. was inspiration for this project, and has kinda awesome adoption, but the U.S. is a very different place. This style guide is a carrot, not a stick.

If you want a lasting legacy for your design system, how about a design that gets put onto a satellite and launched into deep space forever?

Richard Danne designed the NASA logo. The super iconic one they use from 1975-1992:

But not just a logo an entire design system for NASA to use for everything they from forms to uniforms to airplanes to satellites. The design system was codified in a literal three-ring binder and among the first of it's kind.

The story of how it happened and was amazing. They won a pitch between loads of different agencies that they never thought they would get. There were essentially no trained designers at NASA whatsoever. That might have been good, as the implementation of the style guide was extremely thorough. A lot of us struggle to get our own teams using a style guide we make, let alone total and complete saturation of it over a huge organization.


The style guide for NASA was codified as The NASA Graphics Standards Manual, and the story of it was of interest to far more people than just those at Clarity. In August of 2015, a Kickstarter was launched for a reprinting of this iconic manual. It raised nearly a million dollars. Jina had a copy I checked out before the conference and it was extremely cool. She told me you can't even buy it yet, it was for backers only. But Richard told us at the conference they where going on sale right then. Purchased.

Alien Planets

Over the last couple days I have met quite a few of the speakers and I have to confess: I feel like I have been beamed down from another planet.

I told Richard I hope I'm at a conference about style guides 40 years from now and they sound like alien to me, too.

The Most-Referenced Style Guides at Clarity

Three other things that were referenced A LOT

Other People's Notes