@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()).

4. Marketing chrome (nav + footer)

import logo from "@flopay/ui/logo.png";
import { FlopayFooter, Nav } from "@flopay/ui/marketing";

<Nav
  logo={{ src: logo, label: "FloPay" }}
  links={[
    { href: "/pricing", label: "Pricing" },
    { href: "/contact", label: "Contact", cta: true },
  ]}
/>;

<FlopayFooter logo={logo} />;                               // on flopay.com itself
<FlopayFooter logo={logo} baseUrl="https://flopay.com" />;  // any other portal

Nav links stay per-app (the demo points at its own routes), but the chrome is shared: mark cta: true on the call to action and every other item gets a nav-link-item class, which components.css hides below 768px — so narrow viewports collapse to logo + CTA everywhere. Apps that ship their own component CSS instead of importing components.css re-declare that one rule to opt in.

FlopayFooter is the whole footer, content included — the sitemap, tagline and copyright live in flopay-footer.tsx, so adding a footer link is one change here plus a version bump, and every portal picks it up. Portals hosted off flopay.com pass baseUrl to make the marketing routes absolute; demoUrl and contactUrl cover the two entries a portal usually wants to re-point at itself.

Need a different sitemap (a partner or internal portal)? Use the lower-level Footer with your own columns/legal, or start from flopayFooterContent() and edit the result. MarketingLink picks next/link vs. a new-tab anchor per href, so column lists can mix internal routes, absolute URLs and mailto:.

5. Annotation layer

Hand-drawn marker notes and arrows drawn over a UI, for guided demos and product tours. Opt-in, because the arrow geometry is a few KB most pages don't need:

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

import { type Annotation, AnnotationStage } from "@flopay/ui/annotations";

const notes: readonly Annotation[] = [
  {
    id: "email",
    text: "Pop your email in — we'll send your receipt here",
    arrow: "squiggle-right",
    pos: { top: "60%", left: "-56px" },   // the note, within the stage
    posArrow: { left: "18px" },            // nudge the arrow alone
    tilt: -5,                              // note + arrow, hand-placed feel
  },
];

<AnnotationStage annotations={notes}>
  <YourCheckoutForm />
</AnnotationStage>;

AnnotationStage renders both treatments and picks one: floating notes when there's room in the margins, and a plain readable list below the content when there isn't. The floating layer is aria-hidden, so the list is what assistive tech announces — annotations are never lost to a screen reader.

22 arrow variants — six calm directional ones (down-right, up-left, right, …) plus an expressive set (loop-right, squiggle-left, s-curve-down, zigzag-right, hook-left, curl-down, …). Each is a filled outline with a tapered width profile and a solid head, generated by scripts/gen-arrow-paths.py rather than hand-authored — edit the control points there and re-run, don't touch arrow-paths.ts.

One curve covers many directions: rotate re-aims it, flipH / flipV mirror it, and arrowScale lengthens its reach — all on the arrow only, leaving the note's text upright. Those are visual transforms, so a re-aimed arrow overhangs its layout box and its pos usually wants re-checking.

Colour and face come from --annotation-ink (brand blue) and --annotation-font (a handwriting stack); override either per app. The floating/list switch is a @media (min-width: 1120px) rule sized for a ~720px content box — apps in a constrained layout should re-declare that one block.

6. Transactional email

@flopay/ui/email renders a provider-neutral HTML string and matching plain text. It does not send messages or configure a delivery provider.

import { renderTransactionalEmail } from "@flopay/ui/email";

const { html, text } = renderTransactionalEmail({
  preheader: "Your FloPay payment receipt is ready",
  heading: "Payment received",
  body: [
    "Thanks, Alex. Your payment was processed successfully.",
    "Keep this receipt for your records.",
  ],
  action: {
    label: "View receipt",
    href: "https://flopay.com/receipts/FP-2048",
  },
  detail: {
    kind: "keyValue",
    rows: [
      { label: "Reference", value: "FP-2048" },
      { label: "Amount", value: "$48.00 USD" },
    ],
  },
  footer: {
    address: "FloPay LLC, 100 Payments Way, New York, NY",
  },
});

The fixed slots are the content contract: one concise preheader, one heading, plain-text body paragraphs, an optional action, and either a code or key-value detail. Consumers supply content rather than React children or arbitrary HTML, so new account and payment messages reuse the same reading order and layout. All links are real anchors, and the action URL and labelled details remain usable in the generated plain text.

Email clients cannot use the live CSS token preset. The template therefore mirrors the approved values as inline literals: brand #1785e0, text #0a0a0b, border #e5e5e8, an 8px radius, and an Inter-first system font stack with Roboto/Arial fallbacks. The layout is a 600px table-based card with 40px desktop padding and 24px narrow-screen padding. Update src/email/theme.ts whenever the corresponding values in styles/tokens.css change.

The default FLOPAY_EMAIL_LOGO_URL is the hosted approved asset at https://flopay.com/logo.png. The logo is decorative (alt="") because the adjacent text brand name provides the accessible name and remains visible for images-off clients. A service may pass an absolute HTTPS logoUrl when it needs to host the same asset itself; packaged files, data: URLs, and provider-specific CID references are not portable email sources.

The shared transactional footer defaults to FloPay LLC, [email protected], Privacy, Terms, and a service-message notice. It does not include a marketing unsubscribe. footer can override the company, support label/URL, legal URLs, notice, and optional mailing address when legal or support requirements differ.

The initial compatibility baseline is Apple Mail on macOS/iOS; Gmail web, iOS, and Android; Outlook Windows desktop/MSO, Outlook.com, and Microsoft 365 web; and Yahoo. The markup uses layout tables and inline styles, with responsive and dark-mode CSS as progressive enhancements. Before a release changes the layout, verify Outlook Windows, dark mode, and images-off behavior in real clients or an email rendering service in addition to the automated render snapshot.

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.