Sass color.blackness() Function

What You’ll Learn

color.blackness() belongs to the built-in sass:color module (Deprecated Functions). It returns a legacy color’s HWB blackness as a percentage from 0% to 100% at compile time. This page covers the HWB idea, the legacy-color rule, Dart Sass 1.28+ support, migration to color.channel(), and five compiled examples.

What Is color.blackness()?

Blackness is the “how much black ink?” channel in the HWB (Hue–Whiteness–Blackness) model. Official docs: color.blackness() returns that channel as a number between 0% and 100%. Pure white has 0% blackness; pure black has 100%.

• color.blackness(#e1d7d2) → 11.7647058824%
• color.blackness(white) → 0%
• color.blackness(black) → 100%

📝 Syntax

Load the color module, then pass a legacy color:

@use "sass:color";

// Deprecated — Dart Sass 1.28+
color.blackness($color)

// Optional — bring members into scope
@use "sass:color" as *;
blackness($color)

// Recommended migration (Dart Sass 1.79+)
color.channel($color, "blackness")

Parameters

Return value

📦 Loading sass:color & Migrating

Prefer the namespaced form. Bare blackness() only works after @use "sass:color" as *;—otherwise CSS may keep the call as a plain string.

@use "sass:color";

// Old (deprecated, Dart Sass 1.28+)
$b: color.blackness(#e1d7d2); // 11.7647058824%

// New — preferred on Dart Sass 1.79+
$b: color.channel(#e1d7d2, "blackness");

// Optional global-style import
@use "sass:color" as *;
$b: blackness(#e1d7d2);

🎨 HWB: Blackness + Whiteness

HWB describes a color as a hue mixed with white and black. For many everyday hex colors, whiteness and blackness percentages add up to less than 100%—the rest is the pure hue.

• Blackness high → darker, sootier look
• Blackness 0% → no black mix (white is the extreme opposite case)
• Blackness 100% → pure black

📋 color.blackness vs color.channel

🛠 Compatibility

This is about Sass compilers, not browsers. Compiled CSS receives a finished percentage—no color.blackness() call remains at runtime.

Examples Gallery

Examples use color.blackness() on Dart Sass 1.28+. Open View Compiled CSS for verified output (matches official Sass docs samples where noted).

@use "sass:color";

@debug color.blackness(#e1d7d2); // 11.7647058824%

.swatch {
  --blackness: #{color.blackness(#e1d7d2)};
}

.swatch {
  --blackness: 11.7647058824%;
}

@use "sass:color";

@debug color.blackness(white); // 0%
@debug color.blackness(black); // 100%

.extremes {
  --white: #{color.blackness(white)};
  --black: #{color.blackness(black)};
}

.extremes {
  --white: 0%;
  --black: 100%;
}

@use "sass:color";

$brand: #336699;

.brand {
  --blackness: #{color.blackness($brand)};
}

.brand {
  --blackness: 40%;
}

@use "sass:color";

$tone: #e1d7d2;

.hwb-report {
  --whiteness: #{color.whiteness($tone)};
  --blackness: #{color.blackness($tone)};
  --sum: #{color.whiteness($tone) + color.blackness($tone)};
}

.hwb-report {
  --whiteness: 82.3529411765%;
  --blackness: 11.7647058824%;
  --sum: 94.1176470588%;
}

@use "sass:color";

$grey: #6b717f;

.report {
  --blackness: #{color.blackness($grey)};
  --ink: #{if(color.blackness($grey) >= 50%, "inky", "open")};
}

.report {
  --blackness: 50.1960784314%;
  --ink: inky;
}

🚀 Real-World Use Cases

• Reading legacy SCSS — recognize color.blackness in older HWB workflows.
• Safe migrations — replace with color.channel($c, "blackness") on Dart Sass 1.79+.
• Token audits — flag colors that sit too far toward black ink.
• HWB teaching — pair with whiteness to explain the model.
• Conditional mixins — pick light text when blackness is high.

⚠️ Common Pitfalls

• Using it in new code — prefer color.channel($c, "blackness").
• Bare blackness() without as * — may compile as a CSS function string.
• Modern color spaces — $color must be legacy for color.blackness.
• Confusing with CSS blackness — this is an HWB channel reader, not a filter.
• Expecting a color back — this helper reads a percentage; use adjust/change to write.

💡 Best Practices