linear-design

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Linear-Quality Design System

Linear级品质设计系统

Build UI with the craft of Linear, Vercel, and Resend. Great UI is restraint, not addition. The best details are invisible — felt, not seen.

打造具备Linear、Vercel和Resend工艺水准的UI。优秀的UI讲究克制而非堆砌，最好的细节是隐形的——可被感知，而非刻意显露。

Color System

色彩系统

Design a derived color system, not a palette of hardcoded values.

Define 3 foundation variables: base color, accent color, contrast level.
Derive all surfaces, text, icons, borders from these via opacity operations.
Use perceptually uniform color space (LCH/OKLCH) so colors at same lightness look equally light.
Hierarchy through opacity and weight, not hue. Monochrome-first.
Color ONLY for semantic meaning: error (red), success (green), active/selected, brand accent.
No decorative color. No habitual colored icons — make them
```
muted-foreground
```
.
Limit brand color leakage into chrome. The frame should feel neutral and timeless.
No hardcoded hex anywhere. CSS variables / design tokens only.

设计衍生式色彩系统，而非使用硬编码值组成的色板。

定义3个基础变量：base color、accent color、contrast level。
所有表面、文本、图标、边框均通过透明度运算从上述变量衍生而来。
使用感知统一色彩空间（LCH/OKLCH），确保相同明度的色彩视觉亮度一致。
层级通过透明度和字重实现，而非色相，优先采用单色方案。
色彩仅用于表达语义含义：错误（红）、成功（绿）、激活/选中、品牌强调色。
无装饰性色彩，不使用习惯性的彩色图标，统一设为
```
muted-foreground
```
。
限制品牌色在框架中的溢出使用，整体框架应保持中性、不过时的质感。
任何位置不得使用硬编码十六进制色值，仅允许使用CSS变量/设计令牌。

Surface & Elevation

表面与层级

Layer surfaces with subtle background shifts, not heavy shadows.

Define clear elevation hierarchy:
```
background
```
→
```
card/raised
```
→
```
popover
```
→
```
dialog/modal
```
.
Each level is a slight shade shift (via opacity on base), not a different color.
Dark mode: shadows become subtle borders or glows. Replace
```
shadow-md
```
with
```
border border-border/50
```
.
Borders: semi-transparent at low opacity (
```
border-border/40
```
), never solid opaque lines.
Backdrop blur on floating elements:
```
backdrop-blur-sm
```
on overlays, popovers, command palette.
Support high-contrast mode via the contrast variable — accessibility built into the system.
```
-webkit-font-smoothing: antialiased
```
globally.

通过微妙的背景变化实现表面分层，而非使用厚重阴影。

定义清晰的层级结构：
```
background
```
→
```
card/raised
```
→
```
popover
```
→
```
dialog/modal
```
。
每一层级仅做细微的明暗调整（通过基础色的透明度实现），不使用不同色相。
深色模式：阴影替换为微妙边框或发光效果，将
```
shadow-md
```
替换为
```
border border-border/50
```
。
边框：采用低透明度半透明效果（
```
border-border/40
```
），禁止使用实心不透明线条。
浮动元素添加背景模糊效果：遮罩层、弹出层、命令面板添加
```
backdrop-blur-sm
```
。
通过对比度变量支持高对比度模式，将无障碍能力内置到系统中。
全局设置
```
-webkit-font-smoothing: antialiased
```
。

Motion & Animation

动效与动画

Motion is ~30% of why premium UI feels premium.

transition-colors duration-150

is the floor.

Micro-transitions: color/opacity changes use
```
duration-150 ease-out
```
.
Layout transitions: panels, drawers, sidebars use
```
duration-200 ease-in-out
```
.
Entrances: modals/dialogs use spring-based easing — slight overshoot, then settle. Framer Motion:
```
type: "spring", stiffness: 400, damping: 30
```
. CSS:
```
cubic-bezier(0.34, 1.56, 0.64, 1)
```
.
List stagger: items entering a list animate in with 30-50ms stagger between each.
Skeleton shimmer: animated gradient sweep matching content shape, not a static gray box.
Toasts: slide in from consistent anchor (bottom-right), slide out on dismiss.
Number animations: counters animate between values, don't jump.
Exit animations: elements leaving should animate out (opacity + slight translate), not vanish.
Never add artificial delays. Motion should feel instant-but-smooth, not slow.

