Design System for Agents

Ships in the next chaipro release after v0.4.0. It is part of the MCP server, so set that up first: MCP Server Setup.

An agent in Claude, Cursor or VS Code does not know what your site is supposed to look like. Left to itself it reaches for the looks every AI tool reaches for: gradient headlines, purple-to-blue washes, a small label above every heading, everything in a rounded card. And inside a chat client it cannot install design skills of its own.

The design system puts that discipline in your site's MCP server instead, so every agent that connects gets it:

A written design system per site. The rules that tie your theme and design tokens together: a north star, the visitor the site serves, and eight written sections. The agent drafts it with you in a short interview, and nothing is enforced until you enable it.
Design checks. Deterministic checks that read a page's blocks and name the block and the fix for every problem they find. They run on every block the agent writes, and on demand.
Playbooks. Step-by-step procedures for setup, critique, audit and polish, and for improving one aspect of a page (typography, color, layout, motion, copy, intensity).
Theme and token edits. The agent can restyle the site theme and your existing design tokens as a draft, and publish them only after you approve.

Two switches

Nothing is inferred. Two explicit switches decide what happens:

Switch	Set by	Off	On
`designSystem` option on `mcpPlugin`	A developer, once per project	No design tools and no design instructions. Every tool and response is exactly what it was.	The design tools are offered to agents, and agents are told when to use them.
The site's design system is enabled	The agent, only after you confirm	The agent can read the site's look and run checks, but no rules are enforced and block writes are not checked.	The agent follows the rules in force and every block write runs the design check.

Turning the option on changes nothing for a site until that site has a design system and someone has enabled it. A multi-site deployment can turn the option on once and let each site opt in on its own.

Enable it (developers)

Pass designSystem to mcpPlugin in your server plugins:

// src/chaibuilder.plugins.ts
import { mcpPlugin } from 'chaipro/plugins/server'

export const chaiServerPlugins: ChaiServerPlugin[] = [
  // ...your other plugins
  mcpPlugin({
    previewUrl: ({ baseUrl, slug }) => `${baseUrl}/next/preview?path=${encodeURIComponent(slug)}`,
    designSystem: true,
  }),
]

true turns everything on with warning-level checks. To decide how block writes treat findings, pass an object instead:

mcpPlugin({
  previewUrl: ({ baseUrl, slug }) => `${baseUrl}/next/preview?path=${encodeURIComponent(slug)}`,
  designSystem: { designChecks: 'strict' },
})

`designChecks`	What a block write does on a site whose design system is enabled
`'warn'` (default)	Saves, and adds the findings on the changed blocks to the response so the agent fixes them before moving on.
`'strict'`	Refuses a write that has any error finding. Nothing is saved, and the agent gets the errors to fix before it sends the edit again. Warnings do not block.
`'off'`	Skips the check on writes. The agent is told to run `check_page_design` before it asks you to publish.

No migration and no new dependency are needed. The design system is stored with the site's existing AI settings.

Turning on only part of it

The tools come in two groups, both exported from chaipro/plugins/mcp/server:

Group	Tools
`DESIGN_SYSTEM_TOOLS`	`get_design_system`, `save_design_system`, `check_page_design`, `get_design_guide`
`SITE_DESIGN_TOOLS`	`update_site_theme`, `update_design_tokens`, `publish_site_theme`

To give agents the design system and checks but keep site-wide restyling in the builder, leave the second group out:

import { SITE_DESIGN_TOOLS } from 'chaipro/plugins/mcp/server'

mcpPlugin({
  previewUrl: ({ baseUrl, slug }) => `${baseUrl}/next/preview?path=${encodeURIComponent(slug)}`,
  designSystem: true,
  exclude: SITE_DESIGN_TOOLS,
})

The agent is told about these tools in two instruction sections, design-system and site-theme. Drop either with excludeInstructionSections if your app states its own rules. See MCP Custom Tools.

Tools and permissions

Each tool is gated like every other MCP tool: a key that lacks a permission is not offered the tool.

