Theming

Birdpaper UI themes are driven by CSS variables. After importing styles, override variables in your app to change brand colors, sizes, radii, and overlay stacking. Dark mode is toggled with the .dark class on the root node.

Note: ConfigProvider / app.use handle runtime options such as prefix, default size, locale, and zIndex. They do not change colors. Override visual tokens with the approaches in this guide.

Import Styles

Full import (recommended to start):

import "birdpaper-ui/theme/index.css";

On-demand component styles:

import "birdpaper-ui/theme/button.css";
import "birdpaper-ui/theme/input.css";

See Installation for install and on-demand options.

Override Brand Colors

Semantic scales use --bp-{primary|success|warning|danger}-{1..10}. The main brand color is usually step 6. When changing the brand color, override at least the main step and nearby steps so hover and light backgrounds stay coherent:

:root {
  --bp-primary-4: #6aa1ff;
  --bp-primary-5: #4080ff;
  --bp-primary-6: #165dff; /* Primary */
  --bp-primary-7: #0e42d2;

  /* If you use rgba(var(--bp-*-rgb), a), override the RGB channels too */
  --bp-primary-6-rgb: 22, 93, 255;
}

Transparency example:

.my-tag {
  color: var(--bp-primary-6);
  background: rgba(var(--bp-primary-6-rgb), 0.1);
}

See Colors for the full palette and scale usage.

Size and Radius

Component sizes rely on --bp-size-* tokens (mini / small / default / large):

--bp-size-height-*	22px	28px	32px	36px
--bp-size-font-size-*	12px	13px	14px	14px
--bp-size-padding-*	10px	14px	20px	26px
--bp-size-border-radius-*	3px	4px	6px	8px

Example: bump default height and radius everywhere:

:root {
  --bp-size-height-default: 36px;
  --bp-size-border-radius-default: 8px;
  --bp-size-padding-default: 24px;
}

You can also inject a global default size (affects components that do not pass size themselves):

import BirdpaperUI from "birdpaper-ui";

app.use(BirdpaperUI, { size: "small" });

<template>
  <bp-config-provider size="small">
    <App />
  </bp-config-provider>
</template>

Overlay z-index

Overlay components (Modal, Drawer, Tooltip, Message, and similar) derive from --z-index-base (default 3000):

:root {
  --z-index-base: 4000; /* Raising this lifts derived layers too */
}

You can also set runtime zIndex on install or ConfigProvider (works with the variable; default is also 3000):

app.use(BirdpaperUI, { zIndex: 4000 });

Dark Mode

Add or remove .dark on the root node (usually html) to toggle. Under .dark, semantic variables such as --bp-primary-6 map to the dark palette, so app code can keep using var(--bp-primary-6).

// Enable dark mode
document.documentElement.classList.add("dark");

// Disable dark mode
document.documentElement.classList.remove("dark");

// Or toggle
document.documentElement.classList.toggle("dark");

Persist preference and follow the system:

const KEY = "bp-color-scheme";

export const setDark = (enabled) => {
  document.documentElement.classList.toggle("dark", enabled);
  localStorage.setItem(KEY, enabled ? "dark" : "light");
};

export const initColorScheme = () => {
  const saved = localStorage.getItem(KEY);
  if (saved === "dark" || saved === "light") {
    setDark(saved === "dark");
    return;
  }
  setDark(window.matchMedia("(prefers-color-scheme: dark)").matches);
};

To change the brand color only in dark mode, override the dark palette or the mapped variables:

.dark {
  --bp-primary-dark-6: #689fff;
  /* or directly */
  --bp-primary-6: #689fff;
  --bp-primary-6-rgb: 104, 159, 255;
}

See Dark Mode for scale direction, neutral mapping, and adaptation guidelines.

Relation to ConfigProvider

Brand / neutral colors, radius, height, and other visual tokens	Override CSS variables (this guide)
Dark mode	Root .dark class
Default size, locale, register prefix, zIndex, empty-state copy	app.use / ConfigProvider

Do not expect to pass a full theme object through ConfigProvider—that API is not available in the current version. See Global Config.

Advanced: Recompile SCSS

To change the BEM namespace (default bp) or customize SCSS variables from source, recompile theme sources from the package and import the rebuilt CSS. Changing only ConfigProvider's namespace does not rewrite published CSS selectors or --bp-* variable names, which easily breaks styles.

For a token and style overview, see Design Resources. For spacing, type scale, and related conventions, see the Style Guide.

References

• Colors — Functional and neutral palettes
• Dark Mode — Dark mapping and adaptation rules
• Style Guide — Design-side conventions
• Global Config — ConfigProvider API
• Installation — How to import styles