Custom Theme

To create a custom theme, override BEEQ’s root semantics — the brand, intent, and neutral colors — with your own values. BEEQ’s light and dark mode roles already point to those root tokens, so every component picks up your palette in both modes. Override individual mode roles only where your palette needs a different mapping.

Set --bq-brand and the other root semantics here, in the theme. To style UI with the brand color, use the mode role --bq-ui--brand instead, as described in Color architecture.

Namespace your theme using the bq-theme attribute (e.g., bq-theme="my-custom-theme") or a matching CSS class (e.g., .my-custom-theme).

Step-by-step guide

Define root semantics

Create a CSS file for your custom theme (e.g., custom-theme.css) and set the root tokens. Give each intent you change all five steps — see Intent scale for what each step is used for:

[bq-theme="my-custom-theme"],
.my-custom-theme {
  /* Override font family */
  --bq-font-family: 'Inter', sans-serif;

  /* Brand: tint, fill, dark tint, and the two text-safe steps */
  --bq-brand-light:  var(--bq-purple-100);
  --bq-brand:        var(--bq-purple-600);
  --bq-brand-dark:   var(--bq-purple-1000);
  --bq-brand-strong: var(--bq-purple-600); /* text, icons, strokes on light surfaces */
  --bq-brand-bright: var(--bq-purple-300); /* text, icons, strokes on dark surfaces */

  /* Override the neutral scale if needed */
  --bq-neutral-50:  var(--bq-grey-50);
  --bq-neutral-100: var(--bq-grey-100);
  /* ... continue with other neutrals ... */

  /* Repeat the five steps for accent, info, success, warning, or danger
     to change them. Intents you don't set keep BEEQ's values. */
}

Don’t set --bq-focus here. Focus is a mode role that defaults to --bq-brand-strong in light mode and --bq-brand-bright in dark mode, so it follows your brand automatically.

Adjust mode roles (optional)

Override mode roles only where the defaults don’t fit your palette. The most common cases are the on-color of a solid fill, the focus color, and neutral surfaces:

/* Light mode */
[bq-theme="my-custom-theme"]:not([bq-mode]),    /* Default — no mode specified */
[bq-theme="my-custom-theme"][bq-mode="light"],  /* Explicit light mode (via attributes) */
.my-custom-theme:not([bq-mode]),                /* Default — no mode (via CSS class) */
.my-custom-theme.light {                        /* Explicit light mode (via CSS classes) */
  --bq-text--on-brand: var(--bq-white);
  --bq-focus:          var(--bq-brand-strong);
}

/* Dark mode */
[bq-theme="my-custom-theme"][bq-mode="dark"],  /* Explicit dark mode (via attributes) */
.my-custom-theme.dark {                        /* Explicit dark mode (via CSS classes) */
  --bq-background--primary: var(--bq-neutral-1000);
  --bq-text--on-brand:      var(--bq-white);
  --bq-focus:               var(--bq-brand-bright);
}

The full list of mode roles and their defaults is in Colors → Mode roles. Hover and active colors aren’t roles you set per component: BEEQ mixes them from the rest color with --bq-hover and --bq-active, so they follow your overrides.

Apply your custom theme

Include your custom theme CSS file in your project and set the bq-theme and bq-mode attributes on the <html> element.

bq-mode is optional for light mode: without it, the root element uses BEEQ’s light mode roles plus the :not([bq-mode]) overrides from the previous step. Set bq-mode="dark" (or the .dark class) to switch to dark mode.

Always load beeq.css before your custom theme CSS so that your variables correctly override the defaults.

Pick the setup that matches your project:

<!DOCTYPE html>
<html lang="en" bq-theme="my-custom-theme" bq-mode="light">
  <head>
    <link rel="stylesheet" href="path/to/beeq.css">
    <link rel="stylesheet" href="path/to/custom-theme.css">
  </head>
  <body>
    <!-- Your components will automatically use the custom theme -->
    <bq-button>Click me</bq-button>
  </body>
</html>

/* src/index.css — load BEEQ first, then your custom theme */
@import "@beeq/core/dist/beeq/beeq.css";
@import "./custom-theme.css";

/* src/index.css */
@import "tailwindcss";
@import "@beeq/core/dist/beeq/beeq.css" layer(base);
@plugin "@beeq/tailwindcss";
@import "./custom-theme.css";

// tailwind.config.ts
import beeqPreset from "@beeq/tailwindcss";
import type { Config } from "tailwindcss";

export default {
  content: ["./index.html", "./src/**/*.{js,ts,jsx,tsx,vue}"],
  presets: [beeqPreset],
} satisfies Config;

The @beeq/tailwindcss preset maps BEEQ tokens to Tailwind utility classes but does not define your custom theme. Keep the custom theme CSS as a separate file that overrides --bq-* variables, and load it after beeq.css.

With Tailwind v4, @beeq/tailwindcss 1.16.2 and earlier fail with @plugin (b is not a function). On those versions, use @config "@beeq/tailwindcss"; instead.

With Tailwind v4, import beeq.css with layer(base) as shown. Without it, the BEEQ reset overrides Tailwind utilities such as mx-auto. See Apps that use cascade layers.

Set the theme and mode on the root element from your app entry so the attributes are present before any component renders:

// src/main.tsx
document.documentElement.setAttribute("bq-theme", "my-custom-theme");
document.documentElement.setAttribute("bq-mode", "light");

