On Theme: Design Systems in Depth

Hand off the API: a design & build workflow for components, with Jeff Pelletier — #10

• Elyse Holladay • Season 1 • Episode 10

Share episode

📲 Text the show your thoughts!

Design systems aren’t just about components—they’re about how teams work together to build better UI. Jeff Pelletier, a frontend engineer with a design background, joins the show to talk about feature workflows for design systems, how design and engineering can work in parallel, and why documentation should be part of the process, not an afterthought. Jeff and Elyse dive into how to create API-first component specs, the challenge of design-code parity, and the ~drama~ of having a formal process.

💖 On Theme is a brand new podcast, so if you like what you're hearing, please hit subscribe and sign up at designsystemsontheme.com!

Links & References


🎨🎟️ Into Design Systems is May 25-28
Get your ticket at intodesignsystems.com/ontheme

Into Design Systems is back with their annual virtual conference, May 28-30, 2025. Get your ticket now for three days of practical, hands on sessions showing the what, why, and how of design systems. This year, the conference is focused on developer handoff, accessibility, multi brand theming, and governance. You'll get hands on knowledge you can put to use at work immediately, files and resources to take away, and hear from very well known industry speakers. 

Jeff Pelletier:

The benefit of aligning and having parity between your API in design and code is to assist in that handoff. It's to make it as clear as possible. And so when the designer is using the button in their design and they hand it off to the engineer who's building in product, and if those property values are named differently, that's where it can slow things down. And that's kind of the antithesis of design systems, like our goal is to do the opposite and help speed people up.

Elyse:

This is On Theme, Design Systems in Depth, and I'm Elyse Holladay. Together, we'll be exploring how successful design systems get built, maintained, and deliver impact. Design systems is due for a major reinvention moment, and I want to share what's working from design system practitioners out there forging the way. As you listen, text the show with your thoughts, aha moments, and questions by clicking the text link in the show notes. Before we begin, a quick thank you and word from our generous sponsor, Into Design Systems. Into Design Systems is back with their annual virtual conference, May 28 30, 2025. Visit intodesignsystems. com slash ontheme to get your ticket to three days of practical, hands on sessions showing the what, why, and how of design systems. This year, the conference is focused on developer handoff, accessibility, multi brand theming, and governance. You'll get hands on knowledge you can put to use at work immediately, files and resources to take away, and hear from very well known industry speakers. Get your ticket at intodesignsystems. com slash on theme, and I'll see you at the conference in May. All right, let's dive into the show. Today's guest is Jeff Pelletier. He's a hybrid frontend developer who's been focusing on design systems for the past five plus years, at places like Apiture and Bill.com. He's been really active in the design system community lately, attending Knapsack's design system leadership summits, which I also just went to one really, really great event, doing some mentoring of designers which I think is really cool for an engineer. And he's been particularly focused on design system operations. Jeff, thanks for coming on the podcast.

Jeff Pelletier:

Yeah. Thanks for having me, Elyse. Really excited to be here.

Elyse:

I'm excited too. I'm really excited to have you on because, as strange as this may sound, I think engineers are not often featured in design system conversations. Maybe it's just because we have the word design in the phrase"design systems", but I think you can't do design systems without engineering and I think it has to be a partnership. So I'm just really excited to hear some eng focus on the show.

Jeff Pelletier:

Yeah. And I have always, in some sense felt a engineer kind of masquerading, you know, I have a degree in graphic design. And so I came to on the frontend just through an interest in the web. The first website that I ever built was for my band when I was in high school. I just ended up being the guy that was the most likely to understand code, even though I have a design brain. And it's kind of all gone uphill from, from there. So.

Elyse:

Uh, yeah, it, it, me.

Jeff Pelletier:

I've been working on the frontend for almost 20 years now. And I really have my roots in, uh, in graphic design.

Elyse:

Yeah. And I think this is such a special role and a special place to sit in the making of software, right? Like, I said it me, but it really is, like, I started playing around with websites in high school. Like I have a design degree, but I ended up working in coding on the web because those were the jobs that were available, and I could do it. My first couple of years of my career, I was like, I'm a professional CSS person. That was literally what I did. People would hire me to just write CSS and CSS architecture— was a beautiful time. I think that this front of the frontend or design system engineer is such an interesting place because it really is where the rubber meets the road. You have to do the backend. Yes. You have to do the database, but this is what the user actually interacts with. It's what they're seeing. It's what they're using. It's their experience. I think it's a really special role.

Jeff Pelletier:

We have similar origin stories and that's really what attracted me to design systems. I've heard Nathan Curtis say that design systems are a home for hybrids. I wrote a blog post years ago, called frontend roles and responsibilities, because, yes, there is still a role for people who sit in between design and engineering. There are clearly a lot of people in this same position and there are clearly a lot of responsibilities that have, that had been, overlooked in that in between space between design and engineering.

Elyse:

No, we love to sit in the in between. Can you explain to some of our listeners who are not familiar, the difference, and I know that this is a very fuzzy area, but like the difference between backend, frontend, sometimes you'll hear, you know, people say front of the frontend, and then we have this idea of a designer who can code. Can you kind of like walk us through that spectrum of the different, layers of engineering, I guess?

Jeff Pelletier:

