What DESIGN.md Actually Solves for Design Systems

[00:00:00] Tim Gremore: I think with anything right now, it's moving quickly, so whatever tool that we adopt, want to do so with a bit of an open hand that this might get replaced soon, very quickly.

[00:00:09] Tim Gremore: There may be a better way. It might just be the next frontier model that does better, in more efficiently collecting context and building from that context, which lessens the need for tools like DESIGN.md.

[00:00:22] Billy Sweetman: Welcome to Intent & Craft, a product design podcast where we dig into design systems, AI in the design process, and what it really takes to scale design systems for software.

[00:00:31] Billy Sweetman: In this episode, we sit down with Tim Gremore, development lead at Headway. We talk about DESIGN.md, Google's open spec for handing an agent context for your design system in a single file. We dive into what actually belongs in that file, what you can safely leave out. We talk about why we point our design system MCPs at the file instead of generating the file from a library.

[00:00:51] Billy Sweetman: And we also get into Atlassian's published test results and what to kind of make of them.

[00:00:55] Billy Sweetman: We talk about some new customers of our design system, members through our orgs that might be building slide decks, landing pages, internal tools and dashboards who don't have designers or developers on their team. We talk how we can keep governance and contribution healthy once they show up. Now let's dive into it.

[00:01:11] Billy Sweetman: Today we have Tim Gremore, one of our lead developers here at Headway, to kind of discuss DESIGN.md, sort of how we're implementing it and our general thoughts around it. Tim, could you give us maybe a quick overview of DESIGN.md and a little bit about your development background?

[00:01:27] Tim Gremore: Yeah, for sure. Yeah, thanks everybody for joining us. We've been working with, Billy and I have been working with DESIGN.md, to help drive agentic work with design systems, and we've seen some early returns on that investment, on that commitment. It's been good. So yeah, looking forward to sharing a bit about that experience.

[00:01:45] Tim Gremore: For myself, I've been working with Headway for a few years now, and been working with design systems for the past three years, primarily working with design systems. And but outside of that, I've been able to work across web and mobile with different technologies that, that Headway uses with, whether it be React or Ruby on Rails or Phoenix and Elixir, or React Native for mobile.

[00:02:10] Tim Gremore: We've been able to serve customers in a variety of ways and across a variety of platforms. And so it's nice to be able to see design systems begin to take sort of center stage with whatever those products are, whether they're web or mobile. Design systems have always offered a promise of, of efficiency and, and maintainability for organizations.

[00:02:31] Tim Gremore: And so now with agentic help, that's even more, more true. So yeah, again, glad to be able to talk about it today a bit.

[00:02:40] Billy Sweetman: Yeah. Awesome. Now DESIGN.md is really Google's spec. They're kind of the ones who, who put it out there, kind of made it popular. What is DESIGN.md really trying to solve? What is kind of Google's intent behind creating that spec and sort of standard for us?

[00:02:58] Tim Gremore: What drew us to DESIGN.md initially is that it's a simple solution. It's, it doesn't have a complicated level of authentication on top of it. It's portable. I can take it from one model to another, from one provider to another, whether it be Anthropic or OpenAI or even Google itself.

[00:03:16] Tim Gremore: And so, so we like that about it because as we're working with clients, they don't always know exactly what platform they're gonna use and build upon. So that's sort of a, it's a must-have. We need to have something that can be used as organizations grow and adopt modeling and platforms. And so the DESIGN.md format is a, a YAML format.

[00:03:40] Tim Gremore: It's, like I said, it's pretty simple. It gives us a chance to bring all of the different context for a design system, context that's often spread across Figma files or Confluence documents, bring that context into, like I said, a single file, and agents are able to look at that file and reference it repeatedly as needed on demand in the context of a project, and apply the same context that you want your designs to use.

[00:04:14] Tim Gremore: So colors, fonts, spacing, general guidelines as to when to use certain colors, fonts, spacing. There's component definitions within it. So there's, it's a fairly rich amount of context, a fairly rich context given the simplicity of, of it just being a YAML file. And so there's additional tooling on top of what the file is and the specification that Google's provided, and that tooling helps with validation.

