Style Guides with Jeremy Keith

Jeremy Hellooo! I'm fine, thank you. How are you, Brad?

Jeremy Good. How are you, Anna?

Jeremy Good, good.

Jeremy Beautiful, it's gorgeous!

Jeremy Sure. I just updated my job title yesterday, as a matter of fact.

Jeremy I was… I'm currently Shepherd of Unknown Futures.

Jeremy Yeah, I thought that sounded good. Andy Dennis gave me that one. Before that, I was, I don't know, Commander of the Armies of the Seven Kingdoms, something like that. So generally, I don't take much stock in job titles. I don't find them that useful.

But in terms of describing what I do, my stock answer is really glib and I'm like, I make websites. Although these days, there's so much involved in making a website that that doesn't really tell you anything at all.

Historically, I guess I've been involved more in the front end side of things; HTML, CSS, JavaScript, all that good stuff, but also I've done web design, I've called myself a web designer at times; a bit of everything really. Generally at Clearleft, I guess my role is, yes, on the front end development side of things, but more in a kind of strategic over-arching way, as opposed to not necessarily having my hands down in the code, coding stuff for deliverables. Partly that's because I'm just not very fast at doing that stuff, I take way too long to do anything and so it wouldn't be a very good use of my time. The other people at Clearleft are much quicker at doing that, so it's better to have them do that.

Also, I get bored so easily I just find myself flitting from thing to thing, as a way I guess of turning that to an advantage, my job is kind of flitting from thing to thing on a daily basis; checking out stuff, letting the other people in the company know about stuff I've stumbled across, feeding that into the work.

Jeremy Code reviews, that kind of stuff. We have a Front-end pow-wow every Thursday where we talk through stuff on the front end development side of things, but I honestly don't know what my job is.

I'm doing client work as well but I'm not exactly clear what I do. I guess a lot of people would talk about their work in terms of their output, so a UX person might talk about wireframes or visual design; they might talk about Photoshop or Sketch and a front end developer would talk about HTML and CSS but I generally don't have many outputs. It's a lot of talking and yakking and thinking.

Jeremy Yeah. On the one level it's purely an implementation detail, it's like whether we hand over a pattern library or whether we're handing over something else. At another level it's kind of fundamental to how you approach thinking about deliverables, how you approach thinking about the interface. Depends how you come at it.

For the most part, people don't hire Clearleft for pattern libraries or for any particular deliverable: they're hiring Clearleft for design work. Not necessarily even visual design, UX and more like thinky-thinky stuff, I guess. But when it comes to the front end, if we do end up doing front end code for the client, then time has taught us that handing over a pattern library or style guide type thing is definitely more valuable than handing over a set of pages, for example.

So a lot of it's kind of systems thinking, which has been evolving for many, many years at Clearleft. I know Anna's mentioned Natalie Downe, who used to work at Clearleft and now she's at Lanyrd, bought by Eventbrite. She's an amazing front end developer and she started talking and thinking about this very systems-thinking approach to CSS and HTML many years ago and we started putting it into practice in our deliverables; if we were handing over something, how can we hand over a system instead of just handing over a finite set of pages and expecting the client to extract what they need from those pages? How can we give them the extracted bits that they actually need to put together all the pages that we couldn't possibly consider.

So a lot of that really started with Natalie. Because Clearleft doesn't ever do a full site build. For example, we don't do back end development at Clearleft, so we do UX, we do visual design and sometimes we do front end: not every project; sometimes. But we'd never do actual build, the actual back end PHP, Ruby, Python, whatever, and so over the years we've had to get very, very good at delivering our deliverables to the client, whether it's design stuff or whether it's front end stuff, because we're never the last people to touch this stuff: there's always somebody after us.

That was definitely tricky to do at first, but we've been around for ten years now so we've gotten better and better at doing it and this idea of a pattern library has definitely been, I'd say, the most important development when it comes to front end deliverables. Not entirely sure whether it works, when it comes to visual design and UX and that kind of stuff, but certainly for front end deliverables, the pattern library idea has been really, really strong and it's worked really, really well.

Jeremy I'm trying to think back to when we would have first started to do it. I think it would have kind of snuck in the back door. Initially yes, we would have still been delivering pages and we'd kind of throw in this collection of pieces as well: so it'd be more like the pages, the deliverables, but here's also this collection of the pieces cut out into their individual bits. And then over time, that's flipped to the extent where we make it very clear that this pattern library is the deliverable now.

We'll also give you some pages, but these pages, they're not the deliverable; these pages are just examples of the pattern library in action, and that switch has been a gradual thing over the years, I think, going from, we deliver pages and oh, here's a style guide to: we deliver a style guide and oh, here's some pages that use this style guide. That second approach is definitely, definitely more valuable, certainly for other developers taking over who have to build this thing and have to actually put it into action, that's definitely more valuable.

Now, it can be trickier if it comes to other stakeholders like the boss, the client, the guy who signs the cheques. Maybe they need to see more page-like things; maybe they prefer to have a shiny comp or whatever, and we might have to throw them a bone with something a bit shinier, but in our experience, developers really, really like getting a pattern library as a deliverable.

Jeremy Each project's different, so we don't like to have a set process or even a set set of deliverables for every project: it'll change on a project by project basis.

But, that said, broadly I think you could characterise most projects that involve some kind of deliverable as falling into one of two categories and the first category is that pattern library category of, we're going to do design work and we're going to hand over this set of components that you then take and you can put together into an infinite variety of pages of patterns and components.

But that's not the right solution for every project and broadly speaking, the other kind of project is much more where a prototype is going to be a better deliverable. And they're actually very, very different in how you deliver that stuff, because for a pattern library, we're saying, this is quality code; we've really thought about the HTML here and we've really thought about the CSS and we think this is the best little widget and component and you can just take this and you can drop it into your live site and it's going to be great, and the way you approach prototyping is the complete opposite which is, this is not production code; don't you dare drop this into an actual public website! This happens to be written in HTML and CSS and JavaScript, but it could just as easily have been written in KeyNote or some other tool.

What we're providing is a way of demonstrating interaction, of demonstrating visual design, of demonstrating animation, something like that. But we are not saying, this is code for you to use. So in a very, very broad way, when we're doing work that involves front end development, it'll tend to fall into one of those two camps: either this is code that's been delivered to the client for them to use in a live site, or this happens to be code, but the code is only there to illustrate the design and the actual final code needs to be written from scratch in a very different mind-set. So, going back to your question about the initial pitching on projects and discussing deliverables, we tend to get a feel pretty early on of which direction the project would be going, like, oh, this sounds like a job for delivering a pattern library; oh, OK, no, a pattern library is not what they need here, this is about some other kind of problem solving and we need to deliver a working prototype, to demonstrate the design but not to be used in production. So we tend to get an idea pretty early on and then I guess sell them on whichever one we think is the right solution there.

Jeremy There's nearly always mock-ups first. I guess the question is, how long you spend refining those mock-ups or how quickly you decide, OK, this is good enough to get going, right? And again, that will depend on the client.

On some projects, clients absolutely get it and they're like yeah, yeah, it's fine that we're not deciding in the mock-up.

There's that wonderful phrase from Dan Mall about deciding in the browser, which I really like.

Backing up a bit, the whole question of mock-ups, or why do mock-ups exist is, I guess, a philosophical question that we've been tackling a long time. I mentioned that we had front-end pow-wows every Thursday. There's also a Design Review, Design Crit that happens once a week. And then inevitably devolves into this discussion of process and workflow and all of this. And it's a question of what's a mock-up for? Why does it exist?

(Brad and Anna laughing)

This comes up.

Jeremy Yeah, this existential… here's my take, is that there's just three reasons a mock-up could exist:

