# @bsuite/theme 中文文档

规范地址：https://npmcn.com/package/%40bsuite/theme/

版本：1\.5\.7
npm 元数据更新时间：2026-10-20T18:04:09.561Z
中文译文更新时间：2026-11-08T17:36:40.846Z
软件包许可：UNLICENSED

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

原始 npm 页面：https://www.npmjs.com/package/%40bsuite/theme
原文对照：https://npmcn.com/package/%40bsuite/theme/?lang=original
项目主页：https://github.com/Arcane-Fly/bsuite#readme
源码仓库：https://github.com/Arcane-Fly/bsuite

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

- 包体积（解压后）：325 kB，51 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：0 个
- peer 依赖：react \>=18\.0\.0，react-dom \>=18\.0\.0，tailwindcss \>=4\.0\.0，@supabase/supabase-js \>=2\.0\.0
- 首次发布：2026-04-20T03:03:29.897Z
- 最新版本发布：2026-10-20T18:04:09.041Z
- 近 30 天下载量：4352（2026-10-09 至 2026-11-07，npm 官方下载统计）
- 已发布版本数：56（近 12 个月 56 个）

## 中文简介

BSuite环球主题 — D2C Neon Electric + Braden公司基线. Tailwind v4 preset, CSS vars (5-layer), 角色别名, 色彩盲-安全标志, 眼-斜-安全文本比例尺, Branding Provider (runtime white-label). 用于BSU,CRM7,管道,R80.4,

## 安装

```sh
npm install @bsuite/theme
```

也可以使用：`pnpm add @bsuite/theme`、`yarn add @bsuite/theme`、`bun add @bsuite/theme`

## README

# @bsuite/主题

BSuite monorepo 通用主题包. 船舶 D2C 霓虹电源基线 布雷登公司基线 泰尔风能令牌 CSS变量 React `ThemeProvider`运行时间 `BrandingProvider`,还有框架不可知的FOUC预防脚本.

## 里面的东西

-   **CSS 变量** – OKLCH源调色板,角色别名,光/暗表面,阴影桥变量,和WCAG AA兼容的反光文本符号
-   **双重品牌基线** - D2C通过 `@bsuite/theme/css`; 布拉登通过 `@bsuite/theme/braden-css`
-   **原生滚动条** ——两个基线都使用语义拇指/音轨颜色并遵循已解析的根 `.dark` 课。 粗放指针能保持站台宽;强制色模式能保持站台颜色和宽度. 消费者不应在当地重复这些规则.
-   **尾风 v4+ `@theme` 块** —— 说 `@import '@bsuite/theme/preset-v4.css'`
-   **运行时高程** —— 说 `--shadow-elev-0` 结束 `--shadow-elev-4` 总是被放出,包括仅通过保存的页面外观选择的深度。 卡片默认保留其高;0是明确的用户选择.
-   **`<ThemeProvider>`** + 键 **`useTheme()`** 具有本地Storage持久性+系统偏好
-   **`<BrandingProvider>`** ——企业运行时间为D2C应用软件的白标;布拉登短路至静态公司代币
-   **`getThemeInitScript()`** - 为内在化而成的联署材料 `<script>` 防止 FOUC 的标签

## 安装

```bash
pnpm add @bsuite/theme
```

## 消费者设置

### 维特 (Tailwind v4+) — BSU / CRM7 / R80.4 / 通量

**1\. 联合国.** `src/index.css` 或等同的全局样式表 :

```css
@import 'tailwindcss';
@import '@bsuite/theme/preset-v4.css';
@import '@bsuite/theme/css';

/* your app-specific @theme {} overrides below */
```

Braden使用相同的Tailwind桥形状,但导入了公司基线:

```css
@import 'tailwindcss';
@import '@bsuite/theme/braden-css';
```

**2\. 联合国.** `src/main.tsx`数字 :

```tsx
import { ThemeProvider } from '@bsuite/theme/react'

ReactDOM.createRoot(document.getElementById('root')!).render(
  <ThemeProvider>
    <App />
  </ThemeProvider>
)
```

**3个.** `index.html` - FOUC预防:

粘贴结果 `getThemeInitScript()` 输入 `<head>` 样式表之前.

### Next.js 16 (Tailwind v4+) — 管道 :

**1\. 联合国.** `src/app/globals.css`数字 :

```css
@import 'tailwindcss';
@import '@bsuite/theme/preset-v4.css';
@import '@bsuite/theme/css';
```

**2\. 联合国.** `src/app/layout.tsx` ——入行主题动画脚本入行 `<head>`数字 :

```tsx
import Script from 'next/script'
import { getThemeInitScript } from '@bsuite/theme/ssr'
import { ThemeProvider } from '@bsuite/theme/react'

export default function RootLayout({ children }) {
  return (
    <html lang="en" suppressHydrationWarning>
      <head>
        <Script id="bsuite-theme-init" strategy="beforeInteractive">
          {getThemeInitScript()}
        </Script>
      </head>
      <body>
        <ThemeProvider>{children}</ThemeProvider>
      </body>
    </html>
  )
}
```