[00:04:45] Tim Gremore: It helps with additional portability options, so you can take that same thing, your same DESIGN.md file and generate other formats if, if that's something that you need. So it, in a lot of ways, has become a single source of truth for us as we have then built additional tools and conveniences for developers and designers for our clients.

[00:05:08] Billy Sweetman: Yeah, absolutely. One of the things that I think is interesting with the, like, the two halves, we, you know, we talked a little bit about the YAML token definitions at the top, and then we kind of have the heavy markdown prose down at the bottom. And I know ours, the ones that we've built for customers are a little bit pared down.

[00:05:27] Billy Sweetman: But in your opinion... Because they can get really lengthy when we start adding all the component definitions and things like that. In your opinion, what's the shortest useful version of a DESIGN.md? And is there anything, like, deliberately that we've thought that we might have pulled out and just taken out because it didn't make sense, at least for our use cases?

[00:05:46] Tim Gremore: Yeah. Yeah. So starting with the essentials, starting with your design tokens. So making sure that you have well-defined colors and units of spacing and, and type and certain dimensions that might be part of your design system. Making sure you have those essentials as the very foundation of your DESIGN.md and just starting with that.

[00:06:09] Tim Gremore: So the, the beauty of it is you don't need to start with fully built out DESIGN.md. You don't need to adopt every portion of the spec that Google's defined in DESIGN.md. You can start with tokens like you're saying, Billy, and then as you begin to see the benefit of DESIGN.md and you validate that which you've already established in the form of design tokens, then you can begin to add in more.

[00:06:35] Tim Gremore: And so what we've, what we've started is just that. We started with the essentials, what are the common design tokens? Then we begin to add in different guidelines as to when, when those tokens are to be used or when certain components are supposed to be used. And so as we've done that, again, then we can sort of go back and validate it.

[00:06:53] Tim Gremore: Is this actually giving us the result that we hope it, it does for designers and developers? Now there's some sections of the spec that we haven't leveraged yet, and there's a component section, for example. Now part of the reason we haven't adopted that, we've brought this into an existing well-established design system.

[00:07:12] Tim Gremore: We've adopted DESIGN.md after we've established that design system, which means we've already had definition, context in Figma, and we've had a UI kit that we've built out. And so the component section of DESIGN.md, it's not needed. We haven't had a strong felt need for it because of the existence of, and the maturity of the design system we've adopted it into.

[00:07:36] Tim Gremore: Now, if it was a newer design system, and potentially as this, you know, as our design system's grown and mature, potentially we'll have a need for it. If it's a newer design system and you, you want your agent to use components in Figma under certain conditions and using certain properties, it's a useful solution.

[00:07:57] Tim Gremore: But again, for us, it wasn't necessarily the case. And so your situation is unique and you... Our, our best advice would be to adopt just the thing that you, you know you need, design tokens, guidelines, and then begin to expand it. Every time you adopt something new, it creates more context, and that might be counterproductive.

[00:08:18] Tim Gremore: And so you wanna make sure you're giving the agent just enough, but you don't need to give it more than, than it needs to do the task that you're asking.

[00:08:26] Billy Sweetman: Yeah, I know early on when we were doing some component definition explorations with the DESIGN.md, and we were building the Figma Make library. And for whatever reason, Figma Make really struggled reading our design components from the design layer library and being able to recreate those in their Figma Make library.

[00:08:46] Billy Sweetman: So we did leverage some of the component definitions in a separate file, not the one that was publicly available, for everyone else on the team to recreate those, and it worked a lot better. There was still a little bit of nuance to kind of get those things, those things isolated. So that was one of the experiments we've done with the component definition.

[00:09:05] Billy Sweetman: And I think like we're starting to see different customers of the design system that might not have access to the core components, and they might be using a little bit more generative UI through Claude Code and things like that. And, and they're starting to show up as sort of customers of the design system.

[00:09:26] Billy Sweetman: And so I think there's a little bit of a conversation of how do we help them define components for them. From what we've seen, most of the stuff looks... They have the token definitions now. Most of the components look okay, but they're not as close as, as we would like. So it'll be an interesting evolution as, as some of those teams who don't have...