Sure. Yeah. You know, there's a whole bunch of different flavors of design, right? Like interaction, design, experience, design, product design. You have people on frontend, who are like the front of the front like me, can focus on anything from responsive web design, modular and scalable CSS, UI frameworks, accessibility, frontend performance is another common one, animation, all of that is kind of the bread and butter for people who I think are more on the front of the front. And then there's backend. Sometimes you hear it referred to as full stack. I generally find that when you have people describing themselves as full stack, it's more backend, and they can jump in and do some frontend work. But I don't know, in my experience, that ends up just being infinite div soup.

Elyse:

No, you're totally right. And you're actually the second person on the podcast who said that exact same thing. Full stack has kind of become a more backend focus, right? If you think about the frontend as React, you're writing React and you're touching the database in the backend. But there's this space of like, okay, React is the frontend. I'm in React, but maybe it's, you know, it's CSS or it's JSX or like whatever it is, right? But it's a much more design layer. And I just think this is so funny because now that's moved into like, oh, that's not real, that's like design. But when I, we were talking about our origin stories, like when I first started writing websites, it was like doing like GeoCities websites and people were like, Oh my God, you can code! And it was like writing tables and CSS. And like, look, you're not going to hear me say that CSS is not a real programming language, because it totally is. But people thought about that as code. CSS architecture was a big deal. And then it was like, oh, we don't need that our full stack developers can do it. I think we're coming around full circle because I think we're starting to see that, when you. I love all my engineering partners, but when you have your full stack engineers do all of your UI, you don't get the level of focus and polish. Part of that is skill. And I don't mean that they're incapable. I mean that they have no incentive or interest they haven't learned it yet, or, a lot of the engineers that I've worked with, they don't want to be doing that stuff. I think it takes a different kind of person. An engineer with a design degree, maybe.

Jeff Pelletier:

Yeah, no, one of the words that you just used is spot on. It's the incentive, right? It comes from the organization. And on top of that, if it's a public organization, the investors, and on top of that, it's like, capitalist society. And so,

Elyse:

That's a different podcast.

Jeff Pelletier:

Very true. But if the incentive is to, you know, ship something, using complex JavaScript framework to meet, product demands, which are driven by shareholder desires, that's a very different output. And what ends up being sacrificed is things like accessibility or, maybe performance. Those are things that if you're promising to deliver quality experiences, you need to have a diverse team that is skilled in all of these various areas or else, yes, it will get live, and yes, you can iterate on it, but if the team isn't diverse enough to create a really quality experience, it doesn't matter how many times you iterate on it.

Elyse:

And then it's just tech debt. And then you're like, oh, we can't do that. And I think a lot of times this gets shoehorned into this idea of polish, like, oh, we'll go back and put like a layer of polish on it. Like, what is this? Like wood varnish? Like you, if you have div soup at the beginning, it can be very, very challenging. We talk about this, especially with responsive design. If your designers are not delivering mockups or wireframes that take into consideration what happens in a responsive way. And they only give you desktop designs. It can be quite hard to turn that into something that makes sense responsively. How do you talk about the value of this stuff in a way that's not just polish, right? When you say polish, it sounds like a thing you can put on top, but a lot of this is fundamental to building a really good UI. How do you talk about that to your teams?

Jeff Pelletier:

You reminded me of something that Aaron Walter, this is from a book that he wrote a very long time ago, but he talked about, when he was on the MailChimp team, and they had a team that he described as guns forward, guns back. And all they were there to do was to sand the edges of all the work that everybody else was doing. And so

that was a form of polishing the work. The way I've heard it talked about more

Jeff Pelletier:

recently is as infrastructure. So, years ago I heard Mina Markham, explain design systems with this really great Venn diagram. She gave an example I think of like a transit system

and all the different pieces—

Jeff Pelletier:

what the schedule is, how do I pay for stuff? There's a lot of other stuff besides just the end goal, which is getting person from point A to point B. Then she contrasted that with design systems. And how the focus is on components, and really there's this whole other world. It's really more about all the connections between not just the tangible output, but how do all the teams work together and communicate? And that's when we start to get into, what is the culture at your organization? And who thought getting into design systems would require you to be a teacher, right?

Elyse:

Yeah, a teacher, a content creator, a seller, like it's all these other skills because you're totally right. It's the process by which we make UI. But one of the things that we wanted to talk about today, I really want to get into the meat of this, cause I think it relates to this idea of polish and of, putting quality, I'm going to air quotes, quality, whatever that means, into the system and into the process. And that is this idea of a feature workflow for design systems. I'm really curious to hear about this because I've read Nathan Curtis's article, but this is not something that I've formally implemented anywhere. You've worked at design systems at relatively large organizations. Tell us a little bit about the places that you've been, their size, what the design system team was like there.

Jeff Pelletier:

Yeah, so the company that I'm currently with, Apiture is only around 250, total. So smaller when I contrast it with my time at Bill, which was, I went through three acquisitions while I was there. Bill acquired three different companies. And the team scaled from, I think when I started there were maybe 10 designers, and it was up to like 35 or something by the time that I left, and I want to say somewhere around 600 engineers.

Elyse:

Big enough.

Jeff Pelletier:

Much more, large scale. Yeah, for sure.

Elyse:

