Liquid Glass Web 是做什么的？
将 Liquid Glass 材质模型适配到浏览器的 Web 设计系统。内容位于不透明层上，导航和控件等轻薄半透明功能层浮于内容之上。该实现是对 Apple“Adopting Liquid Glass”公开指南的独立适配，不包含任何 Apple 字体、符号或资源。
技能包含内容
| 路径 | 用途 |
|---|---|
assets/tokens.json | 真相之源：颜色（含 light、dark、contrast 三个主题）、字体、间距、圆角、尺寸、材质、阴影。 |
assets/tokens.css | 编译后的 CSS 自定义属性及类型类。修改令牌后请通过 scripts/build_tokens_css.py 重新生成。 |
assets/liquid-glass.css | 组件样式（lg-* 类），框架无关。 |
assets/liquid-glass.react.js | 可选的 React 18 捆绑包，暴露 window.LG（传统脚本方式，需依赖 window.React 和 window.ReactDOM）。 |
assets/liquid-glass.d.ts | 组件属性类型声明，兼作文档。 |
assets/example.html | 纯 HTML 编写的完整屏幕示例，可复制其结构。 |
references/brand-book.md | 设计原则、语气、颜色、材质、排版、布局、动效、图标、无障碍。设计前请先阅读。 |
references/html-api.md | 无 React 版本下每个组件的标记语法。 |
references/components/<Name>.md | 每个组件的使用指南：消费者需提供的内容、注意事项。 |
scripts/contrast_check.py | 对每个主题下所有令牌对（包括最坏情况的玻璃效果）进行 WCAG 对比度检查，失败时返回退出码 1。 |
scripts/build_tokens_css.py | 将 tokens.json 编译为 tokens.css。 |
工作流程
A. 构建或重构 UI
- 阅读
references/brand-book.md，然后阅读references/components/中所需的组件文件。 - 将
assets/tokens.css和assets/liquid-glass.css复制到项目中，并按顺序加载。在 React 项目中，可使用捆绑包或参照references/html-api.md中的标记进行移植。其他框架则请移植标记。 - 布局两个层：
- 内容层： 不透明，位于
canvas和surface上。所有需要阅读的内容都放在这里。 - 玻璃层： 仅限导航和控件，浮动于滚动内容之上（如工具栏、标签栏、分组、菜单、中型面板）。
- 内容层： 不透明，位于
- 按令牌名称使用设计变量（如
var(--accent)）。凡是有对应令牌的，切勿硬编码颜色、圆角或间距值。 - 完成前请执行下方检查清单。
B. 品牌重塑（新的强调色或中性色）
- 仅修改
assets/tokens.json中的值。保留令牌名称，因为 CSS 依赖它们。 - 每个更改的强调色都必须在每个主题中拥有配套令牌：
accent、on-accent、accent-text、accent-glass、focus-ring。如果深色主题的强调色较浅，则on-accent必须较深。 - 运行
python3 scripts/contrast_check.py assets/tokens.json，调整值直到输出RESULT: PASS。请勿降低检查阈值。 - 运行
python3 scripts/build_tokens_css.py assets/tokens.json > assets/tokens.css。 - 除非另有要求，否则保留玻璃令牌（
glass-fill、glass-edge、glass-lift、glass-blur）。玻璃层应保持无色。
不可协商的规则
- 玻璃仅用于功能层。切勿在列表行、内容卡片或页面分区上使用玻璃，也不可在玻璃上叠加玻璃。
- 常规玻璃上的文字仅可使用
ink、ink-glass-muted、accent-glass或critical-glass。切勿在玻璃上使用ink-secondary、accent-text或critical，它们会在深色或明亮内容上失效。 - 清晰玻璃（
lg-glass--clear）仅用于照片、视频或地图之上，并需在其下方放置lg-dim。其上只能放置图标和 19px 以上的粗体标签。 - 每个视图只允许一个
prominent按钮。所有控件应为胶囊形状（radius-full）。嵌套圆角应保持同心：内层圆角 = 外层圆角 − 内缩量。 - 触摸目标至少为
target-min（44px）。每个仅含图标的控件都必须有aria-label。 - 状态指示必须同时包含图标和文字；颜色本身不得单独传达含义。
- 尊重
prefers-reduced-transparency、prefers-contrast和prefers-reduced-motion用户偏好。CSS 已处理这些，请勿覆盖。 - 禁止使用 Apple 的 SF Symbols、Apple 字体或徽标。字体栈使用设备系统字体；React 捆绑包中的图标集为原创占位符。
交付前检查清单
- 工具栏后方无自定义背景；内容应在它们下方滚动，当栏重叠内容时需有
lg-edge滚动边缘效果。 - 玻璃元素数量较少（仅限栏、分组、菜单、面板）。其他元素不应使用玻璃。
- 已在
data-theme="light"、"dark"和"contrast"三种主题下检查画面。 - 若修改了令牌：
contrast_check.py输出 PASS，且已重新生成tokens.css。 - 键盘操作：所有控件均可通过键盘到达，并显示
focus-ring轮廓。 - 文案：操作按钮使用句子式大小写，仅列表分区标题使用首字母大写，动词在前，不使用 emoji。