[APPLAUSE] So the last talk I gave, though, was the first time I'd spoken on the stage with dry ice.

They had a dry ice machine.

And this is the first time I've spoken with a bong on the stage, so two firsts.

So this talk is about documentation, but please don't all leave.

Documentation may not be as exciting as what you've just seen, but it is vital to a project's success.

So I'm sure that you've all had this experience, where you launch a site, and it was such hard work, but it was worth it because it looks amazing.

It's a work of art, and the client is happy, and you're so proud, and you put it on your portfolio site, and you move on to the next project.

Then, a few months later, some new designers and developers, they come in and they make adjustments.

They use styles that don't fit with the content, add huge images that slow the site down, they throw in a bunch of fonts, and it just looks terrible.

So you quietly remove the site from your portfolio.

But whose fault is this? The next person who works on your project, they aren't a mind reader.

They're not going to know why you've made certain decisions.

If they're very new, they might not even know about best practices like optimizing images, or why it's bad to use web fonts.

And that's why we create documentation.

Explaining where and when different pieces of content should be used forces you to think about your site as a system rather than as a series of pages.

The act of writing it also forces you to think about why you're doing things in a particular way, and this is where style guides come in.

Style guides are a type of documentation that encourages people-- be they designers, or developers, or content producers-- to follow a set of rules that help maintain consistency.

And there are actually many different types of style guide, which I'll very briefly walk you through now.

So you've probably all seen branding guidelines.

These often go into obsessive detail about logo placement, and color usage, and typography, but they're not helpful to us because they're usually entirely geared towards print, with the white space around the logo unhelpfully noted in millimeters, and the color scheme in Pantones, which just never translate well to the web.

Then there are print guidelines which go into even more detail, and this is one of many guidelines for the Uk's National Health Service print material.

And it's important for an organization like the NHS to have these so that people trust the message that's being communicated, and also to make sure that the design is created in a way that is accessible to as many people as possible.

With any organization this big, it's quite common for these guidelines to be ignored, which is bad if you're trying to communicate a message that could be the difference between life and death.

And I want to be sure that this defibrillator is going to work when I use it, and having such a playful font-- it makes me wonder what I'm going to find when I actually open that box.

Content guidelines focus on the way in which it's appropriate to communicate.

So when you've got lots of people working on a project, it's important that you sound consistent with the brand.

So MailChimp, they have their own guidelines called voice and tone.

Their recommended message for a success dialogue box is, find piece of work, you totally deserve a raise.

And it fits with the playfulness of MailChimp's brand, but that tone of voice is likely to be very different from, say, the way that your bank tells you that you've gone overdrawn.

We have similar guidelines for code, too.

So when there are multiple developers working on the same project, it's good to maintain a consistent style to the way that you write code, to avoid conflicts and just make it easier for everyone to know where things live.

And finally, there are style guides built specifically for websites, which I sometimes refer to as front end style guides.

And these are what I'll be focusing on today.

They'll often contain a mixture of all the ones I just showed you, and unlike a regular style guide they're interactive.

So you can hover over a link, and it will change state.

And you can highlight the text-- you can fill out form fields.

It's like an instruction manual for building and maintaining a specific website that you can actually use.

There isn't a specific type of front end style guide that is going to fit every project.

There are many different techniques for building up a style guide for the web.

And I'm still going to start by showing you a couple of techniques that are aimed specifically at designers, alongside front end style guides.

And this is because front end style guides, they need investment from designers to be useful.

So I'm going to show you these to help you sell the idea to the rest of your team.

If you have an existing site that you want to create a style guide from, or just consolidate styles, the first thing you can try is something called an interface inventory.

So Brad Frost came up with the term, and to demonstrate it he went his bank's website.

And very simply, he took screenshots of all the different styles of buttons on the website that he could find.

There are dozens, and this is just for one website, one brand.

Imagine how much CSS there is just for these button styles.

And an interface inventory is so easy to do.

You're just basically going to go through the site like you would a content audit, and gather as many different styles as possible, group them by function, and put them all in a slide deck.

But don't just stop at buttons.

You can also create inventories of all of these different elements.