So yeah. First just give us the overview of what is a feature workflow?

Jeff Pelletier:

Yeah so if you've read Nathan's articles,

the definition that he gives is that a feature workflow is

Jeff Pelletier:

a set of steps and substeps, mutually agreed on by the core design systems team, that can be leveraged internally and for contributions. It's really something that can be used for, not just components, components is again the focus here, but he described it as a feature workflow instead of a component workflow because design systems are more than just components. So you could use a feature workflow for things like design language, design tokens, larger things like patterns or, more recently, they're being referred to as recipes by Brad Frost, or other contributions like content, for example.

Elyse:

So take us through the steps.

Jeff Pelletier:

Sure. So the five most common are Discovery, Design, Build, Documentation, and then, some type of Publish or Release step. I've seen plenty of variations or permutations on that, but those are the five main categories. I think one of the important things to highlight is that the steps don't necessarily have to start sequentially, like waterfall. You could start thinking about design, or even build, like how to even just set up the scaffolding for this thing, before even the discovery is done. But generally they will finish in sequence.

Elyse:

Yeah, and I think that's a really important note, because when you write out any kind of process and you formalize any kind of process, you're like, okay, first we do discovery, then we do design, then we build. In reality, we've been talking about this in between space between design and engineering, and especially for design system teams, whose whole mandate is to be between design and engineering, you cannot separate those steps in such a formal waterfall, one goes in front of the other, way. Design and build should be happening fairly simultaneously. If you're working on something, and just making a picture of it in Figma or whatever, and you don't know how it's going to function. And then you get over into engineering and they're like, oh yeah, that's not going to work like this, we can't do the hover state, and we can't do this, then you've wasted a bunch of time. It's hard to write that down as like, and then you do these two steps simultaneously. But I think that part is, is particularly important to call out.

Jeff Pelletier:

Yes. Dan Mall talks about it as the hot potato process where the designer and the engineer are just kind of passing things back and forth very rapidly. I found that it is incredibly valuable to have engineers in the room as early as discovery, because if you're going through that process and evaluating things, really, the end goal of discovery is, scoping the feature. So what is this thing? What is in, what is out? And Engineers can be really helpful as part of that conversation, and part of that decision making, because there are things that, perhaps, won't work. And if you're scoping what is actually in from a feature perspective, that is part of that conversation.

Elyse:

Yeah, totally. So, let's start at the beginning. What goes into discovery?

Jeff Pelletier:

Yeah. At Apiture our designer Jim, has stamped out a huge list of things that he does. And he actually works in just a discovery Figma file. So he has a completely separate environment for all of the component discovery that he's done. He goes out and talks to engineers and designers. Some of the things he's included are interviews, reaching out to teams, collecting component specific feedback, inventory, so auditing our products, you know, collecting component examples in production, identifying needs. So looking at what are all the different variants of all these things and how's that going to influence the properties, understanding the UX. So analyzing it from a larger like UX perspective. And then, even researching public design systems. There's a naming discussion, and then work in his Figma file to kind of consolidate all of this, share it out with the team. And we, we have, review cycles for all of that as well. The goal is to get to the end and have what the scope is, but part of that process is internal review by the system team and review by design. And so once we get something that we include at the core system level, we have approval because we've had eyes on it by the internal core team, as well as, the design community and, approval from design leadership. And then also that is the point where you formalize and create the tickets for the next few steps.

Elyse:

So the goal of discovery is it sounds like kind of twofold. One is yes, we are, or are not going to actually do this work and B, what is actually the scope of the work?

Jeff Pelletier:

Yeah. That's accurate. And there's a little bit of crossover. I just did some more work around governance model and how that it pairs with something like a feature workflow. And it's really interesting because governance models are really just a series of questions that you're asking to determine, should this thing live at the core level or should it live at a a product layer or some tier that's kind of higher than that? And so, there is overlap between that and the decision, of whether this thing is included at the core level as part of discovery.

Elyse:

Okay. So let's say we are like, yes, we're going to do it. We have some sense of scope.—and I want to come back to scope because it always changes once you actually get into later steps—but you have some sense of scope. You're like, okay, yes, this is a thing that we're going to actually build, whether it's a component or a pattern or whatever. Next we move into design slash design and build kind of simultaneously. So what is happening at those steps?

Jeff Pelletier:

Yeah. So, Design is working in a separate Figma file in our case. And so it's all of the design work. At Apiture for a lot of the more atomic things that we've been working on, it's not necessarily creating something from scratch, it's going in, and updating the thing that is already there. But you need to check accessibility, so we have accessibility tools that we use in Figma to make sure that we're considering accessibility on the design side. We also have responsive web considerations that we try to look at in design as well. We make sure that we're applying design to tokens. And then we also have an API discussion. In Figma, there are ways that you can map things to the API in code, in some cases, there are exceptions to that. And so it just helps to have a conversation and say, what are those exceptions?

Elyse:

