MBE 设计系统快速指南

版本: 3.0.0 | 更新日期: 2026-02-01

概述

MBE 设计系统由三个核心包组成:

快速安装

在现有项目中使用

# 使用 pnpm（推荐）
pnpm add @mbe/design-tokens @mbe/ui @mbe/tailwind-config

# 或使用 npm
npm install @mbe/design-tokens @mbe/ui @mbe/tailwind-config

配置 Tailwind CSS

在 tailwind.config.ts 中:

import type { Config } from 'tailwindcss';
import mbeConfig from '@mbe/tailwind-config';

const config: Config = {
  presets: [mbeConfig],
  content: [
    './app/**/*.{js,ts,jsx,tsx}',
    './components/**/*.{js,ts,jsx,tsx}',
    './node_modules/@mbe/ui/**/*.{js,ts,jsx,tsx}',
  ],
};

export default config;

导入 CSS 变量

在全局样式文件中:

/* globals.css */
@import '@mbe/design-tokens/dist/tokens.css';
@tailwind base;
@tailwind components;
@tailwind utilities;

核心组件

GlassCard - 毛玻璃卡片

import { GlassCard } from '@mbe/ui';

// 基础用法
<GlassCard>
  <h2>标题</h2>
  <p>内容</p>
</GlassCard>

// 带变体和效果
<GlassCard 
  variant="primary"  // 'default' | 'primary' | 'success' | 'warning' | 'error'
  hover              // 启用悬停效果
  glow               // 启用发光效果
  className="p-6"
>
  <h2>高级卡片</h2>
</GlassCard>

// 可点击卡片
<GlassCard hover onClick={() => handleClick()}>
  <span>点击我</span>
</GlassCard>

Button - 按钮

import { Button } from '@mbe/ui';

// 变体
<Button variant="primary">主要按钮</Button>
<Button variant="secondary">次要按钮</Button>
<Button variant="outline">轮廓按钮</Button>
<Button variant="ghost">幽灵按钮</Button>
<Button variant="danger">危险按钮</Button>

// 尺寸
<Button size="sm">小按钮</Button>
<Button size="md">中等按钮</Button>
<Button size="lg">大按钮</Button>

// 状态
<Button loading>加载中</Button>
<Button disabled>禁用</Button>

// 图标
import { Plus } from 'lucide-react';
<Button icon={<Plus />}>新增</Button>

Badge - 徽章

import { Badge } from '@mbe/ui';

<Badge variant="default">默认</Badge>
<Badge variant="primary">主要</Badge>
<Badge variant="success">成功</Badge>
<Badge variant="warning">警告</Badge>
<Badge variant="error">错误</Badge>
<Badge variant="info">信息</Badge>

Input - 输入框

import { Input } from '@mbe/ui';

// 基础用法
<Input 
  placeholder="请输入..."
  value={value}
  onChange={(e) => setValue(e.target.value)}
/>

// 带图标
import { Search } from 'lucide-react';
<Input 
  icon={<Search />}
  placeholder="搜索..."
/>

// 状态
<Input error errorMessage="输入有误" />
<Input disabled />

Skeleton - 骨架屏

import { Skeleton } from '@mbe/ui';

// 基础骨架
<Skeleton className="h-4 w-full" />

// 圆形骨架（头像）
<Skeleton className="h-12 w-12 rounded-full" />

// 组合使用
<div className="space-y-2">
  <Skeleton className="h-4 w-3/4" />
  <Skeleton className="h-4 w-1/2" />
  <Skeleton className="h-4 w-full" />
</div>

useToast - 提示通知

import { useToast, ToastProvider } from '@mbe/ui';

// 1. 在应用根组件添加 Provider
function App() {
  return (
    <ToastProvider>
      <YourApp />
    </ToastProvider>
  );
}

