───────────────────────────────────────
F L U I D F U N C T I O N A L I S M
───────────────────────────────────────
Fluid Functionalism
Refined UI components with satisfying hover.
A shadcn/ui registry of components, the systems they share, and blocks that compose them. Every transition exists to make a state change legible: springs instead of durations, one hover highlight that glides from item to item under your cursor, and labels that get heavier without shifting the layout. Components that touch a primitive ship in two flavors, Radix and Base UI, with the same API on both.
Docs and demos · Browse components · Compare with shadcn/ui
Install
A new app can start with every component installed and wired, from one command:
npx shadcn@latest create -n my-app -t next https://www.fluidfunctionalism.com/r/starter/default.json
Replace default with the settings you want, joined by dashes: radix, pill, compact, lucide/tabler/phosphor/hugeicons, light/dark. The home page builds this command from your Make them yours settings.
In an existing project, add the registry once:
npx shadcn@latest registry add @fluid
Then install any component, system, or block by its registry name:
npx shadcn@latest add @fluid/button
Or install straight from the URL, without adding the registry:
npx shadcn@latest add https://www.fluidfunctionalism.com/r/button.json
Dependencies, shared libs, and hooks resolve on their own.
Pick a flavor
Every component that touches a primitive has both a Radix and a Base UI flavor. The bare name installs Radix. Put base/ in front of it for Base UI:
npx shadcn@latest add @fluid/base/button
The URL form is https://www.fluidfunctionalism.com/r/base/button.json. Dependencies follow the flavor you pick, so a Base UI dialog pulls in the Base UI button. Components built on top of a flavored one (AskUserQuestions, Banner, Calendar, ColorPicker, CommandMenu, InputCopy, InputMessage, and the blocks) accept base/ too. Everything else has one source and installs from the bare name in either kind of project. The tables below list the names.
Overwrite the stock files
A stock shadcn project already has button.tsx, dialog.tsx, tooltip.tsx, and friends. This library installs under the same names, so pass --overwrite to replace them:
npx shadcn@latest add @fluid/dialog --overwrite
Without the flag the CLI asks per existing file, and a non-interactive shell (a coding agent, a CI job) exits at the first question.
Load Inter with its optical size axis
Font weight animations use Inter's wght and opsz axes together: the heavier weight widens a label, a tighter optical size pulls it back, so text changes weight without moving its neighbours. Load the variable font with both axes.
Self-hosted, the way the docs site does it:
@font-face {
font-family: "Inter";
src: url("/fonts/InterVariable.ttf") format("truetype");
font-weight: 100 900;
font-display: swap;
}
With next/font/google, ask for the axis: Inter({ subsets: ["latin"], axes: ["opsz"] }).
With an AI coding agent
Every doc page and playground has a Copy prompt button. The prompt is a self-contained brief: the install command, a usage snippet, the props, the built-in behaviors to compose around, and the docs URL. Paste it into your agent and it wires the component in without fetching anything.
An agent that reads the docs on its own gets Markdown. llms.txt lists every page, and any docs URL with .md added (or fetched with Accept: text/markdown) returns the install commands for both flavors, a usage snippet, and the full props tables. llms-full.txt is every page in one file.
For a whole project rather than one component, install the /fluid-functionalism skill:
npx skills add mickadesign/fluid-functionalism
The source lives in skills/fluid-functionalism. It reads the stack fresh on every run with a bundled script, so it installs the right flavor and leaves no audit file in your project. Alongside it sit the component catalog, the interaction-design decisions built into each component, and the rules for writing custom motion next to them.
Components
Install with npx shadcn@latest add @fluid/<name>. A second name means the component has a Base UI flavor.
| Component | Registry name | What it does |
|---|
| Accordion | accordion · base/accordion | Collapsible sections with animated expand/collapse and fluid hover in grouped mode |
| AskUserQuestions | ask-user-questions · base/ask-user-questions | Stepped question flow with single/multi-select, an inline "other" input, skip, and multi-question navigation |
| Badge | badge | Compact label with solid and dot variants, the Tailwind color palette, and 2 sizes |
| Banner | banner · base/banner | Status message in 5 statuses and 2 contrasts with a status icon, up to 3 actions, a dismiss that collapses its height, and a fixed full-bleed variant |
| Button | button · base/button | Variants, sizes, loading state, icon slots, and a weight shift on hover |
| Calendar | calendar · base/calendar | Month grid for a day or a range with one fluid hover across 2 months, a range band that follows the pointer, booked days, and ISO week numbers |
| Card | card | shadcn's compositional card with stacked, inline, and grid layouts, borderless dividers, media/logo/feature slots, and 2-D fluid hover |
| CarouselDots |
Systems
The systems every component shares. Each installs as code, the same way.
| System | Registry name | What it does |
|---|
| Fluid Hover | use-fluid-hover | One hook and one highlight per list. The highlight glides from item to item under your cursor instead of blinking between them |
| Motion | springs | 3 spring speeds, fast, moderate, and slow, each with an exit one tier quicker than its entrance |
| Reveal | reveal | 1 class reveals a whole page, on load and on scroll |
| Scrollbars | scroll-area · base/scroll-area | A scrollbar that stays out of the way but never disappears, with native scroll on touch |
| Sizes | size-context | 2 sizes, a 36px default and a 28px compact, shared by buttons, inputs, selects, tabs, and rows |
| Surfaces | elevated | 8 elevation levels so popovers, dropdowns, and dialogs stay visible at any depth, in light and dark |
| Typography | type-scale · typography | 6 type roles, each a size and a leading at both sizes, plus a prose sheet for rendered markdown with a builder to tune it |
Blocks
Compositions that install as one item each, with every component they use.
| Block | Registry name | What it is |
|---|
| App Sidebar | sidebar-app · base/sidebar-app | A complete app shell: workspace header, search field, collapsible sections with badges, user footer, and an inset topbar |
| Settings Dialog | dialog-sidebar · base/dialog-sidebar | The xl Dialog as a canvas, a Sidebar of sections down its left edge, and a scrolling panel of controls |
| Queued message stack | queued-stack · base/queued-stack | Sonner-style stack of queued composer messages: fan out on hover, drag to reorder, morph into the sent message |
Presets
The Sidebar, Card, InputMessage, AskUserQuestions, Dropdown, Combobox, and CommandMenu playgrounds encode the configuration you build in the rail into a short code. Nothing is stored: the code is the configuration itself. Install it as one block that composes the component with the options you picked:
npx shadcn@latest add https://www.fluidfunctionalism.com/r/preset/<code>.json
Add ?preset=<code> to the doc page URL to reopen the playground as you left it, or to share it.
Icons
Components render icons through named slots with Lucide defaults, so lucide-react is the only icon dependency an install adds. To use another icon library, wrap your app in the installed IconProvider and override any slot. Names you leave out keep their Lucide default:
import { IconProvider } from "@/lib/icon-context";
import { CaretRight, MagnifyingGlass } from "@phosphor-icons/react";
<IconProvider icons={{ "chevron-right": CaretRight, "search": MagnifyingGlass }}>
<App />
</IconProvider>
Or install a whole set (@fluid/icons-tabler, @fluid/icons-phosphor, @fluid/icons-hugeicons, @fluid/icons-untitledui) and pass its map to IconProvider.
What makes these different
- Motion as information. Transitions make state changes legible. Nothing moves for decoration.
- Hover as preview. One highlight per list glides from item to item under your cursor, so you see where a click lands before you click.
- Springs, not durations. 3 spring speeds cover the library. Interrupt an animation and it reverses from where it is instead of finishing first.
- Weight without reflow. Selected and hovered labels get heavier. An optical-size axis compensates the width and a ghost span reserves it, so nothing shifts.
- Two flavors, one API. Radix or Base UI, whichever your project already uses.
- Drop-in compatible. Your shadcn theme tokens (colors, radii, fonts) apply as they are.
Tech stack
Development
npm install
npm run dev # docs site on http://localhost:3000
npm test # vitest
npm run lint
npm run registry:build # shadcn build + scripts/postbuild-registry.mjs, writes public/r
node scripts/build-skill-craft.mjs # writes the skill's craft reference
Sources live in registry/: radix/ and base/ hold the two flavors, default/ the single-source components, hooks, and libs, blocks/ the compositions. public/r is the built output users install from, and it is committed. CI rebuilds it and fails when it drifts from the sources, so run npm run registry:build and commit the result with any registry change. The skill's craft reference works the same way: it is generated from the prompt entries in lib/docs/prompt-entries.ts, and a test fails when the committed copy has drifted.
Guides in the repo: motion-guidelines.md, component-documentation-guidelines.md, preset-guidelines.md, tone-of-voice.md, and README-guidelines.md for what this file carries and what it defers.
Contributing
Open an issue before a pull request, so the direction is agreed before the work starts. CONTRIBUTING.md has the setup, the rules every change follows, and the checks to run.
License
MIT © Micka Touillaud