One is that it's for buy-in, it's basically for sign-off. You're mocking something up to present it to a decision-maker who then says thumbs up or thumbs down, so that's this decision-making thing, I guess what Dan could be talking about, deciding in the mock-up. That's use number one.

Use number two is it's a deliverable for a front end developer, so in other words they're something a visual designer gives to a front end developer to get turned into code, so that's a separate use-case.

Now here's problem number one, is that mock-ups made for the first use-case end up getting used for the second. So, if you're designing for sign-off, everything's perfect: everything lines up at the top and the bottom, it's exactly the right amount… everything looks beautiful. It's not a real test of the edge cases of content. And unless you then make further mock-ups that are more accurate and reflect the real situation with content and you just hand over this perfect situation to developers, well, everyone's just going to get disappointed: the developers are going to be frustrated because it's not accurate, the designer's frustrated because, hey, that doesn't look like my mock-up, and the client is frustrated because that doesn't look like what they were presented with.

Oh, and then there's a third use of a mock-up, which is for a visual designer to think. They have a tool that they're comfortable with, like Photoshop, Sketch, Illustrator, whatever and it's the fastest way for them to get ideas down is to create a mock-up.

Jeremy Yeah, or even a full interface; even making a page. But the difference is that the reason for its existence is that third use case and not those first two. So, for a designer to go away and create, here's a page in Photoshop, or here's a page in Sketch, that's absolutely fine, I think, as long as the reason for doing that is to get ideas out. It's not then fine to then present that to a client and say, what do you think? Give us sign-off, and it's not fine to present that to a developer and say: there you go. Now go and build that. They're three very different use cases. The getting the designs out of your head, getting sign-off and a template for build. Those are three different use-cases. And yet what happens is, a single mock-up will end up kind of doing all three.

Jeremy So this is the problem I've found with mock-ups, we've found in general, is this mis-match, I guess, of expectations. And this is why I love Dan's idea of deciding in the browser, so for that first use-case, you're talking about deciding in the mock-up; you show the client to give you sign-off. The decision has been made. Then you move on to use-case number two where you're handing it over to a developer to turn into real code and that's when reality hits and differences crop up; questions come up that you hadn't anticipated, but now it's too late to make the decision to say, oh well, look, that's been agreed, that's been decided, that's what the client signed off on, so I really like Dan's idea of deciding in the browser where you say, yeah, you do stuff in Photoshop or Sketch or whatever you're comfortable with; it's more about that third use case, use whatever tool is comfortable with you. But you don't go to the client and say, approval or not approval, until you've got it in web browsers, until you've got it in code, because that's just so much more accurate to reality. So much more realistic, and makes much more sense to decide in that point, but going back to the original question, would there be mock-ups preceding the mark-up, I guess, the CSS? Yeah, almost always, there's almost always some kind of mock-up. Now, in an extreme case, that mock-up could be literally paper; could be pencil on paper. More often than not, it is usually a tool like Photoshop or Sketch, something. But like I said, there's definitely diminishing returns in polishing that mock-up too much, making it perfect because what's the point? The actual place to do that and make it perfect is in the code, when it's in web browsers, so the right level of fidelity I guess is the big question and that changes from person to person, from project to project, from client to client. I don't think there's a right answer. The right answer is to figure out what's the right level of fidelity for the mock-up for this project, for this client.

Jeremy Yeah, it's interesting. I think that the systems approach that came from the front end with people like Natalie thinking this way has definitely infected the visual design part as well: it tends to happen sooner. Even if it's almost retro-active: the designer maybe finds it easier to just go away and just design screens, interfaces, but that's retro-actively…

Jeremy Yeah, use-case three, exactly. But then retro-actively, OK, now I'll extract the patterns and put them together, and that's when they might notice inconsistencies in their own designs; oh, I thought this button was meant to be the same in all five screens but actually it's slightly different here and I'll need to adjust that and make it consistent. Because doing good design, it should be consistent, there should be a logic behind it. Yeah, there's definitely been more systems thinking happening on the visual design side and we've tried things like Style Tiles, Element Collages, these kind of things.

