Sass color.lightness() Function

What You’ll Learn

color.lightness() belongs to the built-in sass:color module (Deprecated Functions). It returns a legacy color’s HSL lightness as a number from 0% to 100% at compile time. This page covers the brightness dial, siblings hue / saturation, migration to color.channel(), and five compiled examples.

What Is color.lightness()?

Lightness is how bright a color looks on the HSL scale—from black (0%) through midtones to white (100%). Official docs: color.lightness() returns that percent as a number between 0% and 100%. It only reads the value; it does not lighten the color.

• color.lightness(#e1d7d2) → 85.2941176471%
• color.lightness(#f2ece4) → 92.1568627451%
• color.lightness(#dadbdf) → 86.4705882353%

📝 Syntax

Load the color module, then pass a legacy color:

@use "sass:color";

// Deprecated — still works on legacy colors
color.lightness($color)

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

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

Parameters

Return value

📦 Loading sass:color & Migrating

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

@use "sass:color";

// Old (deprecated, still available)
$l: color.lightness(#e1d7d2); // 85.2941176471%

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

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

🎨 HSL Trio: Hue, Saturation, Lightness

Official docs also list color.hue() and color.saturation() the same way (deprecated readers for the other two HSL channels). Together they rebuild the classic hsl(h, s, l) triple from any legacy color.

• Lightness 0% → black (no brightness)
• Lightness near 50% → midtones with clear hue
• Lightness 100% → white (full brightness)

📋 color.lightness vs color.channel

🛠 Compatibility

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

Examples Gallery

Examples use color.lightness(). Open View Compiled CSS for verified output (matches official Sass docs samples where noted).

@use "sass:color";

@debug color.lightness(#e1d7d2); // 85.2941176471%

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

.swatch {
  --lightness: 85.2941176471%;
}

@use "sass:color";

@debug color.lightness(#f2ece4); // 92.1568627451%
@debug color.lightness(#dadbdf); // 86.4705882353%

.palette {
  --cream: #{color.lightness(#f2ece4)};
  --cool: #{color.lightness(#dadbdf)};
}

.palette {
  --cream: 92.1568627451%;
  --cool: 86.4705882353%;
}

@use "sass:color";

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

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

@use "sass:color";

.compare {
  --soft: #{color.lightness(#e1d7d2)};
  --mid: #{color.lightness(#6b717f)};
  --deep: #{color.lightness(#036)};
  --brand: #{color.lightness(#336699)};
}

.compare {
  --soft: 85.2941176471%;
  --mid: 45.8823529412%;
  --deep: 20%;
  --brand: 40%;
}

@use "sass:color" as *;

.panel {
  --lightness: #{lightness(#e1d7d2)};
}

.panel {
  --lightness: 85.2941176471%;
}

🚀 Real-World Use Cases

• Reading legacy SCSS — recognize color.lightness in older HSL workflows.
• Safe migrations — replace with color.channel($c, "lightness") on Dart Sass 1.79+.
• Token audits — sort surfaces by brightness before lighten / darken.
• Conditional mixins — pick text color when lightness is above or below 50%.
• Teaching HSL — show why pale colors clamp to white under fixed lighten.

⚠️ Common Pitfalls

• Using it in new code — prefer color.channel($c, "lightness").
• Confusing with lighten() — lightness reads; lighten writes a new color.
• Bare lightness() without as * — may compile as a CSS function string.
• Modern color spaces — $color must be legacy for color.lightness.
• Expecting a color back — this helper reads a percent; use scale/adjust to change.

💡 Best Practices