docs: Improve theme.json
ambiguos descriptions in the schema and in the doc site
#48450
Labels
Developer Experience
Ideas about improving block and theme developer experience
[Type] Developer Documentation
Documentation for developers
[Type] Enhancement
A suggestion for improvement.
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 pageOr 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
Currently is not clear that this refers only to constrained layout.
styles.spacing
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
andstyles.elements
.Example (inspired from Chakra UI):
The text was updated successfully, but these errors were encountered: