Contrast

Foreground and background color utilities for maintaining legibility on context-colored backgrounds.

@layer helpers

Context tokens

Two families of helper classes pair foreground and background colors for legibility on context-palette backgrounds. The contrast family (.fg-contrast, .bg-contrast) reads token-defined values from CSS custom properties at runtime; the accessible family (.fg-a11y, .bg-a11y) embeds a WCAG 2.1–computed color at Sass build time. Both families use compound selectors — the context class and the helper class must appear on the same element.

Contrast colors

Contrast colors come from the token system: each context exposes a --{context}-contrast CSS custom property at :root, and the contrast helpers read that property at runtime. Because the values are CSS custom properties, dark mode updates are handled automatically.

Contrast text

.fg-contrast applies the token-defined contrast foreground color for the active background context. It requires a .bg-{context} class on the same element to match the compound selector.

Default background with contrast color text.

Alternate background with contrast color text.

Primary background with contrast color text.

Secondary background with contrast color text.

Neutral background with contrast color text.

Danger background with contrast color text.

Success background with contrast color text.

Warning background with contrast color text.

Info background with contrast color text.

Black background with contrast color text.

White background with contrast color text.

<p class="bg-default fg-contrast p-xsmall">Default background with contrast color text.</p>
<p class="bg-alternate fg-contrast p-xsmall">Alternate background with contrast color text.</p>
<p class="bg-primary fg-contrast p-xsmall">Primary background with contrast color text.</p>
<p class="bg-secondary fg-contrast p-xsmall">Secondary background with contrast color text.</p>
<p class="bg-neutral fg-contrast p-xsmall">Neutral background with contrast color text.</p>
<p class="bg-danger fg-contrast p-xsmall">Danger background with contrast color text.</p>
<p class="bg-success fg-contrast p-xsmall">Success background with contrast color text.</p>
<p class="bg-warning fg-contrast p-xsmall">Warning background with contrast color text.</p>
<p class="bg-info fg-contrast p-xsmall">Info background with contrast color text.</p>
<p class="bg-black fg-contrast p-xsmall">Black background with contrast color text.</p>
<p class="bg-white fg-contrast p-xsmall">White background with contrast color text.</p>

Accessibility tip: Color alone shouldn't convey meaning as it's not perceived by assistive technology users. Ensure clarity through text with adequate contrast, ARIA attributes where needed, and consider using .visually-hidden for screen reader content.

Contrast background

.bg-contrast applies the token-defined contrast background color for the active foreground context. It requires a .fg-{context} class on the same element.

Default text with contrast color background.

Alternate text with contrast color background.

Primary text with contrast color background.

Secondary text with contrast color background.

Neutral text with contrast color background.

Danger text with contrast color background.

Success text with contrast color background.

Warning text with contrast color background.

Info text with contrast color background.

Black text with contrast color background.

White text with contrast color background.

<p class="fg-default bg-contrast p-xsmall">Default text with contrast color background.</p>
<p class="fg-alternate bg-contrast p-xsmall">Alternate text with contrast color background.</p>
<p class="fg-primary bg-contrast p-xsmall">Primary text with contrast color background.</p>
<p class="fg-secondary bg-contrast p-xsmall">Secondary text with contrast color background.</p>
<p class="fg-neutral bg-contrast p-xsmall">Neutral text with contrast color background.</p>
<p class="fg-danger bg-contrast p-xsmall">Danger text with contrast color background.</p>
<p class="fg-success bg-contrast p-xsmall">Success text with contrast color background.</p>
<p class="fg-warning bg-contrast p-xsmall">Warning text with contrast color background.</p>
<p class="fg-info bg-contrast p-xsmall">Info text with contrast color background.</p>
<p class="fg-black bg-contrast p-xsmall">Black text with contrast color background.</p>
<p class="fg-white bg-contrast p-xsmall">White text with contrast color background.</p>

Accessible colors

The accessible family resolves a color at Sass build time using color-contrast(), which applies the WCAG 2.1 relative luminance formula to the context's base color. The result is always either white or black — whichever achieves a contrast ratio above 4.5:1 against the context background. Both light-mode and dark-mode values are computed from their respective context color maps and wrapped in light-dark().

CSS-native color-contrast() is not yet supported in browsers. Chassis CSS computes accessible colors using a Sass function at build time, which means runtime overrides to context colors via CSS variables will not update these utility values automatically.

Accessible text

