Color System

A comprehensive guide to using Blueprint UI's semantic color tokens, themes, and CSS custom properties for consistent and accessible interfaces.

Core Concepts

Our color system is built on HSL values and CSS custom properties, enabling dynamic theming and customization. Key principles include:

  • Utilizes CSS custom properties (variables) for all color definitions.
  • Supports multiple themes: Light (default), Dark, and Modern, out of the box.
  • Theme definitions are located in app/colors.css. This file is intended for customization and is updated by the Theme Customizer tool.
  • A reference copy of the original theme values (as scaffolded by the CLI) is available in app/colors-default.css.
  • Maintains semantic naming for color tokens (e.g., --primary, --background) for better maintainability.
  • Follows a foreground/background pattern for consistent contrast across components and themes.
  • Integrated with Tailwind CSS for easy utility class usage (e.g., bg-primary, text-foreground).

Applying Themes

Blueprint UI themes can be applied globally to your entire application or locally to specific sections using the ThemeSection component.

The themes (Light, Dark, Modern) are defined in app/colors.css using class selectors (e.g., .dark, .modern) and section-specific classes (e.g., .section-theme-dark).

Global Theming

To apply a theme globally, add the corresponding class (dark or modern) to the <html> or <body> tag in your app/layout.js. The light theme is applied by default if no theme class is specified.

// To apply the Dark theme globally (e.g., in app/layout.js)
export default function RootLayout({ children }) {
  return (
    <html lang="en" className="dark" suppressHydrationWarning>
      {/* ... rest of the layout ... */}
    </html>
  );
}

Section-Specific Theming

Use the ThemeSection component to apply a theme to a specific part of your page. This component wraps its children in a <div> and applies the appropriate theme class (e.g., section-theme-dark) or data attribute, ensuring correct color inheritance.

import ThemeSection from '@/components/snippets/Customizer/theme-section';


export default function MyPage() {
  return (
    <>
      <ThemeSection theme="light">
        <div className="p-8">
          <h1 className="text-foreground">Light Section Content</h1>
          <button className="bg-primary text-primary-foreground">Button</button>
        </div>
      </ThemeSection>


      <ThemeSection theme="dark">
        <div className="p-8">
          <h1 className="text-foreground">Dark Section Content</h1>
          <button className="bg-primary text-primary-foreground">Button</button>
        </div>
      </ThemeSection>


      <ThemeSection theme="modern">
        <div className="p-8">
          <h1 className="text-foreground">Modern Section Content</h1>
          <button className="bg-primary text-primary-foreground">Button</button>
        </div>
      </ThemeSection>
    </>
  );
}

The ThemeSection component ensures that all Blueprint UI components within it correctly inherit the specified section's theme colors.

Base Colors

The foundation of our color system starts with background and foreground colors.

Background Color

bg-background

Foreground Color

text-foreground

// Base colors for backgrounds and text
<div className="bg-background text-foreground">
  Main content
</div>


// With different opacities
<div className="bg-background/90">
  90% opacity background
</div>

Semantic Colors

Color tokens that describe their purpose rather than their appearance.

// Primary colors
<button className="bg-primary text-primary-foreground hover:bg-primary/90">
  Primary Button
</button>


// Secondary colors
<button className="bg-secondary text-secondary-foreground hover:bg-secondary/80">
  Secondary Button
</button>


// Accent colors
<div className="bg-accent text-accent-foreground p-4">
  Accent Section
</div>


// Success colors
<div className="bg-success text-success-foreground p-4">
  Success Section
</div>


// Destructive colors
<button className="bg-destructive text-destructive-foreground">
  Delete
</button>


// Muted colors
<p className="text-muted-foreground">
  Muted text content
</p>

Text Hierarchy

Creating clear visual hierarchy using different text colors.

Main Heading

Supporting text content that provides additional context

Disabled or inactive text element
// Primary text
<h1 className="text-foreground text-2xl font-bold">
  Main Heading
</h1>


// Secondary text
<p className="text-muted-foreground">
  Supporting text content
</p>


// Disabled text
<span className="text-muted-foreground/60">
  Disabled or inactive text
</span>

Best Practices

Guidelines for using color tokens effectively.

Do

// DO: Use semantic color tokens
<div className="bg-background text-foreground">
  <button className="bg-primary text-primary-foreground">
    Click me
  </button>
</div>
  • Use semantic color tokens
  • Match colors to their purpose
  • Consider dark mode support

Don't

// DON'T: Use raw color values
<div className="bg-white text-black">
  <button className="bg-blue-500 text-white">
    Click me
  </button>
</div>
  • Use raw color values
  • Mix semantic and visual colors
  • Ignore color contrast

Exporting & Using Color Variables

All colors in Blueprint UI are defined as CSS custom properties (variables) in HSL format within app/colors.css. This makes them highly reusable and accessible.

You can directly use these CSS variables in your own custom stylesheets to maintain consistency with the Blueprint UI theming system. The tailwind.config.js file provided by the CLI is already configured to use these variables for its color palette.

CSS Variable Structure

Here’s a simplified look at how color variables are defined in app/colors.css for different themes:

/* app/colors.css (snippet) */
@layer base {
  :root, /* Light Theme (default) */
  .section-theme-light {
    --background: 0 0% 100%;
    --foreground: 0 0% 12%;
    --primary: 220 14% 24%;
    /* ... other light theme variables */
  }


  .dark,
  .section-theme-dark {
    --background: 225 15% 8%;
    --foreground: 220 10% 92%;
    --primary: 220 10% 80%;
    /* ... other dark theme variables */
  }


  .modern,
  .section-theme-modern {
    --background: 215 30% 97%;
    --foreground: 215 35% 15%;
    --primary: 215 60% 45%;
    /* ... other modern theme variables */
  }
}

Using Variables in Custom CSS

To use these variables in your own CSS rules, use the hsl(var(...)) syntax:

/* In your custom CSS file */
.my-custom-component {
  background-color: hsl(var(--accent));
  color: hsl(var(--accent-foreground));
  border: 1px solid hsl(var(--border));
}


.my-custom-component:hover {
  background-color: hsl(var(--primary));
  color: hsl(var(--primary-foreground));
}

Theme Customizer

The built-in Theme Customizer tool directly modifies the HSL values in app/colors.css. Any changes you make through the customizer will be saved to this file, allowing for persistent theme adjustments.