A complete design.md example.
A design.md is a plain markdown file that describes a whole design system, written so that Cursor, Claude Code, v0 and Lovable can build from it directly. If you want the concept first, read what a design.md is. If you want to see one, it is right below, in full, with nothing removed.
This design.md example is the real file Logofai generated for Strike9, a streetwear label. It runs to twelve numbered sections: brand essence, colour tokens for light and dark mode with a usage note per token, a Google Fonts pairing and an eleven-level type scale, an 8-based spacing scale with container widths, radii and four elevation levels, button variants and states, five card patterns, form and focus specifications, voice rules with worked example copy, motion easing and durations, accessibility minimums, logo clear space and minimum sizes, and a closing do and do-not table. Every value is a real number rather than an adjective, which is what lets an AI coding tool apply it without interpreting it. Copy the whole thing below, adapt the values to your own brand, or generate a design.md from a logo in about a minute.
The whole file. Nothing trimmed.
This is unedited output, not a tidied-up illustration. The odd phrasings are the model’s own. Copy it as a starting point and replace the values with yours.
# DESIGN.md — Strike9
## 1. Brand essence
- Loud discipline: high-impact, never sloppy.
- Night-market grit: built for concrete, queues, clubs, and cold sidewalks.
- Sharp confidence: graphic, direct, and cut with intent.
Tagline: Built loud. Cut for the street.
## 2. Colour tokens
### Light mode
```css
:root {
--bg: #FDFDFD;
--surface: #FDFDFD;
--surface-2: #F3F2F2;
--text: #141213;
--text-2: #341124;
--muted: #6E686B;
--border: #E2DFE0;
--primary: #4D0D2E;
--primary-ink: #FDFDFD;
--accent: #660A3A;
--accent-2: #280F1C;
}
```
Usage notes:
- `--bg`: main page background; keep clean to let product and graphics hit harder.
- `--surface`: default card, nav, drawer, and modal fill.
- `--surface-2`: raised panels, table rows, form fills, and soft section breaks.
- `--text`: primary copy and high-priority interface text.
- `--text-2`: subheads, metadata, and editorial text with a brand tint.
- `--muted`: helper copy, timestamps, placeholders, and low-emphasis UI.
- `--border`: dividers, input borders, card outlines, and quiet separators.
- `--primary`: main action colour for CTAs, badges, and key highlights.
- `--primary-ink`: text and icons placed on primary fills.
- `--accent`: drop alerts, campaign moments, sale flags, and energetic highlights.
- `--accent-2`: deep graphic blocks, hover depth, and tonal layering.
### Dark mode
```css
[data-theme='dark'] {
--bg: #141213;
--surface: #280F1C;
--surface-2: #341124;
--text: #FDFDFD;
--text-2: #E2DFE0;
--muted: #A69FA2;
--border: #4D0D2E;
--primary: #660A3A;
--primary-ink: #FDFDFD;
--accent: #4D0D2E;
--accent-2: #341124;
}
```
Usage notes:
- `--bg`: night-mode foundation for lookbooks, drops, and product grids.
- `--surface`: main card and panel colour; keeps the palette rich, not flat black.
- `--surface-2`: deeper stacked panels, accordions, and expanded states.
- `--text`: primary readable type on dark backgrounds.
- `--text-2`: secondary copy and body-supporting information.
- `--muted`: quiet UI copy without losing legibility.
- `--border`: visible separators and control outlines on dark surfaces.
- `--primary`: dominant CTA fill for dark pages.
- `--primary-ink`: CTA text on primary fills.
- `--accent`: secondary highlight, active states, labels, and graphic hits.
- `--accent-2`: subtle dark tonal blocks and background depth.
## 3. Typography
Google Fonts pairing:
- Headings: Archivo Black, weight 400.
- Body: Space Grotesk, weights 400, 500, 600, 700.
Type scale:
| Level | Size / line-height | Family | Weight | Use |
|---|---:|---|---:|---|
| Display | 56 / 1.05 | Archivo Black | 400 | Drop pages, campaign heroes, oversized product statements. |
| H1 | 40 / 1.1 | Archivo Black | 400 | Page titles and collection names. |
| H2 | 30 / 1.15 | Archivo Black | 400 | Section headers and editorial blocks. |
| H3 | 22 / 1.25 | Archivo Black | 400 | Card titles, feature titles, FAQ groups. |
| Lead | 19 / 1.55 | Space Grotesk | 500 | Hero subheads and intro copy. |
| Body | 16 / 1.6 | Space Grotesk | 400 | Product descriptions, articles, support copy. |
| Small | 14 / 1.5 | Space Grotesk | 400 | Helper text, compact UI, card metadata. |
| Caption | 12.5 / 1.4 | Space Grotesk | 500 | Labels, footnotes, legal, shipping notes. |
| Eyebrow | 12 uppercase tracked | Space Grotesk | 700 | Drop tags, category labels, nav markers. Use 0.12em tracking. |
| Button | 15 / 1 | Space Grotesk | 700 | CTAs and commerce controls. |
| Code | 13.5 / 1.45 | ui-monospace | 500 | Order numbers, discount codes, technical snippets. |
## 4. Spacing and layout
Spacing scale is 8-based with one tight exception:
- 4px: micro gaps, icon nudges, focus offset.
- 8px: compact internal spacing.
- 12px: button gaps, form rhythm.
- 16px: default component padding.
- 24px: card padding and section internals.
- 32px: grid gaps and stacked content.
- 48px: small section spacing.
- 64px: standard page-section spacing.
- 96px: hero and campaign spacing.
Layout:
- Max container width: 1120px.
- Page gutter: 16px mobile, 24px tablet, 32px desktop.
- Product grids: 2 columns mobile where possible, 3 tablet, 4 desktop.
- Keep compositions tight, blocky, and asymmetric when campaigns need energy.
Radius scale:
- 6px: inputs, tags, compact controls.
- 10px: buttons and small cards.
- 14px: base brand radius.
- 20px: large cards, banners, modals.
- full: pills, avatars, circular icon buttons.
Elevation:
- Level 1: `0 1px 2px rgba(20, 18, 19, 0.08)` for subtle cards.
- Level 2: `0 8px 20px rgba(20, 18, 19, 0.12)` for dropdowns.
- Level 3: `0 16px 36px rgba(20, 18, 19, 0.18)` for modals and sticky commerce.
- Level 4: `0 24px 64px rgba(20, 18, 19, 0.28)` for campaign overlays.
## 5. Buttons
General:
- Use Space Grotesk 700, 15px / 1, slight letter spacing of 0.01em.
- Radius: 10px default.
- Include icon spacing of 8px.
- Transitions: background, border, color, transform, and box-shadow.
Variants:
- Primary: background `--primary`, text `--primary-ink`, border `--primary`. Use for Buy now, Join the drop, and Checkout.
- Secondary: background `--accent-2`, text `#FDFDFD`, border `--accent-2`. Use for strong secondary commerce actions.
- Outline: transparent background, text `--primary`, border `--primary`. Use for size guides, wishlists, and secondary nav.
- Ghost: transparent background, text `--text`, no border. Use inside navs, tables, and cards.
Sizes:
- Small: 36px height, 12px horizontal padding, 14px type.
- Medium: 44px height, 16px horizontal padding, 15px type.
- Large: 52px height, 22px horizontal padding, 15px type.
States:
- Hover: lift by -1px, deepen fill to `--accent` for primary or add `--surface-2` for ghost.
- Active: return to 0px lift and use a tighter shadow.
- Disabled: 45% opacity, no transform, cursor not-allowed, keep label readable.
- Loading: preserve button width and show a small monochrome spinner.
## 6. Cards
Base card:
- Fill `--surface`, border `1px solid --border`, radius 14px, padding 24px.
- Use Level 1 elevation on light mode; use border-first styling in dark mode.
Feature card:
- Add a bold H3, short body copy, and one graphic mark or icon.
- Use `--surface-2` for quieter features and `--accent-2` for louder campaign moments.
- Keep copy under 18 words where possible.
Pricing card:
- Structure: plan name, price, short promise, feature list, CTA.
- Default card uses `--surface` and `--text`.
- Featured dark variant uses `--accent-2` fill, `#FDFDFD` text, `--accent` badge, and primary CTA.
- Place the featured card slightly higher or wider, not with unrelated colours.
Testimonial / quote card:
- Use large quote text in Space Grotesk 500 or H3 styling.
- Add source name, role, and optional city.
- Use `--surface-2` with a left border in `--accent`.
Promo banner:
- Use `--primary` or `--accent` fill with `--primary-ink` text.
- Keep one message, one CTA, and one proof point.
- Good examples: New drop live, Heavyweight fleece, Free shipping threshold.
## 7. Forms
Labels:
- Space Grotesk 600, 14px, `--text`.
- Place labels above fields with 8px gap.
Inputs, selects, textareas:
- Height: 44px for inputs/selects; textarea minimum 120px.
- Padding: 12px 14px.
- Radius: 6px.
- Background: `--surface` or `--surface-2` for dense areas.
- Border: `1px solid --border`.
- Text: `--text`; placeholder: `--muted`.
Focus:
- Border changes to `--accent`.
- Focus ring: `0 0 0 3px rgba(102, 10, 58, 0.22)`.
- Never remove focus styling for keyboard users.
Error:
- Use `--accent` for error border and message.
- Error message: 14px, Space Grotesk 500, placed 6px below field.
- Keep copy direct: Choose a size before checkout.
## 8. Voice and copy
Writing rules:
- Say it like a drop announcement: short, sharp, high-energy.
- Keep confidence earned: describe fit, fabric, and function without fake hype.
- Use street cues with restraint: night, concrete, queue, block, drop, rotation.
Example headlines:
- Gear Up. Strike After Dark.
- Heavy Fits For Loud Nights.
Example product copy:
- Boxy heavyweight tee with a clean drape and deep berry-black print.
- Built for the queue, the train, and the last stop home.
FAQ:
- When is the next drop? Drops land without filler. Join the list and catch the first signal.
- How does Strike9 fit? Most pieces run boxy with street-ready room. Check each product page for exact measurements.
- Do you restock sold-out pieces? Sometimes. Core colours may return; limited graphics usually stay gone.
- How should I wash it? Cold wash, inside out. Hang dry to keep the print sharp.
## 9. Motion
Easing:
- Standard: `cubic-bezier(0.2, 0, 0, 1)` for most UI movement.
- Punch: `cubic-bezier(0.16, 1, 0.3, 1)` for drawers, banners, and drop reveals.
- Exit: `cubic-bezier(0.7, 0, 0.84, 0)` for dismissals.
Durations:
- 80ms: pressed states and micro feedback.
- 140ms: hover transitions.
- 200ms: menus, accordions, filters.
- 320ms: modals, drawers, image reveals.
- 480ms: campaign hero entrances only.
Motion rules:
- Movement should feel quick and heavy, not floaty.
- Use small vertical shifts: 1–4px for controls, 8–16px for panels.
- Respect reduced-motion preferences with opacity-only transitions.
## 10. Accessibility
- Body text should meet WCAG AA contrast: 4.5:1 minimum.
- Large display text should meet at least 3:1, but aim higher for commerce clarity.
- Do not place muted text over saturated fills unless contrast is verified.
- Interactive targets should be at least 44px tall or wide.
- Focus-visible rule: show a 3px ring using `--accent` or `rgba(102, 10, 58, 0.28)` with 2px offset.
- Never communicate errors, sale status, or selection with colour alone; add text or icons.
## 11. Logo usage
Minimum size:
- Digital: 96px wide for the full logo.
- Small placements: use a simplified mark only if available; never crush the wordmark below legibility.
- Print: 28mm wide minimum.
Clear space:
- Maintain clear space equal to the height of the 9 around all sides of the logo.
- Keep the logo away from busy product photography unless placed on a solid panel.
Do / do not:
- Do use the logo in `#141213`, `#FDFDFD`, `#4D0D2E`, or `#660A3A` depending on contrast.
- Do place the logo on clean light, dark, or tonal berry backgrounds from the palette.
- Do keep proportions locked and edges sharp.
- Do not add new hues, gradients from outside the palette, glows, bevels, or chrome effects.
- Do not stretch, rotate, outline, texture, or place the logo over low-contrast imagery.
- Do not pair the logo with soft lifestyle styling that weakens the loud streetwear stance.
## 12. Final Do / Don’t table
| Do | Don’t |
|---|---|
| Use berry-black saturation for CTAs and campaign moments. | Introduce greens, blues, yellows, or unrelated hype colours. |
| Keep copy short, direct, and drop-ready. | Write soft lifestyle paragraphs with no point of view. |
| Let product photography and type carry the energy. | Overload layouts with effects, stickers, and random graphics. |
| Use strong contrast on every button and form state. | Hide key commerce actions in muted styling. |
| Build layouts with tight grids, bold scale, and clean negative space. | Make everything chaotic just because the vibe is loud. |The brand this file belongs to is documented in the Strike9 case study, so you can compare the written system against the finished identity.
What each section does. And why it is there.
Reading a design.md top to bottom is not very useful. Reading it as five jobs is.
What it holds. Two blocks of CSS variables, one for light mode and one for dark, and a usage note for every single token.
What a tool does with it. The usage notes are the part that matters. A model given only a hex list has to guess where each colour goes, and it guesses badly: brand purple ends up as body text. Written as "--muted: helper copy, timestamps, placeholders", the choice stops being a guess. Note that Strike9 defines --primary-ink separately, so a tool never has to work out what colour text sits on a filled button.
What it holds. A Google Fonts pairing, then an eleven-level scale with exact sizes, line heights, weights and the use case for each.
What a tool does with it. Naming the fonts as Google Fonts is deliberate: the tool can import them without asking. The "Use" column is what stops a model applying Display styling to a card title. Sizes are absolute numbers rather than "large" or "small", because a relative word gets reinterpreted every time the model runs.
What it holds. An 8-based spacing scale, container width, page gutters, grid rules, a radius scale and four elevation levels.
What a tool does with it. Without this, AI output drifts. Every generated component picks its own padding and the page reads as a set of unrelated blocks. A fixed scale means the fifth screen a tool builds still matches the first. The radius scale is the single fastest way to make generated UI look like one product.
What it holds. Buttons, cards and forms, written as variants, sizes and states rather than as prose.
What a tool does with it. This is the longest part of the file and the most valuable. It specifies hover lift, disabled opacity, focus ring colour and loading behaviour. Those states are exactly what AI tools skip when left to improvise, and exactly what makes an interface feel unfinished when they are missing.
What it holds. Writing rules, example headlines, example product copy and answered FAQs in the brand tone.
What a tool does with it. A design system that stops at colour leaves the writing to chance. Examples work far better than adjectives here: "Gear Up. Strike After Dark." teaches a model more about the register than the instruction "be bold" ever will. The worked FAQ answers give it a length and rhythm to imitate.
Five ways it goes wrong. Avoid these.
A palette listed as #4D0D2E, #660A3A, #280F1C tells a tool nothing about where each colour belongs. Name them by role, not by appearance, so --primary survives a rebrand that changes the hue.
If only light mode is defined, a tool asked for a dark interface invents a second palette, usually by inverting values. Contrast breaks and brand colours turn muddy. Define both, even if you only ship one today.
Words like modern, clean and premium describe almost every brand and constrain nothing. Replace them with rules a writer could follow and at least two real examples of finished copy.
Default styling is the easy half. Hover, focus, disabled, error and loading are where generated UI falls apart, and they take three extra lines each to specify.
A design.md that describes last year’s brand is worse than none, because tools follow it confidently. Keep it in the repo next to the code so it changes in the same pull request.
Writing your own. Two routes.
By hand, budget an afternoon. The tokens are quick; the component states and the voice section are what take the time, and they are also the parts that decide whether the file works. Our guide to writing a design.md walks through the sections in order, with the naming conventions that make a model reason about tokens correctly.
Or start from a logo. Logofai reads the mark, extracts the palette, pairs typography and writes all twelve sections, along with a live HTML style guide and developer exports as CSS variables, a Tailwind config and W3C design tokens JSON. It costs 9 credits and takes about a minute. Either way you end up with the same artefact: one file your tools can build from.
Once you have it, point Cursor at it or use it with v0 and Lovable and every screen they generate lands on brand. If you are weighing this against a traditional brand document, design.md versus a style guide covers what each one is actually for.
Want this file for your brand? One click.
Or read how the design system generator builds it.