linear-design

Linear 风格设计系统

以 Linear、Vercel 和 Resend 的精湛工艺构建 UI。出色的 UI 在于克制，而非堆砌。 最好的细节是无形的——能被感受到，而不是被看到。

色彩系统

设计一套衍生色彩系统，而不是一组写死的调色板。

• 定义 3 个基础变量：基础色、强调色、对比度级别。
• 通过不透明度运算，从这些变量派生所有表面、文本、图标和边框。
• 使用感知均匀的色彩空间（LCH/OKLCH），确保明度相同的颜色看起来同样明亮。
• 通过不透明度和字重体现层级，而非色相。优先采用单色。
• 颜色仅用于表达语义：错误（红色）、成功（绿色）、激活/选中、品牌强调色。
• 不使用装饰性色彩。避免习惯性地使用彩色图标——将其设为 muted-foreground。
• 限制品牌色渗入界面框架。整体框架应显得中性、经得起时间考验。
• 任何地方都不写死十六进制颜色值。只使用 CSS 变量 / 设计令牌。

表面与层级

通过细微的背景变化叠加表面，而非使用浓重阴影。

• 明确划分层级：background → card/raised → popover → dialog/modal。
• 每一层只需轻微改变色调（通过基础色的不透明度实现），而不是使用不同颜色。
• 深色模式：用细微边框或辉光替代阴影。将 shadow-md 替换为 border border-border/50。
• 边框：使用低不透明度的半透明边框（border-border/40），绝不使用不透明的实线。
• 背景模糊：在浮动元素上使用 backdrop-blur-sm，包括叠加层、弹出框和命令面板。
• 通过对比度变量支持高对比度模式——让无障碍性融入系统。
• 全局设置 -webkit-font-smoothing: antialiased。

动效与动画

动效约占高端 UI 质感的 30%。transition-colors duration-150 是最低标准。

• 微交互过渡：颜色/不透明度变化使用 duration-150 ease-out。
• 布局过渡：面板、抽屉、侧边栏使用 duration-200 ease-in-out。
• 入场动画：模态框/对话框使用基于弹簧的缓动——轻微过冲后稳定下来。 Framer Motion：type: "spring", stiffness: 400, damping: 30。CSS：cubic-bezier(0.34, 1.56, 0.64, 1)。
• 列表交错动画：列表项进入时依次播放动画，每项间隔 30-50ms。
• 骨架屏闪光效果：使用与内容形状匹配的渐变扫光动画，而不是静态灰色方块。
• Toast 提示：从固定位置（右下角）滑入，关闭时滑出。
• 数字动画：计数器在数值之间平滑过渡，而不是突然跳变。
• 退出动画：元素离开时应播放退出动画（透明度变化 + 轻微位移），而不是直接消失。
• 切勿添加人为延迟。动效应感觉即时而流畅，而非缓慢。

布局架构

以下结构模式能让应用像工具，而不是网站。

• 三栏布局：可折叠侧边栏（240-280px）+ 主内容区 + 可选详情面板。
• 可调整大小的面板：在列之间设置拖动手柄。悬停时显示手柄，并保存宽度偏好。
• 粘性页眉：滚动时收缩或变形。绝不在页眉和正文中重复内容。
• 侧边面板/抽屉与模态框：上下文详情使用侧边面板（保持在流程中），专注任务使用模态框 （阻断当前流程）。侧边面板从右侧滑入，模态框居中显示并带有背景遮罩。
• 命令面板：悬浮于布局之上的 Cmd+K 叠加层。支持模糊搜索、分类结果、 最近项目和键盘导航。这是高级用户的主要导航方式。
• 分屏视图：并排显示内容，便于比较或在列表旁查看详情。

键盘优先设计

达到 Linear 品质的应用，用键盘操作比用鼠标更快。

• 命令面板（Cmd+K）：搜索命令、导航、执行操作。必须提供。
• 单键快捷键：按 C 创建，按 S 查看状态，等等。在工具提示和上下文菜单中显示。
• 列表导航：按 j/k 或方向键浏览项目，按 Enter 打开。
• 多选：Shift+Click 范围选择，Cmd+Click 切换单个项目的选中状态。
• 焦点管理：对话框关闭后，焦点返回触发控件。创建后，焦点移至新项目。
• 界面中的快捷键：在工具提示、上下文菜单和命令面板结果中显示键盘快捷键提示。让用户自然地熟悉快捷键。
• 按 Escape 关闭：所有覆盖层、模态框、弹出框和命令面板都应按 Escape 关闭。

渐进式披露

默认状态保持简洁。交互时再逐步显示复杂内容。

• 行操作：编辑、删除、选项菜单——仅在行 :hover 时显示。
• 元数据：时间戳、次要徽章——在默认状态下不重要时，于悬停时显示。
• 工具栏：选中项目后显示批量操作栏，而不是始终显示。
• 上下文菜单：右键显示完整操作集。在菜单项中包含键盘快捷键。
• 子菜单安全区域：在光标与子菜单之间设置三角形命中区域，防止鼠标斜向移动时关闭菜单（Linear 的做法——约 40 行代码，用户看不见，却能感受到操作流畅）。
• 如果不是主要内容或主要操作，就不应在默认状态下显示。

