Style Guides with Mina Markham

Mina Hey!

Mina Thank you for asking me, this is great.

Mina Yes I am; I've been there about three months now.

Mina Thank you.

Mina Yeah, I was there working on the Marketing team, doing some similar work to what I was doing for the Clinton campaign, so yeah, it's been great.

Mina Very hot!

Mina Sure, OK. So, to set the scene a little bit, I was the first engineer that was hired on the tech team. I was actually the fourth one in the office because I had to move from Austin where I was living to Brooklyn so it took me a while to get there.

By the time I was in the office, we had our Director of Front End, Kyle Rush there; three Front End Engineers and a few Back End Engineers as well and around maybe the second week of me being in the office, he approached me, he being Kyle… we need this Bootstrap or like this Pattern Library; I think you might be a good person to do that, do you think it's something you can take on?

And I immediately said yes, because I actually had been thinking about that in my head as well, trying to figure out how to broach the topic and how to bring up, I want to do this thing because I think it would be beneficial for us, but luckily it was already on his mind and it was something he really wanted to do so I was lucky in the sense that I didn't need to try to get any buy-in because it was already there. So, I was kind of prepared in my head to try to convince people and I kinda got this gift of, we need to do it; please do it. I'm like, that's exactly what I wanted to do, this is great!

Mina Sure. Mainly, I had no way of knowing what the velocity would be like at the time because I'd never done anything like this before but I knew enough to know that we were going to be hiring a lot of people very quickly, we were going to be moving very quickly and it seemed to me that we needed some kind of system or some kind of guide in place so that people could build apps and web pages that were all very individually consistent and on-brand.

Also, at the time I was hired, the site that we had was… the first version of the site was kinda very inconsistent in a bunch of places and so me just looking at it and going from pages, I was seeing the visual inconsistencies on it and I wanted to figure out a way to address it and solve it so I started doing it officially after I was given the OK to do this project but in my head, I was doing a visual UI inventory: OK, we have ten different kinds of buttons, we have all different kinds of blues, all these different icons and so I was seeing all of this differentiation between elements and wanting to figure out how can we fix this.

Mina No… yeah, the first version of Pantsuit… I built two separate versions in my time there. The first one was based on the site as it existed when the campaign launched and the goal of the first version of it was a complete re-write of the underlying code for maintainability, for modularity and for being able to build things and iterate quickly, but I couldn't change anything visually; it was one of the key points was that I couldn't do any visual changes because we wanted a one-to-one UI parity for the sake of A-B testing, so my first goal was to re-write everything while changing nothing. And that took a lot of… it's a little frustrating on my end, mainly because the reason I wanted to do it was to fix the inconsistencies and then I was told I couldn't do it, because everything had to be exactly the way it already was so then we could then start testing things, iterating and making improvements but the very first thing I had to do which is, don't change anything, just make the code easier to work with.

Mina I think I snuck in some changes here and there! Mainly they were concerned with anything that would potentially skew our first few tests; they wanted the first test to be just testing them, make sure the code base was fine and didn't have any detrimental effects to the site so I think I snuck in a few things here and there; maybe I got rid of a couple of unnecessary blue colours or something but for the most part, I was very much like one-to-one nothing changed.

Mina Well, there was an effort to completely re-design all of hillaryclinton.com properties and applications so in conjunction with completely re-doing the visual look of the site we re-built everything code-wise, visually-wise: everything was re-done.

In that process, a new version of Pantsuit, it was obviously needed because it needed to match what the re-design was going to be and so I took that moment to basically re-write Pantsuit again entirely. It kind of changed some of the architecture for things that I was noticing weren't quite working the way I thought they would or from feedback I got from the other engineers about how they were using it so I took the opportunity and when I had to visually change Pantsuit to match the re-design to also change the architecture as well.

Mina We had… there was the one repo and so basically while everything was in development, I had the master branch that everyone was using that code and pointing to build sites as we were continuing to develop the new project but yeah, we had… I just used a different branch to write my code that way and as the team who was doing the re-design, for one, we worked off… let me back up!

