State modelling
Documenting meaningful component states
A method for reviewing default, focus, filled, validation, disabled, read-only, selected, open, and responsive states without a decorative matrix.
By Gummy UI · Published
A state exists because behavior changes
A useful state matrix begins with decisions the user or application can observe. Empty and filled controls affect labels and support text. Disabled and read-only controls look similar at a glance but have different focus, submission, and editing behavior. Open overlays introduce focus movement and dismissal. Selected items need both a visible treatment and a programmatic state.
Gummy UI names these states in component source, documentation, and Lab specimens. The goal is not to render every possible prop combination. It is to expose the conditions that change meaning, input method, focus, validation, layout, or motion so reviewers can compare the contract with the implementation.
Separate live behavior from forced specimens
A Component Lab often needs a persistent hover or focus example so several states can be reviewed at once. Those forced specimens are visual references; they are not substitutes for moving focus with a keyboard or opening the actual primitive. Gummy UI keeps live examples alongside state cards so an internal class cannot be mistaken for evidence of interaction.
This distinction matters when a material response spans several layers. A forced focus ring may look correct while the live reservoir, label, or popup behaves differently. Browser review should compare the persistent specimen with the real selector and event path, then update both if the reference has drifted.
Include environmental states
Theme, direction, viewport, input method, and motion preference are part of the state space. A control can pass its default desktop example and still fail when a long label wraps at 320 pixels, when RTL reverses horizontal navigation, or when reduced motion leaves an active transform stuck in a compressed position.
The practical approach is to keep component states and environmental axes distinct. First verify the control’s own default, active, invalid, disabled, and open conditions. Then exercise representative combinations across light and dark, LTR and RTL, compact width, keyboard and pointer, and reduced motion. This produces useful coverage without pretending to test a combinatorial infinity.
Write the expected outcome
A label such as “keyboard focus” is more useful when its expected outcome is documented: which element receives focus, which indicator appears, which relationship is announced, and what the next key does. Similar detail helps with validation, focus restoration, roving navigation, and native form participation.
Tests can then assert behavior rather than class names. Styling assertions remain appropriate for stable tokens and reduced-motion rules, but the state contract should be readable in roles, values, names, attributes, and focus. The result is a matrix that guides implementation instead of merely cataloguing screenshots.