# @burtson-labs/ui 中文文档

规范地址：https://npmcn.com/package/%40burtson-labs/ui/

版本：0\.19\.2
npm 元数据更新时间：2026-10-26T18:04:13.982Z
中文译文更新时间：2026-11-08T20:37:38.459Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40burtson-labs/ui
原文对照：https://npmcn.com/package/%40burtson-labs/ui/?lang=original
项目主页：https://ui.burtson.ai/
源码仓库：https://github.com/Burtson-Labs/ui

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

- 包体积（解压后）：2.9 MB，462 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：4 个
- peer 依赖：react \>=18，react-dom \>=18，@mui/material \>=6，@emotion/react \>=11，@burtson-labs/icons \>=0\.5\.0
- 首次发布：2026-09-24T21:18:08.843Z
- 最新版本发布：2026-10-26T18:04:13.327Z
- 近 30 天下载量：2323（2026-10-09 至 2026-11-07，npm 官方下载统计）
- 已发布版本数：34（近 12 个月 34 个）

## 中文简介

在伯特森实验室自己的行为原始物上,Tailwind v4 stypeling和Burtson Icons上,为伯特森实验室的产品做反应组件.

## 安装

```sh
npm install @burtson-labs/ui
```

也可以使用：`pnpm add @burtson-labs/ui`、`yarn add @burtson-labs/ui`、`bun add @burtson-labs/ui`

## README

