Style Guides and Pattern Libraries are great tools for documenting the relationships between code and design, but beautiful docs and consistent UI are only half the battle. Somewhere, behind the scenes, those patterns have to live in our code, and hopefully make life easier for developers. We can go beyond “living” style guides to find tools that encourage and document pattern-making from the ground up, across projects, without adding developer overhead. From Sass maps and Jinja macros, to front-end architecture and style-guide generators — let’s talk about the code patterns that make our UI patterns possible.

 

Unedited Transcript

Chris Coyier:

That was the nice fade out. Which prepares you that something is about to happen. Resuming of Clarity. I have some housekeeping stuff. It's fun though, not the boring kind. One is that all the videos you have seen are available to you. And the news about it that is wait for an e mail and you will get one and it will explain how to do it. And it paid for by site point. And you will get a free membership to that. And not only that when you log in to watch the videos you get free access to a book. It called jump start Sass. Which was coauthored by our next speaker, Miriam. And it's hot off the press. That's cool. I'll tell you more about that in minute. More stuff, welcome back welcome back. There is an R S V P at event bright space. In order to go it to that is that you R S V B for that. There are some people in the house. The party is tonight be and you can do that right from the Clarity website. If you want to go, and you should. I'll be there. We are giving away a bunch of books, all worth to have. And decided a way to do that is through twitter. Go to twitter, and tweet and include the hash tag which is hop in for this event is Clarity 2016. And the that she tag book. And then tweet the comment about your favorite most of the time and tweet about a thing. And twink, is that a thing? That's different. Tweet anything you want and we will look and pick that funny? There are 18 books to give away, and we will give away nine today and nine tomorrow. And they are smashing. So nine books today. Maybe you'll win one.

Our next speaker, Miriam Suzanne is going to give a talk about the code patterns for pattern making. It's going to get a little cody here. And and there is a saying, and it's Miriam what is new, are you writing for your talk? And she said, life has been crazy in the last new months. And one of the good things is that Miriam wrote a novel called Riding Side Saddle. It's not a tech book. Look it up. And it then was adapted for the stage. So a production company picked it up for the stage. And the production picked up Miriam's band and score the thing and it will play all through march. And one of the books is Jump Start Sass, she is living in a two different worlds. She is an odd bird. One of the reasons you may have heard for her is the Suzy framework, and that's one of the many things she has done. Welcome her to the stage

Miriam Suzanne:

