Import a design system

Many projects now come with their design written down in a Markdown file: a DESIGN.md an AI tool made, a style guide, the brand’s rules. midcode reads that file and writes what it holds into your project’s theme: its colors, its fonts, its text styles, its text sizes, radii, shadows and named spacings. You see all of it before anything is written, and the whole import is one edit.

Use it on a project you already have, or to begin a new one. It works the other way too: a theme made or changed in midcode can be exported as a DESIGN.md.

Import into a project

1. 1

   Open the Assets tab of the left panel. On the right of “Styles”, click the button “Import a design system (Markdown)”.

2. 2

   Choose where the file comes from:

   • –

     a Markdown file of the project that reads as a design system (DESIGN.md, docs/style-guide.md…), listed by its path,

   • –

     “Choose a Markdown file…”, for a file anywhere on your Mac,

   • –

     “Paste from the clipboard”, when you copied it out of a chat.

3. 3

   midcode shows what the file holds, each thing drawn as what it is: colors as swatches, fonts and text styles set in themselves, radii as corners, shadows cast. Click one to leave it out. The box at the right of a group takes all of it in or out.

4. 4

   Click “Import 19” (the number is how many you kept).

In the list:

• –

  A dimmed item is already in the project with the same value. Nothing is written for it.

• –

  An amber dot means the project has it with another value. Hover it to see what it changes from. A color shows the old value on the left half of its swatch.

• –

  A font nothing in your code loads yet says where its files will come from: “From this Mac”, “Google Fonts”, or “Not loaded” when it’s in neither. See Fonts.

• –

  “4 not imported” opens the list of what the file defines that midcode doesn’t write, each with the reason.

• –

  The row with the robot lists the sections of the file that aren’t tokens (Components, Do’s and Don’ts). They stay in the file, for your agent.

“Keep as DESIGN.md” writes the file at the root of the project, where coding agents look for it. It’s offered when the file came from outside the project and there’s no DESIGN.md there yet.

⌘Z undoes the whole import, the DESIGN.md and the fonts’ rules included, and Publish lists it as “Import design system Heritage”.

Start a new project from one

1. 1

   On the hub, click “New project” and choose the technology and the starter as usual. See New project.

2. 2

   Under “Design system”, click “Choose a Markdown file…” and pick the file. The field shows the system’s name and how many colors, fonts, text styles and so on it holds.

3. 3

   Click “Create project”.

The project is made by its framework’s own tool, then its theme gets the tokens, its fonts are loaded the same way an import loads them, and the file is kept at its root as DESIGN.md. It works with every starter except the Shopify themes.

What midcode reads

The file is read, never run. midcode understands the ways these files are usually written:

A heading says what its section holds (Colors, Typography, Radius, Shadows, Spacing). Sections about components, do’s and don’ts, responsive behavior or prompts are skipped whatever is in them.

What each thing becomes:

Names are written as Tailwind writes them: On Surface and onSurface both become on-surface. A font given as a single family gets the fallbacks of what it is: "Space Grotesk", ui-sans-serif, system-ui, sans-serif. A text style called like a Tailwind utility (overline, uppercase) gets type- in front.

What midcode writes

