@flopay/ui

The shared FloPay design system — the single source of truth for design tokens, a Tailwind v4 theme preset, and a small set of React primitives. Consumed by landing, demo, docs, and dashboard.

It is framework-agnostic at the token layer: the same CSS custom properties drive both the plain-CSS apps (landing, demo) and the Tailwind v4 apps (docs, dashboard). Change a token once here and every app inherits it.

Install

pnpm add @flopay/ui

react and react-dom (^19) are peer dependencies (only needed if you import the React components).

Usage

1. Plain-CSS apps (landing, demo)

Import everything (reset + tokens + shared component classes) at the top of your global stylesheet:

/* app/globals.css */
@import "@flopay/ui/styles";

/* ...your page-specific CSS, using var(--brand), var(--text), etc. */

Or cherry-pick:

@import "@flopay/ui/styles/tokens.css";      /* :root design tokens only */
@import "@flopay/ui/styles/reset.css";
@import "@flopay/ui/styles/components.css";   /* .btn-primary, .nav, .footer, .card ... */

2. Tailwind v4 apps (docs, dashboard)

Add the preset after Tailwind. It registers the tokens as theme values, so utilities like bg-brand, text-text-secondary, border-border, and font-sans resolve to the shared tokens:

/* app/globals.css */
@import "tailwindcss";
@import "@flopay/ui/styles/preset.css";

<button className="bg-brand text-bg-card rounded-lg px-6 py-3">Get started</button>

The preset uses @theme inline, so the .dark overrides in tokens.css apply at runtime without recompiling.

3. React primitives

import { Button, Container, Section, SectionHeader, Badge, Card, cn } from "@flopay/ui";

<Container>
  <Badge dot>Live</Badge>
  <SectionHeader label="Pricing" title="Simple, usage-based" description="No surprises." />
  <Card className={cn("p-10")}>…</Card>
  <Button variant="primary">Start building</Button>
</Container>;

The primitives render the shared component classes, so they work in plain-CSS apps (which import components.css) and in Tailwind apps (where you can extend them via className + cn()).

Design tokens

styles/tokens.css defines surfaces, borders, text, accent, brand (--brand: #1785e0), status colors, radius, layout (--max-w, --nav-h), and typography. A .dark block provides a dark-theme starting point.

Develop

pnpm install
pnpm dev         # tsup --watch
pnpm build       # emits dist/ (esm + cjs + d.ts); CSS in styles/ ships as-is
pnpm typecheck
pnpm biome:fix

Release

Publishing uses npm trusted publishing (GitHub OIDC) — the same mechanism as the @flopay/* SDK packages, so no NPM_TOKEN is required. One-time setup: register this repo + the publish.yml workflow as a trusted publisher for @flopay/ui on npmjs.org (npm package → Settings → Trusted publishers).

After that, releases are automatic:

1. Bump version in package.json on main.
2. CI runs (.github/workflows/ci.yml).
3. On CI success, Publish Package (.github/workflows/publish.yml) sees the new version has no v<version> tag, npm publishes via OIDC, then pushes the tag. (No npm provenance: this repo is private, and provenance attestation requires a public source repo.)

CSS files ship raw (no build step); only the JS/types are bundled by tsup.