信息密度

紧凑而清晰。界面框架简洁，内容密集。

• 列表和表格使用较紧凑的行高（1.25-1.4，而非 Tailwind 默认的 1.5）。
• 紧凑的行内元数据：状态圆点 + 头像 + 优先级图标 + 标签，全部放在同一行。
• 等宽数字：所有数字列都使用 font-variant-numeric: tabular-nums，让数字对齐。
• 等宽字体：ID、分支名称、代码、技术字符串使用 font-mono text-xs。
• 表格中的数字右对齐。
• 密度权衡：减少界面框架的间距（侧边栏内边距、页眉高度），为内容腾出空间。内容区域可以紧凑，导航框架则保持宽敞。

按钮与操作

• 每个页面、模态框或卡片中，variant="default"（主要）按钮最多只能有一个。
• 其他所有操作：使用次要、轮廓或幽灵样式，根据视觉权重选择。
• 危险操作：使用 variant="destructive"，并在执行前显示确认对话框。
• 同一上下文中的按钮高度保持一致。不要在同一视图中混用尺寸。
• 所有可点击元素的光标都设为 pointer。

交互性与微交互

• 每个可点击元素：都应有明确的 hover: 状态（颜色/不透明度）和 active: 状态（按下效果）。
• 不要使用没有视觉悬停反馈的裸 <div onClick>。
• 可聚焦元素：使用 focus-visible:ring-2 ring-ring。
• 拖动手柄：悬停时显示，默认隐藏。
• 复制到剪贴板：提供简短的“已复制！”反馈（工具提示或行内文本切换，持续 1.5s）。
• 乐观更新：操作后界面立即变化，服务端异步完成同步。
• 智能菜单定位：菜单保持在视口内，靠近边缘时翻转方向。
• 输入防抖：搜索/筛选输入防抖 200-300ms，并显示细微的加载指示器。

排版

• 每个视图：一个主导标题，一个视觉焦点。避免多个视觉重点互相竞争。
• 界面框架退后，内容突出——让高对比度文本衬托在更柔和的框架上。
• 仅使用设计系统令牌。不要使用任意字号或字重。
• 标题使用展示字体（例如 Inter Display、Geist）以增强表现力。正文使用常规字重。
• 字间距：大标题稍微收紧（tracking-tight），正文使用默认值。

文本截断

• 单行：使用 truncate，并在 flex 父级和 span 上设置 min-w-0。
• 多行：使用 line-clamp-{n}，并明确设置最大行数。
• 文本绝不溢出。每个字符串都应设定边界。绝不使用 break-all。

状态

• 加载中：使用与实际布局形状匹配的 <Skeleton>，并添加闪烁动画。内容区域内绝不使用加载动画。
• 空状态：标题 + 单行描述 + 单个 CTA。绝不留白。
• 错误：提供易于理解的消息 + 后续操作指引。
• 禁用：opacity-50 cursor-not-allowed。绝不移除元素。

表格与数据展示

• 悬停时高亮整行（背景轻微变化）。
• 数字右对齐，文本左对齐。
• 列支持排序，并用轻量指示器（尖括号图标）标示。
• 内容溢出时支持水平滚动，并冻结首列。
• 悬停时显示行操作（渐进式披露）。
• 可选：使用极低不透明度的交替行背景（even:bg-muted/30）。

组件

• 仅使用 shadcn/ui。绝不重新实现 Dialog、Tooltip、Dropdown、Select、Tabs、Badge、Card、Skeleton。
• 仅使用 Lucide 图标。不要使用表情符号。不要使用装饰性 AI 图标（闪光、魔杖、星星）。
• 仅含图标的按钮：必须用 <Tooltip> 包裹，并提供简短标签。无一例外。
• 根据密度统一图标大小（高密度为 16px，标准密度为 18-20px）。不要随意混用。
• 全局统一边框圆角，绝不偏离系统圆角规范。

间距

• 以 4px 为基础单位。不要使用任意值（mt-[13px] 属于违规）。
• 不要让元素孤立。所有内容都应遵循布局网格。
• 删除可单靠间距替代的边框和分隔线。
• 留出充足留白——空白本身就是设计。

打磨

• UI 组件中不要使用 console.log。
• 不要使用 z-[9999]——使用已定义的 z-index 级别。
• 不要使用 !important 覆盖样式。
• 不要硬编码颜色——所有颜色都应通过 CSS 变量设置。
• 按 Escape 键应关闭所有覆盖层。
• 切换标签页或分区时更新 URL，以便分享。
• 响应式设计：移动端侧边栏折叠为仅图标模式或抽屉。面板垂直堆叠。

审查输出格式

针对每个问题：

1. 文件路径 + 行号
2. 问题所在（一句话）
3. 修复方案

按以下类别分组：颜色/表面 → 动效 → 布局 → 键盘 → 渐进式披露 → 密度 → 交互性 → 排版 → 状态 → 表格 → 打磨

排序：交互故障 > 缺少键盘支持 > 缺少状态 > 动效问题 > 视觉不一致 > 打磨问题。

结尾说明：哪些方面仍需要人工进行设计判断，无法仅靠代码解决。