liquid-glass

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Liquid Glass Design

Liquid Glass 设计

Build native macOS/iOS applications with Apple's Liquid Glass design and HIG.

使用Apple的Liquid Glass设计和HIG构建原生macOS/iOS应用。

Core Rules

核心规则

Three-Layer Model

三层模型

┌─────────────────────────────────────────┐
│     GLASS LAYER (Navigation/Controls)   │  ← Glass here ONLY
├─────────────────────────────────────────┤
│         CONTENT LAYER (Your App)        │  ← Never glass here
└─────────────────────────────────────────┘

Glass is ONLY for navigation floating above content. Never on content itself.

┌─────────────────────────────────────────┐
│     GLASS LAYER (Navigation/Controls)   │  ← 仅在此处使用玻璃效果
├─────────────────────────────────────────┤
│         CONTENT LAYER (Your App)        │  ← 绝不能在此处使用玻璃效果
└─────────────────────────────────────────┘

玻璃效果仅适用于悬浮在内容上方的导航栏，绝不能应用在内容本身。

Five Principles

五大原则

Content First - Glass floats above, content shines through
Depth Through Light - Lensing creates hierarchy, not opacity
Adaptive Tinting - Colors respond to background dynamically
Semantic Emphasis - Tint primary actions only
Accessibility Built-In - System handles adaptations automatically

内容优先 - 玻璃效果悬浮于上方，内容清晰透出
以光塑层次 - 通过透镜效果构建层级，而非透明度
自适应着色 - 色彩随背景动态响应
语义化强调 - 仅为主要操作添加着色
内置无障碍支持 - 系统自动处理适配

Materials (macOS 14+ / Pre-iOS 26)

材质（macOS 14+ / iOS 26之前版本）

swift

// Card with material
.padding(24)
.background(.regularMaterial, in: RoundedRectangle(cornerRadius: 16, style: .continuous))

// Material options (lightest → heaviest):
// .ultraThinMaterial, .thinMaterial, .regularMaterial (default), .thickMaterial, .ultraThickMaterial

swift

// 带材质的卡片
.padding(24)
.background(.regularMaterial, in: RoundedRectangle(cornerRadius: 16, style: .continuous))

// 材质选项（从最浅到最深）：
// .ultraThinMaterial, .thinMaterial, .regularMaterial (默认), .thickMaterial, .ultraThickMaterial

Liquid Glass API (iOS 26+ / macOS Tahoe)

Liquid Glass API（iOS 26+ / macOS Tahoe）

swift

// Basic
Button("Action") { }.glassEffect()

// Variants
.glassEffect(.regular)   // Standard UI
.glassEffect(.clear)     // Media backgrounds only
.glassEffect(.identity)  // Disabled

// Interactive (adds bounce/shimmer)
Button("Tap") { }.glassEffect(.regular.interactive())

// Multiple glass elements - MUST wrap in container
GlassEffectContainer(spacing: 30) {
    HStack {
        Button("A") { }.glassEffect()
        Button("B") { }.glassEffect()
    }
}

// Button styles
Button("Cancel") { }.buttonStyle(.glass)           // Secondary
Button("Save") { }.buttonStyle(.glassProminent).tint(.blue)  // Primary

swift

// 基础用法
Button("Action") { }.glassEffect()

// 变体
.glassEffect(.regular)   // 标准UI
.glassEffect(.clear)     // 仅适用于媒体背景
.glassEffect(.identity)  // 禁用状态

// 交互式（添加弹跳/微光效果）
Button("Tap") { }.glassEffect(.regular.interactive())

// 多个玻璃元素 - 必须包裹在容器中
GlassEffectContainer(spacing: 30) {
    HStack {
        Button("A") { }.glassEffect()
        Button("B") { }.glassEffect()
    }
}

// 按钮样式
Button("Cancel") { }.buttonStyle(.glass)           // 次要按钮
Button("Save") { }.buttonStyle(.glassProminent).tint(.blue)  // 主要按钮

Essential Patterns

核心模式

Card

卡片

swift

VStack(alignment: .leading, spacing: 12) {
    HStack {
        ZStack {
            Circle().fill(color.opacity(0.15)).frame(width: 36, height: 36)
            Image(systemName: icon).foregroundStyle(color)
        }
        Spacer()
    }
    Text(value).font(.system(size: 28, weight: .bold, design: .rounded))
    Text(label).font(.caption).foregroundStyle(.secondary)
}
.padding(20)
.background(.regularMaterial, in: RoundedRectangle(cornerRadius: 16, style: .continuous))

swift

VStack(alignment: .leading, spacing: 12) {
    HStack {
        ZStack {
            Circle().fill(color.opacity(0.15)).frame(width: 36, height: 36)
            Image(systemName: icon).foregroundStyle(color)
        }
        Spacer()
    }
    Text(value).font(.system(size: 28, weight: .bold, design: .rounded))
    Text(label).font(.caption).foregroundStyle(.secondary)
}
.padding(20)
.background(.regularMaterial, in: RoundedRectangle(cornerRadius: 16, style: .continuous))

