Skip to content
FelicityUI

Installation

Initialize FelicityUI in a React, SwiftUI, or Jetpack Compose project and copy native source for Button, Input, Accordion, Dialog, and Drawer.

React items are TypeScript source. The CLI copies them into your tree. You own the files. There is no FelicityUI runtime to import from npm.

Requirements

  • Node.js 22 or later. CLI 0.1.6 or later (npx felicityui@latest).
  • A React app (Vite or Next.js). The CLI detects src/ and installs next to it.
  • Tailwind CSS v4. If it is missing, init/add install it with clsx and the Vite or PostCSS plugin.

FelicityUI does not scaffold apps. Use an existing Vite or Next.js project, then run init from the app root.

1

Initialize

Create the project config

Writes felicityui.json, installs semantic tokens, and installs lib/cn.ts. Vite and Next.js --src-dir projects land under src/. On React, the CLI also installs clsx, Tailwind v4, the @ alias, and patches your CSS entry.

terminal
npx felicityui init --platform react
2

Add a component

Copy native source

If felicityui.json is missing, add runs init first. Existing files are never overwritten unless you pass --overwrite — the CLI prints a diff and exits.

terminal
npx felicityui add button --platform react
3

Configure

Let the CLI finish the Vite project

After add, FelicityUI installs clsx and Tailwind, points @ at your source root in Vite and tsconfig, and patches the global CSS. Restart the dev server. Pass --skip-install only if you will add those packages yourself.

Import tokens.css from the Tailwind entry

Put @import "tailwindcss" and @import ".../tokens.css" in the same stylesheet (src/index.css or app/globals.css). Importing tokens.css from JavaScript raises an unknown @theme warning because @theme is only valid in the Tailwind pipeline.

If styles or @/lib/cn still fail

Run felicityui doctor. It checks clsx, Tailwind, the Vite @ alias, tsconfig paths, and that tokens.css is not imported from a JS entry.

src/index.css
@import "tailwindcss";
@import "./ui/tokens/tokens.css";
@source "./components/ui";

@theme inline {
  --color-action-primary: var(--felicityui-color-action-primary);
  --color-action-primary-foreground: var(--felicityui-color-action-primary-foreground);
  --color-action-secondary: var(--felicityui-color-action-secondary);
  --color-action-secondary-foreground: var(--felicityui-color-action-secondary-foreground);
  --color-danger-default: var(--felicityui-color-danger-default);
  --color-danger-foreground: var(--felicityui-color-danger-foreground);
  --color-fg-default: var(--felicityui-color-fg-default);
  --color-muted: var(--felicityui-color-muted);
  --color-border-strong: var(--felicityui-color-border-strong);
  --color-focus-ring: var(--felicityui-color-focus-ring);
}
vite.config.ts
import path from "node:path";
import tailwindcss from "@tailwindcss/vite";
import react from "@vitejs/plugin-react";
import { defineConfig } from "vite";

export default defineConfig({
  plugins: [react(), tailwindcss()],
  resolve: {
    alias: {
      "@": path.resolve(import.meta.dirname, "src"),
    },
  },
});
PathPurpose
felicityui.jsonPlatform, aliases, registry URL
components/ui/button.tsxButton source
components/ui/input.tsxInput and Textarea source
components/ui/accordion.tsxAccordion source plus accordion.css
components/ui/dialog.tsxDialog source plus dialog.css
components/ui/drawer.tsxDrawer source plus drawer.css
lib/cn.tsclassName helper
ui/tokens/tokens.cssSemantic CSS variables

Paths are relative to the app root. React projects under src/ get that prefix. Confirm with npx felicityui doctor.

4

Usage

Call the native API

After add, import from the files in your tree. This is Button. Dialog and Drawer follow the same pattern on their pages.

example.tsx
import { Button } from "@/components/ui/button"

<Button>Button</Button>

Catalog

Five complete items. Each has a native implementation for React, SwiftUI, and Compose. Do not invent stubs that cannot be installed.

  • Button

    Native <button>, SwiftUI.Button, and a Compose button with FelicityUI colors.

    terminal
    npx felicityui add button --platform react
  • Input

    Native <input>, SwiftUI TextField, and Compose OutlinedTextField. Textarea ships in the same item.

    terminal
    npx felicityui add input --platform react
  • Accordion

    Native details/summary, SwiftUI DisclosureGroup, and a Compose expandable column.

    terminal
    npx felicityui add accordion --platform react
  • Dialog

    Native <dialog>, SwiftUI .alert, and Compose AlertDialog. Short confirms only.

    terminal
    npx felicityui add dialog --platform react
  • Drawer

    Edge panel on the web, .sheet on iOS, ModalBottomSheet on Android. No overlay library.

    terminal
    npx felicityui add drawer --platform react

Next