Enterprise Design Systems Management

Assets, Processes, & Documentation

Ben Callahan

Ben Callahan

Enterprise Design Systems Management

Check out a free preview of the full Enterprise Design Systems Management course

The "Assets, Processes, & Documentation" Lesson is part of the full, Enterprise Design Systems Management course featured in this preview video. Here's what you'd learn in this lesson:

Ben further breaks down the layers of a design system into three parts: assets, processes, and documentation. Examples of assets, processes, and documentation for each layer are also provided in this segment.


Transcript from the "Assets, Processes, & Documentation" Lesson

>> So each of these layers are made up of three parts. I break that down just with assets, processes and documentation, so we'll take a quick look at each of those. So assets are the tangible things that make each layer very usable, so here's the kinds of things that I'm talking about.

Things like UX and design files, a repository somewhere in Git is an asset, right? Component files in that Git repository could be something that you consider an asset. Any image files or font files, anything that's taken up space somewhere, really. So a couple examples at the foundations layer, you might have a set of logos that are intended for use in your digital interface of some kind, right?

At the tokens layer, you may have taken that sorta abstract set of tokens and transformed that into a file that can be pulled into a web project. In this case, we're looking at some CSS primitive color tokens, so this is something that's an artifact, an asset of the the token build process.

At the core systems layer, you may be using some of those tokens to sorta offer, as a very simple example. But to offer a layout system, in this case it's just a little sass mix in that you could use to help with layout. So this is an example of kinda bringing design decisions together into a system of some kind.

And then of course at the components layer, just a simple example would be the button in Figma, right? So this is a very tangible, it's an asset a designer can use in a tool. So just remember, these are the really tangible things that a design system offers. And of course, there's more than assets, so let's talk a little bit about processes.

So the processes around your system are what define human behaviors as you work on and with the design system. These tend to fall into a few kinda big categories. Communication is a big one, because your design system is bringing together so many disciplines. We have to put some real process in place for how and when we communicate, we'll talk a little bit more about that a little later.

Governance and testing becomes a huge deal, because with this amazing offering that you're giving, comes a lot of risk too. If you've got a ton of folks using your system and you're giving them faulty code or stuff that doesn't work well, that comes with that risk, right? So we need to make sure we've got really good process to find around governance.

What's the quality level that we ascribe to for everything that we release, and how do we test that and validate that? This also includes how we might go around about prioritizing some work, defining roadmaps, that kinda thing. Contribution processes, is kinda where we get into setting your expectations for what it looks like for folks who are not on the design system team to contribute back to it in some way.

And if you want them to do that more than one time, you should probably be very clear with what that process is gonna be like for them [LAUGH]. As the system evolves, synchronization becomes something, we were talking earlier about, React and Angular and maybe view and all these different in this case, development frameworks.

Well, when you've got all of these different frameworks that you're supporting, what is the process look like for you to keep all of those assets in sync, right? This is a challenge, a real challenge, is hard to do that in an automated way. So we have to put some processes in place to make sure that we're at least being transparent about the state of each of those things.

And we also prioritize those synchronization tasks into our backlog. Deprecation as your system matures, you're gonna reach a point where you realize there's a better way to do a thing. And so you're probably gonna need to take something out of the system. That comes with a whole [LAUGH] other set of processes where you've gotta think about the communication and how you're working with the folks you're supporting as subscribers to remove something from their products.

And then of course release and versioning, are you choosing to do that at the system level or at the component level? There's lots of ways to do this. A lot of that just depends on the architecture of your products and what your subscribers specifically need. Extension and variation, it's guaranteed that your system is not gonna do everything perfectly for everybody [LAUGH].

So, what happens when those subscriber teams needed to do something that it doesn't do. Can they take us peace and extended, have you enabled that? What's the process around how that works? And then onboarding and I mean this in a couple different ways, of course you wanna work to onboard new subscribers to using the system that's a big part of the job.

But also as new employees join to jump onto product teams or feature teams, how do you as the design system team help support those folks becoming new employees? Cuz there's a lot of benefit to having them learn how the system works before they move into doing their product work.