If you're trying to convince someone of the value of creating a style guide for a site, just do a quick interface inventory on it to highlight just how much could be consolidated.

Explain that consolidating these styles will help make the code leaner, and the site more visually coherent and easy to maintain.

This is only practical if you have an existing site.

So let's say you want to start from scratch, or completely revamp a current design.

Samantha Warren is a web designer with a background in art, and she quickly realized that creating beautiful website mock ups at the start of a project and presenting them to the client was wasting a lot of time, because sometimes a visual style that she'd come up with was completely not what the client was hoping for.

But it wasn't until she'd shown them something that they started talking about what they did want.

So she was trying to think of a way to facilitate this conversation about a design without creating a pixel perfect mock up.

She then tried creating mood boards for clients, mood boards like you would use for interior design, but she just found them too abstract at all.

They felt too disconnected from a website, and clients would often already have a mood board made as part a re-branding exercise.

So then she created style tiles.

So they're in between mood boards and mock ups, and they contain snippets of design elements but they're not presented like a website.

It's meant is a tool for conversation rather than a fixed deliverable.

And they're less risky than presenting a finished comp to a client.

Since they're quick to make, you can create a few of them for a client to choose from, and ask them, is this the impression you're going for? They remove that dangerous big reveal stage of a project, where the client takes one look at all of your hard work and says, nope, that's not use at all.

So here's how a style tile is put together.

So the most important aspect of the style tile are these words that are used to describe the feeling that the design should evoke.

And each tile has different words.

One might say conservative, whereas another tile might say modern.

And these words influence the typography that's chosen, which is also different for each tile.

There are some small design snippets to give a very rough idea of what some design elements will look like in practice.

The color palette is shown.

And finally, each style has a version number.

So after coming up with a style tile the client liked, Samantha was then able to work on a mock up incorporating these styles, and this is what it looks like.

You can even use a chosen tile to form the beginnings of your front end style guide before the bulk of the design work has even started.

So Dan Moore has a very similar approach, which he calls element collages.

So like style tiles, they're a tool to facilitate conversations but they come a little further along in the design process, or even straight after a style tile has been selected.

And here's what one looks like.

It's not a mock up of a page, it's kind of a digital scrapbook of ideas.

So here, Dan is prototyping some styles for how buttons will look, and what donation fields will look like.

And this technique is perfect for designers who aren't yet comfortable with putting their designs straight into code, but they want to move away from doing full comps.

The most valuable thing that element collages do is they focus a client on how that feature will work, regardless of what size screen it's on.

Now that we have an infinite number of devices, and screen sizes, and resolutions to worry about, breaking out the canvas entirely helps a designer and the client to think more about how something is going to work in context of the site as a whole, rather than on a specific page.

Design agency Clearleft had been trying out element collages in their design phase.

One problem that they encountered was that their explorations were looking too much like pages, and the client didn't really understand what it was that they were being shown.

As you can see in this collage, [INAUDIBLE] the various modules shown wouldn't all be found on the same page, it still looks too website-like.

So they found a better way to present the element collages was on a wide, horizontal canvas, rather than a long vertical one.

So this is an element collage that John Aizlewood, of Clearleft, worked on for Code for America.

And here he's trying to think of ways to style block quotes, and he's toying with two very different styles that he's going to ask the client their opinion about.

Style prototypes are the next step along.

They're basically element collages, but in code.

And they skip the sitting in Photoshop phase and enable you to mock up something really quickly for feedback.

There are prototypes of some of the content elements on the page, but these are all mocked up in HTML rather than in Photoshop.

So they adapt to different screen widths, or you can try it out in the environment that it's designed in.

And this gives a much more realistic impression of what the finished thing will feel like to use.

So I built a style prototypes in practically every project now.

The design only has to use Photoshop for assets like icons, and the rest of the time they're handing me sketches which I roughly mock up, they tweak, and that gets presented to the stakeholder.

This is an ideal approach if you have a hybrid designer and developer on your team.

The code doesn't have to be great, it's a prototype after all.

And it's best to start building them during the design phase.