Yeah. I mean, I think we're, we're always striving for design code parity right? Like we want the pictures that we make to match the stuff that we develop. And I think Figma has done an incredible job moving in that direction. But at the end of the day, it's not the web. And I mean, this, there are so many cans of worms here. I'm like, should designers code? Should we make mockups and pictures? Should we just be prototyping? Like we could get into some really, really, really challenging discussions! But at what level do you need to match, in terms of design output, versus code output? And properties, or your API, I think is one where I'm trying to match in the core ways, right? Like if there are color variants, or if there's a disabled state, or if there's a big and a small size, those need to exist in the design, and the design language and the design component, and they need to exist in code. Because, I'm curious if you agree with me, I think that's one of the biggest places where if designers are sending stuff over to engineers, that has a version in design that isn't equivalent in code, engineers are often just going to build it.

Jeff Pelletier:

Yes, I think that's true, and the benefit of aligning and having parity between your API in design and code is to assist in that handoff. It's to make it as clear as possible for the engineer, because when the engineer is building this thing, they've got a million other concerns. And so when the designer is using the button in their design and they hand it off to the engineer who's building in product, and if those property values are named differently, that's where it can slow things down. And that's kind of the antithesis of design systems. Like our goal is to do the opposite and help speed people up.

Elyse:

Where I really get into it is this idea of flow state. You touched on this when you said, an engineer has a million other things that they're thinking about. We all do, but it's like, yeah, okay, I'm thinking about how does this connect to the data, I'm thinking about performance, I've been thinking about how I'm integrating with our other APIs, like whatever it is. You get in this flow state where you're like I'm, I'm putting these things in, I'm connecting this bit, I'm connecting that bit, I'm loading the data, and I'm showing it like I'm doing the state, when you click a button, this thing happens, and then you're like, okay, great, I need to pull in this button. And then you're looking at the mockup and you're like, what is that button? And now I have to go, I got to stop, look at the docs, look in the Figma, go in and inspect, go dig in Confluence somewhere. And I'm not saying that that is unreasonable. It's just, it breaks your flow, in a way that I think, a lot of times what happens is they're like, instead of getting out of the flow state, like I'll, I'll just stick something in, I'll come back to this And I, I really emphasize that because it's not about, your developers are lazy. Your developers don't care about design. Your developers don't want to make it nice. They don't give a fuck. Like it's not a, it's not that. It's, I'm in the middle of balancing like all these concerns, as I try to implement this thing and make it work, I will come back, and I'm not going to like pause all of that flow state and go like, look up this other thing and and then it gets, it gets dropped at the end, unfortunately, a lot of times.

Jeff Pelletier:

Yeah. I've heard some of the numbers that are thrown around is like, it takes you 20 minutes to recontextualize when somebody comes and knocks on your door, and, you know, pulls your focus away. And even having the presence of a cell phone on your desk can be a distraction. They've done studies on people who are working without a cell phone on their desk, not even looking at it or using it, and then people who aren't and the people who, who don't have that phone on the desk are performing better because they're able to focus more. And so yeah, it affects us as humans more than I think we realize. And so, any time that you're introducing that to, somebody who's consuming your work from the design systems workflow, we have to understand that it really does distract.

Elyse:

It really can. And I, I can't tell you how many times I've been coding something and I'm like, okay, I'm going to work on this I'm in the middle of like, hover state or focus state, or especially something that's like a little bit challenging to test where you have to take an action to get to a state or like re- go through a process to like get back to this finicky thing that you were testing, dropdowns, menus, stuff like that. And I'm like, okay, I'm going to do this border and I'm going to do this and I'm going to do that, and then I notice something else, as I'm going. And I'm like, oh, I'm just going to go over here and like fix this background color or fix that padding. And already I have forgotten. And I'm in code review and I'm like, oh man, like I forgot to go back and fix the menu thing that I was working on. Because it's that easy. I mean, I'm sure this is true for designers too, but for, for engineers, and especially on the frontend, all these little states, again, like menus, overlays, focus and hover states, accessibility, like all of this stuff can be very, very detailed. So detailed that when you get pulled out of it, to go look up kind of other information, like in the docs, like a lot of times you forget. And I think that's just very normal. So the easier we can make it, the more likely we are to get that quote unquote polish.

Jeff Pelletier:

Very true. Yeah. I have experienced the most, I call it being in the zone, when I was working 100 percent in CSS. And I'm like, man, I can just get into, where I lose like two or three hours, you know, like I just put on some good music and, you can be so productive.

Elyse:

think because you're in one modality, right? You're not jumping between frontend, backend, design, Figma, like, I think that's a real challenge. But okay, we've gotten way into talking about, uh, consumer developer needs, which that is a soapbox that I love. But let's go back to our process. We're kind of in, in that design and build process. So we talked a little bit about design, we're working on our component, or working on our edit to our component, our pattern or whatever. Tell me a little bit about, how you sync, not sync up the design and build process in terms of like literal timing, but how does that collaboration start to flow back and forth between design and build, between design and engineering? What's the ideal setup there, rather than just like, I made a design in Figma here, engineer, now you build it.

Jeff Pelletier:

During my time at Bill, we created these component specs that were just Google docs, they were API first.

Elyse:

Oh, cool.

Jeff Pelletier:

Let's just stamp out a table of this is the API for the component in Figma, this is what we have in code. It's collaborative. Engineers are less likely to go into Figma and try to figure out how things work over there, but Google Docs, everybody can kind of understand. And so in addition to API, we had anything else that is not easy to communicate with Figma. So, stuff like behavior, state, responsive, accessibility, sometimes. That was really fun. I and a, another design technologist kind of worked on over 30 Google docs for component handoff and really started to see some participation from engineers.