With Tailwind 4, into the stylesheet that has your @theme block. A variable goes after the last one of its kind, a text style after your last text style:

 @theme inline {   --color-background: var(--background);   --color-foreground: var(--foreground);+  --color-primary: #1A1C1E;+  --color-tertiary: #B8422E;-  --font-sans: var(--font-geist-sans);+  --font-sans: "Public Sans", ui-sans-serif, system-ui, sans-serif;+  --font-display: "Playfair Display", ui-serif, Georgia, serif;+  --radius-sm: 4px;+  --radius-md: 8px;+  --spacing-gutter: 24px; }++.headline-lg {+  font-family: var(--font-display);+  font-size: 2.5rem;+  font-weight: 600;+  line-height: 1.1;+}

A stylesheet with @import "tailwindcss" and no @theme block gets one, right after its imports.

Without Tailwind, into .midcode/theme.css, where a text style is a utility and points at its font through --theme():

@theme {
  --color-primary: #1A1C1E;
  --font-display: "Playfair Display", ui-serif, Georgia, serif;
  --radius-md: 8px;
}

@utility headline-lg {
  font-family: --theme(--font-display);
  font-size: 2.5rem;
  font-weight: 600;
  line-height: 1.1;
}

There the import comes after midcode’s own setup when the project didn’t have it yet (midcode.css and its import), which is a step of its own in the history.

After the import, everything is in the Styles of the Assets tab and in the right panel’s lists: a color under “Project colors”, a text style in the Style row of Typography, a text size in the Size list.

Fonts

A theme names a font; the site still has to load its files, or visitors see the next family of the stack. When nothing in your code loads a font the import brings (no @font-face rule, no next/font, no link to a font service, no Fontsource package), midcode loads it for you:

The files go into the folder your site serves as it is, under fonts/, and one @font-face rule per file goes into the stylesheet the theme is in:

@import "tailwindcss";

@font-face {
  font-family: "Space Grotesk";
  font-style: normal;
  font-weight: 400 700;
  font-display: swap;
  src: url("/fonts/space-grotesk-latin-400-700.woff2") format("woff2");
  unicode-range: U+0000-00FF, U+0131, U+0152-0153;
}

@theme {
  --font-sans: "Space Grotesk", ui-sans-serif, system-ui, sans-serif;
}

Which files: the weights your text styles use, plus regular and bold, each upright and in italic when the family has one. A variable font is one file for all its weights (and one more for its italic). From Google Fonts, the Latin and Latin Extended files.

To load a font later, open Fonts in the Styles of the Assets tab. A font the site doesn’t load has an amber download button on its row: click it, and midcode looks on this Mac, then on Google Fonts. It’s one edit, like the import. When the font is in neither place, the message has “Ask the agent”.

Export the theme as Markdown

On the right of “Styles”, beside the import button, “Export the design system (Markdown)” writes the project’s theme as a DESIGN.md:

• –

  “Save as DESIGN.md” writes it at the project’s root. When the project already has one, the item reads “Update DESIGN.md”.

• –

  “Save to a file…” saves it anywhere on your Mac.

• –

  “Copy as Markdown” puts it on the clipboard.

The file has the tokens in its front matter, the way Google’s DESIGN.md format writes them, and the whole theme as CSS under “Tokens in code”, because fonts, text sizes and shadows have no place in that front matter:

---
version: alpha
name: my-site
colors:
  primary: "#1A1C1E"
typography:
  headline-lg:
    fontFamily: Playfair Display
    fontSize: 2.5rem
    fontWeight: 600
    lineHeight: 1.1
rounded:
  md: 8px
---

# my-site

## Tokens in code

```css
@theme {
  --color-primary: #1A1C1E;
  --font-display: "Playfair Display", ui-serif, Georgia, serif;
  --radius-md: 8px;
}

.headline-lg {
  font-family: var(--font-display);
  font-size: 2.5rem;
  font-weight: 600;
  line-height: 1.1;
}
```

Importing that file again finds nothing to do: what goes out reads back as what’s in the theme.

“Update DESIGN.md” keeps the file you have and brings it up to date:

• –

  Its words stay: the overview, the components, the do’s and don’ts, and whatever else its front matter says (description, components).

• –

  A token the theme changed takes its new value. Where the words quote a color that changed (#B8422E), they quote the new one.

• –

  A token the theme gained is added.

• –

  A token the file has and the theme never had stays (a spacing called sm, a color you left out of the import).

• –

  A token the theme had at the last export and has no more is taken out of the front matter.

• –

  “Tokens in code” is written again, or added at the end.

Saving into the project is one edit: ⌘Z takes it back and Publish lists it (“Export the design system”, “Update DESIGN.md”).

Hand it to your agent

The message “19 styles imported · 2 fonts loaded” has the button “Ask the agent to use it”. It puts a note in the agent’s prompt, for you to read and send: where the tokens are, how each kind is written as a class in this project, where the rest of the system is (DESIGN.md), and which fonts are still not loaded. The pages and components built with the system are the agent’s work, or yours on the canvas.

Limits

• –

  midcode reads the file with rules, not with an AI: a value it can’t recognise as a color, a length, a font or a shadow isn’t imported. Check the list before importing.

• –

  A spacing called xs, sm, md… isn’t written: Tailwind reads --spacing-sm before its own widths, so max-w-sm would become that many pixels. A spacing called 1, 2, 4… is already a step of Tailwind’s scale, and a “base unit” isn’t a token. They’re listed under “not imported”.

• –

  Components (a button’s colors, a card’s padding) aren’t built: they stay in the file as guidance.

• –

  Breakpoints, motion, z-index and opacity scales aren’t read.

• –

  Dark colors come in as separate tokens (--color-background-dark). midcode doesn’t set up a dark theme with them.

• –

  Gradients aren’t colors, and aren’t imported.

• –

  A file bigger than 1 MB is refused.

• –

  Fonts: a font inside a collection (.ttc) isn’t read. The .woff2 midcode makes from a font on your Mac leaves its outlines as they are, so it’s a little bigger than one a dedicated tool (or Google) makes. Undoing the edit takes the rules out; the files stay in fonts/.

• –

  The fonts’ url() is the address the folder is served at (/fonts/…). A site published under a sub-path has to adjust it.

• –

  Export: link styles go out as CSS rules, and aren’t read back by an import. Removing a token doesn’t take the sentences about it out of the file’s words.

• –

  “Paste from the clipboard” and “Copy as Markdown” haven’t been tried beyond the text they handle; the rest was tried with Next.js, Vite + React and plain HTML, and the fonts with files from a Mac and from Google Fonts.