Design.md: How to make your design system work with AI

0:00Design.md is everywhere right now. You drop one in and your site looks on brand in seconds, right? A lot of what you see out there today is this version. It's pulled from a website, but I want to take the design.md deeper. I want it to go into the product. It should still stay lightweight and high level, but what changes is the coverage. I want to make sure that it is pointing to the components, the rules, the edge cases, and making sure that all of that is defined and easy to reference. So, the AI builds with them in mind and doesn't hallucinate. This video is for the whole

0:31product team, design, engineers, PMs, founders. We're going to build a design.md for a real product. It points the AI to where all the complexity lives, the components, the rules, the metadata. All of that's going to be defined in a very lightweight version. Let's get started. Let's talk a little bit about what a design.md file is. I'm going to share my screen. So, the specs for design.md, they came from Google, Google Stitch, and it's basically just a file format. It says Y A M L front matter contains machine-readable design tokens, and then markdown body at the end. Basically, what it's saying is that the first part of a design.md

1:12is just definitions like this. It's going to have the name, the colors, the specs, all of the details here. And then, at the end of the document, it's going to actually write it out more like this is how you use the typography, this is how you use the design tokens, this is how you define it more in English. So, it's giving you all the detailed specs, and then it's writing it

1:35out more as like a definition of sorts. And this has become really useful because when you plug this into your document and it fully understands the branding, the components, the imagery, the spacing, then it's going to read this file every time you design something, and it's going to make sure that it's really following these guidelines. So, that AI isn't just hallucinating, making up design decisions that aren't being made. This

1:58has been really useful in my projects. Um so, I'm going to start by showing us how to actually create a design.md in our product. So, I want to take the design.md one step further. A design.md does have all of your branding guidelines. It's great. Um but, where I see it start to break a little bit is when you're building a really complex product or just you have a lot of components and a lot of styling and many specifications is that it feels very surface level, and it should. It should be very lightweight. But, what I want to do is I want to I want to connect it more easily

2:33to your component library, your storybook, so that it just has, "Hey, this is the component." And then it says, "Reference this file to go deeper." So, this means that all of the work that you've been doing on your component library and figuring out how to create a component library that really speaks to AI, you're just going to make sure that your design.md is clearly communicating with AI how to get to that next deeper level that you've started to create. So, first, like I said, let's jump into the design.md. So, there is a skill that Google Labs created. I'll share the link below. And it basically is defining

3:13exactly what we talked about, how um a design.md should work. So, there's a few ways to use it. Um it also says you can compare your current one with the standard. Um it also tells you right down here how you can install for CLI reference. So, what you're going to do is you're going to go into CLI, and here, let's start up Claude. I'm going to be using cal.com as my example. It's an open-source platform. It's what I've

3:36been using for a lot of these videos. So, let's go ahead and paste the instructions to install. It's basically telling me here that Claude.md flags, adding new dependencies as an ask first, so it's asking me. Um there's a couple ways you can do it. You can do a global CI- CLI, which means anytime you're in any project, it'll work. Um I'm just going to do it just

3:57for this one right now. So, it's just going to be for this one project. Okay, so it basically it's giving you four options of how you can use this. You can validate uh design.md for structural correctness. So, if you already have one, you can compare to, you can convert into a design.md into tokens, which is very cool, or a spec.

4:19We want a spec, right? And it's telling me right here. Um and you can see here it's literally saying you're in the branch design.md. I created this branch so I could work on it here. Um do you want to run a spec? So, we do. Yes, I want to run a spec. I want you to look into all of the components, all of the design, all of the Tailwind, all of the CSS, and I want you to build this design.md file based

4:44on all of the branding from this repo. So, it's gone and found the design tokens in the package theme. It's going to read them. Okay, so you can see it's here. It says it's done everything. The design.md spec requires colors as hex. Okay. So, this is interesting because a lot of the times we want to make sure we're building tokens. This is just a way to make sure that everything is defined very clearly. Um it's the the Google way, which sometimes I push back on, but it seems to be working. So, I just followed the guidelines where it says it's just going to pull all the hex