Pantsuit itself was a completely different separate project in repo from all the other sites that were consuming it so what I did was I would build things, the fundamental foundational stuff inside of the Pantsuit project, the repo itself; import that… I would import that into the re-design product that the entire team was working on and as I would build the actual web pages, the interfaces, I would either, if I started building it inside the project itself, I would then copy that and port it over to the Pantsuit repo, commit it, add it… bump the version and we would then re-import that new version and the re-designed site repo, so it was a lot like a circular kind of process where sometimes I would iterate on the UI inside the Pantsuit project itself, if I was working directly inside of the particular components or if I was working in a larger interface and was making tweaks to the larger interface that I thought should be ported back into the library, I would then move from the product to the system, so it felt at the time, it was kind of like more of a fluid design in the browser type situation, because after I got the fundamental stuff, I did separate inside of the Pantsuit project itself but after that, all the iterations tended to be in the browser, having indirect conversations with our web designer and building things on the fly and then porting them back over into the system.

Mina Yeah, that's right.

Mina Yeah, that sound about right. When I built the second version, initially I built everything, the foundational stuff like the CSS architecture and the organisational structure, I built all of that separate in its own Pantsuit repo and then as the designer was iterating on the website, because that's the project that Pantsuit was built for and was the main one consuming it, as he would iterate on the UI for the site, either he and I would sit down, decide OK, do we think that this would be beneficial outside of this context and if it was, I would then port it back over into the Pantsuit library.

If it wasn't, then it just stayed inside the website, the main website project itself, as an additional CSS file. So it was a lot of… first it was me and our Design Lead deciding if we could foresee a use case for any particular component outside of the context he designed it in and if we could, I would go back and port it.

After the site became live and more people started using the Pantsuit system, I would start having weekly sessions with not just me and our Lead, Victor, but also the other designers and engineers who were using Pantsuit and designing with it and say, have you guys been working on anything that you think should be in the library and if they have, then they and I would talk about it and figure out the best way to get that into the library itself.

Mina Yeah, that's a good way to put it. The way I would describe my job to other people was that I was like the translator between engineering and design.

Mina And so people tended to come to me to figure out anything to do with the visual, the UI, decide to figure out the best place for it sometimes, the best approach on how they should create it, how it should be implemented, so I kind of became this hybrid straddling a couple of the worlds.

Mina I don't think I ever had to push back. We were kinda conservative in the sense of what we put into Pantsuit; we really kept the Library itself pretty light because we didn't want the extra CSS… because when you consumed Pantsuit, you got the entire Library, there wasn't any modular aspects so you couldn't pick and choose which components it was just because of the way our build process works so for that reason, I kept the library pretty intentionally light because I didn’t want a lot of extra CSS being served to people who didn't need it.

So, it was kind of rare that something got added to the Library after the first initial couple of iterations of it. I think one instance of something being added was, we added a pagination that was being used for… I built it for the blog and I think we had some other project that needed to have cut to paginate some different pages so I thought, OK, since I already have this thing built, I'll just stick it inside Pantsuit and you guys are already consuming Pantsuit so that way you can go ahead and get it for free.

So yeah, I pretty intentionally didn't add a lot of things to the Library because I didn't see the benefit of adding on a lot of extra code for what might end up being two projects who would need this particular component so I guess the answer to the question is, I really tried to see, was there more than a couple of use cases that we see this being used for? If we only think of one or two then maybe we should do it just one-off in each individual project and be done with it.

Mina Sure; I built Pantsuit, when I say hillaryclinton.com, what I meant was, all of the content-driven pages, that was the first consumer of the site, so it was the Home Page, the Biographies, Issues pages, the Blog, State specific pages; anything that had a lot of heavy content that was the first product that consumed it and then we had other separate projects that were like the Donations platform, the Events platform, Sign-up platform; these one-off special projects like the roulette game we had where it was a side by side comparison of where Hillary and Trump were doing in any particular year so we had those one-off type fun projects; they were all under the umbrella of hillaryclinton.com but they were all separate products that were run by separate teams within the Tech team itself and they all in some form used Pantsuit as a foundation.

