 know this room is quite far from where the other sessions are, so thank you for making it all the way over here. I'm sorry I was late. Obviously this session was supposed to be yesterday. I had some food poisoning, but you made it here and as did I, so yay. Today we're gonna talk about style guide driven development. I'll hail the robot overlords. I'm realizing looking at this title that it was a bit click-baity. I don't actually have any pictures of robots in it in my slides, so I apologize for that. I can play a name of a giant song called Robot Parade if that will help, but otherwise robots are a sort of metaphor for the automation in front end. If you don't know who I am, I'm John Albin Wilkins. I'm a senior front-end developer for Previous Next. I am also a serial open source developer. I got started with the Zen theme, still the maintainer of that, and then I wrote a whole bunch of modules just to support all the things that the theme system couldn't do. You can find all of them listed there under slash us John Albin. I've also branched out to other bits in GitHub, Zen grids, normalize, SES, KSS node, and chroma. We're gonna talk a lot about, well, you're gonna see a lot of KSS node today, because that's the automated style guide bit. So yesterday when I missed the original session, I finally managed to drag myself out of the hotel and make it to a buff, which was at two o'clock, and if you came, it was wonderful. It was just a style guide discussion buff, and it was really illuminating to me because the thing that everybody wanted to talk about was process. When you talk about process, it doesn't really work when you just have somebody up here lecturing you about process, because it's really about questions and conversations, right? So I'm gonna start that sort of conversation thing everywhere. How many people here are comfortable with raising their hand when the presenter asks you a question? Fantastic. Okay, how many people would prefer to just yell something out? Okay, one. Morton will be here soon, too, so. So the question that I want to start the conversation with is where are we headed? Okay. Nicholas Gallagher has this great quote, wow, that's incredibly small font. He says, are you new to front-end web development? Here's the secret. No one really knows what they're doing either. And if you look at front-end blog posts, they're all over the place. There's all these different technologies that are going on. Vagrant, MPM, SAS, last-web components, Behad, regression testing, CSS frameworks, Bootstrap, Linting, it's incredibly difficult to figure out what's the thing that I'm supposed to do next, right? And, yeah, I feel like there's so many more. Travis, why slow? Page speed. And the essential problem here is what Frank Chimero said last year, which is everybody is describing the one little piece they've created, but don't explain or even reference the larger concepts of how all of these elements link together, right? And it's because, you know, we're at DrupalCon, so of course we're talking about Drupal, so we're talking about the technology. It's really easy to focus in on those little bits while you're at a technology conference and while you're talking about one particular thing on your blog post, right? So technology is sort of like focusing in on the brushwork of a particular painting, right? It's wonderfully detailed and you can learn a lot by looking at it at this detail. But, of course, you have no idea what's going on until you step back and look at the entire picture, right? And process is that, you know, process is all about understanding the bigger picture, right? So when previous DrupalCon people were asked, like, what's going on? We don't understand what's going on. And I thought about it and I've been doing this long enough. I've been doing web developments since 1994, no, 93, that it's a little bit easier for me to figure some of those stuff out or at least realize that I don't have to try to do everything that I see in a blog post this week. I can think about the bigger picture for a little bit and not worry about some of the technologies. So, but can people in the back hear me? I want to make sure that I'm at the right microphone. Okay, good. When I tried to make sense of this, all of these different technologies, I realized that basically there is only really three categories. There's front end performance, components, and continuous integration. So any of these front end projects can be described using, you know, one or more of these three broad categories. And to resay this without so much jargon is basically you're making shit faster, you're making shit modular, and you're automating the shit. Those are the three things that you have to do. That's it. That describes any project. And I don't know if you want to play a fun game where like people just yell out projects and then I tell you which three categories it is, but we could. There's the one person who was yelling out, you want to try? Anyway, what was that? No JS. So definitely, you know, the Node.js packages are all about components, right? Because you're building a system using all these different Node.js packages. And those, those are components, right? Suppose I don't know Node.js, like web server system, I would think that that's all about front end performance as well. Right. So like I said, they can be combinations of things, but these are the sort of, yeah, and continuous integration, you know, it's got some of that in there as well, because you know, you're building up with a package.json, you're able to build these projects much faster. That's part of the, the automation. So to understand, you know, where we're headed is, it's good to take a look at how we've been doing stuff traditionally. And that's always like waterfall, right? So we, we plan our projects, then we do like design them, then we develop them and then themers get totally shafted by being last in this process, right before the deadline. And there are a couple of different things here that can go wrong. One is, you know, you get to, you know, let's say today's there on this timeline. And you realize that you're not going to be able to finish by the deadline. So what do you do? You go over budget and like your company loses money because you went over, you know, you went over the past of deadline and you have a fixed bid or, you know, one other way you can do it is just not do half of this, the seeming bit, right? So you, you limit the scope to meet the deadline because it's a hard deadline in this case, right? And what happens here, what this means is that essentially since you're only theming half of the stuff that you developed and designed and planned, you've wasted an insane amount of time. You could have completed this project, you know, months ago in the middle of this thing, you could have completed the entire project that got in the same result for half the money, right? This is horrible way to do projects, right? And software developers have been looking at this problem because it's not just a front end problem. It is a software development problem. And so they've started to do what's called agile development. How many people here are like totally not familiar with agile development? So you've all heard of it, you know a little bit. We're going to go through super fast oops, I want that last slide. So agile development is all about reducing the risk by controlling and minimizing your risk, okay? And a typical agile project looks like this. This is, this is, yeah, I think this is the way most agile projects are. This is how you would do it in Scrum, which is what I'm trained in. You still have the start and deadline, but you break that timeline into a discrete set of sprints. So you have two weeks and you just find that the end of those two weeks, that's the end of Sprint one. And then the next sprint is another two weeks and you just divide up that time into these equal parts. And you organize your project by creating a backlog of features. And you go through and discuss with the product owner, which is oftentimes just the client, like who's in charge of this, the end result, right? And you prioritize all these features. So you decide which ones are the most important. Those go at the top of your backlog. So for Sprint one, you basically just grab the first couple features that are in your backlog and start working on them. And when you finish the sprint, you're supposed to finish those features, right? So then the next sprint, you just grab the next couple of features and start doing those and complete them during your next sprint. And for each two weeks sprint, you're going through with the client, with the product owner, and you're prioritizing, reprioritizing the goals. Because surprise, sometimes the, you know, priorities change in the middle of a project. But since we're reprioritizing at each stage of the sprint, there's a minimization of like things that can go wrong, right? So like the priorities completely change. You can react to that much quicker and then in a waterfall process. And yeah, each sprint, you prioritize project roles. You complete those set of features and then you create something that's potentially releasable, right? Because you've completed those set of features so you could have, you know, some, some product. And the question then becomes, you know, what does it mean to do a website using actual development, right? And I got hired by a previous next about a year ago and Kip Pepper asked me, he asked, he said, how do we get designers and front-end developers integrated into our Agile workflow? Because they had, they'd trained all their back-end developers in Agile and they were, couldn't figure out how to get front-end developers and the designers, you know, into that process better. Because they were, you know, transitioning from this, the waterfall method. So all the designs done up front and they're like, wait a second, how do we, how do we do Agile and web development that includes, you know, design everything? But by the way, does everybody here know Kim? Kim Pepper is a Drupal 8 developer. I think I have a picture of him somewhere. That's Kim. Not Photoshopped in any way, I swear. And I told Kim, like, I have no idea. I have no idea how to do all this stuff. But he, he and Owen Lansbury, who are the co-owners of previous next, sent me to a training and I became a certified scrum master. And then after that training, it became really obvious to me exactly how we do it. And the process of building a website with Agile development is style guide driven development. And the requirements for this are pretty simple. Component based design and automated style guides. So the entire rest of this presentation is just going to be talking about those two things and showing you demos of those things. So let's start off by component based web design. There's been a lot of talk about components recently, including several sessions already. I think there was a session right before this, it's about, about components. So when I say components, I'm talking about object and OSCSS, module and smacks, block and block element modifier. For some reason, we never decide what to call this thing, even though we all know what it is. It's web component in the sort of upcoming HTML spec. But essentially what a design component is, it's, you're trying to find a single chunk of design that you can reuse. So it's applied to a sort of loose collection of HTML elements. It's completely repeatable, even if you never repeat it. So like the header of your website is going to be a component, even though you won't have multiple headers on the page, but it's still discreet, repeatable chunk of CSS. And it's specific in that the, we replace the CSS specificity, which gets us into so much hot water, and replace it with a naming convention that's very specific. So you're, you have a, you know, a class name that is very specific, but it's very low specificity, because it's just a single class name on your rule sets. And they're, they're self-contained, right? So if you apply that class to something, it's, those styles are not going to bleed over into other things. And finally, they're, they're nestable, right? So you can have a sort of mini component that fits nicely into a larger component. Layout is actually just a certain type of component, where it just moves giant chunks of the page around, and then you obviously nest all of your other components inside the layout. Let's see here, let's, so here's a website that I did several years ago. And if you look at this, this is a good, good design system that was made. So it's, it was really easy to translate into components, because you can see here that there's a, there's a lot of repeating elements already. So we have this giant sort of teaser at the top here with name, and there's a category next to the date, and some teaser text, and another category at the top left here. And that's very similar to this other sort of medium-sized teaser, which also has this, this share count in red circle there. So bits of this, I think the share count is actually a mini component, right? So it's, it's, its own component, and then the larger teaser is a, has a certain styling of it, and because it shares a lot with this, this medium-sized as well, you end up reusing some of those CSS inside other components. So I, in true rational fashion, I've done iterations of this presentation multiple times. I'm not sure if I need to go over this at all. Who here has not seen this slide before? Oh, yeah, I'm about third at half of you. I don't know, what do you, what do you think? Should we go over this stuff again? Because I've done it at, at, at, I did it in Austin, I did it in Amsterdam as well. I'll go over it super brief. That way we get sort of a good balance for the people who have never seen it, and those people who have seen it a couple times already, geez, get on with it John. So to me, basically everything is a component, right? So every single piece of design is going to be a component. These base components, those are the design that you apply to an HTML element, right? So like block quote is an HTML element. Your selector for that rule set is block quote, and you are applying a sort of default design to that HTML element. This is super useful for like the wissy wig area of your Drupal site because a lot of times you don't have as much control over, you know, adding the right classes and the right markup in there. So if you style all of your sort of HTML elements with some default styling, it'll at least look decent than inside the wissy wig area. Layout component is another kind of component which, like I said before, is just moving large sections of your page around and is a container for all of the other components. And then all the other components, a component basically has five different parts. The sort of wrapper component itself, like if it's a really simple component, it may just have the one thing, right? So it's just a component. It's a single HTML element. It has a single class that you apply to it. You're done. Like that's, it's a really simple component. Actually, yeah, I want to go through it. So, yeah, go through this fast. So if it's a simple component, you just have a single selector, a single class dot flower, and it applies that design, right? And more complicated components will then, often, time to have elements where you are having to apply a class name to some of that, you know, HTML that's in this loose collection of HTML, right? So these are the pedals. So you would like add that class and make a rule set for that just to apply that particular chunk of design. You have flower faces, flower stems, flower leaves. And I want to make sure that you understand that I really did mean like a loose collection of HTML elements because flower bed, this is obviously a wrapper element around the normal flower. But it's not, it's not nested inside the flower. It's outside the flower, right? So just because it's, you know, dot flower underscore underscore bed, that doesn't imply that it is a sub HTML element in the DOM, right? It's not a child element in the DOM. It's these, all of these HTML elements are just sort of like next to each other on the DOM, not necessarily in any particular structure. Then we go on to modifiers, which is basically a variation of it. So you have a flower dash dash tulip and this applies almost exactly the same design, but slightly tweaked. We'll get these a lot of times in our designs where, you know, the like those teasers, right? So the main teaser heads has certain styling in a bit. And then like you've got a slightly very different teaser on a different page. And it's like 90% the same, but slightly different. So you end up reusing all of that same CSS and I usually put it in the exact same file. So like a component and its variation will go in the same file. And then you just add a extra rule that applies the tulip variation of the CSS, right? Then after modifiers, we've got state, right? So this is the hover state of our flower component, right? And there are various kinds of states. This one is a pseudo element, pseudo, yeah, pseudo class. And you also have like JavaScript applied classes. So that is pollinating. This would be, you know, some JavaScript event has happened and it's inserted this extra class into the markup, right? And then of course, media queries are states, right? So this is the depth stop version of the flower component. And don't forget the print styles are also, you know, media queries. So this is the print version. And then lastly, we have skin. This is something that is not used in many places. Like university sites like having skins and like Yahoo back in the day used to have like, you know, the main page was like all yellow because it's Yahoo and like the finance section then had to be all green because it's money. So, but the skin is basically, let me show you a skin. Here's the is night, yeah, the flower during nighttime. So this is a variation, a modifier essentially, but that class name is applied at sort of like at the body class. So it affects a whole bunch of components, right? So it's essentially just a modifier but where you define how it gets modified is a different place in the HTML. Whoops. So I actually have an automated style guide of this. So if you go to johnalvin.github.io flower power, you can see an actual like HTML representation of all this stuff. And if people don't quite understand, you know, the idea of buying components they can go there and get some examples. No, one thing I would say is that I didn't talk much about the naming convention here. And I've got a slide in a couple slides here that talk about triple eight. But I feel that sometimes people overcomplicate stuff. I've seen this on an actual website, which I've worked on. This wasn't me in particular, but it was on a website that it developed. And it's trying to describe too much things here. It's trying to come up with, it's trying to show you that this is sort of nesting HTML and you just, you don't need to have that kind of verbosity in your component namings. Oh yeah, this actually goes on for a little while. But I don't name the person who actually wrote this, but I would like to say that sucking at something is the first step to becoming sort of good at something. So it's okay to make mistakes, right? And I think that a lot of times we have a hard time naming things because we see this naming things is hard, right? How many people have heard this statement before, right? Almost everybody, right? It's, there's an old saying, an old joke. There are two hard things in computer science. Naming things, cash invalidations and off by one errors. And the set up to the joke is that they're obviously talking about a very serious thing, because they mention naming things and everybody knows that that's really hard, right? And the thing is that this statement by itself is wrong. Because naming things is hard if the names are user facing, right? And it's that if that's really important there, right? It's not true unless you have the if. So it's if the names are user facing. If, if, that's gone too far. Let me go back. Gotta love a good comic sound joke, yeah? And the, the idea behind this is that if you have like these words in your like user interface of Drupal, right? You have to make sure you get that stuff named properly. Like, you know, the, the tweet button. You want to make sure that all those things that people can see are named well and make sense. But we're CSS developers, right? So like the only people who see our names are inspecting the HTML, right? And as long as you document all of your names, the, the, and you know, those, those names are basically just for internal use of your team. So poor naming, giving it a bad name has a very low cost, right? So as long as you document it, there's not, it's not too bad because you have some documentation, the other developers read it and then they understand what it is, even if it's a really bad name. So I wanted to give people some advice about how to name things and not get stressed out about this, which is spend 30 seconds trying to come up with a name for your design component, right? Don't worry about it. Develop it. And then when you're done sort of developing like, oh, how it works in IE8, yay! Then you can spend five minutes just like thinking about it again, okay. Mm, mm, mm, right. And maybe like add a little to-do comment there if you think it should be renamed to something else. And then like commit it. Oh, also if you're doing like peer reviews, you can have somebody else spend five minutes thinking about it, right. And then commit it, right. And after some time you can refactor. I mean, it's okay. Because these are internal names for your team, for the people who are developing the website, it's really low cost so don't stress out. I've seen products go really off the rails trying to come up with these things. And the most important thing is naming conventions. So naming conventions is way more important than the actual names, right. The Drupal 8 CSS coding standards talk about the naming convention that we're using in Drupal 8. And that is essentially that the syntax that I was showing you earlier in that flower example is the same as things. So here it is again. You can go to the Drupal 8 website and see all of this stuff. But essentially the way that we're going to do it and we are doing it in Drupal 8 is the name of the component, if it's a multi word thing that you can't figure out how to do it in one word, then you put a dash in between the different words. So that's the component. Modifiers are, you know, you know when you look at the HTML element or the HTML source and you see a dash dash there that that means this is a variation of the normal component. And then double underscore means that it's a piece of the component. Sometimes a variant of your component will need special styling for a particular element so that's the way that thing will look. Then you have your different states, is, date, hover. I mean this is basically all the different kinds of variations you should ever see in your CSS. I have a very flat structure of how I keep my components organized because it's really easy to find stuff. You inspect that, if you're coming onto a project and you don't know what's going on, you can inspect the DOM, find the CSS class on the actual HTML element and then go look for that, you know, a file with that component folder. Now, how many people here have difficulty adding classes into the markup? Right, so the rest of you don't use Drupal. I'll give you one little sort of codey tip here which is the fugly selector hack. I used to have a picture of Morton on this slide but I took it off and tried to be nice to him. You know, especially with links in particular inside Drupal, it's really hard to get down into that A tag and insert the classes you want, right? So this is a very typical one. So say this is a node teaser, right? So then I can get at the node DPL, right? So it's fairly easy for me to add in this class name that wraps around the H2, right? So feature title there that I've got that class in but I can't figure out how to get the class that I wish I could use on the link inside the H2 is feature underscore underscore title dash link. I can't figure out how to get that into the Drupal markup. So instead I write some sass, right? And presumably you can do this with less as well. But I write the DOM that I wasn't able to change with Drupal and then extend into the class name that I wish I could have used. So above this I've got a rule that is using, that says feature underscore underscore title link that has all the CSS. And then at the bottom of my files I've got these like these ugly sort of fugly selectors that extend then into the beautiful bit. So this is super helpful because I find that if I'm looking at a really ugly selector while I'm writing my CSS properties I forget about how a component is supposed to be structured. I accidentally write a rule set that will bleed into something else. If I write it this way with all of my nice rules at the top and then the ugly selectors at the bottom it allows me to write very concise components that don't bleed into other things. So that's components. It was step one of doing style guide driven development. We can start at 2.15, yeah? Okay, good. So now we're gonna talk about style guides. So half-way point. I first started using style guides on in web development in 1996. And essentially it was just a PDF document but it was nice. Your style guide is a documentation for a design system. So you have this document and it describes exactly how you should be applying the design to different parts of your website or your corporate branding, the site of the truck, whatever. These are what documentation, what style guides are. And they're amazing. They're really, really nice. The problem is that out of date style guides are completely useless. They suck so hard. And the more that I would use style guides in web projects I would get designers who would be like, they're frazzled because they have strong deadlines and they're like, here's a style guide. So the changes that I discussed with the client for the last two weeks aren't in here. So this page and that page are out of date and yeah, you'll forget that. And then I'll forget that later on the project and I'll remember exactly what the style guide is and then they'll yell at me for not doing it the way that they said to do it rather than the way it was documented to do it. So I stopped using style guides, right? I was basically like, okay, you've got enough time to update the photoshop file. Don't worry about a style guide because it's never right anyway. But when I was looking at all the blog posts of front-end development, like oh, this is going on, this is going on, I saw one thing that caught my eye was because I'd used style guides before and I knew how much they sucked, automated style guides sounded really interesting to me. And this idea is basically that as you write your CSS, there's software that automatically generates the style guide for you, right? And I was like, okay, that gets around this problem of being out of date. If you're updating your styles and there's just a little bit of documentation in there that you also update because it takes like a minute and a half to do, then you can sort of ensure that your style guide is always up to date because you just tweak the CSS file right there and boom. So one of the ones that I like and there are a whole bunch of different style guide systems but one of the ones that I really like for simplicity is KSS, which stands for Niles Style Sheets or something like that, I can't remember what it is. But it is a spec for how you write CSS comments so that KSS parsers can go in and grab it and generate style guides for you. And the spec comes with a Ruby implementation, which if you wanna use, you have to build a Ruby app in order to use. So I didn't really like that one but I found a Node.js variant of it that actually worked when I tried it, which was amazing. And that's github.com.kssnode. In fact, I liked it so much. I'm now one of the maintainers for the project. So this is an example of a KSS comment. It's just so easy to write. So this is using CSS syntax but of course you can also use slash slash space like see it, sass comments, that works as well. The first line is basically the title of the component that you're writing. In this case, we're writing a button and then you can have zero or more paragraphs that talk about it. So like, this is a standard button suitable for clicking. And then I'll have a list of all of my variations of it. So there's a shiny button that you shouldn't press because it's a big shiny red button. And then there's a hover state. So you can have your variations and your hover is sort of listed here underneath. And then the very last thing here is basically it is a style guide and it is components.button. So what that last line says is you're building an automated style guide so you need some sort of navigation to get to all the places. So we're gonna let you create your own hierarchy of how you navigate through your style guide. So in this case, we've decided that we're gonna, one of the sections of the style guide is gonna be called components. And then we're defining that this is the button thing that goes under components. And you can have as many levels of the style guide that you want. So you could, if you wanted to have like components.forms.button, you can do that. It's up to you for defining the hierarchy. And the software will just parse through that and find all of your components and then create them in the hierarchy and build the style guide using the hierarchy that you've designed. And that's it. That's all you have to do as far as writing KSS. Super simple. And then you just have the parser go and do it. So essentially this is what we have. Since you've built all of your design using components you can think of all of those things as like a component library. So you have your CSS source and sometimes you can have different, what's the JavaScript preprocessor? Sorry, what was that? Oh, no, no, less. Yeah, that's another SAS preprocessor. We're talking about the JavaScript preprocessor. Coffee script. Yeah, there we go. Yeah, so coffee script. And they can all be generated and you end up with this individual source here. And then over in the corner there is Drupal and it's sucking in of course all the raw source that the web is expecting, which is CSS and HTML and JavaScript. And your style guide is reading through all of your CSS source files, whatever language you happen to be using. And then generating a stack of HTML files, static HTML files that describe all of those components. And then it's sort of hot linking in the same HTML and the same CSS that are going into your application. So then really nice thing is that then when you look at your style guide, it is showing you an exact representation of that component. It's not a picture of that component, it is the real component living in the style guide the way it will live in your application as well. That's super, super useful. I'm gonna show you a demo now. But the first thing you're gonna see in the demo is that I'm using a task runner, right? And a task runner is, it's basically, well, these are all the different things that you can do with a task runner. It's a way to automate a whole bunch of different steps. If you're only doing one of these things and then you don't need a task runner, right? If you're only just building SaaS or building CSS from SaaS, then you don't need a task runner, right? And so that's what I was doing. I never used grant or anything like that because we're just making SaaS or just making CSS. And then as soon as I started using style guides in my system, I needed a way to build the style guide. So then I'm doing two things. And then I had to pick a task runner because then it allowed me, instead of having to type two commands, like do the SaaS, now do the style guide. It was really repetitive. Now I just have a single command, which is like gulp watch. And it watches all my SaaS files and goes, oh, let's generate some CSS. Oh, you change the SaaS file, I'll regenerate the style guide, right? So that's what a task runner is for. And right now, by default, in our project to previous next, we're doing those first three things here. We're building CSS. We're linting all of our CSS and all of our JavaScript. And then we're building the style guide. We have plans to also add visual regression testing to that, which was an excellent session on that earlier in the week. And then of course you can do live reloading, which we're having some issues trying to get it to work. If you know how to get that integrated with Gulp, by the way, come and see me and talk for it. So all of these things you can do with a single command, right? So you run the command, it generates a SaaS, can reload your browser after it loads all that stuff up. Let's do a live demo. So watching software get installed on Wi-Fi is really fun. So I've done it ahead of time. And then I'll just go over the commands that I did. So I get cloned the Zen theme, and then switched over to the 7.x, 6.x branch. I've got about 85% of the way done with having a fully described style guide inside this version of Zen. So I've switched to that branch. It's sort of in the alpha level stage. Everything works, but some things might change before the actual 6.0 version comes out. And the first thing that I'm going to do is, right now I have some Ruby requirements. So I have to run bundle install, which will read from a gem file. Let's see here. So it just reads, like I'm using breakpoint in SaaS to control media queries and stuff like that. So it just reads through this real fast when I type bundle install, and installs the minimum requirements for this project. And you see here, it's fetching all that stuff. It's installing SaaS, installing Compass. And then at the end there, it automatically creates a gem file.lock file, which says these are the exact versions of the software that I happened to just download. And you may want to share that with other people on your team, because otherwise it's going to suck for you. So I always add that to get and make sure it's in the project so that everybody is on the same page as the start's versions go. And then KSS node is a Node.js application. So I have to run npm install, which is the same thing. It will look in the npm install. It will look in the package.json file, and then grab all of these node things, including KSS. And we'll install it here. And you can see it's going through. This took so long during the keynote, scrolling much better, and finishes. And the last thing is that, like the gem file.lock file had the exact versions, Node has the same thing, but you have to write an extra step. So npm shrinkwrap-dev will create this file, which says these are the exact versions of this software that I use so that everybody on your team is using the same thing. So that only the first person who does npm install has to do this step, because once your project has an npm shrinkwrap file in it, or a gem file.lock file in there, when you type bundle install, and when you type npm install, it actually ignores the original gem file. It ignores the original package.json, and just looks at the shrinkwrap, just looks at the lock file, and builds from that file. And of course, yeah, got to add it to Git. And yeah, so that's it, as far as like requirements are getting added in installs, and like I said, I'm using gulp, which was also installed when I ran npm install. So I'm gonna type gulp, and it's going to clean out any old CSS here. It started generating some style guide stuff. So here, it's sort of listing all of the different files that it's parsing, grabbing some HTML. Like I said, it's Alpha Software, so I'm getting a warning here, but that's just because I haven't updated the layouts yet. And then it's finished, right? And then it's doing some linting at the end, and boom, it created a style guide just now. If I go in, this has just sort of proved to you that that folder used to be empty until five seconds ago. And if I hit reload now, yeah, there we go. So it just, thank you. I'll be here all day. Yeah, so this is a style guide, and this is the hierarchy that I specified inside my KSS comments here. So I've decided that the first section of it is gonna be color sass, and then my base HTML elements, my layouts, and then my components. I have a feeling that I'm gonna be playing around with how I organize my components in my style guide because, well, here's a project that I'm actually developing right now with Previews Next. With a great team. But if I pop into the components, there's like 43 different things here, and it gets a little bit long, so I need to play around with reorganizing it. But if we look at this, you're going to see all of the sort of boilerplate components that Zen includes. And to make this easier, because obviously you can't see this, it's on my local system, I have actually taken the Zen style guide and then posted it to GitHub, which is where, no, this one. No, it's not. Oh, I know where it is. Uh-oh, I didn't load this ahead of time. Gethub.com slash JohnAlpin. Zen style guide. Then click on this link. There we go. Okay, yay, Wi-Fi. So this is the publicly accessible version of what you get out of the box. It has a boilerplate list of a bunch of different components that you probably will use, and anything that you don't use, you can literally just like delete an entire folder, like, I don't need that component, and then you just run gulp again and your style guide is now up to date again. So this shows all the colors that are in Drupal by default. I'm kind of feeling like there's a little bit too many colors here. I'm going to want to simplify this a little bit before I do a 6.0 release. But you can see here that it's documented all these different colors, which is really nice. And then I actually have a way to describe the colors using functional names, rather than just color names. Instead of, you know, let's make this border red, let's make this thing the border color. So if we go up here, one of these gray ones is going to be, yeah. So this gray medium light color, which is actually, you know, pound CCC is inherited by the border color. So anytime that I use border as the name of my color, it's going to inherit it from here. And there's actually a way with this system, which is called chroma, to have different color schemes. So if you are Yahoo! or, you know, a university and you need, like, the exact same design, but different colors on different sites, you can create a new color scheme where essentially you would just have, like, somewhere in here, you would need to specify, like, a primary or secondary color, something like the big colors, right? And then you could create a new scheme and you just define the new primary and secondary colors and everything gets inherited properly so that if you're down at the level of, oh, I've got my auto-complete select background is inheriting from the primary color, I don't need to redefine this color in the new scheme. I'm just redefining the primary color and it all inherits nicely. We needed this for a project recently. So that's, in a nutshell, that's what chroma does and it's included with Zen. But this style guide then... Yeah, so we look at our base and this is a listing of all the HTML elements and their stylings, headings. It's really nice to just be able to see how all of these different bits of here will actually look on your site and you can see, you know, the generic link styling, right? Obviously you want to go in and add your actual link styling and then run Gulp again and you'll get an update version. Let's do that now, actually. Let's go into components and let's tweak this box component. So I'm going to open up. I've got a box.scss file. Here I'm using the SAS syntax for the comments. Super simple box styling for LA. I'm pointing at where I'm keeping my markup. Right now, my markup is being kept inside a handlebars file, which is .hbs, but you can also just use vanilla HTML. There is a feature that's getting in that is almost ready to go in KDSS node, which allows you to use twig for your styles, for your HTML elements. That's going to be really nice. The nice thing about handlebars right now is that it's really close to the twig syntax. It's going to be in Drupal 8. We're going to go back now and see. That's pointing at where your markup is, how you're applying these styles to it. Let's change it so that we're going to use ridiculous like 10 pixels and more padding. I'll just actually wait. Before I hit save, I should really run GulpWatch. When I first run GulpWatch, it's going to assume that you've made some changes before you started it, so it's going to regenerate everything real fast. It's done. If I go here, because I haven't hit save yet, if I reload it should still look the same. It looks the same. Now I've got to go back into my editor, hit save, and then I have to real quick to my command line. Was it fast enough? Or didn't I hit save? This might be the live demo error. Thank you for debugging my problem. I'm just going to close that tab so I don't do that again. Go back to components. Box styling for LA. It regenerated already. Now it's 10 pixels and super fat padding. If you are editing the CSS and you just don't go up here and also edit the comments, you're just being dumb, because it's just incredibly simple. You end up with a style guy that is always up to date. Let's go back to the last couple of slides here before I take questions, because I haven't really talked about the process. We've started doing this the previous next, and it's been a huge win, a really big win for the designers, for the back-end developers, and for the front-end developers. One of the things that it does is it allows us to do decoupled development, because you remember way beginning I had that waterfall diagram where the back-end developers have to finish making the HTML before I can style it. Front-end developers have to go second. But because we're designing inside the style guide, we can literally, as soon as it designs, if you've worked with a designer and you've finished the design, you can start making your components in the style guide while the back-end developer is writing all the custom PHP for that goes into that component. This is an actual quote from a back-end developer. I love the style guide stuff. It means I can make things pretty. Because I no longer have to, as a front-end developer, I no longer have to touch Drupal, really. The back-end developer can just look at the style guide and go, oh, I need that class and that class and this is a rough HTML. I'll just use that inside this TPL file. So the responsibility of who makes the theme-level change is decoupled. It can be the front-end developer or it could be the back-end developer. That's a huge win. And don't underestimate this. I can make things pretty aspect of it because it's really nice for a back-end developer that they can make things look really good. This is essentially why Bootstrap has become so popular. It's not from front-end developers. It's from back-end developers or people who don't know front-end that are able to make things look pretty with Bootstrap because they can just sort of copy and paste. You can do that with your own custom designs by creating a component library and by automatically generating your style guide. One of the nice things of having food poisoning yesterday was that I got to this... The first thing that I got to go to was as a boff. I managed to drag myself out of bed about style guide generation. I thought it was going to be more technical. The things that we would talk about, but everybody wanted to talk about process, about how this affects the way people actually work. And this style guide has become basically the key feature of your process that allows your designers, your front-end developers and your back-end developers all to work together. And you end up with a whole bunch of wins. The clients can see work progressing faster because they don't necessarily have to have all of the PHP bits done before they start to see some of the designs. Because that was one of the things that traditionally... My project manager would freak out because I'm doing some theming and everything looks really bad until the last week when all of a sudden everything magically comes together and looks like a real design. Having this style guide show the little chunks of design, everybody gets a much better sense that we're actually making good progress on this. We're not sweating quite so much as we go through the process. Lawyers are happy. This is something that I learned yesterday was that they were like, as a university IT person, how do I convince all these other colleges that they have to follow a style guide? They just want to do whatever the hell designs that they want to do. And somebody else came in and was saying, well, talk about accessibility now, people that aren't following accessibility standards are getting sued for millions of dollars now. They're starting to really go after people who don't follow the accessibility laws of 508 compliance. Having a style guide that meets those accessibility requirements means that the lawyers are happy. They're like, look, we've built this thing that will ensure that there's accessibility in your site. Therefore, you over there in the arts history, you have to follow the style guide. It's really, really interesting. I keep learning more about wins of how you include style guides and how it's affecting people's processes. I would just love to learn more about how style guides are affecting different people. I hope I've been able to convince you what a game changer this has been for myself and for other people who have started using this in their process. Thank you, and let's start having some questions here. Put the mic here. Is it on? We use a style guide. We actually use the style guide module inside of Drupal. We have designs made, and then our theme is just going in and basically do the style guide page while we're working on all the other stuff and that way the theme sort of moves as we're working. I'm just curious if you see the two could be complementary one another or is one better than the other, or did you try doing this way and I'm going down the wrong path? I haven't looked at the style guide module in a long time. Somebody asked this exact same question at Amsterdam, and I just haven't had time to look at it again. Way back when it was first written, I was sitting next to Ken Rickard when he wrote it. I know the capability just happened. It was nice for the time, and I don't know about his new capabilities, so I would love if somebody would give me a demo of the style guide module. The reason why we picked KSS Node was two reasons, basically, is that it gave us the ability to have a standard tool that we could use on any kind of project, like a Drupal project or app development or something else. It's independent of Drupal, therefore, we're not dependent on a Drupal 8 version of the style guide module being written before we do our first Drupal 8 site. That's why we picked KSS Node, and we were also trying to get out of Sandbox a little bit by using a tool that's available to anybody who does web development. We're hoping to leverage more contributors in getting a better sense of what's out there. Like I said, if somebody's used the style guide module, come show me a demo, please. My question is, you know, Drupal outputs a lot of crazy things, like views and exposed filters. Really? There's a lot of markup and stuff to that, and I was wondering how you would want to handle things like that to work out the style guide model that you sort of have here. Right. So when we do it in the style guide, the markup that we write, of course, is right now, it's in a handlebars file. And we try to do, like, an idealized markup. So, like, if we could get Drupal to do it, we wish it looked like this, right? Now, I know that sometimes when we go to the actual implementation in Drupal, we can't quite get it the exact same way. But if we've written the CSS itself, you know, good enough, a lot of times we can just sort of ignore, you know, six or seven layers of divs there and just apply, like, the class name on, like, the outermost div, and then, like, on a couple of the inner divs, right? And you still get the same design, even though oftentimes what will happen is there'll be some random middle div there that's getting CSS from the date module, and then we have to, like, override it. But that's, you know, if you have a really good backend developer, they can change the markup to do whatever the heck they want, right? But sometimes we'll know ahead of time that the markup that Drupal is going to give you, like, for the menus, it's got to be a nested list of unordered lists, right? So we know ahead of time that it's going to be that. So when I was creating the boilerplate HTML for Xen, sometimes I would go in and do an HTML spec on a particular piece of Drupal code, and then copy and paste that chunk of HTML into my file and my style guide, and then start, like, cutting stuff out, but still having the sort of skeleton of what's needed, the skeleton of what Drupal is actually going to give you. You mentioned the previous session, which was about Pattern Lab. And my question is to understand how you see the process of how potentially what you're describing and what Pattern Lab does, at least to my understanding, how those things work together. It seems to me, from a first glance of seeing these things, that Pattern Lab generates a style guide that we then use to define our theme, and this appears to be defining the theme that generates the style guide. So if my understanding isn't correct, I'd like to be challenged, definitely, but my question is how does the process work for those two? Right. And maybe I can go back to that one slide. I had a very similar question in Amsterdam. Yeah, this one. Right. And the places where I've drawn these boxes, like, this is the component library, and this is the style guide over here, and this is the application. Those are kind of arbitrary. The thing that I wanted to say was that these resources are being shared among all these different parts, of the component library as being inside the theme, and therefore part of Drupal, part of the app, and the style guide is separate. For example, this style guide was then, and, of course, is inside the theme, too, so maybe it's part of the theme and it's part of the component library. Those are kind of arbitrary definitions of where the things are. Really quick, Pattern Lab, for those of you who don't know it, essentially it's an alternate style guide generation tool that's PHP-based, and it's a very similar thing to KSS Node, and I didn't get far enough. It was one of the... KSS Node and Pattern Lab were the two things that we were evaluating, or they were the last two things we were evaluating. It's going to be one of these two, and we ended up with KSS Node. So I didn't get into the details of how you specify a component in Pattern Lab, but the only reason why we didn't choose Pattern Lab was because out of the box, we went to the elements, atoms, organisms way of describing web systems that Brad Frost came up with, and we weren't using that approach, so it was the nice thing... I mean, you could still create a hierarchy that was like that in KSS Node, but it does not care about what your hierarchy is. You define it, so it's super flexible. So it would still adopt, like Brad Frost, all that stuff and put it into KSS Node that would be easy. Understanding that you picked one, that helps me a lot. Thank you. I was just kind of curious how this ties into client deliverables. Are you delivering the style guides, or are you delivering some homepage, PSD, program page, PSD, and then building the components out from there? So I'm going to answer the PSD question part of it first. I've worked with two different kinds of designers at Previous Next, one of whom is still developing their CSS skills, so they're more comfortable doing the designs initially in Photoshop, which is totally fine. So you just make sure that they are understanding that they need to think of this component methodology so that they're building discrete design chunks inside their Photoshop file. And then you can have a conversation with them about, okay, how do I extract those out into design, and how do the different components work together? And the other kind of designer that I've worked with is like they also know CSS. So it's whatever processes is more comfortable for the designer, right? And just as a front developer, you have to work with them so that this other designer, he actually ended up learning how to write KSS comments because it's actually really easy. So then he makes some of the components himself, right? And then I'll do a peer review just to make sure that he's got all the front-end, performance bits, all the dots above the eyes and cross-tees and this sort of stuff. So the approach that you work with a designer depends on the designer, and just have a conversation, that's the most important bit. There was a second part of that question, though, and I forget what it was. How does it tie into client deliverables? Right, client deliverables. So to... I would say that, yes, it's a deliverable, right? And the reason for this is because the website that they get is a living entity, right? And you may not be the next developer that modifies this website, right? So if you've got a style guide in place, you're lowering the cost of further development for the client. So making sure that they understand that there's a style guide here that future developers can come in and learn how to apply the same designs to new features later, that's a huge win for them. So absolutely, it's part of the deliverables. Sometimes they'll have internal developers that they have on staff and will do the initial design... or the initial implementation and then hand it off and they get this great style guide and as long as they keep it up to date, which is fairly easy to do, then they can continue on their way and adding new features to their site with their internal devs. Basically, have you found that having this helps reduce the number of deliverables? Currently, we'll do five or six page designs and our designers sometimes have problems actually figuring out the components they can reuse. I'm trying to help figure out a way to reduce the number of designs so we don't have these slight variations and issues like that. Yeah, one of the things that one of the other sort of process wins is with designers, if you've got a designer who's not on the project full-time, they've just done some designs and then they've finished up what they think is all of the design and they go off and they're doing some other project and then they come back like three weeks later because there's one thing that you forgot to design. They come back, sometimes they can be so frazzled that they've forgot what they've designed before and they're like, oh, I've got a new feature, I haven't heard half an hour to do it before I have to go on this other project and I've got to build up a new design. It looks completely different from what's on the other site. So having a style guide, like showing them what's already been built, like they can go and look through their designs on this style guide and they're like, oh, well, it just needs that and then it becomes a five minute task for them instead of a half an hour task. There's a huge win for that. The style guide becomes a great place for everybody to know what's going on and familiarize yourself with the project. The very first time I used KSS node was actually on a project that I was brought in late in the project just to help with the development in front of it. It was a big, like four or five different front end developers working on this project. Huge code base and they were like, ah, you know, just jump into tickets and you'll familiarize yourself with the code bases that go. Three months later I still had no idea where anything was because it was just huge and confusing to me and so I started implementing a style guide for that site as a defense mechanism so that I could figure out what was going on. We'll do these last two people in the line here because it's over here as far as time-wise goes. There's nobody else coming in here but we'll finish up these questions. Feel free to leave if you need to go to another session. Otherwise, are there any other sessions? Plenaries last. So the KSS node is good for visualizing classes. Is there anything, or does it handle visualizing mixins? Is there anything automated for... Right, so, um, if you look at this, the syntax here, there's nothing really that's tying this comment to the .button class except that it happens to be in the same file. Like KSS node, like you can write a completely different CSS lecture here and you have no idea, right? The way that this gets matched up in the style guide is that you've written the CSS lecture and then presumably in... Well, I don't have a markup in there. If I had pointed out an HTML file in this comment, the HTML file is the one that has the class in it. So they just get matched up in the normal way. HTML and CSS have been matched up. That means that you can actually describe anything you want with the KSS comment, really. It doesn't have to be about CSS. So if you... Actually, if you write a comment like this without a link to some separate markup, it's going to assume that it's a SAS preprocessor. And if I go over to the demo... Where's my key? There it is. I guess what I'm wondering is... Let's say you have a mix-in that's like big-ass text or something like that. Like, how... Is there a way to visualize without that being applied to a class, specifically, in the code base? I know what you're saying. I haven't got that far in my exploration with Stagguides. But essentially, I've got a section here that talks about mix-ins. So I've got... I've documented my Clearfix mix-in, which is just inside my SAS folder here, so that I know, oh, I can use this Clearfix mix-in. And I've got our RTL mix-in that will apply right to left styles if I need it. So visually-hidden mix-in. So you can describe all your mix-ins just using KSS comments and just putting it inside the hierarchy however you want. That's as far as I've gotten. It's actually a really good idea. I do have an actual component, though, that is dot visually-hidden. So that one gets described in the Stagguide. So if you click on that in the components, then you would see how it gets applied. But it's a little bit separate. Maybe I could add a link that says, if you want to know what this mix-in looks like, go look at this other mix-in, or this other component. Yeah, that makes sense. Yeah. Thanks. Last question. So you talked about, you have a bullet there for layouts as a component as well. I think this is broken right now. Like this last... Anyway, go ahead. Okay, so I'm just wondering if you could talk about the intention or how that would look within the frame of the KSS. That is an excellent question because you're like, well, wait a second. It's a media query. So if I jump over to the ACC one, the way that the Stagguide looks is you can change it the way you want it to. This is a default way that the Stagguide looks. The markup in the Stagguide is written in such a way that the styles that apply, you know, like this gray sidebar, are completely separate and won't bleed across into your own custom components. They all... All those classes are like KSS. Whatever. Or KSS-whatever. So they're not going to go into your components. But you're right. This is a layout here and the breakpoints are all wrong because the layout normally is going to be full-width of this window instead of just this little section of the Stagguide. That's one of the open issues in this is that I want to figure out how to get it so that the media query applies properly to that thing. It's not going to be too hard just like I haven't got to it. There have been too many other features implementing. So, yeah. Thank you. Thank you very much.