flnxi-Wu/docs/archive/设计系统使用指南.md

设计系统使用指南

快速开始

1. 导入样式工具

import { cardStyles, buttonStyles, inputStyles, navItemStyles, cn } from '@/lib/ui-styles'

2. 使用统一样式

卡片 (Card)

// 标准卡片
<div className={cardStyles.base}>
  <h2>标题</h2>
  <p>内容</p>
</div>

// 带悬停效果的卡片
<div className={cardStyles.hover}>
  <h2>标题</h2>
  <p>内容</p>
</div>

// 大卡片
<div className={cardStyles.large}>
  <h2>标题</h2>
  <p>内容</p>
</div>

按钮 (Button)

// 主要按钮
<button className={buttonStyles.primary}>
  保存
</button>

// 次要按钮
<button className={buttonStyles.secondary}>
  取消
</button>

// 危险操作按钮
<button className={buttonStyles.danger}>
  删除
</button>

// 幽灵按钮（无背景）
<button className={buttonStyles.ghost}>
  更多
</button>

输入框 (Input)

// 标准输入框
<input
  type="text"
  className={inputStyles.base}
  placeholder="请输入..."
/>

// 错误状态输入框
<input
  type="text"
  className={inputStyles.error}
  placeholder="请输入..."
/>

导航项 (Nav Item)

// 基础导航项
<button className={navItemStyles.base}>
  导航项
</button>

// 带悬停效果
<button className={navItemStyles.hover}>
  导航项
</button>

// 激活状态
<button className={navItemStyles.active}>
  导航项
</button>

组合样式

import { cn } from '@/lib/ui-styles'

// 组合多个样式类
<div className={cn(
  cardStyles.base,
  'mt-4',  // 额外的 Tailwind 类
  isActive && 'ring-2 ring-indigo-500'  // 条件样式
)}>
  内容
</div>

迁移现有代码

迁移前

// ❌ 不统一的样式
<div className="rounded-lg border border-gray-200 bg-white shadow-md p-4">
  <button className="px-4 py-2 rounded-md bg-blue-500 text-white">
    按钮
  </button>
</div>

迁移后

// ✅ 使用统一样式
<div className={cardStyles.base}>
  <button className={buttonStyles.primary}>
    按钮
  </button>
</div>

最佳实践

1. 优先使用样式工具

// ✅ 正确
import { cardStyles } from '@/lib/ui-styles'
<div className={cardStyles.base}>

// ❌ 错误（除非有特殊需求）
<div className="rounded-2xl border border-slate-200 bg-white shadow-lg p-6">

2. 使用 cn() 函数组合样式

// ✅ 正确
import { cn, cardStyles } from '@/lib/ui-styles'
<div className={cn(cardStyles.base, 'mt-4', isActive && 'ring-2')}>

// ❌ 错误
<div className={`${cardStyles.base} mt-4 ${isActive ? 'ring-2' : ''}`}>

3. 保持一致性

// ✅ 正确：所有卡片使用相同的样式
<div className={cardStyles.base}>卡片 1</div>
<div className={cardStyles.base}>卡片 2</div>
<div className={cardStyles.base}>卡片 3</div>

// ❌ 错误：每个卡片样式都不同
<div className="rounded-lg shadow-md p-4">卡片 1</div>
<div className="rounded-xl shadow-lg p-6">卡片 2</div>
<div className="rounded-2xl shadow-xl p-8">卡片 3</div>

常见场景

表单

import { cardStyles, inputStyles, buttonStyles, spacingStyles } from '@/lib/ui-styles'

<form className={cn(cardStyles.base, spacingStyles.form)}>
  <div>
    <label className="block text-sm font-medium mb-2">用户名</label>
    <input type="text" className={inputStyles.base} />
  </div>
  <div>
    <label className="block text-sm font-medium mb-2">密码</label>
    <input type="password" className={inputStyles.base} />
  </div>
  <div className="flex gap-4">
    <button type="submit" className={buttonStyles.primary}>
      提交
    </button>
    <button type="button" className={buttonStyles.secondary}>
      取消
    </button>
  </div>
</form>

导航菜单

import { navItemStyles } from '@/lib/ui-styles'

<nav className="space-y-2">
  {items.map((item) => (
    <button
      key={item.id}
      className={item.active ? navItemStyles.active : navItemStyles.hover}
    >
      {item.label}
    </button>
  ))}
</nav>

卡片列表

import { cardStyles, spacingStyles } from '@/lib/ui-styles'

<div className={cn('grid gap-6', spacingStyles.section)}>
  {items.map((item) => (
    <div key={item.id} className={cardStyles.hover}>
      <h3>{item.title}</h3>
      <p>{item.description}</p>
    </div>
  ))}
</div>

扩展样式

如果需要添加新的样式，请在 lib/ui-styles.ts 中添加：

// lib/ui-styles.ts
export const customStyles = {
  // 你的自定义样式
  special: 'rounded-2xl bg-gradient-to-r from-indigo-500 to-purple-500 ...',
} as const

检查清单

在提交代码前，请检查：

• 使用了统一的样式工具类
• 圆角、阴影、间距符合规范
• 支持深色模式
• 添加了过渡动画
• 响应式设计正确