// 2. 在组件中使用
function MyComponent() {
  const { toast } = useToast();

  const handleSuccess = () => {
    toast.success('操作成功！');
  };

  const handleError = () => {
    toast.error('操作失败，请重试');
  };

  const handleWarning = () => {
    toast.warning('请注意检查输入');
  };

  const handleInfo = () => {
    toast.info('这是一条提示信息');
  };

  return (
    <div>
      <Button onClick={handleSuccess}>成功提示</Button>
      <Button onClick={handleError}>错误提示</Button>
    </div>
  );
}

设计令牌

颜色系统

/* 主色调 */
--color-primary-50: #f0f9ff;
--color-primary-500: #3b82f6;
--color-primary-900: #1e3a8a;

/* 成功色 */
--color-success-500: #22c55e;

/* 警告色 */
--color-warning-500: #f59e0b;

/* 错误色 */
--color-error-500: #ef4444;

/* 中性色 */
--color-gray-50: #f9fafb;
--color-gray-900: #111827;

在 Tailwind 中使用

// 使用设计令牌颜色
<div className="bg-primary-500 text-white">主色背景</div>
<div className="text-success-500">成功文字</div>
<div className="border-warning-500">警告边框</div>

在 JavaScript 中使用

import { colors, spacing, typography } from '@mbe/design-tokens';

// 访问颜色值
console.log(colors.primary[500]); // #3b82f6

// 访问间距
console.log(spacing[4]); // 1rem

最佳实践

1. 一致性原则

始终使用设计系统组件，而不是自定义样式:

// ✅ 推荐
<GlassCard variant="primary">
  <Badge variant="success">Active</Badge>
</GlassCard>

// ❌ 避免
<div className="custom-card-class">
  <span className="custom-badge">Active</span>
</div>

2. 组合使用

组件可以灵活组合:

<GlassCard hover glow className="p-6">
  <div className="flex items-center justify-between mb-4">
    <h3 className="text-lg font-semibold">课程标题</h3>
    <Badge variant="primary">进行中</Badge>
  </div>
  <p className="text-gray-400 mb-4">课程描述...</p>
  <div className="flex gap-2">
    <Button variant="primary" size="sm">继续学习</Button>
    <Button variant="ghost" size="sm">查看详情</Button>
  </div>
</GlassCard>

3. 响应式设计

利用 Tailwind 响应式类:

<GlassCard className="p-4 md:p-6 lg:p-8">
  <div className="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-4">
    {/* 响应式网格 */}
  </div>
</GlassCard>

4. 暗色主题

设计系统默认支持暗色主题:

// 组件自动适应暗色主题
<GlassCard>
  {/* 内容在暗色背景下自动调整 */}
</GlassCard>

从旧组件迁移

替换 shadcn/ui Card

// 旧代码
import { Card, CardHeader, CardContent } from '@/components/ui/card';
<Card>
  <CardHeader>标题</CardHeader>
  <CardContent>内容</CardContent>
</Card>

// 新代码
import { GlassCard } from '@mbe/ui';
<GlassCard>
  <h3 className="text-lg font-semibold mb-4">标题</h3>
  <div>内容</div>
</GlassCard>

替换 shadcn/ui Button

// 旧代码
import { Button } from '@/components/ui/button';
<Button variant="default">点击</Button>

// 新代码
import { Button } from '@mbe/ui';
<Button variant="primary">点击</Button>

故障排除

样式不生效

1. 确保已导入 CSS 变量:

   @import '@mbe/design-tokens/dist/tokens.css';
   

2. 确保 Tailwind 配置正确:

   content: [
     './node_modules/@mbe/ui/**/*.{js,ts,jsx,tsx}',
   ],
   

3. 重启开发服务器:

   pnpm dev
   

TypeScript 类型错误

确保安装了正确版本的依赖:

pnpm add @mbe/ui@latest

相关文档

• UI 组件替换指南
• 完整部署指南
• 系统架构

设计系统快速指南 | MBE v3.0.0 | 2026-02-01