Design System

Generate a Design System from an existing codebase, then review what it found.

Magpie gives you a prompt to run with a coding assistant in your repository. The coding assistant reads the stylesheets, templates, components and documentation and writes one file describing the interface as it is built. You will see what the file contains before anything is created, and conventions the coding assistant only inferred will wait for your approval.

Get started free

From a repository to a Design System

  1. Copy the prompt

    Create Design System links to Import from a file or a codebase, where Copy the prompt copies the instructions and the file format. The prompt is written for any coding assistant. Download the schema gives the format as a JSON Schema.

  2. Run it in the repository

    The prompt asks the coding assistant to record what the code already does, not to redesign it. It needs no screenshots and does not run the application.

  3. Upload or paste the answer

    The file can be JSON or Markdown, up to 5 MB, named .json, .md, .markdown or .txt. A pasted answer can include text around the JSON.

  4. See what it contains

    The review page counts each kind of content, with a sentence saying what each kind is, and says what will happen when you create the system. Nothing is created until you create it, and the import can be discarded instead.

What the prompt asks for

The coding assistant is asked to read AGENTS.md, CLAUDE.md, README, style guide and contributing files, and to take only their instructions about the interface: design, layout, components, content, accessibility and how a coding assistant should build interface.

Tokens
:root custom properties, SCSS variables, Tailwind configuration, theme objects and token JSON files, with values copied as written and other themes' values recorded beside them.
Components
Only components the repository reuses, each with its source file, stylesheet, variants, states, how many pages use it and examples in the application.
Patterns and page archetypes
Conventions compared across several real pages, such as list pages, settings pages and creation flows.
Brand
The few colors a designer would put on a brand sheet, and the typography.
Only what the code shows
The coding assistant is told to leave out anything the repository does not show, instead of adding general best practice.
Markdown instead of JSON
For an assistant that cannot write JSON, Use Markdown instead of JSON shows the DESIGN_SYSTEM.md format. Anything in it that Magpie does not recognise is kept as a page.

Stated in the code, or inferred

The coding assistant marks everything it records with where it came from, and its source as a file and line, such as assets/css/forms.css:81. That mark decides what happens on import.

Stated in the code
A defined token, a documented rule or a component's source file. It is added to the system as approved.
Inferred from repeated code
A convention repeated across several files but not written down. It waits under Needs review, and stays out of the shared system and exports until someone approves it.
Seen in a few places
A convention with weaker evidence, such as a pattern seen on one page. It also waits under Needs review.
Brand
Brand colors and typography from an import are added hidden from the shared Brand page. Logo files cannot come from the file; add them on the Brand page.

Needs review

Needs review lists the inferred conventions with their source references, and a badge on each says where it came from.

Approve
Adds it to the system as documented. Approve all approves everything waiting.
Reject
Keeps it out, and the decision is kept so that a later import does not add it again.
Mark tentative
Keeps it in the list and records that the evidence is weaker.
Restore for review
Rejected and dismissed content is listed under Rejected, and can be put back in Needs review.

Inconsistencies

Where the code does one thing in different ways, the coding assistant does not choose. It records an inconsistency, such as button heights of 40px in 27 places, 36px in 4 places and 32px in 3 legacy places, with a sentence saying what you are choosing between.

Its review shows a table of the values found: each value, where it is used, how many places use it and the source file, with a sample beside a color. Choose one of the values or type another, then select Use this value. If the inconsistency names a token, that token will take the value; otherwise a rule for coding assistants stating the value will be added. A reason is optional and is kept with the decision.

Dismiss changes nothing in the system, and a later import will not add that inconsistency again.

Import again after the code changes

Run the prompt again and choose Import on the existing system. What the system does not have will be added. What differs is listed beside the current version and changes only when you select Replace, and what you rejected stays out.

A DESIGN_SYSTEM.md or design-system.json exported from Magpie can be imported the same way.

Document the codebase you already have.

Create a Magpie account, open Design System and choose Import from a file or a codebase.

Create account