It might seem strange to start coding so early on in a project, but it means that you can test ideas out quickly before writing proper code.

You might already maintain a code standards documents.

So Harry Roberts is a front end developer who has his own CSS guidelines, and it's been so popular that he's created an entire site for it.

CSS guidelines are just one example.

They could be written about HTML, PHP-- basically whatever language is used on a site.

Ideally, they need to be written before you start building.

In Harry's CSS guidelines, it contains not just how to format CSS in a consistent way, but why it should be done in this way.

Coding standards should evolve over time in response to changes in specifications and accessibility best practices.

A good set of guidelines will tell you what to do.

So, "keep selectors as short as possible."

A great set of guidelines will tell you why.

So, "keep selectors as short as possible in order to keep specificity down and performance up."

An excellent set of guidelines will go one step further, and back up that reasoning with further reading.

And this is invaluable for new developers working on your team, as it helps them learn best practices.

If you're a more stable part of a project where you're building out components, then something like a pattern primer-- which is a term Jeremy Keith of Clearleft likes to use-- is going to be more useful as an ongoing piece of documentation.

This is the main type of style guide that I'm going to be diving into, as the idea is that it's not a throwaway deliverable.

It's a system-- a living, breathing, evolving library of components.

Each component or module-- each small piece of the design-- is referred to as a pattern.

And they're like LEGO blocks.

They're independent of each other and they can live on their own, or alongside other patterns to form pages.

In this quote Jeremy uses the term pattern library.

A pattern primer is a pattern library, it's just watch Jeremy likes to call his.

And I think of a pattern library as a part of a front and style guide, which might also include code standards and content guidelines.

Basically, anything that's going to help someone to maintain a site.

Before Natalie Downe co-founded Lanyrd, she was a front end developer at Clearleft.

And when she was developing a new pattern, she'd add it to a long page which had all the patterns on it, and she called this a pattern portfolio.

And this is where Jeremy's primer evolved from.

The difference between Natalie's version and Jeremy's is that Jeremy separates the patterns from the page template, and shows the mock up alongside the pattern.

pattern libraries are built using the same mock up and the same styles as the live site to keep it as accurate a representation as possible of the actual site.

But this is not the only deliverable that Jeremy gives to the client.

He'll also mock up a few pages, but with the intention being that the client can use the pattern library to assemble new pages going forward.

So it might seem like quite a lot of work up front to get set up with a style guide, but as you'll see, they more than make up for it in the long term.

When you're working with a really big site the design in the code get out of sync very quickly, and a style guide is a good check and balance.

It's something that can be used to make sure that you're staying on track.

And this is especially important if you have a sprawling site with multiple people working on it, like Starbucks So they have a pattern library, and it's really fantastic that they've made it public.

It contains things like the grid system that they use, various layout modules, dialogue boxes, and form styles.

This documentation is especially useful for when external teams are brought in to work on a site.

Things like form validation styles can be reused, so Starbucks now don't have to reinvent the wheel every time they introduce a new section to their site.

Or worse, duplicate code or styles that already exist.

Interacting with inconsistent UIs across government websites is what spurred 18F to put together, in a relatively short period of time, the US web design standards.

And it's so exciting to see governments focusing on this, not just as a way to make their sites less confusing to users, but also as a way to save public money.

Because they're not having to reinvent the wheel with every new site.

What they put together is a set of common UI elements that have already been usability tested, and meet accessibility standards out the box.

And these components are intended to be reused to maintain visual consistency across US government websites.

Alongside the patterns are guidelines on how to adapt them in a way that maintains these standards.

And what's incredible is seeing a government write up and share their research, which then directly influences the decisions that another government's web team makes.

There's a Trello board for the MVP of the US web design standards, and it's public so you can see some of the discussions that went into designing components.

Like their date picker, which they've based directly off one gov.uk bill and wrote about.

They're not just open sourcing their code, they're open sourcing their work flow and their research.

And this is what makes the industry great, is people sharing knowledge and building upon things that have been proven to work, rather than starting from scratch every time.

And seeing this makes me very happy.

Another benefit of style guides is when you use them as part of your QA flow.

