Colors - BEEQ Design System

Color in BEEQ serves communication, not decoration. The system gives every color a clear role — brand identity, feedback, hierarchy, or data — so interfaces stay consistent across products and themes.

Always reach for a semantic token (--bq-text--primary, --bq-background--brand, etc.) rather than a raw primitive value. Semantic tokens adapt automatically to light and dark mode. Primitives do not.

Color architecture

BEEQ organizes color in two tiers that work together:

Primitive palette

The raw color values. Named by hue and numeric scale (--bq-iris-600, --bq-grey-200), these are the actual hex values. Use them only when defining a custom theme or creating new semantic tokens — not in component code.

Semantic tokens

The application layer. Named by role (--bq-background--primary, --bq-text--brand), these tokens point to primitives and flip automatically between light and dark values. These are what you use in day-to-day design and development.

Color palette

Brand

The brand color anchors primary actions, interactive states, and brand surfaces. Three stops cover the full light-to-dark range.

bq-brand-light

#e9f0ff

bq-brand

#4f46e5

bq-brand-dark

#181545

Accent

The accent color is reserved for white-label customization. It is not applied in the default BEEQ theme.

bq-accent-light

#efebf8

bq-accent

#6538be

bq-accent-dark

#140b26

Neutral

The neutral scale underpins surfaces, text, borders, and icons. bq-neutral-* tokens are direct aliases of the grey primitive scale.

bq-neutral-50

#f6f6f8

bq-neutral-100

#f1f2f4

bq-neutral-200

#e7e8eb

bq-neutral-300

#caccd2

bq-neutral-400

#a6aab3

bq-neutral-500

#898e99

bq-neutral-600

#646a77

bq-neutral-700

#3f4350

bq-neutral-800

#2a2c35

bq-neutral-900

#1c1d23

bq-neutral-950

#15161a

bq-neutral-1000

#0d0e11

System colors

System colors communicate success, caution, error, and information. Each role has three stops — light (tinted background), main, and dark — for composing surfaces, text, and icons. Never use them for decoration or branding.

bq-success-light

#e5f7f5

bq-success

#00b49d

bq-success-dark

#00241f

bq-warning-light

#fbf4ec

bq-warning

#d99048

bq-warning-dark

#2b1d0e

bq-danger-light

#fce7ea

bq-danger

#e1172f

bq-danger-dark

#2d0509

bq-info-light

#e9f0ff

bq-info

#4f46e5

bq-info-dark

#181545

Focus

The focus color is applied to keyboard focus rings across all interactive components.

bq-focus

#4f46e5

Data colors

A curated set of 12 perceptually distinct hues for charts, graphs, and data-driven visualizations. Use them in sequence — bq-data-01 first — to maintain legibility as more series are added.

bq-data-01

#4f46e5

bq-data-02

#6538be

bq-data-03

#de1395

bq-data-04

#1eb3db

bq-data-05

#00b49d

bq-data-06

#dc6726

bq-data-07

#f2d412

bq-data-08

#e1172f

bq-data-09

#156eeb

bq-data-10

#646a77

bq-data-11

#060708

bq-data-12

#ffffff

The full primitive palette — all hue scales grouped by color — is available in the Primitive color scales reference section below.

Semantic tokens

Semantic tokens are the building blocks of every BEEQ component. They abstract the “what” (raw hex) from the “why” (intended role), so the same design token automatically resolves to the correct light or dark value without manual overrides. Each group below shows both the light and dark values side by side. Click any swatch to copy the CSS custom property name.

Background

Use background tokens for page surfaces, cards, modals, drawers, and overlays.

--bq-background--primary

--bq-background--secondary

--bq-background--tertiary

--bq-background--alt

--bq-background--inverse

--bq-background--brand

var(--bq-brand)

--bq-background--overlay

var(--bq-neutral-900)

Token	Light primitive	Dark primitive	When to use
`--bq-background--primary`	`var(--bq-white)`	`var(--bq-neutral-1000)`	Main page canvas
`--bq-background--secondary`	`var(--bq-neutral-100)`	`var(--bq-neutral-950)`	Panels, sidebars, elevated cards
`--bq-background--tertiary`	`var(--bq-neutral-200)`	`var(--bq-neutral-800)`	Nested sections within cards
`--bq-background--alt`	`var(--bq-neutral-300)`	`var(--bq-neutral-700)`	Hover states on secondary surfaces
`--bq-background--inverse`	`var(--bq-neutral-900)`	`var(--bq-neutral-600)`	Dark banners on light backgrounds
`--bq-background--brand`	`var(--bq-brand)`	`var(--bq-brand)`	Brand callouts, primary action areas
`--bq-background--overlay`	`var(--bq-neutral-900) / 60%`	`var(--bq-neutral-900) / 60%`	Modal scrims, drawer overlays