Jeremy Right, again, every client's different, every project's different and I was on some project where in showing them a document which is meant to show, here's a bunch of elements collaged together, the client was mistaking it for an actual page, which you could kind of see, it kind of makes sense that that's what our brains would interpret that file as, but as soon as Jon flipped it and made it horizontal rather than vertical, then straight away it was clear: oh no, I'm just looking at a collection of components one after the other, but they don't form a cohesive whole, it's just separate components.

So that was really interesting and that's something that Dan, because we got the element collage thing from Dan Mall, and he's taken that back on board himself: oh yeah, that's actually really smart and now he does that too.

So again, lots of experimentation, I would say on both the front-end and visual design side, we haven't got everything figured out and we're still figuring this out; there's definitely issues with the tools, some tools seem to lend themselves more than others. Even in small ways like with Photoshop, as soon as you go to create a new document, it asks you what's the width and the height of the document. That's a small thing, but straight away you start to think in terms of well, is it a mobile or a tablet or desktop screen, whereas something like Sketch is an infinite canvas. So it has a slightly different take on it, you can just throw things onto this infinite canvas, so it maybe lends itself a bit more to this componentised element collage or style tile way of thinking.

But like I said, the tools don't really matter, it's how you approach it. As for designers thinking the systemic way, I think good design tends to do that anyway because you start with a type system, is usually at the root of everything, and a grid system will come out of that but it's a system; it's systems built on systems, there's rules behind that and so good designs will have rules anyway.

I guess the difference is, making those rules clear and bringing them out and showing them. Like sometimes it's retro-active; well, let's slap on some translucent pink columns to show what the grid looks like. Nobody yet has decided to slap on a golden ratio Fibonacci swirl onto their design, so that's good, right?

Jeremy You know what I mean about the retro-active… oh look, it's a system; it's totally a system here! But you know, we're still figuring this stuff out.

Jeremy Why can't you just build it? Why can't you just do what I…

Jeremy So, what tends to happen on projects is that there'll be some lead in with visual design and the visual design would probably begin a bit before front end dev, although it's always good to have a front end dev around to just look over your shoulder and check stuff.

Then you have a period of both visual design and front end dev happening together, kind of back and forth where, get it into web browsers, look at it and maybe adjust the visual designs, but then there comes a point where it's like, it's not worth going back into Photoshop, Sketch, Illustrator, whatever your tool is, at this point; we just need to be doing this in browsers and there's no point, it's just wasted effort, to reflect those decisions and those changes in the visual design files because those visual design files aren't the deliverable: those are tools to get you to the deliverable, which is the final website.

So, it's different from project to project where that point is, the point at which you don't need to go back to the visual design files at this point; let's just sit together and make changes in CSS Web Inspector.

Jeremy Yeah, it's not for sign-off.

Jeremy Exactly.

Jeremy Like I said, at Clearleft I'd been thinking about the system thinking for quite a while and I mentioned Natalie, and when Natalie left we had Andy Hume working at Clearleft, a great front end developer. And he was giving a talk at South by Southwest a few years ago, about CSS systems; now this wasn't necessarily pattern libraries; things like OOCSS and SMACSS and BEM and all this stuff, just a way of approaching CSS in a more engineering kind of way, I guess.

But he did talk about style guides, the concept of style guides. Specifically he mentioned that the BBC had this GEL, this Global Experience Language, which the whole organisation uses. But he pointed out that one of the problems with GEL is that it's in a PDF and it would make much more sense for it to be in HTML, to be in the final medium.

It was quite fascinating: when it got to the Q&A, somebody stood up and said, "I'm from the BBC and I'm from the GEL team" and I was kind of thinking, oh shit, Andy's in for it now, but the guy was like, no, you're absolutely right, it makes no sense that it's in a PDF, it should be in HTML. Oh, thank goodness!

