Base Styles

Base SCSS utilities and variables for WordPress.

Note: This package requires Dart 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

npm install @wordpress/base-styles --save-dev

Usage

In your application's SCSS file, include styles like so:

@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';

Make sure to use namespaces when accessing utilities, variables, functions, etc. For example:

.selector {
	color: colors.$gray-300;

	@include mixins.break-medium() {
		font-size: variables.$font-size-large;
	}
}

CSS Admin Themes

The package also includes a built version of the output generated by the wordpress-admin-schemes() mixin which can be used directly in your project. The CSS file is located at node_modules/@wordpress/base-styles/build-style/admin-schemes.css.

Tokens

The variables below are the SCSS tokens that @wordpress/components and the editor use for elevation and border radius. New UI should use the CSS design tokens from @wordpress/theme instead; these remain for existing SCSS.

Elevation tokens

Each value is meant to be used as a box-shadow.

| Variable | Value | | -------------------- | ---------------------------------------------------------------------------------------------------------------------------------- | | $elevation-x-small | 0 1px 1px rgba(0, 0, 0, 0.03), 0 1px 2px rgba(0, 0, 0, 0.02), 0 3px 3px rgba(0, 0, 0, 0.02), 0 4px 4px rgba(0, 0, 0, 0.01) | | $elevation-small | 0 1px 2px rgba(0, 0, 0, 0.05), 0 2px 3px rgba(0, 0, 0, 0.04), 0 6px 6px rgba(0, 0, 0, 0.03), 0 8px 8px rgba(0, 0, 0, 0.02) | | $elevation-medium | 0 2px 3px rgba(0, 0, 0, 0.05), 0 4px 5px rgba(0, 0, 0, 0.04), 0 12px 12px rgba(0, 0, 0, 0.03), 0 16px 16px rgba(0, 0, 0, 0.02) | | $elevation-large | 0 5px 15px rgba(0, 0, 0, 0.08), 0 15px 27px rgba(0, 0, 0, 0.07), 0 30px 36px rgba(0, 0, 0, 0.04), 0 50px 43px rgba(0, 0, 0, 0.02) |

@use '@wordpress/base-styles/variables';

.card {
	box-shadow: variables.$elevation-small;
}

Radius tokens

Each value is meant to be used as a border-radius.

| Variable | Value | Applied to | | ----------------- | -------- | -------------------------------------------------------------- | | $radius-x-small | 1px | Elements like buttons nested within primitives like inputs. | | $radius-small | 2px | Most primitives. | | $radius-medium | 4px | Containers with smaller padding, such as menus and popovers. | | $radius-large | 8px | Containers with larger padding, such as cards and modals. | | $radius-full | 9999px | Pills. | | $radius-round | 50% | Circles and ovals. |

@use '@wordpress/base-styles/variables';

.pill {
	border-radius: variables.$radius-full;
}

Contributing to this package

This is an individual package that's part of the Gutenberg project. The project is organized as a monorepo. It's made up of multiple self-contained software packages, each with a specific purpose. The packages in this monorepo are published to npm and used by WordPress as well as other software projects.

To find out more about contributing to this package or Gutenberg as a whole, please read the project's main contributor guide.