高端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提示：从固定锚点（右下角）滑入，关闭时滑出。
数字动画：计数器在数值变化时平滑过渡，而非直接跳转。
退场动效：元素消失时应播放退场动画（透明度变化+轻微位移），而非直接消失。
不得添加人为延迟，动效应呈现即时且顺滑的质感，不能拖沓。

Layout Architecture

布局架构

The structural patterns that make an app feel like a tool, not a website.

Three-column layout: collapsible sidebar (240-280px) + main content + optional detail panel.
Resizable panels: drag handles between columns. Show handle on hover, store width preference.
Sticky headers: compress or transform on scroll. Never duplicate content in header and body.
Sheet/drawer vs modal: use sheets for contextual detail (stays in flow), modals for focused tasks (blocks flow). Sheets slide from right, modals center with backdrop.
Command palette:
```
Cmd+K
```
overlay that floats above layout. Fuzzy search, categorized results, recent items, keyboard-navigable. This is primary navigation for power users.
Split views: side-by-side content for comparison or detail-alongside-list.

让应用看起来像工具而非网站的结构模式。

三栏布局：可折叠侧边栏（240-280px）+ 主内容 + 可选详情面板。
可调整大小的面板：栏之间添加拖拽手柄，hover时显示手柄，存储用户的宽度偏好。
粘性头部：滚动时压缩或变换形态，禁止在头部和正文重复展示内容。
抽屉/Sheet vs 模态框：上下文详情使用抽屉（保留上下文流程），聚焦任务使用模态框（阻断流程）。抽屉从右侧滑入，模态框居中显示并带遮罩。
命令面板：
```
Cmd+K
```
触发的悬浮层，位于布局最上层，支持模糊搜索、分类结果、最近访问项、键盘导航，是重度用户的主要导航方式。
分栏视图：并排展示内容用于对比，或在列表旁展示详情。

Keyboard-First Design

键盘优先设计

A Linear-quality app is faster with keyboard than mouse.

Command palette (
```
Cmd+K
```
): search commands, navigate, execute actions. Must exist.
Single-key shortcuts:
```
C
```
to create,
```
S
```
for status, etc. Show in tooltips and context menus.
List navigation:
```
j/k
```
or arrow keys to move through items,
```
Enter
```
to open.
Multi-select:
```
Shift+Click
```
range select,
```
Cmd+Click
```
toggle individual.
Focus management: after dialog close, focus returns to trigger. After create, focus new item.
Shortcuts in UI: display keyboard shortcut hints in tooltips, context menus, and command palette results. This teaches users the shortcuts naturally.
Escape to dismiss: every overlay, modal, popover, command palette closes on
```
Escape
```
.

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

命令面板（
```
Cmd+K
```
）：支持搜索命令、导航、执行操作，为必备功能。
单键快捷键：
```
C
```
创建、
```
S
```
修改状态等，在tooltip和上下文菜单中展示提示。
列表导航：
```
j/k
```
或方向键遍历列表项，
```
Enter
```
打开详情。
多选：
```
Shift+点击
```
范围选择，
```
Cmd+点击
```
切换单个项选中状态。
焦点管理：关闭对话框后焦点回到触发元素，创建新项后焦点落在新项上。
UI中展示快捷键：在tooltip、上下文菜单、命令面板结果中展示快捷键提示，自然引导用户学习使用。
Escape关闭：所有悬浮层、模态框、弹出层、命令面板都支持
```
Escape
```
键关闭。

Progressive Disclosure

渐进式展示

Resting state is minimal. Complexity reveals on interaction.

Row actions: edit, delete, options menu — visible only on row
```
:hover
```
.
Metadata: timestamps, secondary badges — shown on hover where non-essential at rest.
Toolbars: bulk action bars appear on selection, not permanently.
Contextual menus: right-click surfaces full action set. Include keyboard shortcuts in menu items.
Sub-menu safe areas: triangle hit area between cursor and sub-menu so diagonal mouse movement doesn't close the menu (the Linear pattern — ~40 lines of code, invisible to user, felt as smoothness).
If it's not primary content or primary action, it should not be visible at rest.

默认状态保持极简，交互时才展示复杂功能。

行操作按钮：编辑、删除、选项菜单仅在行
```
hover
```
时显示。
元数据：时间戳、次要标签等非核心信息在hover时展示，默认状态隐藏。
工具栏：批量操作栏仅在选中内容时显示，不永久展示。
上下文菜单：右键点击展示完整操作集合，菜单项中包含快捷键提示。
子菜单安全区域：在光标和子菜单之间设置三角形点击热区，避免鼠标斜向移动时意外关闭菜单（Linear经典模式——约40行代码，用户无感知，却能带来顺滑的使用体验）。
非核心内容或非核心操作，默认状态下都不应显示。