Elyse:

I feel like this is like the design system version of like test driven development. It's like, we're going to write out all the requirements first. We're going to write out all the properties. We're going to write out all the variants. We're going to write out all the states. It's a lot easier to build once you have all of that. It's not set in stone, right? Like if you're in the middle of building or designing it, and you discover some other things that you hadn't considered, like, fine, you go back and update it. But how many, how many times have you been designing something or building something? And you're like, oh shit, like, I entirely didn't think about this whole state.

Jeff Pelletier:

You certainly learn during the process. And that's what's great about Google docs is that if you change something, one, you have a history, but also you have comment threads. And so it's really easy for engineers to come in and go, I was able to accomplish 75 percent of what we had planned from an API perspective, but I had to change a few things. Here's what I did differently. And you have a record of that in the history. So I found that really helpful. At one point we did a full API reconciliation project, where I had a massive spreadsheet with all the properties of every component. It was really, really helpful to be able to go back in the history and Google Docs and see when properties changed or what the conversation was. After we had got through a whole bunch of those manual Google docs, that's right around the time when Eight Shapes published their component specs plugin. And I was like, oh man, this is like a lifesaver. Like you can literally just point it at a component and have it generate a whole bunch of specs, which are exactly the same thing. They're intended for handoff. So if I were doing that again today, I would probably do a combination of kind of like the component specs in Figma that are all just automatically generated by the plugin with maybe a little bit of manual API Google doc or something.

Elyse:

We've, we've been saying handoff. Can you talk a little bit about how you see the difference between like internal team handoff? Versus what is handoff like on a, on a product team? Like, I think there's different levels of detail there. What are you kind of like including or not including?

Jeff Pelletier:

And yeah this

Elyse:

is

Jeff Pelletier:

stuff that I am really just getting into. I mentioned the governance model previously. It's something that I put together just over the last month or so. Right up front I say, don't be afraid, this may look like a massive flowchart, but it's really just a conversation. So product team and design system team have a conversation, better understand what is this request? What is this thing, that may be a potential contribution to the design system? And then you have this question tree of like, does it already exist, does it meet requirements? Can it be edited to meet requirements? The answer to each of those will determine whether you just continue as you were, or proceeding to different size contributions, or a completely new feature. So we have them sized as a small enhancement, a large enhancement, and a completely new feature. There's those three, but then there's also this kind of sub part of the tree, which is, is it a visual or API discrepancy or is it a bug? And we have kind of like flows for each of those. Visual discrepancy is interesting because it starts to get into questions like, was the discrepancy deliberate? Did the designer do it on purpose? Or is, you know, one is it a difference between our stuff internally as a core system team, between design and code, or is it just new design, and the designer felt very strongly about the decisions that were made.

Elyse:

I just want to pause on that real quick because, I can't tell you how many times I've seen people say, I found a bug in the design system. When what they mean is, this looks different, or this is not what I expected. When I come to design systems groups, a lot of times it's all designers, and I'm like, am I the only engineer in the room? What does an engineer mean when they say that's a bug?

Jeff Pelletier:

Well, there are a lot of different types of bugs, but generally engineers will mean they saw something on the console or something's not behaving the way that they expected. I think those are really the two big categories that engineers are, are probably talking about. For me, having a design eye, I'm looking at a component and I'm going, all right, there's something visual going on here that's not right.

Elyse:

Which we can call a bug from the, from the API or the spec, right? It was like, oh, this was supposed to be blue, but it's purple. A lot of times when I hear people say, I found a bug in the design system, they are meaning like, my designer put an icon in this button, and when I tried to use the design system button, it doesn't have an icon. And I'm like, my dude, that is not a bug.

Jeff Pelletier:

Yeah. The, the result of that in our governance model is like, that is a clear, deliberate, discrepancy. You know, designer made a decision to add an icon in there. The outcome of that is either, the product team either updates to better adhere to the design from the system, so don't use the icon in the button. Or, it's intentional and the product team is going to move forward implementing like this custom design. So neither of those end up in the core design system, right?

Elyse:

I think this, button icon example is a really good example, because you'll hear designers say like, oh, the engineers, they don't care about polish or they don't care about design quality, or like they're making all these like inconsistent things. And it's like, they care, they're trying to do the best job and they're looking at these mockups, and they don't necessarily know, is that intentional? Is it not intentional? Should I be following the system? Should I be doing this as a one off? Engineers have a lot of respect for designers. And they're like, I respect my designer and their choices, and so if I'm seeing this icon in here, like I'm assuming that the designer has done this for legitimate reasons. And so, I've been training our engineers, and our designers internally, to be like, if the designer didn't annotate, specifically, that it was supposed to be different, and like, the thing that you're getting out of code doesn't have it, like, go with the one in code. That's not going to work for every team, but we've been kind of approaching it in that way, trust the system. And then from design, we're going to really like describe here's what was intended to be different or what was not intended to be different.

Jeff Pelletier:

