# @lovett/ui 中文文档

规范地址：https://npmcn.com/package/%40lovett/ui/

版本：0\.6\.0
npm 元数据更新时间：2026-11-01T17:05:46.132Z
中文译文更新时间：2026-11-01T20:05:35.213Z
软件包许可：未声明

本文由上游 README 机器翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40lovett/ui
原文对照：https://npmcn.com/package/%40lovett/ui/?lang=original

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：9 MB，335 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：17 个
- peer 依赖：react ^19\.0\.0，react-dom ^19\.0\.0，lucide-react ^0\.469\.0，react-router-dom ^7\.1\.0
- 首次发布：2026-06-20T21:30:53.325Z
- 最新版本发布：2026-11-01T17:05:45.954Z
- 已发布版本数：31（近 12 个月 31 个）

## 中文简介

为Lovett组合设计系统原语、令牌、布局和模式。

## 安装

```sh
npm install @lovett/ui
```

也可以使用：`pnpm add @lovett/ui`、`yarn add @lovett/ui`、`bun add @lovett/ui`

## README

# @lovett / ui

原语、令牌、布局和模式：组件库ignite-workspace的应用； 安装Lightwork和广告引擎。它的子系统包括 `thread`， `detail`， `filter-core`， `data-grid`， `data-table`， `meta-previews`， `file-upload`， `icons` 和 `lib`.

## 规范的家：在这里，只在这里（ADR-CE-0151，接受日期2026-11-01）

这个目录位于 `edwinlov3tt/lovett-packages` 是 **唯一的来源和唯一的出版商** 的 `@lovett/ui`． 它是从ignite-workspace导入的 `packages/ui` 拥有完整的历史 点燃 `main` @ `2675a1440c6e5b61da21659fd00e1251594fbd65` （2026-10-16），取代过时的0.0.9 曾经住在这里的叉子。决定是ADR-CE-0151 `~/engines/docs/decisions/_active/`； Packages-pm释放它。

-   **在这里改变一个原语**，发布，消费者碰撞。消费者永远不会将此树与 `workspace:` 或者 `file:` (adr - ce - 0041)。
-   **release是一个标签 `main`** （`ui-v<version>`)、打包、tarball安装和检查； 然后发表。从来没有从树枝上。每次发布都必须高于注册表的最高版本， 在发布时间阅读(`npm view @lovett/ui versions`）。

### 切换（ADR-CE-0151 D1, D4）

1.  发布 **0.6.0** 从 `main` 在这里。当npm时完成 `latest` 等于一个 `pnpm pack` 标签的。
2.  Ignite-workspace停止发布（它的位置discoverypro-pm）： delete `.github/workflows/publish-ui.yml` 并且把npm信任的发布者从这个仓库中移走。在那之前 `ui-v*` 推到那里的标签会发布，NPM会指向 `latest` 在它。
3.  光功（lw-pm）：退休 `scripts/ui-release.sh` 或者指向它 `LOVETT_UI_DIR` 在这里。
4.  每个消费者在选择的版本上移动到一个家庭版本：从其供应商那里移动到一个家庭版本 npm的雇主构建的0.5.0，广告引擎的0.3.4的目录。

## 开发

```bash
pnpm install          # own lockfile; not a pnpm workspace
pnpm typecheck
pnpm test             # vitest, jsdom
pnpm build            # tsup -> dist/ (ESM, split chunks, bundled .d.ts, CSS + fonts copied)
pnpm check:dist-esm   # refuses a dist Node's ESM resolver cannot load; runs in prepublishOnly
```

源输出(`main`/`exports` -> `./src`)是源消费者解决的问题； `publishConfig` 把它们换成 `./dist` 为已发布的tarball。两张地图必须同时改变。

`scripts/check-dist-esm.mjs` 扫描每一个 `dist/*.js`． 它的存在是因为深层说明符没有 文件扩展名(`react-syntax-highlighter/dist/esm/styles/prism`)在Vite下构建绿色并失败 在Node下导入。在发布时是0.0.7和0.0.8，在这里被固定在0.0.9，在ignite's中丢失了 Tree（已发布的0.4.2包含它），并在0.5.0中再次修复。

## 主题

一套，几个造型。主题是一个有作用域的样式表，它重新指向工具包自己的令牌名称； 没有组件知道它在哪个主题中。进口 `tokens.css` 和 `styles.css` 首先是主题。

| 主题 | 进口 | 选择在 |
| --- | --- | --- |
| 套件（默认深色，浅色） | `@lovett/ui/tokens.css` | `data-theme="light"` (或 `combo`) `<html>`;没有代表黑暗 |
| v2 | `@lovett/ui/theme-v2.css` | `data-ds="v2"` 在任何元素上 |
| 洛维特(光工作) | `@lovett/ui/theme-lovett.css` | `data-ds="lovett"` 下面 `<html>` |
| Admium (0.5.0) | `@lovett/ui/theme-admium.css` | `data-ds="admium"` 在 `<html>` 或者任何元素 `<html data-theme="light">` |

**Admium** 是带有橙色调的暖色调(`#EF6820` 填满, `#E04F16` 按下, `#FFF0E5` 色彩, `#C2410C` 橙色文字)，由业主于2026-10-17在adadm的实验室批准。这是一个记号 覆盖套件的光主题，所以它只适用于 `data-theme="light"`;在黑暗中 没有匹配。除了令牌之外，它还添加了三样东西，它们都有作用域：

-   **凸起的主按钮**： 1px的白色内高亮（12%到0，从上到下），1px的圆环 在它自己的橙色，a `0 1px 2px rgba(13,18,27,0.24)` 影子，半粗体标签，也是一样的 半径和其他按钮一样。没有上升，没有发光的盘旋。
-   **控制发际线**：二级和图标按钮和搜索栏休息 `#E6E4E2` （`--border-control`)，而分割线则保留下来 `#F2F1F0`.
-   **国家芯片** 重新解析范围，因此它们的着色边界跟随温墨。

