@bm-fe/design-tokens
v1.0.1-beta.0
Published
BitMart Web 体系的设计 Token 单一事实源
Downloads
55
Readme
@bm-fe/design-tokens
BitMart Web 体系的 Design Token 单一事实源（Single Source of Truth）
项目定位
@bm-fe/design-tokens 是 BitMart 前端体系的设计 Token 管理中心，负责：
- 统一管理设计变量（颜色、字体、间距、圆角、阴影等）
- 作为 UI 设计 → 工程实现 的唯一中间层
- 为多技术栈输出可直接消费的产物
- 保证 Token 的可版本化、可回滚、可审计
在线预览
访问 Design System Playground 查看：
- Design Tokens 预览 - 查看所有 Token 及其值
- 使用指南 - 完整的集成和使用说明
- Vue2 组件预览 - 组件样式展示
安装
# npm
npm install @bm-fe/design-tokens
# yarn
yarn add @bm-fe/design-tokens
# pnpm
pnpm add @bm-fe/design-tokens快速开始
Nuxt 2 / Vue 2
1. 配置 Tailwind Preset：
// tailwind.config.js
const legacyPreset = require('@bm-fe/design-tokens/presets/tailwind/legacy');
module.exports = {
presets: [legacyPreset],
};2. 使用 Element UI 主题：
// main.less
@import '~@bm-fe/design-tokens/dist/less/variables.less';3. 使用：
<template>
<div class="page">
<el-button type="primary">主要按钮</el-button>
</div>
</template>
<style scoped>
.page {
background-color: var(--color-bm-bg-page);
color: var(--color-bm-text-primary);
}
</style>API 参考
产物列表
| 产物路径 | 格式 | 使用场景 |
| --- | --- | --- |
| dist/css/variables.css | CSS Variables | 所有现代浏览器 |
| dist/js/tokens.js | ES Module | JavaScript/TypeScript 项目 |
| dist/js/tokens.d.ts | TypeScript 定义 | TypeScript 类型支持 |
| dist/json/tokens.json | JSON | 工具集成 |
| dist/less/variables.less | Less 变量 | Element UI 主题 |
| dist/scss/variables.scss | SCSS 变量 | SCSS 项目 |
| dist/themes/light/variables.css | CSS | 亮色主题 |
| dist/themes/dark/variables.css | CSS | 暗色主题 |
Tailwind Presets
| Preset | 路径 | 适用场景 |
| --- | --- | --- |
| Legacy | presets/tailwind/legacy | Nuxt 2, Vue 2 |
| Modern | presets/tailwind/modern | Nuxt 3, Vue 3, Next.js, React（即将支持） |
使用方式
CSS Variables：
.my-component {
color: var(--color-bm-text-primary);
background-color: var(--color-bm-bg-page);
border: 1px solid var(--color-bm-border-default);
}Tailwind CSS：
<div class="text-bm-text-primary bg-bm-bg-page border border-bm-border-default">
内容
</div>JavaScript/TypeScript：
import * as tokens from '@bm-fe/design-tokens/dist/js/tokens.js';
console.log(tokens.colorBmTextPrimary); // "#171717"
console.log(tokens.colorBmBgPage); // "#ffffff"Token 架构
分层设计
Primitive Token（基础层）
↓
Semantic Token（语义层）
↓
Component Alias（组件层，可选）示例：
{
"color": {
"cyan": {
"500": "#00B8D4" // Primitive - 基础色值
},
"bm": {
"function": {
"cex-brand": "{color.cyan.500}" // Semantic - 语义化
}
}
}
}使用规则
| 规则 | 说明 |
| --- | --- |
| 组件中只能使用 Semantic Token | 如 --color-bm-text-primary |
| 禁止直接使用 Primitive Token | 如 --color-cyan-500 |
| 禁止硬编码颜色值 | 如 #00B8D4 |
主题切换
方法 1：data-theme 属性
<html data-theme="light"> <!-- 亮色主题 -->
<html data-theme="dark"> <!-- 暗色主题 -->// 切换主题
document.documentElement.setAttribute('data-theme', 'dark');方法 2：导入不同主题文件
// 亮色主题
import '@bm-fe/design-tokens/dist/themes/light/variables.css';
// 暗色主题
import '@bm-fe/design-tokens/dist/themes/dark/variables.css';Vue 2 示例
<template>
<button @click="toggleTheme">
切换到 {{ theme === 'light' ? '暗色' : '亮色' }} 主题
</button>
</template>
<script>
export default {
data() {
return {
theme: 'light'
}
},
methods: {
toggleTheme() {
this.theme = this.theme === 'light' ? 'dark' : 'light';
document.documentElement.setAttribute('data-theme', this.theme);
}
}
}
</script>常用 Token 速查
文本颜色
| Token | 用途 |
| --- | --- |
| --color-bm-text-primary | 主标题、正文 |
| --color-bm-text-secondary | 次要文字 |
| --color-bm-text-tertiary | 提示文字、占位符 |
| --color-bm-text-button | 按钮文字 |
背景颜色
| Token | 用途 |
| --- | --- |
| --color-bm-bg-page | 页面背景 |
| --color-bm-bg-dialog | 弹窗、卡片背景 |
| --color-bm-bg-input-page | 输入框背景（页面上） |
| --color-bm-bg-input-overlay | 输入框背景（浮层上） |
| --color-bm-bg-mask | 遮罩层背景 |
功能色
| Token | 用途 |
| --- | --- |
| --color-bm-function-cex-brand | CEX 品牌色（青色） |
| --color-bm-function-cex-buy | 买入/上涨（绿色） |
| --color-bm-function-cex-sell | 卖出/下跌（红色） |
| --color-bm-function-cex-warning | 警告（黄色） |
最佳实践
推荐做法
<template>
<!-- 使用语义化 Token -->
<button class="bg-bm-function-cex-brand text-bm-text-button">
提交
</button>
<!-- 使用 CSS Variable -->
<div :style="{ color: 'var(--color-bm-text-primary)' }">
动态文本
</div>
</template>不推荐做法
<template>
<!-- 不要使用硬编码颜色 -->
<button style="background-color: #00B8D4; color: white;">
提交
</button>
<!-- 不要使用 Primitive Token -->
<div class="bg-cyan-500">
内容
</div>
</template>Token 命名规范
格式：{category}-{concept}-{variant}-{state}
color-bm-text-primary ✅ 正确
color-bm-bg-surface-hover ✅ 正确
button-bg-color ❌ 包含组件名
headerBgColor ❌ 不是 kebab-case常见问题
Q: Token 没有生效？
检查以下几点：
- 确保已安装依赖：
npm install @bm-fe/design-tokens - 确保已引入 CSS：
import '@bm-fe/design-tokens/dist/css/variables.css' - 确保 Tailwind 配置了 preset
Q: 如何自定义 Token？
在项目中覆盖 CSS Variables：
:root {
--color-bm-function-cex-brand: #your-color;
}Q: 主题切换后颜色没变化？
确保在 HTML 根元素上设置了 data-theme 属性：
document.documentElement.setAttribute('data-theme', 'dark');Q: TypeScript 类型提示不工作？
确保 tsconfig.json 中包含了类型定义：
{
"compilerOptions": {
"types": ["@bm-fe/design-tokens"]
}
}项目结构
design-tokens/
├─ tokens/ # Token 源数据（唯一事实源）
│ ├─ primitive/ # 基础 Token（颜色、间距、字体等）
│ ├─ semantic/ # 语义 Token
│ └─ themes/ # 主题定义（light/dark）
│
├─ presets/ # 技术栈 Preset
│ └─ tailwind/
│ ├─ legacy.ts # Nuxt 2 / Vue 2
│ └─ modern.ts # Nuxt 3 / Next.js
│
├─ dist/ # 构建产物（npm 发布内容）
│ ├─ css/ # CSS Variables
│ ├─ js/ # JavaScript/TypeScript
│ ├─ json/ # JSON Token
│ ├─ less/ # Less 变量
│ ├─ scss/ # SCSS 变量
│ └─ themes/ # 主题产物
│
├─ scripts/ # 构建和校验脚本
└─ docs/ # 文档支持的技术栈
| 技术栈 | 支持方式 | 状态 | | --- | --- | --- | | Nuxt 2 / Vue 2 | Tailwind Legacy + Element UI | 已支持 | | Nuxt 3 / Vue 3 | Tailwind Modern + Element Plus | 即将支持 | | Next.js / React | Tailwind Modern + CSS Variables | 即将支持 |
开发
安装依赖
pnpm install校验 Token
pnpm run validate构建
pnpm run build发布
npm version patch|minor|major
git push --tags变更规则
- Patch: 修正值，不改变语义
- Minor: 新增 Token
- Major: 删除或改变 Token 语义
文档
相关资源
License
ISC © BitMart FE Team