UI elements

Use UI tokens for interactive component fills — buttons, toggles, chips, selects, and other small shapes.

--bq-ui--primary

--bq-ui--secondary

--bq-ui--tertiary

--bq-ui--inverse

--bq-ui--brand

var(--bq-brand)

--bq-ui--brand-alt

--bq-ui--success

var(--bq-success)

--bq-ui--success-alt

--bq-ui--warning

var(--bq-warning)

--bq-ui--warning-alt

--bq-ui--danger

var(--bq-danger)

--bq-ui--danger-alt

Token	Light primitive	Dark primitive	When to use
`--bq-ui--primary`	`var(--bq-white)`	`var(--bq-neutral-900)`	Default component fill — buttons, cards
`--bq-ui--secondary`	`var(--bq-neutral-100)`	`var(--bq-neutral-950)`	Secondary fill — input backgrounds, toggles
`--bq-ui--tertiary`	`var(--bq-neutral-500)`	`var(--bq-neutral-700)`	Disabled states, placeholder fills
`--bq-ui--inverse`	`var(--bq-neutral-900)`	`var(--bq-neutral-100)`	Inverted fill — dark-on-light component fills
`--bq-ui--brand`	`var(--bq-brand)`	`var(--bq-brand)`	Primary brand buttons, key call-to-action fills
`--bq-ui--brand-alt`	`var(--bq-brand-light)`	`var(--bq-brand-dark)`	Low-emphasis brand fills, badge backgrounds
`--bq-ui--success`	`var(--bq-success)`	`var(--bq-success)`	Success state fills
`--bq-ui--success-alt`	`var(--bq-success-light)`	`var(--bq-success-dark)`	Success tinted backgrounds, alert fills
`--bq-ui--warning`	`var(--bq-warning)`	`var(--bq-warning)`	Warning state fills
`--bq-ui--warning-alt`	`var(--bq-warning-light)`	`var(--bq-warning-dark)`	Warning tinted backgrounds, caution alert fills
`--bq-ui--danger`	`var(--bq-danger)`	`var(--bq-danger)`	Destructive button fills, error states
`--bq-ui--danger-alt`	`var(--bq-danger-light)`	`var(--bq-danger-dark)`	Danger tinted backgrounds, error alert fills

The *-alt variants are tinted backgrounds — use them for low-emphasis states such as badge fills or alert backgrounds.

Stroke

Use stroke tokens for borders, dividers, and outlines.

--bq-stroke--primary

--bq-stroke--secondary

--bq-stroke--tertiary

--bq-stroke--inverse

--bq-stroke--brand

var(--bq-brand)

--bq-stroke--success

var(--bq-success)

--bq-stroke--warning

var(--bq-warning)

--bq-stroke--danger

var(--bq-danger)

Token	Light primitive	Dark primitive	When to use
`--bq-stroke--primary`	`var(--bq-neutral-200)`	`var(--bq-neutral-900)`	Default borders, dividers, separators
`--bq-stroke--secondary`	`var(--bq-neutral-600)`	`var(--bq-neutral-700)`	Emphasis borders, selected outlines
`--bq-stroke--tertiary`	`var(--bq-neutral-900)`	`var(--bq-neutral-400)`	High-contrast borders
`--bq-stroke--inverse`	`var(--bq-white)`	`var(--bq-neutral-950)`	Borders on inverted or dark surfaces
`--bq-stroke--brand`	`var(--bq-brand)`	`var(--bq-brand)`	Focus rings, brand-highlighted outlines
`--bq-stroke--success`	`var(--bq-success)`	`var(--bq-success)`	Success state borders, valid field outlines
`--bq-stroke--warning`	`var(--bq-warning)`	`var(--bq-warning)`	Warning state borders
`--bq-stroke--danger`	`var(--bq-danger)`	`var(--bq-danger)`	Error state borders, invalid field outlines

Text

Use text tokens for all typographic content — headings, body copy, labels, captions. Never apply a raw hex value to text.

--bq-text--primary

--bq-text--secondary

--bq-text--inverse

--bq-text--brand

var(--bq-brand)

--bq-text--success

var(--bq-success)

--bq-text--warning

var(--bq-warning)

--bq-text--danger

var(--bq-danger)

--bq-text--info

var(--bq-brand)