So basically, because everything's on one page it's faster to test.

You can easily spot style conflicts and quickly drill down to a specific element that's causing things to break.

And you might even want to do visual regression testing on your style guide to see if a change his unintentionally affected any other patterns.

Normally mock up is hidden behind view source, but by displaying the code on the page alongside the pattern, your team can help spot errors in the code.

And it's also going to encourage you to write better code if you're effectively showing off to everyone.

Another nice thing that you can do is install a browser plug in, called Tota11y-- which is spelled like that, with the Ls replaced with ones-- that toggles common accessibility issues, like color contrast.

So I ran this on my style guide, and it's flagging up where the text doesn't contrast enough with the background to be easily readable to people with low vision.

And because all of my patterns are in a style guide, I can test them all at once, without having to go through every single template that I've built.

When you're rapidly iterating, a lot of inconsistencies can creep in.

So when you do a code review, having all your modules in one place helps keep track of what's new, what's a duplicate, and what's not being used anymore.

So I talked earlier about Brad Frost's interface inventory.

A pattern library is basically a built version of that.

Chris Coyier decided to create a pattern library of his app CodePen.

And even though he'd built the thing, he was really surprised by just how many buttons styles that there were.

Doing an audit on your site is a great thing to do because a lot of these styles can be consolidated.

That way, you end up with a more consistent design and leaner code.

If you can build elements straight in code using something like style prototypes, you're going to be giving a much more realistic representation of what a design is going to look and feel like.

You can immediately show it on different devices and browsers, and get an idea straight away if something is going to work in practice, and feedback any issues early on to the designer.

One of the best ways to make sure that your style guide is kept up to date is to have someone on the team who is a kind of evangelist of it.

Someone who keeps it in check and makes sure that new patterns are always added to it.

So there's an entire team at Marriott Hotel who just maintain their style guides.

While most places are unlikely to be able to justify having that, having just someone on your team who is in charge of regularly checking the style guide is up to date and being maintained, and nagging others to contribute to it-- that's going to go a long way.

Think of that person as the gatekeeper for new content or functionality.

GitHub hire a lot of developers, and they maintain their own standards for writing HTML and CSS, organizing files, and the reasoning behind why they do particular things.

And this makes the onboarding process for new employees a lot easier, because they can point them to these documents.

Style guides can also be used to measure how different features are going to affect performance.

So Dan Mall worked with Tim Kadlec on Radio Free Europe's redesign, and they were told that because of the nature of the content, some of the site's users had been jailed or hanged just for accessing the site.

So performance in this project was critical.

They were thinking about it right during the design stage, as they were building up an element collage.

When they started building, Tim created a grunt task which measured how fast each pattern is loading.

"Lonely Planet" also think a lot about performance.

Each file has performance stats logged in the style guide, and changes to these are highlighted and plotted on a graph.

And this is a great way of visualizing which areas can be optimized to make the most impact.

Since this is all public, it also creates more of an incentive to optimize aggressively.

And its prominence hopefully prevents file sizes creeping up too much with each release.

pattern libraries are also a fantastic tool for rapid prototyping.

Federico, who works on MailChimp, used theirs as a way to quickly build up new pages or update existing ones.

So he managed to test out an idea using real code that was also responsive in just 20 minutes, and he did this by slotting together existing patterns.

Building things in this modular way is becoming a revelation, not just in web design but also in the real world.

So I saw on the news a story about a 57 floor building that had been built in just 19 days, because it had been built in a modular way, mostly off site.

But no matter how good your pattern library or documentation is, it's not a replacement for talking to the client or the rest of your team.

This isn't just something that you're going to build, hand over, and that's it.

Dan Mall has adopted the goal that every deliverable that he hands over has to come with a proper conversation.

Also, don't wait until the end of the project to build one.

Start putting it together from day one.

Otherwise, it's likely to be this snapshot in time that people are less likely to maintain because they don't feel invested in it.

And this is why it's so important to get the designers involved in making and maintaining it.

Like Jina says, if it's not part of your workflow you're asking for it to become outdated.

That being said, you can still make one if the site already exists.

