Agent setup | Base Design System

Set up a coding agent to build with BDS, in an app or on a doc page, and keep it up to date.

Your agent can install BDS, wire up the styles, and learn where the guidelines live. It then checks for updates at the start of every UI task. Prefer to set things up yourself? See Manual.

Recommended model

Use Claude Opus 5.5 (claude-opus-5-5) for building, fixes, and reviews with BDS. It is the model we test the setup prompts and skills against, and BDS Studio uses it for both its agent and its judge. Other capable coding models work too, but check their output against the guidelines more closely.

Set up your agent

Pick the prompt that matches what you are making. Building an app installs BDS into a repo. Making a doc or page needs no repo: the agent styles a single HTML file, such as a bdocs page, with BDS tokens.

Building an app

Copy this prompt into Claude Code, Codex, Toshi, or another coding agent, from the root of your app's repo. The agent installs the packages, adds the and the Build UI with BDS skill to your repo, checks its work, and tells you what to try first. It stops and asks when it needs you, for example to sign in to GitHub.

Set up the Base Design System (BDS) in this repo. Work through these steps
in order. Stop and tell me when you need me to do something.

1. Check access. Run `gh api repos/base/bds -q .name`. If it fails, stop
   and ask me to sign in with `gh auth login`, using a GitHub account in
   the `base` organization.
2. Check the project. BDS needs React 19.3 or newer and Tailwind CSS v4.
   If React is older, stop and tell me. If the app has no Tailwind, ask
   me before adding it. Note the repo's package manager.
3. Install. Add `@base-org/bds-web` and `@base-org/bds-tokens` at the same
   version with the repo's package manager.
4. Set up CSS. Read the manual:
   `gh api repos/base/bds/contents/apps/docs/content/docs/manual.mdx -H "Accept: application/vnd.github.raw"`.
   Add the lines under "Set up your CSS" to the app's global stylesheet.
5. Add the agent block. Read `apps/docs/content/docs/index.mdx` the same
   way. Copy the fenced block that contains `bds-agent-setup` into this repo's
   `AGENTS.md`, or `CLAUDE.md` if that is what the repo uses. If a
   `bds-agent-setup` block is already there, replace it; never keep two.
6. Install the Build UI with BDS skill. Save
   `skills/build-ui-with-bds/SKILL.md` from `base/bds` to
   `build-ui-with-bds/SKILL.md` in the repo's skills directory
   (`.agents/skills/`, `.claude/skills/`, or `.pi/skills/`; use
   `.agents/skills/` if the repo has none).
7. Verify. Confirm that both packages are in package.json at the same
   version, the global CSS imports Tailwind, `spectrum.css`, and
   `@base-org/bds-web/styles.css`, an import of `@base-org/bds-web/product/button`
   resolves, the skill file is in place, and the repo's typecheck or build
   passes.
8. Hand off. Reply in 120 words or fewer, in this shape:

   Status: what you installed and changed, and anything that failed.
   Next: two or three first tasks for this repo, such as building a new
   screen with BDS components, auditing an existing screen against the
   BDS guidelines, or replacing custom buttons and inputs with BDS ones.

Once it finishes, try one of the tasks it suggests. If something fails, see Troubleshooting.

Making a doc or page

Use this for bdocs pages and other single HTML files, such as a report or a one-pager, when there is no app repo or build step. BDS components are React and need a build, so the agent recreates their look with BDS tokens in one <style> tag instead. Copy this prompt into your agent from any folder. It installs the Make docs with BDS skill for your user, so it works wherever you start, and tells you what to try first.

Set me up to make documents and pages with the Base Design System (BDS),
such as bdocs pages or single HTML files. I don't have an app repo, so
don't install packages, create a repo, or look for package.json. Stop and
tell me when you need me to do something.

1. Check access. Run `gh api repos/base/bds -q .name`. If it fails, stop
   and ask me to sign in with `gh auth login`, using a GitHub account in
   the `base` organization.
2. Install the Make docs with BDS skill. Read it with
   `gh api repos/base/bds/contents/skills/make-docs-with-bds/SKILL.md -H "Accept: application/vnd.github.raw"`
   and save it as `make-docs-with-bds/SKILL.md` in your user-level skills
   directory, so it works in every folder: for example `~/.claude/skills/`,
   `~/.pi/agent/skills/`, or `~/.agents/skills/`. If you can't install
   skills, follow it for the rest of this session.
3. Verify. Confirm the skill file is in place and that you can read
   `packages/tokens/src/tokens/spectrum.css` from `base/bds`.
