Sketchbook
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.
  • variant is emphasis. It is never called role, which names an accessibility role. A status tone is feedback; a step of size is size.
  • 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 own False | True axis, never a value of State.
  • State in the design file is the interaction axis only: Rest, Hover, Focus, Press and Loading.
  • Events are change, input and click; 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

  1. Look for an existing word with sketchbook api list.
  2. Add it to spec/api.json (props, content, states.keys or events) with its meaning and, if it is drawn, its design-file name.
  3. Run sketchbook api check, then sketchbook check.

Next steps

View as Markdown