Color System

The color system is built around 11 semantic colors, each with a specific purpose. Instead of raw hex or RGB values, components consume colors through the Color enum. The framework then resolves each color to the correct CSS classes for every variant and context.

This approach ensures consistency: changing a color definition in one place updates every component that uses it. The underlying values use OKLCH for perceptually uniform shade palettes that look correct across light and dark modes.

All 11 colors rendered as live Button components in each of the 3 variants: Filled, Outlined, and Text. These are real components using the actual color system.

Each color has a defined semantic purpose. Use the right color for the right context to keep the UI consistent and accessible.

The ColorPaletteRegistry.Resolve(Color) method returns a ColorPalette record with 56 CSS class properties. Components use this internally to map a Color enum value to the correct Tailwind classes for every variant and context.

// Internal usage — components resolve their color classes via the registry
var palette = ColorPaletteRegistry.Resolve(Color.Primary);

// Each property returns ready-to-use Tailwind CSS class strings
// e.g. palette.FilledButtonClasses → "border-... bg-[var(--ui-color-primary-filled-bg)] text-..."
// e.g. palette.BorderOutlined     → "border-app-border-strong"
// e.g. palette.TextOnFilled       → "text-[var(--ui-color-primary-filled-text)] ..."

The 56 properties are grouped by category. Each property contains ready-to-use CSS class strings that include background, border, text color, hover states, and dark mode overrides.

All color values are defined as CSS custom properties following a consistent naming pattern. Variant-specific properties (filled, outlined, text) reference the underlying shade palette.

/* Naming pattern for CSS custom properties */
--ui-color-{colorname}-{variant}-{type}

/* Examples */
--ui-color-primary-filled-bg
--ui-color-primary-filled-text
--ui-color-primary-filled-border
--ui-color-primary-outlined-bg
--ui-color-primary-outlined-text
--ui-color-primary-outlined-border
--ui-color-primary-text-bg
--ui-color-primary-text-text
--ui-color-primary-text-border

/* Dark mode suffix */
--ui-color-primary-filled-bg-dark
--ui-color-primary-outlined-bg-dark

Each color defines a tonal shade palette with 11 steps from 50 (lightest) to 950 (darkest). Shades are generated using a perceptually uniform tone scale, meaning each step looks evenly spaced to the human eye regardless of hue.

/* Tonal shade palette — each color defines 11 shades from 50 (lightest) to 950 (darkest) */
--ui-color-primary-50:  /* Tone 95 — very light tint */
--ui-color-primary-100: /* Tone 90 */
--ui-color-primary-200: /* Tone 80 */
--ui-color-primary-300: /* Tone 70 */
--ui-color-primary-400: /* Tone 60 */
--ui-color-primary-500: /* Tone 50 — perceptual midpoint */
--ui-color-primary-600: /* Tone 40 */
--ui-color-primary-700: /* Tone 30 */
--ui-color-primary-800: /* Tone 20 */
--ui-color-primary-900: /* Tone 10 */
--ui-color-primary-950: /* Tone 5  — very dark shade */

/* Used in variant variables */
--ui-color-primary-filled-bg: /* resolved from shade config (e.g. shade 300) */
--ui-color-primary-outlined-bg: /* resolved from shade config (e.g. shade 100) */

Each seed color in the theme produces a palette of 11 shades. The palette is generated algorithmically using a perceptually uniform tone scale: the seed color's hue is preserved across all shades while the lightness is set to specific target tones.

The algorithm extracts hue and chroma from the seed color, then creates 11 shades by setting the tone (perceptual lightness on a 0-100 scale) to fixed target values. Chroma is automatically adjusted at the extremes to keep colors within the sRGB gamut.

The gamut mapping ensures all generated colors are valid sRGB values. For very vivid seed colors, the chroma is reduced at extreme tones (very light or very dark) to prevent out-of-gamut colors.

The color system is implemented across these files in the Sillium.Core.Blazor project.