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.