Starting from a blank canvas is slow, so it's tempting to drop a ready-made style file into a project and let an AI agent run with it. It does get things moving. It also smuggles another product's assumptions into the code before I've worked out what my own product needs.
awesome-design-md helps with the blank page. It's a collection of DESIGN.md files modeled on well-known products and brands, each covering the visual theme, color roles, type, components, layout, depth, responsive behavior and guardrails.
The repo suggests copying a file into your project and asking an agent to build from it. I stop one step short of that. I treat the copied file as research, and use it to write a new design system for the project before the agent implements anything.
The problem with using it as is
A reference DESIGN.md was written for someone else's company, audience, product and content. The font might be proprietary. A dark interface that suits a developer tool can feel wrong in a reading app. Dense controls lifted from an expert dashboard won't help a simple onboarding flow.
Hand that file to an agent unchanged and you hand over all of those assumptions with it. The result can be perfectly consistent and still wrong for the product. Usually it looks like a familiar brand with different words pasted in.
What the collection is good for
It gives me better vocabulary than "make it minimal." I can look at how Linear, Vercel, Notion or Stripe build hierarchy and ask where the character really comes from. Is it the type, the spacing, the color, the borders, the imagery, the interaction?
I almost never take one reference whole. One might help with editorial rhythm, another with dense product controls, and I might look somewhere else entirely for motion. Every reference needs a reason to be there. Mixing a few visual skins for no reason just gets you a muddier skin.
At this stage I'm after a short list of decisions worth trying. I'm not looking for a brand to copy.
Start with the product
Before touching DESIGN.md, I write down what the design has to serve:
- Who uses the product?
- What are they trying to get done?
- Is this a marketing page, an app, documentation, or a visual experience?
- What real content already exists?
- Which devices, accessibility needs and technical limits matter?
- What should the interface never turn into?
This stops the reference from quietly becoming the product strategy. A beautiful dashboard can't tell me whether my product needs a dashboard in the first place.
Borrow decisions, not the skin
The DESIGN.md files in the collection share a useful structure. When I read them, I'm looking for decisions that can move to another project:
- The visual theme and the atmosphere it's going for.
- Semantic color roles, not a pile of hex values.
- Type hierarchy and line length.
- Spacing, grid, density and whitespace.
- How components behave by default, on hover and focus, and when disabled, loading or in an error state.
- How the layout actually changes across screen sizes, as opposed to the desktop version shrunk down.
- Explicit do and don't rules.
A few values might carry over unchanged. Most need translating. "Use purple" doesn't describe a system. "Keep one accent color for the primary action and never use it as decoration" does.
Write a new DESIGN.md for the project
I replace the borrowed file with one written for the actual project. This is the outline I use:
# Design System: [Project]
## Product context
- Primary users
- Main task
- Platform and usage environment
- Content and technical constraints
## Creative north star
A short description of the visual idea and why it fits the product.
## Foundations
### Color
- Semantic roles and accessible values
### Typography
- Families, weights, hierarchy, line height, and reading measure
### Layout and spacing
- Grid, containers, spacing scale, density, and breakpoints
## Components
- Structure, variants, states, and interaction rules
## Motion
- Purpose, duration, easing, interruption, and reduced-motion behavior
## Responsive behavior
- What reflows, collapses, scrolls, or disappears
## Accessibility
- Focus, contrast, keyboard order, touch targets, and semantics
## Code mapping
- CSS variables, framework tokens, and shared component locations
## Do and don't
- Decisions the agent must preserve
- Common patterns that do not belong in this project
The file should name the project's real fonts, tokens, breakpoints, components and code conventions. If the codebase already has a token layer, point DESIGN.md at it. Don't create a second source of truth.
For V2SPACE I didn't write "copy a minimalist portfolio." The system spells out a white, text-first page, IBM Plex Sans at 16px, a structural rail, a narrow reading column, two font weights and quiet hover states. It also bans cards, gradients, shadows and decorative stats. All of that came from what the site is for and what's on it, not from any one reference.
Test one screen before the rest
I try the new DESIGN.md on one representative screen first. It needs enough real content to expose weak rules: a long title, some secondary copy, an action, a few repeated items, an interactive state, and a narrow viewport.
Then I look at what actually rendered. I squint to blur the details and check whether the hierarchy still holds. I check that related things group naturally, long labels wrap, keyboard focus stays visible and touch targets are big enough. On mobile I want the layout to actually reflow, not just shrink.
If that screen doesn't hold up, I fix the system before building anything else. Otherwise the same bad rule ends up on ten pages and I get to fix it ten times.
Give the agent a bounded job
Only then do I ask the agent to build. The request names the target screen, the real content, the existing components, the states it has to handle and how I'll check the result.
DESIGN.md is the visual contract. AGENTS.md explains how to work in the repo. Product requirements say what has to exist. Each one covers something the others don't.
With those boundaries set, the agent can make small decisions on its own without inventing a new visual language for every screen. It also knows enough to turn down a trendy pattern that doesn't fit.
Keep it current
DESIGN.md should change when the project's design decisions change. I don't regenerate it after every screenshot, and I don't treat it as a frozen moodboard either.
It needs enough detail to actually constrain the implementation, but it should stay short enough for a person to read through. If nobody on the project can explain why a rule is there, I don't expect the agent to get it either.
I still use awesome-design-md, because it gets me past the blank page. I just don't treat the file I pick as build instructions. I use it to write the design system the project should have had from the start.