Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We鈥檒l occasionally send you account related emails.

Already on GitHub? Sign in to your account

Block Styles Breakdown #20331

75 of 82 tasks
mtias opened this issue Feb 20, 2020 · 36 comments
75 of 82 tasks

Block Styles Breakdown #20331

mtias opened this issue Feb 20, 2020 · 36 comments
[Feature] Design Tools Global Styles [Type] Overview


Copy link

@mtias mtias commented Feb 20, 2020

This is an overview of the concrete tasks needed to proceed with the project scope of #9534 (see also #19611). It operates on three levels, or style origins: local blocks, theme defaults, and global modifications.

Screenshot 2020-03-11 at 19 59 19

First 馃寠

Goal: prototype a system that connects the three style origins and demonstrates how it works for a few top-level blocks.


Ensure at all times the editor reflects the front faithfully.

  • Create the concept of implicit style attributes to control the appearance of the block. #15450 #21021
  • Centralize style mappings #25051
  • Migrate existing attributes (font-size, color) and introduce missing properties (line-height, family). #22700
  • Evolve a theme.json specification for controlling the editor and the style attributes of different origins. #22518 #20588
  • Merge the different style origins (block, theme, user). #20047 #20290
  • Generate front-end styles using the new system. #19883
  • Generate editor styles using the new system. #22520


These are the different tools that interact with appearance values.

  • Expose global styles tool in edit-site. This should be a straightforward rendering of a sidebar in the site editor displaying the global values and palette. #24250
  • Allow users to modify some style attributes in the global styles panel. #20367
    • colors: link colors (link, hover / focus, active) #21032
    • typography: font families, font size, line height. #21030 #21028 #20773
    • reset modifications to theme defaults. #20868
  • Develop interface components to operate with new attributes. Prior art in font sizes and color panel. #20367
    • line-height to Paragraph and Heading inspectors. #20339

Second 馃寠

Goal: develop all necessary sub-systems.


  • Stabilize:
    • (one pr remaining to merge) Client: review there's no duplication and improve the way metadata is structured.
    • Server-client metadata: do not send data we already have #26802
    • Server: consolidate theme.json entity #26802
    • Server: consolidate theme.json processor #27237
    • Prepare a core patch for 5.7 (closed) #27506
  • theme.json
    • Consolidate dynamic selectors (selectors for blocks that represent multiple HTML elements, such as heading or list). #24423 #26945
    • Control design tools visibility (superseded) #27295
    • Make settings & styles top-level keys #28163
    • Split global selector into defaults and root #28533
  • Style properties
  • Presets


Third 馃寠

Goal: merge the non UI parts of global styles in WordPress 5.8.

block.json / block supports:

  • #28913 Add support for skip serialization to all properties. Core blocks can be migrated iteratively.
  • #29616 border-width, border-style, border-color
  • #29335 Alignments
  • #31488 link color: make it work like layout or duotone. #25151 Will also fix link color for author roles.


  • #29891 Changes to theme.json
  • Versioning theme.json from the theme, implemented as part of #30541
  • #29568 colors: allow having defaults, theme, and custom
  • #29778 Theme authors should be able to use any styles in theme.json independently from the block.json support.
  • #24165 Mobile: confirm there are not blockers to make theme.json cross-platform (web & mobile).
  • #30191 Use wp_theme taxonomy instead of post_name to associate user styles with particular themes.


  • #29828 theme.json: customTemplates.
  • block supports: allow changing UI control labels #29155 (discarded, instead we rephrased the labels to be more adequate for different contexts) #30075


  • Update theme.json docs to make clear what's part of WordPress 5.8 and what's part of the plugin. #33131
  • Update theme support docs to state that link color is now stable and part of Wordpress core, using theme.json. The experimental-link-color theme support will be deprecated and removed when the plugin requires WordPress 5.8 as the minimum version. #33162
  • Update docs for block supports, including a note about __experimentalSkipSerialization.


  • #27504 Hooking into the lifecycle of GS: stabilize API and define what sort of hooks do we need.
  • #30082 Block editor settings & global styles settings.

Bug fixes

  • Disable/Enable custom colors, gradients, and font sizes #32200
  • Empty color palette should disable the feature #32225 #32358
  • settings.color no longer have the theme colors #32027 #32358
  • Block presets generate incorrect styles #31660