Token	Light primitive	Dark primitive	When to use
`--bq-text--primary`	`var(--bq-neutral-800)`	`var(--bq-neutral-100)`	Main headings, body copy, labels
`--bq-text--secondary`	`var(--bq-neutral-600)`	`var(--bq-neutral-400)`	Supporting text, captions, placeholders
`--bq-text--inverse`	`var(--bq-neutral-50)`	`var(--bq-neutral-800)`	Text on dark/inverted backgrounds
`--bq-text--brand`	`var(--bq-brand)`	`var(--bq-brand)`	Branded links, highlighted labels
`--bq-text--success`	`var(--bq-success)`	`var(--bq-success)`	Confirmation messages, positive feedback
`--bq-text--warning`	`var(--bq-warning)`	`var(--bq-warning)`	Caution text, in-progress states
`--bq-text--danger`	`var(--bq-danger)`	`var(--bq-danger)`	Error messages, destructive confirmations
`--bq-text--info`	`var(--bq-brand)`	`var(--bq-brand)`	Informational callouts

Icons

Use icon tokens for SVG fills. Pair each icon token with the text or background token of the same semantic context — e.g. use --bq-icon--danger alongside --bq-text--danger.

--bq-icon--primary

--bq-icon--secondary

--bq-icon--inverse

--bq-icon--brand

var(--bq-brand)

--bq-icon--success

var(--bq-success)

--bq-icon--warning

var(--bq-warning)

--bq-icon--danger

var(--bq-danger)

--bq-icon--info

var(--bq-brand)

Token	Light primitive	Dark primitive	When to use
`--bq-icon--primary`	`var(--bq-neutral-800)`	`var(--bq-neutral-100)`	Default icon fill
`--bq-icon--secondary`	`var(--bq-neutral-600)`	`var(--bq-neutral-400)`	Subdued icons, decorative marks
`--bq-icon--inverse`	`var(--bq-neutral-50)`	`var(--bq-neutral-800)`	Icons on dark/inverted surfaces
`--bq-icon--brand`	`var(--bq-brand)`	`var(--bq-brand)`	Brand-highlighted icons
`--bq-icon--success`	`var(--bq-success)`	`var(--bq-success)`	Success state icons
`--bq-icon--warning`	`var(--bq-warning)`	`var(--bq-warning)`	Warning state icons
`--bq-icon--danger`	`var(--bq-danger)`	`var(--bq-danger)`	Danger/error state icons
`--bq-icon--info`	`var(--bq-brand)`	`var(--bq-brand)`	Informational icons

Using colors in code

CSS custom properties

Every token is a native CSS custom property. Apply semantic tokens directly to any element:

.card {
  background-color: var(--bq-background--primary);
  border: 1px solid var(--bq-stroke--primary);
  color: var(--bq-text--primary);
}

.badge--success {
  background-color: var(--bq-ui--success-alt);
  color: var(--bq-text--success);
}

.icon--danger {
  fill: var(--bq-icon--danger);
}

Primitive values are equally accessible when you need a specific scale step — for example, building a gradient or a custom illustration:

.hero-gradient {
  background: linear-gradient(
    135deg,
    var(--bq-iris-100),
    var(--bq-iris-600)
  );
}

Tailwind CSS

Add @beeq/tailwindcss to your project to use BEEQ’s semantic tokens as Tailwind utility classes. Tailwind v3 — add it as a preset in tailwind.config.ts:

import beeqPreset from '@beeq/tailwindcss';
import type { Config } from 'tailwindcss';

export default {
  content: ['./src/**/*.{html,ts,tsx,vue}'],
  presets: [beeqPreset],
  theme: {
    extend: {
      // Add your own utilities on top of BEEQ's token set
    },
  },
} satisfies Config;

Tailwind v4 — load it with @plugin in your CSS entry file:

@import "tailwindcss";
@plugin "@beeq/tailwindcss";

Once set up, all semantic tokens are available as utility classes:

Category	Tailwind prefix	Example class
Background	`bg-`	`bg-primary`, `bg-brand`, `bg-inverse`
Text	`text-`	`text-primary`, `text-secondary`, `text-danger`
Border	`border-`	`border-primary`, `border-brand`, `border-danger`
Icon fill	`fill-`	`fill-primary`, `fill-brand`, `fill-success`
UI fill	`bg-ui-*`	`bg-ui-brand`, `bg-ui-success`, `bg-ui-danger-alt`
Data fill	`bg-data-*`	`bg-data-01`, `bg-data-05`

Primitive hues are also available as standard Tailwind color utilities:

<!-- Semantic tokens (recommended) -->
<div class="bg-primary text-primary border border-primary">…</div>
<p class="text-secondary">Supporting text</p>
<span class="text-danger">Error message</span>

<!-- Brand badge using semantic tokens -->
<span class="bg-ui-brand text-alt rounded-full px-s py-xs2 text-s font-semibold">
  New
</span>

<!-- Success state -->
<div class="bg-ui-success-alt border border-success text-success rounded-s p-m">
  Changes saved successfully.
</div>

