Fluid Functionalism

Fluid Functionalism

Use this skill to bring Fluid Functionalism into a React/Next.js project as selective shadcn registry components, not as a vendored library.

Sources:

• Docs: https://www.fluidfunctionalism.com/docs
• Registry: https://www.fluidfunctionalism.com/r/registry.json
• GitHub: https://github.com/mickadesign/fluid-functionalism

Fit

Use Fluid Functionalism when the project already uses, or can reasonably adopt:

• React or Next.js
• Tailwind CSS
• shadcn/ui registry workflow
• Framer Motion for interactive motion
• Radix UI or Base UI, matching the project's primitive engine

Do not install it wholesale. Pull only the components needed for the current interface, then adapt the generated files to the project's local tokens, component names, and import aliases.

Design Principle

Fluid Functionalism is strongest for operational UI and AI/product surfaces where motion clarifies state:

• Motion communicates state changes.
• Hover acts as preview, especially through proximity hover.
• Spring animation should adapt when a user reverses direction.
• Components should inherit the existing shadcn theme instead of imposing a new visual brand.

For one-off hover fixes, use css-interaction-tips. For custom React animation work, use framer-motion. For final visual QA, use preflight.

Install Workflow

1. Confirm the project has shadcn configured (components.json) and Tailwind available.
2. Check whether the target file already exists, especially components/ui/button.tsx, components/ui/dialog.tsx, and similar shared primitives.
3. If existing shared primitives would be overwritten, install in a throwaway branch/project or fetch the registry JSON and port the useful pattern manually.
4. Add the registry when repeated use is likely:

npx shadcn@latest registry add @fluid

5. Install selected components:

npx shadcn@latest add @fluid/button

6. For one-off installs, use the direct registry URL:

npx shadcn@latest add https://www.fluidfunctionalism.com/r/button.json

7. Preserve the project's existing primitive engine. For fresh projects, read Studio's current behavior-engine default and choose the matching variant. Base UI variants use -base names, such as button-base, dialog-base, tabs-base, and tooltip-base.
8. If keeping font-weight animation, ensure the app loads Inter variable or adjust the generated font-weight helper to the project's variable font.
9. Run the app, check light and dark themes, and browser-test the exact interaction. Pay attention to hover previews, keyboard focus, reduced-motion behavior, and overwritten local components.

Component Selection

Read references/component-inventory.md when choosing components. For the freshest list, query the live registry:

curl -LfsS https://www.fluidfunctionalism.com/r/registry.json \
  | jq -r '.items[] | select(.type == "registry:ui") | [.name, .title, .description] | @tsv'

Fast choices:

• Core controls: button, tabs, tabs-subtle, switch, slider, select, dropdown, tooltip.
• Forms: input-group, input-copy, checkbox-group, radio-group, color-picker.
• AI/chat UI: input-message, chat-message, thinking-indicator, thinking-steps, ask-user-questions.
• Data and layout: table, accordion, dialog, surfaces, elevated.

Adaptation Rules

• Preserve local design-system ownership. Do not replace established primitives unless the user asked for a Fluid Functionalism skin.
• Keep generated code inspectable and project-owned, like normal shadcn components.
• Normalize imports after install. The registry commonly uses @/lib/* and @/components/ui/*.
• If a component brings icon switching, decide whether the project really needs Tabler, Phosphor, and HugeIcons. Prefer the existing icon set when possible.
• Treat surfaces and elevated as a system-level choice. Install them when nested popovers, dialogs, or dropdowns need a consistent elevation ladder.
• Keep MIT attribution when copying substantial source out of the upstream repo instead of installing through the registry.

Validation

After integration:

• Run the repo's lint/build/test commands.
• Use a browser check for the changed screen.
• Verify keyboard focus, disabled states, loading states, and dark mode.
• Inspect generated CSS variables and dependencies for unintended palette or package sprawl.