Some of the final questions of our current model are like really determining does it belong it in the design system or at that core layer. So what is the shared need? Are there more than three product teams that are going to use this thing? If they come to you and they say, I just designed this thing, I don't know if anybody else is going to use it, and I need it like next week, that's a pretty good, indicator that this is just going to be business as usual, and continue doing your own thing. If they say I've already identified five different teams and I also have a designer or an engineer who can help with the contribution, that's a very different conversation.

Elyse:

Yeah, and that's really getting into the pace layers concept. If you already have this thing implemented in five parts of the product, and you want to graduate it into the system, you have time to look at the APIs of all of those things, look at the design of all of those things, think about how it's going to work, think about how you can get the teams to actually like go back and refactor it, and kind of like bring some consistency to the places in those five different implementations that are inconsistent.

Jeff Pelletier:

I think another job requirement for design systems folks is like organizing chaos, right? Like the, part of the job is—

Elyse:

cat herding

Jeff Pelletier:

know, everything, there, there's chaos all around us. And if we can incrementally introduce some structure to that, or some organization to that, it's going to be beneficial for, for everybody. I'm just really getting started on the governance model stuff, but the feature workflow is something that I have implemented before and seen tremendous success with.

Elyse:

Yes. I think that kind of brings us to this last couple of steps in the process, which is really around documentation and publishing. But when, when you're designer and engineer working together, you've got something kind of going, you've got a draft in Figma, you've got a draft in code, you're starting to like bring them closer together. How are you thinking about documentation, as a requirement for actually shipping the thing, rather than something that you just like maybe do later, and how are you thinking about documentation as a way to help the product designers and engineers do their handoff.

Jeff Pelletier:

Yeah. So, documentation is a challenge from a priority perspective at every organization that I've been with. At Apiture, we're using ZeroHeight and we, we have separate tickets to track design documentation, and then tech doc documentation. And so on the design side, we're including everything like, usage, do, don't do, all the standard stuff that you would want to find in a design tab for a component. And then on the code side, we have the Storybook embed, so the whole API of the component. And then not just the Storybook embed, but also anything that's relevant, that as a developer who's working on it, when you're in that context, take a few notes and ensure that anybody who's trying to pick this thing up and use it has some of that context that we try to add a little bit around there. But yeah, I mean the struggle is, is always there. It's different depending on the size of the organization. I mean, larger organization, you just have more chefs in the kitchen. So you have, I think engineering generally is wanting to use like Storybook docs for example. And then design will say, Oh, we're going to have a whole separate platform, the most popular I've seen has been ZeroHeight, there are tools like Knapsack that try to bridge that and, and kind of do both. So that's more of a cultural level thing where you have to kind of level set with everybody and say, we really want to have one location for everybody to start with. And then, once you've ironed that out, then it's like yes documentation is its own step, and yes we are going to have separate tasks because the people authoring this stuff are most likely different people, right? The designer is not going to be authoring our tech docs, and the engineer is not going to be authoring the design docs. Making that clear and reflecting that as part of your feature workflow, as well as in your JIRA backlog, as part of your your ticket structure, I've found to be really successful. I mean, I had, we had retros at Bill where I had engineers and designers, really, saying like, the Jira ticketing seems much more clear, we're getting into a much better cadence with the component work, the process is getting more solid, like tracking tasks is, is better. It's not just with the documentation tickets, but when people start to feel like, oh yeah, I have a lot better sense of, not only what I'm working on, but I can see, I'm the engineer working on this build ticket, but I can see the design ticket is assigned to, this designer, it's also in this sprint and we're kind of working in tandem. And I think that helps everybody start to wrap their head around. documentation is actually as important as a build ticket or a design ticket for each of these components. So, yeah it's really, it's, it's the conversations as part of the culture, but then also kind of building it into the tracking system so that you can kind of weigh it in a way that everybody understands.

Elyse:

Yeah, it doesn't get forgotten. One of the things that I think is really valuable about this is if you're doing some of this like discovery and spec, especially if you're doing API documentation first, like you actually taking the time to write out the props and the variants and the interactions and the states. You have like 80 percent of your documentation already, right?

Jeff Pelletier:

Yeah, you do have, you have quite a bit. The handoff docs are focused around what are the what, what's the spec and what's the requirements. A lot of that can be sourced for, your documentation site or reference site.

Elyse:

I think the, the thing where we get it really twisted with design system, documentation is where like a button is an element that a user can click to do an action. It's like, yeah, like, like of course I don't wanna write, I don't wanna be writing that. Like I don't wanna take the time to write that, like we already know. But if you can pull that API documentation that you've already been writing when you're writing the spec, and be like, like that's what people wanna know. They wanna know, like, in the mockup that I have, it does have an icon, or it's got a dropdown menu, like, is that an option? Is that a property? Is that a thing that I can add? Can I combine these two components, a button with an icon that also makes a menu, like how do I put those things together? And I think that's the kind of documentation that is the most valuable, that is also the hardest to write.

Jeff Pelletier:

That requires the, the UX understanding and the ability to, to write and craft great content in a way that is accessible and understandable by the widest audience audience. And that's a particular skill set? One of the other areas that you just reminded me of, that we're just getting into at Apiture, is this concept of recipes. Which is not necessarily coded components, but, they do exist in code, they are examples of putting together some of the smaller things that already exist at the core system layer. And we have multiple varieties of the way products will adopt this stuff. So in some cases we're stitching together an entire form as a recipe, and we had to write very light CSS to space things out or something. In other products they're using like Tailwind, and so we, we've been looking at potentially, we could at least just show them, here's how you would apply our design tokens to a Tailwind config and then use the class, the CSS utility classes that are generated to, leverage fundamental pieces of the system, even if you're not really going to be able to use any of our components. Cause we do have, I don't want to get into the whole tech stack and everything, but we do have products that are not necessarily going to be able to use some of the components.

