定制概览

Nebutra-Sailor 中所有可定制的内容——品牌颜色、主题、仪表板页面以及引导流程。

Nebutra-Sailor 被设计为完全可白标化。每一个视觉和结构元素——从品牌调色板到单个仪表板页面——都可以在不分叉核心包的情况下进行定制。

可定制的内容

品牌与主题

更改品牌颜色，通过 data-brand 在内置 Brand Package 之间切换，配置明暗模式，以及创建完全自定义的 oklch 主题。

组件库

在 Storybook 中浏览所有组件，独立开发新组件，以及使用 CVA 变体扩展现有原语组件。

架构

定制遵循严格的单向 Token 流。在较低层级的更改会自动向上传播。

@nebutra/tokens   ← 在此处编辑 CSS 变量以重新品牌化
      ↓
@nebutra/ui       ← 组件消费 token；在此处添加新组件
      ↓
apps/web          ← 仪表板页面组合组件
apps/landing ← 营销网站组合组件

由于 @nebutra/ui 中的每个颜色和间距值都是 CSS 变量引用（而非硬编码的十六进制值），编辑位于 packages/design/design-tokens/tokens/*.json 的 DTCG token 源——或运行调色板脚本——就能级联影响整个产品。

token 构建会据此重新生成（generated）packages/design/tokens/styles.css；该文件本身不接受手工改动。

快速上手（5 分钟以内）

更改品牌颜色

# 将蓝色换为紫色，青色换为琥珀色，只需一条命令
node scripts/generate-palette.mjs --primary=#7C3AED --secondary=#F59E0B

该脚本会将 brand-override.css 打印到标准输出——它本身不会写入任何磁盘文件。将输出重定向到一个文件并在 @nebutra/tokens/styles.css 之后 @import 它，或者将数值并入 packages/design/design-tokens/tokens/*.json 中的 DTCG token 源后重新构建。

切换活跃的 Brand Package

import { applyLanguage, clearLanguage } from "@nebutra/theme";

applyLanguage("vanta", { persist: true }); // LANGUAGE_REGISTRY 中任意内置 id
clearLanguage(); // 恢复出厂默认

nebutra theme list
nebutra theme use vanta

切换深色模式

import { useTheme } from "@nebutra/tokens";

const { theme, setTheme } = useTheme();
setTheme("dark"); // "light" | "dark" | "system"

高级定制

目标	从哪里开始
新建 Brand Package	`packages/design/tokens/brands/<id>/brand.json` + 在 `packages/design/theme/src/languages.meta.json` 中添加条目，然后运行 `node packages/design/theme/scripts/sync-languages.mjs`（会重新生成 `languages.json`——不要手动编辑它）
新建 UI 原语组件	`packages/design/ui/src/components/` + Storybook 故事
新建仪表板板块	`apps/web/src/app/(dashboard)/[section]/page.tsx`
修改引导步骤	`apps/web/src/app/(onboarding)/`
重写调色板生成器	`scripts/generate-palette.mjs`

所有运行时 CSS 变量都被编译进单一文件 packages/design/tokens/styles.css——但该文件是 generated 产物(其文件头本身也这么写)，每次 token 构建都会被覆盖。唯一真实来源是位于 packages/design/design-tokens/tokens/*.json 的 DTCG token JSON；在那里改动，然后运行 Style Dictionary 构建，让 sync-styles.mjs 重新生成 styles.css。任何地方都不要硬编码十六进制值。

/* packages/design/tokens/styles.css — 摘录 */
:root {
  --brand-primary:   var(--blue-9);     /* #0033FE */
  --brand-accent:    var(--cyan-9);     /* #0BF1C3 */
  --brand-gradient:  135deg, var(--blue-9) 0%, var(--cyan-9) 100%;

  --neutral-1:  #ffffff;
  --neutral-12: #0a0a0a;
}

打开 Storybook 的 Design Tokens 版块，可在明暗两种模式下查看每个 token 的实时视觉参考：pnpm --filter @nebutra/storybook dev → http://localhost:6006

可定制的内容

品牌与主题

仪表板页面

引导流程

组件库

架构