[00:09:46] Billy Sweetman: They're not using the actual design system. They can't use the actual design system. They don't have development resources. They don't have design resources, how they'll consume that in the future, so.

[00:09:55] Tim Gremore: Yeah. And if, yeah, if I could add to that, Billy, that's a, it's a good point where an organization that's large enough that has a design system, not everybody is able to use your React UI kit, for example. And so DESIGN.md becomes the thing that their agent can leverage to produce something that's design system informed and provides at least aesthetically consistency with the design system.

[00:10:24] Tim Gremore: So yeah, so there are different customers even within the same organization for what DESIGN.md needs to do. And it's been our solution to help them apply the design system to something that's not React in this case.

[00:10:39] Billy Sweetman: And I, I think, based on that, like for some of our customers will have a mature MCP, and we found that like a DESIGN.md is still needed for those folks who can't even leverage the MCP for the things that they're building. So it, it was one of those things that maybe at first we thought, oh, maybe we don't need this, but we did find kind of a use for it.

[00:11:01] Billy Sweetman: Speaking of the MCP, you know, in some of our webinars, we have a diagram where we kind of show how we think through where the DESIGN.md kind of sits in that structure. And we know some teams generate their DESIGN.md from their core library. In our diagram, we kind of have the MCP and the component library, whether that be the Figma library, inheriting from that, from that file.

[00:11:27] Billy Sweetman: Could you talk us through maybe like the differences between those two approaches, you know, using the DESIGN.md sort of as the source of truth for those versus something else in generating that out?

[00:11:39] Tim Gremore: Yeah. Yeah, that's really good. DESIGN.md opened up another, just another option for us when we publish a design system MCP. So prior to DESIGN.md, we would extract variables from Figma, and we'd build some tooling in order to do that. And then we'd extract those, that design knowledge from Figma.

[00:12:03] Tim Gremore: We would bake that knowledge into an MCP, and then configure your agent, pull in the MCP, and you would have, you'd have design system context available to your agent right then and there. The limitation in that is it was primarily, not exclusively, but it was very heavily weighted to the development side of, of your team, and it wasn't exactly serving the designer.

[00:12:31] Tim Gremore: And so the ability for us to instead have something like DESIGN.md, I would say primarily serves designers, though it does serve both design and development. It just doesn't fully serve and meet the needs of the development team. Having that DESIGN.md file, which can then be the source of context for the MCP that we publish, that did a couple different things.

[00:12:56] Tim Gremore: I mean, it helped minimize the amount of tooling we, we need to write to pull knowledge out of Figma into the MCP, 'cause now we just pull from the file a well-written spec, right? So it's, there's definition there, and so you can build tooling around it in a reliable way. And now, but now because you're doing that, you have sort of one, still one single location for truth, and you have a solution that serves design and development when it comes to generative AI work.

[00:13:26] Tim Gremore: So that was a pretty, a pretty useful win for us when we, when we started to reference DESIGN.md as the foundation for our MCP definitions that we, we build around design systems. So like I mentioned, MCPs it leans toward serving the development side. DESIGN.md leans towards serving the design side.

[00:13:48] Billy Sweetman: Mm.

[00:13:48] Tim Gremore: Just a little bit more about that. You know, the, the thing that DESIGN.md doesn't provide an agent with is a list of props that your React component has.

[00:14:00] Tim Gremore: And so if you can give an agent that definition, that API to your component in React form directly, you save cycles, you save time, and you get a more accurate output from your agent.

[00:14:14] Tim Gremore: There's the component section in DESIGN.md, but again, that's, there's a difference between your UI kit and components that are in Figma. And so it, that component definition leans toward serving designers and your design tooling. And so MCP along with DESIGN.md help, help serve both designers and developers, though there is overlap between both tools.

[00:14:40] Billy Sweetman: Yeah, I always feel like the component definition is more, of the questions I want to talk a little bit about, it's like rebuilding, it's instructions to rebuild those components. And the thing that, and maybe this is, we can talk about this a little bit. Like, if the MCP is kind of loading the context on demand of the different components, props that it has, things like that, and then DESIGN.md is kind of giving those instructions.