Tool	Permissions	What it does
`get_design_system`	`ai:read`, `pages:read`	Reads the site's design system: the written rules, site context, theme fonts, radius and colors, the design tokens to reuse, the page's brief, and the rules in force when it is enabled.
`save_design_system`	`ai:read`, `ai:use`, `pages:read`	Saves or changes part of the design system, the site context from the interview, and a page's brief.
`check_page_design`	`ai:read`, `pages:read`	Runs the design checks on a page draft and lists the findings, errors first.
`get_design_guide`	`pages:read`	Returns a playbook: `setup`, `craft-floor`, `critique`, `audit`, `polish`, `typography`, `color`, `layout`, `motion`, `copy`, `bolder`, `quieter`.
`update_site_theme`	`theme:edit`	Changes the draft theme: fonts, radius and colors.
`update_design_tokens`	`design_tokens:edit`	Restyles existing design tokens. Never creates one.
`publish_site_theme`	`pages:publish`, `app:publish_theme`	Publishes the draft theme and design tokens after you approve.

With the built-in roles:

Role	Design system tools	`update_site_theme`, `publish_site_theme`	`update_design_tokens`
Owner, Admin	Yes	Yes	Yes
Designer	Yes	Yes	No, unless you grant `design_tokens:edit`
Editor	Yes	No	No
Viewer	No (no `mcp:use`)	No	No

If your project manages roles in the database, grant these keys to the roles that should have them, the same as any other permission.

Setting up a site's design system

Ask the agent: "Set up a design system for this site." The agent only starts a setup when you ask for one, or when you accept its one-line offer. It then works through the setup playbook:

Reads what exists. Your current fonts, palette, design tokens and site context, plus one or two finished pages. It asks whether to keep and sharpen the current look or to replace it.
Interviews you. At most three questions a round: who the main visitor is and what they must do or believe, what the business makes possible and what is genuinely different about it, and what must be kept (logo, colors, fonts, voice, words to avoid, proof you can show). It does not ask you for hex codes or a style label like "modern".
Proposes one direction in a single message: a one-line north star, the direction and what it refuses, a theme (fonts from your registered fonts, a radius, and the palette as light and dark pairs, every surface and foreground pair at 4.5:1 or better), how your existing button, card, input and badge tokens change, and the eight sections as named rules with exact classes. You approve it or ask for one round of changes.
Saves it, disabled. If you want the new look straight away, it also applies the theme and token changes as drafts (see Theme and token edits).
Asks you to enable it. Only on a yes does it save the design system as enabled. From then on every page follows it and every block write is checked.

The interview's answers about the business also go into the site context, tone and banned words: the same site AI settings you see in the builder's AI context, so the in-builder assistant benefits from them too.

What a design system holds

The design system holds the written rules only. The values stay where they have always lived: colors, fonts and radius in the theme, component styles in design tokens. Changing a color is a theme edit; the design system says how and where that color is used.

Part	What it is
North star	One line naming the creative direction.
Visitor mode	Who the site serves, which sets how expressive it may be: `persuade` (marketing), `operate` (tools), `read` (docs), `experience` (portfolio).
Color strategy	`restrained` (neutrals and one accent), `committed` (one color on a large share of the surface), `full-palette` (three or four named roles) or `drenched` (color as the surface).
Eight sections	Overview, Colors, Typography, Layout, Elevation & Depth, Shapes, Components, Do's and Don'ts. Written in Markdown, in theme and token terms.
Anti-references	Looks the site deliberately refuses, such as the category default or the stock AI looks.

A page can also have a design brief: its own visitor mode, the idea the page owns, the story it tells, and how the first screen is composed. The agent saves one when you plan a page with it, and reads it before it edits that page.

Changing, pausing and starting over

Ask the agent to change a section. Only the parts it saves change; the rest stays as it was.
Ask it to pause the design system. It saves it as not enabled: the rules stay saved but nothing is enforced and block writes are no longer checked.
Ask it to start over, and it replaces the saved design system instead of changing it.

Saving the design system is site context, not page content: there is nothing to publish.

What the agent follows once it is enabled

With an enabled design system, the agent reads it at the start of any task that adds or restyles content, and follows it along with a fixed quality floor:

