Manual

The Base Design System is the component library and token set behind Base's product surfaces: Dashboard, Console, and Docs. This site documents what the components are for and how to use them well; Storybook remains the workbench for props, controls, and interaction states. Setting up with a coding agent instead? See Agent setup.

Set up

Install

yarn add @base-org/bds-web @base-org/bds-tokens

bds-tokens holds the raw values and has no React dependency. bds-web is the component library and reads its colours from those tokens — install it without the token stylesheet and components render unstyled.

React 19.3 or newer is required. Freeze, AnimateHeight, and the metric card charts depend on Fragment Refs, which only became stable in 19.3.

Set up your CSS

Your global CSS must import Tailwind, the spectrum tokens, and the BDS global styles, in that order:

@import 'tailwindcss';
@import '@base-org/bds-tokens/tokens/spectrum.css';
@import '@base-org/bds-web/styles.css';

styles.css points Tailwind at the compiled components and holds everything else they rely on: the dark variant, the type scale, the rounded-* and --bg utilities, focus rings, and the loading animations. Import it rather than copying its rules, so they stay in step with the components.

Import a component

Every component is its own entry point; there are no barrel exports.

import { Button } from '@base-org/bds-web/product/button';

Set shared defaults

Every component exports a [Component]PropsContext. Wrap a region in it to give every instance inside the same default props; props set on the component itself still win, and a className from context is merged with the component's own.

import { ButtonPropsContext } from '@base-org/bds-web/components/button';

<ButtonPropsContext value={{ size: 'sm', variant: 'secondary' }}>
  <Toolbar />
</ButtonPropsContext>;

Update

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

Upgrade both packages together, to the same version:

yarn up @base-org/bds-web @base-org/bds-tokens

Read CHANGELOG.md in base/bds for every version in between and follow any breaking-change notes. Then compare the bds-agent-setup version in your instructions file with the block on the Agent setup page and paste the new block over the old one if it has changed. Do the same for the Build UI with BDS skill: compare its version with the copy in base/bds and replace yours if it is newer.

Troubleshooting

React is older than 19.3

Freeze, AnimateHeight, and the metric card charts use Fragment Refs, which became stable in React 19.3. Upgrade react, react-dom, and their types together before installing BDS.

Components render unstyled

The global stylesheet is missing the token import or the BDS styles.css import, so Tailwind never generates the classes the components use. Check it has all three lines from Set up your CSS, and that the app runs Tailwind CSS v4.

The two packages are on different versions

@base-org/bds-web reads its colours from @base-org/bds-tokens, and both release together. Upgrade them to the same version in one step.