> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vibely.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# Design systems

> Attach a design system to a web project so Vibely builds with a fixed palette, type, component list, and set of design rules.

<Info>
  Creating and attaching design systems requires the **Business** or **Enterprise** plan.
</Info>

A **design system** gives Vibely a fixed set of design decisions to build with: a color palette, fonts, a list of components, and rules such as "use the design-system tokens, never raw color values". When a design system is attached to a project, Vibely applies it on every message, so every page and component follows the same visual language.

<Frame>
  <img src="https://cdn.vibely.sh/doc/v1/design-systems-1.webp" alt="Design systems" width="1200" height="675" />
</Frame>

A design system is a set of rules, not a component library. Attaching one doesn't copy component source code into your project. Vibely follows the system's rules when it writes your components. If you want to share actual code between projects, use a [workspace template](/features/design/workspace-templates) instead.

## Built-in design systems

Vibely includes three design systems that every workspace can use:

| Design system | Look |
| - | - |
| **Editorial Monocle** | Warm paper background, high-contrast serif type, a terracotta accent |
| **Modern Minimal** | White background, Inter, a single blue accent |
| **Warm Craft** | Cream background, a clay accent, Hanken Grotesk |

## How design systems are applied

When a design system is attached to a project, Vibely adds these files to it:

```text theme={"system"}
.vibely/rules/libraries/<system>/design-system.json
.vibely/rules/libraries/<system>/design-tokens.md
.vibely/rules/libraries/<system>/components.md
.vibely/rules/libraries/<system>/library-guidelines.md
src/design-system/<system>/tokens.css
```

`tokens.css` defines the palette and type as CSS variables, and the other files hold the component list and the rules. On every message, Vibely reads the system's key tokens, component names, and rules, and follows them. It uses the system's tokens instead of hard-coded colors, builds from the listed components instead of creating one-off versions, and doesn't bypass the type and spacing scale with inline values.

A project can have one design system at a time. Attaching a different one replaces the first.

<Note>
  Design systems apply to **web projects**. For mobile projects, set the look with [design guidance](/features/design/design-guidance) or with [knowledge](/features/context/knowledge).
</Note>

## Create a design system from a project

A workspace design system is one of your web projects whose `DESIGN.md` describes the system: its palette, fonts, components, and rules.

<Steps>
  <Step title="Open Design systems">
    Go to **Settings → Design systems**.
  </Step>

  <Step title="Pick a project">
    Under **Create a design system**, choose a web project and click **Create**. If the project has no `DESIGN.md`, Vibely adds a starter one with placeholder colors and fonts.
  </Step>

  <Step title="Describe the system">
    Open the project and edit `DESIGN.md` so it describes your real design, or ask the agent to write it from the project's styles.
  </Step>

  <Step title="Release a version">
    Back in **Settings → Design systems**, click **Release version**. Only released design systems can be attached to projects.
  </Step>
</Steps>

## Attach a design system to a project

<Steps>
  <Step title="Open the project's settings">
    In the project, open **Settings**.
  </Step>

  <Step title="Choose a design system">
    Under **Design system**, pick a released workspace design system or a built-in one, then click **Attach**.
  </Step>
</Steps>

Vibely applies it from the next message on. When a newer version of the attached system has been released, the button reads **Update to** that version.

You can also attach a design system when you create a project from an AI tool through the [Vibely MCP server](/integrations/vibely-mcp-server): ask it to list design systems (`list_design_systems`), then create a web project with the one you picked (`create_project`). Vibely attaches it before the first build.

```text wrap theme={"system"}
Create a Vibely web project for a recipe-sharing site using the Warm Craft design system.
```

Projects with a design system attached skip the [design directions](/features/design/design-guidance) step, because the look is already decided.

<Frame>
  <img src="https://cdn.vibely.sh/doc/v1/design-systems-2.webp" alt="Design systems" width="1200" height="675" />
</Frame>

## Manage design systems in your workspace

**Settings → Design systems** has three sections:

* **Create a design system**: turn a web project into a design system.
* **Workspace design systems**: design systems your workspace owns, with their released version. A workspace design system shows **Not released yet** until a version is released, and it can't be attached to a project before then. Click **Release version** to release the next version, **Open** to open its project, or **Remove** to stop using the project as a design system. Removing doesn't change the project or the projects it's already attached to.
* **Built-in design systems**: the three systems that ship with Vibely. They can be attached to any project.

## Updates

Releasing a new version of a workspace design system doesn't change projects it's already attached to. Re-attaching a system rewrites its five files in the project, and only those files. If you edited any of those files by hand, your edits are replaced.

## Key notes and limitations

* **Business plan.** Creating, managing, and attaching design systems need the Business or Enterprise plan.
* **Web projects only.** Design systems are made from web projects and can't be attached to mobile projects.
* **One per project.** Attaching a second system replaces the first. There's no separate detach option.
* **Rules, not components.** The component list tells Vibely which components to build and how. It doesn't ship prebuilt components.

## FAQ

<AccordionGroup>
  <Accordion title="What's the difference between a design system and a workspace template?">
    A design system shares design rules: tokens, a component list, and guidelines. A [workspace template](/features/design/workspace-templates) shares a whole codebase, including real components, pages, and configuration. Use a design system to keep projects visually consistent. Use a template to start projects from the same code.
  </Accordion>

  <Accordion title="Can I use a design system with design directions?">
    No. When a design system is attached, Vibely builds with it and skips design directions. To explore looks first, create the project without a design system.
  </Accordion>

  <Accordion title="Can I bring my own brand colors and fonts without a design system?">
    Yes. Name them in your prompt, or put them in [workspace knowledge](/features/context/knowledge) so every project uses them.
  </Accordion>
</AccordionGroup>

## Related topics

<CardGroup cols={2}>
  <Card title="Design guidance" icon="palette" href="/features/design/design-guidance">
    Pick a look before the first build.
  </Card>

  <Card title="Workspace templates" icon="copy" href="/features/design/workspace-templates">
    Share a whole codebase across projects.
  </Card>

  <Card title="Vibely MCP server" icon="plug" href="/integrations/vibely-mcp-server">
    Create projects from Claude, ChatGPT, and other AI tools.
  </Card>

  <Card title="Knowledge" icon="book" href="/features/context/knowledge">
    Rules Vibely follows on every message.
  </Card>
</CardGroup>


## Related topics

- [Design guidance](/features/design/design-guidance.md)
- [Bring Figma designs into Vibely](/integrations/figma.md)
- [Workspace admin settings](/features/workspace/admin-settings.md)
- [Workspace templates](/features/design/workspace-templates.md)
- [Iterate](/features/web-apps/iterate.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.