@fanvue/ui

React component library built with Tailwind CSS for the Fanvue ecosystem.

Features

• 🎨 Tailwind CSS v4 - Modern CSS-first theming with design tokens
• ♿ Accessible - WCAG 2.1 AA compliant with Radix UI primitives
• 📦 Tree-shakable - Import only what you use
• 🌙 Dark mode - Built-in light/dark theme support
• 📝 TypeScript - Full type definitions included
• 🧪 Tested - Unit tests with Vitest, E2E with Playwright

Setup

1. Install

npm i @fanvue/ui

2. Peer dependencies

# Required
npm i react react-dom tailwindcss

# Only if using DatePicker
npm i react-day-picker

# Only if using animated icons
npm i motion

3. Configure CSS

Add the following to your CSS entry point (e.g. app.css):

@import "tailwindcss";
@source "../node_modules/@fanvue/ui";
@import "@fanvue/ui/styles/theme.css";

4. Load Inter font

Load the Inter typeface via Google Fonts or @fontsource-variable/inter:

<link rel="preconnect" href="https://fonts.googleapis.com" />
<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
<link href="https://fonts.googleapis.com/css2?family=Inter:[email protected]&display=swap" rel="stylesheet" />

or

npm i @fontsource-variable/inter

Usage

import { Button } from "@fanvue/ui";

function App() {
  return (
    <Button variant="primary" size="40">
      Click me
    </Button>
  );
}

Animated icons

@fanvue/ui/animated-icons ships animated twins of the icons that have one. Each is exported under the same name as the static icon and renders in exactly the same box, so switching is a one-line change and nothing in your layout moves:

import { HeartIcon } from "@fanvue/ui";                // static
import { HeartIcon } from "@fanvue/ui/animated-icons";  // animates on hover

<HeartIcon size={24} />;

They live on their own subpath and depend on the optional motion peer, so @fanvue/ui consumers never pay for Motion unless they import from here.

Not every icon has a twin — an icon is only mapped once its animated artwork has been compared against ours — so a missing export means the pair was rejected or upstream has no equivalent. SpinnerIcon is deliberately absent: a loading indicator must not wait for a hover. Keep using the static one with animate-spin, or Loader.

Nothing animates when the user has asked for reduced motion (prefers-reduced-motion: reduce), including animations you start yourself through controlRef.

By default an icon animates while hovered. To drive it from a parent instead — an icon inside a button, say — pass a controlRef, which also turns the hover trigger off. Drive it from focus as well as hover: the <svg> is not focusable, so a keyboard user reaching the button gets nothing from hover alone.

const icon = useRef<AnimatedIconHandle>(null);

<button
  onMouseEnter={() => icon.current?.startAnimation()}
  onMouseLeave={() => icon.current?.stopAnimation()}
  onFocus={() => icon.current?.startAnimation()}
  onBlur={() => icon.current?.stopAnimation()}
>
  <HeartIcon controlRef={icon} /> Favourite
</button>;

The animated artwork is stroke-only, so these icons take no filled prop — passing one is a type error rather than a silent no-op. Where our static twin is also stroked artwork the animated one is drawn at the same stroke weight; where the static twin is fill-painted there is no stroke to match, so the animated outline can read a little lighter. Browse what is available in Storybook under Foundations → Icons with animated switched on: icons badged anim have a twin, and clicking a card copies the right import. Artwork and animations come from lucide-animated (MIT), built on Lucide (ISC) and in part Feather (MIT) — the full licence texts are in THIRD-PARTY-NOTICES.md, which ships with the package.

Theming

Customize the theme by overriding CSS variables:

:root {
  --color-primary-500: #00aeef;
  --color-neutral-500: #6b7280;
  --color-background-0: #ffffff;
}

Development

Prerequisites

• Node.js 20+
• pnpm 9+

Installation

pnpm install
pnpm dev
pnpm storybook

Scripts

| Command | Description | | ------------------------ | ------------------------------------ | | Development | | | pnpm dev | Start Vite dev server | | pnpm dev:watch | Rebuild dist/ on change (live-reload into apps) | | pnpm build | Build the library for production | | pnpm preview | Preview production build | | Testing | | | pnpm test | Run unit tests | | pnpm test:watch | Run tests in watch mode | | pnpm test:coverage | Run tests with coverage report | | pnpm test:storybook | Run Storybook interaction tests | | pnpm test:e2e | Run Playwright E2E tests | | pnpm typecheck | Run TypeScript type checking | | Linting & Formatting | | | pnpm lint | Check for lint errors (Biome) | | pnpm lint:fix | Auto-fix lint errors | | pnpm format | Format code | | Storybook | | | pnpm storybook | Start Storybook dev server on port 6006 | | pnpm build-storybook | Build Storybook static site | | Icons | | | pnpm icons:sync | Re-import icons from Figma and regenerate components, tests, stories | | pnpm icons:animated | Re-import animated icons from the lucide-animated registry and regenerate | | Tokens & Build | | | pnpm build:dictionary | Generate styles from design tokens | | pnpm build:showcase | Build the showcase site | | pnpm size-limit | Check bundle size | | Publishing | | | pnpm publish:dry-run | Build and dry-run npm publish |

Live-reloading into pandora/eden

To iterate on a component and see it live in eden (local.fanvue.com) without publishing:

• Easiest: from the pandora repo root, run pnpm start:localui. It runs this library's watch build automatically and points eden at this checkout's dist/. See pandora's README ("Live-reloading @fanvue/ui from a local checkout"). Variants: pnpm start:dev:localui and pnpm start:docker:localui pick up the matching env files and handle AWS auth.
• Manual: run pnpm dev:watch here, and start eden with USE_LOCAL_FANVUE_UI=1 (or pnpm --filter @pandora/eden start:localui).

Requires this repo checked out beside pandora (or FANVUE_UI_PATH set in pandora). Component markup, Tailwind classes and design tokens all hot-reload: pandora's eden/postcss.config.mjs redirects the @fanvue/ui/styles/theme.css import to this checkout's src/styles/theme.css, so token edits show up without a published (pre)release.

Figma + Storybook Integration

This library is integrated with Figma through Chromatic Connect. View the complete documentation in Storybook:

pnpm storybook
# Navigate to "Documentation > Figma Integration"

Commit Convention

This project uses Conventional Commits. Commit messages are validated by commitlint.

# Examples
feat(button): add loading state
fix: resolve focus ring issue
docs: update installation guide

For guided commit messages, install Commitizen globally:

npm i -g commitizen

Then use cz instead of git commit.

Contributing

See CONTRIBUTING.md for guidelines.

Security

See SECURITY.md for reporting vulnerabilities.

License

Apache 2.0 © Shift Holdings Ltd