Row with Hover

带悬停效果的行

swift

HStack { content }
.padding(16)
.background(isHovering ? Color.primary.opacity(0.04) : .clear)
.background(.quaternary.opacity(0.5), in: RoundedRectangle(cornerRadius: 12, style: .continuous))
.onHover { withAnimation(.easeInOut(duration: 0.15)) { isHovering = $0 } }

swift

HStack { content }
.padding(16)
.background(isHovering ? Color.primary.opacity(0.04) : .clear)
.background(.quaternary.opacity(0.5), in: RoundedRectangle(cornerRadius: 12, style: .continuous))
.onHover { withAnimation(.easeInOut(duration: 0.15)) { isHovering = $0 } }

Badge

徽章

swift

HStack(spacing: 8) {
    Circle().fill(isActive ? .green : .orange).frame(width: 8, height: 8)
    Text(status).font(.caption).fontWeight(.medium)
}
.padding(.horizontal, 12).padding(.vertical, 8)
.background(.regularMaterial, in: Capsule())

swift

HStack(spacing: 8) {
    Circle().fill(isActive ? .green : .orange).frame(width: 8, height: 8)
    Text(status).font(.caption).fontWeight(.medium)
}
.padding(.horizontal, 12).padding(.vertical, 8)
.background(.regularMaterial, in: Capsule())

Icon with Tinted Background

带着色背景的图标

swift

ZStack {
    Circle().fill(color.opacity(0.15)).frame(width: 32, height: 32)
    Image(systemName: icon).font(.system(size: 14, weight: .semibold)).foregroundStyle(color)
}

swift

ZStack {
    Circle().fill(color.opacity(0.15)).frame(width: 32, height: 32)
    Image(systemName: icon).font(.system(size: 14, weight: .semibold)).foregroundStyle(color)
}

Shapes

形状

swift

// Always use .continuous
RoundedRectangle(cornerRadius: 16, style: .continuous)  // Cards
RoundedRectangle(cornerRadius: 12, style: .continuous)  // Rows
RoundedRectangle(cornerRadius: 8, style: .continuous)   // Small elements
Capsule()  // Pills, badges
Circle()   // Icons

swift

// 始终使用.continuous
RoundedRectangle(cornerRadius: 16, style: .continuous)  // 卡片
RoundedRectangle(cornerRadius: 12, style: .continuous)  // 行
RoundedRectangle(cornerRadius: 8, style: .continuous)   // 小元素
Capsule()  // 药丸、徽章
Circle()   // 图标

Colors

色彩

swift

// Semantic foreground
.foregroundStyle(.primary)    // Main content
.foregroundStyle(.secondary)  // Subtitles
.foregroundStyle(.tertiary)   // Timestamps

// Backgrounds
.background(.quaternary)
.background(.quaternary.opacity(0.5))

// Accent meanings
Color.blue    // Primary actions, selection
Color.green   // Success, active
Color.orange  // Warning, loading
Color.red     // Destructive, error
Color.purple  // Premium, AI
Color.cyan    // Security

// Tinted backgrounds: always 15% opacity
.fill(color.opacity(0.15))

swift

// 语义化前景色
.foregroundStyle(.primary)    // 主要内容
.foregroundStyle(.secondary)  // 副标题
.foregroundStyle(.tertiary)   // 时间戳

// 背景色
.background(.quaternary)
.background(.quaternary.opacity(0.5))

// 强调色含义
Color.blue    // 主要操作、选中状态
Color.green   // 成功、活跃状态
Color.orange  // 警告、加载中
Color.red     // 破坏性操作、错误
Color.purple  // 高级功能、AI
Color.cyan    // 安全

// 着色背景：始终使用15%不透明度
.fill(color.opacity(0.15))

Typography

排版

swift

.font(.largeTitle).fontWeight(.bold)      // Page titles
.font(.headline).fontWeight(.semibold)    // Section headers
.font(.subheadline).fontWeight(.medium)   // Row titles
.font(.body)                               // Content (17pt default)
.font(.caption)                            // Metadata
.font(.caption2)                           // Timestamps
.font(.system(size: 28, weight: .bold, design: .rounded))  // Stats

Rules: Min 11pt. Avoid Ultralight/Thin/Light. Use system fonts for Dynamic Type.

swift

.font(.largeTitle).fontWeight(.bold)      // 页面标题
.font(.headline).fontWeight(.semibold)    // 章节标题
.font(.subheadline).fontWeight(.medium)   // 行标题
.font(.body)                               // 内容（默认17pt）
.font(.caption)                            // 元数据
.font(.caption2)                           // 时间戳
.font(.system(size: 28, weight: .bold, design: .rounded))  // 统计数据

