@tomo-inc/tomo-ui

Tomo UI is a React-based design system built on top of HeroUI and Tailwind CSS v4.
It provides:

• A component layer (Button, Card, Modal, etc.) with Tomo defaults
• A provider layer (TomoUIProvider) and a theme hook (useTheme)
• A Tailwind v4 plugin that wires HeroUI and Tomo design tokens together

It is designed so that applications only depend on @tomo-inc/tomo-ui, without touching the underlying UI framework directly.

1. Installation

This package is currently intended for use inside the Tomo monorepo and selected internal projects.

Install from your workspace (example uses pnpm):

pnpm add @tomo-inc/tomo-ui

Peer dependencies (usually already present in the host app):

• react >=18
• react-dom >=18
• tailwindcss ^4 (for apps that want to use the Tailwind plugin)

2. Usage

2.1 Basic React usage

Wrap your app with TomoUIProvider and import components from the root package:

import {
  TomoUIProvider,
  Button,
  Card,
  CardBody,
  CardFooter,
  CardHeader,
} from "@tomo-inc/tomo-ui";

export function App() {
  return (
    <TomoUIProvider>
      <div className="app-root">
        <Card>
          <CardHeader>
            <h1>Tomo UI Starter</h1>
          </CardHeader>
          <CardBody>
            <p>Now you can start building with @tomo-inc/tomo-ui components.</p>
          </CardBody>
          <CardFooter>
            <Button color="primary">Get Started</Button>
          </CardFooter>
        </Card>
      </div>
    </TomoUIProvider>
  );
}

2.2 Tailwind CSS v4 integration

Tomo UI ships a Tailwind v4 plugin that wraps HeroUI and Tomo design tokens.
In your main CSS entry (for example src/index.css):

@import "tailwindcss";

@plugin "@tomo-inc/tomo-ui/tailwind/plugin";

@source "./**/*.{js,ts,jsx,tsx,mdx}";
@source "../node_modules/@tomo-inc/tomo-ui/dist/**/*.{js,mjs}";

Notes:

• @plugin references the Tomo UI plugin only; your app does not need to reference HeroUI directly.
• @source must include:
  • Your application source (so Tailwind can see your class usage)
  • Tomo UI’s dist (so Tailwind can generate classes used by Tomo components)

Tailwind v4 is configured via PostCSS only. A minimal postcss.config.(js|mjs|cjs) looks like:

export default {
  plugins: {
    "@tailwindcss/postcss": {},
  },
};

2.3 Dynamic theme configuration

Tomo UI allows you to provide a theme configuration at runtime.
The type is aligned with HeroUI’s theme configuration surface.

import {
  TomoUIProvider,
  useTheme,
  type ThemeConfig,
} from "@tomo-inc/tomo-ui";

const themeConfig: ThemeConfig = {
  themes: {
    light: {
      colors: {
        primary: "#FCD436",
      },
    },
    dark: {
      colors: {
        primary: "#FCD436",
      },
    },
  },
  defaultTheme: "light",
};

export function Root() {
  return (
    <TomoUIProvider themeConfig={themeConfig}>
      <ThemedApp />
    </TomoUIProvider>
  );
}

function ThemedApp() {
  const { theme, setTheme } = useTheme();

  return (
    <div>
      <p>Current theme: {theme}</p>
      <button onClick={() => setTheme("light")}>Light</button>
      <button onClick={() => setTheme("dark")}>Dark</button>
    </div>
  );
}

Under the hood, the provider:

• Runs the Tomo UI Tailwind plugin at build time to generate base tokens
• Uses themeConfigToCSS at runtime to convert your ThemeConfig into CSS variables
• Scopes the variables to the provider’s DOM subtree, enabling per-subtree theming

3. Architecture Overview

High-level architecture of @tomo-inc/tomo-ui:

• React components

  • Most components are thin wrappers around HeroUI components.
  • Props and types are re-exported from the root package so consumers only import from @tomo-inc/tomo-ui.
  • Domain-specific primitives (e.g. formatted numbers, QR code, MFA/passcode inputs) live under src/components.

• Provider and theming

  • TomoUIProvider wraps HeroUIProvider and a custom ThemeContextProvider.
  • ThemeConfig (a typed wrapper around HeroUI’s theme config) is converted to CSS variables via themeConfigToCSS.
  • Theme variables are scoped to a unique DOM node, allowing:
    • Multiple independent theme instances on the same page
    • Runtime theme switching (light/dark or brand-based)

• Tailwind v4 integration

  • src/tailwind/plugin.ts defines baseConfig and exports heroui(baseConfig) as the Tailwind plugin.
  • The compiled plugin is exposed as @tomo-inc/tomo-ui/tailwind/plugin.
  • During build, HeroUI’s theme dist is copied into dist/theme so that Tailwind can scan it through Tomo UI’s own package paths.
  • Applications only interact with:
    • @plugin "@tomo-inc/tomo-ui/tailwind/plugin";
    • @source "../node_modules/@tomo-inc/tomo-ui/dist/**/*.{js,mjs}";

• Dynamic theme vs. build-time theme

  • Build-time: Tailwind + HeroUI produce the base class names and token structure.
  • Runtime: ThemeConfig controls the concrete colors and layout tokens via CSS variables.
  • This separation allows you to change branding and theme behavior without changing the Tailwind build configuration.

4. License, Copyright, and Usage

Important: This package is primarily intended for internal use within Tomo, Inc. and for selected partners.
It is not a general-purpose public UI library unless explicitly documented and licensed as such.

• Ownership

  • @tomo-inc/tomo-ui is owned and maintained by Tomo, Inc..
  • All source code, compiled artifacts, and design assets are copyrighted.

• Usage scope

  • Intended for:
    • Applications and packages inside the Tomo monorepo
    • Official Tomo products and demos
    • Partner integrations explicitly authorized by Tomo, Inc.
  • Not intended for:
    • Unlicensed redistribution
    • White-label resale as a standalone UI library

• License

  • Unless otherwise stated in the repository root (e.g. in a LICENSE file), usage is governed by Tomo’s internal agreements and partner contracts.
  • If you are unsure whether you are allowed to use this package, please contact the Tomo team or your technical point of contact.

If you are extending @tomo-inc/tomo-ui or integrating it into a new application, please:

• Prefer importing from the root package (@tomo-inc/tomo-ui) instead of deep imports.
• Avoid depending on HeroUI directly; treat it as an internal implementation detail.
• Keep Tailwind integration minimal and aligned with the usage examples above, so that future UI framework changes can remain transparent to applications.