[00:15:03] Billy Sweetman: We always talk about like, where does the design philosophy, where does it tell when to use what, when not to use a specific thing? We've put some of that information into like Figma descriptions, and really hoping to leverage DESIGN.md to do more of that. Or is there a better place for that kind of instructional use?

[00:15:23] Billy Sweetman: Is that something that maybe goes into our agents file? Because the concern is like the DESIGN.md files can get really long if we're filling out, "Here's every component, here's the definition, here's when to use it, when not to use it." Or is there a version that's maybe chunked out a little bit? Do you have any thoughts around on how to effectively place those instructions so that agents know when they should be using something or how they can figure those things correctly?

[00:15:46] Tim Gremore: Yeah. That, yeah, it's a really good question, right? If you talk about a single YAML file, in theory that file is, you're putting a lot of weight on a single file. So it's important to consider, like, when do we outgrow this? Identify and anticipate, like, when would we actually as an organization outgrow this single DESIGN.md spec?

[00:16:06] Tim Gremore: What we found is when you don't zero in on a single part of tooling around agents, you're just better for it. And so what I mean by that is if, if we were to put everything in MCP, we would lose knowledge and opportunity with things like a prompt or a resource, or a hook.

[00:16:26] Tim Gremore: You know, different options that agents have at their disposal to help serve you better with the prompts that you feed it. So same thing with DESIGN.md, right? We don't wanna put too much into that in a way that we miss other levers that we can pull to provide a better result.

[00:16:44] Tim Gremore: Things like routing, if you have an agents MD file, which I'm sure you do, you should if you don't, at part of your project, that agents MD can help guide the agent when to use DESIGN.md. And there might be instances where you say, "Don't use DESIGN.md here because I've got this other resource for you to answer the question with."

[00:17:06] Tim Gremore: So you can begin to separate some of the resources and context that you have into different files. Use a skill file when you can. There's a lot that you get from DESIGN.md, and one of the benefits of what Google's created is, like I mentioned earlier, you can use the tooling that comes with the spec to validate that, one, you've adhered to the spec, which is helpful.

[00:17:32] Tim Gremore: There's times where you might have to diverge from it. Organizationally, you might just say, "Well, this is our constraint and therefore we can't adhere to it perfectly." But it helps to know when you're diverging from it, not just blindly diverging from it. Is that you can generate other resources from that single YAML file, from your DESIGN.md file using Google's tooling.

[00:17:53] Tim Gremore: And so you could use DESIGN.md with the tooling to generate a skill file, or you could partition off some of the knowledge in that file into some other context which you'd then route your agent to under certain conditions. What have your thoughts been on that, Billy?

[00:18:11] Tim Gremore: What have you seen?

[00:18:12] Billy Sweetman: Yeah, I mean, like we've, we've talked a little bit about like it's really validating for teams who don't have access to the design system to be able to use that. And we've used it in probably not the way necessarily Google has intended with, you know, building those Figma Make components, like having those instructions and those definitions in there.

[00:18:31] Billy Sweetman: And I know, you know, we've extended sort of the format, 'cause at least as of this recording, there is no multi-theme support in there in light or dark mode. So we've based on some of the conversations in GitHub, we've extended it on our own, and I think it does do a really good job of building that set of instructions for teams who can't necessarily use the components.

[00:18:58] Billy Sweetman: So it allows them to generate things that look similar. And the thing that I care about the most is like, well, how do we tell agents to use the components correctly? When to use things? When do we define those things? And we can put some of that stuff into the key characteristics.

[00:19:12] Billy Sweetman: We can put some of that stuff in the do's and don'ts. And just finding that right, that right balance, to really make it effective for teams so that a designer comes up and says, "Well, actually we should never use a segmented control here because Claude Code decided to put a segmented controller in there."

[00:19:27] Billy Sweetman: It's like, well, it's just instruct the agent, so it knows those things and have that in there.

[00:19:31] Tim Gremore: Yeah, that's good. Yeah, do's and don'ts go a long way.

