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.

Sign up for GitHub

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

Already on GitHub? Sign in to your account

theme.json spec: document link color feature #22929

Merged
merged 1 commit into from
Jun 8, 2020
Merged

theme.json spec: document link color feature #22929

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
59 changes: 46 additions & 13 deletions docs/designers-developers/developers/themes/theme-json.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -16,8 +16,6 @@ The Block Editor surface API has evolved at different velocities, and it's now a

This describes the current efforts to consolidate the various APIs into a single point – a `experimental-theme.json` file that should be located inside the root of the theme directory.

When this file is present a few Block Editor mechanisms are activated.
Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We now enqueue the presets as CSS variables whether or not the theme uses theme.json.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Interesting, where this happens, do we have a dev note planned for this and a Core ticket to backport the change?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Also, it seems like the logical next step is to apply the block styles as inline styles using the CSS variable in this case. That way, we won't require any CSS from the theme author when defining custom presets.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It was done at #22722, because for link color we are referencing colors using preset CSS variables, and in that case, we need the variables even if the theme does not support theme.json.

I agree we need to update the current way to reference colors to be based on CSS vars like we are doing here. I had a PR for that #21490 so I guess we can reopen and continue that work.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hi @youknowriad, @nosolosw This link requires the CSS var presets so we will need to include the global styles generation mechanism in core. It is a big step I guess may be able to do it but in case we don't want to do it, I guess a possible way to go would be to rely on condition "process.env.GUTENBERG_PHASE === 2" if the condition matches we reference the colors using the CSS variables otherwise we reference by value (for now), if we add this check into

gutenberg/packages/block-editor/src/hooks/color.js

Line 275 in 784abc4

link: colorObject?.slug
, we avoid the need to backport global styles engine into the core (instead of reference we temporarily reference always by value on the plugin). I guess we don't need to make this decision now but it is a possibility we have. This possibility also does not causes problems with deprecations etc.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is the "link color" pr something that is going to be included in 5.5 even if we don't have "theme.json" ready? If it's the case, we might need a dev note there too right?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

(Just read the previous comment where you reply to the question)

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I've expressed my conservative views on this topic before. However, I also appreciate how the link color feature is a great one to have in 5.5. What if we port to core only the functions that take presets from add_theme_support and the core defaults lib/experimental-theme.json (in case the theme doesn't define any)? Note that we also use the core defaults file for controlling the editor features. cc @gziolo

My thinking is that if we do that, and don't open it to third-parties (no hooks, no reading theme.json from themes, etc), we have leeway to modify the format in the next WordPress version. Is that correct? If it's not, I may suggest looking at alternatives (perhaps not using the core file and use inlined PHP variables within the specific functions or something like that). What do you think?


### 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.
Expand Down Expand Up @@ -98,7 +96,7 @@ Some of the functions are context-dependant. Take, as an example, the drop cap:
}
```

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 block context wouldn't make sense based on the current implementation so would be ignored, but it could be used by plugins that extend its functionality.
In the example above, we aim to encapsulate that the drop cap should be disabled globally but enabled in the paragraph context. Based on the current implementation, the drop cap in the Image block context wouldn't make sense so it would be ignored (but it could be used by plugins that extend its functionality).

## Current Status

Expand Down Expand Up @@ -159,16 +157,29 @@ If the `experimental-theme.json` contains any presets, these will take precedenc

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:
#### Color Properties

| Context | Background | Gradient | Link | Text |
| --- | --- | --- | --- | --- |
| Global | Yes | - | - | - |
| Paragraph | Yes | - | Yes | Yes |
| Heading [1] | Yes | - | Yes | Yes |
| Group | Yes | Yes | Yes | Yes |
| Columns | Yes | Yes | Yes | Yes |
| Media & text | Yes | Yes | Yes | Yes |

[1] The heading block represents 6 distinct HTML elements: H1-H6. It comes with selectors to target each individual element (ex: core/heading/h1 for H1, etc).

#### Typography Properties

| Context | Text's Color | Background's Color | Background's Gradient | Font Size | Line Height |
| --- | --- | --- | --- | --- | --- |
| Global | - | Yes | - | - | - |
| Paragraph | Yes | Yes | - | Yes | Yes |
| Heading [1] | Yes | Yes | - | Yes | Yes |
| Group | Yes | Yes | Yes | - | - |
| Columns | Yes | Yes | Yes | - | - |
| Media & text | Yes | Yes | Yes | - | - |
| Context | Font Size | Line Height |
| --- | --- | --- |
| Global | - | - |
| Paragraph | Yes | Yes |
| Heading [1] | Yes | Yes |
| Group | - | - |
| Columns | - | - |
| Media & text | - | - |

[1] The heading block represents 6 distinct HTML elements: H1-H6. It comes with selectors to target each individual element (ex: core/heading/h1 for H1, etc).

Expand Down Expand Up @@ -245,13 +256,14 @@ The list of features that are currently supported are:
"styles: {
"color: {
"background": <value>
}
}
}
},
"core/paragraph": {
"styles": {
"color": {
"background": <value>,
"link": <value>,
"text": <value>
},
"typography": {
Expand All @@ -264,6 +276,7 @@ The list of features that are currently supported are:
"styles": {
"color": {
"background": <value>,
"link": <value>,
"text": <value>
},
"typography": {
Expand All @@ -276,6 +289,7 @@ The list of features that are currently supported are:
"styles": {
"color": {
"background": <value>,
"link": <value>,
"text": <value>
},
"typography": {
Expand All @@ -288,6 +302,20 @@ The list of features that are currently supported are:
"styles": {
"color": {
"background": <value>,
"link": <value>,
"text": <value>
},
"typography": {
"fontSize": <value>,
"lineHeight": <value>
}
}
},
"core/heading/h4": {
"styles": {
"color": {
"background": <value>,
"link": <value>,
"text": <value>
},
"typography": {
Expand All @@ -300,6 +328,7 @@ The list of features that are currently supported are:
"styles": {
"color": {
"background": <value>,
"link": <value>,
"text": <value>
},
"typography": {
Expand All @@ -312,6 +341,7 @@ The list of features that are currently supported are:
"styles": {
"color": {
"background": <value>,
"link": <value>,
"text": <value>
},
"typography": {
Expand All @@ -325,6 +355,7 @@ The list of features that are currently supported are:
"color": {
"background": <value>,
"gradient": <value>,
"link": <value>,
"text": <value>
}
}
Expand All @@ -334,6 +365,7 @@ The list of features that are currently supported are:
"color": {
"background": <value>,
"gradient": <value>,
"link": <value>,
"text": <value>
}
}
Expand All @@ -343,6 +375,7 @@ The list of features that are currently supported are:
"color": {
"background": <value>,
"gradient": <value>,
"link": <value>,
"text": <value>
}
}
Expand Down