Skip to content
opsinjs
Edit this page

Foundations

Motion

Springs as CSS tokens, motion chosen by the job it does, and a reduced-motion fallback declared token by token.

Motion shows where things went, such as a sheet arriving from the row you tapped. It never celebrates, never carries urgency and never delays an answer. A new surface starts with none and gains it only when you can name what it explains.

Springs as tokens

A spring is authored in tokens/motion.json as stiffness, damping and mass, sampled into a CSS linear() easing, and emitted by scripts/build-tokens.mts as two custom properties, --opsin-ease-<name> and --opsin-duration-<name>. The duration is the computed settling time, so always use the pair together. A damping ratio below 1 overshoots.

SpringOvershootsUse it for
spring-snapYesDirect manipulation, such as a switch flipped
spring-settleYesPopovers, tooltips and menus
spring-calmNoA health value on screen moving to a new reading
spring-sheetNoSheets, dialogs and full-screen pushes

Never hand-write a linear() value or tune a spring inside a component. Change tokens/motion.json and regenerate.

Choosing by job

A transition that does none of these five jobs probably should not exist.

JobBehaviourTokens
EnterDecelerates into placeease-enter with duration-base, or duration-slow for a full-width or full-height surface
ExitAccelerates, about two thirds as long as its enterease-exit with duration-fast
FeedbackAcknowledges a touch on pointer-down and settles on releaseduration-instant down, spring-snap back
NavigationThe surface beneath recedes and dimsspring-sheet
LoadingLoops, so it alone uses keyframesduration-shimmer

Duration follows distance, not importance, and duration-deliberate is the ceiling for anything a reader waits on. Use transitions wherever a reader can interrupt, because a transition reverses from wherever it is. Controls accept input while they animate.

Five interaction motions

Each is one job above, on the token kept for it, and built into the components listed. Try them, then again with reduced motion on.

Theme
Density
Text
Status
Accent theme
Accent
motion-the-five-interactions · base base · style base-lyraOpen under the product theme
motion-the-five-interactions.tsx
"use client"

import { Toast as ToastPrimitive } from "@base-ui/react/toast"
import { useState, type ReactNode } from "react"

import { Button } from "@/components/ui/button"
import { Checkbox } from "@/components/ui/checkbox"
import { Menu } from "@/components/ui/menu"
import { SegmentedControl } from "@/components/ui/segmented-control"
import { Switch } from "@/components/ui/switch"
import { Toast } from "@/components/ui/toast"

/** One labelled row: the motion's name, what to do, and the component. */
function Row({ name, hint, children }: { name: string; hint: string; children: ReactNode }) {
  return (
    <div className="flex flex-col gap-opsin-2 border-t border-edge pt-opsin-4 first:border-t-0 first:pt-0">
      <p className="m-0 flex flex-wrap items-baseline gap-x-opsin-2">
        <span className="text-opsin-headline text-foreground">{name}</span>
        <span className="text-opsin-footnote text-muted-foreground">{hint}</span>
      </p>
      <div className="flex flex-wrap items-center gap-opsin-3">{children}</div>
    </div>
  )
}

/** Raises a toast through the provider the surrounding `<Toast>` mounts. */
function RaiseToast() {
  const manager = ToastPrimitive.useToastManager()
  return (
    <Button
      variant="secondary"
      onClick={() =>
        manager.add({
          title: "Example note saved",
          description: "Throw it right or down to dismiss it.",
        })
      }
    >
      Save example note
    </Button>
  )
}

export default function MotionTheFiveInteractions() {
  const [remind, setRemind] = useState(false)
  const [summary, setSummary] = useState(false)
  const [range, setRange] = useState("recent")
  const [lastAction, setLastAction] = useState<string | null>(null)

  return (
    <Toast>
      <section
        aria-label="The five interaction motions"
        className="flex w-full max-w-md flex-col gap-opsin-4 rounded-opsin-lg border border-edge bg-card p-opsin-5 shadow-card [corner-shape:var(--opsin-corner-shape)]"
      >
        <Row name="Press" hint="Hold, then let go">
          <Button variant="primary">Save example</Button>
          <Button variant="secondary">Not now</Button>
        </Row>
        <Row name="Toggle" hint="Hold the row, then flip and tick">
          <div className="flex w-full flex-col">
            <Switch label="Example reminder" checked={remind} onCheckedChange={setRemind} />
            <Checkbox label="Send the example summary" checked={summary} onCheckedChange={setSummary} />
          </div>
        </Row>
        <Row name="Glide" hint="Choose another range">
          <SegmentedControl
            label="Example range"
            value={range}
            onValueChange={setRange}
            options={[
              { value: "recent", label: "Recent" },
              { value: "earlier", label: "Earlier" },
              { value: "all", label: "All" },
            ]}
          />
        </Row>
        <Row name="Unfold" hint="Open the menu">
          <Menu
            trigger={<Button variant="secondary">Example actions</Button>}
            items={[
              { label: "Share", onClick: () => setLastAction("Share") },
              { label: "Rename", onClick: () => setLastAction("Rename") },
              { label: "Remove", separatorBefore: true, onClick: () => setLastAction("Remove") },
            ]}
          />
          <span aria-live="polite" className="text-opsin-footnote text-muted-foreground">
            {lastAction ? `Last example action: ${lastAction}` : null}
          </span>
        </Row>
        <Row name="Arrive" hint="Raise a toast, then throw it">
          <RaiseToast />
        </Row>
      </section>
    </Toast>
  )
}
MotionWhat movesComponentsTimingUnder reduced motion
PressA capsule sinks to 0.97 and settles backButton, a button-shaped Link, the close controls on Dialog, Sheet and Toastduration-instant down, spring-snap upOne frame, no travel
Press on a surfaceA linked tile sinks to 0.98, with no overshootCard, MetricTileduration-instant down, duration-fast upOne frame, no travel
ToggleThe thumb squashes while held and travels, the tick draws itself, the dot growsSwitch, Checkbox, RadioGroupspring-snapNo squash, one frame
GlideOne puck or bar moves to the new choiceSegmentedControl, Tabsspring-snapOne frame
UnfoldA popup grows from its anchor and comes into focus from a slight blurPopover, Menu, Select, Combobox, Tooltipspring-settle in, ease-exit outA short crossfade
ArriveA toast rises from its edge, follows a swipe and leaves the way it was thrownToastspring-settle in, ease-exit outA short fade, and the swipe still follows
  • None of the five moves a value. A tile holding a reading never springs, and Value, RangeBar and ScoreDial stay still.
  • A link inside a sentence keeps its one-pixel press, because a word in running text should not change size.
  • Escape closes a popup at once, and a tooltip reached with Tab appears at once.

Health values

  • Motion never signals urgency, so nothing pulses, flashes or shakes. Alerts owns that rule.
  • A health value appears at its final figure, with no count-up and no dial sweep.
  • No overshooting spring touches a measurement, range position, status or count, because for one frame it would show a number nobody measured. A value already on screen moves on spring-calm, and its digits are replaced in place rather than rolled.

Choreography

  • Morph, do not swap. A tile that opens into a detail view becomes that view, and its value never leaves the screen.
  • Depth, not translation. An arriving surface comes forward while the one beneath recedes and dims. Nothing slides sideways or pans the screen.
  • One thing moves at a time. Stagger only a list arriving, most important first and capped, and never re-stagger what is already on screen.
  • Exits leave together. Focus moves once, when the sequence ends.

Reduced motion

Six of the thirteen motion tokens declare a fallback, which scripts/build-tokens.mts emits inside @media (prefers-reduced-motion: reduce). A fallback removes travel and keeps the cue that something changed.

TokenUnder reduced motion
spring-snap, spring-calmlinear over 0ms, so the end state arrives at once
spring-settle, spring-sheetlinear, as a cross-fade of about a tenth of a second
ease-standardlinear
duration-shimmerZero, so a skeleton stops sweeping

