Installation

@kothry/ui is built on React (18 or 19) and Tailwind CSS v4: components reference semantic tokens only, and the utility classes are generated by your app's Tailwind build. Three steps — install, configure Tailwind, import the styles — and every component is ready to use.

Install the package

react and react-dom (≥18) are peer dependencies; Radix primitives, cva and lucide-react ship with the package. Tailwind CSS v4 is required in the consuming app.

Already on Tailwind v4? Then the first line is all you need. / 项目已用 Tailwind v4？那只需第一行。

# pnpm
pnpm add @kothry/ui
pnpm add -D tailwindcss @tailwindcss/postcss postcss

# npm
npm install @kothry/ui
npm install -D tailwindcss @tailwindcss/postcss postcss

Configure Tailwind v4

Tailwind v4 needs no tailwind.config — just the PostCSS plugin (what this docs site uses). On Vite, use the @tailwindcss/vite plugin instead.

Skip this section if Tailwind v4 is already wired up. / Tailwind v4 已就绪的项目可跳过本节。

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

Import the styles

Import the token sheet after Tailwind, then add an @source so Tailwind scans the package output — v4 ignores node_modules by default, and without it the components' utility classes are never generated. The path is relative to this CSS file.

@kothry/ui/styles.css carries all primitive, semantic and component tokens, including the .dark mappings. / @kothry/ui/styles.css 含全部 primitive、semantic 与 component token，包括 .dark 暗色映射。

/* globals.css */
@import 'tailwindcss';
@import '@kothry/ui/styles.css';

@source '../node_modules/@kothry/ui/dist';

Use a component

Everything exports from the package root. The preview below is rendered live by this snippet.

import { Button, Input } from '@kothry/ui';

export default function Page() {
  return (
    <div className="flex items-center gap-2">
      <Input size="sm" placeholder="Search reports…" className="max-w-48" />
      <Button size="sm">Submit</Button>
      <Button size="sm" variant="outline">
        Cancel
      </Button>
    </div>
  );
}

Monorepo / workspace usage

Inside this pnpm workspace, depend on the workspace version and point @source at the package source instead of dist — utility classes then update in dev without rebuilding the ui package.

This is exactly how this docs site consumes the package. / 本文档站就是按这种方式接入的。

// package.json
{
  "dependencies": {
    "@kothry/ui": "workspace:*"
  }
}

/* globals.css — adjust the relative path to your app's location */
@source '../../../packages/ui/src';

Next steps

Two more wiring guides complete the setup.

Fonts — load Inter / Satoshi / Fira Code and wire the font stacks. / 加载三个字族并桥接字体栈。
Theming — light / dark / system switching with next-themes. / 用 next-themes 实现亮暗与跟随系统切换。