Add docs for variations key in theme.json

[oandregal]

Follow-up to #46343

What?

This PR adds docs for the variations key added to theme.json in WordPress 6.2.

Why?

We should aim to document every aspect of the theme.json specification, so it's clear to extenders.

How?

By adding the respective section to the theme.json how-to docs.

Testing

Inspect the new section and proofread.

Read it as part of the whole document.

[andrewserong]

This reads well to me, just left a tiny grammatical nit, but feel free to ignore it.

Thanks for updating the docs! ✨

[carolinan]

Today I have had more time to test whether it works with block style variations added from themes and plugins.
I found this reply from @tellthemachines:
#49550 (comment)

Thanks for bringing this up!

it only works for CORE styles (for example, the "rounded" style in the image block), not custom styles registered via register_block_style

Correct, the initial implementation only included core style variations, with the standard design tools. Because existing custom style variations are styled via a classic stylesheet, which depending on specificity might not be overridable with the core design tools such as color, typography etc.., custom styles were excluded then.

I'm thinking that the custom CSS field could be leveraged to solve that problem, and also that it should be possible to add new custom variations from theme.json. I opened an issue in #49602 suggesting some next steps.

When testing variations in theme.json with the theme-registered custom styles, I even get PHP warnings. The PHP warnings and the limitation is not relevant for this PR other than making sure that the documentation explains that only core block style variations work.

[oandregal]

Thanks @carolinan for the context. I pushed 1f2098d for clarification and tested that block variations defined via block.json work.

[oandregal]

@carolinan I almost forgot to mention that #49807 will fix the error for Gutenberg when an unregistered style variation is used in the theme.json.