WordPress · t-hamano · May 21, 2025 · May 15, 2025 · May 15, 2025 · May 15, 2025
diff --git a/packages/base-styles/CHANGELOG.md b/packages/base-styles/CHANGELOG.md
@@ -2,6 +2,10 @@
 
 ## Unreleased
 
+### Breaking Changes
+
+-   This package now requires [Dart Sass](https://www.npmjs.com/package/sass) to compile. Legacy Sass compilers like [LibSass](https://sass-lang.com/blog/libsass-is-deprecated/) ([`node-sass`](https://www.npmjs.com/package/node-sass)) and [Ruby Sass](https://sass-lang.com/blog/ruby-sass-is-unsupported/) are no longer supported ([#70135](https://github.com/WordPress/gutenberg/pull/70135)).
+
 ## 5.23.0 (2025-05-07)
 
 ## 5.22.0 (2025-04-11)

diff --git a/packages/base-styles/README.md b/packages/base-styles/README.md
@@ -2,6 +2,8 @@
 
 Base SCSS utilities and variables for WordPress.
 
+Note: This package requires [Dart Sass](https://www.npmjs.com/package/sass) to compile. When using this package, make sure you are using Sass version 1.23.0 or later, which is based on Dart Sass.
+
 ## Installation
 
 Install the module
@@ -10,33 +12,29 @@ Install the module
 npm install @wordpress/base-styles --save-dev
 ```
 
-## Use
-
-### SCSS utilities and variables
+## Usage
 
 In your application's SCSS file, include styles like so:
 
 ```scss
-@import 'node_modules/@wordpress/base-styles/colors';
-@import 'node_modules/@wordpress/base-styles/variables';
-@import 'node_modules/@wordpress/base-styles/mixins';
-@import 'node_modules/@wordpress/base-styles/breakpoints';
-@import 'node_modules/@wordpress/base-styles/animations';
-@import 'node_modules/@wordpress/base-styles/z-index';
-@import 'node_modules/@wordpress/base-styles/default-custom-properties';
+@use '@wordpress/base-styles/colors';
+@use '@wordpress/base-styles/variables';
+@use '@wordpress/base-styles/mixins';
+@use '@wordpress/base-styles/breakpoints';
+@use '@wordpress/base-styles/animations';
+@use '@wordpress/base-styles/z-index';
+@use '@wordpress/base-styles/default-custom-properties';
 ```
 
-If you use [Webpack](https://webpack.js.org/) for your SCSS pipeline, you can use `~` to resolve to `node_modules`:
+Make sure to use namespaces when accessing utilities, variables, functions, etc. For example:
 
 ```scss
-@import '~@wordpress/base-styles/colors';
-```
-
-To make that work with [`sass`](https://www.npmjs.com/package/sass) or [`node-sass`](https://www.npmjs.com/package/node-sass) NPM modules without Webpack, you'd have to use [includePaths option](https://sass-lang.com/documentation/js-api#includepaths):
+.selector {
+	color: colors.$gray-300;
 
-```json
-{
-	"includePaths": [ "node_modules" ]
+	@include mixins.break-medium() {
+		font-size: variables.$font-size-large;
+	}
 }
 ```
 

diff --git a/packages/base-styles/_colors.native.scss b/packages/base-styles/_colors.native.scss
@@ -1,5 +1,7 @@
 /** @format */
 
+@use "sass:color";
+
 // Hugo's new WordPress shades of gray, from http://codepen.io/hugobaeta/pen/grJjVp.
 $black: #000;
 $white: #fff;
@@ -41,23 +43,23 @@ $blue-30: #5198d9;
 
 // Grays
 $gray: #87a6bc;
-$gray-light: lighten($gray, 33%); //#f3f6f8
-$gray-dark: darken($gray, 38%); //#2e4453
+$gray-light: color.adjust($gray, $lightness: 33%); //#f3f6f8
+$gray-dark: color.adjust($gray, $lightness: -38%); //#2e4453
 $gray-900: #1a1a1a;
 $gray-700: #757575;
 
 // $gray-text: ideal for standard, non placeholder text
 // $gray-text-min: minimum contrast needed for WCAG 2.0 AA on white background
 $gray-text: $gray-dark;
-$gray-text-min: darken($gray, 18%); //#537994
+$gray-text-min: color.adjust($gray, $lightness: -18%); //#537994
 
 // Shades of gray
-$gray-lighten-10: lighten($gray, 10%); // #a8bece
-$gray-lighten-20: lighten($gray, 20%); // #c8d7e1
-$gray-lighten-30: lighten($gray, 30%); // #e9eff3
-$gray-darken-10: darken($gray, 10%);
-$gray-darken-20: darken($gray, 20%); // #4f748e
-$gray-darken-30: darken($gray, 30%); // #3d596d
+$gray-lighten-10: color.adjust($gray, $lightness: 10%); // #a8bece
+$gray-lighten-20: color.adjust($gray, $lightness: 20%); // #c8d7e1
+$gray-lighten-30: color.adjust($gray, $lightness: 30%); // #e9eff3
+$gray-darken-10: color.adjust($gray, $lightness: -10%);
+$gray-darken-20: color.adjust($gray, $lightness: -20%); // #4f748e
+$gray-darken-30: color.adjust($gray, $lightness: -30%); // #3d596d
 
 // Custom
 $toolbar-button: #7b9ab1;

diff --git a/packages/base-styles/_colors.scss b/packages/base-styles/_colors.scss
@@ -1,5 +1,3 @@
-@import "./functions";
-
 /**
  * Colors
  */

diff --git a/packages/base-styles/_default-custom-properties.scss b/packages/base-styles/_default-custom-properties.scss
@@ -1,11 +1,13 @@
+@use "./mixins";
+
 // It is important to include these styles in all built stylesheets.
 // This allows to CSS variables post CSS plugin to generate fallbacks.
 // It also provides default CSS variables for npm package consumers.
 :root {
-	@include admin-scheme(#007cba);
 	--wp-block-synced-color: #7a00df;
-	--wp-block-synced-color--rgb: #{hex-to-rgb(#7a00df)};
+	--wp-block-synced-color--rgb: #{functions.hex-to-rgb(#7a00df)};
 	// This CSS variable is not used in Gutenberg project,
 	// but is maintained for backwards compatibility.
 	--wp-bound-block-color: var(--wp-block-synced-color);
+	@include mixins.admin-scheme(#007cba);
 }
diff --git a/packages/base-styles/_functions.scss b/packages/base-styles/_functions.scss
@@ -4,6 +4,21 @@
 * @param {string} hex - the hexadecimal value to convert
 * @return {string} comma separated rgb values
 */
+
+@use "sass:color";
+@use "sass:meta";
+
 @function hex-to-rgb($hex) {
-	@return red($hex), green($hex), blue($hex);
+	/*
+	 * TODO: `color.{red|green|blue}` will trigger a deprecation warning in Dart Sass,
+	 * but the Sass used by the Gutenberg project doesn't support `color.channel()` yet,
+	 * so we can't migrate to it at this time.
+	 * In the future, after the Gutenberg project has been fully migrated to Dart Sass,
+	 * Remove this conditional statement and use only `color.channel()`.
+	 */
+	@if meta.function-exists("channel", "color") {
+		@return color.channel($hex, "red"), color.channel($hex, "green"), color.channel($hex, "blue");
+	} @else {
+		@return color.red($hex), color.green($hex), color.blue($hex);
+	}
 }