Motion

Motion is the only part of this system that costs the user time. A colour is read instantly, a spacing step is read instantly, and a 300ms slide is 300ms the user spends waiting to find out what happened. That is the whole economics of this page: every animation has to buy back the time it spends, and most of them do not.

So motion earns its place by answering a question the still frame cannot answer. Where did this come from. What did my click do. Is anything still happening. Three questions, three jobs, and nothing else on the list.

The words this page uses ​

The tint / travel split is the most load-bearing distinction on this page. Almost every reduced-motion decision in this library reduces to "keep the tint, drop the travel", and the components that got it wrong got it wrong by dropping both.

The three jobs ​

Motion in a Nubisco application is doing one of exactly three things. If you cannot name which, you have decoration.

What motion is not for ​

It is not for delight, polish, brand expression or making a screen feel alive. This library is used to build a CMS, an integration console, a back office and a node graph editor. In all four, the user is doing work, and the thing that feels good is that the interface got out of the way.

The concrete prohibitions:

• Nothing animates on page load. No fade-up on cards, no staggered rows. First paint is the fastest paint, and a page that assembles itself is a page that is not ready.
• Nothing that carries data animates its data. A number does not count up. A chart does not draw itself in. A table does not stagger rows. The reader is trying to read.
• Nothing bounces, overshoots or springs. There is not a single overshoot curve in this library and there should not be. Overshoot says "toy"; these are tools that manage production infrastructure.
• Nothing loops unless something is genuinely pending. A loop is a claim that work is in flight. NbSkeleton has an animated prop precisely so a placeholder that is not waiting on anything can stop making that claim.
• Nothing animates a layout size in the application frame. NbShellPanel collapses and maximises by changing flex, with no transition on the size at all. This is deliberate: animating flex sizing inside the shell fights the sibling coordination that makes maximise work, and a panel that takes 300ms to get out of the way is a panel the user resizes twice.

Duration ​

The tokens ​

Four tokens, declared in src/styles/variables/_animations.scss and emitted on :root by src/styles/_theme.scss. These are the only motion tokens the library ships.

Choosing a step ​

Work down this table. The left column is what is moving, not how far, because the size of the thing is what sets the expectation.

The literals in the library, and which are load-bearing ​

Not every hard-coded number in the source is a mistake, so here is the honest ledger. These are conventions worth following, whether or not they are tokenised yet:

When you write a new component: use the token if a token fits, and if you write a literal, write the reason above it, exactly as Design Tokens requires for every other family.

Easing ​

Linear movement of a discrete object looks wrong, because nothing in the physical world starts and stops at full speed. Everything that starts and stops is eased. Everything that never stops is linear. That single sentence covers every correct case in this library.

Two hard rules on top of the table:

Never linear on something that starts and stops. NbCard uses 70ms linear on a hover tint, and at 70ms on a colour that is unobjectionable, because there is no travel and no perceptible ramp at that length. Do not read it as licence: any duration above ~100ms, or any travel at all, needs a curve.

Never ease-in on an enter, or ease-out on an exit. An entrance that starts slowly reads as reluctant, and an exit that decelerates reads as an element that changed its mind. This is the most common motion bug in review.

Choreography ​

Choreography is what happens when one user event moves more than one thing. The failure mode is not ugliness, it is ambiguity: two things moving independently look like two events, and the user starts looking for a second cause.

One event, one duration ​

Everything that moves because of the same click shares a duration and a curve.

NbModal is the shipped example. The scrim fades and the dialog scales and rises, and both run 0.2s, so the whole thing reads as one surface arriving rather than a backdrop plus a box.

// Modal.vue, abridged. One event, so one number, twice.
.nb-modal-enter-active,
.nb-modal-leave-active {
  transition:
    opacity 0.2s,
    transform 0.2s;

  .nb-modal--content {
    transition:
      opacity 0.2s,
      transform 0.2s;
  }
}

The corollary: do not stagger a container against its own contents. If a panel slides in and its heading fades in 100ms later, you have built two events out of one and added 100ms to the time before the panel is readable.

Things enter from where they belong and leave back through it ​

Direction is information. An element that arrives from the wrong edge tells the user it came from somewhere it did not.