So this is one I knocked together for A List Apart long after the site had gone live, just to help keep track of what styles there were.

It's important to think about who you're building your style guide for.

Is it for developers? Is it for an editorial team adding content to a CMS? That will dictate what kind of a message that you choose to convey.

You should also consider how strict you want it to be.

So are they a set of guidelines that are open to interpretation, or are they rules that need to be followed? I tend to lean towards more relaxed guidelines, but it will really depend on the project.

So this is code for America's style guide.

Each design pattern that appears on the site is built in isolation, and multiple patterns can be assembled together like LEGO blocks.

They have a micro site for each of their cities, so their guidelines are very relaxed because they wanted to allow people more creativity in appropriating their city's micro sites to its individual needs and culture.

And here's the information that is shown for each pattern.

Each pattern has a unique name that the team can refer to.

The pattern itself is displayed at full width, with the idea being that it can adapt and slot into any space.

It has the code that you would need to reproduce that pattern, a description of when that pattern is appropriate to ue-- so here I'm explaining that this pattern should be used as a call to action.

And finally, it has a link to the pattern on its own, individual page, just for debugging purposes.

Each individual pattern is a discrete file, a bit like an include file.

You can even keep them in an includes folder if you want.

Everything is self-contained, so that if the patent becomes obsolete the components can be removed easily.

And if you're using Sass or LESS, these file should have the same name as the pattern files so that they're easy to find, and so that you know that the matching files are related.

The style guide uses a compiled version of the main site styles so that it's exactly the same as the website.

But I also add some CSS just for the style guide, which I don't include in the production site.

And I prefix all the class names in the style guide HTML, so things like the pattern wrapper with .xx so that they

never clash with the main site styles.

I then set up a function that loops through to the pattern files, and spits each of them out onto one page, and I add things like color swatches and typography straight into the style guide, as I'm not going to reuse these components anywhere on the production site.

I then add some code to the function that outputs the mock up for that pattern next to the pattern itself.

And the width the patterns should be independent of the layout, so that you can fit them into any space.

That way if the layout changes you won't have to update the patterns.

They'll just work anywhere.

And this technique is essential for responsive websites.

So I've been working on my Jekyll's version of a patent library.

Jekyll, for anyone who doesn't use it-- hands up who uses Jekyll-- it's a static site generator that also plays nicely with GitHub Pages, which hosts my site.

So when I commit a change to the style guide, that change automatically gets pushed to the live site.

The pattern lives in a Jekyll collection, which means I can loop through all the files in that collection and output them onto one page.

And I've also added content in the YAML front matter of each file, which gets displayed as part of the pattern.

I then have a grunt task that copies the pattern files into the includes folder, strips out the YAML so that I can use exactly the same patterns on the site as are in the style guide.

And that way, my style guide is always in sync with the site.

Brad Frost and Dave Olsen have created Pattern Lab.

So it does a lot of really cool things, like letting you randomly change the width of the container and search through all the patterns, and it's an excellent starting point for a project.

So it uses PHP, but there are ports for node and .net.

There are some tools out there that will even generate a style guide fully based on common [? senior ?] CSS.

So KSS, which stands for Knyle Style Sheets, does this with the aim to make your style guide easier to maintain.

So you write comments in this way with the various states, and KSS will look through these and generate a style guide from all of them.

Tools like Frontify do a similar job.

So they generate a style guide for you displaying things like swatches and typography used.

And they also have a discussion feature.

And this is good for if your team works remotely, or if a client works off site and you want to make communication as clear and collaborative as possible.

It's so important that your style guide is available from outside the internal network, because external agencies, or freelancers like me, will need to access it.

And people are also more likely to use it if it's easy to find.

My favorite tool is Typecast because it promotes a content first approach.

So I'm not sure it can really be called a style guide because it doesn't do stuff like generate color swatches for you, but it's great as a first step towards making one.

It's purely for prototyping typography and helping build a solid foundation in the browser.

So padding, margin, and line heights can be tweaked, and it generates fairly decent CSS.

As you know, Photoshop is terrible is showing what type will actually look like in a browser.

