Document a Design System

You can view the Design Systems of a team you belong to and edit them when that team's resource permissions allow it.

A Design System belongs to Personal or a team, and a team can have several. Each one has a Brand section, which is a Brand Kit, and sections for foundations, components, patterns, page archetypes, content rules, accessibility rules, guides, implementation notes and assistant rules.

Create a Design System

Choose Personal or a team, open Design System and select Create Design System. Enter a name. The system opens private, with its Brand section ready for a logo, colors and typography.

The same drawer links to Import from a file or a codebase, for a Design System file you already have or one a coding assistant writes. See Import from a codebase below.

Click a name, description or value to change it. Changes save immediately. Adding an item asks only for its name; the rest is filled in on its page.

Sections

The system's page lists its sections. Click a title to rename it. Shared controls whether the section appears when the system is shared. Hidden removes it from browsing for everyone. Drag Move, or use Move up and Move down, to reorder sections. Add section creates a section for pages you write.

Implementation and Assistant rules start unshared, because they name source files and internal practice.

Foundations

Foundations hold tokens in these categories: color, typography, spacing, sizing, radius, border, shadow, layout, breakpoints, motion and icons. A token has a name such as color.text.primary, a value such as #181817 or 16px, and optional usage guidance. A value can be another token in braces, such as {gray.900}; the page shows the resolved value. A color can have values per theme.

Each token is drawn from its value: a color as a swatch, spacing as a bar of that length, a type style as text in that style. Copy actions on the shared page copy the value, the token name or the CSS variable.

A breakpoint has a behavior field for what changes at that width.

In any Markdown field, {space.4} shows the token's current value and name, and <Button> links to the component, pattern or page archetype with that name. Text inside code is left as written.

Components

A component page can hold a description, usage, variants, states, properties, anatomy, sizing, accessibility, do and don't lists, code samples and examples in the application. Properties are described without a framework.

Implementation records the source file, the styles file, whether the component exists or is proposed, and an instruction such as "Use the existing component. Do not create local styles for it." Exports repeat this instruction.

A component is Draft, Stable or Deprecated. A deprecated component names what replaces it in Replaced by.

Preview takes HTML with inline CSS and shows it in a frame that runs no scripts and loads nothing from the network. Screenshots cannot be uploaded to a Design System.

Patterns and page archetypes

A pattern answers when to use it, when not to, what to use instead, how it is structured, how editing works, what happens on mobile, which components it uses, which existing implementation to reuse and what mistakes are common. A page archetype describes a recurring page type: layout, navigation, header, actions, anatomy, components, responsive behavior and rules. Both can list examples as source files and routes.

Rules

Content rules cover voice, terminology, labels, errors and dates. A terminology rule has a preferred and an avoided wording. Accessibility rules apply across the product. Assistant rules are instructions for coding assistants, with a scope (global, component, pattern or platform) and a priority of Normal, Important or Critical. Critical rules come first in assistant context.

Import from a codebase

1. Open Create Design System, then Import from a file or a codebase. Under Generate from an existing codebase, select Copy the prompt. The prompt includes the file format.
2. Run it with your coding assistant from the project's repository.
3. Upload the file the assistant writes, or paste its answer.

The file can be JSON or Markdown, up to 5 MB. An accepted name is .json, .md, .markdown or .txt. A pasted answer can include text around the JSON. Download the schema gives the format as a JSON Schema. Use Markdown instead of JSON shows the DESIGN_SYSTEM.md format, for an assistant that cannot write JSON.

Before anything is created, the review page shows what the file contains, with a sentence saying what each kind of item is, and what happens when you create the system. Nothing on that page needs a decision. Items the file marks as stated in the code or its documentation are added as approved. Items it marks as inferred from repeated code are listed under Needs review and stay out of the shared system and exports until approved. Places where the code disagrees with itself are imported as inconsistencies and also wait under Needs review.

Brand items from an import are added hidden from the shared Brand page. Logo files cannot come from a file; add them on the Brand page.

To compare a new scan with an existing system, open the system and select Import. Items the system does not have are added. Items that differ are listed side by side and change only when you select Replace.

Review

Needs review lists inferred items with their source references. Each item carries a badge saying where it came from: Inferred from repeated code or Seen in a few places. Approve adds an item to the system as documented. Reject keeps it out and remembers the decision so a later import does not add it again. Mark tentative keeps it in the list and records weaker evidence. Approve all approves every inferred item.

An inconsistency shows a table of the values found in the code: each value, where it is used, how many places use it and the source file. A value that is a colour has a sample beside it. Choose one of the values from the list, or choose Another value… and type it, then select Use this value. If the inconsistency names a token, that token's value is set to the value you chose. Otherwise a rule for coding assistants stating the value is added. A reason is optional; it is kept with the decision and becomes the details of the rule when one is added. Dismiss changes nothing in the system: the inconsistency moves to the Rejected list, and a later import will not add it again.

Share

The system's Visibility is Private, Unlisted or Public. A private system can be opened only by members of the owning team. Anyone with the address can open an unlisted or public system, without signing in. Search engines are asked not to index unlisted systems; public systems can be indexed.

A shared system shows approved items in sections marked Shared. Source paths are removed from pages unless Implementation is shared. The shared address on the system's page copies when you click it. Preview shared view shows a member exactly that. The Brand section has its own sharing setting on the Brand page, under Share Brand Kit; its address keeps working. A Brand Kit made before Design System was added is now the Brand section of a private Design System with the same name, and its address /brand-kits opens Design System.

Press Ctrl+K or Cmd+K on a shared page to search names, descriptions, rules, brand items and, when shared, source paths.

Export

Export produces:

• DESIGN_SYSTEM.md, Markdown for coding assistants, at Compact, Standard or Complete detail, for the whole system, foundations, selected components or selected patterns, with an optional line saying what you are building;
• design-system.json, the complete system in the Magpie Design System format;
• tokens.json in the W3C Design Tokens format, and tokens.css;
• a ZIP of these files and the downloadable Brand files.

Exports contain approved items only. Copy context copies the Markdown instead of downloading it. The export page also gives a section to paste into AGENTS.md or CLAUDE.md; Magpie does not edit those files.

When the system is shared and its For developers section is shared, the Markdown is available at /design-system/<address>/assistant.md.

History

The system page lists recent changes, such as a token's value changing from one value to another, items added or removed, reviews and imports.

If a Design System or file cannot be opened, check the selected team and its sharing controls, then Contact support.