deeplethe/solid-glass · 上手攻略
- 仓库：deeplethe/solid-glass
- 链接：https://github.com/deeplethe/solid-glass
- 分类：engineering / design-system / ai-apps
- 作者：spark
- 更新：2026-10-15
§0 自检三证
- GitHub URL：已 fetch（README + GitHub Pages 文档已读，200 OK）。
- 顶会 venue+年份：不适用——本仓库为设计系统/前端样式库，无学术发表。
- README 子模块 anchor：已落（
blocks/docs/material/docs/installation/create/status-glyph/agent-workspace）。 - ⚠️ 仓库卡片标注成熟度为
experimental，周增 +1844 stars 但总星仅 757，作者署名deeplethe，组织关系未独立核实。
一、是什么
deeplethe/solid-glass 是一个专为 AI 应用（聊天、Agent、实时流式响应）打造的 UI 设计系统，作者把它定位在「flat design」与「Liquid Glass」之间的折中地带：
- Flat design：纯色块，没有表面质感；信息密度高但缺乏层级。
- Liquid Glass：高度透明 + 折射 + 流体效果；在长文本页面上，背景会和正文"打架"。
- Solid Glass：只让边缘（outline）透出来——既保留玻璃材质暗示，又不干扰阅读。
它的视觉关键词是四个：触觉（Tactility）、精确（Precision）、物理感（Physicality）、材质感（Materiality）。核心实现是 一份 CSS（src/solid-glass.css），通过 data-slot 与 shadcn/ui 组件既有的 class 名挂钩，所以你已有的 shadcn 组件不需要改任何代码就能换上这套外观。
二、解决什么问题
AI 应用界面有几个棘手的特性：
- 流式响应：文字、Token、Agent 步骤持续刷新，普通 UI 容易闪烁。
- 状态密集：loading / thinking / done / error / ask-user 同时存在，色块和动效容易被滥用。
- 决策等待：用户需要随时看清"现在轮到我说话"——视觉层级不能糊。
Solid Glass 的策略是：用中性表面减少视觉干扰，用层次（厚度/阴影/空间）建立层级，把颜色和动效留给真正有意义的反馈。它自带一套 Agent 专用组件：status-glyph（三点光表示轮次进行中与状态）、turn-status、composer、tool-steps、diff-view、ask-card、context-ring、task-notice、reasoning——这些正是 AI 应用中最难"不喧宾夺主"的部件。
三、快速安装
3.1 前置条件
- 已有的 shadcn/ui 项目（React 19 + Tailwind CSS 4 + Base UI / base-nova 组件）。
- Node 环境可用
npx shadcn@latest。
3.2 三步安装
# 1) 初始化（如果还没做过）
npx shadcn@latest init
# 2) 拉 Solid Glass 主样式表
npx shadcn@latest add deeplethe/solid-glass/solid-glass
# 3) 按需拉它的 Agent 专用组件（示例：状态指示器）
npx shadcn@latest add deeplethe/solid-glass/status-glyph
3.3 在 globals.css 里接入
⚠️ 重要：先删除 shadcn init 写出的 :root 与 .dark 颜色变量——Solid Glass 用同样的变量名定义自己的配色，否则会冲突。导入顺序如下：
@import "tailwindcss";
@import "tw-animate-css";
@import "shadcn/tailwind.css";
@import "./solid-glass.css";
3.4 本地预览文档站
git clone https://github.com/deeplethe/solid-glass.git
cd solid-glass
npm install
npm run dev # 默认 http://localhost:5191
/dev/banner（仅开发态）会画一张 banner；/dev/examples 会挂载全部示例并把失败的列出来，支持 ?q=button,card、?theme=light、?hover=<selector>、?click=<selector> 等调试参数。
四、核心用法
4.1 Material 页面：理解四个规则
https://deeplethe.github.io/solid-glass/docs/material 给出四条"做玻璃"的硬规则：
- 饰面在边缘（finish is at the edge）——中央干净，细节落在边界。
- 重而非轻（heavy, not airy）——靠厚度建立层级，不靠空气感。
- 深度 = 厚度（depth is thickness）——阴影来自厚度而非模糊半径堆砌。
- 一种状态（one state）——避免多状态叠加造成混乱。
写自己的组件时守住这四条，整体视觉就一致。
4.2 Create 页面：旋钮式试色
https://deeplethe.github.io/solid-glass/create 提供 thickness / tint / chart colour / type / radius / rim / blur 的滑块，每改一次就即时重新生成几行 CSS——这是最实用的设计 token 探索工具，比直接改 CSS 变量直观得多。
4.3 自带组件分类速览
| 组件 | 用途 |
|---|---|
status-glyph |
三点光，表示 Agent 正在工作及所做子动作 |
panel、tag、dot-loader |
最薄的玻璃面板、小标签、等待中的点行 |
turn-status |
Agent 的当前轮次状态行 |
composer |
给 Agent 输入的输入框 |
tool-steps |
Agent 调工具的步骤列表 |
diff-view |
文件/字段差异展示 |
ask-card |
Agent 反问用户时的卡片 |
context-ring |
当前上下文窗口使用率环 |
task-notice |
后台任务通知 |
reasoning |
思考过程展示 |
4.4 扩展自己的组件
要新增"自己牌"的组件并入 registry，三件事：
- 在
src/components/ui/写.tsx，遵循 shadcn 风格：函数组件 + 每部位带data-slot+ 用cn()from@/lib/utils。 - 在
src/examples/写-demo.tsx，再为额外例子各写一个文件。 - 在
content/solid/写.mdx：front matter（title、description）、<ComponentExample name="-demo" />、Installation、Usage，以及每个 example 的小标题。
提交流程：改动进 dev 分支（PR），由维护者合并到 main——合并后文档站和 registry 同步发布。
4.5 构建产物结构
src/solid-glass.css：主题本体，所有颜色、三档玻璃厚度、单一状态、动效都在这里。registry.json：shadcn add 用的 registry，由scripts/build-registry.mjs自动生成。src/components/ui/：shadcn 组件 + Solid Glass 自带组件。src/create/、src/pages/create.tsx：旋钮式创建器，options.ts定义每个旋钮对应哪个 CSS 变量。src/blocks/、src/pages/blocks.tsx：整屏组合示例（blocks page 用/view/<name>单独展示）。scripts/build-docs.mjs：把content/转成src/docs/generated.json。
五、典型适用场景
- AI 聊天 / Agent 产品 的前端外壳——尤其是需要展示"思考过程 / 工具调用 / 上下文余量"的场景。
- shadcn/ui 项目想要"换一套更有质感的皮肤"而不重写组件。
- 深色优先 的产品（Sage Glass 默认就把 dark 设计为材质主体态，light 反而是补充）。
- 设计 token 探索 —— 用
create页面试色比改 tokens 快得多。
六、坑与注意
- shadcn 版本要求：项目用 React 19 + Tailwind CSS 4 + Base UI 组件。如果你的 shadcn 还停在 React 18 / Tailwind 3，组件 hook 可能装不上——先升 shadcn 再装 Solid Glass。
- 变量冲突：shadcn init 写出的
:root/.dark颜色变量必须删，否则会被 Solid Glass 静默覆盖，调试极痛苦。 - shadcn 组件局部修改：仓库自带的 button / input / tabs / dialog / dropdown-menu / sheet / sidebar / 表单控件等和 stock shadcn 有细微差别；样式表不依赖这些差异——所以即便你换回 stock 也不会崩，但视觉会回退一些。
- 图标/图片托管：README 的图全部存在
docs/下，文件名固定为banner-N.webp（数字递增）。换图时用新编号并改 README 链接——因为 GitHub 对同一文件地址会缓存。 SOLID_GLASS_ORIGIN与SOLID_GLASS_BASE环境变量：自己 fork 部署时需要设这两个变量，让 Solid Glass 自有组件能正确互相引用。- Registry 安装命令是 fork-aware：
npx shadcn@latest add deeplethe/solid-glass/...通过 GitHub 路径定位，所以如果维护者换了 repo 名，命令会失效。 - 成熟度 = experimental：卡片明确标 experimental，API 可能变。生产环境使用前建议锁版本或盯紧 CHANGELOG。
- 总星 757 与周增 +1848 不对称——典型"新仓库爆发"曲线，社区背书还没沉淀，长期可用性需要观察。
七、与同类对比
| 方案 | 形态 | 与 Solid Glass 的差异 |
|---|---|---|
| shadcn/ui 默认 | 极简、几乎无材质 | Solid Glass 在它之上叠了"玻璃"语言 |
| Apple Human Interface Guidelines / Liquid Glass | 系统级，平台独占 | Solid Glass 跨 Web，且主动收敛材质强度以服务长文本 |
| Material UI / Ant Design | 完整组件库 + 主题 | 体量远大；Solid Glass 只换皮肤，不接管状态机 |
| Tailwind UI / Radix Themes | 商业 / 半商业主题 | Solid Glass 走开源 + shadcn 兼容路线，集成成本更低 |
tweakcn 等主题生成器 |
一键换色 | Solid Glass 提供AI-Agent 专用组件（tool-steps、ask-card、context-ring 等），这是其差异化关键 |
如果你只是要"换个好看点的皮"，上面的通用主题更轻；如果你在做的产品有大量 Agent / 工具调用 / 上下文状态需要可视化，Solid Glass 的组件库是现成的。
八、一句话推荐结论
shadcn 项目的"AI-Agent 皮肤包"，一份 CSS + 一组 Agent 专用组件，轻接入、深色优先、设计 token 可旋钮试色；适合"不想重写组件但想换气质"的中小型 AI 前端项目，对老版 shadcn/Radix 用户不太友好，且成熟度 experimental 上生产需谨慎。