文档目录

安装

在 React 19 + Tailwind v4 项目中接入样式与组件。

前置条件

Node.js ≥ 26
pnpm 12
React 19.2.8（peer 范围 ^19.2.0；19.3 与 Next 16 预渲染存在已知兼容问题）
Tailwind CSS v4

方式一：CLI 拷贝安装（推荐）

用 shadcn CLI 把组件源码直接拷进项目，再按需改造——这是 shadcn/ui 的使用习惯。

$npx shadcn init

初始化生成的 components.json 中加入本项目的 registry：

{
  "registries": {
    "@tennantite": "https://tennantite.rikka.cc/r/{name}.json"
  }
}

然后安装基础资产与组件：

$npx shadcn add @tennantite/tennantite-base @tennantite/button

CLI 安装会做什么

tennantite-base 条目自动安装 @tennantite/tokens 与 @tennantite/textures 两个 L0 资产包，并落下一个 base.css（记录需要引入的资产 CSS）。
组件源码拷贝到 components/tennantite/<组件名>/，跨组件依赖（registryDependencies）随组件一并拉取。
组件内部导入已改写为 @/components/tennantite/... 别名与 components/tennantite/lib/ 下的共享工具（cn、gui、screen 类型），不覆盖你已有的 @/lib/utils。

方式二：npm 直装

$pnpm add @tennantite/ui @tennantite/tokens @tennantite/textures

接入样式

在 Tailwind 入口 CSS 中按顺序引入：

@import "tailwindcss";
@import "@tennantite/tokens/css/tokens.css";
@import "@tennantite/textures/css/textures.css";
@import "@tennantite/ui/css/scroll-area.css";

/* 让 Tailwind 扫描包内类名；路径相对本 CSS 文件 */
@source "../node_modules/@tennantite/ui/dist";

body {
  background-color: #1f1f1f;
  color: var(--color-mc-text-main);
  font-family: var(--font-mc);
  font-size: var(--text-mc);
}

@source 的路径必须相对当前 CSS 文件；消费者按自己的目录位置调整，否则组件里的 Tailwind 类不会生成。

npm 直装：扫描包产物 node_modules/@tennantite/ui/dist。
CLI 拷贝：扫描拷贝目录，如 @source "../../components/tennantite"。

第一个组件

npm 直装时从包导入：

import { Button, Panel } from "@tennantite/ui";

CLI 拷贝时从本地组件导入：

import { Button } from "@/components/tennantite/button";
import { Panel } from "@/components/tennantite/panel";

export function StartPanel() {
  return (
    <Panel className="p-12">
      <Button variant="success">开始游戏</Button>
    </Panel>
  );
}

框架

组件默认 SSR 安全。仓库内提供 Next.js App Router 与 TanStack Start 两个验证应用；rsbuild playground 用于快速预览。约束与验证方式见 SSR / RSC。

常见问题

类名缺失：检查 @source 是否覆盖 node_modules/@tennantite/ui/dist。
间距不对：--spacing 等于 2px，w-20 是 40px，不是 80px。
React 版本：保持 19.2.8，避免 19.3 与 Next 16 的预渲染兼容问题。
中文显示：像素字体只覆盖拉丁字符，中文按令牌回退到系统无衬线字体。