Sass color.scale() Function

What You’ll Learn

color.scale() belongs to the built-in sass:color module. It fluidly scales one or more color channels toward their maximum or minimum by a percentage of the remaining room. This page covers how percentages work, how scale differs from adjust and change, optional $space (Dart Sass 1.79+), and five compiled examples.

What Is color.scale()?

Scale means “slide this dial a percentage of the way toward its end stop.” Official docs: each keyword argument between -100% and 100% moves a property from its current position toward the maximum (positive) or minimum (negative). So $lightness: 50% makes colors 50% closer to maximum lightness without jumping all the way to white.

• color.scale(#6b717f, $red: 15%) → #81717f (docs also show rgb(129.2, 113, 127))
• color.scale(#d2e1dd, $lightness: -10%, $alpha: -50%) → rgba(184, 208, 201, 0.5)
• color.scale(#998099, $whiteness: 100%, $blackness: -50%) → #d5d5d5

📝 Syntax

Load the color module, then pass a color plus keyword channel percentages:

@use "sass:color";

color.scale($color,
  $red: null, $green: null, $blue: null,
  $saturation: null, $lightness: null,
  $whiteness: null, $blackness: null,
  $x: null, $y: null, $z: null,
  $chroma: null,
  $alpha: null,
  $space: null)
// Global alias:
// scale-color(...)

Common parameters

Return value

📦 Loading sass:color

Prefer the module API. Official docs also document the global name scale-color() for older stylesheets.

// Recommended — namespaced
@use "sass:color";
$c: color.scale(#6b717f, $red: 15%);

// Optional — bring members into the current namespace
@use "sass:color" as *;
$c: scale(#6b717f, $red: 15%);

// Optional — custom namespace
@use "sass:color" as c;
$c: c.scale(#6b717f, $red: 15%);

// Legacy global name
$c: scale-color(#6b717f, $red: 15%);

⚖️ How Fluid Scaling Works

Official docs: each percentage says how far to move from the current value toward the channel’s maximum (positive) or minimum (negative).

📋 scale vs adjust vs change

Official docs point to these three siblings for different jobs.

🛠 Compatibility

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

Examples Gallery

Examples 1–3 and 5 compile on everyday Dart Sass. Example 4 shows official $space / chroma results for Dart Sass 1.79+. Open View Compiled CSS to inspect the output.

@use "sass:color";

@debug color.scale(#6b717f, $red: 15%); // #81717f (docs: rgb(129.2, 113, 127))

.swatch {
  color: color.scale(#6b717f, $red: 15%);
}

.swatch {
  color: #81717f;
}

@use "sass:color";

.overlay {
  background: color.scale(#d2e1dd, $lightness: -10%, $alpha: -50%);
}

.washed {
  color: color.scale(#998099, $whiteness: 100%, $blackness: -50%);
}

.overlay {
  background: rgba(184, 208, 201, 0.5);
}

.washed {
  color: #d5d5d5;
}

@use "sass:color";

$c: #6b717f;

.compare {
  --scale-20: #{color.scale($c, $lightness: 20%)};
  --adjust-20: #{color.adjust($c, $lightness: 20%)};
  --change-70: #{color.change($c, $lightness: 70%)};
}

.compare {
  --scale-20: #878d9a;
  --adjust-20: #a1a5af;
  --change-70: #acb0b9;
}

@use "sass:color";

// Requires Dart Sass 1.79+
@debug color.scale(#d2e1dd, $lightness: -10%, $space: oklch);
@debug color.scale(oklch(80% 20% 120deg), $chroma: 50%, $alpha: -40%);

.modern {
  --oklch-lightness: #{color.scale(#d2e1dd, $lightness: -10%, $space: oklch)};
  color: color.scale(oklch(80% 20% 120deg), $chroma: 50%, $alpha: -40%);
}

.modern {
  --oklch-lightness: rgb(181.2580722731, 195.8949200496, 192.0059024063);
  color: oklch(80% 0.24 120deg / 0.6);
}

@use "sass:color";

$brand: #336699;

.card {
  background: $brand;
  color: color.scale($brand, $lightness: 40%);
  border-color: color.scale($brand, $lightness: -25%);
  outline-color: color.scale($brand, $saturation: -30%);
  --soft: #{color.scale($brand, $alpha: -40%)};
}

.names {
  --module: #{color.scale(#6b717f, $red: 15%)};
  --global: #{scale-color(#6b717f, $red: 15%)};
}

.card {
  background: #336699;
  color: #75a3d1;
  border-color: #264d73;
  outline-color: #42668a;
  --soft: rgba(51, 102, 153, 0.6);
}

.names {
  --module: #81717f;
  --global: #81717f;
}

🚀 Real-World Use Cases

• Hover / active states — fluidly lighten or darken without hardcoding new hexes.
• Soft borders — scale saturation or lightness toward a quieter twin.
• Overlay fades — scale alpha toward transparent for chips and sheets.
• Token ladders — generate related steps that stay proportional on light and dark seeds.
• Perceptual tweaks — use $space: oklch on Dart Sass 1.79+.
• Teaching color math — contrast scale vs adjust vs change side by side.

⚠️ Common Pitfalls

• Treating % like adjust — $lightness: 20% is not the same as adjust(..., $lightness: 20%).
• Mixing RGB + HSL keywords — on legacy colors Sass errors if you combine those families (or with HWB) in one call.
• Using $space on older Dart Sass — needs 1.79+; bare channel scales still work earlier.
• Expecting full white from 50% — 50% only moves halfway toward maximum lightness.
• Forgetting units — scale arguments are percentages such as 15%, not bare 15.

💡 Best Practices