# How to use Library

A guide to using Library to bring design context into your team and your AI tools.

## Overview

### What is Library?

Library is where your design system lives. Document your components, tokens, and patterns in one place, publish them to a public URL, and let your AI editor read from the same source.

## Getting started

### Organisations & workspaces

Library is organised in three levels:

- **Organisation** — your team or company account. Members and billing live here.
- **Workspace** — a self-contained design system. An organisation can have many; teams usually create one per product or brand.
- **Folders & pages** — the documentation tree inside a workspace.

Each workspace has its own settings, members, Figma imports, API keys, and published URL. Switch between them with the workspace picker in the top-left corner.

### Folders and pages

Workspaces are made of folders and pages. Folders group; pages hold the content. A typical setup:

```
Foundations/
  Colours
  Typography
  Spacing
Components/
  Button
  Input
  Modal
Patterns/
  Empty states
  Forms
```

## Document

### Document your design system

Two ways: by hand, or with an AI agent.

#### Manually, by hand

Bring your Figma libraries in, then write the pages yourself.

**Styles and components**
1. Open Integrations in the sidebar.
2. Click Add Figma library → Styles and components.
3. Connect Figma when asked (once per account), then paste the file URL.

**Variables**
Variables come in through the Library plugin for Figma. Install it, log in with your Library credentials, open your file, choose what to push, and click Push to Library.

**On a page**
Type `/figma` and pick a variable, style, or component to embed. The block stays linked to the source. Add your own copy around it.

#### Automatically, with an AI agent

Connect Library to your editor and have the agent draft pages from a Figma file — variants, props, anatomy. You review.

In Claude Code, paste your workspace and token into the command, then copy and run it:

```
claude mcp add library-guide \
  --transport sse \
  https://mcp.library.guide/<your-workspace> \
  --header "Authorization: Bearer <your-token>"
```

**Where to get them:**
- **Workspace** — your workspace slug. Find it in Workspace settings.
- **Token** — create one in Workspace settings → API keys with Allow document writes enabled. Copy it before closing the dialog. Anyone with it can edit your workspace through an agent — keep it private.

Run `/mcp` in Claude Code to confirm. Then point it at a Figma file with a prompt like:

> Read the Figma file at https://figma.com/file/… and for every component on the page, create a page under the Components folder in Library. Include a description, variants, anatomy, and usage guidelines. Embed the component with a Figma block at the top.

### Slash commands

Type `/` in a page to open the menu. Three groups:

- **Format** — headings, lists, blockquote.
- **Insert** — tables, columns, code, dividers, embeds.
- **Library Blocks** — Figma, Storybook.

Filter by typing — `/h2`, `/figma`, `/table`.

## Publish

Every workspace gets its own URL — `your-workspace.preview.guide`. There's nothing to deploy: every change you make is live the moment you save it.

**What gets published**

The published site is a read-only view of your workspace. Visitors see the same pages, folders, and Figma blocks your team writes — no editor controls, no workspace-internal links.

Each page also gets an AI chat sidebar. Visitors can ask questions in plain language and get answers grounded in your design system, without leaving the page.

**Visibility**

Set this in Workspace settings:
- **Public** — anyone with the link can view.
- **Private** — only workspace members can view, after signing in.

**Custom domain (Coming soon)**

When you're ready, point your own domain at Library and the published site moves over — for example `design.your-company.com`. The `.preview.guide` URL keeps working as a fallback.

## Build with Library

### MCPs

Library exposes your workspace as an MCP server, so any MCP-capable editor — Claude Code, Cursor, Windsurf, v0 — can read it and, with permission, write back to it. Same URL, same token, every editor.

**Install**

In Workspace settings → Integrations → Library MCP, pick your editor for the exact command. The Claude Code one looks like this:

```
claude mcp add library-guide --transport sse https://mcp.library.guide/<your-workspace>
```

In Cursor and Windsurf, add a new MCP server in settings pointing at the same URL with SSE transport. Any other editor that speaks MCP works the same way.

**Reads vs. writes**

Public workspaces are read by default. No API key needed — the agent can navigate folders, search pages, and read content as soon as it's connected. Private workspaces always require a key.

To let the agent write back to pages — append updates, draft docs from a Figma file — create a key in Workspace settings → API keys with Allow document writes, then add an Authorization header to the install:

```
--header "Authorization: Bearer <your-token>"
```

**What the MCP exposes**

Read tools (no key required for public workspaces):
- `api.getWorkspace()` — explore your design system: folders, pages, and how things are organised.
- `api.listDocuments()` — search and browse pages — component docs, guidelines, token references.
- `api.readDocument(id)` — read the full content of a page: usage guidelines, component specs, token definitions.

Write tool (requires a key with document writes):
- `write_design_context` — append approved updates to a page.

**Verify**

Run `/mcp` in Claude Code, or open the MCP panel in your editor.

### Set the rules

Once Library is connected, the agent can read your tokens, components, and patterns while it writes product code — but you have to tell it to. Add a rule to your project (`CLAUDE.md` for Claude Code, `.cursorrules` for Cursor):

> Before writing or modifying UI code, query the Library MCP for the relevant tokens, components, and patterns.
>
> Use Library tokens for color, spacing, typography, radii, and shadows — never hardcoded values. Use existing Library components by reference; don't recreate them in-line.
>
> If you can't find a matching token or component, surface that to me before adding a one-off.

The same rules work for human teammates: open the published site or the AI chat sidebar to look up the right token before pasting hex codes.

### Lint against the system

When something does drift, the agent can audit a file against Library directly. Paste a file, ask for a report:

> Audit the file I'm about to share against our Library design system.
>
> 1. List every hardcoded value — color, spacing, font size, radius, shadow — that should be a Library token. For each, suggest the correct token name.
> 2. List any custom UI that should be replaced with an existing Library component (Button, Input, Modal, etc.). Quote the lines.
> 3. List anything that doesn't have a match in Library, so I can decide whether to add it.
>
> Return the findings as a short markdown checklist.

### Catch drift in CI

The same audit can run automatically on every change. Wire it into a pre-commit hook or a CI step that pipes the diff through your editor of choice with the prompt above — fail the build if anything new lands without a matching Library token or component.

**The net effect:** Design and code stop drifting. Whether it's an agent or a human writing the code, every change is measured against the same source of truth.