docs: Improve `theme.json` ambiguos descriptions in the schema and in the doc site

[tresorama]

The theme.json is the main place where theme dev do most of their work, so it is very important that every properties of the json file is described well from a consumer perspective.

Description of every properties of the theme.json will be suggested in code editor via intellisense. So the dev will benefits if every questions about the usage of a property is already answered in the intellisense.

theme json living standard has room for improvement.

Show full default theme.json in doc page

Or at least a link to the code.

Some references: https://chakra-ui.com/docs/styled-system/theme https://tailwindcss.com/docs/theme

Use more real example of code snippets while describing

Reference: https://tailwindcss.com/docs/theme#customizing-the-default-theme

Some properties are under-described, some example:

---

settings.layout.content

This is used in children of a block that uses constrained layout.
its value is max-width value when "content" is selected as width of the child.

Currently is not clear that this refers only to constrained layout.

---

styles.spacing

These are global styles, applied to body selector

Currently is not clear where these definition will be used (body).

Same for :

• styles.typography
• styles.color
• styles.border
• styles.filter
• styles.shadow
• styles.outline

styles.color

Example of good explanation:

settings.typography.fontSize

Bonus: Some properties are maybe unnecessary

Is better that these considerations live in a separate issue, because related to a new version of the schema. I include here because they emerged in my mind while writing this issue

---

styles.border
styles.filter
styles.shadow
styles.outline
These styles are applied to body.

Why we need these ?? Dev can use styles.css for arbitrary css.

---

styles.global What about a unified global JSON object syntax for defining Top-Level styles ?? This could replace or complement styles.css and styles.elements.

Example (inspired from Chakra UI):

styles: {
  global: {
    'body': {
      color: 'var(--wp--preset--color--body-text)',
      lineHeight:  "1.5",
      fontWeight: "400"
    },
    a: {
      color: 'var(--wp--preset--color--link-text)',
     "&:hover": {
       textDecoration: "underline"
     },
    },
    input: {
      font: 'inherit',
    },
    'input[type="checkbox"]': {
      color: 'var(--wp--preset--color--brand-primary)',
    },
  },
}

[ghost]

@tresorama Thanks. Added a pull request to improve descriptions, I agree some were way too short and incomplete.

I haven't removed any you deem "unnecessary" as I can't judge that. Could you please make a separate issue for that? And also a separate one for changing the syntax and unifying things.