Style Guides with Jina Anne

Jina I'm great, thanks for having me back!

Jina Awesome, yeah, and I'm excited about talking about Lightning because I still can't believe how big it got.

Jina Yeah… let me go way back… so, I switched over to the core team at Salesforce because I saw the Salesforce1 Mobile Style Guide and this team that we have now kinda has evolved many, many times so when I started it was a cross-functional team of visual designers, interaction designers and front end developers and before we called ourselves the Design Systems Team it was called the Salesforce Cloud, because we have all these clouds; I guess now we have Commerce Cloud, Sales Cloud, Service Cloud, Marketing Cloud so Salesforce Cloud was kinda considered the core all-umbrella cloud.

But that was kind of a confusing name and so we re-branded our team to be the Systems Team and then after a while, Design Systems to be a little bit more obvious about what we do.

And so at the start, we had the Salesforce1 Style Guide but nobody was really using it. It was really beautiful and like I said, it attracted me to join the team, but it wasn't actually… devs weren't using the code and designers were kind of still doing their own thing and I think there were a lot of reasons for that but one of the things that we worked on, which is what I kinda consider the early genesis of the Lightning Design System were Design Tokens and so we had the Style Guide that nobody was using but we also had the beginnings of what Design Tokens were and that was fully embraced and adopted by our engineers and designers and so we were building that system out and it worked pretty well; people were definitely referencing the tokens in their Sketch files, developers were using tokens in their CSS and then at some point down the road, realised tokens are only going to get you so far and so the idea was, we were going to make a CSS framework and that framework initially was just going to be used by the UX Team for rapid prototyping and using that as a living spec.

Then we thought yeah, if this is pretty good, we can offer this to our Open Source developer community for people building apps to basically shoehorn into the Salesforce platform, they want it to look and feel like it belongs and then we thought maybe down the road, this will get used in production and our own engineers will use it! We were thinking this would be two or three years out and oh, it did not happen that way at all!

So I recruited my really good friend, Stephanie Rewis and then we recruited some more along the way. We were building this thing thinking we had a pretty good amount of time ahead of us and then it just all kind of happened really fast. Our engineers were basically copying and pasting our code because they realised the work had already been done by our team and it looked nicer than theirs!

And so when we realised that was already starting to happen, we had to basically shift our plan around and prioritise our production engineering team instead and so everything kind of got flipped around but it's awesome because it means we're shipping our product much faster and more efficiently, but it also kind of was like… oh crap, what did we just get ourselves into?

Jina Yeah, and oh man, the times that we've had to completely change things around. The first version of it wasn't prefaced with slds- and in all the classes and then we realised people were combining it with old CSS and there were clashes happening, so we had to go… luckily at this point I think we were still in Alpha phase so we could say, hey, sorry, you've got to change your syntax and then we were using the BEM syntax and there's all these things that you just find out along the way and you realise, oh, maybe we should have known that at the beginning, so we actually had to deprecate that syntax and introduce a new BEM syntax because it turns out, our production code uses XML and double-dashes cannot be commented. So, just all sorts of little fun, quirky things like that have come up along the way and it's been interesting and definitely educational.

Jina Yeah. I like to think of them as the sub-atomic part of the Design System but it's basically at its… I think one of the easiest ways to define it is it's like a variable; in fact, in most cases that is how it's used, it's a variable.

So in our case, we use Sass but when we give the CSS over to our Core Production Team, we actually use a different format: they don't use Sass, so we have basically Tokens for them and so basically the idea, Tokens, if you think about when you localise content, you might put all your content into strings that are tokenised and then you can replace those tokens with whatever language, so it's similar to that technology that our Engineering Team are already using for things like colours and font sizes but in our case, we're using them as Sass variables instead, so we built out this entire infrastructure of Tokens which is great because we also have to think about native devices, so this is a way that we can still scale our design without having a contact like the Mobile Android Team, the iOS Team, the Windows Team to make colour changes, we just do it on our end and it all rolls out in the build system to all those different teams.

And we also generate other things like colour swatches for designers. There's a lot of different ways that you can use Tokens but the most common use case is a variable…

Jina Yeah, exactly, and that was really important for us because we have a huge developer ecosystem where some of our customers are building on Java, some of them are on PHP, Node, all sorts of different formats and they might be using Sass, they might be using Less, they might be using XML for Android: there's all sorts of stuff people could be using and so this is a way we can scale our design to all sorts of different formats agnostically.

Jina I'm going to talk to it as well as I can; there's a lot of technical stuff that I have a lot of help from awesome people on my team but the primary format that we're concerned with for most of Salesforce is the Lightning platform and so that is what we hope that everyone moves over to but we seem to acquire companies all the time and so not everybody is using the Lightning platform so it's very important that we set something up that would work for people that are on Ember or React or whatever, so the way it's set up is… it used to be its own repo; now it actually lives inside the Design System repo but it's a set of files, either JSON or YAML.

