@cimom/vben-core-design

该包提供了 Vue Vben Admin 项目的核心设计系统，包括设计令牌（Design Tokens）、CSS 变量、BEM 规范工具和全局样式。它是整个项目样式系统的基础，确保了界面风格的一致性和可定制性。

安装

pnpm add @cimom/vben-core-design

基本使用

引入全局样式

在应用的入口文件中引入全局样式：

// main.ts
import '@cimom/vben-core-design';

使用 BEM 规范工具

在 SCSS 文件中使用 BEM 规范工具：

// 引入 BEM 工具
@import '@cimom/vben-core-design/bem';

// 使用 BEM 工具创建组件样式
@include b(button) {
  display: inline-flex;
  align-items: center;
  justify-content: center;
  font-weight: 500;
  border-radius: var(--border-radius-base);

  // 元素
  @include e(icon) {
    margin-right: 8px;
  }

  // 修饰符
  @include m(primary) {
    background-color: var(--primary-color);
    color: #fff;
  }

  @include m(small) {
    padding: 4px 12px;
    font-size: 14px;
  }

  @include m(large) {
    padding: 12px 20px;
    font-size: 16px;
  }
}

使用设计常量

在 SCSS 文件中使用设计常量：

// 引入设计常量
@import '@cimom/vben-core-design/constants';

.custom-element {
  // 使用预定义的断点
  @media (min-width: $screen-sm) {
    width: 80%;
  }

  @media (min-width: $screen-md) {
    width: 60%;
  }

  @media (min-width: $screen-lg) {
    width: 40%;
  }
}

使用 CSS 变量

在组件中使用 CSS 变量：

<template>
  <div class="custom-component">
    <h2 class="title">标题</h2>
    <p class="content">内容</p>
  </div>
</template>

<style scoped>
.custom-component {
  padding: var(--padding-md);
  background-color: var(--background-color);
  border-radius: var(--border-radius-base);
  box-shadow: var(--box-shadow-base);
}

.title {
  color: var(--text-color);
  font-size: var(--font-size-lg);
  margin-bottom: var(--margin-sm);
}

.content {
  color: var(--text-color-secondary);
  font-size: var(--font-size-base);
}
</style>

包含内容

设计令牌（Design Tokens）

设计令牌是设计系统的基础变量，包括：

• 颜色系统
• 字体系统
• 间距系统
• 边框系统
• 阴影系统
• 动画系统

这些令牌被转换为 CSS 变量，可以在整个项目中使用。

全局样式

包含以下全局样式：

• 基础样式重置
• 通用工具类
• 过渡动画
• NProgress 样式
• UI 组件基础样式

BEM 规范工具

提供了一套基于 SCSS 的 BEM（Block, Element, Modifier）规范工具，用于创建可维护的 CSS 代码。

CSS 变量

所有设计令牌都被转换为 CSS 变量，可以在项目中使用。

CSS 变量参考

颜色变量

:root {
  /* 主题色 */
  --primary-color: #1890ff;
  --primary-color-hover: #40a9ff;
  --primary-color-active: #096dd9;
  --primary-color-outline: rgba(24, 144, 255, 0.2);

  /* 成功色 */
  --success-color: #52c41a;
  --success-color-hover: #73d13d;
  --success-color-active: #389e0d;
  --success-color-outline: rgba(82, 196, 26, 0.2);

  /* 警告色 */
  --warning-color: #faad14;
  --warning-color-hover: #ffc53d;
  --warning-color-active: #d48806;
  --warning-color-outline: rgba(250, 173, 20, 0.2);

  /* 错误色 */
  --error-color: #ff4d4f;
  --error-color-hover: #ff7875;
  --error-color-active: #d9363e;
  --error-color-outline: rgba(255, 77, 79, 0.2);

  /* 文本色 */
  --text-color: rgba(0, 0, 0, 0.85);
  --text-color-secondary: rgba(0, 0, 0, 0.65);
  --text-color-disabled: rgba(0, 0, 0, 0.25);

  /* 背景色 */
  --background-color: #fff;
  --background-color-light: #f5f5f5;
  --background-color-dark: #f0f2f5;

  /* 边框色 */
  --border-color: #d9d9d9;
  --border-color-split: #f0f0f0;
}

/* 暗黑模式 */
.dark {
  --primary-color: #177ddc;
  --primary-color-hover: #1890ff;
  --primary-color-active: #0050b3;

  --text-color: rgba(255, 255, 255, 0.85);
  --text-color-secondary: rgba(255, 255, 255, 0.65);
  --text-color-disabled: rgba(255, 255, 255, 0.3);

  --background-color: #141414;
  --background-color-light: #1f1f1f;
  --background-color-dark: #000;

  --border-color: #434343;
  --border-color-split: #303030;
}

字体变量

:root {
  /* 字体系列 */
  --font-family:
    -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, 'Helvetica Neue',
    Arial, 'Noto Sans', sans-serif, 'Apple Color Emoji', 'Segoe UI Emoji',
    'Segoe UI Symbol', 'Noto Color Emoji';

  /* 字体大小 */
  --font-size-base: 14px;
  --font-size-sm: 12px;
  --font-size-lg: 16px;
  --font-size-xl: 20px;
  --font-size-xxl: 24px;

  /* 行高 */
  --line-height-base: 1.5;
  --line-height-sm: 1.2;
  --line-height-lg: 1.8;
}