It reads a finished section of your site first and reuses its section padding, container width, heading roles and button tokens, so a new page reads as the same site.
It styles components through your existing dt# tokens and colors only through theme roles (bg-primary with text-primary-foreground, bg-card with text-card-foreground, and so on), and it uses the theme fonts.
It keeps body text at 4.5:1 contrast (3:1 for large text) in light and dark, one h1 per page, a readable line length, real hover and focus states, and one deliberate motion moment per page rather than the same entrance on every section.
It avoids gradient text, purple-to-blue gradients, gray text on a colored surface, eyebrow labels above headings, raw palette or hex colors, emoji as icons, cards inside cards, and invented or archived tokens.
It says what it checked (contrast pairs, states, measure) rather than calling a page "polished".

You can read the whole quality floor any time: ask the agent for the craft-floor guide.

Design checks

The checks read a page's blocks and their classes, including classes that come from design tokens, and report what can be seen from them. Each finding names the rule, the block id and the fix.

Check	Severity	Catches
`gradient-text`	Error	Text filled with a gradient.
`purple-blue-gradient`	Error	Purple, violet or fuchsia to blue gradients.
`same-family-pair`	Error	A surface with its own color as text, such as `bg-primary text-primary`.
`gray-on-colored-bg`	Error	Gray text on a colored surface.
`unknown-token`	Error / Warning	A `dt#` token the site does not have (error, it renders nothing), or an archived one (warning).
`multiple-h1`	Error	More than one `h1` on the page.
`raw-palette-color`	Warning	Raw palette or hex colors (`bg-blue-600`, `text-gray-500`, `bg-[#...]`) instead of theme colors.
`heading-order`	Warning	Skipped heading levels, such as `h1` straight to `h3`.
`eyebrow-kicker`	Warning	A small label above a heading.
`off-theme-font`	Warning	A font family that bypasses the theme fonts.
`long-measure`	Warning	Body text set wider than a comfortable line length.
`missing-hover`	Warning	A button-like element without a hover or focus-visible state.
`small-touch-target`	Warning	A control too small to tap comfortably.
`nested-cards`	Warning	Cards inside cards.
`repeated-section-layout`	Warning	The same section composition repeated down the page.
`identical-entrance-animation`	Warning	The same entrance animation on every section.
`emoji-as-icon`	Warning	Emoji or unicode glyphs used as icons.
`banned-word`	Warning	Words from the site's banned words list.
`theme-contrast`	Error / Warning	A theme surface and foreground pair under 3:1 (error) or under 4.5:1 (warning). Reported by `check_page_design` only.

A finding reads like this:

- [error] gradient-text on bid a1b2c3 (Heading): Gradient text (bg-clip-text with text-transparent).
  Fix: Set the text in one solid theme colour (text-foreground or text-primary); carry colour
  in a surface or an accent element instead.

On every write

On a site with an enabled design system, add_blocks, edit_block and add_custom_block run the check on the blocks the edit changed, plus anything the edit newly broke elsewhere (a colored section that makes the unchanged gray text inside it unreadable, a removed h2 that leaves an h1 followed by an h3). A page's older problems are not blamed on every write; that is what check_page_design is for. On a language page the check reads the copy that language shows.

On demand

Ask the agent to "check the design of the pricing page". check_page_design checks the whole draft, or only the blocks you name and what is inside them. It also works on a site with no enabled design system, where the findings are general quality checks to act on as you choose. Heading checks are skipped on a global block, which has no page structure of its own.

A clean check is evidence, not proof. The checks read classes. They cannot see an image behind text or judge whether a layout feels right, so the agent is told to look at the preview too, and so should you.

Playbooks

For a critique, an audit, a polish, or a request to make something bolder, quieter, better typeset, more colorful, better laid out, animated or clearer, the agent fetches the matching playbook before it acts. Each one says what to assess, what to change, what must stay, and how to verify.

Topic	Use it for
`setup`	The design system interview and direction. Only when you ask for a setup.
`craft-floor`	The quality floor and the patterns that make a page read as machine-made.
`critique`, `audit`, `polish`	Reviewing a page, from a critique you read to a pass that fixes the details.
`typography`, `color`, `layout`, `motion`, `copy`	Improving one aspect of a page.
`bolder`, `quieter`	Changing a section's intensity.

A playbook changes what you named and keeps everything else. "Make the hero bolder" changes the hero, not the page. The playbooks work whether or not the site has a design system.

Theme and token edits

Site-wide restyles go through three tools. The agent uses them only for a site-wide change you approved, such as the end of a setup, never to fix one page.

The theme

