What is a DESIGN.md?
A DESIGN.md is a Markdown file that describes a design system in plain language: its colors, fonts, type scale, spacing and effects, and how to use them. It sits in your repository beside the code, where AI coding tools can read it, in the same way a README explains a project to people.
Because it is plain text, it works with any tool that reads your files, and it can be reviewed and edited like any other document.
Why AI-built sites look generic
When an AI coding tool has no design rules, it falls back on defaults: the same fonts, the same spacing, the same rounded cards. A screenshot helps a little, but the tool still has to guess the exact sizes, weights and colors. A DESIGN.md replaces those guesses with measured values and a clear scale to stay within.
What PikSpec’s DESIGN.md contains
PikSpec writes the file from values measured on the rendered page, under these headings:
- Colors: Primary, secondary, accent and neutral colors, plus roles such as background, surface, text, border and action.
- Typography: Body, heading and monospace families, and a type-scale table with each step’s size, line height, weight and letter spacing, marked as observed or partly derived.
- Spacing: The spacing steps, and the base rhythm when one is detected.
- Radius and Shadows: Corner radii and box shadows ordered by elevation.
- Provenance: Which values are measured and which had to be inferred.
- Quality evidence: What supports the result, and warnings where the capture was thin.
Generate a DESIGN.md in Chrome
1. Open a website you are permitted to inspect, open PikSpec from Chrome’s toolbar and choose Grant access & analyse.
2. Review the detected colors and typography in Styles.
3. Open Tokens and generate the token package. DESIGN.md downloads together with tokens.json, tokens.css, a Tailwind v4 theme and tokens.scss, so the brief and the code tokens always match.
Use it with Claude Code, Cursor, v0 and Codex
Save DESIGN.md in your project, then refer to it when you ask for UI work, for example: “Build the pricing section using the colors, type scale and spacing in DESIGN.md.” Tools that read project instructions, such as a CLAUDE.md, AGENTS.md or Cursor rules file, can be told to follow it for every change.
Copying a prompt or downloading the file does not send anything to an external AI tool; you decide what to share. PikSpec works alongside Claude Code, Cursor, v0, Codex, Windsurf and GitHub Copilot and is not affiliated with them.
DESIGN.md and the Design Pack
DESIGN.md is the compact brief for a coding tool. The Design Pack is a self-contained HTML reference of the same capture, with swatches, type specimens, spacing, radius and shadows laid out visually, which is easier for people to review. Use the Design Pack to check the capture and DESIGN.md to build from it.
What a generated DESIGN.md cannot tell you
PikSpec describes how the page rendered, not the original team’s source files or token names. Hover states, breakpoints and fonts that were not captured are not in the file. Review it before relying on it, adapt it to your own product, and only reuse designs you have the right to use.
The free plan includes 3 / month token generations, each producing DESIGN.md and the four token files.
Contact PikSpec
Email support@pikspec.com for support, privacy requests or content reports.