That works. You all look comfortable. I like how this is light over here, and over there, but not here. So I will stay here the whole time. No. We'll see if I can dive back and forth between them faster enough. I'm going to talk about code patterns for pattern making. You know we have been talking style guides. To me , one of the most important thing about the style guide is the maintainable patterns we build in this. For me, a lot of that happens in the code. We have had a lot of talks about style, and we will have more and but I want to focus in. An early experience with documentation. If you don't document you don't have this is an example of how to use documentation. Are you serious? This is the thing. The documentation made no sense at all, it didn't do anything. At that point, I had no programming skills. I do artsy shit. I had no plans, there were no badges back then. Now we have badges for everything. No hub account. The first Suzy post was from my brother, who was good enough to put it on hub for me. What I'm trying get to and not is context matters. He I'm in a different context than sales force, it's a beautiful design system and it works way better than anything I can build. And we are both doing it right hopefully. This is my team, well we've grown up a little bit. Those are my brothers and me, playing, doing a card sort. Now we are a team of 4 or 5, depending on which week it is. How many of you are on small teams? Under ten? And how many are over 200? Larger teams? Okay. Great. Yeah, I built Suzy thinking it was the right answer at some point. And I realized later on it was a great answer for teams doing consulting moving from one project to the next. I don't know about enterprise team, I don't know what you do with 200 people. I work with five. That matters there is a difference. You get different stresses and different things you have to deal with. I'm not throwing to the wall anybody, when I design something, we are all solving similar things. I'm solve similar things to lightening design in some ways, and we have different con straightens. Somebody said small bootstrap, something something something, it wasn't Brad Frost, I looked it up. Tiny boot straps for every client the. Great. I found it like that. I first found that idea when I watched at a down talk, in 2008. And I feel like every talk I have done is based on that. So I have to give her credit. What she was saying early on is we don't need frame works that have all the opinions for us, we need systems building in those so we can write tiny boot straps for every project. My team is very small and we are taking on clients, and we are doing a fast hand off and we don't see the project again maybe. So really the architecture we build for pattern making is going to make huge different. This goes to an internal team and they are going to do anything they want with it. If I don't build the pattern right it will fall apart two week after I'm gone. So the architecture is what we are selling them. Quality architecture is just patterns and code. If it's just documentation, it's not enough. People will forget about and it and ignore it. I am going back to look at the code we did in the 2010, and I know it isn't there. I did that to myself. Patterns that we see in a style guide, somebody mentioned earlier that style guides are unit tests, that's great. And they are also integration tests in that they come from lots of different patterns coming together to become what you see finally in the browser. Sooff design, H T M L, C S S and java script and data. So you have to get the whole team on board and the pattern has to be integrated across all this. And the way style guides are often done is that they show these relationships. Between components and also the relationships that create components. So maintains in the style guide have to come together. I could have done another Brad frost slide here. Moving the style guide as an attached thing as part of the process. Because if the style guide is not part of the process it will slowly fade away. That involves the process we are all going through. So I'm really into tool kits. And making sure the style guide is in the wail and visible and easy to get to. There shouldn't be any silos. That was mentioned earlier. I don't recall exactly what they said. But I quoted it any way. Somebody said, a pattern A P I, I love that. That's what we are trying to build. An A P I for developers to continue working on a project A P I that we already designed for them. I'm going to cover a couple of the basics of what is known as C S S architecture. I feel there is a problem, it seems to me that H T M L patterns are usually the core of my web architecture and C S S is plugs into that. All of these tools you have seen, atomic, inverted triangle. They all have slightly different approaches and guidelines, but basically they give you the same set of rules and they are all great for somebody. I like mixing them together and making them my own because parts work for me and my team and some don't. What is presentation, what is logic, what is structure? Those lines aren't hard but you have to find he them and what works for your team. Keep things we'll say siloed. And the whole way along always, specificity is the guide. And that see how you move things. Building from smaller to larger, I like to think of it the way inverted triangle talks about it. You have to reach for the hook, when you are being explicit, that's when you can be more specific. When you are talking about a very narrow pattern, that's used in very specific ways, then you are getting down towards the bottom of the of the triangle. But a lot of it is at the top, the broad end. C S was designed for that, that's it's purpose. We had our styles in mind but that was too specific. It's already inC S S, we don't have to fight cascade, and specificity. And in my mind a lot of the big enterprise architectures try to make the cascade go away. And I don't think that's a good idea. We don't want to repeat ourselves. Which is a good rule. But at the same time we don't to want stretch for patterns. It's not enough to say, these two elements share a border style, so I'm going to make a pattern of this bored style that is shared between the two elements. Do they share a purpose that gives them the border style? And if they do they happen we can create the pattern and we can represent the pattern differently, we can say, no, it's not a border style they share it's a background style they share. And the pattern still works the that's important patterns should be meaningful This is a good quote. Anatomywise enable, the main designer of Sass, and she said it work great when it's used semantically the main place it's breaking ask when I qualified to represent things that have no meaning behind them. So build one offs. Someone said at an earlier. I guess it was Nathan. We will move on. For example, Suzy was trying to solve a problem with making grid map meaningful. So when I look at the code I don't see that top code where it's all the math required, it's not actually real complex math, but it looks ugly and if I put that math in my code nobody would know what those mean but if I put the results in the code, nobody would know what that is either. But it I put a grid in here then he pit meaning and maintainability any my code. I don't use grid any more, I don't think you need them. Naming conventions are also part of that. And very important. We try to keep naming conventions consistent across the entire team and that includes the back end of the data base because often you will get confused with the one developer using one thing and another using another thing so we try to keep naming conventions consistent with everybody. That doesn't come down to whether you are using dashes or under scores. So part of a naming convention should be making sure in an in the patterns of naming things we are making it clear what they are. Sorry for us that's often, layout regions how they pattern and we can see when they are dealing with an I layout region as compared to a component. And that difference is clear in the name. Components or break downs, maybe organisms have molecules make it's blocks. Things have states. So is dash pattern from smacks is great. If you see is dash or has dash, you know that's a state. I have also used data attributes. And then J S hooks we split those out because we run into problems if we are not aware of something used in J S, so when we add J S something we know it's needed for java script. There are various patterns, these are some of the ones we might use. But you could come up with your own. For region we use data region and we have a consistent pattern for naming or region. For component, I don't know, we go back and forth. And we try on to be consistent. Is it a class or does a get its own data attribute. And then elements a name space class and infrastatic data state or the S pattern and for the java script hook we use J S as long you all know it and it's consistent across the project and you use it, then that's all that matters so you can see what something is by looked at how it's named. There is no right answer, but if you have no answer that's totally wrong. I'm going to look a little bit at some abstract patterns. This is one of the things that is Sass has done to our patterns. In C S S you can't represent the abstract. So you start with an A tag, in Sass there is something before that there is variables and functions. And the variables are storing patterns that exist even before dealing with anything concrete. How do we represent this? We have three brand colors and we need to put those in code? How is that represented in code? How is the one of the early ways to do this is this? And it's still really common and popular. You have color variables. Some people name space them with color, some don't. It's great, it's easy to access, we can say there we want a background this color, it would be easy to manipulate with functions. Force grouping is wrong. They are actually not grouped. In terms of a machine readable way that are not grouped in my way. I would say that's a downside of this approach. Sass doesn't know that these are all colors. Oh, I see what I meant. Yeah. We are going to go on anyway. So I like using maps. It comes up with its own problems. They are already named spaced and Sass knows these are all part of the same system. That's important to me because of style guides and we'll look at how I use that. It makes accessing them a little more complex if we do it in a simple way. You know I have to map get colors brand pink. That's no great of the if you are trying to do you other operations on the colors, you are adding other functions there and you have message functions and that's ugly. It's machine readable and it all there. We have this problem also. If I have define a brand of blue. And I want to adjust the blue, I can't do that because the map doesn't exist at the time that I'm defining it. So I can't access the map yet. So I would have to create the map again it just gets complex. It's not good. So we worked around that by using this approach where we define things now. We define what we will want to happen and then we don't execute them in you have a function. Instead saying desaturate, I am going to want this color, and we just say, do that when we get there. It's more readable in some ways, it looks like change functions and you can change them together. And then we have our own color gray, and that's all in our acute color tool kit. We do some self reference in the maps. As you can see, so we actually have layers of colors defined. Because we want sort of real basic just this is the color and then we also, we don't want to use those directly in our code because we want more semantic read in or codes. So we have text which we have designed at gray. And then we can change with a border are without touching gray. We can say we want border to go red now. There are trade offs for that. There are reasons for teams to go either way. I don't think it would make sense for lightening to use this type of approach. Because they are not passing off Sass files. Handing off class names doesn't have that opportunity, so they will build something different. It's part of this goal was an is to make documentation the lazy option. This is one of my favorite things about having colors in maps is because it gets really complex to do colors on the fly in the code. So people are forced to go back in the pattern and say what colors exist here? And then create the new one in the pattern documentation in order get the a new color. Some people think it makes it more complex, and I think great. We are try to figure out how to turn this into, we made everything machine readable. How do we turn it into a style guide without doing anything. We don't have a team just doing style guide. We want it to come from the documentation we are already doing. Here is Sass doc, which we started expanding it and you use inline documentation, this isn't the only option. We added something to it. We added a preview option, preview color palate. I think sales force does the opposite. They have a file with all the colors and they import it. So that makes sense too. And our generator gives us a color palate. Any time we make changes in the map we can do the same thing in text sizes. Again we can do the same thing, I can define ratios, if I want to do modular scales, and I can say, make adjustments based on the ratios so I can define the sizes I want. And then we do the same thing for fonts. They are defined in maps. The machine understand them. Once the code has the information we can use of information where we need it. So is comport importing code and then we can move it and. Here we have all our fonts and we can automatically create the fonts we want. We dry our code and what is left over is a tool kit. We have the tool kits now and we have made them available. But they may or may not work for you. I don't know, build your own if they don't. Internet systems are better than just straight up solutions. The tool should fit you. This is a tool for hitting things, what do you want to hit? At one point I was playing with these C S S only tabs, and I was building a pattern like this, and I tried to use it in various places and I had to change it every time I used it. And this is the result. So right away, I got rid of the stupid toggle pattern. We use true for other tools. You can't test C S S perfectly with code. We use this for functional unit tests. So when we are returning something, we make sure that when we come back, and we make changes we are still working. True gives results like this. We also lint our code. That's robots. So Sass lint returns something like this. I have a warning that should fit. We have some concrete patterns. I'm short on time. But we will do did anyway. We use N I N J A N U N J U C K S. These are H T M L templates. They are like food processors for our mark up. And I don't think the H T M L processors get that attention. We also use patterns here, and they work very much in the same way, what are the things that can change? So instead of a. I think template logic is great. There are good reasons to manipulate data, and control it, so I'm all for it. I think templates should look like templates, I don't like them hidden. This is the icon from lightening design, I'm not picking on them, they are doing it right for their users. We would do this differently because we have that control. One thing I would do, is any time I see related classes, classes that are part of a system, I put them their own system. So I can see they are related. So they have that here in S L D, S icon text. I would break those out into data attributes so I can see data icon color, I have these options. Data icon size, and I have these options. And I broke those out of their global space and G I N given them their on. I have a few variables you can pass, to have differences in your icons. It's much simplified. That's the final macro in nunchucks. We are simplifying them and it means I want an icon that gives a warning symbol. I'm out the time. We built into her man, which is our theme for tools we built in some tools there to generate a greater wall of icons. So any time we update icons they update automatically. Wave macro, you don't care what's in side it. We call it macro. How do we document that? We don't know we're working on it. This is try to mimic how those Sass documentation works. Or maybe we need to do the documentation in Sass, we want to connect the patterns and say these are part of the same pattern. Our Sass pattern isn't different from our template pattern. And then show, magic and waving. And we'll get a saga out of that. And we failed a lot of time. It's time too build saga by hand and they were always old and that wasn't worth it. So we tried to get saga to happen. There is still work to do. We are focused on the code pattern and make sure those are there first and those patterns make things meaningful. Yeah, so that's it.

