@flopay/ui

The shared FloPay design system — the canonical manifest for design-token values shared by CSS and transactional email, 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()).

Checklist and step indicator

A tick list for setup checklists and a step indicator for wizards. They need no provider or dashboard code, and use no hooks apart from ChecklistSkeleton's useId, so they render from Server Components too.

import Link from "next/link";
import { Checklist, ChecklistRow, ChecklistSkeleton, StepIndicator } from "@flopay/ui";

{loading ? (
  <ChecklistSkeleton rows={3} />   // role="status", announced as "Loading"
) : (
  <Checklist>
    <ChecklistRow label="Verify your domain" done status="Connected" />
    <ChecklistRow label="Brand your emails" href="/setup/emails" linkAs={Link} />
    <ChecklistRow label="Invite your team" optional />
  </Checklist>
)}

<StepIndicator
  steps={[
    { label: "Account", status: "done" },
    { label: "Domain", status: "current" },
    { label: "Emails", status: "upcoming" },
  ]}
/>;

A ChecklistRow shows a filled tick on the success token when done and an empty one otherwise, optional status text on the right and, with optional, a neutral "Optional" Badge. With href the whole row is one link: a plain <a>, or the component you pass as linkAs (it receives href, className and the row content), so the package never imports a router.

StepIndicator is an ordered list. Each step passes its own status (done, current or upcoming), so steps can be completed out of order, and the current step carries aria-current="step". Rows and steps say their state in visually hidden text, so it is never conveyed by colour alone: "Done" / "Not done" for a row, "Done" / "Current" / "Upcoming" for a step. Pass statusLabels to either to change that wording.

ConfirmDialog

A confirm/cancel alert dialog for a consent or destructive step. The caller owns open and supplies all the wording; the dialog only reports which way the user chose.

"use client";

import { useState } from "react";
import { Button, ConfirmDialog } from "@flopay/ui";

const [open, setOpen] = useState(false);
const [saving, setSaving] = useState(false);

<Button onClick={() => setOpen(true)}>Turn on reminders</Button>

<ConfirmDialog
  open={open}
  title="Send abandoned-cart emails?"
  description={<p>Customers who leave a cart get a reminder. <a href="/terms">Terms</a></p>}
  confirmLabel="Yes, send them"
  cancelLabel="Not now"
  confirming={saving}
  onConfirm={async () => {
    setSaving(true);
    try {
      await enableReminders();
      setOpen(false);
    } finally {
      setSaving(false);
    }
  }}
  onCancel={() => setOpen(false)}
/>;

Clear confirming when the request fails too (the finally above): while it is set the dialog can't be confirmed, cancelled or dismissed, so a rejection that leaves it true traps the user in the dialog.

While open it renders role="alertdialog" with aria-modal="true", labelled by title and described by description (text or a node); while closed it renders nothing. Confirm calls onConfirm; Cancel, Escape and a click on the backdrop call onCancel, and a click inside the panel does not, nor does a drag that starts inside the panel and ends on the backdrop. Focus moves to Cancel on open, Tab and Shift+Tab stay inside the dialog, and on close focus goes back to the element that opened it. While confirming, both buttons are disabled and Escape and the backdrop are ignored, so an in-flight request can't be dismissed. It renders in place (no portal), so it server-renders as-is.

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. The Product column links to Card Vault, Chargeback Prevention and Subscription Recovery in that order, followed by the remaining product placeholders.

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.cjs rather than hand-authored — edit the control points there and run pnpm gen:arrow-paths; use pnpm gen:arrow-paths:check to verify the committed module without changing it. Don't edit 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 inlines the shared colors and radius from design-tokens.json; the build bundles those values into the email entry point, so consumers do not need a runtime JSON file. Email-only choices — the accessible link color, 600px width, and Inter-first font stacks with Roboto/Arial fallbacks — remain local to src/email/theme.ts. The layout is a 600px table-based card with 40px desktop padding and 24px narrow-screen padding.

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.

7. Email editor controls

