Color Tokens

@duskmoon-dev/core provides 65+ color tokens based on Material Design 3’s dynamic color system. All tokens are generated from @duskmoon-dev/design YAML files in OKLCH format and delivered as CSS custom properties. Components use color-mix(in oklch, ...) for hover/focus states, which works regardless of the input color format.

Token Naming Convention

DuskMoonUI uses two naming patterns for text-on-background tokens:

• -content (e.g., --color-primary-content) — text color on filled backgrounds. Use when the parent has a solid brand/semantic color.
• on-*-container (e.g., --color-on-primary-container) — text color on container (lighter) backgrounds. Use when the parent has a soft container background.

Both patterns are standard in Material Design 3. The -content suffix is used for the full-intensity color role; the on- prefix is used for container-level roles.

Color Token Categories

Primary Colors

The main brand color used for key UI elements like buttons, links, and active states.

/* Primary color tokens */
--color-primary              /* Main brand color */
--color-primary-content      /* Text on primary */
--color-primary-container    /* Light background variant */
--color-on-primary-container /* Text on container */

Secondary Colors

Complementary accent color for secondary actions and elements.

/* Secondary color tokens */
--color-secondary              /* Accent brand color */
--color-secondary-content      /* Text on secondary */
--color-secondary-container    /* Light background variant */
--color-on-secondary-container /* Text on container */

Tertiary Colors

Third brand color unique to @duskmoon-dev/core for additional visual variety.

/* Tertiary color tokens */
--color-tertiary              /* Third brand color */
--color-tertiary-content      /* Text on tertiary */
--color-tertiary-container    /* Light background variant */
--color-on-tertiary-container /* Text on container */

Surface Colors

Background and surface colors with Material Design 3’s five-level elevation system.

Surface Container Elevation Levels

/* Surface color tokens */
--color-surface                   /* Base surface */
--color-surface-dim               /* Dimmed surface */
--color-surface-bright            /* Bright surface */
--color-surface-container-lowest  /* Elevation level 0 */
--color-surface-container-low     /* Elevation level 1 */
--color-surface-container         /* Elevation level 2 (default) */
--color-surface-container-high    /* Elevation level 3 */
--color-surface-container-highest /* Elevation level 4 */
--color-on-surface                /* Primary text color */
--color-on-surface-variant        /* Secondary text color */
--color-surface-variant           /* Alternative surface */

Base Colors (Neutral Scale)

DaisyUI-compatible neutral color scale for general UI elements.

/* Base (neutral) color scale */
--color-base-100     /* Lightest neutral */
--color-base-200
--color-base-300
--color-base-400
--color-base-500
--color-base-600
--color-base-700
--color-base-800
--color-base-900     /* Darkest neutral */
--color-base-content /* Text on base colors */

Semantic Colors

Dedicated colors for specific UI states and feedback.

Info (Blue)

Success (Green)

Warning (Yellow)

Error (Red)

/* Semantic color tokens for each state */
--color-info               --color-info-content
--color-info-container     --color-on-info-container

--color-success            --color-success-content
--color-success-container  --color-on-success-container

--color-warning            --color-warning-content
--color-warning-container  --color-on-warning-container

--color-error              --color-error-content
--color-error-container    --color-on-error-container

Outline Colors

Border and divider colors.

/* Outline tokens */
--color-outline         /* Primary borders */
--color-outline-variant /* Subtle borders */

Accent Colors

A highlight color for emphasis and interactive elements.

/* Accent color tokens */
--color-accent         /* Highlight color */
--color-accent-content /* Text on accent */

Neutral Colors

Used for backgrounds, borders, and muted UI elements.

/* Neutral color tokens */
--color-neutral         /* Neutral background */
--color-neutral-content /* Text on neutral */
--color-neutral-variant /* Muted variant */

Inverse Colors

For elements that need to contrast strongly against the current surface, like snackbars and tooltips.

/* Inverse color tokens */
--color-inverse-surface    /* Inverted background */
--color-inverse-on-surface /* Text on inverted bg */
--color-inverse-primary    /* Primary on inverted bg */

