Design System
Document tokens, components, patterns and rules as a site people can browse.
A Design System is a browsable site for one product's interface: its brand, design tokens, components, page patterns and writing rules. You write each page in Magpie, and the site is kept to Personal or your team until you share it by its address or publicly.
Get started freeSections and pages
A new Design System opens private, with sections for the brand, foundations, components, patterns, page archetypes, content, accessibility, guides, implementation notes, assistant rules and developer files. Rename, reorder or hide a section, and add sections of your own for pages you write in Markdown.
Adding a token, component, pattern or rule asks only for its name; the rest is filled in on its page. Click a name, description or value to change it, and the change saves at once. The system's page lists recent changes, such as a token's value changing from one value to another, and a version label you set is shown on the shared overview.
Any account can create a Design System, in Personal or a team, and a team can have several. Members of the owning team can view its systems, and edit them when the team's permissions allow it.
Design tokens
Foundations hold design tokens: named values such as colors, sizes and fonts, usually written as CSS variables in code. They are grouped as color, typography, spacing, sizing, radius, border, shadow, layout, breakpoints, motion and icons.
- Name and value
- A token has a name such as color.text.primary, a value such as #181817 or 16px, and optional guidance on when to use it.
- References
- A value can be another token in braces, such as {gray.900}. The page shows the value it resolves to.
- Theme values
- A color can have a value for each theme, such as light and dark.
- Drawn from the value
- A color is shown as a swatch, a spacing token as a bar of that length and a type style as text in that style. A breakpoint has a field for what changes at that width.
- Copy
- On the shared site, each token copies as its value, its token name or its CSS variable.
Components
A component page can hold a description, usage, variants, states, properties, anatomy, sizing, accessibility notes, do and don't lists, code samples and the places the application uses it. Properties are described without naming a framework.
- Implementation
- 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."
- Draft, Stable or Deprecated
- A deprecated component names the component that replaces it in Replaced by.
- Preview
- HTML with inline CSS, shown in a frame that runs no scripts and loads nothing from the network. Screenshots cannot be uploaded to a Design System.
- Examples in the application
- The source files and routes where the component is used.
Patterns, page archetypes and rules
- Patterns
- When to use one, when not to, what to use instead, how it is structured, how editing works, what happens on mobile, which components it uses, which implementation to reuse and the common mistakes.
- Page archetypes
- A page type the product repeats, such as a settings page or a record page: its layout, navigation, header, actions, anatomy, components, responsive behavior and rules.
- Content rules
- Voice, terminology, labels, errors and dates. A terminology rule has a preferred and an avoided wording.
- Accessibility rules
- Rules that apply across the product.
- Assistant rules
- Instructions for coding assistants, each with a scope and a priority of Normal, Important or Critical.
- Links between pages
- In any Markdown field, {space.4} shows that token's current value and name, and <Button> links to the component, pattern or page archetype with that name.
Sharing the site
A Design System is Private, Unlisted or Public. A private system opens only for 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, and public systems can be indexed.
- Shared sections
- A shared system shows approved content in the sections marked Shared. Hidden takes a section out of browsing for everyone, the team included.
- Implementation and Assistant rules
- Both start unshared, because they name source files and internal practice. Source paths are removed from shared pages unless Implementation is shared.
- Preview shared view
- Shows a member exactly what someone outside the team will see.
- Search
- Ctrl+K or Cmd+K on a shared page searches names, descriptions, rules, brand content and, when they are shared, source paths.
- The Brand section
- The brand has its own sharing setting and its own address.
Document your first Design System.
Create a Magpie account, open Design System and enter a name, or import a system from a codebase.