📑 Contents

• Installation
• Basic usage
• Optimized imports
• Transition catalog
• Motion tokens
• Utility classes
• Scripts
• Development
• License

📦 Installation

npm install @gem-org/gemsitions

For a prerelease tagged on npm:

npm install @gem-org/gemsitions@beta

The consuming application must use react and react-dom ^19.

@gem-org/gem-system is an optional peer. Gemsitions reads --gem-* tokens from the host when they exist, and falls back to neutral values otherwise. It does not reimplement design-system components (Button, Modal, Shine, etc.).

🚀 Basic usage

Import the complete stylesheet once in your application entry point, then use the transitions:

import "@gem-org/gemsitions/styles.css";
import { FadeTransition, SlideTransition } from "@gem-org/gemsitions";

export function Panel({ open }: { open: boolean }) {
  return (
    <FadeTransition isIn={open}>
      <SlideTransition isIn={open} from="bottom">
        <div>Hello</div>
      </SlideTransition>
    </FadeTransition>
  );
}

The main package import is convenient for prototypes or applications that use most of the library.

⚡ Optimized imports

To load only what your application uses, import the tokens, optional utilities, and the transition subpath:

import "@gem-org/gemsitions/tokens.css";
import "@gem-org/gemsitions/utilities.css"; // optional layout / overflow / position
import "@gem-org/gemsitions/fade-transition.css";
import { FadeTransition } from "@gem-org/gemsitions/fade-transition";

export function Panel({ open }: { open: boolean }) {
  return (
    <FadeTransition
      isIn={open}
      classNames={{ root: "gemst-relative gemst-overflow-hidden" }}
    >
      <div>Hello</div>
    </FadeTransition>
  );
}

Import tokens.css only once. Prefer one CSS + JS subpath per transition you use. If you prefer not to manage per-transition stylesheets, use styles.css (tokens + utilities + all transition sheets).

Motion helpers are also available from @gem-org/gemsitions/utils, and duration / easing / intensity tokens from @gem-org/gemsitions/tokens.

🧩 Transition catalog

Gemsitions includes 14 transitions, organized by purpose.

🚪 Enter, exit & mount

• FadeTransition — gradual opacity enter / exit.
• SlideTransition — edge slide (top / bottom / left / right), optional fade.
• ScaleTransition — pop-in / pop-out for modals, tooltips, and popovers.
• CollapseTransition — dynamic height or width (0 ↔ auto) for accordions and menus.

📐 Morphing, layout & containers

• SharedLayout — FLIP morph between collapsed and expanded rects (layoutId for cross-tree morphs).
• AutoAnimateContainer — animates host dimensions when inner content changes.

📋 Lists, grids & sequences

• StaggerGroup — cascading enter / exit with staggerDelay.
• FlipList — animated reorder / filter (FLIP; stable keys required).
• SwipeToDismiss — drag-to-dismiss for toasts and list items.

🪟 Views, pages & flows

• CrossFadeView — soft view switching with optional pagination and swipe.
• PushStack — depth stack (push / pop) for wizards and navigation.
• ViewTransition — reactive wrapper around document.startViewTransition(), with CSS fallback when the API is missing.

✨ Content micro-animations

• AnimatedNumber — counter-style interpolation, or formatted figure morph (fade / up / down).
• TextMorph — title / label copy swap, with splitBy tokens and staggerDelay.

Shared behavior

Most transitions accept timing props (duration, delay, easing — including { enter, exit }), asChild, isDisabled, ignoreReducedMotion, className / style / classNames, and phase emits (onX / outX).

Presence wrappers (Fade, Slide, Scale, Collapse) also support keepMounted, initial, and onPhaseChange. Prefer transform and opacity; with prefers-reduced-motion: reduce, motion snaps unless ignoreReducedMotion is set.

Public classes use the .gemst-* prefix (BEM). Motion custom properties use --gemst-*.

🎨 Motion tokens

Duration, easing, and intensity live in the tokens subpath (TypeScript + generated CSS):

import { duration, easing, intensity } from "@gem-org/gemsitions/tokens";

import "@gem-org/gemsitions/tokens.css";

| Family | CSS examples | | --- | --- | | Duration | --gemst-duration-fastest … --gemst-duration-slower | | Easing | --gemst-easing-standard, --enter, --exit, --emphasized, --linear | | Intensity | --gemst-intensity-* |

Color, spacing, and typography come from the host (--gem-*) when available; Gemsitions does not ship a design-system palette.

🧰 Utility classes

Optional layout / overflow / position helpers with no Design System dependency:

import "@gem-org/gemsitions/utilities.css";

| Group | Classes | | --- | --- | | Layout | .gemst-flex, .gemst-grid, .gemst-inline-flex, .gemst-block, .gemst-hidden | | Overflow | .gemst-overflow-hidden, .gemst-overflow-auto, .gemst-clip | | Position | .gemst-relative, .gemst-absolute, .gemst-inset-0, .gemst-isolate |

Pass them via className or classNames slots. Transition SCSS only controls motion and rigid structure.

🛠️ Scripts

• npm run dev — starts Storybook at http://localhost:6006.
• npm run build — syncs "exports", builds the library, subpaths, and CSS into dist/.
• npm run build-storybook — builds the static documentation.
• npm run bundle — measures barrel and subpath bundle sizes.
• npm run typecheck — checks TypeScript types.
• npm run lint — runs ESLint.

🧑‍💻 Development

• Transitions live in src/transitions/<Name>/.
• Motion tokens live in src/tokens/ (duration, easing, intensity).
• Shared helpers live in src/utils/.
• Published TS/TSX does not import CSS/SCSS — the host loads emitted sheets.
• Public classes use the .gemst-* prefix and BEM naming.
• TypeScript is strict and any is not allowed.
• Storybook is the development and documentation environment.
• Complements @gem-org/gem-system and @gem-org/gemffects; do not reimplement their UI or visual effects here.

📄 License

MIT