Style Engine

The Style Engine powering global styles and block customizations.

Installation (JS only)

Install the module

npm install @wordpress/style-engine --save

This package assumes that your code will run in an ES2015+ environment. If you're using an environment that has limited or no support for such language features and APIs, you should include the polyfill shipped in @wordpress/babel-preset-default in your code.

Important

This Package is considered experimental at the moment. The idea is to have a package used to generate styles based on a style object that is consistent between: backend, frontend, block style object and theme.json.

Because this package is experimental and still in development it does not yet generate a wp.styleEngine global. To get there, the following tasks need to be completed:

TODO List:

• Add style definitions for all the currently supported styles in blocks and theme.json.
• The CSS variable shortcuts for values (for presets...)
• Support generating styles in the frontend. (Ongoing)
• Support generating styles in the backend (block supports and theme.json stylesheet). (Ongoing)
• Refactor all block styles to use the style engine server side. (Ongoing)
• Consolidate global and block style rendering and enqueuing
• Refactor all blocks to consistently use the "style" attribute for all customizations (get rid of the preset specific attributes).

See Tracking: Add a Style Engine to manage rendering block styles #38167

Glossary

A guide to the terms and variable names referenced by the Style Engine package.

Block style (Gutenberg internal)

An object comprising a block's style attribute that contains a block's style values. E.g., { spacing: { margin: '10px' }, color: { ... }, ... }

Global styles (Gutenberg internal)

A merged block styles object containing values from a theme's theme.json and user styles settings.

CSS declaration or (CSS property declaration)

A CSS property paired with a CSS value. E.g., color: pink

CSS declarations block

A set of CSS declarations usually paired with a CSS selector to create a CSS rule.

CSS property

Identifiers that describe stylistic, modifiable features of an HTML element. E.g., border, font-size, width...

CSS rule

A CSS selector followed by a CSS declarations block inside a set of curly braces. Usually found in a CSS stylesheet.

CSS selector

The first component of a CSS rule, a CSS selector is a pattern of elements, classnames or other terms that define the element to which the rule’s CSS definitions apply. E.g., p.my-cool-classname > span. See MDN CSS selectors article.

CSS stylesheet

A collection of CSS rules contained within a file or within an HTML style tag.

CSS value

The value of a CSS property. The value determines how the property is modified. E.g., the 10vw in height: 10vw.

CSS variables (vars) or CSS custom properties

Properties, whose values can be reused in other CSS declarations. Set using custom property notation (e.g., --wp--preset--olive: #808000;) and accessed using the var() function (e.g., color: var( --wp--preset--olive );). See MDN article on CSS custom properties.

Inline styles

Inline styles are CSS declarations that affect a single HTML element, contained within a style attribute

Usage

generate

Generates a stylesheet for a given style object and selector.

Parameters

• style Style: Style object.
• options StyleOptions: Options object with settings to adjust how the styles are generated.

Returns

• string: generated stylesheet.

getCSSRules

Returns a JSON representation of the generated CSS rules.

Parameters

• style Style: Style object.
• options StyleOptions: Options object with settings to adjust how the styles are generated.

Returns

• GeneratedCSSRule[]: generated styles.