Experimental: Contrast-Color CSS Integration Points

Status: Experimental Last updated:

What Is contrast-color()?

The CSS Working Group is developing contrast-color(), a function that automatically generates a contrasting color from a background. This section identifies where Default Admin could integrate contrast-color overrides to improve accessibility resilience. Note: This is informational only; contrast-color is not yet part of WCAG standards and requires @supports feature detection.

How It Works

contrast-color(color, target: AA) returns either white or black (or specified options), whichever has higher contrast against the input color. Browsers will handle the contrast math, eliminating the need for manual light/dark branching. 

/* Example: Using contrast-color to pick text automatically */
button {
  background: var(--button-bg);
  color: white; /* fallback for browsers without support */
}

@supports (color: contrast-color(white)) {
  button {
    color: contrast-color(var(--button-bg), target: AA);
  }
}

Benefits Over Current Approach

Integration Points in Default Admin

1. Button Foreground

Priority: Highest

Most frequently interacted with; manual branching is error-prone when presets change.

/* File: core/themes/default_admin/css/base/variables.css */
@supports (color: contrast-color(white)) {
  --button-fg-color--primary: contrast-color(
    var(--button-bg-color--primary), 
    target: AA
  );
}

Impact: Removes dependency on --gin-color-button-text token switching.

2. Accent-Derived Foreground

Priority: High

Automatically adapts when users change accent presets.

/* File: core/themes/default_admin/css/base/accents.css */
@supports (color: contrast-color(white)) {
  --gin-color-primary-text: contrast-color(
    var(--gin-color-primary), 
    target: AA
  );
}

Impact: Eliminates need for per-preset text color overrides.

3. Focus Ring Color

Priority: Medium

Focus indicators adapt to whatever background surface they appear on.

/* File: core/themes/default_admin/css/base/variables.css */
@supports (color: contrast-color(white)) {
  --gin-color-focus: contrast-color(
    var(--gin-bg-layer), 
    target: 3:1
  );
}

Impact: Reduces hard-coded focus colors; ensures 3:1 focus-to-unfocused contrast automatically.

4. Form Control Borders

Priority: Medium

Form element borders must meet 3:1 contrast against background.

/* File: core/themes/default_admin/css/base/variables.css */
@supports (color: contrast-color(white)) {
  --gin-border-color-form-element: contrast-color(
    var(--gin-bg-layer), 
    target: 3:1
  );
}

5. Link Text Color

Priority: Lower

Links embedded in content; less critical for primary UI.

/* File: core/themes/default_admin/css/base/variables.pcss.css */
@supports (color: contrast-color(white)) {
  --gin-color-link: contrast-color(
    var(--gin-bg-app), 
    target: AA
  );
}

Full Integration Example

/* Comprehensive approach with fallbacks */
:root {
  /* Default fallback for browsers without contrast-color support */
  --button-fg-color--primary: var(--gin-color-button-text);
  --gin-color-focus: #007bff;
  --gin-border-color-form-element: #999;
}

/* Enhanced support for modern browsers */
@supports (color: contrast-color(white)) {
  :root {
    --button-fg-color--primary: contrast-color(var(--button-bg-color--primary), target: AA);
    --gin-color-focus: contrast-color(var(--gin-bg-layer), target: 3:1);
    --gin-border-color-form-element: contrast-color(var(--gin-bg-layer), target: 3:1);
  }
}

Proposed Rollout Strategy

Phase 1: Pilot (Months 1–3)

  1. Add @supports-wrapped contrast-color for button foreground only
    • Lowest risk; most frequently used and tested
    • Gather browser support metrics via feature detection
    • Log fallback usage if contrast-color unavailable
  2. Monitor real-world usage
    • Track which browsers fallback to manual colors
    • Collect user feedback on readability

Phase 2: Expand (Months 4–6)

  1. Add to focus ring and form borders
    • Medium complexity; affects accessibility indicators
    • Test across all theme mode combinations
  2. Validate contrast in forced-colors mode
    • Ensure high-contrast overrides still work

Phase 3: Full Integration (Months 7–12)

  1. Integrate with accent system
    • Highest complexity; affects accent-mix-base derivation
    • Requires rethinking how light/dark mode colors are generated
  2. Deprecate manual light/dark branching
    • Remove redundant tokens once support is sufficient

Current Browser Support

⚠️ As of May 2026, contrast-color() is not yet part of the CSS Color Module Level 4 final spec and is highly experimental. Implementations vary; always provide fallbacks via @supports.

Support Status

Feature Detection Pattern

/* Check support at runtime (JavaScript) */
const supportsContrastColor = CSS.supports('color', 'contrast-color(white)');
if (supportsContrastColor) {
  document.documentElement.classList.add('has-contrast-color-support');
}

/* Or use CSS @supports directly (recommended) */
@supports (color: contrast-color(white)) {
  /* Apply contrast-color enhancements */
}

References & Resources

Specifications & Drafts

Related Drupal Documentation

Implementation Discussions