API vocabulary
One set of names for props, content, states and events, registered in spec/api.json and checked by A1.
On this page
Every component speaks one vocabulary. spec/api.json registers the names, what they mean and how each is drawn in the design file, so variant means emphasis in every component and a state is never a prop by another name. Check A1 compares every contract against it (decision SB-0078).
The rules
- Prop keys are camelCase; prose spells them dash-case.
variantis emphasis. It is never calledrole, which names an accessibility role. A status tone isfeedback; a step of size issize.- What a component holds (its text, icons, children) is content, not a prop:
label,leadingIcon,trailingIcon. - A boolean that changes how the component looks (
disabled,readOnly,selected) is a boolean prop. In the design file it is its ownFalse | Trueaxis, never a value ofState. Statein the design file is the interaction axis only: Rest, Hover, Focus, Press and Loading.- Events are
change,inputandclick; any other event is custom and carries the element prefix (sb-toggle).
Read it
sketchbook api list
sketchbook api list button
sketchbook api explain readOnly
sketchbook api check
list shows each name as canonical, alias or extension and ends with the totals. check fails on any name that is not registered.
When code spells a name differently
A contract keeps the name the code uses (check C3 compares them). Register the difference under aliases: the canonical name, and a value map when values differ (default -> primary). An alias is visible debt: A1 warns about it on every run until the component's API is migrated. Sketchbook's components have none left except field-set.legend, Field Set's legend drawn as Label text (SB-0122).
When a name belongs to one component
Register it under extensions with its reason (button.type: native form behavior). An extension that several components share belongs in props.
Add a name
- Look for an existing word with
sketchbook api list. - Add it to
spec/api.json(props,content,states.keysorevents) with its meaning and, if it is drawn, its design-file name. - Run
sketchbook api check, thensketchbook check.
Next steps
- Contracts: where a component's props and events are declared.
- Check list: A1 and the checks around it.
- Troubleshooting: what the A1 warning means.