01MVP Starter Kit

本页是 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 -- 移动端优先，桌面端优化

硬性约束（每次提交 UI 代码前请自查）：

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

Typography

font-sans（Geist Sans + Source Han Sans CN）：正文、界面、标题
font-mono（Geist Mono）：代码、日志

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

大标题用 tracking-tight，长文正文用 leading-relaxed。

Color System

以黑白灰单色系为基础，通过少量语义色（success、destructive）承载状态，不作为装饰。

实际页面分层规则：

页面分层速查：最外层用黑色强边框 → 内部元素用灰色细边框 → 文档正文用浅灰底 → 状态色只给反馈用。每个语义 token 在亮色和暗色模式下有对应取值，组件引用 token 就能自动适配，不需要写 dark: 前缀。

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。

Radius 和 Shadow

01MVP 默认方角（--radius: 0px）。头像、开关和 pill badge 可用 rounded-full。

推荐语义类：

<div className="theme-frame p-6">外层强面板</div>
<div className="theme-surface p-4">普通信息块</div>
<input className="theme-control h-12 px-4" />

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

新增 UI 的默认约束：

主容器、面板、按钮、输入框必须能跟随 theme preset 切换
业务组件里不要写死 bg-white、text-gray-*、border-zinc-*、shadow-xl、任意 hex / OKLCH 颜色
需要新的视觉角色时，先在 apps/01mvp-web/src/styles/theme.css 为全部 preset 和 dark mode 增加变量，再封装语义类
新增顶层页面要放进已有 shell，或提供现有的 theme preset 切换入口，不能做一个无法切换风格的孤立页面

Theme Presets

Preset	适合场景	风格说明
`01mvp`	教程、会员内容、品牌页	外层黑框，内部灰线，黑白灰为主
`vercel`	产品官网、开发者工具	细线、低装饰、强留白
`linear`	SaaS 后台、协作工具	轻微冷色、柔和面板
`claude`	文档、教程、知识库	温和中性色，长文阅读更轻

Motion

动画必须有明确目的，时长控制在 150ms 到 300ms
尊重 prefers-reduced-motion
推荐 easing：ease-out、ease-in-out

响应式设计

断点：sm: 640px、md: 768px、lg: 1024px、xl: 1280px、2xl: 1536px。移动优先，用 md:、lg: 前缀逐层增强。交互元素尽量达到 44x44px 触摸区域。

手机端默认更紧凑。参考微信小程序和 WhatsApp 的信息密度：单列、短路径、清楚的列表行、少量底部操作。不要让移动端首屏被超大 Hero、厚卡片或过多 py-16 / py-24 挤掉主要内容。桌面端需要更强品牌展示时，再通过 md: / lg: 放大字号、section 间距和卡片 padding。

设置页和表单页按 App 设置页处理：手机端优先使用分组列表、紧凑行、弱阴影或无阴影、12px 到 16px 的内容 padding。输入框保持 44px 到 48px 高度；未修改时不要常驻灰色保存按钮，用户修改后再显示明确的满宽操作。头像、昵称、邮箱这类账号信息优先横向排列，避免用大卡片和大头像消耗首屏。

与组件库的关系

packages/ui -- 纯 shadcn/ui 原子组件，禁止手改
packages/ui-shared -- 跨项目复用的业务组件
apps/*/src/components -- 单应用专用组件

自定义品牌方向

从默认风格迁移到品牌化视觉时，优先改：

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

UI 设计规范