Information Density

信息密度

Dense yet clean. Chrome is sparse, content is dense.

Tight line-heights in lists and tables (1.25-1.4, not Tailwind default 1.5).
Compact inline metadata: status dot + avatar + priority icon + label, all in one row.
Tabular numbers:
```
font-variant-numeric: tabular-nums
```
on all number columns so digits align.
Monospace: IDs, branch names, code, technical strings in
```
font-mono text-xs
```
.
Right-align numbers in table columns.
Density trade-off: reduce chrome spacing (sidebar padding, header height) to give content room. Content area can be dense; navigation frame stays spacious.

紧凑但整洁，框架极简，内容高密度展示。

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

Buttons & Actions

按钮与操作

AT MOST one
```
variant="default"
```
(primary) button per page/modal/card.
All other actions: secondary, outline, or ghost — pick by visual weight.
Destructive:
```
variant="destructive"
```
+ confirmation dialog before execution.
Consistent button height per context. Never mix sizes in the same view.
Cursor
```
pointer
```
on everything clickable.

每个页面/模态框/卡片最多只能有一个
```
variant="default"
```
（主）按钮。
其他所有操作按钮：次要按钮、线框按钮或幽灵按钮，根据视觉权重选择。
破坏性操作：使用
```
variant="destructive"
```
样式，执行前弹出确认对话框。
同一上下文下按钮高度保持一致，同一视图中禁止混合使用不同尺寸。
所有可点击元素光标设为
```
pointer
```
。

Interactivity & Micro-interactions

交互与微交互

Every clickable element: distinct
```
hover:
```
state (color/opacity) +
```
active:
```
state (pressed).
No bare
```
<div onClick>
```
without visual hover feedback.
Focusable elements:
```
focus-visible:ring-2 ring-ring
```
.
Drag handles: appear on hover, hidden at rest.
Copy-to-clipboard: brief "Copied!" feedback (tooltip or inline text swap, 1.5s).
Optimistic updates: UI changes instantly on action, server catches up async.
Smart menu positioning: menus stay in viewport, flip direction when near edges.
Input debounce: search/filter inputs debounce 200-300ms, show subtle loading indicator.

每个可点击元素都要有明确的
```
hover:
```
状态（颜色/透明度变化）+
```
active:
```
状态（按压效果）。
不得使用没有hover视觉反馈的裸
```
<div onClick>
```
元素。
可聚焦元素：
```
focus-visible:ring-2 ring-ring
```
。
拖拽手柄：hover时显示，默认状态隐藏。
复制到剪贴板：提供简短的“已复制！”反馈（tooltip或行内文本切换，显示1.5秒）。
乐观更新：用户操作后UI立即变更，服务端异步同步状态。
智能菜单定位：菜单始终保持在视口内，靠近边缘时自动调整弹出方向。
输入防抖：搜索/筛选输入防抖200-300ms，展示微妙的加载指示器。

Typography

排版

Each view: one dominant heading, one focal point. No competing visual weights.
Chrome recedes, content advances — high-contrast text against quieter frame.
Design system tokens only. No arbitrary font sizes or weights.
Display font for headings (e.g. Inter Display, Geist) for expression. Regular weight for body.
Letter-spacing: slightly tighter on large headings (
```
tracking-tight
```
), default on body.

每个视图只有一个主标题、一个视觉焦点，没有互相竞争的视觉权重。
框架视觉上退后，内容突出——高对比度文本放在低存在感的框架上。
仅使用设计系统令牌，不得使用任意字号或字重。
标题使用展示字体（如Inter Display、Geist）增强表现力，正文使用常规字重。
字间距：大标题使用略紧的字间距（
```
tracking-tight
```
），正文使用默认值。

Truncation

文本截断

Single-line:
```
truncate
```
+
```
min-w-0
```
on flex parent and span.
Multi-line:
```
line-clamp-{n}
```
with deliberate max.
Text never overflows. Every string is bounded. Never
```
break-all
```
.

单行截断：在flex父容器和span上设置
```
truncate
```
+
```
min-w-0
```
。
多行截断：使用
```
line-clamp-{n}
```
设置明确的最大行数。
文本永远不能溢出，所有字符串都有边界限制，禁止使用
```
break-all
```
。

States

状态

Loading:
```
<Skeleton>
```
matching real layout shape + shimmer animation. Never spinner in content.
Empty: title + one-line description + single CTA. Never blank.
Error: human-readable message + what to do next.
Disabled:
```
opacity-50 cursor-not-allowed
```
. Never remove the element.