So please, designers, use Typecast instead.

There are a few key features your front end style guide should have, as well as a lot of optional ones.

So before you do anything, start with the basics.

Just draw HTML elements without any CSS classes.

Things like heading levels, default paragraphs, links, tables, form input boxes.

And you can reuse this HTML on every project.

And it's great to just sit down with a designer and tweak things with them like the line heights, and make sure you've got a really decent typographic grounding for the site.

So I use Paul Lloyd's Barebones, which has all of our HTML elements, along with an explanation of when you can use them.

And the design is nice and minimal, so you might also want to use his CSS as a starting point.

After you've put in some basic elements, start adding the patterns, and aim to only include the patterns that you need.

It's tempting to want to show everything in your boilerplate, but be realistic.

While it's nice to have, most sites are unlikely to ever need a style for the keyboard element.

I'm so guilty of this.

I just want to add everything I can think of to style guides, just in case, but it doesn't help me the code any leaner.

So I'm sure you're like me, and you've got a toolbox at home that's just full of things that you don't use.

So mine has multiple things I've got more of one of, parts for furniture that I don't have anymore, and things I've kept just in case I might need them.

In MailChimp's style guide, they say that they only add new patterns when there's a sound case for doing so, because new patterns come at a high cost in terms of design elements, additional code, and maintenance.

And they also say that new patterns also increase the cognitive load they put on their users.

And I get that.

I get that kind of cognitive load when I'm searching for a particular tool in my toolbox.

They know that the more that they add to their pattern library, the more features they have to support, and the more complex the library and the site gets.

So only add patterns that are needed.

Alongside your patterns show the markup that's needed to replicate it.

This is Saleforce's, and they have fantastically detailed design system documentation, and you should really check it out.

So I like to put my code behind a show hide so that the page doesn't get too long.

But because Salesforce-- they have so many patterns, they've actually split them onto multiple pages.

So they make all their mock up visible on one page, and it's still manageable.

So this is usually HTML, but it should be whatever language that someone who's building the site would need to recreate that pattern.

So for example, South Tees Hospital, their website is built in Wordpress, so their code examples-- some of them are Wordpress short code.

Someone without any knowledge of HTML can easily add components a new page in the Wordpress editor view without having to open up a code editor.

And it also means that if the mock up changes further down the line the short code should stay the same.

You may also want to show the CSS.

So Salesforce actually display the Sass that they use for each of their patterns.

I wonder how useful this is, because unlike the mock up, a pattern CSS in isolation is missing the global styles.

So it's not possible to replicate using just that snippet.

But I guess it is useful as a learning tool for other people to see how it's made.

Don't forget to show the extremes, such as this really long heading which I've added just to make sure it doesn't look weird if the text wraps.

And also, show what happens when people do things that the designer might not have anticipated, like having two headings right next to each other.

As you go, check the patterns on different devices and browsers, and also make a habit of switching off JavaScript to make sure your fallbacks work.

Adding notes is especially useful for back end developers who need to understand the logic to certain styles.

So here, there are groups that could have any of three different states to signify whether it's a public group-- which is the default state-- a private group, or a group which the user is already a member of.

So there are some notes which I've added that just explain what these three different styles mean.

Color swatches are a really nice thing to add to a style guide.

So if a code for America's style guide-- each color has its own hex code and RGB value.

If I'm using LESS or Sass, I'll also include the variable name needed to invoke that color so that I can quickly reference it when I'm coding.

And I also like to ask the designer to choose these names, because it's something that they seem to love doing and it helps them get invested in the style guide.

Many style guides, like MailChimp's, they document how to set up their grid.

So it can take a while to set up this documentation the first time you do it, but they're solid investment because they make building templates going forward so easy.

And they also force you to think about why you're building it in a particular which can, in turn, improve the quality of your design and code.

So I've seen some really lovely examples of grids in style guides.

Like Starbucks' is really good.

It has these toggles for showing the grid as a layer like you can do in Photoshop, and it's ideal for checking whether something is lining up properly.

If you've got animations on your site, document these too, to keep the styles and timing consistent, and write up when to use specific ones.