So let's take a look at a few examples of these. At the foundations layer, you probably will wanna define a process at some point in health or in the life of the system. For how there's communication between the brand and the design system teams. If we know, the system has to be fed by things that are happening at the brand level.

Well, we need to know when things change, right? That has to be reflected in the system, so we need to establish those communication processes with that organization too. At the tokens layer, and we talked a little bit about the idea that, there's a lot of power with tokens.

But what happens when somebody needs to change the value of one of those colors or one of the padding that could have a ripple impact throughout your products? So there's a lot of power, there's a lot of risk, to alleviate the risk, we think through the process for when something like this changes.

At the core systems layer, deprecating an old core system. I mean, when I was doing web stuff back in the day, it was all float based, right? So, my layouts were all float left, clear, all kinds of stuff, right? So, these days, there's way much better options for doing layout, you've got all kinds of options on the web and CSS.

So, in that scenario, if I had built a layout system using floats, well, it's probably at this point way past time to deprecate that and offer them a better way to handle layout. But that process is removing something from a team that trusted you when they became a subscriber.

So you have to have a process in place to maintain that trust through changing the stuff they're using. This kinda thinking, shows that you're trustworthy or part of the organization. And then at the components layer, we talked briefly about contribution but one example might be. Hey, this thing you offered me didn't do everything I needed it to do.

So I extended it and I'd like, I think other teams could benefit from that. So, let's talk about how we get that integrated back into the system, of course, these are just a few examples, right? And you're probably, well, I can guarantee you, you're not gonna start with all of these processes defined.

It's totally okay, it's very natural for these things to kinda evolve as the system matures, and as you need them, right? Deprecation is not gonna be something you need in early stage of your design system. But as that becomes a need for you, it's worth it to go ahead and document, work with those teams to define the process.

All right, so that's processes, let's talk briefly about documentation. So documentation is really simply just an explanation of why something is the way it is. And it's usually a breakdown of how and when, and a lot of times when not to use a thing. Typically answers these kinds of questions.

So what is it that we believe about a thing, or what is it defining it? Or when should I use and not use a thing, who owns this? Give me some examples of a thing in use. And if you go look at documentation on websites, you'll see these specific questions being answered kinda all over the place.

So let's take a look at a few examples here. So at the foundations layer, we may want to document the digital product team's point of view on color. How is it that we think about color, how do we use colors together? How do we consider color in terms of accessibility?

Things like this, and if we look just briefly, this is a screenshot from IBM Carbon. And this is just their doc site, where they're talking a little bit about the anatomy of color in their interfaces. And so, you can see this is just an overview of how color anatomy works in Carbon.

At the tokens layer, we may have an explanation on how to name tokens. And that's just because naming [LAUGH] tokens is notoriously hard like anything, right? Naming stuff, it's always hard, especially challenging for tokens because we tend to sorta break these into multiple layers. And as an example again, from carbon, here's a screenshot from their Doc's site.

Where they're just showing the breakdown of token naming, why is it that we've chosen to name a thing in this way? What's cool about this is, it helps those subscribers to understand every single token, if you know this, every token makes sense, right? You can look at the name of the token and understand the intent, which is I think a really helpful thing.

So, they've taken the time to go ahead and document that here. At the core systems layer, we might have some documentation around how to use one of those core systems, in this case a theming system. So again, just from Carbon, an example where, they have taken their theming system and provided some really good documentation.

Around how you can actually implement that core system in the interface work that you're doing on a product. And then at the component layer, of course, let's break down the pieces and parts of a specific component. So again, from Carbon just as a great example, they've got a really nice section on the anatomy of a button that just gives names to every little piece, right?

It helps us to clarify the language we're using when we're talking about a specific component. Super helpful for those who are planning work around this kinda component or even just hoping to use it in their interface work. Of course, there's a lot of other things that will need to be documented, but it's helpful to see a few examples here.

Learn Straight from the Experts Who Shape the Modern Web

  • In-depth Courses
  • Industry Leading Experts
  • Learning Paths
  • Live Interactive Workshops
Get Unlimited Access Now