Back to Details

basic-design-principles

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Design Principles

设计原则

This skill enforces precise, crafted design for enterprise software, SaaS dashboards, admin interfaces, and web applications. The philosophy is Jony Ive-level precision with intentional personality — every interface is polished, and each is designed for its specific context.
本规范为企业级软件、SaaS仪表盘、管理后台界面和Web应用提供精准的精细化设计标准。设计理念是达到Jony Ive级别的精度同时保留适配场景的个性：每一个界面都经过打磨，且完全适配其特定的使用场景。

Design Direction (REQUIRED)

设计方向（必填）

Before writing any code, commit to a design direction. Don't default. Think about what this specific product needs to feel like.
编写任何代码前，先确定设计方向。不要使用默认配置，思考这款产品具体需要什么样的风格感受。

Think About Context

考虑使用场景

  • What does this product do? A finance tool needs different energy than a creative tool.
  • Who uses it? Power users want density. Occasional users want guidance.
  • What's the emotional job? Trust? Efficiency? Delight? Focus?
  • What would make this memorable? Every product has a chance to feel distinctive.
  • 这款产品的功能是什么？ 金融工具需要的风格和创意工具完全不同。
  • 目标用户是谁？ 高频重度用户偏好高密度信息展示，偶尔使用的用户需要更多引导。
  • 需要传递的情绪价值是什么？ 信任感？效率？愉悦感？专注感？
  • 什么设计能让产品有记忆点？ 每款产品都有机会打造独特的风格辨识度。

Choose a Personality

选择风格定位

Enterprise/SaaS UI has more range than you think. Consider these directions:
Precision & Density — Tight spacing, monochrome, information-forward. For power users who live in the tool. Think Linear, Raycast, terminal aesthetics.
Warmth & Approachability — Generous spacing, soft shadows, friendly colors. For products that want to feel human. Think Notion, Coda, collaborative tools.
Sophistication & Trust — Cool tones, layered depth, financial gravitas. For products handling money or sensitive data. Think Stripe, Mercury, enterprise B2B.
Boldness & Clarity — High contrast, dramatic negative space, confident typography. For products that want to feel modern and decisive. Think Vercel, minimal dashboards.
Utility & Function — Muted palette, functional density, clear hierarchy. For products where the work matters more than the chrome. Think GitHub, developer tools.
Data & Analysis — Chart-optimized, technical but accessible, numbers as first-class citizens. For analytics, metrics, business intelligence.
Pick one. Or blend two. But commit to a direction that fits the product.
企业级/SaaS UI的风格范围比你想象的更广，可以参考以下方向：
精准高密度 —— 紧凑间距、单色调、信息优先，面向长期使用工具的重度用户，参考Linear、Raycast、终端的视觉风格。
温暖易接近 —— 宽松间距、柔和阴影、友好配色，面向需要传递人文感的产品，参考Notion、Coda等协作工具。
专业可信赖 —— 冷色调、分层深度、金融级厚重感，面向处理资金或敏感数据的产品，参考Stripe、Mercury等企业级B2B产品。
清晰现代化 —— 高对比度、大量留白、有辨识度的排版，面向需要传递现代、果断调性的产品，参考Vercel、极简风格仪表盘。
实用功能优先 —— 低饱和配色、功能导向的高密度布局、清晰的层级关系，面向内容优先级高于视觉包装的产品，参考GitHub等开发者工具。
数据与分析导向 —— 适配图表展示、专业但易读、数据信息优先，面向分析、指标、商业智能类产品。
选一个方向，或者最多融合两个方向，但是必须确定适配产品的明确方向。

Choose a Color Foundation

选择色彩基础

Don't default to warm neutrals. Consider the product:
  • Warm foundations (creams, warm grays) — approachable, comfortable, human
  • Cool foundations (slate, blue-gray) — professional, trustworthy, serious
  • Pure neutrals (true grays, black/white) — minimal, bold, technical
  • Tinted foundations (slight color cast) — distinctive, memorable, branded
Light or dark? Dark modes aren't just light modes inverted. Dark feels technical, focused, premium. Light feels open, approachable, clean. Choose based on context.
Accent color — Pick ONE that means something. Blue for trust. Green for growth. Orange for energy. Violet for creativity. Don't just reach for the same accent every time.
不要默认使用暖中性色，根据产品定位选择：
  • 暖色系基底（米白、暖灰）—— 亲和力强、舒适、人性化
  • 冷色系基底（ slate、蓝灰）—— 专业、可信、严肃
  • 纯中性色基底（正灰、黑白）—— 极简、 bold、技术感
  • 微调色基底（轻微色彩倾向）—— 有辨识度、有记忆点、有品牌感
