Vercel's design system specification is truly a textbook-level example of what I've seen.
Today, I seriously studied their DESIGN.md. With both light and dark themes, it completely describes colors, fonts, spacing, components, motion, and copywriting rules into an executable design methodology.
I feel like I can follow this path for the design.md of all my future products.
Details are here:
Some friends might not be clear on what DESIGN.md is. Simply put, it's a design specification for AI to read. When AI helps us write code, it needs to know what colors to use, what font sizes to apply, and the spacing between elements.
Without this file, the interfaces AI produces look different every time, with an inconsistent style.
After reading Vercel's DESIGN.md, I realized that a good DESIGN.md is far more than just telling the AI which hex codes or font sizes to use. It represents a whole set of design thinking. It quite subverted my perception.
Today, I'll break down why this file is so good.
1
First, let's talk about color.
When I first started writing DESIGN.md, the color section was actually very simple. I'd list a few color values, tell the AI which was the primary, secondary, and accent color, and that was basically it.
But writing it this way, the AI still doesn't know how these colors correspond to different interaction states.
For example, for a button, what color should the default state be? How much darker should it get on hover? What color should it be the moment it's clicked? If these details aren't explicitly defined, the results generated by AI may differ every time.
Vercel's approach completely solves this problem.
In their design system, each color series is broken down into 10 gradients from 100 to 1000, and each number corresponds to a fixed interface state.
100 is the default background for elements, 200 is the background on hover, and 300 is the background on click. Moving up, 400 is the default border, 500 is the hover border, and 600 is the click border.
700 is used for solid color blocks, like tags or the button itself; 800 is the hover state for these blocks. 900 is used for secondary text and icons, and 1000 is used for primary text and icons.
It looks like just numerical numbering, but behind it lies a complete interaction logic.
100 to 300 manage background states. 400 to 600 manage border states. 700 and 800 manage solid color block states. 900 and 1000 manage information hierarchy.
In other words, Vercel is actually telling the AI that there are several states here. Color is just the manifestation of these states.
The benefits of this are very direct.
When AI writes code, it doesn't need to guess how much darker a button should get on hover, nor does it need to guess how the border should change. The default state corresponds to 100, hover to 200, and click to 300; the rules are pre-defined.
Additionally, on this basis, Vercel provides both light and dark themes but uses the exact same Token names.
For example, gray-1000. In the light theme, it's #171717, close to pure black. In the dark theme, it becomes #ededed, close to pure white.
For a design system, these two colors are actually the same thing.
They both represent the most important information on the page. Developers and AI, when generating interfaces, focus on the semantic meaning of gray-1000 rather than the specific hex value behind it. When the theme switches, the system automatically maps this semantic meaning to the corresponding color.
2
After solving the color problem, another more important constraint is the rhythm of the page.
Vercel's spacing system is based on multiples of 4px, providing only 9 values in total: 4, 8, 12, 16, 24, 32, 40, 64, 96. All spacing in the entire product is chosen from these numbers.
My first reaction was that it seemed a bit limited. What if I need 20px? What if I need 28px?
I asked a designer friend, and he said that for the vast majority of products, 9 spacing styles are basically enough.
If there are too many spacing choices, the rhythm of the page is lost. Many terrible websites have very haphazard spacing designs. This is actually a major taboo in product design.
Excellent design systems don't give infinite choices; they actively limit choices.
Vercel directly provides a clear set of rhythm suggestions: keep 8px between elements within a group, 16px between groups, and 32 to 40px between sections. This is indeed defining the breathing rhythm of the page.
Users might not notice these gaps, but they will naturally sense which parts belong to the same whole and where a new content area begins.
Often, a page looks comfortable not because the designer used some advanced technique, but because this rhythm is kept consistent throughout.
Typography follows the same logic.
Vercel's font system is identical to the logic of color and spacing.
All text is categorized into several fixed roles: heading, label, copy, and button.
Under each role, Tokens of different sizes are provided, and each Token has pre-defined font, size, weight, line height, and letter spacing.
Previously, when facing a piece of text, a designer might think about whether to use 14px or 15px and what line height is appropriate.
With a design system, the way of thinking changes. The AI first determines what role this text plays. Is it a heading, body text, or secondary information? Once the role is determined, the corresponding style is also determined.
Moving from a font-size mindset to a role-based mindset. From visual decision-making to semantic decision-making. This is where the true value of a design system lies. Brilliant.
Seeing this, you realize that whether it's spacing or fonts, Vercel is doing the same thing: reducing free play during the execution phase as much as possible, with rules determined in advance, so execution only requires choosing a role.
This is true for designers, for developers, and for AI.
3
Additionally, copywriting is also treated as an important part of Vercel's design specification. This is the part most easily missing from most DESIGN.md files.
Vercel defines these details very specifically.
For example, button copy must be an action plus an object. Like "Deploy Project" or "Delete Member." You can't just write vague words like "Deploy," "OK," or "Delete."
The reason is simple. When seeing "Delete," the user still needs to think about what exactly is being deleted. With an action and an object, the user can immediately form a complete understanding.
Error messages are similar. Vercel's rules are clear. First, tell the user what happened. Then, tell the user what to do next.
For example, if a build fails because the package file exceeds the size limit, the solution is to reduce the size or adjust the limit. After reading three sentences, the user immediately knows where the problem is and what to do next.
Error prompts in many products are "Operation failed, please try again later." The information content of such a prompt is almost zero. The only information the user gets after reading it is that it failed. As for why it failed and what to do next, they still have to guess.
Copywriting specifications in a design system are essentially reducing this guesswork.
Vercel also standardized the notification messages after an operation is completed, which only need to state what change occurred. For example, "Project deleted," not "Project deleted successfully."
Because the fact that the prompt box can pop up already indicates that the operation is complete. The word "successfully" is redundant information.
Next is motion.
This part is particularly interesting because it's exactly the opposite of my intuition. I would think that the more animation, the more refined the product.
So, adding a little animation to a button hover or a menu popup seems to make it look high-end. Many Vibe Coding products now seem to be heading in this direction.
But Vercel's attitude is completely different. They even explicitly wrote that in many interaction scenarios, 0 milliseconds is often the best choice. In other words, no animation, completed instantly.
If a button changes from a default state to a hover state, this change is already clear enough. The best feedback is for it to happen immediately; adding an extra layer of animation will instead make the interface feel sluggish.
Of course, some scenarios do require motion.
For example, a popup suddenly appearing. If there's no transition at all, people won't know where it came from. This is where animation has value.
Vercel even specifies the duration for different scenarios. Normal state changes are about 150 milliseconds, popovers about 200 milliseconds, and modals about 300 milliseconds.
The larger the change, the more reaction time is given. The smaller the change, the more direct the feedback.
The logic behind it is always the same: don't move if you don't have to, and when you must move, keep it fast, light, and restrained.
The last part that left a deep impression on me is accessibility.
To be honest, I rarely paid special attention to this part before. Because most of the time, as long as a product's interface looks good and the functions work, it seems enough. But Vercel wrote this part very seriously.
They require sufficient contrast between text and background. State changes cannot rely solely on color; they must be paired with icons or text descriptions.
All interactive elements must have a clear focus state and cannot be removed for the sake of visual cleanliness.
These rules mean the design system serves everyone, including people with low color sensitivity, those who navigate with a keyboard, and those looking at their phones in bright light.
This DESIGN.md is too professional. I think when everyone makes new products in the future, they can write their own DESIGN.md based on the ideas of these two MD files.