规则： 最小字号11pt。避免使用Ultralight/Thin/Light字重。使用系统字体以支持动态类型。

Spacing (8pt Grid)

间距（8pt网格系统）

swift

// Standard values: 4, 8, 12, 16, 20, 24, 32, 40, 48

.padding(24)                    // Cards
.padding(16)                    // Rows
.padding(.horizontal, 12).padding(.vertical, 8)  // Badges

// Rule: external spacing ≥ internal spacing
VStack(spacing: 24) { CardView().padding(20) }  // Correct

swift

// 标准值：4, 8, 12, 16, 20, 24, 32, 40, 48

.padding(24)                    // 卡片
.padding(16)                    // 行
.padding(.horizontal, 12).padding(.vertical, 8)  // 徽章

// 规则：外部间距 ≥ 内部间距
VStack(spacing: 24) { CardView().padding(20) }  // 正确示例

SF Symbols

swift

// Preferred: hierarchical for depth
Image(systemName: icon).symbolRenderingMode(.hierarchical).foregroundStyle(color)

// Match weight to nearby text
Image(systemName: "gear").font(.system(size: 14, weight: .semibold))

swift

// 推荐：使用分层样式以体现层次感
Image(systemName: icon).symbolRenderingMode(.hierarchical).foregroundStyle(color)

// 匹配相邻文本的字重
Image(systemName: "gear").font(.system(size: 14, weight: .semibold))

Hit Targets

点击目标区域

swift

// MINIMUM: 44pt × 44pt
Button { } label: { Image(systemName: "gear") }
    .frame(minWidth: 44, minHeight: 44)

swift

// 最小值：44pt × 44pt
Button { } label: { Image(systemName: "gear") }
    .frame(minWidth: 44, minHeight: 44)

Animations

动画

swift

// Hover
.onHover { withAnimation(.easeInOut(duration: 0.15)) { isHovering = $0 } }

// Spring
withAnimation(.spring(response: 0.3)) { }
withAnimation(.bouncy) { }

// Entry
.opacity(appeared ? 1 : 0).offset(y: appeared ? 0 : 10)
.onAppear { withAnimation(.spring(response: 0.5, dampingFraction: 0.8)) { appeared = true } }

swift

// 悬停效果
.onHover { withAnimation(.easeInOut(duration: 0.15)) { isHovering = $0 } }

// 弹簧动画
withAnimation(.spring(response: 0.3)) { }
withAnimation(.bouncy) { }

// 入场动画
.opacity(appeared ? 1 : 0).offset(y: appeared ? 0 : 10)
.onAppear { withAnimation(.spring(response: 0.5, dampingFraction: 0.8)) { appeared = true } }

Do's and Don'ts

注意事项（可做/不可做）

DO:

Use
```
.regularMaterial
```
for cards/toolbars
Use
```
.continuous
```
on ALL rounded rectangles
Use 15% opacity for icon backgrounds
Wrap multiple glass in
```
GlassEffectContainer
```
Use 44pt minimum hit targets
Use 8pt grid spacing
Use SF Symbols with
```
.hierarchical
```

DON'T:

Apply glass to content (lists, tables)
Stack glass on glass without container
Use sharp corners
Go below 11pt text
Create touch targets < 44pt
Use full-color images on glass

可做：

为卡片/工具栏使用
```
.regularMaterial
```
所有圆角矩形均使用
```
.continuous
```
图标背景使用15%不透明度
将多个玻璃元素包裹在
```
GlassEffectContainer
```
中
使用最小44pt的点击目标区域
使用8pt网格系统设置间距
为SF Symbols使用
```
.hierarchical
```
模式

不可做：

为内容（列表、表格）应用玻璃效果
在未使用容器的情况下堆叠玻璃效果
使用尖锐边角
使用小于11pt的文本
创建小于44pt的触摸目标
在玻璃效果上使用全彩图片

Accessibility

无障碍支持

System handles automatically:

Reduce Transparency → opaquer glass
Increase Contrast → visible borders
Reduce Motion → no bouncy effects
Dynamic Type → text scales

Manual override if needed:

swift

@Environment(\.accessibilityReduceTransparency) var reduceTransparency
.glassEffect(reduceTransparency ? .identity : .regular)

系统自动处理以下内容：

降低透明度 → 玻璃效果更不透明
增加对比度 → 显示可见边框
减少动态效果 → 无弹跳效果
动态类型 → 文本自动缩放

如需手动覆盖：

swift

@Environment(\.accessibilityReduceTransparency) var reduceTransparency
.glassEffect(reduceTransparency ? .identity : .regular)

References

参考资料

For detailed patterns and examples, see:

references/components.md - Full component implementations
references/apple-hig.md - Complete Apple HIG guidelines

如需详细的模式和示例，请查看：

references/components.md - 完整组件实现
references/apple-hig.md - 完整Apple HIG指南