update_site_theme changes the draft theme. Only what the agent passes changes.

Fonts for headings and body, by exact name. Only fonts registered on your site are accepted; anything else is refused with the list of available fonts. See Custom fonts.
Radius in px or rem.
Colors as [light, dark] pairs of six-digit hex values, keyed by theme role.
Readable pairs only. A change that leaves a surface and foreground pair it touches under 3:1 is refused and nothing is saved. A pair under 4.5:1 is saved and reported, since it is only fine for large text.

Besides the 19 colors in the Theme panel, the agent can set the optional success, warning, info, purple, orange and aqua roles and their foregrounds. Once set, classes like bg-success render. The Theme panel does not show these roles.

Design tokens

update_design_tokens restyles tokens your site already has, so a component changes everywhere at once.

It never creates a token. An unknown token id is refused. Create new tokens in the builder, then the agent can restyle them.
Built-in tokens: the agent's classes merge over the token, and its layout, focus and disabled classes always stay. It can also reset a built-in to its shipped value.
Your own tokens: the agent sets the complete class list, and can rename, describe or archive the token.

Drafts and publishing

Theme and token edits are drafts, exactly like edits in the builder. Previews show them straight away, and they appear in the builder's publish list as Theme and Design Tokens. The live site keeps its old look until they are published.

publish_site_theme takes the theme and tokens live on every published page at once. The agent may call it only after you have seen the change in a preview and explicitly approved publishing the theme, and never in the same turn as the edits. You can also publish from the builder as usual. Publishing the theme also takes the site's saved AI settings and design system live with it.

The in-builder assistant

The builder's own AI assistant does not use the design system yet. Its prompts are unchanged, and saving the AI context in the builder leaves a saved design system and page briefs in place.

Custom tools

A tool of your own that writes blocks through applyPageEdit gets the same write-time check by passing { designChecks: true }. It does nothing until both switches are on, so the option is safe to set everywhere. See MCP Custom Tools.

Gotchas

The theme has no revision history. An agent's theme change cannot be restored from Revisions. Before a site-wide restyle, note the current values, or keep the change as a draft until you are sure.

A saved design system is not an enabled one. After a setup, the agent asks whether to enable it. Until you say yes, the rules are reference only and nothing is checked on write.

Tokens are edit-only for agents. If the direction needs a component your site has no token for, create the token in the builder first.

Theme tools may be missing for editors. The built-in editor role has no theme:edit, and the designer role has no design_tokens:edit. Grant them if those roles should restyle the site through an agent.

Troubleshooting

Symptom	Cause
No design tools in `tools/list`	`mcpPlugin` has no `designSystem` option, the key lacks `ai:read` or `pages:read`, or the tools are in the `exclude` list.
`update_design_tokens` or the theme tools are missing	The key lacks `design_tokens:edit`, `theme:edit` or `app:publish_theme`, or `SITE_DESIGN_TOOLS` is excluded.
The agent ignores the design system	It is saved but not enabled. Ask the agent to enable it.
A block edit fails with "Design check failed, so nothing was saved"	`designChecks: 'strict'` and the edit had an error finding. The agent fixes the errors and sends the edit again.
A theme change is refused as unreadable	A surface and foreground pair would drop under 3:1.
A font is refused	It is not registered on the site. Register it, then retry.
A token is refused as "not a design token of this site"	Agents cannot create tokens. Create it in the builder first.
`publish_site_theme` asks for `confirmed`	The agent must get your explicit approval first.
"Nothing to publish"	The live site already has the current theme and tokens.

Verify

List the tools your key sees (see MCP Server Setup) and confirm get_design_system and check_page_design are there.
Ask the agent to read the site's design system. On a new site it reports that none is set up and describes the current fonts, palette and tokens.
Ask it to check the design of a page. It lists findings, errors first, with a block id and a fix for each.
After a setup, confirm you were asked before the design system was enabled, then ask for a new section and check the edit's response ends with a Design check line.
After a theme change, confirm the live site is unchanged until the theme is published.

MCP Server Setup - enable the server and connect a client.
MCP Custom Tools - add your own tools and instructions.
Theming - the theme values the design system builds on.
Design tokens - the component styles agents restyle.
Custom fonts - registering fonts the theme can use.
Preview & Publish - drafts and the live site.