加载中：使用与真实布局形状匹配的
```
<Skeleton>
```
+ 扫动动效，内容区域禁止使用单独的加载 spinner。
空状态：标题+单行描述+单个行动按钮，禁止空白展示。
错误状态：展示可读性强的错误信息+下一步操作指引。
禁用状态：
```
opacity-50 cursor-not-allowed
```
，禁止直接移除元素。

Tables & Data Display

表格与数据展示

Full row highlight on hover (subtle background change).
Right-aligned numbers, left-aligned text.
Sortable columns with subtle indicator (chevron icon).
Horizontally scrollable with frozen first column on overflow.
Row actions on hover (progressive disclosure).
Alternating row backgrounds at very low opacity (optional,
```
even:bg-muted/30
```
).

hover时整行高亮（微妙的背景变化）。
数字右对齐，文本左对齐。
可排序列展示微妙的排序指示器（ Chevron图标）。
内容溢出时支持横向滚动，首列冻结。
行操作按钮hover时展示（渐进式展示）。
可选添加极低透明度的斑马纹行背景（
```
even:bg-muted/30
```
）。

Components

组件

shadcn/ui only. Never reimplement Dialog, Tooltip, Dropdown, Select, Tabs, Badge, Card, Skeleton.
Lucide icons only. No emojis. No decorative AI icons (sparkles, wands, stars).
Icon-only buttons: MUST wrap in
```
<Tooltip>
```
with short label. No exceptions.
Consistent icon size per density (16px dense, 18-20px standard). Don't mix arbitrarily.
Consistent border radius throughout — never deviate from system radius.

仅使用shadcn/ui组件，禁止自行实现Dialog、Tooltip、Dropdown、Select、Tabs、Badge、Card、Skeleton组件。
仅使用Lucide图标，禁止使用emoji，禁止使用装饰性AI图标（闪光、魔法棒、星星等）。
纯图标按钮：必须用
```
<Tooltip>
```
包裹并添加简短标签，无例外。
同一密度下图标尺寸一致（紧凑模式16px，标准模式18-20px），禁止随意混用。
全系统圆角保持一致，不得偏离系统定义的圆角值。

Spacing

间距

4px base scale. No arbitrary values (
```
mt-[13px]
```
is a violation).
No orphaned elements. Everything on a layout grid.
Remove borders/dividers replaceable by spacing alone.
Generous whitespace — empty space IS the design.

以4px为基础缩放单位，禁止使用任意间距值（如
```
mt-[13px]
```
属于违规）。
无孤立元素，所有元素都对齐布局网格。
可以用间距替代的边框/分隔线直接移除。
充足的留白——空白本身就是设计的一部分。

Polish

打磨优化

No
```
console.log
```
in UI components.
No
```
z-[9999]
```
— use defined z-index scale.
No
```
!important
```
overrides.
No hardcoded colors — all through CSS variables.
```
Escape
```
closes every overlay.
URL updates on tab/section change for shareability.
Responsive: sidebar collapses to icon-only or drawer on mobile. Panels stack vertically.

UI组件中不得有
```
console.log
```
。
不得使用
```
z-[9999]
```
，使用定义好的z-index缩放体系。
不得使用
```
!important
```
覆盖样式。
无硬编码色值，所有色值通过CSS变量定义。
```
Escape
```
键可以关闭所有悬浮层。
切换标签/分区时URL同步更新，支持分享。
响应式适配：移动端侧边栏折叠为仅图标模式或抽屉，面板垂直堆叠。

Audit Output Format

审核输出格式

For each issue:

File path + line
What's wrong (one sentence)
The fix

Group by: Color/Surface → Motion → Layout → Keyboard → Progressive Disclosure → Density → Interactivity → Typography → States → Tables → Polish

Rank: broken interactions > missing keyboard support > missing states > motion gaps > visual inconsistency > polish.

End with: what still needs human design judgment that code alone cannot fix.

每个问题包含：

文件路径+行号
问题描述（一句话）
修复方案

按以下分组排序：色彩/表面 → 动效 → 布局 → 键盘支持 → 渐进式展示 → 密度 → 交互 → 排版 → 状态 → 表格 → 打磨优化

优先级排序：交互故障 > 缺失键盘支持 > 缺失状态 > 动效缺失 > 视觉不一致 > 打磨优化

最后补充：哪些内容仍然需要人工设计判断，无法仅通过代码解决。