Tokens

Tokens are the public interface of @bitsyui/core. Primitive palettes and fixed scales sit underneath; Bits, Patterns, and your own CSS read the semantic tier on top.

Two tiers

Primitives give the raw values. The semantic tier names what a value is for, and that is what everything else reads.

Tier 1

Primitives

Twelve-step palettes (gray, brand, error, warning, success) and fixed scales for space, radius, shadow, and type.

--bitsy-gray-50 … --bitsy-gray-950
--bitsy-brand-500
--bitsy-space-3
--bitsy-radius-xl

Tier 2

Semantic

Roles for text, background, border, and brand, plus control and container shape. Appearances and dark mode remap these.

--bitsy-color-text-primary
--bitsy-color-bg-brand-solid
--bitsy-color-border-secondary
--bitsy-radius-control

Semantic color

Each name is prefixed with --bitsy-color-. Switch the mode or appearance in the header to see them remap.

Swatch	Text	Use
	`text-primary`	Headings and body copy
	`text-secondary`	Labels and supporting copy
	`text-tertiary`	Hints, captions, quiet metadata
	`text-placeholder`	Placeholder text
	`text-brand`	Links and brand text
	`text-on-brand`	Text on a brand solid
	`text-error`	Error messages

Swatch	Background	Use
	`bg-canvas`	Page canvas behind surfaces
	`bg-primary`	Default surface
	`bg-secondary`	Subtle surface, code, previews
	`bg-tertiary`	Selected and pressed states
	`bg-brand-solid`	Primary actions
	`bg-brand-subtle`	Brand tints
	`bg-error-subtle`	Error tints

Swatch	Border and focus	Use
	`border-primary`	Control borders
	`border-secondary`	Dividers and container borders
	`border-brand`	Brand emphasis
	`border-error`	Invalid controls
	`ring`	Focus ring

Fixed scales

Space, radius, and shadow are fixed steps, so app layouts stay dense and predictable. Type steps stay fluid within a narrow range.

Space	Size
`--bitsy-space-1`
`--bitsy-space-2`
`--bitsy-space-3`
`--bitsy-space-4`
`--bitsy-space-5`
`--bitsy-space-6`
`--bitsy-space-7`
`--bitsy-space-8`

Radius

xs

sm

md

lg

xl

2xl

full

Bits read --bitsy-radius-control and --bitsy-radius-container, which each appearance points at a step.

Shadow

xs

sm

md

lg

xl

Bits read --bitsy-shadow-control, --bitsy-shadow-container, and --bitsy-shadow-overlay.

Overrides

Most projects only need a handful of overrides. Recolor through the brand palette, and reshape through the semantic shape tokens.

@import "@bitsyui/core";

:root {
  --bitsy-brand-900: #1f3a5f; /* primary actions, brand text */
  --bitsy-brand-700: #2f5180; /* hover, brand border */
  --bitsy-brand-500: #4a73b0; /* focus ring */
  --bitsy-radius-control: var(--bitsy-radius-md);
}

Earlier names such as --bitsy-color-accent and --bitsy-color-muted still resolve as aliases of the semantic names, so older overrides keep working. New code should use the semantic names.

The CLI generates the same kind of file: pnpm dlx @bitsyui/cli init bitsy.css --dry-run prints a small override sheet on top of @bitsyui/core.