.fg-a11y applies the WCAG-computed foreground color (white or black) for the active background context. It requires a .bg-{context} class on the same element.

<p class="bg-default fg-a11y p-xsmall">Default background with accessible color text.</p>
<p class="bg-alternate fg-a11y p-xsmall">Alternate background with accessible color text.</p>
<p class="bg-primary fg-a11y p-xsmall">Primary background with accessible color text.</p>
<p class="bg-secondary fg-a11y p-xsmall">Secondary background with accessible color text.</p>
<p class="bg-neutral fg-a11y p-xsmall">Neutral background with accessible color text.</p>
<p class="bg-danger fg-a11y p-xsmall">Danger background with accessible color text.</p>
<p class="bg-success fg-a11y p-xsmall">Success background with accessible color text.</p>
<p class="bg-warning fg-a11y p-xsmall">Warning background with accessible color text.</p>
<p class="bg-info fg-a11y p-xsmall">Info background with accessible color text.</p>
<p class="bg-black fg-a11y p-xsmall">Black background with accessible color text.</p>
<p class="bg-white fg-a11y p-xsmall">White background with accessible color text.</p>

Accessible background

.bg-a11y applies the WCAG-computed background color (white or black) for the active foreground context. It requires a .fg-{context} class on the same element.

<p class="fg-default bg-a11y p-xsmall">Default text with accessible color background.</p>
<p class="fg-alternate bg-a11y p-xsmall">Alternate text with accessible color background.</p>
<p class="fg-primary bg-a11y p-xsmall">Primary text with accessible color background.</p>
<p class="fg-secondary bg-a11y p-xsmall">Secondary text with accessible color background.</p>
<p class="fg-neutral bg-a11y p-xsmall">Neutral text with accessible color background.</p>
<p class="fg-danger bg-a11y p-xsmall">Danger text with accessible color background.</p>
<p class="fg-success bg-a11y p-xsmall">Success text with accessible color background.</p>
<p class="fg-warning bg-a11y p-xsmall">Warning text with accessible color background.</p>
<p class="fg-info bg-a11y p-xsmall">Info text with accessible color background.</p>
<p class="fg-black bg-a11y p-xsmall">Black text with accessible color background.</p>
<p class="fg-white bg-a11y p-xsmall">White text with accessible color background.</p>

With components

Both families compose directly with component context classes. The examples below use badges and cards with a context background class alongside .fg-contrast or .fg-a11y.

Context Contrast

<span class="badge primary">Context</span>
<span class="badge fg-contrast bg-primary">Contrast</span>
<span class="badge fg-a11y bg-primary">Accessible</span>

On cards:

Contrast text

Some quick example text to demonstrate the difference between contrast and accessible text.

<div class="card bg-primary fg-contrast">
  <div class="card-header">Contrast text</div>
  <div class="card-body">
    <p>Some quick example text to demonstrate the difference between contrast and accessible text.</p>
  </div>
</div>
<div class="card bg-primary fg-a11y">
  <div class="card-header">Accessible text</div>
  <div class="card-body">
    <p>Some quick example text to demonstrate the difference between contrast and accessible text.</p>
  </div>
</div>

CSS

All four classes are generated via Sass loops over $context-colors. The contrast classes read --{context}-contrast CSS custom properties from :root, defined by the token system; the accessible classes embed computed color values directly — no runtime variable cascade occurs.

@each $color, $value in $context-colors {
  .bg-#{$color}.fg-contrast {
    color: #{to-opacity(var(--#{$color}-contrast), var(--fg-opacity, 1))};
  }
  .fg-#{$color}.bg-contrast {
    background-color: #{to-opacity(var(--#{$color}-contrast), var(--bg-opacity, 1))};
  }
}

@each $color, $value in $context-colors {
  .bg-#{$color}.fg-a11y {
    color:
      light-dark(
        #{to-opacity(color-contrast(get-sass-color($value)), var(--fg-opacity, 1))},
        #{to-opacity(color-contrast(get-sass-color(map.get($context-colors-dark, $color), true)), var(--fg-opacity, 1))}
      );
  }
  .fg-#{$color}.bg-a11y {
    background-color:
      light-dark(
        #{to-opacity(color-contrast(get-sass-color($value)), var(--bg-opacity, 1))},
        #{to-opacity(color-contrast(get-sass-color(map.get($context-colors-dark, $color), true)), var(--bg-opacity, 1))}
      );
  }
}