亮色还是暗色模式？ 暗色模式不是简单反亮色模式的色值，暗色传递技术感、专注感、高级感，亮色传递开放、友好、干净的感觉，根据场景选择。
强调色 —— 只选1种有表意属性的强调色：蓝色代表信任，绿色代表增长，橙色代表活力，紫色代表创意，不要每次都用同一种默认强调色。

Choose a Layout Approach

选择布局方案

The content should drive the layout:
  • Dense grids for information-heavy interfaces where users scan and compare
  • Generous spacing for focused tasks where users need to concentrate
  • Sidebar navigation for multi-section apps with many destinations
  • Top navigation for simpler tools with fewer sections
  • Split panels for list-detail patterns where context matters
内容应该驱动布局设计：
  • 高密度网格 适用于用户需要扫描、对比信息的重信息界面
  • 宽松间距 适用于需要用户专注完成的任务型界面
  • 侧边栏导航 适用于有很多功能模块的多分区应用
  • 顶部导航 适用于功能模块较少的轻量化工具
  • 分栏面板 适用于需要上下文关联的列表-详情模式

Choose Typography

选择排版方案

Typography sets tone. Don't always default:
  • System fonts — fast, native, invisible (good for utility-focused products)
  • Geometric sans (Geist, Inter) — modern, clean, technical
  • Humanist sans (SF Pro, Satoshi) — warmer, more approachable
  • Monospace influence — technical, developer-focused, data-heavy
排版决定产品基调，不要总是用默认配置：
  • 系统字体 —— 加载快、原生体验、无感知（适合功能优先的产品）
  • 几何无衬线字体（Geist、Inter）—— 现代、干净、技术感
  • 人文无衬线字体（SF Pro、Satoshi）—— 更温暖、更有亲和力
  • 等宽字体倾向 —— 技术感、面向开发者、数据密集型产品

Core Craft Principles

核心落地规范

These apply regardless of design direction. This is the quality floor.
无论选择什么设计方向都要遵守以下规则，这是质量底线。

The 4px Grid

4px网格体系

All spacing uses a 4px base grid:
  • 4px
    - micro spacing (icon gaps)
  • 8px
    - tight spacing (within components)
  • 12px
    - standard spacing (between related elements)
  • 16px
    - comfortable spacing (section padding)
  • 24px
    - generous spacing (between sections)
  • 32px
    - major separation
所有间距都基于4px网格：
  • 4px
    - 微间距（图标间隙）
  • 8px
    - 紧凑间距（组件内部间距）
  • 12px
    - 标准间距（相关元素之间的间距）
  • 16px
    - 舒适间距（区块内边距）
  • 24px
    - 宽松间距（区块之间的间距）
  • 32px
    - 大区块分隔间距

Symmetrical Padding

对称内边距

TLBR must match. If top padding is 16px, left/bottom/right must also be 16px. Exception: when content naturally creates visual balance.
css
/* Good */
padding: 16px;
padding: 12px 16px; /* Only when horizontal needs more room */

/* Bad */
padding: 24px 16px 12px 16px;
上下左右（TLBR）必须一致。如果顶部内边距是16px，左、下、右内边距也必须是16px。例外情况：内容本身已经能形成视觉平衡的时候可以调整。
css
/* 正确 */
padding: 16px;
padding: 12px 16px; /* 仅当横向需要更多空间时使用 */

/* 错误 */
padding: 24px 16px 12px 16px;

Border Radius Consistency

圆角一致性

Stick to the 4px grid. Sharper corners feel technical, rounder corners feel friendly. Pick a system and commit:
  • Sharp: 4px, 6px, 8px
  • Soft: 8px, 12px
  • Minimal: 2px, 4px, 6px
Don't mix systems. Consistency creates coherence.
遵循4px网格体系。锐角更有技术感，圆角更友好，选一套体系坚持使用：
  • 锐利风格：4px, 6px, 8px
  • 柔和风格：8px, 12px
  • 极简风格：2px, 4px, 6px
不要混用不同体系，一致性才能带来视觉连贯性。

Depth & Elevation Strategy

深度与层级策略

