a11y-color-scaler 🎨️♿️

A lightweight SCSS utility that automatically adjusts text color for better contrast against any background — while preserving your brand palette.

• ✅ WCAG 2.1 compliant
• ✅ SCSS-only (no JS)
• ✅ Design-system friendly
• ✅ Works with any color palette

🚀 Installation

You can use a11y-color-scaler in two ways:

📦 Option 1: Install via npm

npm install a11y-color-scaler

Then import it in your SCSS:

@use 'a11y-color-scaler' as *;

📁 Option 2: Manual copy

Copy _contrast.scss into your SCSS project and import it using:

@use 'path/to/_contrast.scss' as *;

🧪 Live Demo

Try it live: CodePen Demo

🔧 Usage

$text: #83b2b2;
$bg: #d4ffff;

.block {
	background-color: $bg;
	color: adjust-contrast-color($text, $bg);
}

The function will automatically adjust the text color to ensure it meets the WCAG contrast ratio threshold (4.5:1 by default) by gradually darkening or lightening it.

📀 Accessibility thresholds

This utility follows official WCAG 2.1 contrast guidelines:

| Text type | Minimum contrast | | --------------- | ---------------- | | Regular text | 4.5:1 | | Large/bold text | 3:1 |

You can control the threshold via the optional third parameter:

// Default (4.5:1)
color: adjust-contrast-color($text, $bg);

// For large or bold text (3:1)
color: adjust-contrast-color($text, $bg, 3);

🛠 Function Signature

adjust-contrast-color(
  $text-color,
  $bg-color,
  $threshold: 4.5,
  $step: 3%,
  $max-steps: 10
)

Parameters

| Name | Type | Default | Description | | ------------- | ------ | ------- | ------------------------------------------ | | $text-color | Color | – | Initial color you want to use | | $bg-color | Color | – | Background color to check contrast against | | $threshold | Number | 4.5 | Desired contrast ratio | | $step | % | 3% | Adjustment step for each iteration | | $max-steps | Number | 10 | Max iterations to prevent infinite loops |

📊 Based on WCAG 2.1

• Uses official luminance and contrast ratio formulas
• Respects color balance and keeps as close to original as possible
• Formula based on: WCAG 2.1 contrast ratio definition
• Test your color combos: WebAIM Contrast Checker

♿️ Bonus: respects system-level contrast preferences

Some users enable “Increased Contrast” in their operating system for better readability.
You can respond to this setting using the built-in mixin prefers-strong-contrast.

.block {
	background-color: $bg;
	color: adjust-contrast-color($text, $bg); // WCAG 4.5

	@include prefers-strong-contrast(
		color,
		$text,
		$bg
	); // Boost to WCAG 7 if user prefers it
}

This mixin uses the CSS media query @media (prefers-contrast: more) to apply stronger contrast only when requested by the user’s system.

Mixin signature

@mixin prefers-strong-contrast(
	$property,
	$text-color,
	$bg-color,
	$threshold: 7
);

| Parameter | Type | Description | | ------------- | ------ | --------------------------------------------------------- | | $property | String | CSS property to apply (e.g., color, background-color) | | $text-color | Color | The original color you want to use | | $bg-color | Color | The background color for contrast comparison | | $threshold | Number | Contrast ratio to meet (default 7) |

You can use this for any property, including color, background-color, border-color, etc.

🎖️ How is this different from other contrast tools?

While other tools like a11y-color-contrast only validate whether a color pair meets accessibility standards (WCAG),
a11y-color-scaler actively adjusts the text color to meet those standards — without breaking your design.

| Tool | Type | Purpose | | --------------------- | ---------- | ---------------------------------- | | a11y-color-contrast | JS Library | Checks contrast between colors | | a11y-color-scaler | SCSS Tool | Dynamically adjusts color for WCAG |

This means you can focus on design, and let the utility do the contrast correction for you.

📄 License

MIT – free for personal and commercial use.

🙌 Author

Created by Serhii Ivcheko (@JAZzmiX)

Inspired by real needs in design system development.