Palettes

[gfellerph]

Context

What is the issue that we're seeing that is motivating this decision or change?

Decision

Semantic layer order matters for setting up cascade

POC: https://codepen.io/alizedebray/pen/QwWVXzm?editors=1100

Static colour scheme layer vs. dynamic colour scheme layer

Palette background colours are static based on the root colour scheme. Having palette colours on the static scheme layer enables us to set color-scheme directly on the palette because the background of the palette is not set with light-dark().

Difference: Static colour scheme components are setting color-scheme themselves, every other component that's not doing this,

Preferred and forced colour schemes

Body background

Decided to define body background in a dedicated component since it might not be the palette-default in a specific theme.

• Redefine body background and body foreground tokens

Fallback

Only needed in the scheme layer where we use light-dark, https://dev.to/janeori/css-lightdark-mode-implementation-without-duplicating-vars-22c9 can maybe help reducing the need for two fallback space toggles to one space toggle.

light-dark is resolved at component level, even if the light-dark CSS function is only used at the :root. For the fallback, we can't use color-scheme to switch color-scheme, so we can't just define the fallback variables at the :root only. We need to redeclare them wherever a colour scheme can be changed. Otherwise, it will just take the :root definition into account. The affected selectors are :root, [data-color-scheme], .palette, .banner, .card, ....

The fallback works, because we're patching the mode variables at the static-scheme semantic layer:

Benefits:

• Minimal fallback
• No token resolving during build time
• Using just one space toggle variable

Drawbacks:

• Having to redeclare scheme tokens at component level where schemes can change (common drawback for all previously discussed solutions)
• Hard coding color-scheme-mode token overrides can break if static color scheme tokens change in Token Studio

/* using `light-dark()` */
:root {
  --post-scheme-even: light || dark;
}

[data-color-scheme="light] {
  --post-fallback-color-scheme: ;
}

[data-color-scheme="dark"] {
  
}

:root,
.palettes {
  --post-component-bg-light: var(--post-fallback-color-scheme, var(--light-token));
  --post-component-bg: var(--post-component-bg-light, var(--dark-token));
}

/* fallback overrides */
:root {
  --post-scheme-even: initial || ;
}

Open todos

• Fallback
• Banner (design needed)
• Cards
• Discuss order of layers
• Documentation
  • Fallback reason/behavior
  • Fallback variable Placeholder
  • Fallback mixin
  • @gfellerph add code comments
• Testing
  • Nesting [data-color-scheme] inside palettes and vice versa
  • Visual regression tests on the POC examples
• @oliverschuerch inform @sandra-post
• @gfellerph create documentation and testing tickets
• @alizedebray update discussion

Accent Colors

The design is not clear here and we need a discussion with Designers.

Example:
On Cargo Palette-Brand there is an accent color (lightblue) used on the heading, but also an accent color (lightgray) used inside of the card.

• Do we need/want multiple accent colors to be defined on the palette?
• Do we need/want an accent color on the palette and another accent color on the card (nested.accent)?

No mather which solution is prefered, the implementation of these accent colors is not complete on the current integration-test branch.

Consequences

What becomes easier or more difficult to do because of this change?

Example (optional)

If applicable, show a code example to support the decision.

[alizedebray]

Implementation

Context

There are only two possible color modes:

• light
• dark

The mode can be set at two levels:

• Page level – defined by user settings or overridden using a [date-color-scheme] attribute.
• Container level – for example, a palette might declare a mode that matches its background color.

This leads to four possible combinations:

• light: the container is always in light mode, regardless of the page mode.
• dark: the container is always in dark mode, regardless of the page mode.
• even: the container uses the same mode as the page.
• swapped: the container uses the opposite mode of the page.

Both the base and fallback implementations are built around these four combinations.

Base Solution

In the base solution, we use the CSS color-scheme property to set the container’s mode, like this:

	light page	dark page
--post-scheme-light	light	light
--post-scheme-dark	dark	dark
--post-scheme-even	light	dark
--post-scheme-swapped	dark	light

Then, the color of the components inside the container is set using the light-dark() CSS function.

Fallback Solution

💡 Note: This fallback is temporary and will be removed once browser support for light-dark() improves.

Some browsers do not support light-dark(), so we use a fallback approach.

Instead of setting the color-scheme, the container sets a custom property called --fallback-prefers-light, which maps to the same four modes as the base solution:

	light page	dark page
--post-scheme-light	initial	initial
--post-scheme-dark	(empty)	(empty)
--post-scheme-even	initial	(empty)
--post-scheme-swapped	(empty)	initial

In the case:

• initial → light mode is preferred
• (empty) → dark mode is preferred

This property is then used to determine the colors of components inside the container, based on this technique.

color-scheme.set Mixin

To support both the base and fallback solutions together, we created a color-scheme.set mixin.
Use this mixin in any container that sets a color scheme using a token (e.g. palettes, cards, banners).

Example usage:

@use '../functions/tokens';
@use '../mixins/color-scheme';

.my-container {
  @include color-scheme.set(tokens.get('scheme-token-name', $token-map));
}

This is equivalent to:

.my-container {
  // if light-dark() is supported the color-scheme property is simply set from the token
  @supports (color: light-dark(black, white)) {
    color-scheme: var(--scheme-token);
  }

  // if light-dark() is not supported the fallback custom property is set instead
  @supports not (color: light-dark(black, white)) {
      --fallback-prefers-light: #{$scheme-token};
      @extend %scheme-fallback-variables;
    }
}

%scheme-fallback-variables Placeholder

One key difference between the two approaches is when the colors are resolved:

• the light-dark() function is returning a color depending on the closest color-scheme
• the color declared with the --fallback-prefers-light is static and cannot be changed just by changing the --fallback-prefers-light value

Base solution:

With light-dark(), the color adjusts automatically based on the closest container's color-scheme.

:root {
  --color: light-dark(#000, #fff);
}

.parent {
  color-scheme: dark;
}

.children {
  color: var(--color); // ✔️ Adjusts automatically based on the parent's scheme
}

Fallback solution:

With custom properties, colors must be updated manually whenever the --fallback-prefers-light value changes.

:root {
  --color-light: var(--fallback-prefers-light) #000;
  --color: var(--color-light, #fff);
}

.parent {
  --fallback-prefers-light: ;
}

.children {
  color: var(--color); // ❌ Will not update correctly if --fallback-prefers-light changes at the parent level
}

To make it work correctly, you must re-declare the dependent variables wherever --fallback-prefers-light is set:

.parent {
  --fallback-prefers-light: ;
  --color-light: var(--fallback-prefers-light) #000;
  --color: var(--color-light, #fff); // ✔️ Now correct
}

To make this easier and avoid bloating the CSS, we use the %scheme-fallback-variables placeholder.

When a container uses the color-scheme.set mixin, it automatically extends this placeholder, ensuring that the right color variables are re-declared where needed.