NbToaster encodes this as a custom property rather than a fixed translate, so one transition rule serves six placements and each one arrives from its own edge:

.nb-toaster-enter-from,
.nb-toaster-leave-to {
  opacity: 0;
  translate: var(--nb-toaster-shift);
}

NbNotificationCenter does the same thing by flipping the sign: the panel normally drops 4px from its bell, and the --above variant, which opens upward, rises 4px instead. NbMenu rises from its trigger. Every popover in the library travels toward the thing that opened it and retreats into it.

Reflow is part of the event ​

When something leaves a stack, the survivors close the gap. That closing is not a separate animation, it is the tail of the same one, and it gets the same duration.

NbToaster is the only place in the library that does this properly, and it takes two pieces:

// The `-move` class is what animates the survivors.
.nb-toaster-enter-active,
.nb-toaster-leave-active,
.nb-toaster-move {
  transition:
    opacity var(--nb-animation-fast) ease,
    translate var(--nb-animation-fast) ease;
}

// Taken out of flow while leaving, so the toasts below slide up into the
// gap instead of snapping.
.nb-toaster-leave-active {
  position: absolute;
}

Without position: absolute on the leaving element, the gap closes instantly at the moment of removal and the survivors teleport while the departing toast is still fading. This is the single most common <TransitionGroup> bug, and the fix is two lines.

We do not stagger lists ​

Staggered list entrances are the most-cited technique in motion writing and this library ships exactly none of them, on purpose. Our lists are data tables, log rows, tree nodes and query results. A staggered table is a table you cannot read until it finishes, and the user opened it to read it.

What to do instead, when content arrives progressively:

• Show structure immediately. NbSkeleton with the right variant and lines puts the shape of the answer on screen at first paint. See Status indicators.
• Do not animate the swap. When data replaces the skeleton, it replaces it. A cross-fade between a placeholder and real content produces a moment where both are half-visible and neither is legible.

Sequencing across a flow ​

Where a sequence genuinely exists, the library uses time, not animation, to separate the beats. useConfirm() holds a resolved dialog in its success state for SUCCESS_MS (900ms) before dismissing it, and waits CONFIRM_LEAVE_MS before presenting the next queued question. Under reduced motion that second delay drops to 0, because there is no animation to wait out.

That is the pattern: separate beats with a pause between finished animations, never with a longer animation. A 900ms hold is legible. A 900ms fade is a slow interface.

The patterns we ship ​

Six shapes cover almost everything. Each one below is what the library actually does, with the file to read.

A panel changing size ​

NbShellPanel, NbBottomPanel. The size change is not animated. Collapse and maximise change flex and take effect immediately, because the panels coordinate with their siblings through flex and an animated flex-basis fights that coordination.

What is animated is the tint that tells you which state you are in: a collapsed panel dims its header to opacity: 0.6 over 0.12s ease and restores it on hover. That is causality without travel, and it costs nothing.

If you build a panel that genuinely slides, for example an inspector over content rather than beside it, that is an enter and an exit: --nb-animation-fast, ease-out in, ease-in out, travelling from and back through the edge it is docked to. See Inspectors.

A dialog appearing ​

NbModal, NbConfirm, NbCommandPalette. Scrim fades, content scales up slightly and drops into place. The scale starts near 1 and the rise is small:

.nb-modal-enter-from {
  opacity: 0;

  .nb-modal--content {
    transform: scale(0.96) translateY(-8px);
    opacity: 0;
  }
}

0.96 and 8px, not 0.8 and 40px. A dialog that zooms is a dialog whose text is unreadable for the first half of its entrance. NbCommandPalette uses scale(0.97) at 0.15s for the same reason.

A popover appearing ​

NbMenu, NbSubmenu, NbNotificationCenter, the v-tooltip directive. 0.12s, opacity plus a 4px translate toward the trigger. NbSubmenu drops the translate entirely and fades only, because a submenu appears beside its parent row and a 4px rise would read as it detaching.

The tooltip directive is the outlier: animationTime defaults to 300ms with ease-in-out, and its exit is pinned to HIDE_ANIMATION_MS = 200 in src/directives/ToolTip.directive.ts, which must equal the tooltipDisappear keyframe duration or the chip is detached mid-animation. If you change one, change both. See Tooltip.

