Premium Liquid Glass（高级液态玻璃界面）

高级液态玻璃

目标：打造一个让人感觉平静、有空间感和高端感的界面。玻璃是一种用于浮在内容之上的控制材质，而不是可以随意到处使用的风格。成功测试：用户会说“这感觉很干净、有层次感”，而永远不会说“有人给所有东西都加上了模糊效果”。

本技能控制着 Android (Compose)、iOS (SwiftUI)、Flutter 和 Web (CSS/Tailwind) 上的材质、层次、深度、动效和可访问性。项目的自有品牌控制着标识、调色板和文案。默认品牌标记定义在 assets/tokens.json 中。

0. 安全与范围

• 仅在用户选择的项目内工作。不要读取密钥、密钥或环境变量。不要发起网络请求或安装软件包；如果需要某个库，仅提及其名称，让用户自行决定。
• 在修改现有应用代码之前，先提出更改建议。
• 仅使用虚构的示例内容。
• 在非 Apple 平台上切勿使用 Apple 字体（San Francisco）或 SF Symbols。请使用 Inter、Roboto 或平台适配套字体，搭配 Material Symbols/Lucide 风格的图标。在 iOS (SwiftUI) 上，原生 SF Symbols 和系统字体为标准。
• 标记为 (VERIFY) 的事实可能随 API 版本过时；请始终对照项目依赖项进行确认。

1. 五项硬性规则

1. 内容永远不能是玻璃。卡片、列表行、表单、页面背景和媒体保持不透明或柔软表面。
2. 玻璃仅用于浮动层：底部导航药丸、滚动内容上的顶部栏、浮动操作按钮、底部面板和菜单、搜索栏、Toast/提示条、以及小型浮动筹码。
3. 玻璃上绝不能嵌套玻璃。在玻璃表面内部，使用实心填充、细微分隔线或透明度差异来分隔项目。
4. 可读性优先于美观。正文文本在最差背景上需要 4.5:1 的对比度（大文本和图标为 3:1）。运行 scripts/contrast_check.py。
5. 每个玻璃表面都有实体降级方案（旧版操作系统、Reduce Transparency 无障碍设置、省电模式、低 GPU 性能、或缺乏 backdrop-filter 的浏览器）。

在将玻璃应用于任何元素之前，请先问自己：“这种材质传达了什么样的功能角色？” 有效答案：它浮在滚动内容之上；它是临时的或上下文相关的；它必须在内容在其下方移动时保持可触及。没有答案 = 不使用玻璃。

2. 通用工作流程

1. 检查：目标平台（Android Compose、iOS SwiftUI、Flutter、Web）、操作系统版本限制、现有主题标记、导航结构、无障碍要求和性能目标。
2. 层次映射（在编写任何代码之前）：元素 -> 层级（内容/结构/浮动）-> 是否玻璃 -> 层级 -> 原因。将其与方案一起呈现。
3. 标记：从 assets/tokens.json 开始；调整品牌颜色；为每种模式下的每个层级重新运行 python scripts/contrast_check.py --tokens assets/tokens.json。
4. 使用平台模板构建：
   • Android: assets/GlassTheme.kt & references/compose-implementation.md
   • iOS (SwiftUI): assets/GlassView.swift & references/swiftui-implementation.md
   • Flutter: assets/glass_theme.dart & references/flutter-implementation.md
   • Web (CSS/Tailwind): assets/glass.css、assets/tailwind-glass.config.js & references/web-implementation.md
5. 验证：使用 references/review-checklist.md 和 scripts/audit_compose.py (Android) 进行检查。报告证据（对比度比率、每个屏幕的玻璃层数、降级渲染）。

3. 材质层级（起始值）

层级	用途	模糊值	填充色 (深色模式)	填充色 (浅色模式)
none	内容、卡片、列表、背景	-	不透明表面	不透明表面
thin	仅图标或大标签控件、筹码	16 dp/px	ink @ 0.55	white @ 0.55
regular	导航药丸、顶部栏、搜索栏、FAB、toast	24 dp/px	ink @ 0.66	white @ 0.70
thick	面板、菜单、对话框、文本密集覆盖层	32 dp/px	ink @ 0.78	white @ 0.82
scrim	模态面板后面的遮罩	0-8 dp/px	black @ 0.20-0.45	black @ 0.20-0.45

详细信息及已验证的对比度数值：references/tokens.md。填充色使用表面 ink 颜色着色，而非纯白色，这样深色模式下的文字在明亮背景下仍能保持可读性。

4. 平台现实检查

Android (Jetpack Compose)

• Modifier.blur() / RenderEffect 仅模糊元素自身内容，而非其背后的内容。真正的背景模糊需要库（Haze 使用 Apache-2.0 许可，支持 Compose）或针对对话框的窗口模糊（API 31+）。
• 模糊效果需要 Android 12 (API 31) 或更高版本 (VERIFY)。低于 API 31 时，始终渲染实体降级表面。
• 预算：每个屏幕最多 2-3 个同时模糊的层。切勿模糊列表项。
• 完整细节：references/compose-implementation.md。

