Tokens

Provider tokens extend the design-token maps that back props like color, size, rounded, and variant. Use this when remapping theme colors is not enough—for example a new brand color or a pill radius.

This is separate from the instance customProps / custom-props API on components, which forwards HTML attributes to internal parts.

How it works

Built-in tokens live in @bridge-ui/core (for example Button variant → color maps with base / hover / focus classes). Registry tokens deep-merges on top of those maps. Lookups use the merged tree, so <Button color="brand" /> resolves your classes when brand exists under the active variant.

Typical Button shape:

components: {
  Button: {
    tokens: {
      // new or overridden rounded token → class string
      rounded: Record<string, string>;
      // density → size → class string
      density: Record<string, Record<string, string>>;
      // variant → color → { base, hover, focus }
      variant: Record<
        string,
        Record<string, { base: string; hover: string; focus: string }>
      >;
    };
  };
}

Other components expose similar maps (color, size, padding, shadow, …)—see BridgeUIComponentsConfig in @bridge-ui/core.

Add a brand color

Define Tailwind utilities that use your theme tokens, then register them under each variant you need:

Add a rounded or size token

Button: {
  tokens: {
    rounded: {
      pill: "rounded-[2rem]",
    },
  },
},

<Button rounded="pill">Pill</Button>

Sizes and densities follow the same pattern: keys become prop values; values are the class strings (or nested maps) the component already expects for that axis.

Combine with defaults

Once a token exists, set it as the app default:

Button: {
  defaultProps: { color: "brand", rounded: "pill" },
  tokens: {
    /* brand + pill definitions */
  },
},

TypeScript

Runtime accepts any string key you register. For autocomplete and type-checking, augment the matching *Overrides interface—see Type overrides.

Next steps

Type overrides — ButtonColorOverrides, config augments, and more
Theme colors — remapping primary without new tokens
Classes — slot-level styling without new prop values