# Motion Canonical: https://socra.design/principles/motion The normative spatial and interruptible behavior for every transition. Motion explains cause and effect: transitions originate at the action, use retargetable springs, and never make a user wait for choreography to finish. Status: ready. Prefilled as the decision system for every future page. Library: UI knowledge ## Anatomy - A named user outcome. - A decision rule that removes subjective taste. - A semantic design relationship and platform conformance reference whenever the rule reaches UI. - A deletion test: if the element does not create value, simplify or remove it. ## States - **Rest:** Shows the stable, enabled component without implied activity. - **Hover:** Adds pointer affordance without moving content or changing meaning. - **Focus:** Shows the shared visible focus treatment without depending on hover. - **Pressed:** Acknowledges active input immediately and returns cleanly on release. - **Selected:** Uses a neutral surface plus native selected semantics when selection applies. - **Disabled:** Remains legible, unavailable, and absent from misleading interaction feedback. - **Loading:** Preserves context while honestly identifying work that has not completed. - **Error:** Places the failure and recovery path beside the action or content that failed. ## Motion Stable state changes respond immediately. Appearance, expansion, and morphing begin at the triggering origin and use an interruptible spring that can retarget from its live position and velocity. When spatial motion is not meaningful, the component changes without decorative travel. ## Usage - Use the owning platform implementation first. Each renderer improves once and every product on that platform inherits the fix. - Name the user job before the component. A component earns a place only when it helps the user decide, act, recover, or understand. - Promote missing behavior into the owning platform domain. Product-local UI creates drift; platform contracts preserve shared meaning and native quality. - Raise luminance to bring a surface forward. Depth reads as light. A surface that comes toward the reader catches more of it, so a raised panel, a selected tab, a menu, a popover resolves LIGHTER than what it sits on — in dark mode away from the canvas, in light mode toward the white it cannot exceed. The ladder runs page, resting card, elevated, and never doubles back. ## Avoid - Do not build a product-local replacement. A local implementation splits behavior, access requirements, and future migrations. - Do not copy theme values. Semantic values are shared system roles and are consumed by meaning. - Do not add decoration as a substitute for structure. If the hierarchy is weak, fix the hierarchy. - Do not darken a surface to lift it. Darkening in a dark theme pushes a surface INTO the page — it reads as a hole cut in the canvas rather than a panel resting on it. Sinking a surface to make it stand out is the most common way a dark interface loses its depth. ## Tokens - `designTokens.color[mode].color.brand.primary`: One primary action per screen. - `designTokens.spacing.role.contentGap`: Use semantic relationships instead of local measurements. - `designTokens.accessibility.target.minimum`: Equivalent access begins with a viable interaction target. ## Example ```tsx ``` ## Guidelines ### Ownership Components own transitions in shared source; products never re-choreograph them. ### Origin Appear, expand, and morph transitions accept the triggering action’s origin so cause and effect remain spatially continuous. ### Springs All transitions are springs and fixed-duration keyframes are outside the system, because spring motion behaves like matter (design). ### Interruption Every transition is interruptible and retargets from current position and velocity when interrupted, canceled, or reversed, because motion that cannot yield to input makes the interface lie about being ready. ### First frame Motion advances on the first frame after the input that caused it; an opening frame spent at rest reads as the product hesitating, not as ease. ### Arrival Opening answers the reader at least as briskly as dismissal, because a surface slower to arrive than to leave reads as reluctance. ### Compositing A surface that dims what is behind it paints the dim on its own scrim and never lowers the opacity of the content, so a moving surface composites one layer instead of re-rasterizing the page beneath it. ### Layer promotion Layer promotion is armed for the duration of a motion and released at rest.