Match your depth approach to your design direction. Depth is a tool, not a requirement. Different products need different approaches:
Borders-only (flat) — Clean, technical, dense. Works for utility-focused tools where information density matters more than visual lift. Linear, Raycast, and many developer tools use almost no shadows — just subtle borders to define regions. This isn't lazy; it's intentional restraint.
Subtle single shadows — Soft lift without complexity. A simple 
0 1px 3px rgba(0,0,0,0.08)
can be enough. Works for approachable products that want gentle depth without the weight of layered shadows.
Layered shadows — Rich, premium, dimensional. Multiple shadow layers create realistic depth for products that want to feel substantial. Stripe and Mercury use this approach. Best for cards that need to feel like physical objects.
Surface color shifts — Background tints establish hierarchy without any shadows. A card at 
#fff
on a 
#f8fafc
background already feels elevated. Shadows can reinforce this, but color does the heavy lifting.
Choose ONE approach and commit. Mixing flat borders on some cards with heavy shadows on others creates visual inconsistency.
css
/* Borders-only approach */
--border: rgba(0, 0, 0, 0.08);
--border-subtle: rgba(0, 0, 0, 0.05);
border: 0.5px solid var(--border);

/* Single shadow approach */
--shadow: 0 1px 3px rgba(0, 0, 0, 0.08);

/* Layered shadow approach (when appropriate) */
--shadow-layered:
  0 0 0 0.5px rgba(0, 0, 0, 0.05),
  0 1px 2px rgba(0, 0, 0, 0.04),
  0 2px 4px rgba(0, 0, 0, 0.03),
  0 4px 8px rgba(0, 0, 0, 0.02);
The craft is in the choice, not the complexity. A flat interface with perfect spacing and typography is more polished than a shadow-heavy interface with sloppy details.
深度策略要匹配你的设计方向。深度是设计工具不是必填项，不同产品需要不同的策略：
仅边框（扁平化） —— 干净、技术感、高密度，适合信息密度优先的工具类产品，视觉提升优先级低于信息密度。Linear、Raycast和很多开发者工具几乎不用阴影，只用细边框区分区域，这不是偷懒，是有意的克制。
微妙单层阴影 —— 柔和的悬浮感没有复杂度，简单的
0 1px 3px rgba(0,0,0,0.08)
就足够，适合想要温和深度感又不想有多层阴影厚重感的友好型产品。
多层阴影 —— 丰富、高级、有立体感，多层阴影能打造真实的深度感，适合想要传递厚重感的产品，Stripe和Mercury用的就是这种方案，最适合需要有实体感的卡片组件。
表面色值差异 —— 背景色差不需要阴影就能建立层级，
#f8fafc
背景上的
#fff
卡片本身就有悬浮感，阴影可以强化效果，但色值已经完成了主要的层级区分工作。
选一种策略坚持使用，有的卡片用扁平边框有的用厚重阴影会造成视觉不一致。
css
/* 仅边框方案 */
--border: rgba(0, 0, 0, 0.08);
--border-subtle: rgba(0, 0, 0, 0.05);
border: 0.5px solid var(--border);

/* 单层阴影方案 */
--shadow: 0 1px 3px rgba(0, 0, 0, 0.08);

/* 多层阴影方案（按需使用） */
--shadow-layered:
  0 0 0 0.5px rgba(0, 0, 0, 0.05),
  0 1px 2px rgba(0, 0, 0, 0.04),
  0 2px 4px rgba(0, 0, 0, 0.03),
  0 4px 8px rgba(0, 0, 0, 0.02);
工艺体现在选择上，不是复杂度上。有完美间距和排版的扁平界面，比细节粗糙的多阴影界面要精致得多。

Card Layouts Vary, Surface Treatment Stays Consistent

卡片布局可以多样，表面处理保持一致

Monotonous card layouts are lazy design. A metric card doesn't have to look like a plan card doesn't have to look like a settings card. One might have a sparkline, another an avatar stack, another a progress ring, another a two-column split.
Design each card's internal structure for its specific content — but keep the surface treatment consistent: same border weight, shadow depth, corner radius, padding scale, typography. Cohesion comes from the container chrome, not from forcing every card into the same layout template.
单调的统一卡片布局是偷懒的设计，指标卡片不需要和套餐卡片、设置卡片长得一样，有的可以带迷你折线图，有的可以带头像堆，有的可以带进度环，有的可以做两栏拆分。
根据卡片的具体内容设计内部结构，但是要保持表面处理一致：相同的边框粗细、阴影深度、圆角半径、内边距比例、排版规范。连贯性来自容器的通用规则，不是把所有卡片都塞进同一个布局模板。