// src/main.ts
document.documentElement.setAttribute("bq-theme", "my-custom-theme");
document.documentElement.setAttribute("bq-mode", "light");

<html lang="en" bq-theme="my-custom-theme" bq-mode="light">

To switch to dark mode, change the bq-mode attribute:

<html lang="en" bq-theme="my-custom-theme" bq-mode="dark">

You can also use CSS classes instead of HTML attributes:

<body class="my-custom-theme light"> ... </body>
<!-- or -->
<body class="my-custom-theme dark"> ... </body>

For a full React setup — packages, styles, icons, and event handling — see the React framework guide. For the Tailwind utility classes that BEEQ ships alongside your custom theme, see Colors → Tailwind CSS.

Full example: Nebula theme

Nebula pairs a fuchsia brand with a cyan accent on violet-tinted neutrals, and adds rounder corners and Space Grotesk type. It changes every component in three short layers:

Root semantics. Brand, accent and the neutral scale, plus the font and radius tokens. BEEQ’s mode roles read from these, so light and dark mode follow on their own.
Mode roles. Four dark-mode overrides: solid brand and accent fills switch to their bright steps, with dark text on top.
Component variables. Two component-level choices: cards sit on the raised surface with a hairline border, and the progress bar uses the accent instead of the brand, on a cyan-tinted track in dark mode.

Nebula doesn’t set info, success, warning or danger, so those keep BEEQ’s values: the info alert stays blue while the brand turns fuchsia. Toggle the mode in the preview to compare both palettes.

Every Nebula value passes the contrast checklist in light and dark mode. If you change a color, check the pairs it affects again.

How overrides work

BEEQ wraps every theme and mode selector in :where(), for example :where([bq-mode="dark"]). :where() has zero specificity, so any selector you write — :root, .promo, [bq-theme="my-custom-theme"], or a component tag — wins over BEEQ’s defaults, whichever stylesheet loads first. You don’t need !important or extra selector weight.

Mode roles reference root semantics (e.g., --bq-ui--brand: var(--bq-brand)), and CSS resolves var() on the element that declares the role. Roles are declared on the theme/mode element, usually <html>, so overriding a root semantic deeper in the tree doesn’t re-derive the roles below it. Override the role itself in that case.

Override levels

Pick the narrowest level that covers your change:

Global
Per mode
Subtree
Component

Change root semantics on :root (or your theme selector). Every mode role that points to them updates in both modes:

:root {
  --bq-brand-light:  #e0f2fe;
  --bq-brand:        #0369a1;
  --bq-brand-dark:   #0c4a6e;
  --bq-brand-strong: #0369a1;
  --bq-brand-bright: #7dd3fc;
}

A mode role set on :root (e.g., --bq-text--on-brand) applies in both modes. Use the per-mode level if light and dark need different values.

Override a mode role for one mode only:

[bq-mode="dark"] {
  --bq-ui--brand:       var(--bq-brand-bright);
  --bq-text--on-brand:  var(--bq-neutral-1000);
}

Override mode roles on a container to restyle everything inside it:

.promo {
  --bq-ui--brand:      var(--bq-purple-600);
  --bq-text--on-brand: var(--bq-white);
}

Setting a root semantic such as --bq-brand on .promo doesn’t change --bq-ui--brand inside it, because the role was already resolved on the root element. Override the roles directly, or set bq-mode on the container so BEEQ re-declares the roles there.

Use a component’s own CSS variables for a one-off change. They’re listed in each component’s Styling section:

bq-alert {
  --bq-alert--background-info: var(--bq-ui--info-alt);
}

Contrast checklist for custom brands

BEEQ’s own themes are checked by an automated contrast test. When you bring your own colors, check these pairs in both modes before you ship. All ratios follow WCAG 2.1 Level AA.

Pair	Minimum
`--bq-{intent}-strong` (light mode) and `--bq-{intent}-bright` (dark mode) on `--bq-background--primary`, `--bq-background--secondary`, `--bq-ui--primary`, `--bq-ui--secondary`	4.5:1
`--bq-text--{intent}` on its tint, `--bq-ui--{intent}-alt`	4.5:1
`--bq-{intent}-bright` on the dark surfaces above and on `--bq-ui--{intent}-alt`	APCA Lc 60
`--bq-text--on-{intent}` on `--bq-ui--{intent}` at rest	4.5:1
`--bq-text--on-{intent}` on the hover and active mixes of `--bq-ui--{intent}` (20% `--bq-hover` / `--bq-active`)	4.5:1
`--bq-text--primary` and `--bq-text--secondary` on primary and secondary surfaces	4.5:1
Icons, `--bq-stroke--tertiary`, `--bq-stroke--{intent}`, and `--bq-focus` on `--bq-background--primary` and `--bq-ui--primary`	3:1

Mid-tone brand colors often can’t reach 4.5:1 with white and stay readable on hover. If white text on your brand fill fails, either use a darker step for the fill in light mode (e.g., --bq-ui--brand: var(--bq-brand-strong)) or pick a dark on-color. Then check the hover and active mixes again — they shift the fill toward a dark neutral.

Get started

Frameworks

Foundations

Theming & customization

Guides

Step-by-step guide

Full example: Nebula theme

How overrides work

Override levels

Contrast checklist for custom brands

​Step-by-step guide

​Full example: Nebula theme

​How overrides work

​Override levels

​Contrast checklist for custom brands

Step-by-step guide

Full example: Nebula theme

How overrides work

Override levels

Contrast checklist for custom brands