Mina How did I market it? It's cool, it's fine.

For one, I built a documentation site that I felt was pretty comprehensive so that people knew what it was and how to use it and then whenever I made updates to the Library, whenever I bumped the version or add new components, I created this automated Slack hook that would ping our main tech channel to let people know, hey, there's an update to Pantsuit; you can look at the code here, you can look at the docs here, so every time something new happened, people were made aware and the onus was still on them to either upgrade their version of Pantsuit in their project or whatever but I made the marketing of it after the initial reveal where I just told people about it, that it was a thing that existed, every time an update happened, I made that kind of an automated thing so that people just like, oh hey, look the Pantsuit Bot told me there's a new version of Pantsuit…

Mina Yeah!

Mina But also, all of our new projects started from this boilerplate that one of our Front End Architects made and that automatically just included Pantsuit so people already had it when they started their project; if they used a boilerplate that was brought in for them, so after the first big reveal, everything happened automatically; people just had it and they knew where to go look for information on how to use it.

Mina It was kind of a blank slate; it literally just included the dependency for Pantsuit; it didn't include any components per se, but the document…

Mina It was just a white page but the documentation I actually did put a bunch of different template examples, like, here's a fully formed header, so people could've gone for the docs and saw various templates of a sticky header versus a normal header or a footer and just taken the code from there but the boilerplate itself didn't do that.

Mina OK, I think I'm kinda weird because I love documentation!

Mina I like writing it but I guess I'm in the minority in that sense but I used KSS-Node

Mina And I included that inside the Pantsuit repo, that along with Assemble, this templating static site generator, templating language, used those too in conjunction to build out documentation or just the documentation site/the Style Guide, so with KSS Node, the actual documentation took place inside the component files themselves in comments, so I would use a bunch of silent comments to document the code right above the component in its own Sass file.

Mina I feel like some people and some engineers who were using Pantsuit would've just went straight to the code itself and saw and looked at the documentation there because all of the docs, it was literally inside the code base so you didn't actually have to go to the site to read the document if you didn't want to.

So in that sense I put every piece of code I documented inside of its own component file but for some of the larger pages that were talking about our CSS coding standards or things like that, inside of the Pantsuit repo itself, they didn't just include the code for the framework but also included all of the pages for documentation, so, using the site generator from Assemble, I created individual HTML files where I put all of the more content-heavy documentation like how to use our colour palettes, guidelines, things like that.

So, those two things combined, KSS Node helped with documenting the components themselves but the larger overall documentation was handled by… actually Handlebars files for Assemble and the snippets to actually show the living examples of the components, those were individual HTML files that I put inside this folder in the Pantsuit repo called Snippets, and I would link to that HTML file in the CSS, KSS-node comments so KSS-node has this really great ability, if you tell it what HTML file to look for a code example, it'll render it inside on the page itself, so that was how I handled that part. The only down-side to that is meant that I had to go to a separate place to update the mark-up if I needed to but that wasn't that big of a deal.

Mina Yeah, that was a lesson I learned from the first version because the first version of Pantsuit, I tried to do all the docs in KSS and it just, I hit a really weird spot trying to document all the colour variables because I wanted to actually show the colours rendered on the screen and I ended up writing this huge comment because I was writing the mark-up in the comment itself.

Mina It got really weird and wasn't particularly maintainable so for the second version when I was able to not just re-do the Library, but re-do everything, I talked to our main Front End Architect and I asked him to build me this build system that would allow me to render this type/site??? but also to render the KSS-node comments as well and he came up with using that in conjunction with using the Assemble site generator to solve this problem for me.

Mina We didn't really test Pantsuit itself per se. I don't think that it helped in the sense of…