[00:19:35] Billy Sweetman: Yeah. Yeah, exactly. Like, how do we incorporate more of the design philosophy in those, in that, in the rules there?

[00:20:58] Billy Sweetman: I know Atlassian kind of ran tests on DESIGN.md, and published some numbers that, you know, at first glance don't really flatter DESIGN.md a ton. Does that change, like, your mind specifically about anything, or are they really measuring a different job than the one that we kind of see, the file, you know, the job that it serves us versus what they are kind of looking at?

[00:21:22] Tim Gremore: Yeah, it gives me caution for sure, right? Like, I'm interested in what other organizations of significant size are doing. How are they... What are they benefiting from, and what are they skipping? I think with anything right now, it's moving quickly, so whatever tool that we adopt, I want to do so with a bit of an open hand that this might get replaced soon, very quickly.

[00:21:48] Tim Gremore: There may be a better way. You know, the replacement might just be the next frontier model that does better, in more efficiently collecting context and building from that context, which lessens the need for tools like DESIGN.md. So I'm aware of that reality, and I'm sure everybody is at this point.

[00:22:07] Tim Gremore: Your situation is unique, and for us, our situation is such that we're serving multiple products across an organization, multiple platforms, and multiple teams who all have somewhat some independence in what they choose to, and how they choose to build and design. And so we need something that serves a variety of use cases, and I don't know that that's true of a company like Atlassian.

[00:22:32] Tim Gremore: They may have a bit of a narrower scope in some sense because of their primary products. And so there's a difference in our use case than what Atlassian's is.

[00:22:43] Tim Gremore: The need that we had when we first adopted DESIGN.md, again, it's potentially, it's gonna change over time. It may have changed already. And so what Atlassian's reporting is just a different use case and a different time than what we've seen. So at this, as of today, I would continue to recommend DESIGN.md.

[00:23:00] Tim Gremore: Obviously we are in this podcast. But again, like keeping it a bit open, open-handed, at least a loose grip on it, knowing that there might be a better way that is devised to give your agent design system context.

[00:23:12] Billy Sweetman: Yeah, I think one of the, their big thing was it gives instructions to rebuild components instead of using an existing library, which, I mean, that's sort of what the component definition is, and that could invite your agent to build another button instead of using the one that's there.

[00:23:31] Billy Sweetman: But I think, like, across some of the different products that we've worked on and some of our different clients, we have clients where DESIGN.md is their design system. Everything is built in a generative UI tool. The design system is the DESIGN.md. It gets evolved, it gets updated. Everything's being built with Claude Code, and that is how they're standing up landing pages.

[00:23:53] Billy Sweetman: That's how they're standing up different flows. And they don't have designers on staff, and our design team is helping them navigate that space and do that. They don't have heavy development resources. They kind of stitched different tools together to create what they needed, and they have a variety of front-end libraries and things like that.

[00:24:11] Billy Sweetman: And that's like a really great use case for it. And then we've also found that exists, like you were saying, Tim, with some of our bigger clients, where they have members who need to build UI, but they have no developers, they have no design resources, and it helps deliver them what they need.

[00:24:30] Billy Sweetman: And we've used it to do Figma Make components early on. It's helped a lot. So we found a lot of value in these little pieces that maybe it's not super intended for. But it has helped in these, empowering some of these members on teams who might not have access to a suite of tools or a team who doesn't have the resources to build an entire design system from the ground up.

[00:24:50] Tim Gremore: And just to add to that too, Billy, you know, I think in current state, and probably for the foreseeable future, like having a team that can help pinpoint, given our context and our situation, what is the tooling that will help us reinforce the design system and get the value out of our design system, whether the design system exists today or will exist soon, like what is the tooling that we can build to meet our specific needs?

[00:25:17] Tim Gremore: And so maybe, again, maybe in Atlassian's case, that isn't DESIGN.md, or it's negligible as to whether that's gonna be a benefit to them. But having somebody that can help pinpoint the why and then the what behind those decisions is a really important thing to have right now.