ease-enter, ease-exit and the five plain durations declare nothing, so a component built on them reduces itself inside the media query. A component that travels far also swaps the travel for opacity, as Sheet does.

A sheet arriving, with and without the preference
148

--opsin-ease-spring-sheet · --opsin-duration-spring-sheet. Under prefers-reduced-motion: reduce this becomes 1ms with a flat curve. The element still moves, and it simply arrives at once. The checkbox simulates the preference; if you have actually set it, app/globals.css has already applied it and the two states will look the same.

Not written yet.

Declare a fallback on the seven motion tokens that have none, then make scripts/build-tokens.mts --check fail when one is missing. What each becomes is a design decision nobody has taken.

In practice

Base UI keeps a leaving element mounted and marks it with data-starting-style and data-ending-style, so one transition covers both directions.

.sheet {
  transition:
    opacity var(--opsin-duration-spring-sheet) var(--opsin-ease-spring-sheet),
    translate var(--opsin-duration-spring-sheet) var(--opsin-ease-spring-sheet);
  opacity: 1;
  translate: 0 0;
}
.sheet[data-starting-style],
.sheet[data-ending-style] {
  opacity: 0;
  translate: 0 1rem;
}

Transition opacity, translate, scale or filter, never width, height, top or margin. The exception is an absolutely positioned selection indicator, such as the SegmentedControl puck or the Tabs bar, which may transition its width and height because it reflows nothing. An exit does not run if you unmount the element yourself.

Sound and haptics

NOT IMPLEMENTED. This component does not exist in any released version of opsinjs. There is no package to install, no module to import and no props interface to generate code against. Everything on this page is a specification of intended behaviour and may change without notice. Do not write code against it.

This component is not built yet

There is nothing to render because there is nothing to install. What you can read on this page is the specification the implementation will have to satisfy.

PlannedRoadmapWhat “planned” means

Sound and haptics may reinforce a message already on screen in words, and never carry one alone. opsinjs ships neither. Safari on iOS does not implement the Web Vibration API, so opsinjs specifies three haptic patterns for a native shell to implement: acknowledge when a user-initiated action commits, warn when the product has decided its result needs attention, and reject when it is refused. Fire one per action, make no sound by default, let people turn haptics off in the product, and share the escalation budget of visual alerts.

Tokens