[Applause]

Chris:

This is a safe zone, it says, well, inside the box. I see this box. I get it. Do not stand here. Yeah. Question one. On do you think you like Sass too much?

Miriam:

Yeah definitely. Yeah. There are times when I have over engineered things with Sass maps. It seems like it good idea and I go in that direction. And then I have to pull back.

Chris:

That was a good in the talk, like the pull back.

Miriam:

Right I do that with map sometime. And you get it right sometimes.

Chris:

It seems like that's been a thing in your development thinking in your world. Not that particular thing but engineering things in Sass.

Miriam:

That's way more fun than building web sites.

Chris:

There is a delivering classes was a thing you mentioned. I think people think of style guides that way. And they can, I'm going to craft this perfect chunk of C S S and deliver it and anybody that is using it I expect you to have the the H T M L this way, and that's now how your brain works, it's like bring your own H T M L. It seems reversed to me.

Miriam:

The way I was taught was the content comes first and that's what I try to do. That doesn't work for all the enterprise companies, there is times when that doesn't work as well. But I'm not dealing with those times.

Chris:

It's part of you are working on a small team and I deliver what you deliver.

Miriam:

The other thing if I do deliver classes, I want to develop the macro in my templates, where the developer doesn't need to know what the patterns are. They just say I want an icon, and all the classes appear. So nobody else has to learn the pattern. They just learn the abstraction.