Isolated Controls

独立控件封装

UI controls deserve container treatment. Date pickers, filters, dropdowns — these should feel like crafted objects sitting on the page, not plain text with click handlers.
Never use native form elements for styled UI. Native 
<select>
, 
<input type="date">
, and similar elements render OS-native dropdowns and pickers that cannot be styled. Build custom components instead:
  • Custom select: trigger button + positioned dropdown menu
  • Custom date picker: input + calendar popover
  • Custom checkbox/radio: styled div with state management
Custom select triggers must use 
display: inline-flex
with 
white-space: nowrap
 to keep text and chevron icons on the same row. Without this, flex children can wrap to new lines.
UI控件需要做容器封装，日期选择器、筛选器、下拉框——这些应该是页面上经过精细设计的独立组件，不是加了点击事件的纯文本。
有自定义样式的UI永远不要用原生表单元素。原生
<select>
、
<input type="date">
等元素会渲染操作系统原生的下拉和选择器，无法自定义样式，应该构建自定义组件代替：
  • 自定义下拉框：触发按钮 + 定位下拉菜单
  • 自定义日期选择器：输入框 + 日历弹出层
  • 自定义复选框/单选框：带状态管理的样式化div
自定义下拉触发按钮必须使用
display: inline-flex
加
white-space: nowrap
 保证文本和箭头图标在同一行，不这么做的话flex子元素可能会折行。

Typography Hierarchy

排版层级

  • Headlines: 600 weight, tight letter-spacing (-0.02em)
  • Body: 400-500 weight, standard tracking
  • Labels: 500 weight, slight positive tracking for uppercase
  • Scale: 11px, 12px, 13px, 14px (base), 16px, 18px, 24px, 32px
  • 标题：600字重，紧缩字间距（-0.02em）
  • 正文：400-500字重，标准字间距
  • 标签：500字重，大写时轻微调宽字间距
  • 字号体系：11px, 12px, 13px, 14px (基础), 16px, 18px, 24px, 32px

Monospace for Data

数据用等宽字体

Numbers, IDs, codes, timestamps belong in monospace. Use 
tabular-nums
for columnar alignment. Mono signals "this is data."
数字、ID、代码、时间戳都要用等宽字体，使用
tabular-nums
保证列对齐，等宽字体传递“这是数据”的信号。

Iconography

图标规范

Use Phosphor Icons (
@phosphor-icons/react
). Icons clarify, not decorate — if removing an icon loses no meaning, remove it.
Give standalone icons presence with subtle background containers.
使用Phosphor Icons（
@phosphor-icons/react
）。图标是用来表意的不是装饰的，如果去掉图标不损失任何含义，就删掉它。
独立图标可以加微妙的背景容器提升存在感。

Animation

动效规范

  • 150ms for micro-interactions, 200-250ms for larger transitions
  • Easing: 
    cubic-bezier(0.25, 1, 0.5, 1)
  • No spring/bouncy effects in enterprise UI
  • 微交互150ms，大尺寸过渡200-250ms
  • 缓动函数：
    cubic-bezier(0.25, 1, 0.5, 1)
  • 企业级UI不要用弹簧/弹跳动效

Contrast Hierarchy

对比度层级

Build a four-level system: foreground (primary) → secondary → muted → faint. Use all four consistently.
建立四级对比度体系：前景色（主色）→ 次要色 → 弱色 → 极弱色，全程统一使用这套体系。

Color for Meaning Only

颜色仅用来表意

Gray builds structure. Color only appears when it communicates: status, action, error, success. Decorative color is noise.
When building data-heavy interfaces, ask whether each use of color is earning its place. Score bars don't need to be color-coded by performance — a single muted color works. Grade badges don't need traffic-light colors — typography can do the hierarchy work. Look at how GitHub renders tables and lists: almost entirely monochrome, with color reserved for status indicators and actionable elements.
灰色用来构建结构，只有传递信息的时候才用颜色：状态、操作、错误、成功，装饰性颜色是视觉噪音。
构建数据密集型界面的时候，要确认每一处颜色的使用都有价值，分数条不需要按性能做颜色编码，单一低饱和颜色就足够，等级徽章不需要用红绿灯配色，排版就能完成层级区分。参考GitHub渲染表格和列表的方式：几乎全是单色调，只有状态指示器和可操作元素才用颜色。