That recipe

Jeff Pelletier:

playground is an area to try to figure out how to help and assist those teams as much as possible.

Elyse:

This is a theme that's definitely coming out on the season of the podcast. We're talking about like, those people are consumers of your design system, also, like, even if they're not using the code components even if they're just using your styles or your design patterns or your tokens or your documentation. And I think that those recipes are really undervalued in the way that a design system can affect how an engineering team actually builds and ships UI, because when you are, when you're in your code base, you're an engineer, you're working, you're looking at a mock up and you're like, okay, like I got a form to build. The first thing you do, like 98 percent of the time, the first thing you do, is you go look for a different form that you're familiar with, in another part of the product. That's kind of similar. And you copy the pattern, you copy the code pattern, and by doing so, you also copy the design pattern. And if you can seed into your product, these recipes, these patterns, like, this is how we do form validation. This is how we put together the stacking, the margins, like spacing between elements. You are actually literally seeding that all across your engineering org, because that's where people are looking to replicate those things from, rather than putting those things together from scratch. And I think that that is deeply undervalued and like changing the way that we work.

Jeff Pelletier:

If you're looking at it through the lens of a design system, you're, you're taking the considerations of every product at the organization that could possibly use this thing. And that is a much better starting point than, I'm just going to go find a similar form in the product that I am in, right? Yes, that's probably a good starting point, but has it really been vetted from the system perspective? Dan Mall gives the example of the Audi design system, where they right up front, they have, here's our, our stuff. Here's how our system stuff appears on like an Apple watch and on an iPhone and an iPad and like huge desktops. They do it in every single component, like here's the patterns or recipes right up front. If you want to dig deeper on how all the things that we leverage from the system to build that thing, like you can scroll down the page, right? But like that, that's flipping, I think, the way that a lot of doc sites think about documenting things. Like generally you see foundations, and then components, and then patterns, and it kind of progresses from small to large. And this is kind of just completely flipping that.

Elyse:

I love that.

Jeff Pelletier:

How can we do things in a way that is going to best demonstrate how people could use our stuff to actually build the things that they're trying to build?

Elyse:

Yeah, so speaking of people using the things that we've made to build the things are going to build, our last step in this process and a feature workflow is publishing, right? Like, this is actually like getting it out to people. What goes into publishing formally?

Jeff Pelletier:

For us at Apiture, it's really trying to ensure that we are syncing as much as possible. So when we are publishing the component in Figma, we are publishing a version of the package in code. And we're going to update the documentation. Just making sure we are, publishing things in as synchronized form as possible. And then we have a component status table in ZeroHeight, so we make sure that things are updated there in that table, and then, that same status indicator appears on the component page itself. And so it's like, have we switched that from like, design ready, to fully ready, across design, build, and docs. We're a very small team here. So it's just ensuring that we check those boxes try to reduce the number of questions, of people coming to us and going, hey, I found this thing in the most recently published version in Figma, but like, where the heck is it in, in the docs or where the heck is it in, in code? Right.

Elyse:

Oh, no, you can't use that yet. Yeah. What kind of communication are y'all doing about or after the publishing process?

Jeff Pelletier:

One of the things I actually did just set up over the last month was a support channel in Slack. And so we have a general design system channel, but then we also have a brand new support channel. So publish releases in one or both of those Slack channels. I find the in person conversations are the most effective. And this is another thing that Dan Mall says. Setting up something like a learning environment for the entire organization, and then encouraging people across the organization to come. I think this for us traditionally had been much more engineering focused. And so this is really the start of kind of branching out and going, yeah, like maybe the entire organization should be part of this, like, it's not just for engineering audiences.

Elyse:

It really is. I mean, this whole process, right? We've been talking about going from idea to design to code to shipping and we were talking about as a linear process, but it is also a loop. Because the output of the thing that you've published documented, coded, designed, should be something that your product teams are going to use. And then you start back over kind of at the beginning of this process. We've been talking about feature workflow for design systems, but honestly, the feature workflow that you just described for us, is the same feature workflow that product teams use, maybe some of the things around handoff, or the way that you define the spec, the thing that you're defining is different, but you go through that process all over again with the output of the thing the design system team has made. It really has to be a whole cross functional process.

Jeff Pelletier:

When you compare them, I think what you'll find is, in general, design systems have to go through more hoops. They have to have a little bit more rigorous process. It ends up perhaps taking a little bit longer than the average product workflow. And that is again, something Nathan's got some great slides, that show the the overlap there, and what is omitted from the design system workflow when you're working on product.

Elyse:

Yeah, I love that. This is kind of my last question that I wanted to touch on. Thank you for like teeing me up perfectly. I, what I think is so interesting about this feature workflow process is that you can, use that same, those same steps in a incredibly formalized documented, defined way. Or you can do this in a extremely informal, extremely lightweight way. And so you can think about that working for like big or small teams. And it sounds like you've done this a little bit on maybe kind of like both ends of that spectrum. Can you talk a little bit about, I don't know, pros and cons or like, what you do on a bigger, more structured team versus what you do in kind of a more lightweight way.