[00:25:35] Billy Sweetman: Yeah, absolutely. And with that, we talk about the use case of empowering those members on teams, and we've given some of them DESIGN.md. And even if they are building, for example, one of our clients are building in React Native, that's what the design system is in, and they are building in that.

[00:25:53] Billy Sweetman: And how do you feel like they start with DESIGN.md, they're kind of building up the things that they need, they're generating UI. Do you think there's an evolution or a next step where maybe they're not using DESIGN.md and we just get them up and running with the MCP and they slowly transition out of that if they are building in the same front end language?

[00:26:14] Tim Gremore: What that reminds me of is design system adoption is one of the biggest challenges that we've all faced. And so getting team members or, you know, across an organization to commit to using the design system, whether you're a designer or a developer or even in product marketing, whatever your role is, you have some level of commitment to the design system.

[00:26:39] Tim Gremore: And so, to answer your question, the design system helps you establish your product, get to a certain level of maturity with your product, do I need my design system anymore? I would say, yeah, you need it more than ever. Like, the thing that got you to where you are is the thing that's gonna help sustain your product and keep it maintainable and predictable.

[00:27:00] Tim Gremore: So I would say you may not be contributing back to the design system as frequently as you were in the beginning, but it doesn't mean you don't need the design system anymore. And so when there is, there will be a learning, there will be something that the design system has to accommodate in the future, no matter how mature your product is.

[00:27:19] Tim Gremore: There has to be a culture of contribution and commitment to bring that back into the design system, which then helps feed future product design and development. So I would say there's never not a point where you need your design system. The tooling around it might change, so you might, you know, maybe you do say, and maybe this is the heart of your question more so, Billy, but maybe you do say DESIGN.md isn't needed, but I wouldn't say that without having a replacement.

[00:27:48] Tim Gremore: It just means you've got a better way to get your agent the context of your design system. And that's totally fine, but you would never just abandon the thing because you need your design system. That's just how it is.

[00:28:03] Billy Sweetman: Yeah. Yeah. And I was kinda thinking of it as like some of these folks aren't, you know, might not be very technical or this is the first time of them doing like really technical work, in the sense of like actually developing UI and developing product. And DESIGN.md feels like a good, like soft start into using, getting components up and running, getting the brand, philosophy look and feel into their product.

[00:28:28] Billy Sweetman: And then at some point, you know, when they have a little bit more appetite for it, because if they're gonna use the MCP, it's a little bit more work. There's more understanding they have to have about the different tools that are available. It seems sort of like that next level. And we have some folks on some of the teams that we work with who are eager, right?

[00:28:46] Billy Sweetman: They weren't developers, they weren't product designers. They might sit somewhere in between and they're eager to learn those things, and they're eager to kind of move to that next more technical spot. And you know, as a design system team, we kinda wanna help shepherd them to get there and get to the right level of need, and the right level of like tooling, and make it real as easy for them as possible.

[00:29:12] Tim Gremore: I think we've both seen this, Billy, where an organization is using DESIGN.md, using the design system for web and mobile product development.

[00:29:23] Billy Sweetman: Mhm.

[00:29:24] Tim Gremore: But what we then begin to see shortly after that is slide deck creation, right? Like newsletter creation. And so then the question naturally becomes, well, how can I...

[00:29:35] Tim Gremore: Oh, this is great. I use my agent to create the slide deck or help create my slide deck or my newsletter. How can I make that adherent to my design system? Well, DESIGN.md is a fine solution to that problem, to help very easily, very low tech, equip somebody who's developing those non-web and mobile products with the design system.

[00:29:58] Billy Sweetman: Yeah, absolutely. Yeah, it's been really helpful there. In one of our thoughts, or one of the things that we've done with one of our clients in the DESIGN.md is, you know, we can't... Sometimes there's needs that might be outside of what we have visibility in, and we always kind of want to promote this open contribution model.

[00:30:20] Billy Sweetman: How do we, with DESIGN.md, how do we manage sort of the governance around that? Could you talk us a little bit through about that process? 'Cause I know that's something that we care a lot about, is allowing others to contribute back into that and evolve that. How do we manage that for some of our bigger clients?

