Name the field for the editor, not for the component
Schema field names leak into the Studio. If they were chosen to satisfy a component prop, the person filling them in pays for it every day.
A schema is read far more often by the people writing content than by the people writing components, and it is the only documentation most of them will ever get. The title, the description and the preview are the interface.
Describe the outcome, not the mechanism
A field called containerWidth with no description asks an editor to know what a container is. "Bar width — how wide the navigation content sits inside the bar" asks them to know what they want, which they already do.
If a field needs a developer in the room to fill in, the schema has not finished being written.
Previews are part of the model
A list of eleven identical "Section" rows is a list with no information in it. Every block in this starter prepares a preview from its own content — the heading, the number of items, whether it is published — because the person choosing between them is looking at the list, not the schema.
The same applies to groups and fieldsets. Ten fields in one column is a form. Ten fields split into Content, Design and SEO is a decision about what an editor has to think about at once.
The cost of getting it wrong is invisible
Nobody files a ticket saying the field labels are confusing. They ask you to fill the page in for them instead, and that request arrives once a week forever.
Written by
Priya Raman
Design Systems Engineer
Priya works on the seam between design tokens and the components that consume them, and is unreasonably interested in how colour behaves when someone else picks it.