We started with JSON and then we moved to YAML because we found it to be a lot more designer-friendly and at its simplest, it's name and value pairs but you can, depending on how you set it up, you can add in all sorts of other tags, like we can tag an additional comment to describe how it's used or we can flag a Token as deprecated. We can even define which CSS properties are allowed for that Token. So you can add in all sorts of other things to it that you can use for automation and tooling but at its simplest, it's name and value pairs. And then that repo is using Node and so we basically run a command and then it'll generate all the Tokens needed for Sass, Less, Stylus, XML, JSON, Lightning and so on. And then the build process automatically puts that set of Sass variables into our Design System CSS and so it's always going to grab the latest, so that's how we do it on our side of things and then we consume that in our CSS framework as Sass variables.

The way we deliver it to our engineers is we basically compile… we take the compiled CSS and we retain the Sass variables as is, except we change the format of them to match the Lightning format and that way, things are still tokenised but they're not getting all the mix-ins and functions and stuff that Sass has, so that's how they get it and Brandon and Stef on my team, they will basically put that directly into Core and work very closely with—

We have a sister-team on that side of things called the Styling Team and they make sure that we're not introducing any bugs. They run a whole bunch of tests on it and sometimes have to corral other devs to fix things if they've done things that over-ride or stomp on things and so on. So that's how they consume it and then when you use our Open Source CSS framework you can either use the Sass files or you can just used the compiled CSS and then we also offer a couple of other formats for other platforms, our older platform VisualForce and like I said, Lightning and then we also have those as packages, like NPM packages, Bower packages, so it kinda depends on… basically, you choose your own adventure!

Jina And sometimes people might even have to have different things in their compiled CSS depending on their platform so we'll try to automate all that as much as possible. For example, we can't really use Normalize as is on the VisualForce platform because they do a lot of things that it would actually conflict with, so we give them a very special format of the CSS to the VisualForce for that one.

Jina Yeah! They're really awesome. As far as I'm aware I think it's really two people doing… basically they don't do all the styling but they're sort of like the traffic directors in a way of styling. If you have a bug in your code, they're the ones usually that you're going to be talking to, to get that bug fixed and we're really good friends with them; they're awesome!

Jina Yeah, so that's actually, for the Lightning Platform, we're always just putting our stuff in there so if you're using the Lightning Platform, you're just getting those changes for free; you just have to make sure your component mark-up is correct. For all the other people, we use semver and we try to keep tabs on usually about three releases at once, usually it's the current release that's out right now, the next release and then whatever release was out prior because we don't want to leave people behind, so we're usually keeping aware of three really.

Sometimes there might be more than one in the future that we're thinking about, depending on whatever's coming and we have a deprecation strategy in place; we use Sass Deprecate which is our Open Source mixin that you can use; it's a little tool that Brandon created.

Jina Yeah, so it's a really cool idea Brandon came up with where you wrap your deprecated code in this mixin and you tell it through passing of a variable what version it deprecates in, or what version you want it to go away and then basically once you hit that version, it no longer compiles that code that's wrapped in the mixin so it won't be in your output and so… I'm trying to remember how long… I think it's almost two years minimum that we can deprecate things, so we can't remove something next version; it'll be in there for a while but that's because we have this huge promise to our customers that we won't break…

Jina Yeah. On our end we use the warn function in Sass, and I believe if you run it locally, yeah, if you run it locally in your command line it'll tell you, hey, you're using some deprecated stuff and it's in our release notes and then we mark in our docs when things are deprecated as well. But because this is still only maybe a year and a half or… we haven't reached a point yet where we've been able to remove anything but I imagine that that would be a ton of communication and support involved.

Jina We usually deprecate when it's a pattern that no longer meets our standards…

Jina It might be something that…

Jina We have never had a carousel, I am proud to say! People have asked for them, because they're like, well, Bootstrap has a carousel and we're like, we're not Bootstrap.

And so we only build things when we need them for our platforms so that's kinda nice because we're not building… oh, maybe someday probably one day I’ll need this: No. We're not going to build it until we need it. But I guess the biggest things I've seen happen is maybe a certain way a component is structured doesn't meet accessibility requirements so we have to kind of re-structure it, so then we would deprecate the old way, because some people might still be using some of its classes, unfortunately, and then another reason, like I said, we just had to deprecate our entire class BEM structure and so everything's comma separated now with two class names, the old one and the new one, which kinda sucks but we know it's going to go away one day.

Jina Yeah, for sure. So there's all sorts of different things. It might even be, here's a pattern we're introducing and then we realise it's not testing well or users aren't able to use it so we basically design a new pattern instead that works much better so we'll deprecate the old one and point our folks at the new one.

Jina Yeah, we do not have any JavaScript in our Open Source Design System and that is because once you introduce that, it is really difficult to stay agnostic; you basically introduce opinion into the stack. However, internally, and this actually might be Open Sourced as well; we do have a React version of our Design System that some of our smaller product teams use and then Lightning components come with all that baked in so if a developer at Salesforce is using a Lightning component, they don't have to worry about building that because somebody's already built that into the component.

In terms of how we tell people what the expectation is, we right now have been doing that through our docs; saying this class gets removed, this one gets added, add these attributes, remove this and so on: it's all through documentation. But I think we're looking again at possibly re-introducing that into the docs but can't confirm that's actually going to happen; it's being explored right now because it's hard to show… it's easier to show than it is to tell and it's been something that we've never loved about the Design System code-base. We want to be able to have JavaScript…

Jina There's a lot of business reasons around it too that I can't really talk much about!

Jina Right. We do surface on our docs when there is a Lightning component available because not everything has been ported over to a Lightning component yet and so it's nice for people internally to be like, oh, this is going to be easy because I can just use this little Lightning tag and I'm good to go!

Jina I want to be able to say… find out all of your different use cases first, but how do you ever really do that? If we had known that this was going to be used internally and externally on such a scale so quickly, obviously we would make all sorts of different changes but there's no way to ever predict that but I do think there is a model that we were entertaining at the beginning that we abandoned, that is now being talked about again that I wish we had just done it in the first place, which is the way I was calling it back then was skin and bones which I know sounds a little goth but idea of just having the structural bits of the CSS framework de-coupled from the presentational bits and the reason for that is I could foresee that we've gone through some re-designs; even Lightning itself has been re-designed a couple of times and I wanted to try to just have the structural, interactive and static bits, kind of self-contained and then the theme-ing and stuff through background colours and shadows and all that stuff just be a separate thing.

We abandoned it because it was, I guess at the time, a little bit too much abstraction for us to really think about to get this thing shipped but now there's a new look that's going to be out at some point soon and it's requiring some overhead work that if we had done this in the first place, would have been a lot easier and so now I was super-excited when I saw Nicole proposing this again… Nicole's my boss, Nicole Sullivan, she's rad! She's basically trying to champion this again and I'm like, yes, this is going to be good because we want to be able to very quickly do a complete new overhaul without having to re-structure a lot of stuff.

Jina Yeah. Tokens definitely get you a huge chunk of the way there but if you didn't initially have the Token for a shadow and now you need one, now you've gotta go touch the CSS, so that's kinda… yeah.

Jina Yeah, so we've kinda gone back and forth on things. I'm in favour of both being lean and only abstracting when you need to but also trying to think about other use cases such as customisation, theme-ing and all that stuff, so with our Tokens, when we first started architecting that, we had only done the two-tiered naming for colours and I had suggested we also do it for type sizes and our spacing and I did get pushed back because it was seen as over-abstraction. And then, oh, did we wish we had done that because when we first launched Lightning it was big and white spacey and whole aesthetic was about being very modern and fun but we actually ended up annoying some of our customers because they actually need to put as much content on their screen as possible and they didn't need so much space, so we had this huge effort that we called Lightning Tightening!

Jina And it turns out a lot of the engineers thought it was going to be, oh it's just a Token change, this'll be a piece of cake. No, because we probably just want to tighten some gutters and spacing between elements but not adjust spacing inside elements. Spacing Medium on a button, we don't want to touch, but spacing Medium between two cards, we might want to touch and so now this isn't just a simple Token change: we have to now touch some… sorry, is that a fire truck?

Jina …Like, we now have to touch the CSS and so we did have some annoyed devs that were like, hey, I thought the whole point of Tokens was that we basically put the design changes on the Design Team rather than on our team, and this was a huge overhead for them but then the response is, well, it's not that Design Tokens don't allow for that; we just didn't architect it enough to do that, so now we've got component-specific tokens in some cases, so that now if something like this happens again, such as the upcoming refresh of the visual design, we can now be strategic about where we apply spacing changes because we have the two-tiered system, so I'm a big proponent of using that and I see it all the time in the Design Systems Slack; I see it in other conversations where people are like, oh, it's just too much.

Jina I used to be anti-CSS pre-processors because I didn't think I needed them! Now I'm like the Sass fangirl, so…

Jina Yeah, we actually initially didn't have them because I was the nay-sayer: I didn't want them! And then when we realised people were combining our CSS with theirs or even combining it with other frameworks like Bootstrap, we had to introduce them and we definitely, between that plus the BEM syntax, we get people that say, oh, this is just way too verbose but our stance back to people is, clarity is of utmost importance to us and if you can look at a class and know exactly what it does, then that's always going to win over brevity.