[00:30:37] Tim Gremore: Yeah. Yeah, this is kind of the unanswered question, I think, for a lot of organizations. And so how we've tried to answer that is make sure that there's multiple channels of communication, and we do our best to make sure those channels are publicly available.

[00:30:54] Tim Gremore: So if it's a question that a designer or developer has, we try to point them to the same shared channel, whether that be in Slack or Teams or wherever your chat might be happening, make sure they're in a place that others can see. And we've found that it's important to point both designers and developers to that same resource so that as something, a design is newly developed or ready to be developed, there's shared knowledge across disciplines.

[00:31:25] Tim Gremore: There's things that, like, I know, Billy, you and I have answered for one another simply because while we are in the same channel, we know that the question must've been raised, and we have the knowledge to help. So one, like making sure that there's publicly available conversations happening within your organization.

[00:31:41] Tim Gremore: Two, once you have ideas that come to you, whether it be through chat or however folks are reaching out to you from the organization with questions or ideas about the design system, you're affirming the thing that they're asking of you. Like, "Oh, yeah, that's a really good question.

[00:31:59] Tim Gremore: I don't have an answer for you right now. Let me talk with the team, with the design system team." And then you're following up with them quickly. So just some very basic communication, it goes a long way toward helping build trust with the design system and even lowering the fears that some might have about asking questions and the approachability of your team.

[00:32:18] Tim Gremore: And then offering to help usher them through and, like, support them through a contribution. So if it's development side, having clear steps as to what needs to happen for the code contribution to be made back into the design system, and then walking with them through that process, and even offering to take over some of that work if they get to a place where they're not prepared to finish the work or they simply have limited time to do so.

[00:32:46] Tim Gremore: So being able to, again, work with them, come alongside them, even take over the work that they start but are unable to finish for whatever reason. Being able to then celebrate on the backside of contributions, again, publicly, like acknowledging folks that contribute, making sure that others in the organization see the work that's been done, and then calling out how it benefits, being explicit.

[00:33:11] Tim Gremore: Like, this new component is gonna help such and such a team achieve their goal. Being able to call out those specifics also helps encourage others to contribute. And it might not be code, it might not be design, it might just be conversation, but those are all meaningful contributions that have helped us in the past to mature at design systems.

[00:33:35] Tim Gremore: So I would say, yeah, public conversation, support when it comes to contributions and invitations to users who ask questions, invitations for them to do the actual work of the contribution, supporting them through the process, coming alongside after contributions have been made and recognizing those contributions publicly is important. Yeah, how have you seen, Billy, in addition to that, what else have you seen encourages governance and equips us for governance?

[00:34:07] Billy Sweetman: Yeah. I was just thinking like public channels are a real big win across an organization. I think that's where we found a whole bunch of customers that we could serve through DESIGN.md because somebody created an MD file from some brand standards and posted it as just like an off comment, "Hey, I put this together because I'm putting a slide deck together."

[00:34:32] Billy Sweetman: And we saw that, and we were able to essentially engage with them and work with them to leverage the DESIGN.md, and that was sort of a success story there. And then come to find out through that conversation, oh, we have all these other folks who are also asking those questions who we didn't traditionally look at as customers for the design system, and we were able to serve them and get them to use it.

[00:34:57] Billy Sweetman: And that's been really helpful. And now they'll still come through the support channel for updates and requests. We're trying to... I know like using the GitHub workflow and making changes to the DESIGN.md and putting that in might be a little intimidating for some folks.

[00:35:13] Billy Sweetman: But we do have teams where designers are managing that workflow and updating the DESIGN.md and versioning through that 'cause everyone has access to it. Sometimes the bigger organizations, they might not, so you're gonna have to store the file maybe somewhere else. But it's made us kind of think about how do we open up that contribution model more, and then really how do we track that as part of our engagement metrics too because we have all these new customers who might not be engaging with the design system in the way that design and developers are engaging with the design system.

[00:35:46] Billy Sweetman: They're not using the Figma component library. They're not using the coded components. They might not be coming to office hours 'cause they're not having these technical questions, but they're still using it, and they're still leveraging it, and they're still part of that engagement and adoption metric.

