amicro-design-system

Amicro 设计系统与组件指南

本指南定义了 Amicro 仓库的权威设计令牌、组件架构、样式规则和布局标准。所有新功能、微交互、卡片、加载器和页面过渡必须严格遵循这些规则，以保持完美的视觉和谐与品质。

---

1. 核心设计令牌与调色板

字体系列

• 字体：'Outfit', sans-serif（在 index.css 的 @theme { --font-sans: 'Outfit', sans-serif; } 中配置）。
• 标题：使用 font-medium 或 font-semibold，并采用紧凑字距（tracking-[-0.01em] 或 tracking-[-0.019em]）。

调色板（深色与浅色主题）

令牌	深色模式（.dark）	浅色模式
页面背景	#121212	#f8f9fa
卡片容器背景	#161616	bg-white
卡片容器边框	border-white/[0.07] hover:border-white/[0.18]	border-neutral-200/80 hover:border-neutral-300
卡片容器阴影	shadow-[0_4px_24px_-4px_rgba(0,0,0,0.5),inset_0_1px_0_0_rgba(255,255,255,0.06)]	shadow-[0_2px_8px_rgba(0,0,0,0.04),0_12px_28px_-6px_rgba(0,0,0,0.05)]
预览舞台画布	#0d0d0d + shadow-[inset_0_2px_6px_rgba(0,0,0,0.5)]	#f5f6f8 + shadow-[inset_0_1px_3px_rgba(0,0,0,0.03)]
主文本	#ffffff / #f0f0f0	#000000
次要／弱化文本	text-neutral-400 / text-neutral-500	text-neutral-600 / text-neutral-750
未激活的胶囊按钮／按钮	bg-[rgba(255,255,255,0.07)]	bg-neutral-200/80
已激活的胶囊按钮／按钮	bg-[#2a2a2a] text-white	bg-white text-black shadow-sm

---

2. 标准卡片架构（精简展开式布局）

目录网格中的每个组件条目（按钮、卡片展开、3D 轮播、加载器、页面过渡）必须采用精简、优化的卡片布局架构：

展示容器

<div className="mx-auto max-w-[1800px] px-6 pt-5 pb-16 sm:px-10 sm:pt-3 lg:px-16 xl:px-24">
  <div className="space-y-6">
    {/* Island Filter Bar & Secondary Controls */}
    ...
    {/* Responsive Grid */}
    <div className="grid grid-cols-1 gap-x-4 gap-y-8 transition-opacity duration-200 sm:grid-cols-2 lg:gap-x-6 lg:gap-y-10 xl:grid-cols-3 xl:gap-x-8">
      {/* Component Cards */}
    </div>
  </div>
</div>

组件卡片架构

<article className="group/card relative">
  <a 
    href={detailUrl}
    onClick={handleClick}
    className="block focus-visible:outline-none focus-visible:ring-3 focus-visible:ring-ring/50 rounded-3xl no-underline text-inherit"
  >
    {/* Expanded Borderless Playground Stage filling completely with black background */}
    <div className="relative aspect-[16/10] w-full overflow-hidden rounded-3xl bg-black flex items-center justify-center p-4">
      {/* Component Live Interactive Preview Component Here */}
    </div>

    {/* Minimal Card Footer: Only Title & Description, Hover Copy Button */}
    <div className="flex items-center justify-between gap-3 pt-3 px-1">
      <div className="min-w-0 flex-1">
        <h3 className="text-base sm:text-[17px] font-semibold tracking-[-0.015em] text-foreground truncate">
          {label}
        </h3>
        <p className="text-xs sm:text-[13px] font-medium text-muted-foreground truncate mt-0.5">
          {description}
        </p>
      </div>

      {/* Action Copy Button - Fades in on card hover */}
      <motion.button
        whileHover={{ scale: 1.08 }}
        whileTap={{ scale: 0.92 }}
        onClick={handleCopy}
        className="size-8 rounded-lg flex items-center justify-center transition-all duration-200 cursor-pointer border border-border/80 bg-card hover:bg-muted text-muted-foreground hover:text-foreground shrink-0 opacity-0 group-hover/card:opacity-100 focus-visible:opacity-100"
        title="Copy component code"
      >
        <IconSwap>
          <IconSwapItem key={isCopied ? "check" : "copy"}>
            {isCopied ? <Check className="w-3.5 h-3.5 text-emerald-500" /> : <Copy className="w-3.5 h-3.5" />}
          </IconSwapItem>
        </IconSwap>
      </motion.button>
    </div>
  </a>
</article>

---

3. 目录导航与胶囊按钮样式

• 桌面端筛选胶囊按钮栏：
  • 容器：hidden sm:flex items-center p-1 rounded-full border shadow-inner transition-colors duration-300 bg-[#181818] border-white/5（深色）/ bg-neutral-200/50 border-neutral-300/30（浅色）。
  • 激活的胶囊按钮：bg-[#2a2a2a] text-white（深色）/ bg-white text-black shadow-sm（浅色）。
  • 未激活的胶囊按钮：text-[#767676] hover:text-white（深色）/ text-black opacity-70 hover:opacity-100（浅色）。
• 移动端下拉菜单：
  • 带背景模糊效果的模态下拉菜单（backdrop-blur-xl bg-[#181818]/95 border-white/5）。

---

4. 组件微交互与触觉反馈

• 动效：使用 motion/react（framer-motion），并采用三次贝塞尔缓动 [0.16, 1, 0.3, 1]，实现流畅的指数式显现效果。
• 时长预算（硬性规则）：每个单次动画都必须短于 300ms。 这适用于悬停、按压、进入、退出、页面过渡、Toast、菜单、图表绘制和组件交互。
  • 时长：悬停/按压为 0.15–0.2s，进入为 0.25s，退出约为 0.14s（退出动画应短于进入动画），绝对上限为 0.28s。Tailwind：duration-150 / duration-200 / duration-250（绝不使用 duration-300 或更长时长）。
  • 弹簧：在 0.29s 内稳定。欠阻尼系统的稳定时间约为 8 × mass / damping，因此 mass: 1 时使用 damping >= 28（悬停默认值：{ type: 'spring', stiffness: 400, damping: 28 }）。基于时长的弹簧：{ type: 'spring', duration: 0.25, bounce: 0.1–0.2 }。
  • 交错延迟：使用 delay: Math.min(index * 0.015, 0.05)，确保整个网格的进入动画在预算时长内完成。
  • Recharts：animationDuration={280}（其默认值为 1500ms）。
  • 多步骤 CSS 动画编排：每一步 ≤ 0.28s；按时长调整延迟，使整个序列保持同步。
  • 例外：无限循环（旋转指示器、加载器、repeat: Infinity 环境动效），此时该值表示循环周期，而非过渡时长。
• 缓动：进入/退出动画使用 [0.16, 1, 0.3, 1]（缓出）；退出动画也可使用 [0.25, 0.46, 0.45, 0.94]。UI 中绝不使用 easeIn。
• 减少动态效果：应用由 <MotionConfig reducedMotion="user"> 包裹；CSS 动画由 index.css 中的 prefers-reduced-motion 代码块禁用。
• 触觉反馈：始终触发 useWebHaptics 钩子：
  • 复制代码：triggerHaptic('success')
  • 按钮点击 / 切换标签页：triggerHaptic('medium') 或 triggerHaptic('light')
  • 错误：triggerHaptic('error')
• Toast 通知：始终触发 showToast("Copied ... code!")。

---

5. CLI 注册表集成规则

每当添加新组件或过渡效果时：

1. 在 registry/ui/<category>/<name>.tsx 中添加组件源文件。
2. 在 registry/registry.json 中注册组件条目及其依赖项（framer-motion 等）。
3. 提供可复制的 CLI 命令片段：npx @subhanhq/amicro@latest add <kebab-name>。