5:15colors. Great. So, it's written it, which we'll read in a second, but what's great is it's now using its other command lint to actually go through and see if there's any errors or any inconsistencies. So, it's just checking itself. Okay, so it found a couple of changes it needs to make. Perfect. Instead of saying 2XL, it

5:32should be saying XXL. That makes sense. It'll update. Perfect. It won't happen again. Okay, so it looks like it's done. Created the spec. We're going to look for spec.md. Hey, it mined. I like that it used your mind. The actual branding from the repo converted accurately and written validated. There are 28 colors. There are 10 typography levels. It doesn't define how many shapes. It's defining the elevation, the components,

5:55and the layout. Okay, and then it checked itself, so then it told me what it did to fix the changes that it made. You're on the MD range. Okay. So, now let's go take a look at what it's done. So, here's my design.md. Okay. I'm just going to put it in preview. So, this is what it has done. It has defined the brand colors, the neutral, the text orders. This is all just exactly what it said. It's just going to define everything here. Data

6:31visualization. Okay, how it uses that visualization. All of the fonts. And then it has the components here. So, we're going to come back to this in a minute. Um And then at the end, remember we talked about now it's just defining in words. cal.com is an open source scheduling. Feels calm, trustworthy, precise. So, it's just pulling the feeling of it. And then here's the description. This is how

7:00it's defining colors. How it uses them. So, this is really for the AI to understand, "Hey, this is the name of it. This is how we define it. Um this is borders, semantic for all of the colors." And then source of truth, tokens are defined on HSLA HSLA CSS custom properties. Right? So, cal big. This is what we're talking about with those

7:24tokens and semantics here. We have a dark mode. And then it's going into details about about the typography. Um weight 600 only. So, see it's really defining exactly how you should be using these fonts. It's not leaving anything up to interpretation. Um I definitely suggest reading this more in detail and going back and forth because sometimes it might not pick

7:46everything up that it needs to. Um, and it's also like if it keeps making mistakes, you can go back and say, "Hey, update the design.md based on so it doesn't make this mistake again." The scale used to tailwind's default steps. Okay. And then the layout is built on a strict four pixel spacing. I love when it uses

8:04these words. Like it's really concrete. This is strict. Okay, depth is conveyed in two ways, total and tactical. And it's going to define examples of each. Then all of the shapes. And then here are the buttons. Um, so this is actually pulling from the component library that we built already. I'm going to show you guys I'm simplifying I'm just showing you a button for right now, but basically you should be building a very detailed design system. I suggest using

8:37storybook. I'm going to link to a video. I'm going to walk you through how to actually create your components whether you're bringing them in from Figma or another tool. It's going to be able to get all of your components in one place documented. And then it's also going to tell you more in detail how to do this thing called metadata. So a metadata is basically for each component you're very very detailed in describing how it's used. The different sizes you can use

9:04it. The variants that you can use it. The relationship. You can use a button in a footer or a button when you use a button you should always click. It's very very detailed. Um, and this is just to leave no questions up to AI to figure out. So you can see um, like the keywords, AI hints, this is how you use all of this information. And then there's anti-patterns. You should never use two default buttons next to each other. Um, and it's something you can keep building upon. And again, I'll

9:35link to that YouTube in the description. But what I my next level of going deeper on the design.md is the design.md should be lightweight, but it should also say, "Hey, if you want to see more about the metadata of the component, go here." So that's what I want to include as a next step, which I'm going to show you in a second, is I want to make sure that we're not going deeper here, but we're giving the ability for the design.md to know where to look when they want to go deeper. Okay. And then you'll see here after it talks through the components with more detail. You see here this one

10:09is more detailed because this is where we really wanted to detail it. Here is where we need to keep improving with detail here. And then there's do's and don'ts. So this is one of the most important parts of AI is you don't want it to go and make up ideas. So you're very clear about when not to do things. Do use the brand colors. Don't introduce new hues. Do keep all spacing. Do use Cal Sans. Don't use more than two font weights in a single region. Um read this and again, as you go through your product, you might identify other places where I make up mix up things and then

