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

# Use a design system in a project

> Link a design system so a project builds with its components and theme.

Linking a design system puts its components and theme into your project, so the agent builds new screens from them. A project links one design system at a time.

## Link a design system

1. Open **Project settings** (the settings button next to the project name) and go to **Design System**.
2. Find the design system under **Organization Design Systems** (released from your organization's projects) or **Public Design Systems** (available to every project).
3. Click **Link Design**. The project gets the design system's newest release.

Only released design systems are listed. If there are none, the tab says **No released design systems found**. See [Release a design system](https://docs.polymet.ai/design-systems/release.md).

You can also link one when you start a project: on the projects page, pick it in the design system menu of the generation input before you send your first prompt.

## What changes when you link

* The design system's components are copied into the project, and your code imports them from its import path.
* The project uses the design system's theme. **Project settings** > **Theming** is locked and says **Design system's theme is being used by the project. You can update the theme from the design system**.
* Every node on the canvas rebuilds with the new components and theme.

Linking, updating and unlinking apply to the branch you are on. See [Branches](https://docs.polymet.ai/team/branches.md).

## Update to a newer release

When the design system has a newer release, its card shows **New version available**, and the **Design System** tab in Project settings shows a count.

1. Click **New version available**.
2. Polymet replaces the old components with the new release and says **Design system updated successfully**.

Updating always moves to the newest release.

## Unlink

1. In **Linked design system**, open the menu on the design system's card.
2. Click **Unlink**.

**Unlink** is disabled while any file in your project still imports from the design system. Its tooltip says how many, for example **This design system is used in 3 components. Remove these dependencies before unlinking.** Open **Usages** below the card to see which files they are, change them, then unlink. Unlinking also waits for a running generation to finish.

## Limits

* One design system per project. To switch, unlink the current one first.
* The project needs at least one version before it can link (**Project needs to at least have one version to link to a design system**).
* Apart from the ones under **Public Design Systems**, you can only link design systems from your own organization.
* A design system cannot link another design system.

## Related

* [Design systems](https://docs.polymet.ai/design-systems/overview.md) — what a design system is and how to make one
* [Release a design system](https://docs.polymet.ai/design-systems/release.md) — make a new version available to linked projects
* [Themes](https://docs.polymet.ai/canvas/themes.md) — a project's own colors and fonts, when no design system is linked


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