Skip to main content

Color Utilities

NuvoUI includes a comprehensive color system with generated scales, automatic contrast calculation, and utilities for creating accessible, beautiful interfaces.

Configuration​

The color system is built on a set of configurable variables and functions:

Basic Colors​

These colors are are solid and do not have any variations or shades. You can also customize them in the configuration.

Base Theme Colors​

NuvoUI defines a set of base theme colors that can be customized:

Color Primitives​

The system uses a set of color primitives as the foundation for the design system:

Theme Configuration​

NuvoUI supports light and dark themes with customizable token values:

Shadow Colors​

Shadow utilities use these configurable color values:

Dark Mode​

Dark mode support can be enabled or disabled:

Color Scales​

Each theme color generates a complete scale of 10 shades (50-900) with consistent lightness steps. The 500 shade represents the original base color.

Primary Scale Example​

Available Color Scales​

NuvoUI generates color scales for the following base colors:

  • Primary - Main brand color
  • Secondary - Supporting brand color
  • Success - Positive actions and outcomes
  • Danger - Critical actions and errors
  • Warning - Cautions and alerts
  • Info - Neutral information

Background Color Utilities​

Apply background colors using the .bg-{color}-{shade} utilities:

Semantic Background Colors​

For consistency, use these semantic background utilities:

Text Color Utilities​

Apply text colors using the .text-{color}-{shade} utilities:

Semantic Text Colors​

For consistency, use these semantic text utilities:

Text Contrast​

For any background color, you can use .text-on-{color}-{shade} to get the right text color:

How it works

The system calculated luminance following the WCAG algorithm and automatically selects black or white text to maintain readability.

Advanced Color Usage​

Adaptive Contrast​

The adaptive-contrast mixin automatically adjusts contrast based on user preferences:

Creating Custom Color Scales​

You can create custom color scales from any color:

Color Utility Reference Table​

Background Color Utilities​

ClassCSS PropertyDescription
.bg-{color}-{shade}background-color: ...Sets background to specified color and shade
.bg-basebackground-color: ...Sets background to page color (theme-dependent)
.bg-basebackground-color: ...Sets background to card color (theme-dependent)
.bg-activebackground-color: ...Sets background to active state color (theme-dependent)
.bg-hoverbackground-color: ...Sets background to hover state color (theme-dependent)

Where {color} can be any of:

  • primary, secondary, success, danger, warning, info
  • gray, red, blue, green, yellow, purple, pink

And {shade} can be any of:

  • 50, 100, 200, 300, 400, 500, 600, 700, 800, 900

Text Color Utilities​

ClassCSS PropertyDescription
.text-{color}-{shade}color: ...Sets text to specified color and shade
.text-defaultcolor: ...Sets text to default color (theme-dependent)
.text-mutedcolor: ...Sets text to muted color (theme-dependent)
.text-subtlecolor: ...Sets text to subtle color (theme-dependent)
.text-invertedcolor: ...Sets text to inverted color (theme-dependent)
.text-on-{color}-{shade}color: ...Sets text color to provide contrast with background

Responsive Color Utilities​

Add @{breakpoint} suffix to any color utility to apply it at a specific breakpoint:

  • .bg-primary-500@md
  • .text-success-700@lg

SCSS Functions and Mixins​

NuvoUI provides a comprehensive set of color functions and mixins for use in your SCSS:

Functions​

FunctionDescriptionParameters
create-color-scale($color)Creates a complete color scale (50-900) from a single color$color: Base color
find-text-color($color)Returns black or white depending on which provides better contrast$color: Background color
luminance($color)Calculates the luminance of a color according to WCAG standards$color: Color to analyze
is-valid-color($color)Checks if a value is a valid color$color: Value to check

Mixins​

MixinDescriptionParameters
adaptive-contrast($color)Sets background color and automatically determines appropriate text color$color: Background color
bg($color)Sets background color$color: Background color value
color($color)Sets text color$color: Text color value
gradient($direction, $colors...)Creates a linear gradient$direction: Direction, $colors: Colors for gradient

Example SCSS Usage​

Best Practices​

Color Usage Guidelines​

  • Use semantic colors over direct color references (e.g., .bg-base instead of .bg-gray-100)
  • For backgrounds with text, always use .text-on-{color}-{shade} to ensure contrast
  • Use lighter shades (50-300) for backgrounds, darker shades (600-900) for text and borders
  • Reserve 400-600 range for buttons, active states, and prominent UI elements

Accessibility​

  • When color conveys meaning, provide additional indicators for colorblind users
  • Test your interface in grayscale to ensure information hierarchy isn't lost
  • Maintain a minimum 4.5:1 contrast ratio for normal text and 3:1 for large text
  • Use adaptive-contrast mixin to support users with increased contrast preferences