Jeff Pelletier:

You know, after going through the entire process of introducing the concept of a feature workflow to the core team, getting inclusive decisions. And creating all the outputs—so the visual, getting it into our docs, updating JIRA, all of that—the feature workflow becomes your contribution workflow. And when you, when you write about it on your doc site, it can be overwhelming to people coming in the first time. So something that I mention right up front is don't be concerned if this feels overwhelming. You can pick up any piece of this. Like if you only want to pick up, one small sub step in the design step, that is totally acceptable. Or maybe not even pick up any of the actual steps. You're just bringing the contribution to us and having a conversation. And so try to express upfront and as clearly as possible to people yes, this is a very thorough workflow, and it is something that is required from our perspective, in order to support the organization and all the products that we support. Let's make it work for you in the way that works for you.

Elyse:

Yeah. Yeah, absolutely. I mean, I'm a design system team of one. We go through what is effectively the same process, only, don't have it like formally written down with a bunch of steps and a flow chart, because what's happening, for me as a team of one is like, I have a designer who's doing some like creative stuff over here, working on a product and they're talking to an engineer and they're like, actually like, here's the thing that's kind of already in the system, is it like that? Do we want to use this? Do we need to do something different? We're just having a Slack conversation. And then we're making those same decisions. We're saying, yes, this needs to be a new component. No, it doesn't. We're going to edit this one. No, actually, maybe just build that in the product because it's new and we'll see if it works. And then going through all these steps, but in a, in a very, very loosey goosey way. Versus if you are working somewhere very structured, very formalized, whether that's size or organizational culture, right? where everything has to be, like, documented and written down, you do the exact same steps, you just do it in a much more formal way.

Jeff Pelletier:

That's kind of the whole goal with this stuff is like, we think these things through and we set up all these visuals and kind of explain it and documentation so that, people can understand it and start using it. But once you start using it, you know, it's like riding a bike, right? Like you don't need, you're just,

Elyse:

Yeah. You don't need the instruction manual anymore. But I think that I think it's worth calling out because anytime you document a process, you've got it written down, you've got a diagram, and it's like, oh my God, this like formal process, like it's such a pain, it's all these steps. And then we, we publish all this information, especially in the design system space. And we're like, here's your governance process. And then people just getting into design system, or a team who wants to start one up, they're like, oh my god, we have to implement this like complicated formal process. And it's like, this is just the conceptual mechanism by which we do these things. And I think it's really important to say, like, you can do it at varying levels of formality, varying levels of like weight, and still have a really good flow. Jeff, thanks so much for hanging out and talking us through all of this. I think it's really really great and I hope that listeners you're either hearing, oh, like we're doing this, maybe just not in as formal of a way, or oh, like we're missing a step. And so I hope that this has been helpful for everybody. Jeff, as always, I have one last question that I ask everybody who comes in the show. I want to hear a Jeff spicy take on design system.

Jeff Pelletier:

My spicy take is definitely on this recent discussion around components versus patterns. I've heard what I consider more design folks talking about, let's not focus on components, let's focus on the larger things and patterns. Because that is, you know, what people are going to use. And I think that comes from Dan Mall in his book, talking about, you build the big thing first, prove the worth to the organization, and then kind of go back and, and clean up the tech debt after. On the other side, you have what I consider like design coders or like Brad Frost or, I know Nathan Curtis isn't necessarily a coder, but he is like a math, mathematics degree or something. So I don't know, that

Elyse:

Oh, I didn't know that.

Jeff Pelletier:

background, right? And what I'm hearing from that side is, the core tier of your design system is not going to include all of these recipes. Like maybe it's only 30 to 40 like core components. And those larger patterns or recipes are going to live at a completely separate tier in your organization. Brad talks about how that kind of like lifts the burden from the shoulders of people on the core team. And so there's a little bit of differing, camps that I've heard recently.

Elyse:

Honestly, like in, in both cases, whether or not you're thinking about that as like, oh, we put recipes in this other layer, or we don't even include those foundational things in the design system at all, are just two different takes on the same problem, where we're like reinventing the wheel in a kind of an unnecessary way.

Jeff Pelletier:

I see both sides

Elyse:

of

Jeff Pelletier:

it. That's the reason why I think Brad frost is talking about this, like global design system. And also very much understand the value of showing stakeholders the more complex thing and how the design system team helped create that, and then can kind of go back and create all the smaller things after. So yeah, there's, I'm sure there's a valuable paths on both sides.

Elyse:

Yeah. It turns out there's no one right way.

Jeff Pelletier:

What a surprise.

Elyse:

Well, yeah. Thank you so much for coming on the show. It was a real pleasure. I really appreciate it. I love having some engineering voices on.

Jeff Pelletier:

Yeah, thanks Elyse. This was really fun.

Elyse:

Thanks for listening to On Theme. This is a brand new podcast, so if you like what you're hearing, please subscribe now on your favorite podcast platform and at DesignSystemsOnTheme. com to stay in the loop. See you next episode!