10:40you can go and fix them here. So this is a design.md. It's going to be in like we said, like I showed you kind of when I opened the folder. It is going to live as a design.md and you also can go in and you can open your agents or your Claude.md and you want to make sure

11:07Here, let's actually ask. I want to make sure that in my Claude.md and my agents.md it says anytime it's creating any UI to reference the design.md file. So this is really important because the first thing you're going to do is the AI's going to look at the Claude.md um and then the agents. So if this is a Claude, it's going to look into the agents file, which means if you're using Codex or something. So you want to make sure that both of these .mds at the very front are clearly communicating if you're doing any kind of design updates to reference the design.md. Yeah, so it's basically they're just mirrors of

11:41each other, the code.md or the agent.md. Okay, so it's going to add this rule. This is really important. Do not forget this step. When creating or modifying any UI, read and follow design.md. Perfect. Okay, so it's added in a couple places. Wonderful. Okay. So, now let's just go and let's um tell Claude to add where to actually look for more information on the button component. We're going to start here. If you look deeper into the component button, you'll see that there is a metadata.ts file. I want to make sure that the design.md file is referencing the metadata so that when it needs to go deeper into understands all the do's and

12:31don'ts and the details for that specific component, that it just knows exactly where to go. So, I do not want to add it to the design.md. I want it to reference it so that it opens that file when it's ready to actually create a component. So, this is This can be detailed, right? Especially it's it's a lot of work, especially if you're building and you have a ton of components and you need to build all these agentic ways of communicating with components. If you have a really, really large repo, if there's many different parts of the project that you're working on. So, one thing I'm doing is I am offering

13:03workshops. Um so, it's a paid workshop. I go in and I basically understand where your current design-to-code process is, where it's breaking, and solutions that I can give your team so that they actually know how to handle this complication and to actually build a process that makes sense for you and your team. I also am helping design teams build this agentic design system as well. So, there's a link in the description if you're curious to learn a

13:29little bit more about the offerings. Okay, so this is what it's done. I could joy. Per component deep reference the section is the system level summary. It intentionally does not restate every component's full contract. When you are ready to actually build composer modify, open the metadata file first. Okay, so then it gives an example. Okay. Um I actually have done it a little different before, but I don't mind this version of it. Okay, I think this is okay, but also as I continue to build my my design.md, I want to make sure that where I have details about the button component, I want to say reference and

14:06then give it a link the metadata to get deeper and understand more about this component. So, I want you to add it to that specific component as well. Okay, so I'm going to be saving this. Let's go see actually what it looks like in actual MD file. Okay, so what it's done here, actually we can look at the top components. Per component deep reference, the system is system level. So, it's basically exactly

14:30what we said. So, it's telling it to go into each meta.ts. And the example is here is the detail of button, and then it says reference. Open this before building or composing a button to the full contract. I love this. Um I could probably make it a little smaller, less like lighter weight. This is what I would do if you want to take your design.md to the next level so that it really is building your component library, your design system, everything wrapped in one. So, when you're pumping and creating new designs, new features, your whole team, not just designers, but PMs, founders, anyone on the team can go in and they can actually

15:07spin up the designs that they're looking for that are going to be very close to pixel-perfect because we are documenting everything for the AI to never hallucinate, make up things. It's going to pull exactly the work that all of your design team and your product team has done in the past. So, to recap, we took the standard design.md and we pushed it deeper so it can hold the complexity of a real product, right? So, we made sure that all of the components were pointing to the metadata and everything that it needs to make sure that it is building in the best way possible for your product. And a little

15:41bonus, my team and I, we pulled together some of the tools that we use every day to build these agentic design systems to design and code to move faster. And there's a link in the description if you want to see everything that we have, it's free. And if you like this video, please like and subscribe. I put content out weekly to help product teams get better with AI. I'll see you in the next

16:00one.