4. Hand off. Reply in 80 words or fewer, in this shape:

   Status: where you saved the skill, and anything that failed.
   Next: two or three first tasks, such as turning a draft into a
   BDS-styled bdocs page or restyling an existing HTML report.

Update

Packages, the agent block, and the skill update separately. Upgrading @base-org/bds-web does not change the block in your AGENTS.md or your copy of the skill, and a new block does not upgrade your packages.

The block already tells your agent to check all three at the start of every UI task. To update now, copy this prompt into your agent:

Update the Base Design System (BDS) in this repo. Packages, the agent
block, and the Build UI with BDS skill update separately; do all three.

1. Packages. Compare the installed `@base-org/bds-web` with
   `npm view @base-org/bds-web version`. If the repo is behind, read
   `CHANGELOG.md` in `base/bds` for every version in between. Upgrade
   `@base-org/bds-web` and `@base-org/bds-tokens` to the same version in
   their own commit, apply any breaking-change notes, and run the repo's
   checks.
2. Agent block. Read `apps/docs/content/docs/index.mdx` from `base/bds`
   with `gh api` and compare its `bds-agent-setup` version with the block
   in this repo's `AGENTS.md` or `CLAUDE.md`. If it is newer, replace the
   whole block and leave everything outside it untouched.
3. Skill. Compare the `version` in the installed
   `build-ui-with-bds/SKILL.md` frontmatter with
   `skills/build-ui-with-bds/SKILL.md` in `base/bds`. If it is newer or
   missing, save the new copy over the old one.
4. Report in 80 words or fewer: versions before and after, breaking
   changes you handled, and whether the block or skill changed.

Prefer to update by hand? See Update in the manual.

Troubleshooting

The agent can't read the BDS docs

base/bds is internal on GitHub, so gh api returns 404 without access. Run gh auth status to see which account is signed in, then gh auth login with an account in the base organization.

The agent keeps an old block

Compare the bds-agent-setup version in your instructions file with the one on this page. Replace the whole block, not parts of it, and keep only one copy per repo. If both CLAUDE.md and AGENTS.md contain it, keep it in AGENTS.md and point CLAUDE.md at it with @AGENTS.md.

For install problems, such as components rendering unstyled, see Troubleshooting in the manual.

How it works

The block points to the docs instead of copying them. Rules change in one place, the base/bds repo, and every repo that pasted the block reads the latest version the next time its agent starts a UI task.

Three checks keep a repo current:

Packages: the agent compares the installed version with the latest on npm and upgrades when the repo is behind.
The block itself: it carries a version number. When this page publishes a new version, agents notice the mismatch and replace their copy.
The skill: it carries a version number too, checked the same way against the copy in base/bds.

When the block changes, bump bds-agent-setup so existing copies update.

Build UI with BDS skill

The block sets BDS up and keeps it current. The skill covers the UI task itself: it breaks the work into parts, maps each part to a component through a component index, points to the guidelines that apply, and ends with a checklist the agent runs against its own work.

The skill is a map, not a copy. It names which docs to read, and the agent reads them from base/bds, so most rule changes reach every repo without reinstalling anything. The setup prompt installs it; to install it yourself, save skills/build-ui-with-bds/SKILL.md into your repo's skills directory.

Every component page has a When to use section that says what the component is for and what to use instead. The skill's index points to those sections.

When the skill's instructions or index change, bump its version so existing copies update. yarn verify:docs fails if a component page is missing from the index.

Make docs with BDS skill

The Make docs with BDS skill is for pages with no repo and no build, such as bdocs pages and other single HTML files. The agent copies the colour tokens from spectrum.css into a <style> tag, adds a plain-CSS base layer for the type scale, radii, and focus ring (in an app these come from Tailwind), and builds each part from an HTML pattern that matches a BDS component: Card, Banner, Status, Badge, Button, Link, and Stat. It ends with the same contrast, phone-width, and writing checks as the Build UI skill.

Interactive components such as Tabs, Dialog, and Select need React, so the skill swaps them for document structure or says the page needs an app. Like the Build UI skill, it carries a version and replaces itself when the copy in base/bds is newer. To install it yourself, save skills/make-docs-with-bds/SKILL.md into your agent's user-level skills directory.

Reading the docs as Markdown

The docs site also serves every page as Markdown for agents: /llms.txt lists every page, /llms-full.txt has them all in one file, and adding .md to any page URL returns that page. Once the site is deployed, the block will read from there instead of gh api.