What light-dark() does

light-dark() accepts two color arguments and picks between them according to the user's color scheme preference. It became Baseline in May 2024. The function only works when the color-scheme property is used to enable both modes:

:root {
  color-scheme: light dark;
}

.element {
  color: light-dark(brown, black);
}

Whichever mode matches the user's preference is then applied.

The case for more modes

The two-mode limitation is the interesting question here: should light-dark() cover color schemes beyond light and dark, such as grayscale, high contrast or low contrast preferences?

The function's history suggests it was never meant to be the endpoint. When Emilio Cobos requested a function for light and dark mode changes around 2022 and it was added to the specifications, the ticket was closed. Jacob Miller then commented that the approach "doesn't actually solve for the issues people are facing with theming" and argued that the platform shouldn't ship "single-purpose tools for the browser, but rather ones that scale and we can build upon." Bramus reopened the ticket and clarified the intent:

The end goal is to have something like schemed-value(), with light-dark() being an intermediary step towards the final solution.

Custom color schemes are a prerequisite

Extending light-dark() is not the first step. The color-scheme property has to grow values beyond light and dark first, because light-dark() depends on that property to function. Concretely, color-scheme would need to accept a custom scheme value.

Tab Atkins sketched a possible approach in the ticket: register a custom color scheme in a @color-scheme at-rule that defines the scheme's properties, including what color keywords map to, then reference that scheme's ident on color-scheme at the root element:

@color-scheme --high-contast {
  base-scheme: dark;
  canvascolor: black;
  canvastext: white;
  accentcolor: white;
  /* other properties set to specific colors */
}

html {
  color-scheme: --high-contrast;
}

Once registered, the custom scheme can be used as its own standalone value in schemed-value():

@color-scheme --high-contast {
  /* ... */
}

html {
  color-scheme: --high-contrast light dark;
}

body {
  color: schemed-value(--high-contrast, black, white);
}

The flow breaks down as follows:

  • A custom scheme such as --high-contrast is registered in a @color-scheme at-rule.
  • The at-rule defines the scheme's properties, such as whether its base theme is light or dark and what certain color keywords map to.
  • The scheme is declared on the color-scheme property at the root level, e.g. html { color-scheme: --high-contrast; }.
  • Color-related properties apply the scheme through the schemed-value() function.

So the change reaches beyond light-dark() itself: color-scheme would most likely get its own at-rule for custom values.

Why light-dark() itself needn't change

Bramus has addressed the extension question directly: "When schemed-value() ever becomes a thing, light-dark() would become syntactic sugar for it." That means light-dark() doesn't need multi-mode support, because schemed-value() can provide that capability on its own:

light-dark(<color>, <color>); = schemed-value(light <color>, dark <color>);

The same pattern shows up outside color schemes. An open ticket proposes extending light-dark() to images, and the discussion there appears to favor a separate, dedicated function instead. Similarly, work on custom functions using if() led to a demonstration of how light-dark() could be replicated with a custom CSS function:

:root {
  /* ensures light mode comes first */
  --scheme: light;

  /* dark mode is set here */
  @media (prefers-color-scheme: dark) {
    --scheme: dark;
  }
}

/* custom function returns any two values depending on whether system is in light or dark mode */
@function --light-dark(--light-color, --dark-color) {
  result: if(style(--scheme: dark): var(--dark-color) ; else: var(--light-color));
}

p {
  font-size: --light-dark(
    2rem,
    2.5rem
  ); /* returns 2rem if system is in light mode and 2.5rem if system is in dark mode */
}

Nothing is settled. What is certain: light-dark() works today and is Baseline widely available, while custom functions remain a work in progress, available only in Chromium-based browsers at the time of writing.

Where this leaves the question

light-dark() is an intermediary step, and while it could be extended to support multiple modes and custom color schemes, it doesn't have to be. Registering and defining a custom scheme in an at-rule, and making color-scheme able to read it, preserves a simple two-mode function that can be abstracted further when needed.