afilmory/apps/landing/DESIGN_SYSTEM.md

设计系统使用指南

🎨 颜色系统

Pastel Palette Token（自动适配暗色模式）

// ✅ 推荐：使用语义化 token
bg-background           // 主背景
bg-background-secondary // 次级背景
bg-fill                 // 填充色
bg-fill-secondary       // 次级填充
bg-material-medium      // 材质：中等透明度
bg-accent               // 强调色

text-text               // 主文本
text-text-secondary     // 次级文本
text-text-tertiary      // 三级文本（最淡）

border-border           // 边框色

自定义 Accent 混合色

// 10% ~ 80% 的 accent 混合色
bg-accent-10   // 极淡强调色背景
bg-accent-20
bg-accent-30
...
bg-accent-80   // 强烈强调色

❌ 避免硬编码

// ❌ 不要这样
className="bg-blue-500 text-white shadow-xl"

// ✅ 应该这样
className="bg-accent text-background shadow-medium"

📐 阴影系统

从 lib/design-tokens.ts 导入统一阴影：

import { shadows } from '~/lib/design-tokens'

// 5 个标准层级
shadows.subtle  // 轻微阴影 - 用于悬停效果
shadows.light   // 轻度阴影 - 普通卡片
shadows.medium  // 中度阴影 - 浮动面板
shadows.strong  // 强阴影   - 模态框
shadows.heavy   // 重阴影   - 全屏/Hero

使用示例

// 普通卡片
<div className={clsxm('bg-background', shadows.light)}>...</div>

// 浮动面板
<div className={clsxm('bg-background/80 backdrop-blur-xl', shadows.medium)}>
  ...
</div>

// Hero 区块
<div className={shadows.heavy}>...</div>

🔲 圆角系统

import { radius } from '~/lib/design-tokens'

radius.sm    // rounded-xl (12px)   - 小元素
radius.md    // rounded-2xl (16px)  - 按钮、输入框
radius.lg    // rounded-3xl (24px)  - 卡片
radius.xl    // rounded-[28px]      - 大卡片
radius['2xl'] // rounded-[32px]     - Section 容器
radius['3xl'] // rounded-[40px]     - Hero 级别

💨 模糊度系统

import { blur } from '~/lib/design-tokens'

blur.sm     // backdrop-blur-sm (4px)
blur.md     // backdrop-blur-md (12px)
blur.lg     // backdrop-blur-lg (16px)
blur.xl     // backdrop-blur-xl (24px)
blur['2xl'] // backdrop-blur-2xl (40px)
blur['3xl'] // backdrop-blur-[60px]

🎴 Glassmorphic 卡片

预设变体

import { glassCard } from '~/lib/design-tokens'

// 4 种预设风格
glassCard.default   // bg-background/60 + border + backdrop-blur-xl
glassCard.elevated  // bg-background/80 + backdrop-blur-2xl (更实)
glassCard.floating  // bg-background/50 + backdrop-blur-[30px] (更透)
glassCard.gradient  // border-white/15 + backdrop-blur-2xl (配合渐变)

组合使用

import { glassCard, radius, shadows } from '~/lib/design-tokens'

<div className={clsxm(
  glassCard.floating,
  radius.lg,
  shadows.medium,
  'p-6'
)}>
  内容
</div>

📏 Typography

import { typography } from '~/lib/design-tokens'

typography.hero   // text-4xl sm:text-5xl lg:text-6xl font-semibold
typography.h1     // text-3xl lg:text-4xl font-semibold
typography.h2     // text-2xl lg:text-3xl font-semibold
typography.h3     // text-xl lg:text-2xl font-semibold
typography.body   // text-base
typography.small  // text-sm
typography.tiny   // text-xs
typography.label  // text-xs tracking-[0.3em] uppercase font-semibold

使用示例

<h1 className={clsxm(typography.hero, 'text-white')}>
  标题文字
</h1>

<p className={clsxm(typography.label, 'text-text-secondary')}>
  Section Label
</p>

📦 间距系统

import { spacing } from '~/lib/design-tokens'

spacing.section  // space-y-20  - Section 之间
spacing.content  // space-y-12  - 内容组之间
spacing.group    // space-y-6   - 组内元素
spacing.tight    // space-y-3   - 紧密元素

