/fluid-functionalism

name: fluid-functionalism
description: >-
  Build React UIs with Fluid Functionalism — a shadcn/ui registry (@fluid) of
  animated components with a shared motion system: three spring speeds, a
  hover highlight that glides to the item nearest the cursor, labels that
  change weight without layout shift. Use whenever the user mentions Fluid
  Functionalism, @fluid, or fluidfunctionalism.com, asks for UI with
  satisfying/fluid/polished motion in a React, Next.js, shadcn, Radix, or
  Base UI project, builds any interface (settings dialogs, sidebars, command
  menus, chat UIs, forms, lists, tables) in a project with @fluid components
  installed, or asks to review/audit existing UI motion against the system.
  Also use before hand-writing animation code (hover highlights, icon swaps,
  weight changes, enter/exit transitions) there, so custom code follows the
  system instead of inventing timings. Each run, a bundled script reads the
  stack fresh (deps, Radix vs Base UI flavor, MotionConfig, Inter opsz axis),
  so the skill leaves no audit file in the project.

Fluid Functionalism

A [shadcn/ui](https://ui.shadcn.com) registry of components where every transition makes a state change legible: springs instead of durations, one hover highlight per list that glides to the item nearest the cursor, and labels that get heavier without moving their neighbours. Components that touch a primitive ship in two flavors — Radix and Base UI — with the same API.

Docs and live demos: <https://www.fluidfunctionalism.com> — every component page has a playground and a **Copy prompt** button whose text is a self-contained brief (install command, usage snippet, props, docs URL).

Three jobs this skill covers:

1. **Know the project** — read the stack at the start of every run (next section). The read is fast and exact, so nothing is cached and nothing can go stale. 2. **Install and compose the components** — pick the right registry item and flavor, wire it in, and compose around what's already built in. The catalog is [references/components.md](references/components.md); the craft for every doc page and top-level block — the exact behaviors, values, and reasons baked into them — is [references/craft.md](references/craft.md). The catalog maps separately installable parts to the parent section that governs them. Reading that section before composing is what separates using this library from merely installing it. 3. **Write custom UI that belongs next to them** — when you build something the library doesn't ship, follow the motion system so it moves like the rest of the app. Read [references/custom-motion.md](references/custom-motion.md) before writing any animation, hover, or state-change styling by hand.

Every run: read the stack

Before installing, composing, or advising, run the stack script on the app's directory, the one holding its `package.json` and `components.json`. That is the current directory in most projects; in a monorepo, pass it:

node <skill>/scripts/stack.mjs [apps/web]

It needs only Node, finishes in under a second, and writes nothing. It reads the dependencies FF needs (React 19, Tailwind v4, framer-motion, shadcn wiring), settles the flavor verdict, checks the two silent quality killers (`MotionConfig reducedMotion="user"` around the app, Inter without the `opsz` axis), and lists which FF pieces are installed and which same-named files are stock or local. Every line cites the `file:line` it came from. Without Node, read the same files by hand: [what to check](references/stack-audit.md#what-to-check).

**Facts are read, never remembered.** Every stack fact can be read again faster than a cached copy can be verified, and a cached verdict that drifts from the code misleads every session after it. The flavor verdict stays stable without a record because it is derived the same way each time: installed FF components first, then `package.json`. So don't write audit results into the project; they go in your reply.

**Decisions are the exception.** The code cannot show what the user decided: fluid hover declined, a stillness or an off-token duration kept on purpose. The script's `DECISIONS` line points at where earlier ones live, from the app's directory up to the repository root. Read them, honor them, and never re-raise what they settle. Recording a new one is opt-in and goes where the project already keeps intent; see [decisions](references/stack-audit.md#decisions). If the script reports a legacy audit file from an earlier version of this skill, honor its decisions and ignore its facts ([earlier audit files](references/stack-audit.md#earlier-audit-files)).

Before every install, verify the target's current files and diff any same-named file; only pass `--overwrite` when that check shows the targets are still stock.

When asked to audit or advise

Run the full audit in [references/stack-audit.md](references/stack-audit.md): on top of the stack read, it picks the 2–5 UI upgrades that would help most. Systems come first (motion tokens, fluid hover, surfaces, sizes), then components, each rated impact / effort and ranked by impact-per-effort. UI and design system only: infrastructure findings are stated as facts, never pitched as recommendations. Three rules decide how those land, and they are what separates advice from a lint report:

• **Write each one from the interface**, not from the code that causes it:

what someone using the product sees now, on which surface, how often they are looking at it, and which quality it buys back. The file and the size of the fix are the footnote, never the headline.

• **A behavior the app has never had is a question, not a finding.** Fixing

something the product already does badly is advice you give; introducing a new signature motion — fluid hover above all — changes how the whole thing feels, so ask before spending a slot on it. Stillness is often deliberate.

• **A blocked install is