So Salesforce's style guide has a fascinating section on how they use animation.

Google also have a fantastic guide called "Material Design" that includes a lengthy animation section.

So both Salesforce's and Google's are among the best examples of style guides that I've seen, so I highly recommend that you check them out.

Something that is frequently neglected on a site is right to left styles.

So for this style guide, I added a right to left toggle that switched the text direction of all the patterns.

That way, I could easily see if I'd written my CSS in a way that broke the design for languages that were displayed in this way.

After a while your style guide is going to get pretty long.

So you might want to drop in some navigation like a jump link select box, or some navigation to the side.

I prefer jump links because I like my patterns to fill the full width of the screen, so that I can't test that they respond nicely at very big sizes, without the navigation getting in the way.

The style guide that's out of date is almost as useless as no style guide at all.

The challenge for the coming months and years is making ones that are powered by the live site that use the same styles, the same content, and the same code base.

A lot of style guides are built separately from the site, and the code can get out of sync over time.

And Jina calls these zombie style guides when they're unloved and unmaintained.

Don't let your style guide become a zombie-style guide.

"Lonely Planet" have a cover strategy to stop theirs becoming zombified.

So they've hooked it up to an API, meaning that the mock up used it synced with the live site, and they call their system Rizzo.

Rather than have HTML snippets, they display the code needed to pull in the mock up.

So to show you an example, this code outputs a card with a cover image.

And the parameters can be modified to change the output.

So taking this example, if you want to show the same patent but with an author credit, we can add a couple of lines for the author name and avatar, and they appear.

And this tackles a problem where components may become out of date, such as if the mock up changes.

And it also means that if you have multiple components that share a lot of the same mock up, you're not duplicating the code.

Ian Feather, formerly of "Lonely Planet", he credits the success of their style guide to this API, and he mentioned that he built two versions before this one that became zombie-style guides.

But now it has an API.

It's always up to date, and he doesn't have to actively maintain it.

Even the best style guides can be improved, and it feels like everyone is still seeking that holy grail, even Ian Feather.

So this style guide that needs minimal maintenance, that everyone feels invested in, that's easy to update, and that stays up to date.

That's usually a lot easier for an in-house team to achieve than an agency who hand a style guide over as a deliverable.

So Dan Mall talked to me about baking in time after the project to revisit style guides that they delivered to clients.

And I think this is brave, because it's admitting that the system that they've delivered is probably not going to be perfect first time around, and they use this time to see what's working, what's not working, how they can be improved, and they make tweaks based on this feedback.

And I think this should be true for any project.

It's not right to just throw a bunch of documentation at a client, hope for the best, and dusty your hands of it.

External teams should be making more of ongoing relationships with clients because they are the most rewarding.

And I just want to stress the value of making it public.

So other than being a really nice thing to do that helps the community, there are some very good reasons for this.

So one is it that keeps you honest.

You're going to be more likely to maintain the thing if other people can see it.

The second thing is that it's a recruitment tool.

So several people that I've talked to have said that they've joined a company after seeing their style guide.

If you build one, and it's good, you're going to have people like Jina knocking at your door.

"Lonely Planet's" style guide has also helped them with recruitment, and by making their tool, Rizzo, public and open source, it means that some of their new recruits are already familiar with working with the tool before they've even started.

And it opens the doors to people outside your organization to make improvements to your overall design and code.

So a week after the US web design standards went live, Maya tweeted that they'd merged nine pull requests from people outside of government.

My final piece of advice is, don't be intimidated by how all of these examples I've shown you look.

It doesn't have to be a work of art.

That's not the point.

Sure, it helps if it looks nice because people will feel more proud of it, but it's meant as a tool.

Start small and simple, and build upon it as and when you can.

So if you want to learn more, I've set up a repository on GitHub that brings together stuff all about style guides.

Over 300 resources have been added by the community.

So you might want to check this out if you're looking for more ideas and inspiration on creating a style guide, or if you want to add your own.

And I also ran a little podcast with Brad Frost all about style guides.

It's just a short run thing with a total of 12 guests, and a lot of the quotes that I've shown you today in this presentation were directly from those episodes.