Fourth 馃寠

Follow-ups to WordPress 5.8 release.

Block supports:






The things listed here don't need to be necessarily implemented, but should be considered.

block.json: nothing planned

  • #27614 Potential use case to add height (spacer and cover, which has a custom one at the moment).


  • #33232 See also the use case for margin
  • Versioning theme.json data from the user #27230 (comment)
  • Consider a standardized way to modify hover/focus/active states for blocks #27075
  • Allow all block-editor theme support options to be defined via theme.json #26901
  • Consider allowing themes to enqueue stylesheets in theme.json #26902
  • How to express nested content
    • Use a flat structure of selectors core/group core/paragraph. #28163
    • We could have separate files for template parts (in addition to the theme.json for the site or main "document", see #27233
    • We could create CSS vars for container blocks #29714 (comment)
  • Do we need to support dynamic values that change depending on other values? Example for colors #24166
  • Consolidate block attributes, block supports, and theme.json shape #22887
  • Schema and type validation #26955
  • Allow CSS properties that we don't manage? #27231
  • Responsive styles/media queries (styles depending on window size). #20244
  • Define if global attributes (base font, color, page background) can be conceptualized as attributes of a root Site block. #16998 Related: consider global site width and padding #20771

Expand to more style properties:

  • text alignment #24616
  • height #28409
  • margin #25988
  • width #31037
  • Free-form custom CSS area. Consider whether this should be per-block as in #25413 or global to all of them?
  • API for loading font families. This should be inherently extensible and likely unopinionated. Maybe explore an API like wp_register_font_family.
  • Justified text #27300


  • Support for child themes #25612
  • Export theme.json configs (including user preferences) as part of exporting templates & template parts #27941 #27528
  • UI extensibility: allow 3rd parties to hook into it, etc.


  • Global styles sidebar: labels for panels in the global styles sidebar (the subtitle of the "headings" panel, for example, "Headings (h1)", is taken from the __experimentalSelector of the heading block). How is this in the new UI?
  • Integrate new component system #28399
  • Do not show-sidebar if the theme doesn't have theme.json support #27394
  • Custom controls for the Global Styles sidebar. #29778
  • Themes can control the visibility of UI controls. Relates to sidebars #27331 and the old proposal to control visibility #27295 If something is disabled via theme.json it should be disabled for both the global styles and the block sidebar.
  • Blue dot on block panels that have modifications #27474
  • Flow for editing the specific styles of a specific block type #27393
  • Advanced panels of blocks should show which Global Styles are affecting it #27475
  • Exploring beyond a sidebar for exposing styling tools #20212
  • Explore combining all style-related attributes of a block into a "Style" tab in the inspector separate from "Settings".
  • Explore a way to lift local modifications on blocks to global (apply certain modifications to all paragraphs or to all blocks that consume an attribute).
  • Explore if it's needed to show locally on blocks when they are inheriting from a global or theme setting.
  • Allow granular saving options #29388

Iterate on design tools:

  • Add background editing tools to Cover. #20193
  • Add spacing control to Gallery. #20705
  • Establish background tools components hooked to the relevant attributes. #16479
  • Look at how to absorb units for font-size #25137 #23323


  • Try using transient attributes on global styles entity #25138
  • Dark mode: editor #28200 authors #24368
  • Do not create revisions for the CPT used by global styles #30132
Copy link

@jorgefilipecosta jorgefilipecosta commented May 7, 2020

Sharing some thoughts on the current status for infrastructure/ my interpretation of some infrastructure tasks:

Create the concept of implicit attributes for appearance pairing

It seems the style attribute we are using for colors introduced in #21021 addressed this part we are also using it for lineHeight with success and without the need to register new attributes.

Hook appearance variables to the editor rendering.

It seems this is about making sure styles are regenerated when the structure that holds global style changes. For example, #20530 accomplishes this by compiling the styles on GlobalStylesProvider.

Look at style variations as packages of style attribute sets.

We can achieve this by adding a styles structure to theme.json:

    styles: {
        鈥榗ore/paragraph鈥: {
            鈥榟uge鈥: {
                fontSize: 14,

We may also achieve the "Custom User Styles" part of #7551 by just allowing the user to save the current block style attributes as a customization of the theme.json structure.

Copy link

@kjellr kjellr commented Oct 9, 2020

At this week's Block-based Themes meeting, the group discussed some of the upcoming design tools in this ticket, and whether they should be opt-in or opt-out for themes. Here are our notes:

  • If a theme has theme.json, it seems ok to have all new design tools be opt-out.
  • Otherwise, if the feature is expected to 鈥渏ust work鈥 with themes without breaking something, it鈥檚 probably ok to enable it by default. Otherwise, they should be opt-in.
  • If these are 鈥渆ditor鈥 features, and not something the theme needs to explicitly build in support for, then it may be confusing to use add_theme_support() for them.
  • We should keep in mind that if users move between block-based themes and non-block-based themes, it will likely be confusing for seemingly unrelated features to turn on and off.

More details in the meeting notes.

Copy link

@jorgefilipecosta jorgefilipecosta commented Nov 23, 2020

With the first beta version of WordPress 5.7 not very far away I'm sharing this summary after some discussion with @nosolosw specifying what are the tasks we think should be part of v1 and/or that may be part of v1.

What we will do next?

These are the tasks we will work on and plan to have ready soon. Are the most prioritary tasks.

  • Versioning. #27230

    • This needs exploration. One option is that theme.json files have a version number, similarly to block.json files. so if we need to make a breaking change we can still keep code that is able to deal with files from a previous version.
  • Child theme support. #25612

    • A child theme inherits theme.json from parents(s) can add new properties or overwrite existing properties.
  • (In progress) Padding support on global styles. #27154

  • (In progress) Refactor our code and merge it into the core. A PR that started the refactoring #26803.

  • (In progress) Improve the way client-side metadata is structured, make sure it matches server metadata shape, and try to avoid metadata duplication. #25138

  • Update KSES to accept our link color styles. #25151 Revive: #25411

  • (In progress) Expose a structure in the core that wp-cli can use to know what theme.json strings are translatable. wp-cli/i18n-command#224

  • Discuss mobile support #24165 and have some double-checking if the current theme.json functionality can work well on mobile.

What we can do next?

Tasks we can work on, it would be nice to have but are not a must and are lower priority may or may not be part of v1.

  • Create a JSON schema specification for theme.json. Developers can use the schema to validate if their theme.json files are correct and easily locate errors. Improving the developer experience of using theme.json. We can use the scheme in the core to remove invalid paths etc. #26955

Things for the future

Not part of a first version. Things we may consider in the future.

  • Nested styles for semantic contexts. For example, apply a specific base font size for things inside a sidebar. #27233

  • Allow CSS properties that we don't manage at the moment. E.g: apply a specific CSS property like textShadow. #27231

Related tasks but that initially will not use theme.json/global styles mechanisms.

  • Look into the alignment issues #26633

  • Responsive styles/media queries (styles depending on window size). #20244

What decisions do we need to do?

  • Are the APIs we offer themes enough to have control about which UI components are surfaced to the user in the global styles sidebar? OR should we expand our API鈥檚? Should our API's allow to specify that the user can change a given style property like line-height at the global styles level, but not at the block level (block inspector).
  • If a block does not support something like line-height, but the theme specifies a line-height for that block. Should we output a line-height style anyway?
  • What are the controls that are available per block? Which blocks by default have font size available? Which have text color? Which have line-height?

What鈥檚 next on the UI/UX side?

The first beta of WordPress 5.7 goes out in January, so we need to have a v1 for the UI ready sometime before the first beta.

  • Typography tools are going to be g2 based (or at least some parts like font size control). So we need to merge (at least parts of) g2 in order to have the typography tools ready.

  • Extensibility mechanism for 3rd party

  • It seems the global styles although functional does not provide a good experience, panels inside panels, a gigantic list of panels (one per each block). What is the plan for the other parts of UI? What are the things we should improve on the UI of these other parts to make them ready for the first version?

    • Navigation between all the different blocks that we can apply global styles to and between the global context.

    • Color options (text, background, and link).

    • Color palette editor.

cc: @nosolosw, @shaunandrews, @jasmussen, @ItsJonQ, @mcsf, @youknowriad

Copy link

@oandregal oandregal commented Apr 7, 2021

This week's status report:


  • Block Supports: added a gutenberg_block_has_support helper function and support for padding in dynamic blocks 30322, border for search block #30227

  • Fixes: title in the save panel of the site editor 30521, fix for themes without theme.json support but with experimental link color support 30452


  • Block supports:

  • Theme.json

    • Update format #29891 There's now a draft PR at #30541
    • Conversation about whether and how to expand the use of CSS Custom Properties #29714

Copy link

@oandregal oandregal commented Apr 14, 2021

This week in global styles:


  • Parts of theme.json with elements #29891

    • preparations to make changes easier #30801 #30610
    • i18n process: make it not depend on a particular path #30604
    • add mechanism to migrate from a v0 schema to the latest #30600
    • clean-ups #30605 #30612
  • block supports

    • border radius for the button block #30194
    • font size & font family for the button block #30394
    • colors for the verse block #27736
    • border radius for the search block #30227


  • theme.json with elements #29891

    • extract sanitization method #30809
    • changes to shape #30541
  • bugfixes #30830

  • block supports: add new style properties: border-color, border-styles, border-width #30124

Copy link

@oandregal oandregal commented Apr 21, 2021

This week in global styles:


theme.json with elements #29891

  • extract sanitization method #30809

Block Supports & theme.json properties:

  • Added block support & theme.json support for: border-color, border-style, and border-width. #30124

Bugfixes, code quality

  • Clean cached data when switching themes #30830
  • Standarize block editor settings load #30245
  • Fix regression in color panel of global styles sidebar #31015
  • Add utility to retrieve classes and styles in color hook #30869 #30870
  • Polish color labels #30075


theme.json with elements #29891

  • changes to shape (working in all editors & front-end) #30541

Block Supports:

  • Allow skipping serialization for typography attributes #30880
  • Conversation about "overlay" colors #29963 (comment)
  • Migrate more blocks using the skipSerialization mechanism as well as adding more properties #28913


  • kses filtering (approved) #30888


The priority continues to be shipping #29891 as soon as possible to unblock related work.

#28913 is a good issue to look at if you can lend a hand (help with reviews, migrate more blocks, more properties, etc).

Copy link

@oandregal oandregal commented Apr 28, 2021

Weekly status report for core-editor meeting.

Shipped this week


block.json / block supports

  • duotone #26752
  • padding: fix to allow units other than px #31057
  • font-size: can be used in nodes other than the wrapper #30879
  • border-color: fix for dynamic blocks #31020
  • blocks
    • padding for site title #31125
    • padding and letter casing for site tagline #31042
    • link color for post date #30791
    • table uses now background/text colors from the theme #30791


  • custom templates can be translated via theme.json #29828


  • fix to sanitizing user styles #30888

Site editor:



  • Changes to format #29891 are ready #30541 we're now testing and polishing. It also includes versioning (aka migrate the older formats to the new one).
  • Improve API to take data from the theme directly #31267

block.json / block supports

  • typography (line-height, font-weight, etc) can be used in nodes other than the wrapper #30880
  • border and color (background, text) to the pull quote block #30951

New style properties

  • Add support for letter-spacing #31118


  • Add a new endpoint that exposes block editor settings through the REST API (by mobile to access global styles data) #29969
  • standardize capabilities of wp_template, wp_template_part and wp_global_styles #30893


The priority continues to be shipping #29891 as soon as possible to unblock related work.

#28913 is a good issue to look at if you can lend a hand (help with reviews, migrate more blocks, more properties, etc).

Copy link

@oandregal oandregal commented May 5, 2021

Status report for core-editor meeting.

Shipped this week:

block.json / block supports:

  • Improve the typing performance by only rendering hook panel of selected blocks #31381
  • Update padding to allow configurable sides #30607
  • Add utils to get border classes and inline styles #31264


  • Change the format of theme.json and introduce elements as well as versioning #30541
  • The top-level styles & settings use the body selector instead of :root #31302


  • Global Styles settings to use the block_editor_settings_all filter #31027

Site editor:

  • Improve APIs to allow getting theme styles #31267


block.json / block supports:


  • Use theme taxonomy instead of post name to associate user data (stored as a CPT) with the theme #31436


After having landed #29891 via #30541 the priority is to tie up the loose ends before preparing the core patch for 5.8.

Worth highlighting is that there're two new issues to switching away from CSS Custom Properties for link #31488 and font-family #31489 (see rationale in each issue).

Copy link

@oandregal oandregal commented May 12, 2021

This week report for core-editor.

Shipped this week

block supports

  • margin: configurable sides #30608
  • spacing: hide UI for disabled properties #31726
  • rename and stabilize useEditorFeature to useSetting #31587
  • layout: add reset button #30828


site editor:

  • cover against blocks being unregister #31588
  • create metadata for all blokcs #31590
  • remove specificity for link color #31497


block supports:


  • Show both core & theme colors #31669
  • Link color not to use CSS Custom Property #31524


Start the merge process for theme.json APIs.

Copy link

@oandregal oandregal commented May 19, 2021

Status report (core-editor):

This week's focus was on getting things ready for Gutenberg 10.7 (landed most of the things we needed, there are a couple in flight) and start the merge process in core (got an initial PR for this).

Shipped this week

block supports:

  • margin: fix for custom units #31776
  • margin: add server-side support #31808
  • duotone: fix padding crash #31780
  • font-family: fix typo that affects dynamic blocks #31974
  • layout: fix for complex values #31740
  • typography: allow blocks to use these properties in inner markup #30880
  • link color: do not set default #31755
  • link color: fix selector #31820



block supports:


  • Show both core & theme colors #31669
  • Link color not to use CSS Custom Property #31524

core merge


Merge process for theme.json APIS in core.

Copy link

@oandregal oandregal commented May 26, 2021

Status Report (core-editor meeting).

Global Styles and Global Settings have been ported to WordPress core and will be part of the WordPress 5.8 release. The focus now is on polishing and fixing bugs as we find them. The issue description & tasks have been triaged and there're two new sections: "bugfixes" and "docs" with tasks to be worked on in the upcoming weeks.

Now that the 1.0 version of this feature has been shipped and we need to revisit focuses, I thought it'd be a good time to pause these reports while we figure out the next steps. Anything relevant should still be posted here but on an on-demand basis not weekly.

Supported settings & styles that landed core

There's a task above to update this in the docs but wanted to share what we have now.

  • The following settings & styles are still experimental and only work with the plugin: border, font-family, font-style, font-weight, text-decoration, text-transform. The rest are part of WordPress core now, so they work without the plugin as well.
  • Layout is enabled for themes with theme.json support.
  • The default theme.json settings we landed in core work like this:
    • If the settings had a corresponding theme support, it works the same as before. Settings that are enabled by default are color.custom, color.customGradient, typography.customFontSize, typography.dropCap. Settings that are disabled by default are spacing.customMargin, spacing.customPadding, typography.lineHeight. Units can be filtered.
    • Link color is stable, landed into 5.8, and it's disabled by default. Need to make a decision on what to do with the existing add_theme_support('experimental-link-color'). It seems that we can keep it in the plugin and remove it when the minimum WordPress version is 5.8.

Shipped this week

Port to core:

Block Supports:

  • link color: refactored to use the elements mechanism #31524
  • typography: allow blocks to use these properties in inner markup #30880
  • spacing (margin, padding): allow blocks to use these properties in inner markup #31973
  • font-family: fix for dynamic blocks #31974
  • duotone: add an option to disable it #32002
  • units: make UI controls use the ones defined via theme.json #31822


  • Make core colors (classes and CSS Custom Properties) always available #31669 This landed in core as well, but we've found some issues such as #32225 so we're evaluating what to do.


  • Docs: make examples copy-pasteable #32040
  • Fix for REST endpoint used by mobile #31844

Copy link

@oandregal oandregal commented Dec 21, 2021

We're shipping a first version of the GS interface in 5.9, so it looks like this issue could be closed. Both for having a sense of progress but also because the activity has already moved to other smaller and more focused issues (designer tools, site editor improvements, framework changes, etc).

Copy link

@oandregal oandregal commented Dec 21, 2021

I've created #37550 to track some gaps we still have from the original vision of styles at the framework level.

Copy link
Member Author

@mtias mtias commented Dec 21, 2021

Really wonderful work and progress here!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
[Feature] Design Tools Global Styles [Type] Overview
No open projects

No branches or pull requests

9 participants