Global Theme Variables

This page lists the global CSS variables exposed through globals.scss and used throughout Boreal UI.
Variables are grouped into smaller tables so they are easier to browse and search by category.

Colors

Brand, semantic, and supporting color tokens.

Sortable data table
Variable	Usage
--error-color	Color for error messages or failure states
--error-color-hover	Hover color for error-based UI states
--primary-color	Main brand color for primary buttons, highlights, and accents
--primary-color-hover	Darker variant of the primary color for hover states
--primary-color-light	Lighter variant of the primary color for subtle accents
--quaternary-color	Optional quaternary color used for additional accents
--quaternary-color-hover	Darker variant of the quaternary color
--quaternary-color-light	Lighter variant of the quaternary color
--secondary-color	Secondary brand color used for secondary buttons and accents
--secondary-color-hover	Darker variant of the secondary color
--secondary-color-light	Lighter variant of the secondary color
--success-color	Color for success messages or positive states
--success-color-hover	Hover color for success-based UI states
--tertiary-color	Optional tertiary color used for supporting UI elements
--tertiary-color-hover	Darker variant of the tertiary color
--tertiary-color-light	Lighter variant of the tertiary color
--text-color-primary	Text color that contrasts well on primary surfaces
--text-color-primary-contrast	Contrast text token paired with the primary surface
--text-color-quaternary	Text color that contrasts well on quaternary surfaces
--text-color-secondary	Text color that contrasts well on secondary surfaces
--text-color-tertiary	Text color that contrasts well on tertiary surfaces
--warning-color	Color for warnings or caution states
--warning-color-hover	Hover color for warning-based UI states

Backgrounds

Background and surface-related tokens.

Sortable data table
Variable	Usage
--background-color	Default background color for the page
--background-color-dark	Slightly darker variant of the background color
--background-color-darker	Even darker variant of the background color
--background-color-light	Slightly lighter variant of the background color
--background-color-lighter	Even lighter variant of the background color
--background-color-surface	Surface background color for cards, panels, and modals

Text

Text and readability tokens.

Sortable data table
Variable	Usage
--text-color	Default text color for most UI elements
--text-color-light	Muted text color for secondary content
--text-color-lighter	Faint text color for subtle or disabled content

Links

Link styling tokens.

Sortable data table
Variable	Usage
--link-color	Default color for links
--link-hover-color	Color for links when hovered
--link-hover-color-primary	Primary color for link hover states
--link-hover-color-secondary	Secondary color for link hover states

Interaction

Focus, overlays, disabled states, and UI interaction tokens.

Sortable data table
Variable	Usage
--disabled-color	Color for disabled elements
--divider-color	Color used for dividers and borders
--focus-outline-color	Outline color for focus states
--overlay-color	Overlay color for modals or dropdown backdrops

Spacing

Spacing scale used for padding, gaps, and margins.

Sortable data table
Variable	Usage
--spacing-lg	Large spacing token
--spacing-md	Medium spacing token
--spacing-sm	Small spacing token
--spacing-xl	Extra large spacing token
--spacing-xs	Extra small spacing token
--spacing-xxs	Extra extra small spacing token

Typography

Font families, sizes, weights, line heights, and semantic text roles.

Sortable data table
Variable	Usage
--font-family-body	Font family used for body copy
--font-family-heading	Font family used for headings
--font-family-mono	Monospace font family for code text
--font-family-primary	Primary font family token
--font-family-secondary	Secondary font family token
--font-family-ui	Font family used for controls and UI text
--font-size-base	Default font size token
--font-size-body	Semantic font size for body text
--font-size-body-lg	Semantic font size for large body text
--font-size-body-sm	Semantic font size for small body text
--font-size-caption	Semantic font size for captions
--font-size-display	Largest semantic text size for display headings
--font-size-h1	Semantic font size for h1 text
--font-size-h2	Semantic font size for h2 text
--font-size-h3	Semantic font size for h3 text
--font-size-h4	Semantic font size for h4 text
--font-size-h5	Semantic font size for h5 text
--font-size-h6	Semantic font size for h6 text
--font-size-label	Semantic font size for labels
--font-size-lg	Large font size token
--font-size-md	Medium font size token
--font-size-overline	Semantic font size for overline text
--font-size-sm	Small font size token
--font-size-xl	Extra large font size token
--font-size-xs	Extra small font size token
--font-size-xxl	Extra extra large font size token
--font-size-xxs	Extra extra small font size token
--font-weight-body	Default body text font weight
--font-weight-bold	Bold font weight token
--font-weight-bolder	Extra bold font weight token
--font-weight-code	Default code text font weight
--font-weight-heading	Default heading font weight
--font-weight-label	Default label font weight
--font-weight-light	Light font weight token
--font-weight-medium	Medium font weight token
--font-weight-normal	Normal font weight token
--letter-spacing-body	Letter spacing for body text
--letter-spacing-caption	Letter spacing for captions
--letter-spacing-code	Letter spacing for code text
--letter-spacing-display	Letter spacing for display text
--letter-spacing-heading	Letter spacing for headings
--letter-spacing-label	Letter spacing for labels
--letter-spacing-overline	Letter spacing for overline text
--line-height-body	Line height for body text
--line-height-caption	Line height for caption text
--line-height-code	Line height for code text
--line-height-display	Line height for display text
--line-height-heading	Line height for heading text
--line-height-label	Line height for label text