### 尾风地板

所有消费者必须使用Tailwind CSS v4或后期. 遗产 `./tailwind-preset` 导出仅保留到旧已发布的软件包元数据不会中断导入 分辨率; 这不是一个支持的 BSuite 消费路径 .

## 用钩子

```tsx
import { useTheme } from '@bsuite/theme/react'

export function ThemeToggleButton() {
  const { theme, resolvedTheme, isDark, setTheme } = useTheme()
  return (
    <button onClick={() => setTheme(isDark ? 'light' : 'dark')}>
      {isDark ? '☀️' : '🌙'}
    </button>
  )
}
```

这个 `resolvedTheme` 总是返回 `'light'` 或者说 `'dark'` - 需要的时候用这个 _有效_ 主题( 它解决 `'system'` 给您).

## 调色板和角色

所有11克纳克电动颜色都可以作为调色符提供,但消费者UI应该与角色/阴影符相接. 调色板名称是呈现性的;角色是白色标签的稳定合同.

**数值存在于 `src/css/vars.css` 财务报告和审定财务报表 `src/css/braden.css`也只有这里.** 本表给出了每个角色的 _约束_ 和拥有它的线,故意不 字义。 直到2026-09-03,它携带了文字,它的五行中有三行是 0.7.0合同前:它公布错误为紫色 `oklch(0.568 0.202 283.1)` 与“coral/red 决不能是语义错误/破坏性的”——确切的规则是 2026-08-02 重写被推翻——外加"绿色成功"和"橙色预警",两者均被推翻 还被取代. `AGENTS.md` 将此文件命名为 " 主题符号, 既 所以一个相信它的人 画了被推翻的调色板 第二个副本 数值是真理的第二个来源;本表现在指向.

| 角色/标志 | 捆绑到 | 拥有者 | 页:1 |
| --- | --- | --- | --- |
| `--role-primary` | `--neon-electric-blue` | `vars.css:152` | 主要行动和重点 |
| `--role-accent` | `--neon-electric-cyan` | `vars.css:154` | 暗模式下的 Accents, 亮点, 可见焦点 |
| `--role-secondary` | `--neon-electric-deep` | `vars.css:153` | 二级行动;因迪戈-小学0.037 |
| `--role-success` | `--neon-electric-teal` | `vars.css:168` | 成功; 绝不只依靠颜色 |
| `--role-warning` | `--neon-electric-amber` | `vars.css:167` | 警告; 与图标/文本对齐 。 由 LightTNESS 区分出错误 |
| `--role-error` 编号 : `--role-destructive` | `--neon-electric-red` | `vars.css:165-166` | **红色.** 房客无法控制 紫外线测量出正蓝方正蓝方正蓝方正蓝方正蓝方正蓝方正蓝方正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正 |

紫色、印地哥、珊瑚、橙色、黄色和绿色仍留在调色板中 **装饰** 条目。 他们中没有一个可能受语义角色的约束.

布莱登在其中保留了单独的公司身份标志 `@bsuite/theme/braden-css` (单位:千美元)`--braden-red`, (中文(简体) ), `--braden-gold`, (中文(简体) ), `--braden-navy`, (中文(简体) ), `braden.css:62-68`) (中文(简体) ). 红色是 仅限身份. **Braden 错误/ 破坏性角色映射到 `--error-red` (单位:千美元)`braden.css:81,187-188`)——同一误差红色 D2C 品牌用途,由运算器 第2026-08-10号裁决:识别胜过调色板分离,一个人读作红色 在他们读作"布拉登"之前"危险".** 费用在那个文件里 标题 —\\\\\\ \\ \\ \\ \\ \\ \\ \\ \\ \\ \\ \\ \\ \\ \\ \\ \\ \\ \\ \\ \\ \\ \\ \\ \\ \\ \\ \\ \\ \\ \\ 最紧的一对——所以对布拉登的破坏行动必须携带一个图标或一个 明确动词,永远不要单独着色.