Jeremy After this great talk, all these people were coming up to chat to Andy about this, and I was hanging out because I wanted to congratulate Andy and say, great job with the talk, and so this guy starts chatting to me, says he's from Starbucks; it's Lincoln and we're having a chat and he says, you know we actually have a sort of style guide like the BBC thing except it is actually in HTML and CSS and my first question was, "Is it public?" And he was kind of like, no, he hadn't thought about it, so I was like, "Why don't you make it public?" and that's kind of my default reaction when people get in touch with me or come over and say, hey, we've got a style guide or pattern library or whatever, because I've been blogging about it and talking about it, my first question is, "Is it public, and can you make it public?"

And they did, the Starbucks guys made it public and I don't think they thought that much about making it public but boy, did that ever get press: it was like, wow, this huge coup for them, it was great, so I think they're very, very happy they did make it public.

And in general I just love to see people sharing things. Style guide, but in general I like when people blog, I like when people say, hey, I solved this problem and here's how I did it; this worked for me, maybe it won't work for you but I'm going to document what worked for me.

Jeremy Exactly. When I was first learning to make websites I was viewing source, I was on mailing lists, I was reading Ask Dr Web on zeldman.com; these people were just sharing their knowledge and I want to make sure we keep that and whatever new thing comes along in front end development or visual design or whatever, I like it that our default position should be, let's share this, let's just put it out there. Even if it's something that's clearly just for you; I link to style guides all the time. Just last week there was, let's see, Heroku put one live…

Jeremy GitHub updated theirs, they put theirs out there, and I say in the link, this is really only useful for the people at Heroku and GitHub but check out how they're doing it, to see how other people are doing it.

It's not that you're going to take that actual code, you're not going to take their mark-up or their CSS and use it in your own side, but to see how they've approached it and what the thinking was behind it and go, oh, I see, and that can influence your own way and what works for you is going to be completely different to what works for Starbucks or MailChimp or Heroku or GitHub, but the fact that you can look at these other examples is fantastic.

Jeremy Yep, and my general attitude with a lot of this is, it's easier to ask for forgiveness than for permission.

Jeremy Just go and do it and if you get flack from the boss, even though you're getting all this great, positive press say, oh sorry, do you want me to take it down now? And then you should say no, well now you've done it… that was kind of my attitude with stuff like the Open Device Lab, I basically just threw the doors open and said hey, anyone can use these devices, without stopping to think or check whether that was OK or what's the worst that could happen? It's more like, I'll just do it and see what happens and it's fine; everything's fine.

Jeremy So, that's a good question. In a way it's begging the question, because I'm not sure that the…well, first of all, let's step back a bit. The terminology here, I'm going to talk specifics about pattern libraries.

Jeremy Right. What's a style guide? What's a pattern library?

Jeremy OK, my take is, what we tend to be talking about at Clearleft because as I said, the audience for this deliverable we're building is other developers; it's not decision-makers, it's not designers. It's developers who have to actually put the site live. And for that reason, the best way I think to describe what we're providing is a pattern library; it is literally a library of front end patterns.

Now, a pattern library I think can be part of a style guide, and a style guide could contain other things. It could contain tone of voice; it could contain here are the colours, here are the font choices, here are… the classic style guide stuff around where the logo is positioned relative to corners…

Jeremy Right, brand style guides. So I guess a pattern library would be a sub-set, a specific sub-set of style guides, so just having cleared that up, what I'm talking about here is pattern libraries.

In the case of Clearleft, an agency handing over a pattern library as a deliverable, I don't think what we hand over is necessarily what should be maintained. In a way, what we're handing over's kind of a one-time thing saying OK, as part of our engagement, we did the design work, we created a pattern library: here you go, we think this is what you need to go on from here.

