Documentation

Installation

Install the built package from its public Git tag, set up Tailwind v4, then mount one provider. The Vite and Next.js recipes below are both verified in clean consumer projects.

Git tag

Works today

The public install is the built package at the immutable v1.0.1 Git tag. It needs no install script, and the lockfile records the resolved commit.

pnpm add @luc/ui@github:lucxu495/luc-ui#v1.0.1

npm install @luc/ui@github:lucxu495/luc-ui#v1.0.1

yarn add @luc/ui@github:lucxu495/luc-ui#v1.0.1

bun add @luc/ui@github:lucxu495/luc-ui#v1.0.1

Packed tarball

Works today

Use the release tarball for offline or checksum-pinned installs. This repository's consumer gate installs both this artifact and the public Git tag with plain npm.

pnpm add ./luc-ui-1.0.1.tgz

npm install ./luc-ui-1.0.1.tgz

yarn add ./luc-ui-1.0.1.tgz

bun add ./luc-ui-1.0.1.tgz

Core setup

Install

Add the built package from the public Git tag with whichever package manager the project already uses.

pnpm add @luc/ui@github:lucxu495/luc-ui#v1.0.1

Import the styles

The stylesheet is Tailwind CSS v4 and ships the tokens plus component styles. Import Tailwind first, then the package stylesheet, once at the application root.

@import "tailwindcss";
@import "@luc/ui/styles.css";

Install the provider

One provider supplies the resolved theme, the locale and the motion default to every component below it. In Next.js, put the returned init script in the document head before hydration.

import { LucProvider, lucThemeInitScript } from "@luc/ui";

const themeScript = lucThemeInitScript({ defaultTheme: "dark" });
// <head><script dangerouslySetInnerHTML={{ __html: themeScript }} /></head>
// <LucProvider defaultTheme="dark">{children}</LucProvider>

React + Vite

Install Tailwind v4

The Luc UI stylesheet is Tailwind CSS v4 source, so the consumer compiles it with the Vite plugin.

npm install -D tailwindcss@4 @tailwindcss/vite@4

// vite.config.ts
import tailwindcss from "@tailwindcss/vite";
import react from "@vitejs/plugin-react";
import { defineConfig } from "vite";

export default defineConfig({ plugins: [react(), tailwindcss()] });

Render a component

Import from the public package entry and wrap the application in LucProvider.

import { LucProvider, Button } from "@luc/ui";

export function App() {
  return (
    <LucProvider defaultTheme="dark">
      <Button>Save view</Button>
    </LucProvider>
  );
}

Next.js App Router

Install the PostCSS adapter

Next.js compiles the same Tailwind v4 stylesheet through its PostCSS pipeline.

npm install -D tailwindcss@4 @tailwindcss/postcss@4

// postcss.config.mjs
export default { plugins: { "@tailwindcss/postcss": {} } };

Root layout

Import global CSS once, run the theme init script before paint, and keep LucProvider as the client boundary.

import { LucProvider, lucThemeInitScript } from "@luc/ui";
import "./globals.css";

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en" suppressHydrationWarning>
      <head>
        <script dangerouslySetInnerHTML={{ __html: lucThemeInitScript({ defaultTheme: "dark" }) }} />
      </head>
      <body><LucProvider defaultTheme="dark">{children}</LucProvider></body>
    </html>
  );
}

Charts

Prepared series

Charts receive data you prepared. The component supplies a height; use a client boundary in Next.js.

"use client";
import { LineChart } from "@luc/ui/charts";

const rows = [
  { date: "2026-08-01", close: 94.2 },
  { date: "2026-08-08", close: 95.1 },
  { date: "2026-08-15", close: 96.4 },
];

export function PriceChart() {
  return (
    <LineChart
      data={rows}
      xKey="date"
      series={[{ key: "close", label: "Close", type: "line" }]}
      height={240}
      ariaLabel="Weekly closes"
    />
  );
}

TradingView

Provider widget

The TradingView subpath loads a third-party provider widget. Market data and attribution belong to TradingView, not Luc UI.

"use client";
import { TradingViewMiniChart } from "@luc/ui/tradingview";

export function MarketCard() {
  return <TradingViewMiniChart symbol="NASDAQ:AAPL" height={180} />;
}

Troubleshooting

If utilities are missing, confirm Tailwind v4 is configured and @luc/ui/styles.css is imported after @import "tailwindcss".
If an import fails, use a documented package subpath; do not import from src or dist.
If a chart has no width, give it a width-bearing parent; a chart needs a layout box even when height is set.
If a TradingView widget is unavailable, check the wrapper fallback and the network boundary before changing the page.

Requirements

react ^19.0.0
react-dom ^19.0.0
react-hook-form ^7.0.0 (optional, for @luc/ui/forms/react-hook-form)
tailwindcss ^4.0.0
node >= 22 (repository tools)

Components are imported from their own subpath, which is what keeps a chart engine out of a bundle that only needed a button.