CBTIS Design System

快速接入 ​

按项目情况选择一种方式。

方式一：Tailwind CSS v4 项目（推荐） ​

适用于 Vite / Vue / React 等使用 Tailwind CSS v4 的项目，例如 cbtis-homepage-v2、globalcbtis/web。

1. 引入设计系统 ​

设计系统没有发布到 npm，用本地路径或 Git 依赖安装：

bash
pnpm add -D @cbtis/design-system@file:../cbtis-design-system

也可以直接把 src/styles/tokens.css、src/styles/base.css 复制进项目。

2. 引入样式 ​

css
/* src/styles/main.css */
@import 'tailwindcss';
@import '@cbtis/design-system/tokens.css';
@import '@cbtis/design-system/base.css';

/* 使用交互脚本时，让 Tailwind 扫描脚本里动态生成的类名（Toast、上传列表、下拉选项、日历） */
@source '../../node_modules/@cbtis/design-system/src/js';

之后就可以使用 bg-navy、text-muted-foreground、rounded-xl 等工具类。

3. 加载字体 ​

见字体与字号 · 加载字体。

4. 复制组件 ​

打开组件页，点击示例下方的「复制代码」，粘贴到模板中。Vue 项目中把重复的类名封装为组件（例如 v2 的 Button.vue），状态用 v-model / ref 管理。

方式二：不经过构建的页面 ​

适用于静态页、邮件落地页、后台里的独立 HTML。

bash
pnpm install
pnpm build:assets

把 dist/cbtis.css 与 dist/cbtis-ui.js 放到页面旁边：

html
<link rel="stylesheet" href="cbtis.css" />
<script src="cbtis-ui.js" defer></script>

注意

dist/cbtis.css 只包含本仓库示例中用到的类名。在页面里写示例之外的类名不会生效——需要自定义时请使用方式一。

交互脚本 ​

需要交互的组件（对话框、标签页、下拉菜单、下拉选择、日期选择、验证码输入、上传、Toast、移动端菜单、倒计时按钮）由 src/js 提供，零依赖，通过 data-cb-* 属性声明。

引入 ​

js
// ES Module（方式一）
import { init, toast, openDialog } from '@cbtis/design-system/js'
init()

// 直接引入脚本（方式二）：自动初始化，全局对象 window.CbtisUI
CbtisUI.toast.success('已保存')

工作方式 ​

  • 所有组件使用文档级事件委托：init() 调用一次后，之后动态插入的对话框、下拉、上传等都能直接响应
  • 标签页、下拉、多选等需要同步 ARIA 属性的组件，动态插入后调用 init(容器元素) 即可，可重复调用
  • 组件状态变化派发 cb:* 自定义事件（冒泡），业务代码监听即可
组件声明属性事件
对话框data-cb-dialog · data-cb-dialog-open · data-cb-dialog-close原生 close
标签页data-cb-tabscb:tab-change
下拉菜单data-cb-dropdowncb:dropdown-select
下拉选择（单选 / 多选）data-cb-select原生 change · cb:select-change
日期选择data-cb-datepickercb:date-change
日期范围data-cb-daterangecb:daterange-change
验证码输入data-cb-otpcb:otp-change · cb:otp-complete
上传data-cb-uploadcb:upload-add · cb:upload-remove · cb:upload-reject
Toastdata-cb-toast—
提示条data-cb-dismissible · data-cb-dismisscb:dismiss
展开收起（页头）data-cb-disclosure—
输入框data-cb-digits · data-cb-countdowncb:countdown-start

在 Vue 中 ​

Vue 能自己管理的状态（开关、选中项）优先用 Vue 实现，只照搬类名。确实想复用脚本时：

vue
<script setup>
import { onMounted, useTemplateRef } from 'vue'
import { init } from '@cbtis/design-system/js'

const root = useTemplateRef('root')
onMounted(() => init(root.value))
</script>

注意不要让 Vue 与脚本同时控制同一个属性（例如 aria-selected）。

表单类组件（下拉选择、日期、验证码）的值都保存在真实的 <select> / <input> 上，脚本改值时会派发 input 与 change 事件，因此 v-model 直接绑在这些元素上即可；Vue 改值后派发一次 change（或调用 init(el)）让界面同步。

浏览器支持 ​

Chrome / Edge 111+、Safari 16.4+、Firefox 128+（Tailwind CSS v4 的最低要求）。脚本使用 <dialog>、:has()、CSS.escape 等，均在上述版本内。

本地开发 ​

bash
pnpm install
pnpm dev             # 文档站 http://localhost:5173
pnpm build           # 构建 dist/（样式、脚本、独立示例页）与文档站
pnpm icons           # 把 examples 中的 <i data-lucide> 占位符替换为内联 SVG

新增组件：在 examples/<组件名>/ 下写 HTML 片段 → 在 docs/ 下写文档并用 <Demo src="组件名/片段名" /> 引用 → 在 docs/.vitepress/catalog.mjs 登记。