Now, we might highly recommend that that company have their own pattern library, have their own style guide, pattern library and more, but whether they choose to use our deliverable as the starting point for that or not is up to them. It would make sense in a lot of cases that OK, we'll take what Clearleft has given us as a starting point and going forward we'll be maintaining it, we'll be adding to it, we'll be changing it, but it might also be that for to really be owned by an organisation, the organisation kind of has to make it themselves, that it isn't something they've inherited, it's something that comes from within.

I think it's really interesting that most of the examples out there are from companies and products rather than agencies: the examples of style guides, a lot of your guests on the show, they've made this internally, they own it, they've put their blood, sweat and tears into it; I'm not so sure whether you can be as invested in something that you get given, something that's handed over to you, so that might be a bit controversial, but the way I see the pattern libraries that Clearleft are building is not necessarily as things in of themselves to be maintained, but maybe only as starting points.

Jeremy Yeah, these are deliverables, we think they're superior than to delivering pages; we think they're definitely superior to delivering comps but there's a whole step again I think into having this kind of living, maintained style guide, and I kind of feel that that needs to come from inside the company.

Jeremy Yeah, we try wherever possible to have that built into contracts to say, we hand over a pattern library and in a way, that marks the end of our work together, but we want these extra few days, one in a week's time, another in maybe three weeks' time, another in six weeks' time, these regular intervals, to check back in because that's the only way you'll ever find out: how clear was this library? How good was the documentation that a company did? How self-explanatory were those class names that we thought were so great?

Jeremy That was an interesting one because that was to do with the audience. As I said, usually the audience as in for the pattern library will be developers, other developers either front end or back end developers who are taking this and implementing it, and it was really interesting with Code for America, so we had Anna working with us, which was great, and in the first round we made sure that the CSS was really robust, putting in a lot of the current thinking about really maintainable, robust CSS, which means there's a trade-off in the HTML where maybe you've got a lot of class names.

But if the developers are the ones doing the HTML and CSS that's absolutely fine. Now, as it turned out with Code for America, the developers weren't necessarily the ones doing the HTML, because lots of different people were creating new sites or new pages, copying and pasting this stuff, and while it's perfectly reasonable to expect those people to understand, say, basic HTML, what a paragraph tag is, what an H1 is, it's not really fair to expect these people who aren't developers to now have to learn a whole another vocabulary which has these great class names we've come up with, right?

Jeremy And so the second phase of work was really interesting where we started to take some of this complexity that we offloaded the HTML and put it back into the CSS, and we made it clear in the second look, we think this CSS is now actually a bit less maintainable, a bit more brittle, it isn't as robust as what we first delivered, but it is the right thing to do for this audience because the people making the pages aren't necessarily developers, so that was really interesting in a kind of every project is different and there's no right answers and there's no one true way of doing this stuff: it was a great experience.

It was also frankly great to have a client where we got to re-visit stuff, because so often, you do your work for them and then it goes live or it goes out and then you see all the stuff that you could've done better or could've been fixed but now that it's actually live, you want to iterate. And that is one of the downsides of agency work as opposed to product work, is maybe you miss out on the chance of iteration, of being able to re-visit stuff, so the Code for America project was great for a number of reasons, but one of them was the fact that we had a second round that we got to iterate, re-visit the stuff and check our assumptions and re-visit the things we'd decided in the first round.

Jeremy Yeah, it was good; it was good to see how something we thought was fairly fundamental was maybe not necessarily true and so we need to re-visit it, but that's OK; it was all out in the open, it was all clear what the problem was and it was a great project.

Jeremy Awkward pause!

Jeremy That reminds me; apparently there's a story of Peter O'Toole being at the theatre, he was taking some friends to the theatre and they're sitting in the audience and he goes… oh this next bit is great, this is the bit where I come on. Oh shit!

Jeremy You know me; you know once you wind me up and get me going, it's hard to shut me up. I can talk about this stuff all day but yeah, we should probably be merciful upon the ears of the listeners!

Jeremy Well, thank you guys for doing this podcast for the same reason: getting people to share what they know.