A toast entering and leaving ​

NbToaster, NbToast. Covered in choreography above for the mechanics. The part that is motion design rather than CSS is the lifetime, in NB_TOAST_DURATIONS:

A toast carrying a cta never auto-dismisses unless an explicit duration says so, because an action that walks away while it is being reached for is not an action. The countdown bar under the toast is linear, because it is a clock: an eased clock lies about how much time is left.

A skeleton pulsing ​

NbSkeleton. A highlight sweeps across the fill, 1600ms linear infinite, driven by background-position rather than a transform so it costs nothing on a page full of them. animated: false stops it, for a placeholder that is not actually waiting on a request.

A spinner and a progress bar ​

NbSpinner rotates a quarter-turn arc at 900ms linear infinite. NbProgressBar determinate transitions transform: scaleX() at 0.15s ease; indeterminate sweeps at 1400ms linear infinite. NbButton's inline spinner matches NbSpinner's reduced-motion behaviour exactly so the two never disagree inside one product. Choosing between these four indicators is Status indicators; this page only covers how they move.

Reduced motion ​

prefers-reduced-motion: reduce is set by users who get nauseated, dizzy or disoriented by on-screen movement. It is a vestibular accommodation, not a preference for a quieter aesthetic, and it is not a request to turn the interface off.

Keep or drop ​

The four correct fallbacks ​

Every reduced-motion handler in this library is one of these four, and yours should be too.

1. Substitute a tint loop for a travel loop. The strongest pattern, because nothing is lost. NbSpinner's arc stops rotating and becomes a complete ring breathing in opacity:

@media (prefers-reduced-motion: reduce) {
  .nb-spinner__arc {
    stroke-dasharray: none;
    animation: nb-spinner-breathe 1600ms ease-in-out infinite;
  }
}

NbSkeleton does the same, swapping the travelling highlight for nb-skeleton-fade, and NbProgressBar's indeterminate track fills completely and pulses in place rather than leaving a static eighth-width stub that would read as "12% complete", which is a lie.

2. Remove the travel, keep the fade. For enters and exits. NbToaster zeroes the shift and cross-fades in place, and cancels the reflow so the stack closes gaps instantly:

@media (prefers-reduced-motion: reduce) {
  .nb-toaster {
    --nb-toaster-shift: 0 0;
  }

  .nb-toaster-enter-active,
  .nb-toaster-leave-active {
    transition: opacity var(--nb-animation-fast) ease;
  }

  .nb-toaster-move {
    transition: none;
  }
}

3. Change the timing function, keep the animation. For continuous motion that is information. NbToast's countdown bar keeps running, because how much time is left is data, but it steps instead of sweeping so nothing is gliding at the edge of vision:

@media (prefers-reduced-motion: reduce) {
  .nb-toast__progress {
    animation-timing-function: steps(8, end);
  }
}

4. Cancel outright. Only for decorative transitions on a state the component reaches either way. NbCard's hover tint, NbShellPanel's header dimming, NbStepperStep's marker colours. The end state is identical, so removing the transition removes nothing but the ramp.

Two channels, not one ​

A media query alone is not enough for anything that has to respond to the user flipping the OS setting with the page already open. NbSpinner and NbSkeleton carry the same rules twice: once in @media (prefers-reduced-motion: reduce), and once on a --reduced-motion modifier class driven by useReducedMotion().

@media (prefers-reduced-motion: reduce) {
  .nb-spinner__arc {
    stroke-dasharray: none;
    animation: nb-spinner-breathe 1600ms ease-in-out infinite;
  }
}

// Same rules from the runtime preference, so flipping the OS setting with the
// page already open takes effect without a reload.
.nb-spinner--reduced-motion .nb-spinner__arc {
  stroke-dasharray: none;
  animation: nb-spinner-breathe 1600ms ease-in-out infinite;
}

The media query handles first paint, before any script has run. The class handles the mid-session change. Duplicating the block is the cost of covering both, and it is worth paying for anything long-lived on screen.

Never leave transition: none on a value you will need back ​