## 0.6.0：一棵树，从家族发布（2026-11-01）

**任何组件都不会更改其对存在于这两个0.5.0中的标记的查找。** 0.6.0是的并集 两个不同的0.5.0版本（ADR-CE-0151 D2）：

-   **这个家庭是0.5.0** (lovett-packages `feat/ui-home` B12a8d4，从未发表；Admium供应商 它):admin主题和下面的所有者UI规则。
-   **npm的0.5.0** (ignite-workspace `packages/ui` 8f3ae0d1，出版日期2026-10-18；的目录 安装它)：风险办公桌的工具包缺口。那是唯一点燃承诺去触摸 `packages/ui` 在2675a144分裂后。

消费者移动时必须知道的事情：

-   **从npm的0.5.0（目录）：** 您将获得下面的所有者UI规则（无粗体，无颜色） 过渡，芯片边界在其油墨的30%，同心半径)。这些都是业主的意图 变更;检查你的截图。你所有的出口都还在。
-   **从家庭的0.5.0 (adum)：** 你就获得了StateChip `icon` 和 `bare`， `DropdownMenuRadioGroup` 和 `DropdownMenuRadioItem`, SegmentedPill `ariaLabelledBy`， `ariaDescribedBy` 和项目 `title`,托盘 `size="wide"`、按钮 `variant="danger-text"`， `aria-disabled` on按钮和开关， `readOnly` 在开关和复选框上，烤面包机 `closeButtonLabel` 和 `dismissOnEscape`． 洛维特范围的油墨变化只适用于下面 `data-ds="lovett"`.
-   将依赖项替换为 `"@lovett/ui": "0.6.0"`． 对一揽子计划来说，顺风仍然是必要的 源(`@source` 在 `node_modules/@lovett/ui/src`);0.7.0消除了这种需要。

已解决的合并文件。Npm的提交没有冲突地应用到家族树中，所以每个文件 携带双方的变化：

| 文件 | 来自家庭（b12a8d4） | 源自npm （8f3ae0d1） |
| --- | --- | --- |
| `src/badge.tsx` | 重读文本读 `--accent-ink` | StateChip `icon` 和 `bare` |
| `src/checkbox.tsx` | 无颜色过渡 | `readOnly` |
| `src/dropdown-button.tsx` | 菜单填充6px到4px（同心圆半径） | 这个 `danger-text` 变量的类 |
| `src/dropdown-menu.tsx` | 菜单填充，没有颜色过渡 | 无线电组和无线电项； **新的无线电项目 `transition-colors` 删除这**，以匹配所有者的规则（0.6.0编辑对npm的代码所做的修改） |
| `src/floating-drawer.tsx` | 无颜色过渡 | 托盘 `size="wide"` |
| `src/segmented-pill.tsx` | 无颜色过渡 | ARIA道具，项目 `title` |
| `src/styles.css` | 按钮、输入和链接上没有颜色过渡 | `danger-text`， `aria-disabled` 和 `readOnly` 风格 |
| `src/theme-lovett.css` | 搜索字段仅转换其阴影 | 洛维特范围油墨，禁用初级，危险文本，640px以下16px字段 |
| `package.json` | 0.5.0， adm主题导出 | 0.5.0 |

Npm的commit也改变了 `button.tsx`， `switch.tsx`， `toast.tsx` 和 `index.ts`和感动 9个测试文件（其中4个是新的）。仅这个家庭就涉及了73个其他文件：下面的规则，和 新 `theme-admium.css`.

同样在0.6.0中，这些都不可见：

-   **皮棉经营。** `eslint.config.js` 扩展 `@lovett/elint/migrating`, `react-hooks` 和 测试tsconfig连接。修正了传递硬规则：承诺返回处理程序是 `void`艾德 （计算器外壳、代码块、复制字段、文件拖放区、文件夹选择器、配置文件部分），以及 上传id来自 `crypto.getRandomValues` 而不是 `Math.random`.
-   **测试:** 1793人通过，其中记号形状测试。

## 0.5.0：所有者的UI规则，在源处固定（2026-10-17）

