diff --git a/docs/designers-developers/developers/themes/theme-json.md b/docs/designers-developers/developers/themes/theme-json.md new file mode 100644 index 00000000000000..89c86b73cd50e6 --- /dev/null +++ b/docs/designers-developers/developers/themes/theme-json.md @@ -0,0 +1,223 @@ +# Themes & Block Editor: experimental theme.json + +> **These features are still experimental**. “Experimental” means this is an early implementation subject to drastic and breaking changes. +> +> Documentation has been shared early to surface what’s being worked on and invite feedback from those experimenting with the APIs. Please, be welcome to share yours in the weekly #core-editor chats as well as async via the Github issues and Pull Requests. + +This is documentation for the current direction and work in progress about how themes can hook into the various sub-systems that the Block Editor provides. + +* Rationale +* Specification +* Current Status + +## Rationale + +The Block Editor surface API has evolved at different velocities, and it's now at a point where is showing some growing pains, specially in areas that affect themes. Examples of this are: the ability to [control the editor programmatically](https://make.wordpress.org/core/2020/01/23/controlling-the-block-editor/), or [a block style system](https://github.com/WordPress/gutenberg/issues/9534) that facilitates user, theme, and core style preferences. + +This describes the current efforts to consolidate the various APIs into a single point: a `experimental-theme.json` file. + +When this file is present a few Block Editor mechanisms are activated. + +### Presets become CSS Custom Properties + +Presets such as [color palettes](https://developer.wordpress.org/block-editor/developers/themes/theme-support/#block-color-palettes), [font sizes](https://developer.wordpress.org/block-editor/developers/themes/theme-support/#block-font-sizes), and [gradients](https://developer.wordpress.org/block-editor/developers/themes/theme-support/#block-gradient-presets) will be enqueued as CSS Custom Properties for themes to use. + +These will be enqueued to the front-end and editor. + +### Some block styles are managed + +By providing the block style properties in a structured way, the Block Editor can "manage" the CSS that comes from different origins (user, theme, and core CSS), reducing the amount of CSS loaded in the page and preventing specificity wars due to the competing needs of the components involved (themes, blocks, plugins). + +### Individual features can be controlled per block + +The Block Editor already allows the control of specific features such as alignment, drop cap, whether it's present in the inserter, etc at the block level. The goal is to surface these for themes to control. + +## Specification + +The specification for the `experimental-theme.json` follows the three main functions described in the section above: presets, styles, and features. + +``` +{ + presets: { + color: [ ... ], + font-size: [ ... ], + gradient: [ ... ], + }, + styles: { ... }, + features: { ... } +} +``` + +The file is divided into sections that represent different contexts: individual blocks, as well as the global environment. + +``` +{ + global: { + presets: { ... }, + styles: { ... }, + features: { ... } + }, + core/paragraph: { + presets: { ... }, + styles: { ... }, + features: { ... } + }, + core/group: { + presets: { ... }, + styles: { ... }, + features: { ... } + } +} +``` + +Some of the functions are context-dependant. Take, as an example, the drop cap: + +``` +{ + global: { + features: { + dropCap: false + } + }, + core/paragraph: { + features: { + dropCap: true, + } + }, + core/image: { + features: { + dropCap: true + } + } +} +``` + +In the example above, we aim to encapsulate that the drop cap should be disabled globally but enabled in the paragraph context. The drop cap in the image context wouldn't make sense so should be ignored. + +## Current Status + +### Presets + +So far, this function is only enabled for the global section. + +The generated CSS Custom Properties follow this naming schema: `--wp--preset--{preset-category}--{preset-slug}`. + +For this input: + +``` +presets: { + color: [ + { + slug: 'strong-magenta', + value: #a156b4, + }, + { + slug: 'very-dark-grey', + value: #444, + } + ], +} +``` + +The following stylesheet will be enqueued to the front-end and editor: + +```css +:root { + --wp--preset--color--strong-magenta: #a156b4; + --wp--preset--color--very-dark-gray: #444; +} +``` + +The goal is that presets can be defined using this format, although, right now, the name property (used to be shown in the editor) can't be translated from this file. For that reason, and to maintain backward compatibility, the presets declared via `add_theme_support` will also generate the CSS Custom Properties. The equivalent example to above is: + +```php +add_theme_support( 'editor-color-palette', array( + array( + 'name' => __( 'strong magenta', 'themeLangDomain' ), + 'slug' => 'strong-magenta', + 'color' => '#a156b4', + ), + array( + 'name' => __( 'very dark gray', 'themeLangDomain' ), + 'slug' => 'very-dark-gray', + 'color' => '#444', + ), +) ); +``` + +If the `experimental-theme.json` contains any presets, these will take precedence over the ones declared via `add_theme_support`. + +### Styles + +Each block will declare which style properties it exposes. This has been coined as "implicit style attributes" of the block. These properties are then used to automatically generate the UI controls for the block in the editor, as well as being available through the `experimental-theme.json` file for themes to target. + +The list of properties that are currently exposed via this method are: + +- Paragraph and Heading: line-height, font-size, color. +- Group, Columns, and MediaText: color. + +### Features + +This is being implemented, so it's not currently available. + +### Recap of current available functions + +``` +{ + global: { + presets: { + color: [ + { + slug: , + value: , + }, + { ... }, + ], + font-size: [ + { + slug: , + value: , + }, + { ... }, + ], + gradient: [ + { + slug: , + value: , + }, + { ... }, + ] + } + }, + core/paragraph: { + styles: { + line-height: , + font-size: , + color: , + } + }, + /* core/heading/h1, core/heading/h2, etc */ + core/heading/h*: { + styles: { + line-height: , + font-size: , + color: , + } + }, + core/columns: { + styles: { + color: , + } + }, + core/group: { + styles: { + color: , + } + }, + core/media-text: { + styles: { + color: , + } + }, +} +``` diff --git a/docs/manifest.json b/docs/manifest.json index 40c10d70dbe3ab..90e8738b8d5be4 100644 --- a/docs/manifest.json +++ b/docs/manifest.json @@ -233,6 +233,12 @@ "markdown_source": "../docs/designers-developers/developers/themes/block-based-themes.md", "parent": "themes" }, + { + "title": "Themes & Block Editor: experimental theme.json", + "slug": "theme-json", + "markdown_source": "../docs/designers-developers/developers/themes/theme-json.md", + "parent": "themes" + }, { "title": "Backward Compatibility", "slug": "backward-compatibility", diff --git a/docs/toc.json b/docs/toc.json index 4b804c3ee6e510..cc4435707fcf8e 100644 --- a/docs/toc.json +++ b/docs/toc.json @@ -42,7 +42,8 @@ { "docs/designers-developers/developers/feature-flags.md": [] }, { "docs/designers-developers/developers/themes/README.md": [ { "docs/designers-developers/developers/themes/theme-support.md": [] }, - { "docs/designers-developers/developers/themes/block-based-themes.md": [] } + { "docs/designers-developers/developers/themes/block-based-themes.md": [] }, + { "docs/designers-developers/developers/themes/theme-json.md": [] } ] }, { "docs/designers-developers/developers/backward-compatibility/README.md": [ { "docs/designers-developers/developers/backward-compatibility/deprecations.md": [] },