Jina And it's great because we can now actually apply tooling around these classes: we have a Chrome extension that our devs use that can analyse a screen they're working on and be like, here's the CSS classes that are slds…

Jina Yeah, so it can detect, these are slds classes and if you are overriding any of those classes, it'll give you an F and you have to…

Jina …before you check in. Yeah, we were making all sorts of cool internal tools.

Jina Yeah, and then the Style Police!

Jina Well yeah; the Lightning Tightening I mentioned before was a huge, huge undertaking that would've been extremely painful without a Design System in the first place and other examples are, we had to change our navigation style and this is across many, many products and different stacks and we were able to do this very quickly and Execs noticed that because the request is coming from Execs in the first place and then they see how quickly this change rolls out, they definitely noticed that. So much so that… we do this thing called the V2MOM process every year where it's Vision, Values, Methods, Obstacles and Measures. Everybody writes one up for what they're trying to do through the year and it starts with the CEO and then the Execs and kind of rolls all the way down to the individual contributors and you align upwards to your manager or your organisation. The Lightning Design System's adoption is on every Exec's V2MOM at some point…

Jina …for this year so where last year it was all about getting Sales Cloud fully in the mix; now it's like, OK, everybody else. And the reason they did that was because they saw how quickly this one particular use case rolled out and they want to see that happen to everything: they want everything to roll out very quickly.

Jina Yeah, I can. I will say, I'm not super-thrilled with where things are right now, but I'll explain why in a minute.

As I mentioned before, when I started on the team it was a cross-functional team of designers and developers and I really think a good Design Systems team has that awesome mix of talent and skills, but we have grown a lot and a lot of new folks have come in; some folks have left and some things have changed, so now we actually… the team that works on the Lightning Design System is really kind of a virtual team that makes up people from other teams. We still have the Design Systems Team, which is the team I'm on, but the designers have been pulled off my team and put on a new team; we have one that's called Creative UX and they are in charge of basically the visual design and sound and animations and all the really beautiful and experiential parts of our products and then we have a Platform Foundation UX Team which is thinking about the Salesforce eco-system from a platform standpoint; they know how our different patterns and components are used and where and all the different use cases and so they now own that part of the Design System and then our team is focused on the CSS framework and documentation.

As a hybrid, I loved when our team kind of did a lot of that because I got to kind of jump around and do a bunch of different stuff but I understand why we changed it because we just got really big and I guess the thinking is with people focus on their different areas and then collaborating together, we work on the system together, it pulls some of the stress off of the one single team. But it kind of puts me in a funny position: OK, where do I belong?

Jina But I'm very excited to see where things are going, since Nicole's come in a lot of really good changes have been happening and I don't know if you noticed, but there's a re-design of the Lightning Design System that went out somewhat quietly last week!

Jina Yeah, and so lots of new stuff is coming down the pipe… yeah, and so…

Jina Yeah. I really like… I liked the prior model that I'd even wrote in response to an article from Nathan Curtis about team models where he had the centralised team but then you also have federated contributors from product teams and it's a cyclical pairing process where you all own and work on the design system together but that centralised team is really what helps keep the Design System maintained and living and we're slightly different now but we do still have a lot of collaboration and pairing happening so we didn't lose that, which is good.

Jina Yeah. Clarity is a Design Systems conference that I started last year. In fact, Brad spoke at it last year and it's at the Alamo Drafthouse in The Mission in San Francisco, so it's kind of fun and quirky. I like to mix it up because when I first announced it, I got some people that were like, really, a whole conference around Design Systems?

Jina But there's so many topics inside the umbrella of Design Systems that it's not boring at all; there were topics on accessibility, topics on animation, topics on content strategy; there's so many different things to cover.

So, doing it again this year, this time in November and I'm really excited about the line-up. A lot of faces that you might recognise, along with some people that I only just discovered this year like Amélie Lamont's talking and I just found out about her and I'm a big fan.

Jina Yeah, very excited to have her and Debbie Millman, who I still can't believe she said yes; that's so exciting that she's going to keynote.

Jina And then this time I'm doing some workshops too, so, Nathan is doing a Design Systems workshop and Val Head is doing one on prototyping with animations.

Jina I think it'll be really fun.

Jina Oh yeah, so… oh my God, that thing has really grown! designsystems.herokuapp.com is a little form that'll automatically send you an invite if you want to join. There's over 2,600 people in there.

Jina Yeah. I remember when it first started it was just maybe twelve or so people and then it just…

Jina It's cool!

Jina Yeah, I think I even used that in a talk once! Yeah, it's cool; I love that there's this huge passion around Design Systems.

Jina Awesome.