Shadow & Scrim

Used for elevation shadows and overlay scrims (modal backdrops).

--color-shadow /* Base color for elevation shadows */
--color-scrim  /* Base color for overlay scrims */

Elevation Shadows

Theme-aware shadow tokens that use --color-shadow with color-mix() for proper opacity. These adapt automatically when switching between light and dark themes.

--shadow-xs  /* Subtle elevation (1px) */
--shadow-sm  /* Low elevation (cards) */
--shadow-md  /* Medium elevation (dropdowns) */
--shadow-lg  /* High elevation (modals) */
--shadow-xl  /* Higher elevation */
--shadow-2xl /* Maximum elevation */

<!-- Shadow usage via Tailwind utilities -->
<div class="shadow-sm">Low elevation card</div>
<div class="shadow-md">Dropdown menu</div>
<div class="shadow-lg">Modal dialog</div>

<!-- Or via CSS custom properties -->
<div style="box-shadow: var(--shadow-md);">Custom element</div>

MD3 Elevation Levels

Semantic elevation tokens map Material Design 3 levels (0–5) to shadow effects. Use these when you want to express UI hierarchy rather than specific shadow sizes.

--shadow-elevation-0  /* Level 0: No shadow (flat) */
--shadow-elevation-1  /* Level 1: Subtle lift (maps to --shadow-xs) */
--shadow-elevation-2  /* Level 2: Cards, raised surfaces (maps to --shadow-sm) */
--shadow-elevation-3  /* Level 3: Dropdowns, menus (maps to --shadow-md) */
--shadow-elevation-4  /* Level 4: Dialogs, modals (maps to --shadow-lg) */
--shadow-elevation-5  /* Level 5: Maximum prominence (maps to --shadow-xl) */

<!-- Elevation utility classes -->
<div class="elevation-0">Flat surface</div>
<div class="elevation-1">Slightly raised</div>
<div class="elevation-2">Card surface</div>
<div class="elevation-3">Dropdown menu</div>
<div class="elevation-4">Modal dialog</div>
<div class="elevation-5">Top-level overlay</div>

<!-- Also available as Tailwind shadow utilities -->
<div class="shadow-elevation-3">Dropdown via Tailwind</div>

Using Color Tokens

Tailwind Utility Classes

<!-- Backgrounds -->
<div class="bg-primary">Primary background</div>
<div class="bg-surface-container">Elevated surface</div>

<!-- Text -->
<p class="text-primary">Primary colored text</p>
<p class="text-on-surface">Standard body text</p>
<p class="text-on-surface-variant">Secondary text</p>

<!-- Borders -->
<div class="border border-outline">Standard border</div>
<div class="border border-outline-variant">Subtle border</div>

CSS Custom Properties

.custom-element {
  background-color: var(--color-primary);
  color: var(--color-primary-content);
  border: 1px solid var(--color-outline);
}

/* Overlay with opacity using color-mix */
.overlay {
  background-color: color-mix(in srgb, var(--color-surface) 80%, transparent);
}

/* Focus/hover states using color-mix in OKLCH */
.interactive:hover {
  background-color: color-mix(in oklch, var(--color-primary), black 10%);
}

Opacity Variants

Apply opacity to any color:

<div class="bg-primary/50">50% opacity primary</div>
<div class="bg-primary/75">75% opacity primary</div>
<div class="text-primary/80">80% opacity text</div>

Color Token Count

Category	Token Count
Primary	4
Secondary	4
Tertiary	4
Accent	2
Neutral	3
Surface	11
Base	10
Info	4
Success	4
Warning	4
Error	4
Outline	2
Inverse	3
Shadow/Scrim	2
Shadows	6
Total	65

Theme Comparison

Switch between themes to see how colors adapt:

Related Resources

• Theming Overview - Understanding the theme system
• Theme Customization - Adjust sunshine and moonlight
• WCAG Contrast Guidelines