We know we can’t just design fixed web pages anymore—so how can we manage efficient workflows while accounting for the intricate systems and infinite variability that are today’s responsive sites? Style guides to the rescue! Well, sort of.
What we talked about
- Whose responsibility are style guides, and when and how are they built?
- Who are style guides for?
- Should a style guide share a code base with the actual site/app?
- How can we build accessibility and device compatibility into reusable design patterns and components?
- How can designers learn to think in terms of components instead of an overarching design?
- How can we best promote and maintain design patterns?
Featuring
Transcript
Nathan Curtis: Hello and welcome, everyone, to the third A List Apart: On Air event. My name is Nathan Curtis and I’ll be moderating today’s panel and the Q&A that follows about a half hour in. I’m the founder and principal at EightShapes. We’re a UX agency in Washington, D.C. that I partnered and created with Dan Brown, and one of the parts of our business that we’ve developed over the last eight years is consulting with teams large and small on design systems. That led, in 2009, to me writing a book on UX deliverables and how to modularize and systematize them. And then responsive hit; we’ve been doing all our stuff in code and working in online style guides since.
What we want out of this event is to create a space with a feel of a local meetup where we can chat together and really cover some tough questions and topics. But first, I wanted to talk a little bit about our sponsor. Our sponsor for ALA: On Air events is none other than Pantheon, the Drupal and WordPress hosting provider that lets you manage multiple sites from a single dashboard. You can also automate sysadmin work and push changes quickly and safely. So check out one of their live demos by registering at Pantheon.io.
Remember when websites were a collection of static pages? Gosh, I don’t want to remember that time. But those days are long gone. We know we can’t just design fixed pages anymore, so many of us are making our workflows more efficient and encoding intricate systems of decisions: color, icons, typography, UI patterns, and components and layout systems—all that structure and reuse is taking shape via online style guides, which are often huge libraries of reusable design and code bits. These guides describe everything from how to build a site to what the essence of a design language, or actually an organization that created it, is all about. There is seemingly infinite variability. Designers and devs have tremendous freedom to assemble those parts in interesting ways to solve problems. It’s really awesome.
And we take those libraries and we trust them to do it well, right? Except when we don’t trust them. Or they do it wrong. Or they ignore it altogether and things get unglued, cohesiveness breaks down and then we have to talk about it, converge on new decisions, even—gasp!—govern the thing. Certainly we have to maintain it. There’s no right way to build an online style guide, or a design library, or a code kit, or whatever flavor or name you want to give this thing, and that’s what we’re here to talk about today.
Our panelists are, first, Daniel Ferro. He’s a senior interaction designer at Forum One, where he helps design websites in Drupal and WordPress for cause-based organizations, such as the Robert Wood Johnson Foundation. Lately, just about every site Forum One puts out is created using Pattern Lab. Daniel lives in Alexandria, Virginia and enjoys visiting breweries, museums, and following soccer—just like me, he’s a Real Madrid fan! Daniel, welcome.
Sophie Shepherd is a designer who works for Ushahidi, an open-source tool for data collection and mapping. Prior to this, she was a designer at client services agency Happy Cog. When not working, she loves visiting new places, growing vegetables, hiking, and cooking. She lives in Austin and therefore can talk passionately about lake levels, tacos, and beer for hours on end. Welcome, Sophie.
Sophie Shepherd: Thank you.
Nathan: Cyd Harrell is a UX researcher and currently head of product at Code for America. Code for America pairs technologists with local governments to make cities work for everyone. She’s really passionate about the inclusion on the web and can be found writing silly haikus on Twitter, mostly from San Francisco. So, welcome Cyd.
Cyd Harrell: Thanks very much.
Nathan: Let’s start with you. So, when we talk about these online style guides, what are these things and who are we building them for? What’s your distinct perspective on that?
Cyd: So at Code for America, we worked with Clearleft in the fall of 2013 to build a pattern library online style guide for our website, and here of course we are often working by persuasion and example to do something that we think the governments ought to do.
Why did we go responsive, why do we think a library is important? Well, I track very closely the Pew Internet & American Life Project, which I think is one of the most valuable general studies available to us. And not only in their most recent studies do they show something like 68 percent of American adults having a smartphone, but something like 15 percent of American adults have a smartphone as their primary or only means of access to the internet. That means access to information about jobs, to services, to really so many things that a person needs in the modern world. In working with local governments who deliver services to people and are there to help everyone get what they need, they have an imperative to serve everyone. Now, a lot of local government websites at present are something like between 2000 and 2005 vintage, and people who are in charge of them are very concerned that they’re not appropriately reaching all the people that they need to.
[05:00]
The clear solution in 2014–2015 is to go responsive, but we wanted to figure out how we could actually recommend that to governments if we weren’t yet able to do it ourselves. We can’t just say, “Go and build a responsive site!” or “Go and build a set of mobile apps! You can just maintain it for Android and iOS, and maybe you should think about Windows phone…” That’s too messy. So, we actually went with a responsive pattern library with the idea that this would be a practice that we could then recommend to both educate cities about modern web publishing and also offer them an example that they could copy. And we’re announcing several cities in our network, like San Diego for example, working with local design firms to create pattern libraries as they move towards newer and more accessible, more modern city sites. So, I’ve seen it to be a really exciting tool for public servants who’ve been publishing an old model to modernize what they’re doing.
Nathan: So Cyd, can you tell me a little bit about how you distinguish what they might expect? For example, if they’re building a Drupal or WordPress site, they’re like: “So you’re building me a theme, right? I just need to get a theme; you’re just going to put on the website?” As opposed to: “No, it’s a little bit different, it’s a little bit broader than that…” Can you talk just for a minute about how you distinguish between what people expect and what your thing is?
Cyd: Yes, it’s a really important distinction, isn’t it? And there are certainly small sites for which a theme is a terrific solution. It doesn’t involve a whole lot of choices in creating each page, but as we look at broader local government sites—say a site of whatever city any of you listening in the audience live in—that’s going to be a site that offers somewhere in the hundreds of different services, none of which they can deprioritize the way a commercial company could, and they really need a lot of flexibility in constructing the web pages that represent each of those things. So a traditional model of publishing where you have a theme and it has, you know, two or three different templates, sometimes five or even seven, and you’re able to type text in the boxes the templates leave open, just isn’t flexible enough for the needs of a significant organization like a local government to responsively offer all the services they need to.
So, instead of—I like to think of it a little bit more like LEGOs. Instead of a theme that gives you page templates generally and sets of boxes that you can type in, so it’s kind of a fill in the blank, a pattern library offers you pieces to build a page with some level—and I’m sure we’ll get more into this, Nathan, as we talk about how you build them—with some level of guarantee that the pieces will work together and what comes out will look great and be on-brand and be mobile responsive. It’s a pretty big set of promises.
Nathan: So Daniel, talk to me a little bit about your practice in essentially client services and how you deliver these LEGO bits over and over again. How does this present a challenge for you to deliver or even design the experience?
Daniel Ferro: It’s funny, LEGO blocks is the first analogy I always come to, too. It’s a perfect way of visualizing that these are pieces that individually come together to build the big thing. And even before we started using more heavily pattern-based libraries at Forum One, we would use LEGO blocks to educate clients in our scrum agile process. Also internally, when we have new hires, we use it as just a fun tool to play with. But LEGO blocks are a good analogy to communicate the basic concept of pattern libraries. We’ve tended to use a little bit of Brad Frost language—atomic design. So, his metaphor is atoms, molecules, and organisms, so that way you can kind of think of it as the most basic, to a little bit more complicated, to very complicated.
So, we’re still trying to figure out the best way, the best metaphor. The atomic metaphor has not been as successful, maybe as we’d like, to communicate this to clients. We’re currently experimenting with using more Drupal-centric metaphors since we build a lot of Drupal and WordPress sites using the Drupal terminology, like modules, so that we don’t interchange between, “Oh wait, when I say ‘atom’ I mean this.” So I guess the struggle is maybe in coming up with a common language even though the general—once you say LEGO blocks, everyone understands what you’re talking about.
Yeah, so our clients, as you said earlier, are mission-based as we like to say, so a lot of nonprofits including government, and everyone has seemed to generally embrace this concept when we show it to them with the tool we use, Pattern Lab. So, it’s been very successful overall. Just some little things, as I was saying earlier, about just the common language you want to use to communicate what we’re talking about with our clients as we build the site. And on the topic of clients, too, I’m curious during the Q&A what kinds of needs some of the viewers have with their respective clients, be it internal or external. I really want to see what other people are doing or what other challenges people face.
[10:00]
Nathan: That’s great. I remember in our conversation that we started with Sophie, you were really passionate about how your online style guide, or essentially your modular system, was really a design and communication tool. We talked a little bit about metaphors. When you think about who you’re building your stuff for, how do you create metaphors or models for them to understand how all the pieces fit together?
Sophie: Yeah, so I think ours is a little different from what Daniel was explaining because we’re not building stuff for clients per se, so we’re not handing this off to someone else. So really it becomes a tool that we’re using internally, and not only the designers but also the people building the product that we’re working on; our product manager looks at it. And what it’s kind of become is this central place to keep us all on the same page, so everyone is always referring to the pattern library that we’re building to make sure that everything is staying consistent.
And then to go back to what Cyd was saying about the themes: in some way, our pattern library kind of is stepping in as a theming tool for us. So, the product we’re making is open source so people can use this pattern library to then extend it and change it. So, while it is built for a certain purpose, I’m definitely not for themes being used for any old website, the UX and stuff is all going to stay the same. We’re able to use the pattern library as something that people can take and they can change the look and feel of it for their needs. So, ours is kind of a two-part thing, which is us using it internally while referring to it and using it as a kind of index of the design system, and then also a way for people to extend the design system.
Nathan: There’s no doubt about it. When I think about the online style guides or pattern libraries that we’ve built, they really do reflect essentially all the different parts and how they’re interconnected in terms of what we’ve designed as a solution. And when I think about communicating that, I start at the highest level, and you think about executives, people that don’t engage with the design process as often—we communicate through flows of pages and they want to see sort of how you weave or thread through that stitched experience, all those different pieces, and how the pages connect. When I talk to product managers, sometimes I start a little bit more specific, “Here’s the page…” and then I deconstruct that. When I talk with developers, sometimes I’m talking about the most often reusable bit, which oftentimes is a module or sort of a rectangle on a page, like a piece of a sidebar or a header. But when I talk to visual designers, they care about all the different parts. They care about how the color and the type blends together, and they’re thinking about the line height between two lines, and they’re also thinking about the full composition.
And I’m a UX person, I’m an IA, I think in terms of structure and models more than I think about all the different specific things that go into a visual language. But talking to the visual designer and working with them to combine all those parts oftentimes is sort of when the “boots are on the ground” and really where a lot of that positive creative friction can happen.
I’m wondering, how do you work with other visual designers to help them transition into this modular mindset, into this way of thinking to dissemble all the different bits and it’s not a full page composition but a lot of parts that need to fit together?
Daniel: Yeah, the tool we’re using now, Pattern Lab, which allows us to create this living style guide—we watched a presentation here at Forum One, Brad Frost kind of going over Pattern Lab and this tool that he was presenting, and my initial reaction, I looked over my notes that I took over this, was very skeptical. “How can I possibly know what a heading level one is going to look like unless I see it living in the page?” Like, I can make the most beautiful heading or text, but once you put all these other LEGO blocks together, maybe it won’t look so great anymore. So, I didn’t embrace the concept of component-based design initially.
What I realized later is that you can still look at the whole, you can still start with a static design in Photoshop, Sketch, whatever tool you want to use, create like a basic page with realistic content based on whoever you’re working for, the client/internal, and use that as as starting point, and you have “This is what I want my pages generally to look like.” Then you translate all those components into a tool like Pattern Lab, then you have—because we want our heading level one to be the font Roboto, 20 pixels, whatever you want to use. And then you tweak and adjust; you embrace the idea that you won’t get it right initially. You’re taking a good guess and as the site evolves, as you put realistic content in or the actual content in, you start to realize, “Oops, this heading level one looked great with shortened sentences, but I’m realizing your average heading level one is going to be this huge thing, so I need to make it smaller, I need to adjust the line height.”
[15:00]
So, you’re not tossing out the idea of classical composition of the relationship between Object A and Object B. It’s still there but you’re just adding this extra element that you don’t have control or you’re embracing the idea that the client, using a content management system, is going to maybe turn this widget off, turn this widget on, put a huge amount of text, put a little bit of text, add an image, not add an image—all this stuff, you account for it and plan for it. So, it’s kind of using the skepticism I had. I communicate that to designers and reassure them in the same way I was reassured, that you’re not necessarily tossing out the way you did design before, you just have to think about it a little differently.
Nathan: Yeah, without a doubt. I find myself identifying with you because we’re on client services, too. We have a really strong relationship with the content managers and the publishers and hopefully all the developers and QA—all the different people participating in building the experience.
But I suspect, Cyd, your relationship is a little bit different because you really have this Code for America—unless you can talk to everybody that’s in America building a website—you’re really freeing these people with all these reusable bits and then just trusting them to put them together the right way. Does it always work?
Cyd: It isn’t always perfect, but it’s always pretty good. So interestingly, not everyone who works for Code for America is a techie or a designer by any means. And so with our own style guide, which by the way is also open source and if you want to check it out it’s at style.codeforamerica.org… We have lots of people here composing pages in GitHub using the style guide without any design training or any tech training either. And it comes out—sometimes there’s a page where it’s like, “Wow, that’s a little wonky, I wouldn’t necessarily put the proportions that way,” but it’s closer to on-brand than the people would have come with the resources that they have, and generally non-designers will look at it and say, “Okay, great.” And of course then we go back and say, “Oh hey, maybe we can treat this page this way, and is that something that we should then check into the pattern library and change?”
Same thing in the governments that we’re trying to help with this. If you look at, again, go to your city website, whatever the city is, google search for “City of X” will bring it up. It’s usually not looking great and often not looking consistent because people will get different designers to do bits for them and kind of “Frankenstein” it together. So, the fact that you can have this baseline set, not that they never need tweaking, but of elements that look good together, that look good at different sizes of screens, where the colors have been chosen and the fonts have been chosen with some thought to work together in a system… Yes, you can use the pieces wrong, but it sort of predisposes you towards getting it right, if that makes sense.
Nathan: It does, but you start to get at “Whose responsibility is this anyway?” Because I think about the variety of people that you’re talking about that are at Code for America, the variety of disciplines that I work with on a day-to-day basis, particularly developers and visual designers and product managers and so on. Whose responsibility is it to build this style guide and whose responsibility is it to have their fingers in the code?
Sophie, I wonder if you could relate a story or two about how you balance all the different concerns and perspectives, and does everybody play nice together?
Sophie: Sure. So, I am a designer foremost, and previously I didn’t do much front-end development at all, and what I would do is just work really closely with a front-end developer and it was my responsibility as the designer to document what the patterns were, to decide how we were going to be reusing them but not actually be in the code and coding them. But I do think ultimately it’s the designer’s responsibility to choose what the style guide or pattern library is going to contain and how those patterns are going to be used. Lately I found that it’s sometimes faster for me to just code patterns, and something I really like about pattern libraries in general is that they are this gateway for front-end development, so it’s a really nice bridge between different practices and I think it really helps front-end developers to understand design systems, and then it also really helps designers to understand how the front-end code is structured and where the similarities are.
Nathan: Yeah, I would agree. In the practice at EightShapes, we have a number of visual designers who have seemingly graduated up different levels of coding sophistication, where they don’t need to learn the differences between Grunt and Growl and set up all of their environments correctly; they have someone that can help them with that.
[20:00]
But can they get an environment set up, construct a bunch of pages, and then just start flowing text into pages, start opening Inspector to play with things, and then start building pages for a prototype, and then start going into what we call the “visual index” or “kitchen sink” page that has all the different bits of the visual system, often color at the top, and type at the top, and icons, but then all the prominent buttons, forms, and everything else. And then they start tweaking all those things because they know where the variables in Sass are, because they own the color value, the color choice in a sense, and I love that sense of empowerment because it puts people in the same materials working together, it’s really the material that the end-user actually sees. So, I get really passionate about that.
But at the same time, another angle with these online style guides is that they can be so diverse, they can have such different purposes. For example, some teams use it to project their own identity as a team. Some organizations outwardly say, “We use our style guide to publish it publicly so we can recruit great designers because we know how to do design well.” That’s a great part of the mission. But it also starts to conflate all these other things, the pillars of your organization all the way down to code and accessibility, coding manual or editorial or what have you. I wonder, how do you guys think about—and Cyd, if you want to talk about this—around the different constraints and concerns that you build into your library or that you choose not to—what things do you actually try to put into your online style guide?
Cyd: Yeah, that’s a tough one. I mean, it really depends what your top use cases are and I think to build an effective style guide, like to build most effective designs, you’ve got to know a lot about your users.
But as we talk to governments and as we think about accessibility heavily, imagine that that 15 percent of people who are mobile primary and their ability to access the internet are your most important users, because for a city those are the people who are most likely to need city services, right? And so take that as a really interesting constraint on your design. If your top 15 percent of users that you really want to serve have low-end Android phones and possibly throttled data plans, because that’s how it works if you’re on a MetroPCS or an Obama Phone or something like that—it gets slower after a week and a half. How can you use that to create a design that is really spare and yet serves all the brand values that you need to hit as part of your design mission? I think it’s a fascinating challenge and I’ve seen good visual designers just really bite into it.
Nathan: That’s interesting because there’s this comfortable tension we’ve found at EightShapes around “What do we put in our prototypes as the design is unstable and we’re evolving it?” versus “How do we code the thing for production grade?” really so it can be implemented and it has all the other specialized concerns of progressive enhancement and accessibility and other pieces built into it.
Daniel, I recall a story you had mentioned to me earlier around accessibility and how you can use parts that you put into your code library as teaching tools. Can you tell us a little bit about how you integrate things into your code or into your documentation to help teach people those diverse concerns?
Daniel: Sure. In your pattern library, you can obviously maybe hardcode deep level the font you’re going to use—we agreed we’re going to use Open Sans, Roboto, whatever; we can agree this is how the image is going to look, here’s how the caption is going to look… What pattern libraries don’t always capture is the education. A good example is the alt attribute in your image. When your image can’t be displayed and then accessible technology will read the alt attribute inside the image tag and say, “This is a picture of a cat” or what have you, you still need to educate whoever is controlling, whoever is uploading the images, whoever is maintaining adding the alt attribute, how much description, how much is too little, how much is too much. Do you want to say “A picture of, a photo of…” or do you just say, “A cat,” do you say, “A cat sleeping,” do you say what breed it is? Like, all this stuff, unfortunately there’s still a human element that still needs a bit of education, so.
Nathan: That’s great. I think about how we use our library to really prototype content. Once you get all the scaffolding set up and all your componentry wired, then you start injecting different types of content into it repeatedly, repeatedly, using templates like Mustache and what have you, or Handlebars. But I’m wondering, to challenge you a little bit: how does accessibility or an alt attribute, how does an online style guide give you a better platform to do things like that?
[25:00]
Daniel: Well, one of the classical style guides, like for a brand like Nike or something, the way it’s been done for a long time is you’d have maybe a PDF, and it’s like here’s how you use the logo, here’s how you don’t use the logo. Style guides are transitioning more and more to online. Like here at Forum One, we use an internal style guide that’s on the website, you go in there, you see all the proper usages. Google has Material Design and has the great Material Design online, and they show: “This is how you use it, this is how you don’t,” and people read it, they pay attention to it. That’s where you can put in your education. Like, “not only should you not have the logo against black, this is what you should do with your alt attribute. Here’s the right example, here’s a wrong example…” It’s a fantastic opportunity to educate when you’re putting these little constraints as to how you need to use things or how you don’t need to use it, including these little things. So, I think that’s where it really is of great opportunity to kind of evangelize accessibility.
Nathan: That’s great. I want to finish with what might be a potentially deep discussion around how this online style guide really blends with other codebases. I drew upon the contrast of prototype-level code versus production grade code and how we sort of build in from one to the other.
Cyd, I wonder if you could talk a little bit about how your style guide ends up coexisting, gets translated into, essentially gets left behind when these organizations that are really disparate start to use it over time. How do they keep track even with updates of what you do?
Cyd: Yeah, it’s interesting and I think each of them ultimately, as they grow, should build their own. But depending on what CMSes they might have in place, they might have a very different relationship to code and different people writing content might have a very different relationship to code. I think one of the really interesting things about style guides, especially online ones where you can just cut and paste the actual code for something, they start to break down that dichotomy between “Well, I have the content over here, and if I’m writing content I just write it and then I hand it off to someone else to put it online or to put into code,” and it actually empowers me to have access to the code in a very unscary way because it’s like I can just look at it and say, “Oh, if I want this red slab section of this page, I just copy this piece of code and then I fill in my content here.” And we’ve seen that really start to level up people who haven’t had a close relationship to code or any relationship to code.
It gets tricky to integrate with very legacy CMSes, so we are working with organizations that may be Kentico, or Ektron, or Oracle Site Studio or some of these older things where it’s really text in a box. But anywhere you can paste HTML, you can grab the HTML and CSS from the style guide. It works much, much better with a modern CMS along the lines of a WordPress or a Drupal where you can integrate some of that with it. But it’s still doable.
Nathan: Sophie, I wonder if you could reflect a little bit about the relationship of the code that you have and the ultimate delivery of the product and how it lives over time.
Sophie: Sure. So, kind of the point of putting together this pattern library for use in the first place was to make sure that we aren’t repeating work anywhere and that we have one central repository of design elements and code. So, it’s important to us that we use that same front-end codebase for the product itself. So the way that we have it kind of set up is that they’re on two separate tracks—pattern library, which has all of the design and front-end code is on one, and then the product itself is on another—and that just pulls our CSS in. The JavaScript is where it gets a little confusing because it’s in both places. But the CSS—
Cyd: I have to ask, is yours similar—like our pattern library is a branch of the main GitHub repo for the website that just stays as an independent branch.
Sophie: Ours is a separate repo as part of their build process, it pulls just our CSS file. So, they’re not pulling anything else from our pattern library.
Nathan: Interesting, we’re totally geeking out on GitHub repos now because I have a totally third way that I do it!
Cyd: [laughs] Oh!
Nathan: Like, we worked with Marriott for about two and a half years as they went responsive, and so we worked on their header and footer, their nav shell, we worked on their shop and book reservation path, we worked on their hotel websites, the property pages for each of the different hotels. And so each of those was a different project, but there was this design system at the core of all of them, and since we had the benefit of working on multiple projects, we actually had a submodule in GitHub that we would then essentially inject into all these project repos.
The development teams didn’t really reuse a common codebase as far as we knew, or at least we hadn’t established that part of the relationship. But at least a development team would see the project and see the library essentially as a subfolder, as a submodule, and be able to see how we took parts from the core and instanced them, or evolved them, essentially creating other stuff from scratch. So that almost was a cue to them around “What’s reusable? What’s part of this cohesive core?” versus “What am I just building for my project that I won’t find anywhere else?”
[30:00]
Daniel, I wonder, do you want to expand on that in terms of how you’ve used Pattern Lab?
Daniel: Yeah, currently we keep the Pattern Lab in the same Git repo as the codebase. In the future, we’re hoping to kind of have it so that the code, all the visual changes you make in Pattern Lab automatically happen in the Drupal site. Currently, it kind of has to be manually updated. But the analogy one of our front-end developers, Dan Mouyard, uses is “Pattern Lab is clay and Drupal is stone,” that it’s easier to use Pattern Lab as your playground and then take that and put it into Drupal pretty quickly and easily. And then our visual designers have really enjoyed having more control in Pattern Lab to check stuff out in GitHub and make changes to the heading, to the body, to the images and then check it back in with comments. Like, that was something that was kind of missing a little bit before, where it was a bit more waterfall-y.
And since Pattern Lab is visual, it’s right there on the website, you know you’d be like “dev dash whatever slash patternlab,” you can show the client, you can show your project manager, you can show everyone and then you can demo it on a phone, on a TV even, and see like, “This is how you can access your website without a mouse. If all you have is a remote control, this is how you’re going to be able to register for an event.” So, it’s a good demo of accessibility even if not reading detailed instructions. You kind of show them how this is going to look on different devices. So, it’s a great tool just because it’s so visual and because it gives control to the designers and gets everyone involved in the process and makes it less waterfall-y, which is always a good thing, I think.
Nathan: That’s great. We’re going to transition now. It’s the bottom of the hour and we have a huge stack of questions to get through. We’re hopeful we’ll get through six to eight, maybe ten. So, I’m going to start with a pretty simple one and throw it to Sophie: “Is there a difference between living style guides and pattern libraries?”
Sophie: I’m not sure exactly what you would mean by “living style guides.” The way I see—I’m assuming that means that they’re repeatedly updated and likely use the same codebase. The way I see the difference between style guides and pattern libraries is the pattern libraries have every single UI element, where a style guide doesn’t necessarily need to include everything. Like, you could have a style guide that’s just describing fonts and colors and that still counts as a style guide. And then also the way I see pattern libraries is that it’s generally always production code, where a style guide doesn’t need to have that. But I don’t think there’s an official right answer.
Nathan: I think this is a core part of the challenge with online style guides too, because the way you interpreted both parts of that question, I interpreted them a completely different way.
Sophie: [laughs]
Nathan: [laughs] Because people use these terms to refer to things. To me, patterns are abstract principle-based constructs that you can reuse, like a master detail UI pattern, like we have a list on one side and a detailed panel on the other. Yeah, sometimes they’re transformed into production grade reusable bits, but to me a pattern library is a bunch of abstract stuff that isn’t really prescriptive and style guides sometimes can be misinterpreted as it’s the 20-page PDF that has your logo, type, color, iconography, photography and other visual tone that you want to set. And when some people say style guide, they’re really thinking about just that stuff as opposed to “big reusable codebase, the mini-Bootstrap for my company,” and then people’s expectations totally change.
Cyd, did you want to chime in on that too?
Cyd: [laughs] No, I’ve just heard it both ways, and I think we’ve tried out other terms besides “pattern library,” because of course there are some universal pattern libraries there, and I think still if you google “pattern library” they’ve got some of those UI pattern sites and so forth that are abstractions. But we keep referring to our style guide as a pattern library because that’s how people actually use it. Like, I need a design pattern for this. I go to the library and I get it, I copy the code and I paste it, just like we all did on the web in 1995, honestly. It’s the best affordance that you have sometimes for learning how to do new stuff. I grab the code, I paste it, I see if my page worked. Hopefully if we did it right, it did. So, I kind of access the library and get what I need.
Nathan: Alright, Daniel did you want to chime in before we move on to the next question?
Daniel: No, I’m not sure if there’s anything I can add other than—to keep clarifying the last point I was saying—that some of our projects are already doing the one copy of CSS, one copy of images and JavaScript so that it shares it between Pattern Lab and the actual Drupal theme. But we’re kind of in the transition process and moving everything into that.
[35:00]
Nathan: That’s great. So the next question, and I’ll answer first and then one of you guys can jump in: “One thing we’re facing is choosing the level of detail to document patterns. Any recommendation on meeting this for different audiences, from exec. product managers, even developers?”
I actually have some experience doing user research on online style guides, and as it turns out, it’s great to know your audience and do your research and actually show it to them and get their feedback. A couple of things that I’ve learned over time is, number one, pictures always trump words. People want to see examples, they want to see do’s and don’ts with red and green next to them—green to do, red to not do. Material Design does a really good job on their site to show with examples and we actually built tools so that we can embed components and even embed scaled tiny framed pages to contrast them against one another. Iframes, it’s crazy, I don’t get it. Anyway…
Cyd: [laughs]
Nathan: The other thing I would say is make the words count, because when folks come to a color page, everybody in the usability test when they came to the color page said: “Why do I have to read this huge type introduction that talks about strong, saturated, vibrant, all these characteristics. Show me the damn color values! What’s the color of red? How can I copy the color of blue? Am I allowed to tint it? What are the contrast rules? Can I not show this light grey on a white background?” And when they talk about contrast, they want to see a grid, all the colors, the backgrounds and foregrounds on a big grid and big X’s or check marks around which you’re allowed to use. So, make the pictures and the words count. Don’t be overly verbose.
Let’s go to Sophie. Do you have thoughts on how much detail to document?
Sophie: Yeah, I think what you said about who is going to be using it is the most important part, and I did a style guide a couple of years ago where it was actually two different teams who were going to be using it. It was the client-side development team and then also the client-side content and marketing team. What we ended up doing is just making two separate style guides because we knew that the content team really didn’t care about front-end code and accessibility and all of that stuff, so they had a place to go and then the development team had a place to go. I think any way you can not throw everything at everyone and really make it pointed is helpful.
Nathan: Cyd, what do you think?
Cyd: Yeah, it’s a good one. We’re constantly coming up with new use cases, so you kind of want to have everything there. I almost feel like I’m going to fall back on a general web design principle, which is you want people to be able to drill down to detail but you want to present the basics. If I just want to get an article up and I want the colors to look right and I want to style a photo properly, it should be really easy to get at that information. And some of our style guide is organized in sample pages, so you can actually go in and see the patterns that are used in the pages because that’s particularly useful to people, rather than the abstract way a designer might think about it, “Here’s the color page, here’s the image page, here’s the type page,” right? Organizing it in the way that they use it has been really useful.
Nathan: Yeah, that’s so true. For some audiences, they need to see the thing assembled first. You start with the composed whole, then you break it apart as opposed to starting with the Pattern Lab, huge list of all the different elements and they’re like, “I have no idea what this is other than just a bunch of stuff that goes on a page somewhere.” And so starting with the composed whole is a great teaching tool because then as you start to break those pieces apart and decompose it into increasingly granular bits, that really helps.
Daniel, any thoughts on how much to document?
Daniel: My general experience is that people just don’t care about lots of written documentation. I came from a place before where we’d have a 500-page requirements manual and nobody read it, it was kind of useless. I think people respond more to visual things. Like, you don’t want a 500-page instruction manual on how to tango, you’d rather see it. Like, here, show me the steps, show me… We’re visual creatures. It helps a bit more to have it that way, which is, again, why I like Pattern Lab so much is that we’re showing you exactly “Here’s a page type, here it is, look at it. This is what it should look like. Here’s what it should look like in 300 pixels versus 1,000 pixels,” that sort of thing. So I mean, you certainly should document some things but I would lean toward visual examples over long, drawn out requirements documents, just personally.
[40:00]
Cyd: One other thing that we’ve recently done so more research with government folks specifically around markdown and composing pages, and one of the really interesting things that we found that I think a lot of listeners might find useful, is that using real words rather than design words and using them with great consciousness can really help people understand what they see. If your style guide is in the front end where you see it visually and then you click to get the code and it’s labeled with what I call “plain language,” what this is, it really helps people understand and be comfortable with the pieces that they get out of it and then be able to use them.
Nathan: It’s interesting, can you provide an example of a “design word” versus a “plain language” word?
Cyd: [laughs] Well, I’ll provide an example of a use of a design word. So, we were showing someone a style guide that had the simple convention of a hash sign and then a headline that you would have composing in markdown, and we had “hash headline.” But for a different thing, we had an address pattern and we had, you know, “colon address” and a pair. So, she couldn’t figure out—you know, it showed it, it showed the headline rendered properly in the typeface and weight that it should be, but because it said “headline,” she was really confused about what part was actually the code that she needed to add and what part was the actual headline text itself.
And so when we said, “Well, what if we changed this? It’s a convention to use that hash, but what if we just make this a pair tag and it said ‘headline and text’ inside it?” She said: “Oh, that’s much more clear because I’m not understanding that hash, I’m just understanding that this is a headline. But I was really confused by the fact that you rendered both at once.” So, it was a simple choice we could make. [laughs]
Nathan: You reminded me of the distinction between component codes and component names, too, because often times we want to create IDs that are very quick references for those that understand the system really well. We did a lot of work with Sun Microsystems in the latter half of the last decade, rest in peace…
Cyd: [laughs]
Nathan: They had the best—still to date that I’ve ever seen—the best component library and it was all an online style guide in a public URL that everybody could see and people would copy it and make sites that looked like Sun.com. But one of the things that they had was each component had a plain language label, but their teams used that stuff so much that they also had the ID for—like their sidebar component started with “S” and so there was the “S13.” And so everybody would be like, “Oh yeah, just throw an S13 on there. That’s the kind of promo you need,” and when you start on a project, you don’t understand what the hell they’re talking about because they’re talking in all these component codes.
But then the language, or the coding of what the design system is, starts to really make everybody’s communication more efficient, and so you just have to think about what’s the bridge to get people that use the system so often to talk more efficiently about what it is, because plain language can sometimes be really verbose.
Cyd: Can be super wordy, yeah. But it’s an entry point.
Nathan: Yep. So, let’s transition to the next question from Brett Jankord. Sophie I wonder if you could start us off with one or two tools that you use to create style guides. Do you roll your own? What makes your workflow really efficient? What one or two things could you talk about that has really helped you work better?
Sophie: We don’t use any specific tools for style guide creation. Can you hear that? There’s thunder in Austin… So, we use—it sounds silly, but I think GitHub is like the biggest great thing for this, it keeps our team in sync with each other, we use it for communicating back and forth. We couldn’t do it without that. Then we use Gulp for compiling. But we’re not using Pattern Lab. I think the main reason is just because we want to keep it as basic as it possibly can be and not bring in any outside pieces.
Nathan: Interesting. So Daniel, how about you? Other than Pattern Lab, because we know you use Pattern Lab, what other tool or two do you use to improve your online style guide workflow?
Daniel: Well as you can see behind me, just paper is fantastic; I’ve seen visuals with LEGOs. Like, it starts really at the client for us, I think; that if the client doesn’t understand the importance of the patterns and the different modules that are there, then we’re going to build something that isn’t going to be great. That’s another thing I didn’t add about the giant requirements documentation. You can have 500 pages of requirements documentation telling you how to build a submarine that will sink exactly step by step, “This is exactly how you make it so it’s not going to work.” So, if the assumption at the underlying get-go is wrong, then what you build is—while it’s exactly what the client asked for—it’s not going to work.
[45:00]
So starting from the very basics, paper and pencil, we still use it, it’s very beneficial; actual LEGOs, whatever it takes to educate clients or internal stakeholders. Like: “These are the different modules that are available, here’s what we recommend, here’s how it’s going to be used.” So besides all these digital tools, doing old-fashioned stuff I think we’ve found has been very beneficial. And interestingly, Google Material Design, like if you check out their website and videos, they did a lot of actual cutting out of paper to create some of the early concepts of their user interfaces and iconography. So yeah, I think going back to old-fashioned stuff is a great tool to use.
Nathan: Awesome. Cyd, how about you?
Cyd: Well, when we were first developing it, we actually started with Google Drawings, which is a great place to share sort of really rough wireframe-level ideas. And then some of the design was actually done in Photoshop or Illustrator, but it all comes down to GitHub in the end and we’ve definitely got a team of folks here who are passionate about designing in-browser and working in GitHub so that they can iterate on each other’s stuff as quickly as possible.
Nathan: Awesome. I will share one that we grew at EightShapes, called EightShapes Blocks. We use it internally for two main things: it’s actually a component loader based in JavaScript only so it works on the client, but it takes all the modular bits from that submodule library, for example, and it injects them into the page; it knows the right variation to pursue, it adds special classes for the context you’re adding it in. So, it’s essentially a loader that has a lot of extra bells and whistles built into it so you can reuse things with a lot of different intents.
And then the other thing we have, we call it Framer, it’s that iFrame thing, but you can essentially take a page or a component in a certain context of a page and inject it as an iFrame into another page. And so that helps us with a style guide like we built for Marriott a couple of years ago in WordPress. We could still take our component library, which is a separate repo, and for the page describing this bar that is like the brand of the hotel—we have like 30 different content variations that show different colors and brands and stuff—we just injected it into the guidelines page and suddenly it synced with what we’re maintaining rather than the static screenshot pictures that need to live in a WordPress article. Just develop a shortcut, use our little framer and it takes a lot of our bits and propagates them further than they otherwise would be able to.
Sophie: We have a similar thing with markup where as part of our Gulp build we have HTML partials so that we’re not having to code things multiple times, and that inserts it into all of our layouts.
Nathan: And that starts to get at—you build things and you don’t create a build process unless you’re going to build them again, and again, and again, and again. So Eamon Rodeck asks: “What is the decision-making process after the initial site has been built using some sort of pattern library, but as it evolves new needs are required? How do you decide if a new pattern gets added or if an existing pattern gets used?”
Daniel, do you want to start us out? How do you decide whether to build something new or reuse something existing?
Daniel: Well, I think this builds a little bit on the question that I think I see a little bit above, that question that: “Is there a difference between style guides and pattern libraries?” I think the pattern library, again going back to Pattern Lab, it has atoms, molecules, and organisms and it has “page.” You click on “page” and it’ll be like, “Here’s an event listing. Here’s an event landing. Here’s a general landing page.” So, there’s patterns there of like, “Here’s what you have existing.”
I think the style guide is kind of what informs how to create new patterns, and in terms of deciding when you need to create a new pattern, do any of the existing patterns we have here that are listed that you can see that you can click on—will this not work for the new need? Maybe there’s a conference coming up. Is our current event landing, is there something that’s missing or lacking from the event landing that won’t work for the special event you want? If there’s a really, really good justification for creating a totally new element that didn’t exist, that’s when you decide to create a new pattern. So, event landing—”Here’s event landing B that, for whatever reason, needs to be different than what we already established,” and then when you create event landing B, you refer to your style guide to say: “This is how it’s going to be visually on-brand or consistent with what we’ve already created.” So I think in my mind that’s sort of the difference between living style guides and pattern libraries, and then also how you decide how you’re going to do that, create new patterns.
Nathan: Sophie, how about you? How do you decide when to add something new versus leverage something existing?
[50:00]
Sophie: I think having a pattern library prevents you from ever adding something new that you don’t need, so it’s really great to have that as a reference. Whereas if you don’t have it all in one place, if you have a bunch of pages, it’s easy to forget about patterns that exist and then end up making a new pattern that’s just a very slight variation. And then before you know it, your design system is kind of a mess. So usually what we’ll do is we’ll think specifically about the user needs, sketch it out, and then once we have it sketched we can see which patterns we can pull to use. And if there aren’t any to pull to use for that interaction, then we know to build a new pattern.
Nathan: And Cyd, I wonder, what I’m most curious about from you is when you think about those existing patterns and how you already have Code for America, you have a wide range of disparate people and I can’t imagine how inundated you are about how each of those different groups wanting their own special little thing getting integrated into it. How do you manage expectations to inject new things that may only matter to a very narrow set of people?
Cyd: Well, I think actually Sophie and Daniel have said a lot of it. If we have a pattern that is close, then there’s a decision we can make rationally around “Will this pattern do it? Should we make a universal change to that pattern?” Because it’s all GitHub and if someone is part of the Code for America community group, they’re probably pretty high capacity, they can write an inline style to tweak our pattern a little bit and we’re not holding them closely to a brand in the same way that you might if they were part of the same company. So, we’re okay with that in sort of an experimentation and open source way.
But then adding a significant change to our pattern library, like… Well, we recently had—and you won’t believe we left this out in the first place—we didn’t have a pattern for screenshots. It wasn’t a priority when the site was designed; we had other photo treatments. And so our photo treatment carefully darkens, has all this code to style photos as if they were all photos of people. So, we started having the wrong things happening when we started posting screenshots for up-and-coming products. So, that was an obvious choice to design something new; we had a use case that we didn’t have before. A different style of calendar or something you really want to see if you can make the one that you have a little bit more flexible without breaking where it’s already existing… It’s definitely a balance. I really can’t give you a universal rule.
Nathan: When we’ve managed libraries for a longer period of time, we always hit that moment where either you’re on the precipice of or you’ve already jumped off the ledge, realizing: “Oh my gosh, we’re wasting so much time in that stupid hero carousel for this one case that, number one, only one team is going to use, number two, it’s a terrible pattern because it has all sorts of usability flaws. Why are we doing this? Why are we spending all of our time doing this?”
Cyd: [laughs]
Nathan: So, what I find interesting around “create new or use existing” is often: “Is the pattern actually the right one that you need for that particular instance anyway?” and helping people understand not just the relationship of them to the library but their relationship to making good design decisions and how the library potentially reflects that good judgment.
Cyd: Yeah, and intention. I mean, it really is a place where you can say: “Well okay, what is the intention of having something different?” and talk about whether that’s something that’s valuable to your user or not.
Nathan: And it gives you a platform too to have those conversations in hopefully a less confrontational way. If they’re required to use the library, sometimes that conflicts with product needs, what have you. But to ask those good questions and then have them challenge you I think makes it a more healthy, trusting relationship between the two parties, too.
The next question I wanted to shift to was about keeping in sync, and we’re going to finish with this one. Some of us don’t necessarily control the developer, so some of the different product teams that take our pattern or online style guide, and use it to build stuff and they may translate it, they may extend it, or god forbid like we see sometimes, they build it from scratch again. But how do you then—what’s a mechanism that you use in your practice to keep your stuff in sync with their stuff? Daniel, if you could start.
Daniel: Their stuff? What did you mean by “their” again? I’m sorry.
Nathan: If you are delivering to a team that is going to take a codebase that you have that is essentially the online style guide, a bunch of reusable bits, but then they start overlaying their stuff, they start integrating it into their own CMS or they do things to transform it in a way that they can’t just take a revision of yours and place it into theirs, what do you do to help mitigate that challenge?
[55:00]
Daniel: Well, ideally everything would be—the deep-level things—would be controlled by whoever has been in charge of the development, in this case Forum One, who if they built a site, anything high-level would be done by the same firm or company to keep things in sync. If not, and I think that’s kind of a small weakness of agile methodology, that it doesn’t document as heavily. Like, I was just kind of going against these 500-page documents, but if you hand off a site to someone else, that’s where something would be a little bit more useful.
Unfortunately, it’s just hard to control it. If you’re an interior designer, you build the most awesome house, you do the landscaping, you do everything and then you hand it off to the homeowner and then they decide to make all these changes themselves and completely redo stuff, unfortunately it’s their house, it’s their property, they can do whatever they want with it. So, I don’t know… I don’t know what you could do besides having some sort of police and enforcing them and punishing them. People are free to change as they see fit. So, you just hope that whatever you built is so well-documented, so logical, works so well that there’s little reason for someone to go over and make extensive changes that differ markedly from what you initially delivered for them.
Nathan: How about you, Sophie?
Sophie: I think the last point that Daniel just made, which is hopefully if you’re writing your code well or setting up a system that works, it shouldn’t have to change. So, I think that’s a little too good to be true, but in an ideal world that would be the case. But in terms of our workflow, we have kind of a system of checks and balances. So, if a back-end developer wants to change something in our front-end code, they can do that but it gets reviewed and accepted by one of us. And then likewise, every time they have a release of the actual app itself, we have a designer or we have a dedicated testing team test to make sure that everything is looking as it should, and if it’s not then we work together. So, we kind of always… we have things that we own, but at the same time we’re reviewing each other’s work to make sure that they’re staying on track and staying connected.
Nathan: I reflect on that in terms of two different scenarios. One is the design solution we build, hand off, and then walk away, and often times a design system in this online style guide is something our clients don’t even choose to buy; we manifest it and it’s a deliverable at the end. We recently worked on a site that launched responsively a few months ago and the developer took a lot of our style, like 90 percent of the CSS, and probably just adopted it in total and then started to manifest some different handles, some different hooks into their Drupal markup that had constraints, and they I think used a lot less of the markup. And so the CSS became something that was easier for them to reuse, but still at least the way we had architected the taxonomy of the system, it became a way to collaborate with them and talk about increasingly small changes they needed to make. And the visual QA process for that site took something like 15 minutes a page. It was really easy because of that transition.
The other thing: we worked on a large intranet for a tech company for about four years, and we found that since we had such a large library of around 250 components, around 50+ page types that we evolved over time, there was always this retrofit, that as a project would launch we take those and put them back into the library core. And so there would be an investment they were making until they, you know, cut it off because the property diminished in value. But they would make an investment to blend in all those project-specific changes into the library over time, and so it became an investment, it became really its own mini-project at the end of each project.
So, we’re almost out of time. I have one more quick question and then I want to do a closing 15-second “What are your closing feelings on something that really resonated with you?” We’ll go Cyd, then Sophie, and Daniel. But Cyd, I think it was you that said “Obama Phone,” and somebody asked the question, “What the heck is an Obama Phone?” and I agree, I don’t know what that is. So, if you could start with the Obama Phone and then give us one reflection on today, that’d be great.
Cyd: [laughs] Absolutely. So, you may be familiar with it, it’s existed for probably 60 or 70 years, the Lifeline phone program that lets people who are in an economically disadvantaged situation get a very simple phone service. The current administration in Washington has expanded that because of the acknowledgement of how important mobile phones are to getting email and all of that, and you can, if you are receiving other public benefits, get a very simple cellphone with some smartphone features through a public program that is commonly known as Obama Phone. It’s a low-end Android, it’s really not a great phone, but it’s a heck of a lot better than nothing.
Nathan: All right, so what’s your reflection on today’s conversation?
[1:00:00] Cyd: It’s been so fun to geek out with all of you, and everyone listening: I encourage you to dive into this not with fear but as something that can bring a lot more power to your design and allow you to serve a broader base of people, which whether you’re in a commercial organization wanting to get more customers, whether you’re in a more public-facing organization wanting to do a wider service to the world, it’s probably something you want. It’s really powerful and I hope you will.
Nathan: Awesome. Thank you so much for your contributions. Sophie, how about you?
Sophie: I think the biggest takeaway just from talking, the four of us, is how differently we do things and how differently our audiences for the pattern library or style guides are, and different processes. So, just that there’s no right way of doing this and every single project is different and it’s always important to think about why and who you’re making this for.
Nathan: Absolutely, that’s awesome. Thank you so much for everything, Sophie. Daniel, how about you?
Daniel: Well, kind of riffing off of Cyd’s topic of the Obama Phone: there was a presentation at Generate Conf in New York in June called “I Don’t Know What the Hell I’m Doing” by Brad Frost, again, the Pattern Lab guy. He was saying you have to assume that when people visit your website, they’re using the lowest possible connection, the crappiest browser, all these things—you can’t assume that they have the latest of everything installed. And accessibility is not just people who are blind but people who don’t have an iPhone 6 and who have a first-generation Android. Can they still access this essential government activity, website and services and things like that.
And so, I think it’s great that so many people are interested in style guides and pattern libraries because I think, as I was saying earlier, it’s a great tool for evangelizing and teaching the importance of progressive enhancement, accessibility, building sites that work great, future-proof ideally, that have consistency… I think everything is positive about it and I think it’s bringing all of the different sides of website development together, from the UXers to the visual designers, to the front-end developers to the back-end developers, to the clients. So, it’s great. People are experimenting, trying things and we’re going to find consensus and find things that work and talk about it, so it’s wonderful.
Nathan: That’s awesome. Thank you so much, Daniel. My reflection on today was just that people are thinking about the right stuff and addressing the right challenges. There are a lot of questions around “How do I set this up? I’ve got to set up my system with tools and code and all of these different considerations…” but also some questions around “How do I sustain this thing? How do I sync it with other people working at the same time over time, and really how do I spread the word? How do I communicate it? How do I get other people on board? How does this really become a platform for people to work together?” So, that’s what inspires me most, is actually the collaborative relationships that emerge through libraries rather than the component bits itself, even though my book has LEGOs on the cover, and I love that you guys talked about LEGOs!
So, I want to thank all the panelists for joining us today, it’s been a great talk. And I also want to thank the viewers and all of your great questions. We’re going to be announcing upcomingALAevents on the website and social media. Event #4 is in the works, so watch for those updates. We’re also going to add the video of today’s panel to the site probably in a few days and the transcript will be posted at some point, maybe within a week or so.
Thanks again to Pantheon for being our sponsor. Check them at Pantheon.io. And really, thank you everybody for the conversation. It’s been a wonderful experience. Have a great day.
Daniel: Thanks.
Sophie: Thanks.
Cyd: Bye!
