# Design agent

> The DS Manager design agent edits your AI design system from a chat. It changes tokens, fonts and component styles on the canvas, with one undo per turn.

Canonical: https://www.shadcndesign.com/docs/ds-manager-agent

The **Agent** tab is a chat that edits the design system you have open. It works through the same controls you use, so each change appears on the canvas right away and a whole turn undoes in one step.

<RichImage
  src="/docs/ds-manager/agent.webp"
  alt="The Agent tab on the Card page after the request to make cards softer, with the agent's reply and Changes card in the right rail and the rounder, lifted cards on the canvas"
  width="899"
  height="665"
  quality="90"
/>

## Start a chat

1. Sign in. The agent edits the system synced to your account and saves your chats there.
2. Open the **Agent** tab in the right rail, or press `2`.
3. Type a request and press Enter, or click one of the starter prompts.

An empty chat offers these starters:

- Make it feel warmer
- Use a rounded, friendly style
- Tighten spacing for a denser UI
- Give it a bold, high-contrast look
- Create a custom component: color picker (Pro only)

While the agent works, the thread shows one line per step ("Looked up rules", "Edited rules") and the note "Don't close this browser tab". The agent runs in your tab, so closing it stops the turn. Press **Stop** to end a turn early; edits made up to that point stay.

When the turn ends, a **Changes** card sums up what it did. **Undo** on the card takes back the whole turn, and **Redo** puts it back. The card's buttons work until you reload the page.

Use the chat picker at the top of the tab to go back to an earlier chat. **New chat** starts a fresh one and **Delete this chat** removes the open one. The agent names each chat from your first message.

## What the agent can change

The agent edits the open system and nothing outside it. It never writes files or generated CSS; every edit is a change you could also make by hand.

- **Color tokens**, light and dark.
- **Foundations**: style, base color, accent and chart presets, radius, spacing, letter spacing, fonts, icon library and icon style, menu color and accent, shadow, and the system name.
- **Component styles**: any part of any component, for one variant, size or state (hover, focus, selected, open, disabled, invalid), in light or dark mode. A request about one component stays on that component. A request about a mood or a brand gets a full pass over tokens, foundations and the components the look touches.
- **Variants**: add, rename or remove variant and size values.
- **ProBlocks**: one block's own styles, or the shared styles every block uses. On the Free plan only the first block of each category can be edited, and the agent says so ("Hero 2 is part of Pro.").
- **Custom components** (Pro): build a component shadcn/ui does not ship. See [Custom components](/docs/ds-manager-custom-components).
- **Lint locks**: set up which properties agents may change, through a short interview. See [Lint locks](/docs/ds-manager-lint).

After an edit the agent takes a picture of the canvas to check its work, up to four times per message, and fixes what looks broken before it replies. Questions outside your design system get a one-sentence decline.

## Point at something

**Selection.** ⌘-click an element on the canvas, or click **Select an element** (the pointer button in the composer) and then click the element. It shows as a chip above your message, and the agent gets that element's styles with your request. The chip's X clears it, and Esc cancels picking.

**Files.** Click **Add a file** (the paperclip), or paste. The agent reads:

- images (JPEG, PNG, WebP, GIF)
- PDF
- HTML, CSS, SVG, JSON, Markdown and plain text

You can attach up to four files per message, each up to 10 MB. A PDF can be at most 2.25 MB. Not every model reads PDFs: when the selected model can't, the composer says so before the file is sent.

**Links.** Paste a URL in your message and the agent reads that page with its stylesheets. For a design system's site it also reads the color, typography and component pages, then matches them.

A screenshot plus "match this" works well. So does a link to your brand's website.

## Limits

- One message runs for at most 30 minutes. At that point the thread says "Stopped after 30 minutes. Your changes so far are saved."
- On included AI usage, an account can run 200 turns or 400k output tokens per day. On your own API key the cap is 500 turns or 2M output tokens. Both reset at midnight UTC.
- If the thread says "The agent is resting until tomorrow.", DS Manager has reached its own daily limit. Try again the next day.

## AI usage and the free $1

The line under the composer shows what the open chat has cost so far and how much AI usage you have left. An empty chat also shows your balance, for example "You have $1.00 of free AI edits".

**Free plan.** You get $1 of AI usage once. It unlocks when your account is at least 10 minutes old and owns a system. Until then the tab says what it is waiting for, either "Create a system to unlock your free $1" or a countdown like "Your free $1 unlocks in 6 minutes", and it opens by itself when the time is up.

**Pro.** Monthly and yearly Pro include $5 of AI usage each month, about 90 turns. Lifetime includes $5 once. Pro also lets you run the agent on your own API keys. See [Plans and limits](/docs/ds-manager-plans).

<DocsCta
  title="More AI usage and your own keys are Pro"
  description="Pro adds $5 of AI usage a month and lets you run the agent on your own Anthropic, OpenAI, xAI or Google API key."
  primaryLabel="See plans"
  primaryHref="/ds-manager#pricing"
/>

## Use your own API keys

On Pro and Lifetime you can run the agent on your own provider account. A Free account sees "Get Pro to access API keys" in this section.

1. Open Settings: **Settings…** in the account menu, ⌘K, or ⌘,.
2. Go to **API keys**. There is one row each for Anthropic, OpenAI, xAI and Google.
3. Paste your key and click **Add key**. DS Manager checks it with the provider before it stores it. Keys are stored encrypted and never shown again; the row then reads "Key ending in …" with the last four characters.
4. In the Agent tab, open the model menu in the composer's corner. The provider's models now appear marked "your key".

Turns on your key are billed by the provider and never touch your included usage. The models on offer are Claude Opus 5, Claude Fable 5.1, Claude Sonnet 5, GPT-5.6 Sol, GPT-5.6 Terra, Grok 4.6 and Gemini 3.8 Flash. Without a key of your own, the agent runs on Grok 4.6 from your included usage.

Switch a key off to keep it without using it. **Replace…** swaps in a new key and **Remove** deletes it. If a provider refuses your key during a turn, DS Manager switches the key off and shows the reason next to its row.

## When AI usage runs out

A turn that runs out of usage stops, and the thread says "You are out of AI usage." DS Manager never charges you for more.

- **Free:** the tab shows **Out of AI usage** with **See plans**.
- **Pro, monthly or yearly:** "You have used this month's AI usage. Pro adds $5 more next month. To keep going now, add your own API key." **Add your API key** opens Settings. Models on your own key keep working.
- **Lifetime:** "You have used the AI usage that came with Lifetime. To keep going, add your own API key."