<!-- Primitive hue (use sparingly — only for custom illustrations or theme overrides) -->
<span class="bg-iris-100 text-iris-800">Custom highlight</span>

To apply a custom brand, override the CSS custom properties in your stylesheet — the utility classes resolve to whatever the CSS variables point to. See Overriding tokens — CSS in the Theming section below.

Color guidelines

Use semantic tokens for all component and layout styling
Apply --bq-background--brand to primary action surfaces
Use system tokens (--bq-text--danger, --bq-ui--success) for feedback states
Use data colors (data-01 → data-12) for all chart series
Test every custom color combination for sufficient contrast

Don’t

Hard-code hex values in component styles — always use a token
Use the brand color as a large background surface; it creates visual overload
Apply system colors (success, warning, danger) for decoration or branding
Mix more than 4–5 hues in a single view
Rely on color alone to communicate state or meaning

Accessibility

Color alone must never be the only way information is communicated. Always pair color with text labels, icons, or patterns. BEEQ semantic tokens are designed to meet WCAG 2.1 Level AA contrast requirements when used as documented:

Token pair	Use context	Contrast ratio
`--bq-text--primary` on `--bq-background--primary`	Body text, headings	≥ 7:1 (AAA)
`--bq-text--secondary` on `--bq-background--primary`	Supporting text, labels	≥ 4.5:1 (AA)
`--bq-text--inverse` on `--bq-background--inverse`	Inverted surfaces	≥ 7:1 (AAA)
`--bq-text--brand` on `--bq-background--primary`	Large text, UI labels only	≥ 3:1
`--bq-text--danger` on `--bq-background--primary`	Error text	≥ 4.5:1 (AA)

--bq-text--brand on white does not meet AA for small body text. Use it only for large text (18px+ or 14px+ bold) or non-text UI elements.

Verify custom color pairings with the WebAIM Contrast Checker or the APCA Contrast Calculator before shipping. The mint a11y CLI command can also flag contrast issues in your documentation automatically.

When customizing a theme, ensure the full semantic token set is re-validated against WCAG 2.1 AA. Changing a single primitive alias can affect dozens of tokens simultaneously.

Theming and customization

Designers: need to build a custom palette for a client project before applying it in Figma? See Building your color palette.

All BEEQ components read colors from CSS custom properties. Overriding those properties is the one universal mechanism for applying a custom brand — no library modifications needed, and it works regardless of your styling tool. If your project also uses Tailwind, adding @beeq/tailwindcss makes your own utility classes (bg-brand, text-primary, etc.) resolve to the same tokens. The two approaches are independent and complementary — the Tailwind integration does not replace CSS overrides, it builds on top of them.

Overriding tokens — CSS

Set your brand values in your own stylesheet. Every BEEQ component picks them up automatically:

/* your-theme.css */
:root {
  --bq-brand: #0ea5e9;
  --bq-brand-light: #e0f2fe;
  --bq-brand-dark: #0c4a6e;

  /* Adjust system colors if needed */
  --bq-success: #16a34a;
  --bq-success-light: #dcfce7;
  --bq-success-dark: #14532d;
}

Scope overrides to a specific selector for themed sections or multi-brand layouts:

[data-theme="acme"] {
  --bq-brand: #f97316;
  --bq-brand-light: #fff7ed;
  --bq-brand-dark: #431407;
}

This works identically whether you use plain CSS, Sass, PostCSS, or Tailwind’s @layer.

Primitive color scales

The complete raw hue scales — grouped by color, not by meaning. Each step is available as var(--bq-{hue}-{scale}). Use these when tracing which raw value backs a semantic token or when defining a custom theme.

Blue

Corai

Cyan

Gold

Green

Grey

Indigo

Iris

Lime

Magenta

Orange

Purple

Red

Sky

Teal

Volcano

Yellow

Resources

Custom theming

Full walkthrough for applying a custom brand, including light/dark mode token overrides.

GitHub — Theme source

Browse the full primitive palette, semantic tokens, and theme definitions.

​Color architecture

Primitive palette

Semantic tokens

​Color palette

​Brand

​Accent

​Neutral

​System colors

​Focus

​Data colors

​Semantic tokens

​Background

​UI elements

​Stroke

​Text

​Icons

​Using colors in code

​CSS custom properties

​Tailwind CSS

​Color guidelines

​Accessibility

​Theming and customization

​Overriding tokens — CSS

​Primitive color scales

​Resources

Custom theming

GitHub — Theme source

Color architecture

Color palette

Brand

Accent

Neutral

System colors

Focus

Data colors

Semantic tokens

Background

UI elements

Stroke

Text

Icons

Using colors in code

CSS custom properties

Tailwind CSS

Color guidelines

Accessibility

Theming and customization

Overriding tokens — CSS

Primitive color scales

Resources