And I've also written a book about the topic.

It's two pounds, and it goes into a lot more detail about everything that I've just been talking about.

Questions? (moderator) Thanks very much, Anna.

[APPLAUSE] Come with me over to the comfy chair, please.

So, we've got loads of questions from the audience, but I'm not going to keep you hear forever because we have to do the raffle.

Inge said, "I always start with a style guide, but maintaining it is a pain, both budget-wise and time-wise," and Tim said, yeah, we had a style guide but it lost priority over time as we were iterating with sprints, et cetera.

Any tips on how to minimize the difficulty of maintaining it? (anna debenham) I think it's a very common problem.

It's something that I've also encountered, especially when you're working Agile it's really tough to keep up to date.

The way that I've worked around it is by having it as part of my workflow, where we actually build and test things in the style guide rather than making up templates with the things in them.

And we make sure that all of the patterns themselves are directly linked-- they are the same code as is in the site.

So we're using-- a project I'm working on, we're using Jekyll as the collections to pull in, rather than having PHP includes the Jekyll equivalent can be collections.

So it's the same code essentially, and using the front matter to put the data in, which is quite a nice feature of Jekyll in that you can have the different data on the different pages, but different data for the actual pattern library-- it's kind of hard to explain.

How early in the process do you do it? -- do you do a style guide right at the start, and risk its becoming obsolete? Or do you use it at the end when you do a client hand off? Or is there a way that will work for everybody? Or is it project to project? It's going to be right at the start.

If it's not, people won't feel invested in it.

If you just present them with something at the end, they're not going to activity maintain it because it seems really foreign.

If you start off with it-- so I like to start off with encourage the designers to make a style tile, which I'll then turn into a very basic pattern library.

And that will get iterated on over time, so it doesn't stay the same day to day.

And that really helps with the design process, because often there will be styles for things that we've forgotten about, and we'll realize, oh, we've already got a style for this.

So that can be quite handy.

Thanks.

And somebody called Vitaly Friedman noted that you talked about somebody owning the style guide and being a gatekeeper, and he said, isn't having one gatekeeper potentially a single point of failure? Shouldn't it be owned by the team? Yeah, that's a really good point.

I hadn't thought of that.

It should be owned by the team, ideally.

It just helps to have someone who is kind of one of those excitable type people, who just stays on top of it, makes sure that people-- kind of like a cheerleader for it, to make sure that it's not going to go out of date.

So the people I talked to who mentioned this were Jina and Susan, who are both kind of the ring leaders in keeping up their style guides in the company up to date.

But like Vitaly says, the risk is that if they leave, or go on a different project, that that's going to kind of slip to one side.

So yeah, having a team that's backing it, that understands the value of it, that contributes to it is ideal.

How do you actually get that team? Because, forgive give me everybody-- I know you're all different-- but programmers are notoriously reticent about doing documentation.

How do you persuade a bunch of busy people who are iterating like crazy to spend time sharing this documentation work and keeping it up to date? I think-- so I've been working a lot of projects.

It's mainly people who are integrating the front end code into a CMS really appreciate it, because they're used to being handed just templates without any documentation.

So it's good for the designers and the front end developers, because they know that their code and their design is more likely to be properly reflected.

Programmers of it because they can actually use it.

It's a better piece of documentation than a flat set of files.

I struggle to think of a project I've worked where it hasn't been kind of-- where they haven't said, this is great, let's always use this.

Because when they start to see the value of it when they've actually used one this is being maintained, then yeah.

Got you.

Last question-- somebody whose name I won't mention, but it rhymes with mashing smag-- tries to cause trouble wherever he goes-- and he said-- I'll boil it down to a simple question-- don't style guides restrict creativity? That is something I've heard of.

No, I don't believe that's true.

So take that, Vitaly.

We'll have a fight in the after party.

But yeah, I honestly don't think they do.

If you're a good designer it shouldn't be seen as a restriction.

It's just a different way of presenting ideas.

And yeah, that's what I think anyway.

So there, excellent.

Thank you, Anna Debenham.

[APPLAUSE] Thank you.