![Burtson Labs](https://cdn.burtson.ai/logos/burtson-labs-logo-alt.png)

# 伯特森大学

**布尔特森实验室产品的反应组件.**

用于"盗贼隐蔽","哨兵",我们的集群工具和客户端应用. 伯特森实验室自己的原始地层(`src/primitives`: 焦点、 解职、 定位、 存在、 菜单、 选择、 窗体控件) 处理行为; Tailwind v4 处理样式, 图标是 [伯特森图标](https://icons.burtson.ai/)。没有运行时间提供者。 安装软件包, 或复制一个组件的来源并更改它 .

[![Docs](https://img.shields.io/badge/docs-ui.burtson.ai-a60ee5)](https://ui.burtson.ai/) [![npm](https://img.shields.io/npm/v/@burtson-labs/ui?logo=npm)](https://www.npmjs.com/package/@burtson-labs/ui) [![License](https://img.shields.io/badge/license-MIT-blue)](https://npmcn.com/package/%40burtson-labs/ui/LICENSE) [![CI](https://github.com/Burtson-Labs/ui/actions/workflows/ci.yml/badge.svg)](https://github.com/Burtson-Labs/ui/actions/workflows/ci.yml)

AI代理的文档 : [页:1](https://ui.burtson.ai/llms.txt) • 妇女 [llms- full.txt (英语)](https://ui.burtson.ai/llms-full.txt) • 妇女 [与人工智能代理使用](https://ui.burtson.ai/docs/ai-agents)

* * *

## ![](https://icons.burtson.ai/svg-black/package-build.svg) 安装

```bash
npm install @burtson-labs/ui @burtson-labs/icons
```

用 Tailwind CSS v4 添加主题, 让 Tailwind看到组件类 :

```css
@import 'tailwindcss';
@import '@burtson-labs/ui/theme.css';
@source '../node_modules/@burtson-labs/ui/dist';
```

没有 Tailwind(例如 MUI app), 导入预编译样式一次 :

```ts
import '@burtson-labs/ui/styles.css';
```

然后说:

```tsx
import { Button } from '@burtson-labs/ui';

export const Save = () => <Button>Save</Button>;
```

### 或者复制来源

每一组成部分也是登记册中的登记项目 [阴影](https://ui.shadcn.com/) 登记册格式。 CLI 复制文件到 `components/ui`,并添加 Burtson 主题 :

```bash
npx shadcn@latest add https://ui.burtson.ai/r/button.json
```

或者加点 `@burtson` 命名空间到 `components.json` 并按名称安装 :

```json
{ "registries": { "@burtson": "https://ui.burtson.ai/r/{name}.json" } }
```

```bash
npx shadcn@latest add @burtson/button
```

### 与人工智能代理使用

Claude Code, Cursor, Codex, Copilot等编码代理可以将文件读作纯文本,并通过注册处安装组件:

-   [`llms.txt`](https://ui.burtson.ai/llms.txt) 列出每个组件; [`llms-full.txt`](https://ui.burtson.ai/llms-full.txt) 全部保存在一个文件中;每个页面也是 Markdown at `https://ui.burtson.ai/docs/components/<name>.md`。 。 。 .
-   `npx shadcn@latest mcp init --client claude` (或 `cursor`, (中文(简体) ), `vscode`, (中文(简体) ), `codex`)设置shadcn MCP服务器,可以搜索并安装 `@burtson/*` 名称空格 `components.json`。 。 。 .
-   `npx skills add burtson-labs/ui` 安装 [`burtson-ui` 特工技能](https://npmcn.com/package/%40burtson-labs/ui/skills/burtson-ui/SKILL.md)。 。 。 .

这个 [与人工智能代理使用](https://ui.burtson.ai/docs/ai-agents) 页面有一组规则可以粘贴到 `CLAUDE.md` 或者说 `AGENTS.md` 并举出例子。 贡献者代理人:见 [一般事务人员(其他职等)](https://npmcn.com/package/%40burtson-labs/ui/AGENTS.md)。 。 。 .

## ![](https://icons.burtson.ai/svg-black/panel-grid.svg) 构成部分

Access-Agent run-Control – Access-App Sell – App Sell – Avatar – Avatar – Avatar – 上传-徽章 – Breadcrumb – Button – Card –聊天历史 –聊天布局 – 复选框 – 复选卡 – Combobox – 命令 –composers – 连接状态 – 上下文 菜单 – 对话 复制按钮 数据表 – 对话框 滴放菜单 编辑器 标签 空白状态 – 编译器 场 动作 图标 Button 输入 – Kbdd Label – Markdown – Menubar 消息 移动导航 – 本地选择 导航 菜单 – 数字输入器上登入页 页面 页面 切入页 程 – 传输器 动态 传输器 列表 – 列表 中程 – 列表 – 列表 – 中程 中程 –

现场预览、待使用笔记、无障碍笔记和每个笔记的代码 [(原始内容存档于2018-10-21). ui.burtson.ai](https://ui.burtson.ai/docs/components/button)建立聊天应用程序? 这个 [聊天食谱](https://ui.burtson.ai/docs/recipes/chat) 将历史,附件,流线,语音笔记和全屏幕放在一起,并配有完整的源. 造出一个表格? `Field` 任何控件上的线条标签、帮助和错误, `FieldGrid` 上行字段和 `FormActions` 把按钮放在手机上.

每个控件在触摸屏上至少是44px,每个控件显示一个焦点样式(`focusRingClasses`, (中文(简体) ), `fieldFocusClasses`),并满足文本的4.5:1和调色板和任何口音的3:1的边界;在CI中被Playwright所出出一股烟来测量.

### 代理决定、装载和外出

```tsx
import {
  AskUser, AgentPlan, ContextUsage, CircularProgress, LoadingDots,
  ThemeProvider, ThemeToggle,
} from '@burtson-labs/ui';

<ThemeProvider defaultTheme="system" storageKey="app-theme">
  <ThemeToggle />
  <AskUser
    questions={[{ id: 'goal', prompt: 'What should I focus on?' }]}
    onSubmit={async (answers) => { await sendAnswers(answers); }}
  />
</ThemeProvider>

<CircularProgress label="Connecting" />; // unknown duration
<CircularProgress value={64} label="Uploading" showValue />;
<LoadingDots label="Thinking" showLabel />;
<ContextUsage used={42000} limit={200000} />;
```

装入主题输入脚本 `<head>` 因此保存的暗色主题在第一次涂料之前应用( 无) 灯光闪烁)。 在严格的CSP服务下,以数据属性配置的文件:

```html
<script src="/theme-init.js" data-storage-key="app-theme"></script>
```

从复制 `@burtson-labs/ui/theme-init.js`,或提供 `themeInitScript({ storageKey: 'app-theme' })` 内入并添加 `await themeInitScriptHash({ storageKey: 'app-theme' })` 改为 `script-src`。 。 。 .

这个 [主题编辑器](https://ui.burtson.ai/docs/theming) 预览预设,自定义口音, 角半径和控制密度 和导出两个调色板。 特工召回属于你的 运行时间。 见 [审计范围](https://npmcn.com/package/%40burtson-labs/ui/docs/agent-component-audit.md) 现有构成部分 和仍然存在的工作流程差距.

## ![](https://icons.burtson.ai/svg-black/palette.svg) 他们

[`src/tokens.ts`](https://npmcn.com/package/%40burtson-labs/ui/src/tokens.ts) 是颜色、半径和类型的单一来源。 它会产生 `theme.css` (CSS变量,带有阴影名称加 `brand`, (中文(简体) ), `brand-soft`, (中文(简体) ), `success` 财务报告和审定财务报表 `warning`),输入登记册的主题项目,并驱动MUI适配器。 光是默认值; 添加 `class="dark"` 或者说 `data-theme="dark"` 改为 `<html>` 为了黑暗.

### MUI 应用程序

大部分伯特森实验室的应用程序 今天运行的MUI。 他们现在可以分享调色板 一次采用一个屏幕的组件:

```tsx
import { ThemeProvider } from '@mui/material/styles';
import { createBurtsonTheme } from '@burtson-labs/ui/mui';

<ThemeProvider theme={createBurtsonTheme('dark')}>{app}</ThemeProvider>;

// A product accent and admin density; contrast is kept for any accent.
createBurtsonTheme({ mode: 'dark', accent: '#2563eb', density: 'compact' });
```

`@burtson-labs/ui/tokens` 还出口 `accentTokens(accent, mode)` cSS方面,运动时间`duration`, (中文(简体) ), `easing`这 `theme.css` 暴露为 `--duration-*` 财务报告和审定财务报表 `--ease-*` 和每个 `transition-*` 工具运行在, 并且 `elevation` 职等(`shadow.lg` 为浮起的表面, `shadow.xl` 方式的)和 `layer` z-index比例表(提高10分,铬40分,叠加50分,土司100分).

## ![](https://icons.burtson.ai/svg-black/terminal.svg) 开发

```bash
npm install
npm run dev        # docs site with live components, http://localhost:5173
npm run check      # typecheck, lint, format, tests, package build, site build
npm run smoke      # Playwright: touch targets, focus, overflow, keyboard (needs npm run site)
npx playwright test --config playwright.navigation.config.ts # navigation, including mobile Safari
```

| 路径 | 什麽 |
| --- | --- |
| `src/components/` | 每个组件一个文件;以及登记册来源 |
| `src/tokens.ts` | 设计符号(在此编辑) `npm run theme`(中文(简体) ) |
| `src/mui/` | MUI 主题适配器 |
| `site/` | 文档网站 [(原始内容存档于2018-10-21). ui.burtson.ai](https://ui.burtson.ai/); 演示 `site/src/demos/`,注释 `site/src/usage.ts`· ; `/matrix` 使每个州的每个组成部分 |
| `e2e/` | 浏览器烟雾(Playwright, Chromium at 1440 and 390 touch) |
| `scripts/` | 软件包构建、主题和注册生成器、链接预览卡 |

添加组件:写入 `src/components/<name>.tsx` (注释:, `data-slot` 在每一个方面, `focusRingClasses` 或者说 `fieldFocusClasses` 用于焦点,44px on touch),导出自 `src/index.ts`演示 `site/src/demos/<name>.tsx`条目 `site/src/docs.ts`,其注解在 `site/src/usage.ts` 和一个单元格 `site/src/matrix.tsx`。登记簿在下一个建筑上取出.

绘制和格式化 [伯特森实验室前端标准](https://github.com/Burtson-Labs/frontend-standards)。每次推力都由 [哨兵队](https://github.com/Burtson-Labs/sentinel-audit)。 。 。 .

## 初级和API 参考文献

行为原始是伯特森实验室自己的层 `src/primitives`,取自WAI-ARIA的写作实践和网络规格(设计注释,载于其 [读取](https://npmcn.com/package/%40burtson-labs/ui/src/primitives/README.md); 复制源使用 [初级](https://ui.burtson.ai/docs/primitives) 页:1 该套件没有Radix,cmdk或其他组件-图书馆代码,也没有运行时间依赖它们. [API 参考.md](https://npmcn.com/package/%40burtson-labs/ui/API_REFERENCE.md) 列出生成的组件引用,以及 [第三次议会 NoTICES.md](https://npmcn.com/package/%40burtson-labs/ui/THIRD_PARTY_NOTICES.md) (c) 继续调整的许可证(shadcn/ui的类别清单和公约).

## 许可证

[麻省理工学院](https://npmcn.com/package/%40burtson-labs/ui/LICENSE) 伯特森实验室 受到来自 [阴影/ ui](https://github.com/shadcn-ui/ui) (麻省理工学院);见 [第三次议会 NoTICES.md](https://npmcn.com/package/%40burtson-labs/ui/THIRD_PARTY_NOTICES.md)。 。 。 .

## 常见问题

### @burtson-labs/ui 是什么？

在伯特森实验室自己的行为原始物上,Tailwind v4 stypeling和Burtson Icons上,为伯特森实验室的产品做反应组件\.

### 如何安装 @burtson-labs/ui？

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

### @burtson-labs/ui 支持 TypeScript 吗？

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

### @burtson-labs/ui 支持 ESM 还是 CommonJS？

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

### @burtson-labs/ui 可以商用吗？

@burtson-labs/ui 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @burtson-labs/ui 的下载量有多少？

根据 npm 官方下载统计，@burtson-labs/ui 在 2026/10/09 – 2026/11/07 这 30 天内被下载 2,323 次，日均约 77 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @burtson-labs/ui 还在维护吗？

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