Choose a component or a motion primitive

A Component covers a complete interaction that can enter a product: a copy button, drawer, filter grid, upload queue, or inline validation flow. It owns control structure, business states, keyboard and focus paths, errors and recovery, reduced motion, and runtime dependencies together. Each Motion Lexicon Component page provides a realistic preview, the actual React source, a shadcn Registry install path, and links to its underlying Primitives. A team can begin with a working whole and adapt copy, data, and visual language to its design system.

A Motion Primitive focuses on one behavioral rule such as fade, slide, stagger, easing, press feedback, or crossfade. It fits an interface whose structure and business state are already established and whose current task is to decide how an object arrives, leaves, responds to input, or preserves continuity. A Primitive page supplies parameters, implementation rules, related vocabulary, a reduced-motion strategy, source, and a Registry install path. That narrow boundary lets one rule serve several Components and gives design and engineering shared language for timing, space, and interruption.

List the objects and states named by the request. A button may need pending, success, failure, and repeat action. A filter surface may update criteria, result count, list content, empty state, and focus. A drawer may own its trigger, backdrop, focus trap, dismissal gesture, and focus return. These requests have a complete interaction boundary, so a Component provides the closest useful starting point. It keeps dependent states in one contract and lets the team validate the real task immediately.

Next, inspect the structure already owned by the product. An existing menu may already handle focus and keyboard navigation while needing a continuous highlight. An existing list may already own filtering and empty state while needing a clear handoff between old and new cards. An existing button may already cover request states while needing press feedback. A Primitive gives these cases a smaller adaptation surface. The product keeps its semantics and state source, then applies one explicit motion rule to the relevant object and validates it in the real layout.

When starting from a Component, run the complete interaction first and inspect the Motion foundations listed on its page. A copy button combines press feedback and text morphing in one stable location. A filter grid applies crossfade, stagger, and translation at different phases. A drawer places slide and spring behavior inside a focus-complete layer. These relationships explain why the Component moves as it does and identify rules that can be tuned independently. After changing a Primitive parameter, retest pending, error, repeat-action, and reduced-motion paths in the full Component.

When starting from a Primitive, place the behavior back inside the existing component contract. Staggered cards also require stable data order, stable keys, a bounded first group, and repeat-filter behavior. A direction-aware menu also requires navigation hierarchy, a return direction, and a focus target. Text morphing in a button also requires stable width, state copy, and an assistive-technology announcement. The Primitive supplies the precise rule while the product Component continues to own business facts. This ownership keeps local motion connected to state and makes reuse understandable.

Adaptation has three practical layers: content, rules, and structure. Content changes names, copy, icons, color, and data while preserving the interaction’s state relationships. Rules change duration, easing, distance, reveal order, and reduced-motion expression. Structure changes triggers, participating objects, the state graph, focus order, and recovery. Content-level work often begins efficiently from a Component. Rule-level work follows related Primitives. Structure-level work requires a fresh review of the Component API and business state source. Naming the layer early gives design, engineering, and testing one shared boundary.

Technical cost belongs in the choice as well. Component pages state runtime engine, dependencies, and cost level so a team can assess Motion, GSAP, Three.js, WebGL, or CSS before installation. A Primitive usually has a narrower dependency and API surface, which suits selective adoption inside an existing design system. Both paths still require checks for server rendering, layout stability, compositor-friendly properties, interruption, and `prefers-reduced-motion`. The page preview supports judgment, source and Registry files reveal the delivered implementation, and the product environment provides final acceptance.

A practical workflow can stay short: write the user event and expected outcome in one sentence; list objects, states, focus, and recovery; choose a complete Component or one Primitive; open a realistic preview in the matching directory; inspect source, dependencies, and related rules; install into a product branch; then test real data across default, failure, repeat-action, and reduced-motion paths. Each step leaves verifiable evidence and turns the choice from visual preference into a shared judgment about task, state, and runtime boundaries.

Reuse can also improve the library. When the same local rule appears across several product Components, its Primitive deserves stronger parameters, vocabulary, or review guidance. When a Primitive repeatedly appears with the same control structure, states, and accessibility path, an existing Component may need a broader public API or a new Component candidate may have emerged. A contribution should record the real event, boundaries, failure modes, and validation result. Components then remain complete and usable, Primitives remain clear and reusable, and both collections evolve through product evidence.