Controlling design tools visibility

[oandregal]

This issue is to discuss and streamline the behavior of design tools in terms of the visibility of the UI controls for users.

This topic is growing complex, so I want us to agree on a terminology:

• contexts: each block that can have styles/settings assigned. Note that some blocks (core/heading) expose many contexts (core/heading/h1, ..., core/heading/h6) and there's also the "global" context that doesn't match any block.
• block UI: the block sidebar available in all editors.
• global UI: the global styles sidebar available in the site editor.

Use cases

Some examples of what we want theme authors to be able to do:

• Disable custom gradients in all contexts, so they aren't visible in the block and global UIs.
• Enable color presets in every context, and make them visible in the block and global UIs.
• Enable font family and its presets only for the global context (this context is only visible in the global UI).
• Enable line height for all contexts, but make it visible only visible in the global UI.

Some examples that we aim to streamline for users:

• User is able to modify the values of the colors (theme presets) for all contexts at once.
• User is able to modify the values of the font size (theme presets) for the paragraph context.

Coda

A related use case but that merits its own discussion is extensibility by 3rd parties. Things like disabling the typography panel entirely and provide their own, or provide a different mechanism to set font families.

[oandregal]

I think the gist of what we want to streamline is that, for every style property, we want theme authors to be able to control:

• whether or not a style property should be enabled for a particular block/context
• where a style property should be enabled (block UI, global styles UI)

Some ideas

Taking on what Riad and Jorge discussed over here and adding my own ideas. Something along the lines of this could work:

• Settings that control the UI can have "all", "block", and "global", "none" as values. Now they're booleans.

• Declaring the preset values for a style property and declaring whether they are visible in a particular UI are separate concerns. We need to create new keys.

• Every property is enabled by default and users can opt-out (see theme authors feedback). The theme.json that comes with core has them all enabled.

• Consolidate a naming schema for all the settings. With the addition of style properties, this has grown wildly. I'm only opinionated about that we have one that all follow. I can suggest prepending the property name, so it's easier to parse all the things at once ― but, really, I'd be happy with any other that brings clarity.

• Contexts: theme authors still define things per context, global is no longer a fallback. We introduce a new explicit fallback (name *?) to define things that can be common (presets, but also default values for controlling visibility). This requires a new panel UI in the global styles sidebar where users are able to tweak all common presets ― we now use the global.

A potential schema for the settings with all of them, so we have some zoomed out perspective:

{
  "color": {
    "color": "all",
    "colorCustom": "block",
    "colorPresets": [ "..." ],
    "gradient": "all",
    "gradientCustom": "block",
    "gradientPresets": [ "..." ],
    "link": "global"
  },
  "spacing": {
    "padding": "all",
    "units": "block",
    "unitsPresets": [ "px", "em", "rem" ]
  },
  "typography": {
    "dropCap": "block",
    "fontFamily": "global",
    "fontFamilyPresets": [ "..." ],
    "fontSize": "all",
    "fontSizeCustom": "block",
    "fontSizePresets": [ "..." ],
    "fontStyle": "global",
    "fontStylePresets": [ "..." ],
    "fontWeight": "global",
    "fontWeightPresets": [ "..." ],
    "lineHeight": "none",
    "textDecoration": "global",
    "textDecorationPresets": [ "..." ],
    "textTransform": "global",
    "textTransformPresets": [ "..." ],
  }
}

Example

Fixes all use cases in the issue description:

{
  "*": {
    "settings": {
      "color": {
        "colorPresets": [ "..." ],
        "gradientCustom": "none",
      },
      "typography": {
        "fontFamily": "none"
      }
    }
  },
  "global": {
    "settings": {
      "typography": {
        "lineHeight": "global",
        "fontFamily": "global",
        "fontFamilyPresets": [ "..." ],
      },
    }
  }
}

[oandregal]

@jorgefilipecosta @youknowriad is this a fair summary of what we need to do? Are there alternatives you want to be considered? We'd need to solve this one before landing into core #27295

[youknowriad]

Hi @nosolosw I think it's a good summary, though I'm not sure I like the proposal because if the values are "block", "global", "none". It means that config only enables or disables things in a particular context (a boolean) but it doesn't seem to solve the issue for config options that are not booleans. For instance, the available "units" per context...

[jorgefilipecosta]

Hi @nosolosw, this issue is a good summary of the discussion.

Settings that control the UI can have "all", "block", and "global", "none" as values. Now they're booleans.

Do we have as a requirement that for a given block, themes may enable something in the global panel of that block, but disable it at the block level in the inspector?

If this is not a requirement I guess adding the "*" context is enough.

If this is a requirement I think it may make sense for some settings to have different values at the block level than they have at the global level but for other settings, it does not make much sense e.g: for the presets they should be the same at the global and block level. Otherwise, when the user is editing the presets we would probably need a UI that allows to edit for global and for block-level.

[oandregal]

Following the conversation at #27230 I've started a PR at #28110 to make settings and styles top-level keys of the theme.json, which seems to be some common ground we all agree to get this in motion.

[oandregal]

This has been consolidated at #28163 which has more context about how all things fit together, so I'm closing it.

[oandregal]

Wanted to braindump the things discussed at #28163 to have a link to point to without polluting the main thread. The conversation still happens there.

How to offer more granularity for defining where a UI control for a property should be shown? We landed at:

• "all" or true: means everywhere.
• "none" or false: means nowhere.
• "block" means only at the block sidebar.
• "global" means only at the global styles sidebar at the site editor.

Example of theme.json

"color": {
  "custom": true // Show UI for custom colors everywhere.
},
"typography": {
  "lineHeight": "global" // Show UI for lineHeight only in the global styles sidebar at the site editor.
}

We need to accommodate these thoughts to other visibility concerns for the UI controls. See #28163