[00:35:59] Billy Sweetman: So I wanna make sure we include them and call out those wins, because I think that's a really compelling story for leadership too. So the design system is expanding into these roles that maybe you didn't think that it would and continues to demonstrate the value of a very foundational piece for every modern product.

[00:36:17] Tim Gremore: Yes. Yeah, that's good. Yeah, it's an active thing. It's not ever solved contribution model. It's something that you have to continue to work at, and it's one of the most important parts of the design system.

[00:36:32] Billy Sweetman: Yeah, ongoing work to continue to get folks using it and engaging with it and kind of keeping that conversation going.

[00:36:39] Tim Gremore: Right.

[00:36:40] Billy Sweetman: So, sort of in closing here, like, if folks wanted to dive into DESIGN.md and start thinking about how it might empower their products now or help members on their team, where would they start?

[00:36:57] Billy Sweetman: What is a good maybe resource or two or some thoughts? I understand it's gonna be use case by use case basis because every team's gonna be a little bit different, which we have seen. Where might be a good starting point to kind of hit the ground running?

[00:37:12] Tim Gremore: Yeah, that's a good question. Whether you have a design system, it's mature, it's new, or you're just looking to get started establishing a design system, DESIGN.md is worth looking at. I would recommend just starting with the documentation. I would just start with their GitHub page, to be honest, and then looking at the spec itself and get to know the high level, the root level sections of that, and get familiar with what it provides you, what it offers you.

[00:37:42] Tim Gremore: That's the first place I would start. And then, like we said earlier, just starting with the essentials, starting with different tokens, essential tokens, and then you can always add it to a project and begin to iterate on it from there. But I would start getting to know those high level sections of the spec, and then I would look at the different tools that DESIGN.md provides.

[00:38:04] Tim Gremore: So we mentioned the ability to lint your file, to test and validate that it's adhering to the spec itself. Get to know that, potentially even include that in your CI workflow so that depending on how well the spec maps to your organization's needs, if you can adhere to the spec faithfully, then I would encourage you to do that.

[00:38:27] Tim Gremore: And if you can, then you can include that in your CI workflow to make sure you don't diverge from it over time. The other thing is if you have some exceptions where you need from your DESIGN.md file, you might need to generate other versions of it or other tools based on that information.

[00:38:45] Tim Gremore: Again, leverage DESIGN.md and get to know the tools that it provides to help generate that derivative of the DESIGN.md file. And again, it doesn't have to be an all or nothing. It can be a complement to your existing agent context. It probably will always be a complement, but what we've found is that it ends up serving some of the other contexts we provide our agent.

[00:39:08] Tim Gremore: It ends up serving our MCP in particular. So that's where I would start, and then get to know, read, and study how others have used it, like Atlassian's experience. Get familiar with it. Maybe their experience maps very closely to your circumstance, and get to, you know, talk to others and see what they've learned from using it and adopting it.

[00:39:30] Billy Sweetman: Yeah, absolutely. Well, thank you, Tim, for popping on to talk about DESIGN.md. I'm eager to see how we continue to evolve it on various clients of various scales, whether it's big enterprise customers or a little bit smaller. Maybe we'll do another one of these in six months and see what has changed and what we've learned, and chat about how...

[00:39:52] Billy Sweetman: Our new thoughts about it.

[00:39:54] Tim Gremore: Yeah. Yeah, for sure. We love to hear from folks too. So as you explore this and/or you've already explored it, you know, we'd love to connect with you. So let us know what your experience has been 'cause it's an exciting time. There's a lot to keep up to, but it's an exciting time and it's fun to be able to improve design and development efforts.

[00:40:17] Billy Sweetman: Absolutely. All right. Thank you everyone.

[00:40:19] Tim Gremore: Thanks everybody.

[00:40:20] Voiceover: Thanks for watching Intent & Craft. Want to support the show? Subscribe and turn on notifications so you never miss an episode.

[00:40:26] Voiceover: You can also share it with your team or leave a rating and review to help other designers and product leaders find us. We'll see you next time.