Fluid

Your brand, in motion. Open-source motion for React, built on one idea: outlines that flow on real springs. Shapes become your logo, pills flow between options, words come out of a blur, and windows grow out of the card that opened them. Every piece wears your logo, colours and font.

Documentation · Components · Mascots · Changelog

Fluid has three parts:

• An engine, @usefluid/motion: closed-form springs and Metamorph, contour morphing between any two shapes or logos. No dependencies.
• Pieces you copy into your project with the CLI: openings, controls, characters, text and transitions, all made with the engine.
• Agent skills that teach your coding agent to set up your brand, pick and adapt pieces, build new ones and record them as video.

Pieces

Every piece:

• reads ten --fluid-* CSS variables, so it wears your brand;
• has 44 px touch targets and a visible focus ring;
• works with the keyboard and tells screen readers what changed;
• goes straight to its final state when the system asks for reduced motion;
• fits on a 320 px screen, and is tested in Chromium and WebKit, the engine behind Safari.

Each piece folder has a README with an example, its props and its accessibility notes.

Quick start

npm i @usefluid/motion
npx @usefluid/cli init --out src/styles/fluid-theme.css
npx @usefluid/cli logo logo.svg --out src/lib/logo.ts
npx @usefluid/cli add splash-choice morph-dialog

The engine on its own:

import { shapes } from "@usefluid/motion";
import { MorphPath, useSpring } from "@usefluid/motion/react";

<svg viewBox="0 0 120 120">
  <MorphPath d={open ? logo : shapes.circle} fill="currentColor" />
</svg>;

useSpring({ x: open ? 200 : 0 }, ({ x }) => {
  el.current.style.transform = `translateX(${x}px)`;
});

Full API: packages/motion and packages/cli.

Agent skills

npx skills@latest add useFluid/fluidui

They only start when the project uses Fluid or you ask for it by name. More in skills.

Agents can also read the docs directly: every piece page is plain Markdown with .md at the end of its address, and llms.txt lists them all.

Repository

packages/
  motion/        the engine: springs, Metamorph and React bindings
  cli/           the fluid CLI
registry/        the pieces, one folder each: component, styles, demo and README
  index.ts       the catalogue: name, family, texts and agent prompt of each piece
  brands.ts      the example brands used in the demos
skills/          the agent skills
apps/site/       the docs and showcase site, in English and Portuguese
scripts/         packaging, recording and scaffolding

Development

npm install
npm run dev
npm test
npm run typecheck
npm run build && npm run test:e2e
npm run new -- my-piece
node scripts/build-packages.mjs

See CONTRIBUTING for what every piece needs, and the code of conduct. Security problems go through SECURITY.

License

MIT