@hearthforge/ui

The HearthForge design system: the atoms (buttons, dialogs, sheets, menus, inputs, tabs, …) built on Base UI and Tailwind CSS v4, the descriptor-driven DataGrid every table in the panel is, and the one chart renderer. The panel renders with it, and so does every game plugin's UI, so a plugin page looks and behaves like the rest of the panel instead of carrying a look-alike of its own. Components take already-resolved copy and never hard-code a string; the few that need their own labels read them from the ui i18n namespace this package ships.

Install

pnpm add @hearthforge/ui

Node >= 22. The components are React and are styled with Tailwind CSS v4 utility classes against the HearthForge design tokens.

Usage

import { Button, EmptyState } from "@hearthforge/ui";

export function NoBackups({ onCreate }: { onCreate: () => void }) {
  return (
    <EmptyState
      title="No backups yet"
      description="Take one now, or schedule one."
      action={{ label: "Create backup", onClick: onCreate }}
    />
  );
}

export function Save({ onSave }: { onSave: () => void }) {
  return (
    <Button variant="default" size="sm" onClick={onSave}>
      Save
    </Button>
  );
}

(Pass copy through your i18n t() in real code — the literals above keep the example short.)

Register the package's own catalog once, under the ui namespace:

import i18next from "i18next";
import uiEn from "@hearthforge/ui/locales/en";

i18next.addResourceBundle("en", "ui", uiEn, true, true);

In a game plugin: the host share scope

A plugin's UI bundle does not bundle this package. The panel hands every plugin its own copy of React, @hearthforge/ui, @hearthforge/forms, react-query, i18next and a few others through a share scope (globalThis.__hfHost.require; the list is HOST_SHARED_MODULES in @hearthforge/plugin-sdk), and the SDK's uiConfig build preset leaves them external. That is why a plugin's components run on the panel's one React and render with the panel's theme — and why a plugin declares @hearthforge/ui as a peer, never a bundled dependency. The panel also compiles the Tailwind classes these components use; a plugin does not ship them. See the plugin-authoring guide.

In your own app

Outside the panel you own the styles: include this package in your Tailwind v4 sources (@source "../node_modules/@hearthforge/ui/dist/**"; — name the package; a wildcard package segment under node_modules scans nothing) and import the design tokens from @hearthforge/plugin-sdk/build/host-theme.css.

Peer dependencies

react and react-dom (^18 || ^19), @hearthforge/shared (^0.1.1), zod (^4), @base-ui/react, lucide-react, sonner, vaul, cmdk, input-otp, react-day-picker, react-hook-form, react-resizable-panels, embla-carousel-react, and @tanstack/react-query, react-table, react-virtual, react-hotkeys and react-pacer. i18next and react-i18next are optional. The exact ranges are in package.json; every one of them is a peer because the host owns that copy.

Versioning

Pre-1.0: a minor release may break a component's API; a patch never does. Maintenance lines publish from release/X.Y branches under the release-X.Y npm dist-tag and never move latest — see Maintenance releases.

License

Apache-2.0.

Links

• Repository: hearthforge/hearthforge-ui
• Form and wizard engine: @hearthforge/forms
• Contributing: CLA.md (required for every contribution)
• HearthForge core: hearthforge/hearthforge