UI 设计规范

01MVP 的设计系统、视觉 token 和组件实现约束

本页是 01MVP 的设计系统主文档。组件 API 详情请参考 UI 组件包和主题包。

设计背景

目标用户和场景

目标用户：需要快速上线 MVP 的开发者、技术型创始人和小团队
核心诉求：在不牺牲专业感的前提下，尽快交付生产可用产品
设计目标：让界面显得现代、可信、克制，而不是“模板味”很重

品牌个性

Modern
Minimal
Elegant

这套系统默认采用接近 Vercel 的极简方向，但不会机械复制；01MVP 允许在边框、留白和少量阴影上保留自己的层次感。

核心原则

Clarity Over Cleverness
Performance is a Feature
Consistency Builds Trust
Accessible by Default
Mobile-First, Desktop-Refined

落地时对应的硬性要求：

永远优先语义化 token，而不是硬编码颜色
使用边框作为主要分层机制，阴影只做辅助
交互反馈尽量依赖颜色、透明度和边框变化
所有页面默认支持键盘导航与清晰焦点态

Typography

字体族

--font-sans: "Geist Sans", "Source Han Sans CN", sans-serif;
--font-brand: "Geist Sans", "Source Han Sans CN", sans-serif;
--font-mono: "Geist Mono", monospace;

使用规则

font-sans：正文、界面、标题
font-brand：品牌大标题，可与 font-sans 等价使用
font-mono：代码、日志、命令行片段

Token	尺寸	用途
`text-sm`	14px	次级文本、标签
`text-base`	16px	正文默认值
`text-lg`	18px	强调正文
`text-xl`	20px	小标题
`text-2xl`	24px	模块标题
`text-4xl`	36px	页面标题
`text-6xl`	60px	Hero 标题

Color System

设计哲学

以黑白灰单色系为基础，通过少量语义色承载状态，而不是装饰页面。

亮色模式

--background: #ffffff;
--foreground: #111111;
--primary: #000000;
--primary-foreground: #ffffff;
--secondary: #f3f4f6;
--secondary-foreground: #111111;
--muted: #f9fafb;
--muted-foreground: #6b7280;
--accent: #f3f4f6;
--accent-foreground: #111111;
--border: #e5e7eb;
--input: #e5e7eb;
--ring: #111111;
--card: #ffffff;
--card-foreground: #111111;
--destructive: #dc2626;
--destructive-foreground: #ffffff;
--success: #166534;
--success-foreground: #ffffff;

暗色模式

--background: #0a0a0a;
--foreground: #fafafa;
--primary: #ffffff;
--primary-foreground: #000000;
--secondary: #1a1a1a;
--secondary-foreground: #fafafa;
--muted: #1a1a1a;
--muted-foreground: #a3a3a3;
--accent: #1f1f1f;
--accent-foreground: #fafafa;
--border: #262626;
--input: #262626;
--ring: #d4d4d4;
--card: #141414;
--card-foreground: #fafafa;

使用示例

// 正确
<div className="bg-background text-foreground border-border" />
<Button className="bg-primary text-primary-foreground" />

// 错误
<div className="bg-white text-black border-gray-200" />

Spacing 和 Layout

间距尺度

基于 4px：

4, 8, 12, 16, 24, 32, 48, 64, 96

常用建议：

按钮：px-4 py-2
输入框：px-3 py-2
卡片：p-6
Modal：p-8
Section：py-16 md:py-24

不要使用 mt-[13px] 这类任意值，除非确实存在无法用 token 覆盖的布局需求。

Radius 和 Shadow

圆角尺度

--radius-sm: 6px;
--radius-md: 8px;
--radius-lg: 10px;
--radius-xl: 12px;
--radius-2xl: 16px;
--radius-full: 9999px;

推荐映射：

按钮：rounded-full 或 rounded-xl
卡片：rounded-xl
输入框：rounded-lg
Modal：rounded-2xl
Badge / Avatar：rounded-full

阴影策略

默认不依赖阴影制造层次
优先用边框和背景对比
只有浮层、悬浮卡片和下拉菜单才使用轻量阴影

Motion

原则

动画必须有明确目的
时长控制在 150ms 到 300ms
尊重 prefers-reduced-motion
尽量避免交互中位移过大的 hover 动画

组件模式

Buttons

Primary：实色背景，强调主动作
Secondary：描边或低对比背景
Ghost：用于次级操作和工具栏
Destructive：危险操作，使用 destructive

推荐尺寸：

sm: h-9 px-3 text-sm
default: h-10 px-4 text-base
lg: h-12 px-8 text-base

Cards

<Card className="border-border hover:border-border/80 transition-colors">
  <CardContent className="p-6">{/* ... */}</CardContent>
</Card>

卡片默认通过边框区分层级，hover 时优先调整边框颜色，其次才是轻量阴影。

Forms

输入框高度不低于 h-10
标签使用 text-sm font-medium
错误提示使用 text-sm text-destructive
Focus 态统一 ring-2 ring-ring ring-offset-2

响应式设计

断点

sm: 640px
md: 768px
lg: 1024px
xl: 1280px
2xl: 1536px

移动优先

// 正确
<div className="text-4xl md:text-6xl lg:text-8xl" />

// 错误
<div className="text-8xl md:text-6xl sm:text-4xl" />

触摸目标

所有交互元素需要尽量达到 44x44px 触摸区域。

Accessibility

硬性要求：

文本对比度满足 WCAG 2.1 AA
所有交互元素可键盘访问
使用语义化 HTML 结构
装饰性元素使用 aria-hidden="true"
模态框、下拉层支持 Esc 关闭

与组件库的关系

`packages/ui`

只存放纯 shadcn/ui 原子组件
不手改 packages/ui/src/components/*
需要升级时通过 pnpm dlx shadcn@latest add <component> 更新

`packages/ui-shared`

存放跨项目复用的业务组件
可以组合 @mono/ui
可以承载业务逻辑和样式约束

`apps/*/src/components`

只放单应用专用组件
保留 app 层的特定布局与交互

自定义品牌方向

准备从默认风格迁移到品牌化视觉时，优先改这几处：

tailwind.config.ts 或字体配置
src/styles/theme.css 中的语义化颜色变量
圆角尺度和组件默认半径
业务组件层的排版、布局和图形语言

UI 提交前检查

使用语义化 token，无硬编码颜色
遵循 4px 间距系统
亮色 / 暗色模式表现正确
焦点态、键盘导航和触摸目标达标
包含加载态和错误态
动效遵守 reduced motion