iOS (SwiftUI)

• 使用原生 SwiftUI 材质：.ultraThinMaterial (thin 层级)，.thinMaterial / .regularMaterial (regular 层级)，以及 .thickMaterial (thick 层级)。
• 使用 RoundedRectangle(cornerRadius: ..., style: .continuous) 支持 iOS 连续圆角。
• 对于底部面板使用 .presentationBackground(.thinMaterial) (iOS 16.4+)。
• 完整细节：references/swiftui-implementation.md。

Flutter

• 使用 BackdropFilter 搭配 ImageFilter.blur(sigmaX: tier.blur, sigmaY: tier.blur)，并用 ClipRRect 包裹。
• 务必将其包裹在 RepaintBoundary 中，以防止每一帧都重绘背景模糊。
• 切勿在 ListView.builder 或 GridView.builder 的项内部使用 BackdropFilter。
• 完整细节：references/flutter-implementation.md。

Web (CSS / Tailwind CSS)

• 始终同时包含 -webkit-backdrop-filter: blur(...) 和 backdrop-filter: blur(...) 以支持跨浏览器（Safari 需要 -webkit-）。
• 始终为不支持 backdrop-filter 的旧浏览器指定 @supports not (backdrop-filter: blur(1px)) 降级方案。
• 始终实现 @media (prefers-reduced-transparency: reduce) 降级方案，使用实体背景。
• 完整细节：references/web-implementation.md。

5. 无障碍模式 (全部实现)

• 降低透明度：检查系统无障碍标志（Web 上的 prefers-reduced-transparency、SwiftUI 中的 accessibilityReduceTransparency、Flutter 中的 accessibleNavigation、或 Android 上的应用内切换）。将玻璃表面替换为带有可见 1 dp/px 边框的实体表面标记。
• 大字体 (200%) 和屏幕阅读器：没有仅通过颜色传达的信息；仅图标控件上必须有标签；符合逻辑的焦点顺序。
• 减少动态效果：将弹簧动效替换为快速淡入淡出（150 毫秒）；保留状态反馈。
• 触摸目标：最小 48x48 dp / 44x44 pt。手势（滑动）必须提供按钮或可访问的菜单替代方案。

6. 组件与几何规范

导航药丸、顶部栏、FAB、面板、搜索栏、筹码、卡片和分类堆叠的规格：references/components.md。 使用统一的圆角半径：

• 小型筹码：999（完全药丸形状）
• 小型控件/按钮：16 dp/pt
• 内容卡片（不透明）：24 dp/pt
• 浮动导航药丸：28 dp/pt
• 模态面板：32 dp/pt
• 嵌套元素半径 = 外部半径 - 内边距。

7. 动效与触觉反馈

弹簧动画（250-350 毫秒持续时间），短淡入淡出（150 毫秒），最小或零弹跳过冲。在阈值触发时（滑动提交、药丸选择）提供细微的触觉反馈。按下状态：缩放至 0.97 并伴有柔和的高亮效果。尊重系统减少动态效果设置。

8. 图像提示模式 (参考截图)

在生成 UI 模拟提示时，遵循 references/image-prompts.md：每个提示一张屏幕、自包含样式块、精确的屏幕文本、玻璃仅用于浮动层、“卡片不透明”、平台准确的状态栏。将输出作为布局和情绪参考，然后使用设计标记在代码中实现。

9. 审查模式

当被要求审查设计或代码库时：

1. 将每个 UI 元素分类到其层级（内容 vs. 浮动）。
2. 计算每个屏幕的玻璃层数（强制执行最多 2-3 层的预算）。
3. 扫描反模式（玻璃用于卡片、玻璃嵌套在玻璃中、缺少降级方案）。
4. 运行对比度验证 (python scripts/contrast_check.py --tokens assets/tokens.json)。
5. 对于 Android 项目，运行 python scripts/audit_compose.py <src>。
6. 按严重性列出发现，并参考 references/review-checklist.md 提供纠正指导。

10. 参考资料与文件

• references/principles.md - 核心空间原则与 Apple 设计灵感
• references/tokens.md - 标记表、颜色值和已验证的对比度数值
• references/compose-implementation.md - Android Compose 架构与代码片段
• references/swiftui-implementation.md - iOS SwiftUI 架构与代码片段
• references/flutter-implementation.md - Flutter 架构与代码片段
• references/web-implementation.md - Web CSS 与 Tailwind CSS 架构与代码片段
• references/components.md - 组件几何规范、布局和状态
• references/image-prompts.md - AI 模拟生成的提示模板
• references/review-checklist.md - 质量检查点与反模式
• scripts/contrast_check.py - WCAG 对比度验证脚本
• scripts/audit_compose.py - Compose 静态扫描脚本
• assets/tokens.json - 完整的设计标记模式
• assets/GlassTheme.kt - Jetpack Compose 模板
• assets/GlassView.swift - SwiftUI 模板
• assets/glass_theme.dart - Flutter 模板
• assets/glass.css 与 assets/tailwind-glass.config.js - Web CSS 与 Tailwind 模板