The controls behind the dashboard's Emails screens: a switch for each email, and the blocks of the email edit screen. They are root exports like Input, render the shared classes in components.css (so they work in plain-CSS and Tailwind apps), add no runtime dependency, and need no provider or dashboard code: data wiring stays in the app.

Switch, SlotTextField, VariablePicker and BlockList use React state, refs and effects, so in a Next.js App Router app render them from a Client Component (a file that starts with "use client"). Importing other primitives such as Button from @flopay/ui in a Server Component is unaffected.

Switch

An accessible on/off switch: a native <button role="switch">, so Tab, Space and Enter work and screen readers announce its name and aria-checked state.

import { Switch } from "@flopay/ui";

<Switch
  label="Payment receipt"
  labelHidden                    // keeps the accessible name, hides the text (table rows)
  checked={enabled}
  loading={saving}               // busy, still focusable, keeps its state, ignores toggles
  onCheckedChange={(next) => save(next)}
/>;

Use checked + onCheckedChange (controlled) or defaultChecked (uncontrolled). disabled makes it a disabled button. While loading, it shows the Spinner and stays put; flip checked once the save resolves. Pass name to submit name=on in a form when it is on; like a disabled checkbox, a disabled switch submits nothing.

SlotTextField

A labelled field for one email slot, with a Bold / Italic / Link toolbar that writes only Markdown-lite: **bold**, _italic_, [label](https://…) and blank-line paragraphs. No headings, lists, images or raw HTML; use custom HTML mode for anything richer.

import { SlotTextField } from "@flopay/ui";

<SlotTextField
  label="Intro"
  multiline                      // textarea; single-line input by default
  value={intro}
  onChange={(event) => setIntro(event.target.value)}
  error={introError}             // replaces the hint, as in Field
/>;

Typed text reaches onChange unchanged, and toolbar edits fire onChange too. Bold and Italic wrap the selection (or insert the markers with the cursor between them); Link wraps it as [selection](https://) and selects the URL placeholder. The default hint names the syntax; pass hint to replace it.

CodeArea

A labelled monospace textarea for custom HTML / Liquid. It has no editor dependency: spellcheck, autocapitalize, autocomplete and soft wrapping are off, and Tab moves focus on rather than being trapped.

import { CodeArea } from "@flopay/ui";

<CodeArea
  label="Custom HTML"
  value={source}
  onChange={(event) => setSource(event.target.value)}
/>;

Select

A labelled native <select> (for example the email editor's language switcher), laid out like Field: a field-label linked through htmlFor, then the select with the Input look (field field-select). It stays a native control, so Tab, the arrow keys and the platform picker work, and it keeps the browser's chevron.

import { Select } from "@flopay/ui";

<Select
  id="locale"
  label="Language"
  value={locale}                 // "" selects the Default option
  options={[
    { value: "", label: "Default" },
    { value: "fr", label: "French" },
    { value: "de", label: "German" },
  ]}
  onChange={(next) => setLocale(next)}   // the chosen value, not the event
/>;

It is controlled only: value picks the selected option and onChange receives the chosen option's value as a string. disabled and name pass through to the <select>; without them it has neither attribute.

VariablePicker

An "Insert variable" menu button attached to a SlotTextField or CodeArea through its ref. Choosing a variable, by click or with the arrow keys and Enter, replaces the field's selection with the Liquid tag {{ name }} (or appends it if the field never had focus), fires the field's onChange, and returns focus to the field with the cursor after the tag. Escape closes the list and returns focus to the button; with no variables the button is disabled.

import { useRef } from "react";
import { CodeArea, VariablePicker } from "@flopay/ui";

const bodyRef = useRef<HTMLTextAreaElement>(null);

<CodeArea ref={bodyRef} label="Body" value={body} onChange={(event) => setBody(event.target.value)} />;
<VariablePicker
  targetRef={bodyRef}
  variables={[
    { name: "customer.first_name", label: "Customer first name" },
    { name: "order.total", label: "Order total" },
  ]}
/>;

The variable list is a prop; the picker fetches no schema.

PreviewFrame

A container that previews rendered email HTML in an isolated iframe: the HTML goes in srcdoc, and sandbox="" blocks scripts, forms, popups and same-origin access, so client-authored HTML can never reach the dashboard session.

import { PreviewFrame } from "@flopay/ui";

<PreviewFrame title="Email preview" html={renderedHtml} className="h-[720px]" />;

The frame fills the container (at least 480px tall); size it with className.

BlockList

A reorderable list for the email block builder: a ul with one row per item, rendered through renderItem. Each unlocked row has a drag handle (native HTML5 drag and drop, no extra dependency) and native "Move up", "Move down" and "Delete" buttons, so Tab, Enter and Space work. The handle is not focusable and is hidden from screen readers; keyboard users reorder with the buttons. Focus stays with the row: after a move, the moved row's button keeps it (its other Move button if that one is now disabled), and after a delete the next unlocked row's Delete takes it, so a block can be moved or deleted several times in a row.

import { BlockList } from "@flopay/ui";

const [blocks, setBlocks] = useState([
  { id: "header", label: "Header", locked: true },  // never moves, no controls
  { id: "intro", label: "Intro" },
  { id: "button", label: "Button" },
  { id: "footer", label: "Footer", locked: true },
]);

<BlockList
  items={blocks}
  renderItem={(block) => <span>{block.label}</span>}
  onChange={setBlocks}             // new order, or the list without a deleted item
/>;

The list is controlled: each click, key press or drop calls onChange once with a new array of your own item objects, and the rows move when you pass the new items. Ids must be unique. Locked items never move, and nothing moves past one: the first item can't move up, the last can't move down, and an item next to a locked header or footer can't move past it. Those buttons are disabled, and such drops are ignored. Dropping a row on another moves it to that row's place. It renders to static markup on the server with no browser APIs.

Design tokens

design-tokens.json is the source of truth for the fourteen colors and base radius shared by CSS and transactional email. pnpm gen:design-tokens writes the shipped styles/tokens.css deterministically; do not edit that generated file directly. CSS-only values stay in the generator template instead of expanding the shared manifest beyond its consumers. The 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 (tsup), then d.ts + d.cts (tsc, bundled); CSS ships as-is
pnpm gen:design-tokens        # regenerate styles/tokens.css from design-tokens.json
pnpm gen:design-tokens:check  # fail without writing if generated CSS is stale
pnpm typecheck
pnpm knip        # unused files / exports / dependencies, non-writing
pnpm knip:fix    # strips unused exports and exported types (never deletes files or edits package.json)
pnpm lint        # biome check, non-writing
pnpm lint:fix    # biome check --write
pnpm verify      # the gate: knip + lint + typecheck, non-writing; CI and the pre-commit hook run it
pnpm go          # fix-then-check: knip:fix + lint:fix, then typecheck + test + build; run before pushing

Release

Releases are cut and published on Gitea (git.flopay.com/flopay/ui). There is no GitHub push mirror, so .github/workflows/publish.yml never runs:

1. A shipping pull request carries a release intent, .release/pending/pr-<number>.md (.release/README.md); the Gitea check workflow verifies it against the pull request's labels.
2. On merge, Gitea's release workflow (.gitea/workflows/release.yml) runs the check, bumps the version once, commits chore(release): vX.Y.Z, tags vX.Y.Z and pushes both.
3. The same run's publish job publishes to npm every vX.Y.Z tag newer than the highest version npm serves, oldest first, so the newest ends as latest. Each one is built from its own tag on the Node its mise.toml pins. The job authenticates with the org secret NPM_TOKEN (an npm automation token), skips versions npm already has, and waits until npm serves each one. (No npm provenance: that needs GitHub's or GitLab's OIDC, and this repo is private.)

Gitea's secrets and variables are listed in .gitea/README.md.

CSS files ship raw (no build step); only the JS is bundled by tsup. TypeScript 7 ships no compiler API for tsup's own declaration step, so the TypeScript 7 compiler emits the declarations (tsc -p tsconfig.build.json, into dist/.types) and scripts/build-dts.mjs bundles each entry point's into dist/<entry>.d.ts and .d.cts with rolldown-plugin-dts.