WCAG AA的遵守:使用语义文字符号(`text-foreground`, (中文(简体) ), `text-muted-foreground`, (中文(简体) ), `text-text-on-primary`, (中文(简体) ), `text-text-on-accent`而不是生的 `text-white`编号 :`text-black`. 深表面文本为L=0.94,用于延长会场舒适度.

## 电梯(v0.11.0

`shadow-elev-0` . `shadow-elev-4` - 套房的卡通坡道 初释中,这些课程是存在的。 25个呼叫站点横跨crm7 和企业的一体化,四 `CLAUDE.md` 文档和目录 `bsuite-brand-system` 技术指导 `shadow-elev-*` 没有规则 在任何地方都比对它。每个计算 `box-shadow: none`。 。 。 .

-   `shadow-elev-0` 是真实的重置( r)`0 0 0 0 transparent`,而不是没有 一个规则。 这是故意的 `none`,它使 Tailwind v4 无效 复合 `box-shadow` 并用它取出焦点环.
-   几何跟随Tailwind的 `xs`编号 :`md`编号 :`lg`编号 :`xl`颜色来自 `--shadow-ink-*`,从 `--shadow-color` 缩放 以 `--shadow-strength`,在 `.dark`。 。 。 .
-   同一版重新装入了Tailwind自己的 `--shadow-*`, (中文(简体) ), `--inset-shadow-*`, (中文(简体) ), `--drop-shadow-*` 财务报告和审定财务报表 `--text-shadow-*` 在墨迹上 他们从 尾风为 `rgb(0 0 0 / a)` - 纯黑色,禁止任何角色 色彩审计中看不见的,因为字面上存在 `node_modules`。 。 。 . 292 (英语) `shadow-sm|md|lg|xl|2xl` 整个庄园的呼叫站点都在画画, 暗暗地画它.

几何学是不变的,所以没有移动;光模式的转动只有hue-tint. 黑暗模式在物质上变化,因为先前的暗影并没有渲染出.

## 文本作用合同(v. 6.0)

6个测量等级—— `--role-text-heading`, (中文(简体) ), `--role-text-body`, (中文(简体) ), `--role-text-secondary`, (中文(简体) ), `--role-text-muted`, (中文(简体) ), `--role-text-subtle`, (中文(简体) ), `--role-text-disabled` ——在两种模式中都有文件记载的WCAG对比. 全数+方法: `docs/TOKEN-MAPPING.md` 第8.1节.

## 条形梯度( v. 6. 0)

完全有一个装饰性的口音梯度存在整个套接字—— `--gradient-accent` 编号 : `.bsuite-accent-gradient` (单位:千美元)`--role-primary` → `--role-accent`) (中文(简体) ). 只有营销英雄, 从来没有功能文本. `docs/TOKEN-MAPPING.md` 第8.2节.

## 网格/点理论(v. 6.0)

`<HeroGrid>` (公共/预奥英雄乐队)和 `<DotPattern>` (核弹, `@bsuite/ui`)是相互排斥的,并且由 `@bsuite/dry-lint`是因为 `no-grid-dot-doctrine-violation` 规则. `docs/TOKEN-MAPPING.md` 第8.3节.

## Canonical品牌梯度验证

`normalizeBrandingGradient(value, normalizeColour)` 是共同的作者和公共阅读者语法。 它回来了 `accepted` 带有正态字符串(或) `null` 以便继承, `invalid`,或 `unsupported` 有个原因 征召者必须保留拒绝的草案,只画出公认的价值. 被否决的公众凌驾于其品牌角色.

无依赖性帮助器支持线性,光圈和圆锥梯度,它们重复的变体,多层,插入的色彩空间和花样方法,颜色提示,以及有界限的方向/光圈/位置前奏. 负色停止位置是合法的;明确的射线光度不能是负的,而圆形半径不能是百分比. 语义 `var(--role-*)` 叶子保留了遗产,有递归性地验证了后退. `transparent` 是明确的中性关键词。 已清除的字段保留公司或D2C默认.

回调拥有色彩剖析,范围检查和端点策略,包括α形式. BSU 的作者使用已安装的 Culori 转换器进行命名/RGB/HSL 颜色; Braden 消费 犬科作者 ix/OKLCH 不添加转换器依赖性. 回调输出必须是一色符号,在再次验证时保持不变;它不能注入额外的停止,函数或声明. 共享测试使用一个带有被认可的调色板输出的有名-叶政策根;消费者测试必须执行真正的转换器和阅读器回调.

这是一个有界限的品牌合同,而不是任意的CSS评价者:URL,评论,出逃,被引用的符号, `calc()`,未知函数/颜色空格,和未识别的停止语法返回明确拒绝。 语法 [CSS 图像梯度规范](https://drafts.csswg.org/css-images-4/) 财务报告和审定财务报表 [CSS 颜色规格](https://drafts.csswg.org/css-color-4/). 软件包本身不使用或授予品牌权.

## 许可证

UNLICENSED——只使用内部套件.

## 常见问题

### @bsuite/theme 是什么？

BSuite环球主题 — D2C Neon Electric \+ Braden公司基线\. Tailwind v4 preset, CSS vars \(5-layer\), 角色别名, 色彩盲-安全标志, 眼-斜-安全文本比例尺, Branding Provider \(runtime white-label\)\. 用于BSU,CRM7,管道,R80\.4,

### 如何安装 @bsuite/theme？

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

### @bsuite/theme 支持 TypeScript 吗？

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

### @bsuite/theme 支持 ESM 还是 CommonJS？

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

### @bsuite/theme 可以商用吗？

@bsuite/theme 使用 UNLICENSED 许可。作者声明为 UNLICENSED，即不授予公开使用许可（与公共领域的 Unlicense 不同）。使用前需获得作者授权。以上为概括，不构成法律意见，请以许可原文为准。

### @bsuite/theme 的下载量有多少？

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

### @bsuite/theme 还在维护吗？

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