🎯 图标容器

import { iconBox } from '~/lib/design-tokens'

// 3 种尺寸，自带圆角、背景、居中
iconBox.sm  // size-8 + rounded-xl
iconBox.md  // size-10 + rounded-2xl
iconBox.lg  // size-12 + rounded-2xl

// 使用示例
<span className={iconBox.lg}>
  <i className="i-lucide-sparkles size-5" />
</span>

⚡ 过渡动画

import { transition } from '~/lib/design-tokens'

transition.fast    // duration-200
transition.normal  // duration-300
transition.slow    // duration-500

// 使用示例
<button className={clsxm('hover:bg-accent/90', transition.normal)}>
  按钮
</button>

🎭 Hover 效果

import { hover } from '~/lib/design-tokens'

hover.card  // border 和 bg 变化
hover.lift  // 轻微放大 + 阴影加强
hover.glow  // 发光效果

🧩 组件使用模式

标准卡片模式

import { Card } from '~/components/landing'
import { shadows } from '~/lib/design-tokens'

<Card variant="floating" size="lg" hoverable>
  <div className="flex items-center gap-3">
    {/* 内容 */}
  </div>
</Card>

Section 标准布局

import { spacing, typography } from '~/lib/design-tokens'

<section className={spacing.content}>
  <header className={spacing.tight}>
    <p className={clsxm(typography.label, 'text-text-secondary')}>
      Section Label
    </p>
    <h2 className={clsxm(typography.h1, 'text-white')}>
      主标题
    </h2>
    <p className="text-base text-text-secondary">
      描述文字
    </p>
  </header>

  {/* Section 内容 */}
</section>

🌈 渐变组合

// Hero 渐变背景
<div className="bg-linear-to-br from-accent/40 via-purple-600/40 to-slate-900/70">
  ...
</div>

// 文字渐变
<span className="bg-linear-to-r from-sky-300 via-accent to-purple-400 bg-clip-text text-transparent">
  渐变文字
</span>

📋 完整示例

功能卡片

import { Card } from '~/components/landing'
import { shadows, radius, spacing, typography, iconBox } from '~/lib/design-tokens'
import { clsxm } from '~/lib/helper'

const FeatureCard = () => (
  <Card variant="floating" size="lg" className={spacing.group}>
    <div className="flex items-center gap-3">
      <span className={clsxm(iconBox.lg, 'bg-accent/15 text-accent')}>
        <i className="i-lucide-cpu size-5" />
      </span>
      <div>
        <p className={clsxm(typography.h3, 'text-white')}>
          性能与体验
        </p>
        <p className={clsxm(typography.small, 'text-text-secondary')}>
          描述文字
        </p>
      </div>
    </div>
    <ul className={clsxm(spacing.tight, typography.small, 'text-text-secondary')}>
      <li className="flex items-start gap-2">
        <i className="i-lucide-check size-4 text-accent" />
        <span>功能点 1</span>
      </li>
    </ul>
  </Card>
)

🎨 颜色使用场景指南

场景	推荐颜色	示例
页面背景	bg-background	<div className="bg-background">
卡片背景	bg-background/60 ~ bg-background/80	玻璃态透明度
按钮主色	bg-accent text-background	CTA 按钮
按钮次级	bg-fill text-text	次要操作
强调文字	text-accent	重要信息
边框	border-border 或 border-white/10	分隔线
悬浮蒙层	bg-background/50 backdrop-blur-xl	Modal 背景

🚫 反模式（避免）

// ❌ 硬编码阴影
className="shadow-[0_20px_60px_rgba(0,0,0,0.35)]"

// ✅ 使用 token
className={shadows.heavy}

// ❌ 重复的圆角定义
className="rounded-[32px]"
className="rounded-[32px]"

// ✅ 统一使用
className={radius['2xl']}

// ❌ 分散的透明度值
className="bg-white/5"
className="bg-white/8"
className="bg-white/12"

// ✅ 语义化背景
className={glassCard.floating}

📚 参考资源

• Pastel Palette: 颜色系统基础
• Tailwind CSS v4: 工具类参考
• Glassmorphic Design: UI 设计理念
• Motion/Framer Motion: 动画系统

---

最后更新: 2025-11-11
维护者: Design System Team