Mina Testing components, things like that; people did that on their own particular products so Pantsuit helped when they needed to build something quickly for a new test or whatever, but I don't think… Pantsuit itself, we didn't test it and it didn't really give a good… what's the word I'm looking for? It didn't really give a good guideline to who you should test components; I guess that's the best way to put it. If I actually had it my way, we would've done more regression testing on Pantsuit but given the timeframe we had, the resources, that didn't pan out so much but one of my dreams was to do visual regression tests not just on the site but also on the Pantsuit product itself, because I needed to know if I inadvertently broke something!

Mina Yep.

Mina Yeah, something like that. Micah Godbolt, I know he does a lot of talks about this, but ideally what I wanted was, either some kind of overlay for a diff of what's changed, if anything changed, or maybe a gif to show before and after, but it would only spit that out for something that did change.

So, if I changed the colour of a button and the only diff it shows me was that button change then I'd be like, OK, fine, that's exactly what I wanted. But if it spits out a bunch of other stuff that also changed that I didn't intend to change, I'd be like, OK, wait: something went horribly wrong; let me go back and figure out what I did.

In the absence of being able to do that automatically, I did that manually and I had to be very careful, just because… I guess I take it back: I didn't have to be that careful because Pantsuit was versioned and every project was using a particular version of Pantsuit so it wasn't like if I committed a mistake and pushed it up live, it would automatically break everything, because it wouldn't; people actually had to opt into the change I'd made so in that case, it was safeguarded from immediately breaking anything, but unless I was pretty diligent about tracking every instance of something, there was the potential that something could break and that's why I wanted the visual regression test to give me a safe… make me feel a little bit better about making these widespread changes. I didn't do it very often but that would've made me feel a bit more confident if I had that additional layer to check.

Mina It was both, depending on what product you were talking about. There were three different ways that people would consume Pantsuit: there was the manual way, which they would just take the source code and include the Sass files into their own project.

Only one product did that and it was the donations platform and they did it because that was the best way to keep the codebase down. There was the… we had compiled versions of the CSS, just compile CSS and versioned numbers up on our CDN and some people pointed to those compiled files and that was mainly done by any back end applications that didn't have a front end build process associated with it but still needed to have a UI layer attached to it, so there was that way to consume it and in that case, people would just change their source code to link to a different version of the CSS file.

The main way people did it was through npm modules and if they wanted to bump up the version of Pantsuit, they would change the number in their package at JSON then the new version would be bundled up into their larger CSS file in that way.

Mina Yeah and those last, those two other versions, the compiled CSS and doing it manually, those were both added later, based on the feedback I got from several different people because the very first way you could consume Pantsuit, the only way to do it was through the npm module, that was how it started out and as I started hearing more from my people who were trying to use it but couldn't get it to work in their project, I realised that we needed to have the compiled CSS version of theirs to handle that particular use case.

One of our back end engineers who didn't have a front end resource but needed to build this thing and wanted it to look good and wanted it to be on-brand but didn't have the capacity to do that and so, clearly we'd need a different way to consume this project so I got a lot, talking to a lot of the different engineers to see how they wanted to use this thing really helped me to iterate on the workflows and the way that I was presenting the project, I guess.

Mina Yeah! Strangely enough, talking to people is a good idea!

Mina I really am interested in seeing Design Systems on a larger scale, enterprise-level scale because building Pantsuit was an amazing experience but it was kind of a unique experience: it was building it, for one building it on my own which was a strange learning curve for me but also working with a large team of people to figure out how to best make this system work in various different situations that I couldn't even begin to think of.

Pantsuit was for hillaryclinton.com but it was still very much… most of it was still very much, it was a very content-driven… it wasn't a lot like web application stuff inside of Pantsuit, I guess is the best way to put it; it was very much like web pages, maybe a single page app but not a lot of really intense product like web app, so I wanted to be able to figure how to apply what I know about Design Systems and Pattern Libraries to an actual web application that doesn't just have a web app but also iOS apps and Android apps; I want to be able to figure out how to make… how this works in a larger cross-platform product which other people have figured this out, like Salesforce was a great example of figuring out how to do this, but being able to… I kind of want to figure out how I would like to approach something like that.

Mina OK!

Mina Well yep, hopefully!

Mina Bye!