Border Radius

Rounding tokens used across components.

Sortable data table
Variable	Usage
--border-radius-full	Full rounding for pill or circular shapes
--border-radius-lg	Large border radius token
--border-radius-md	Medium border radius token
--border-radius-none	No rounding for UI elements
--border-radius-round	Round border radius token for circular elements
--border-radius-sm	Small border radius token
--border-radius-xl	Extra large border radius token
--border-radius-xs	Extra small border radius token

Shadows

Standard elevation tokens.

Sortable data table
Variable	Usage
--box-shadow-heavy	Strong shadow for prominent elevation
--box-shadow-intense	Intense shadow for deep elevation
--box-shadow-light	Light shadow for subtle elevation
--box-shadow-medium	Medium shadow for moderate elevation
--box-shadow-none	No shadow

Inverted Shadows

Inverted shadow tokens for dark or alternative surfaces.

Sortable data table
Variable	Usage
--box-shadow-inverted-intense	Intense inverted shadow
--box-shadow-inverted-light	Light inverted shadow
--box-shadow-inverted-medium	Medium inverted shadow
--box-shadow-inverted-none	No inverted shadow
--box-shadow-inverted-strong	Strong inverted shadow

Transitions

Motion timing tokens.

Sortable data table
Variable	Usage
--transition-default	Default transition duration
--transition-fast	Fast transition duration
--transition-slow	Slow transition duration

Updating Non-Context Variables

Variables such as spacing, typography, border radius, and shadows are not managed by the ThemeProvider and should be updated directly in your global styles.

1. Import Boreal UI Styles

Import the library styles before your custom overrides:

// React (Core) entry file: src/index.tsx
import "boreal-ui/core/boreal-ui.css";

// Next.js entry file: app/layout.tsx
import "boreal-ui/next/boreal-ui.css";

2. Define Variables in `globals.scss` or `globals.css`

Add or override your tokens inside :root.

/* globals.scss or globals.css */
:root {
  --font-family-body: "Inter", Arial, sans-serif;
  --font-family-heading: "Lora", serif;

  --font-size-body: 18px;
  --font-size-h1: 40px;
  --font-size-label: 14px;

  --font-weight-body: 400;
  --font-weight-heading: 700;
  --font-weight-label: 600;

  --line-height-body: 1.6;
  --line-height-heading: 1.2;

  --letter-spacing-body: 0;
  --letter-spacing-overline: 0.08em;

  --spacing-sm: 8px;
  --spacing-md: 16px;
  --spacing-lg: 32px;

  --border-radius-sm: 4px;
  --border-radius-lg: 12px;

  --box-shadow-light: 0 2px 4px rgba(0, 0, 0, 0.1);
  --box-shadow-medium: 0 4px 8px rgba(0, 0, 0, 0.2);
}

3. Import Your Global Styles After Boreal UI

Import your own global stylesheet after Boreal UI so your custom variables override the defaults.

React (Core)

// src/index.tsx
import React from "react";
import ReactDOM from "react-dom/client";
import App from "./App";
import "boreal-ui/core/boreal-ui.css";
import "./globals.scss";

ReactDOM.createRoot(document.getElementById("root")!).render(<App />);

Next.js

// app/layout.tsx
import "boreal-ui/next/boreal-ui.css";
import "./globals.css";

export default function RootLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <html lang="en">
      <body>{children}</body>
    </html>
  );
}