间距变量

:root {
  /* 间距 */
  --spacing-unit: 4px;
  --spacing-xs: calc(var(--spacing-unit) * 1); /* 4px */
  --spacing-sm: calc(var(--spacing-unit) * 2); /* 8px */
  --spacing-md: calc(var(--spacing-unit) * 4); /* 16px */
  --spacing-lg: calc(var(--spacing-unit) * 6); /* 24px */
  --spacing-xl: calc(var(--spacing-unit) * 8); /* 32px */

  /* 内边距 */
  --padding-xs: var(--spacing-xs);
  --padding-sm: var(--spacing-sm);
  --padding-md: var(--spacing-md);
  --padding-lg: var(--spacing-lg);
  --padding-xl: var(--spacing-xl);

  /* 外边距 */
  --margin-xs: var(--spacing-xs);
  --margin-sm: var(--spacing-sm);
  --margin-md: var(--spacing-md);
  --margin-lg: var(--spacing-lg);
  --margin-xl: var(--spacing-xl);
}

边框变量

:root {
  /* 边框 */
  --border-width-base: 1px;
  --border-style-base: solid;
  --border-color-base: var(--border-color);
  --border-base: var(--border-width-base) var(--border-style-base)
    var(--border-color-base);

  /* 边框圆角 */
  --border-radius-base: 2px;
  --border-radius-sm: 2px;
  --border-radius-md: 4px;
  --border-radius-lg: 8px;
  --border-radius-circle: 50%;
}

阴影变量

:root {
  /* 阴影 */
  --box-shadow-base: 0 2px 8px rgba(0, 0, 0, 0.15);
  --box-shadow-sm: 0 1px 4px rgba(0, 0, 0, 0.1);
  --box-shadow-lg: 0 4px 12px rgba(0, 0, 0, 0.2);
  --box-shadow-card:
    0 1px 2px -2px rgba(0, 0, 0, 0.16), 0 3px 6px 0 rgba(0, 0, 0, 0.12),
    0 5px 12px 4px rgba(0, 0, 0, 0.09);
}

动画变量

:root {
  /* 动画 */
  --animation-duration-slow: 0.3s;
  --animation-duration-base: 0.2s;
  --animation-duration-fast: 0.1s;

  /* 过渡 */
  --transition-base: all var(--animation-duration-base)
    cubic-bezier(0.645, 0.045, 0.355, 1);
  --transition-fade: opacity var(--animation-duration-base)
    cubic-bezier(0.645, 0.045, 0.355, 1);
  --transition-slide: transform var(--animation-duration-base)
    cubic-bezier(0.645, 0.045, 0.355, 1);
}

BEM 规范工具参考

块（Block）

@include b(button) {
  // 样式
}

// 编译为
.vben-button {
  // 样式
}

元素（Element）

@include b(button) {
  @include e(icon) {
    // 样式
  }
}

// 编译为
.vben-button__icon {
  // 样式
}

修饰符（Modifier）

@include b(button) {
  @include m(primary) {
    // 样式
  }
}

// 编译为
.vben-button--primary {
  // 样式
}

状态（State）

@include b(button) {
  @include when(disabled) {
    // 样式
  }
}

// 编译为
.vben-button.is-disabled {
  // 样式
}

高级用法

自定义主题

可以通过覆盖 CSS 变量来自定义主题：

:root {
  --primary-color: #722ed1; /* 紫色主题 */
  --success-color: #13c2c2; /* 青色成功色 */
  --warning-color: #fa8c16; /* 橙色警告色 */
  --error-color: #eb2f96; /* 粉色错误色 */
}

响应式设计

结合 CSS 变量和媒体查询实现响应式设计：

.container {
  padding: var(--padding-md);

  @media (max-width: 768px) {
    padding: var(--padding-sm);
  }

  @media (max-width: 480px) {
    padding: var(--padding-xs);
  }
}

主题切换

实现亮色/暗色主题切换：

// 切换主题
function toggleTheme(theme: 'light' | 'dark') {
  const htmlEl = document.documentElement;

  if (theme === 'dark') {
    htmlEl.classList.add('dark');
  } else {
    htmlEl.classList.remove('dark');
  }
}

注意事项

1. 该包主要提供设计系统的基础，不包含具体的组件实现。
2. 使用 BEM 规范工具时，默认的命名空间是 vben-，可以通过配置修改。
3. 在使用 CSS 变量时，建议始终提供回退值，以确保在不支持 CSS 变量的浏览器中也能正常显示。

与其他包的关系

• @cimom/vben-styles: 基于此包构建，提供了更高级别的样式封装。
• @cimom/vben-core-ui-kit: 使用此包的设计系统构建 UI 组件。
• @cimom/vben-preferences: 可以通过偏好设置来动态切换主题。

常见问题

CSS 变量不生效

确保你的目标浏览器支持 CSS 变量，或者使用 PostCSS 插件进行兼容性处理。

样式冲突

如果遇到样式冲突，可以通过以下方式解决：

1. 使用 BEM 规范确保类名唯一性
2. 使用 CSS Modules 或 Scoped CSS 隔离样式
3. 调整样式优先级

自定义命名空间

如果需要自定义 BEM 命名空间，可以在引入 BEM 工具之前设置变量：

$namespace: 'custom-'; // 默认是 'vben-'
@import '@cimom/vben-core-design/bem';