NbConfirm makes this explicit. Instead of writing transition: none on the dialog, applyConfirmMotion() writes a duration of 0ms:

// src/components/Confirm.env.ts, abridged
const duration = `${reduced ? 0 : CONFIRM_LEAVE_MS}ms`

Two reasons, both real. A none left on a recycled node survives the user turning the preference back off, so the animation never comes back. And a duration is a number other code can read: useConfirm() reads the same value to decide how long to wait before showing the next queued question, so a user with reduced motion gets the shorter queue delay rather than waiting out an animation that never ran.

The script side ​

Two things are not reachable from CSS and must be handled in TypeScript. Both composables are exported from @nubisco/ui:

import { useReducedMotion, prefersReducedMotion } from '@nubisco/ui'

// Reactive, for anything that must respond to a mid-session change.
const reduced = useReducedMotion()

// One-shot, for code paths outside a reactive scope.
if (!prefersReducedMotion()) {
  el.scrollIntoView({ behavior: 'smooth' })
}

useReducedMotion() returns a readonly ref and cleans up its listener via onScopeDispose, so it is safe to call in any setup(). Use it for scrollIntoView behaviour, for scroll-behavior, and for any animation you drive from JavaScript. NbStepper handles the CSS half of this by resetting scroll-behavior: smooth back to auto under the media query, because the stepper scrolls itself when the flow advances and a programmatic smooth scroll is large-field travel the user did not ask for.

Coverage, honestly ​

47 components in src/components/*.vue animate something. 17 handle the preference. Most of the 30 that do not are tint-only and are therefore fine by the keep or drop table: NbButton's background, NbTextInput's border, NbDataTable's row highlight.

These are not fine, because they carry travel:

Fixing these is library work, not application work. Do not patch them from a consuming app with a global override: a blanket kill inside your own stylesheet will also freeze the four indicators that are handling the preference correctly, and you will have made things worse. Report the gap.

Before you write an animation ​

1. Which of the three jobs is this? Continuity, causality or feedback. If none, delete it.
2. Is anything else moving because of the same event? Then it shares this duration and this curve, and the reflow shares it too.
3. Is there a token for the duration? --nb-animation-fast covers almost every enter and exit. If you write a literal, write the reason above it.
4. Which curve? Entering ease-out, exiting ease-in, moving ease, looping linear. Never linear on anything above ~100ms that starts and stops.
5. How far and how big? More travel or a larger surface moves the duration up a step, up to the 0.4s ceiling for anything blocking.
6. Does it carry travel? Then it needs a prefers-reduced-motion block, and that block substitutes a tint rather than deleting the feedback.
7. Does it need to survive a mid-session preference flip? Then it needs the runtime class as well as the media query.
8. Does it still say the same thing with the animation removed? If a user with reduced motion cannot tell what happened, the animation was carrying meaning that should have been in the still frame.

Auditing your own app ​

Two greps. The first counts duration literals against the token scale:

grep -rhoE "(transition|animation)[a-z-]*: *[^;]*" src | grep -cE "[0-9]+m?s"
grep -rhoE "(transition|animation)[a-z-]*: *[^;]*" src | grep -c "nb-animation"

The second finds travel with no accommodation. Any file in the first list that is not in the second is a candidate:

grep -rlE "transform:|translate:|scale\(" src --include="*.vue" | sort > /tmp/moves
grep -rl "prefers-reduced-motion" src --include="*.vue" | sort > /tmp/guards
comm -23 /tmp/moves /tmp/guards

Every file the second command prints is one you must open and check: either the transform is static, in which case it is fine, or it is animated, in which case it is a defect. This is the same command that produced the coverage numbers on this page for the library itself.

See also ​

• Design Tokens for the token grammar and the override tiers, including why you must not set --nb-animation-* to 0 to disable motion.
• Status indicators for choosing between NbSpinner, NbInlineLoading, NbSkeleton and NbProgressBar. That page owns which indicator; this page owns how it moves.
• Dialogs and Inspectors for the surfaces whose enters and exits are described here.
• Accessibility overview for where reduced motion sits among the other obligations.
• Toaster and useToast for toast lifetimes, placement and the shift property.
• Tooltip for animationTime and the exit duration that has to match the keyframe.