[Theme Handbook] Include alternative way to reference presets in theme.json

[bph]

Issue Description

I see in various theme.json files two different notations to reference presets:

• "box-shadow": var:preset|shadow|natural)
• "box-shadow": var(--wp--preset--shadow--natural)

URL of the Page with the Issue

Global Settings & Styles (theme.json)>Block Styles > Referencing a style

Why is this a problem?

theme.json syntax is confusing as it is. It'll help if all forms of syntax at least have a mention so it's clear it's official syntax.

Suggested Fix

Add a mention of the syntax. Analog to the existing example.

As for the Why this syntax?

It was because when serialized as a var would be: var(\u002d\u002dwp\u002d\u002dpreset\u002d\u002dcolor\u002d\u002dwhite); So to void the unreadable markup, we decided on that format. (Jorge)

not sure if the Why is actually necessary to mention

A caveat (worth mentioning)

"using the CSS variable will allow you to do things like linear-gradient(var(--wp--preset--color--base), var(--wp--preset--color--contrast)) while the other syntax will not" (Maggie)

[github-actions[bot]]

Heads up @WordPress/docs-issues-coordinators, we have a new issue open. Time to use 'em labels.

[github-actions[bot]]

Heads up @kafleg @carolinan @TeBenachi - the "themes" label was applied to this issue.

[justintadlock]

@bph - The URL you referenced is to the Block Editor handbook. Should we open a Gutenberg ticket for it? https://github.com/WordPress/gutenberg/issues

The Theme Handbook has a dedicated page for how to reference presets here: https://developer.wordpress.org/themes/global-settings-and-styles/styles/using-presets/