一旦升级到0.5.0，这些将改变每个消费者的渲染方式。消费者固定版本，所以 在那之前什么都不会动。 `src/__tests__/ui-rules.test.ts` grep `src/` 对于那些可检查的 他们不能回来了。

-   **没有大胆的。** `font-bold` / `font-extrabold` / `font-weight: 700` 成为 `font-semibold` (600) 标题、标题、标签和图表，以及 `font-medium` （500）关于行内强调（降价） `strong`（浮动状态栏的标签）。豁免: `meta-previews/`，它可以繁殖 Facebook / Instagram / Messenger chrome，以及700 `@font-face` 这些预览使用。
-   **没有颜色过渡。** `transition-colors` 有色人种成员 `transition-[...]` 列表是 走了, `transition-all` 命名它动画的属性(`width`， `opacity`)，以及CSS 回退的 `--btn-transition`， `--input-transition`， `--pager-transition` 和 `--search-transition` 只保留 `box-shadow` / `transform` (或 `none`）. 颜色,背景, 边框颜色，填充和描边现在立即改变。故意保留：几何渐变（条） 宽度，图表路径，折叠行)和褪色滚动条的 `scrollbar-color`.
-   **染色的芯片边界。** 芯片的边界是它自己的30%的墨水，而不是中性的灰色 默认的 `--state-*-border` 令牌(是 `--border` / `--border-strong`), `DeltaChip`的 中立的语气。 `Badge` 和 `MetricCard`的 `accent` 现在的语气是 `--accent-ink` (同 Kit的轻主题)。
-   **同心半径。** 当一个圆角元素位于另一个元素的内部小于等于8px时，其外部半径为 内半径加上间隙。固定在套件和洛维特范围： `DropdownMenuContent`， `DropdownButton`，折叠式侧边栏弹出框和 `Select` / `Combobox` 列表框填充4px（原来为6），约为md行；这个 `FilterDropdown` 列表为lg / 4px / md （为md / 6px / 8px）； `Modal`的托盘是lg内xl面板（md）；冒泡菜单工具栏 和链接组是lg围绕sm按钮（是sm，圆比外）；数据表 过滤器和列管理器弹出窗口是xl (md)；板列头按钮是lg在2xl 列;文件预览缩略图， `ChipNav`的轨道（12默认，10紧凑型）， `CopyField`的 按钮（现在也在中间）， `SegmentedChoice`， `FilterChip`的移除按钮， `TaskCard` 媒体和 握力，线建议和分类药丸， `TagChipInput` / `FolderTreePicker` 期权和芯片 删除按钮, `StatRow`内面板，业主带， `FolderCard`的复选框 附件掉落叠加和提示环的错误边使用 `calc(var(--radius-X) - gap)` (或 `+`)，所以这两个主题都有。故意单独保留：控件在填充页脚或字段中 线程编写器页脚，附件芯片，芯片里面 `Combobox` / `TagChipInput` 字段), 其中同心圆的答案是一个正方形控制；只允许悬停的行(`FieldRow`，筛选菜单行)； 和洛维特的搜索线索，其同心圆半径是一个正方形的键帽（光之工作的召唤）。
-   **没有条件呈现的对话框。** 试剂盒没有 `{x && <Dialog|Modal|Sheet|Drawer>`； 测试保持这种状态。

## 知道差距

-   `TODO(ui-tray-exit)`： `Tray` （floating-drawer.tsx）有一个进入动画，但是返回 `null` 当 `open` 为false，因此它的关闭动画永远不会运行； `Modal` 也卸载时关闭(它 没有动画损失)。两者都是由它们的开放道具驱动的，这就是对话规则 消费者的要求；保持 `Tray` 通过它的出口装载的是一个单独的行为改变。
-   `TODO(ui-lint-backlog)`： lint运行 `@lovett/elint`自0.6.0以来的迁移预置，为零 错误。在ignite的宽松配置下编写的代码有12条严格的规则 失败;它们列在 `eslint.config.js` 然后一次又一次地燃烧。
-   这个 `ds` x `ui` 重叠（60个名称，6个格式冲突的令牌）是允许共存的 根据ADR-CE-0034 D1。将两者融合是一个单独的决定。

## 常见问题

### @lovett/ui 是什么？

为Lovett组合设计系统原语、令牌、布局和模式。

### 如何安装 @lovett/ui？

在项目目录运行 npm install @lovett/ui，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：react（^19\.0\.0）、react-dom（^19\.0\.0）、lucide-react（^0\.469\.0）、react-router-dom（^7\.1\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @lovett/ui 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @lovett/ui 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @lovett/ui 可以商用吗？

@lovett/ui 使用 未声明 许可。package\.json 没有声明许可证。没有许可证的代码默认保留全部权利，商用前请联系作者或查看仓库中的 LICENSE 文件。以上为概括，不构成法律意见，请以许可原文为准。

### @lovett/ui 还在维护吗？

最新版本 0\.6\.0 发布于 2026/11/02（1 天前）；至今共发布 31 个版本，其中过去 12 个月发布了 31 个；首次发布于 2026/06/21。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。