TokenWhat it controlsUsed by
--opsin-ease-spring-snaplinear(0, 0.0715, 0.2271, 0.4053, 0.5722, 0.7119, 0.8198, 0.8978, 0.9505, 0.9836, 1.0025, 1.0118, 1.015, 1.0147, 1.0126, 1.01, 1.0073, 1.0051, 1.0033, 1.0019, 1)Direct manipulation only: a switch the reader just flipped, a box ticked or a radio chosen, a segmented control or a tab indicator gliding to the new choice, a pressed button settling. It overshoots by 1.5%. That is enough to feel physical but not enough to look playful. The 1.5% is the largest overshoot in the system but not the only one: `spring-settle` overshoots by 0.88%. Only `spring-calm` and `spring-sheet` reach their target without passing it.button, checkbox, dialog, radio-group, segmented-control, sheet, switch, tabs, toast
--opsin-duration-spring-snap283msSettle time for the spring-snap spring, measured from its own parameters.button, checkbox, dialog, radio-group, segmented-control, sheet, switch, tabs, toast
--opsin-ease-spring-settlelinear(0, 0.0742, 0.2328, 0.4113, 0.5758, 0.7116, 0.8157, 0.8905, 0.9412, 0.9736, 0.9928, 1.003, 1.0076, 1.0088, 1.0082, 1.0068, 1.0053, 1.0038, 1.0026, 1.0017, 1)The workhorse for chrome: popovers, tooltips, menus, selects and comboboxes unfolding from their anchor, chips and toasts appearing and disappearing, and a swiped toast springing back.combobox, menu, popover, select, toast, tooltip
--opsin-duration-spring-settle382msSettle time for the spring-settle spring, measured from its own parameters.combobox, menu, popover, select, toast, tooltip
--opsin-ease-spring-calmlinear(0, 0.0829, 0.2457, 0.4157, 0.5642, 0.6832, 0.774, 0.841, 0.8893, 0.9236, 0.9476, 0.9643, 0.9757, 0.9836, 0.9889, 0.9926, 0.995, 0.9967, 0.9978, 0.9985, 1)A health value that changes while it is already on screen: a bar re-filling from one reading to the next, a dial travelling between two values the reader has already been shown. Never a first paint and never a first reveal. A value arrives at its final figure, with no count-up, no dial sweep and no line drawing itself in (health/motion-in-health-ui rule 2). Slightly overdamped (zeta just over 1) so it never overshoots and never bounces.no component
--opsin-duration-spring-calm550msSettle time for the spring-calm spring, measured from its own parameters.no component
--opsin-ease-spring-sheetlinear(0, 0.0881, 0.2576, 0.431, 0.5798, 0.6971, 0.7854, 0.8497, 0.8958, 0.9282, 0.9508, 0.9664, 0.9771, 0.9845, 0.9895, 0.9929, 0.9952, 0.9967, 0.9978, 0.9985, 1)Large surfaces travelling a long distance: sheets, dialogs, full-screen pushes. Overdamped, because a sheet that bounces at the top of its travel reads as a dropped object.dialog, sheet
--opsin-duration-spring-sheet483msSettle time for the spring-sheet spring, measured from its own parameters.dialog, sheet
--opsin-ease-standardcubic-bezier(0.2, 0, 0, 1)Non-spring transitions where a spring would be overkill: colour, opacity, border. Fast out, slow in.accordion, body-map, button, card, checkbox, combobox, consent-sheet, dialog, menu, metric-tile, number-field, popover, progress, radio-group, scale-input, scroll-area, segmented-control, select, sheet, skeleton, slider, switch, symptom-picker, tab-bar, tabs, textarea, toast, tooltip
--opsin-ease-entercubic-bezier(0.05, 0.7, 0.1, 1)Something arriving from off-screen or from nothing. Decelerating, because an arrival should feel like it is coming to rest.no component
--opsin-ease-exitcubic-bezier(0.3, 0, 0.8, 0.15)Something leaving. Accelerating and shorter than its enter, because a reader does not need to watch a dismissal finish.checkbox, combobox, dialog, menu, popover, radio-group, select, toast, tooltip
--opsin-duration-instant80msState change with no travel: hover tint, focus ring. Also the way down of a press, which `foundations/states` applies on pointer-down and `spring-snap` brings back up.button, card, dialog, metric-tile, sheet, toast
--opsin-duration-fast140msSmall elements moving a small distance.accordion, body-map, card, checkbox, combobox, consent-sheet, menu, metric-tile, number-field, popover, progress, radio-group, scale-input, scroll-area, segmented-control, select, skeleton, slider, switch, symptom-picker, tab-bar, tabs, textarea, toast, tooltip
--opsin-duration-base220msThe default for chrome that is not spring-driven.dialog, sheet
--opsin-duration-slow360msLayout change: a list reflowing, a card expanding.no component
--opsin-duration-deliberate560msThe ceiling on a transition a reader is waiting on, such as a first-run reveal or a consent sheet, where the point is that the reader notices. No such transition may exceed it. A looping placeholder period, like the skeleton shimmer, is bounded instead by its iteration count, so a single sweep of it may run longer.no component
--opsin-duration-shimmer1600msOne sweep of a loading placeholder's sheen. This is a period, the time for the sheen to make one pass across the bar, and not a travel time. At 1600ms the movement reads as calm rather than as urgency, which the first motion rule requires of anything that is not a value the reader controls. Its consumer pairs it with a finite iteration count so the total motion stays under the five seconds at which WCAG 2.2 SC 2.2.2 engages.skeleton