Chris:

That's pretty cool. That's not talked about a whole lot. I like that idea. Call a function in M H T M L S. Now you update your function and you get did across your app.

Miriam:

It worked great for our team. I used to have different ways of developing buttons. But the engineers would move it wrong. You need to make one change to it and you get to wrong but as soon as you put it indeed functions they don't have to worry about it. It's more reliable.

Chris:

You literally could write, a mark up.

Miriam:

You can use mustache or react or whatever.

Chris:

There was one subtitle up which said what did you think C S S was for, is that kind of meta conversation? Don't we use style sheets as a style guide in a way. From the front end perspective, we have things that are not working, we have to talk about what we do at C S S more. Another point that hit home was the documentation the easy way out, fine add a new color, but the place you are getting the color, is.

Miriam:

That's Claudine who was working on that for a year. I was building the color system while she was there. And she said, no, it can't give me so many options. I want to be forced to write the documentation first.

Chris:

You don't have to say that, you can trick somebody into doing that you take documentation pretty serious. If you don't document it doesn't exist.

Miriam:

That was a problem I had with Suzy early on I documented it early on, and I decided to stop documenting that part. But to start documenting the part that were interesting.

Chris:

You didn't deliver a prebuilt grid. It's on demand grids that wasn't well documented at first?

Miriam:

People didn't get did. I had to write it down for you.

Chris:

Pretty good take away. Thank you.

[Applause]

Chris:

It's 15 so we have a minute? Let's chill for a minute. Is that what you meant? I got word from on high. Chill.

 

Sketch Notes by Susan Lin