@fairmint/ui

Fairmint's shared design system and UI component library.

Documentation

• @fairmint/ui shared components

Design quality

Read docs/design-quality.md before creating or reviewing product UI. It records the approved onboarding v5 quality bar, the shared spacing and hierarchy rules, reusable component expectations, and the visual-review gate for founder, investor, onboarding, SAFE, grant, and cap-table work.

Quick Start

1. Install

bun add @fairmint/ui

Mantine is included as a dependency — no extra packages to install.

2. Import styles (required)

// In your app's entry file (main.tsx, App.tsx, etc.)
import '@fairmint/ui/styles.css';

This is required. This single import includes Mantine core CSS, notification styles, and Fairmint component animations. Without it, components render unstyled. You do NOT need to install or import @mantine/core/styles.css separately — it's all included.

3. Wrap with provider

import { FairmintProvider } from '@fairmint/ui';

function App() {
  return (
    <FairmintProvider>
      {/* Your app */}
    </FairmintProvider>
  );
}

4. Use components

import { PageHeader, FairmintLogo, LoadingSpinner } from '@fairmint/ui';

Local Development (live editing)

When working on the UI library alongside a consumer app, add the Vite plugin for instant HMR without building:

// your-app/vite.config.ts
import { fairmintUiLocal } from '@fairmint/ui/vite';

export default defineConfig({
  plugins: [fairmintUiLocal(), react()],
});

By default this does nothing — it uses the npm-published package. To enable local source resolution:

LOCAL_UI=1 bun run dev

The plugin checks for ../ui/src/index.ts relative to your app. If found, imports resolve to local source with instant HMR. If not found, it warns and falls back to npm.

Fonts

Add to your index.html:

<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:wght@400;500;600;700&family=Plus+Jakarta+Sans:wght@600;700&display=swap" rel="stylesheet" />

Exports

Development

cd design/ui
bun run dev          # Storybook on port 6006
bun run build        # Build library
bun run test         # Run tests
bun run lint         # Lint (Biome)

Publishing

Automatic on push to main when ui/ files change. Patch version auto-increments if the current version is already published.