# 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).

Four 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.
4. **Keep it current** — bring installed items up to the latest release
   without losing local work: [when asked to update](#when-asked-to-update).

## 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:

```bash
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, 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

…