Interaction Spec

Origin & evolution

The need🫀NeedUserA user need, pain, desire, or constraintView reference → grew with the design-to-engineering handoff. As design systems🧰Design SystemDesign SystemThe root design system entityView reference → matured, teams found that handing over visuals was not enough; the behavioural detail had to travel too. Mature systems now document each component's full state set, default, hover, focus, active, disabled, error, plus the transitions between them and the motion values that govern them, timing and easing, so an animation is specified as "200ms ease-out" rather than left to feel.

The accessibility dimension turned this from good practice into a requirement. The W3C's ARIA Authoring Practices Guide enumerates, for each common widget, the keyboard commands and focus behaviour expected of it, because browsers give ARIA widgets no keyboard support for free; authors must build it. A combo box or a dialog has a defined set of key bindings and a defined focus order, and the interaction spec is where a team records which pattern a component follows and how it meets it.

How it works in practice

A team specs a dropdown menu. The spec states it: opens on click or Enter, closes on Escape, moves the highlight with the arrow keys, wraps at the ends, and returns focus to the trigger on close. Motion is 150ms ease-out on open, 100ms on close. The focus ring is the system focus token, never suppressed. An engineer builds against this without asking, and a tester checks against it without inventing pass criteria. When a later redesign tries to swap the open animation for a 400ms bounce, the spec is the record that says the agreed value was 150ms, so the change is a decision⚖️DecisionStrategyA recorded decision with context, rationale, and consequencesView reference → rather than a drift.

Interaction Spec vs. its neighbours

• Design component🧱Design ComponentDesign SystemA reusable UI componentView reference → is the object; the interaction spec is its behavioural contract. The component is the button; the spec is the documented account of how the button behaves under every input. One component is specified by one spec.
• Design guideline📌Design GuidelineDesign SystemA design usage guidelineView reference → is broad and principle-level ("motion should feel responsive, under 200ms"); an interaction spec is narrow and per-component ("this menu opens in 150ms ease-out"). The guideline sets the rule; the spec applies it to a named component.
• A11y annotation🦻A11y AnnotationAccessibilityAn accessibility annotation on a designView reference → is the accessibility layer specifically, the ARIA roles, labels, and screen-reader behaviour marked up on a design. An interaction spec is wider, covering motion and general behaviour, and overlaps the annotation🗯️AnnotationDesign SystemA note or markup on a design artifactView reference → precisely where keyboard and focus live.

In the graph

In the Unified Product Graph, an interaction spec sits in the Experience, Design & Brand region as a leaf attached to its component by a design_component_specified_by_interaction_specDesign Componentspecified byInteraction Spechierarchy edge. Holding behaviour in a node of its own, rather than burying it in a component's free-text description, makes the design-to-engineering contract explicit and checkable: a component with a populated visual definition but no linked spec is an object whose look is agreed and whose behaviour is not, which is exactly the gap that produces guessed transitions and missing keyboard support downstream.