Navigation Context

导航上下文

Screens need grounding. A data table floating in space feels like a component demo, not a product. Consider including:
  • Navigation — sidebar or top nav showing where you are in the app
  • Location indicator — breadcrumbs, page title, or active nav state
  • User context — who's logged in, what workspace/org
When building sidebars, consider using the same background as the main content area. Tools like Supabase, Linear, and Vercel rely on a subtle border for separation rather than different background colors. This reduces visual weight and feels more unified.
页面需要有归属感，悬浮在空白里的数据表像组件演示，不是成品产品，考虑包含以下元素：
  • 导航栏 —— 侧边栏或者顶部导航，展示用户在应用中的位置
  • 位置指示器 —— 面包屑、页面标题、或者导航激活状态
  • 用户上下文 —— 登录人信息、所属工作区/组织
构建侧边栏的时候，可以考虑和主内容区用相同的背景色，Supabase、Linear、Vercel等工具都是用微妙的边框做分隔，不用不同的背景色，这样能减少视觉重量，感觉更统一。

Dark Mode Considerations

暗色模式注意事项

Dark interfaces have different needs:
Borders over shadows — Shadows are less visible on dark backgrounds. Lean more on borders for definition. A border at 10-15% white opacity might look nearly invisible but it's doing its job — resist the urge to make it more prominent.
Adjust semantic colors — Status colors (success, warning, error) often need to be slightly desaturated or adjusted for dark backgrounds to avoid feeling harsh.
Same structure, different values — The hierarchy system (foreground → secondary → muted → faint) still applies, just with inverted values.
暗色界面有不同的设计要求：
用边框代替阴影 —— 阴影在暗色背景上可见度低，更多用边框做区域区分，10-15%透明度的白色边框可能看起来几乎看不见，但已经起到了作用，不要忍不住把边框调得太明显。
调整语义化颜色 —— 状态色（成功、警告、错误）通常需要轻微降低饱和度或者调整色值适配暗色背景，避免太刺眼。
结构相同，色值不同 —— 层级体系（前景色→次要色→弱色→极弱色）仍然适用，只是用反色的色值。

Anti-Patterns

反模式

Never Do This

绝对不要这么做

  • Dramatic drop shadows (
    box-shadow: 0 25px 50px...
    )
  • Large border radius (16px+) on small elements
  • Asymmetric padding without clear reason
  • Pure white cards on colored backgrounds
  • Thick borders (2px+) for decoration
  • Excessive spacing (margins > 48px between sections)
  • Spring/bouncy animations
  • Gradients for decoration
  • Multiple accent colors in one interface
  • 夸张的投影（
    box-shadow: 0 25px 50px...
    ）
  • 小元素用大圆角（16px以上）
  • 没有明确理由的不对称内边距
  • 彩色背景上用纯白卡片
  • 2px以上的装饰性粗边框
  • 过度宽松的间距（区块之间的边距超过48px）
  • 弹簧/弹跳动效
  • 装饰性渐变
  • 一个界面里用多个强调色

Always Question

随时要自问

  • "Did I think about what this product needs, or did I default?"
  • "Does this direction fit the context and users?"
  • "Does this element feel crafted?"
  • "Is my depth strategy consistent and intentional?"
  • "Are all elements on the grid?"
  • “我是考虑了产品的需求做的设计，还是用了默认配置？”
  • “这个方向适配使用场景和用户吗？”
  • “这个元素是经过精细设计的吗？”
  • “我的深度策略是统一且有意的吗？”
  • “所有元素都对齐网格了吗？”

The Standard

规范标准

Every interface should look designed by a team that obsesses over 1-pixel differences. Not stripped — crafted. And designed for its specific context.
Different products want different things. A developer tool wants precision and density. A collaborative product wants warmth and space. A financial product wants trust and sophistication. Let the product context guide the aesthetic.
The goal: intricate minimalism with appropriate personality. Same quality bar, context-driven execution.
每一个界面都应该看起来是由执着于1像素差异的团队设计的，不是简陋，是精心打磨，并且适配特定的使用场景。
不同的产品有不同的需求，开发者工具需要精准和高密度，协作产品需要温暖和宽松空间，金融产品需要信任和专业感，让产品场景引导美学设计。
目标：带有适配个性的精致极简主义，统一的质量标准，场景驱动的落地实现。