# 示例

两份可以直接导入的样式表，用途不同：

| 文件 | 适合谁 | 它演示什么 |
| --- | --- | --- |
| [`showcase.css`](./showcase.css) | **想学怎么写**自定义 CSS | 最小而安全的一组改动：只用设计变量、不选构建哈希类名、不写 `!important`。60 行，读得完 |
| [`acrylic.css`](./acrylic.css) | **想直接要个好看的皮肤** | 完整的亚克力（Acrylic）皮肤：渐变壁纸 + 半透明玻璃面板 + 背景模糊。约 400 行，覆盖全界面 |

两份都是**导入即用**，不改动仓库里的任何东西。

## 用它

1. 打开 **设置 → 通用 → 自定义 CSS**；
2. 点「**导入**」选中要用的那份（会作为新的样式表加入 `~/.dsh/custom-css/`，原文件不受影响）；
3. 想还原就在文件下拉里选回原来的样式表 —— 或者用「重置」清空当前文件。

## `acrylic.css` 怎么调

它的做法是：**整个界面只有一层有颜色**（壁纸），其余全部透明。
靠的是**给 DSH 的背景令牌重新赋值**，不是逐个控件去覆盖 —— 所以它不会漏、也不会叠。

**只改文件开头 §1 的变量**：

| 变量 | 作用 | 默认 |
| --- | --- | --- |
| `--dsh-acrylic-tone-a/b/c` | 壁纸的三个色相（用 DSH 的静态色令牌） | 蓝 / 绿 / 琥珀 |
| `--dsh-acrylic-base-alpha` | 最底层（body / frame / 右栏整列）留多少白 | `14%` |
| `--dsh-acrylic-layer-alpha` | 层：卡片、菜单、对话框、标签条 | `30%` |
| `--dsh-acrylic-chip-alpha` | 小件：按钮、侧栏、模块底 | `34%` |
| `--dsh-acrylic-input-alpha` | 输入区（字最密） | `46%` |
| `--dsh-acrylic-drift` | 壁纸漂移周期，越大越省电 | `48s` |

**按面积分档，这是最要紧的一条规律**：白玻璃叠在浅色壁纸上，浓度高了**渲染出来就是白的**，
看起来像"根本没做效果"。所以面积越大浓度必须越低。**觉得不够透就调小，不是调大。**

**这里没有"模糊"和"圆角"参数**：

- 不模糊 —— 只有对话框和菜单（浮在文字之上）有模糊；给几十个元素加 `backdrop-filter`
  是上一版的失败做法，嵌起来就是一团糊。
- 不设圆角 —— DSH 的对话框、菜单、卡片各有自己的圆角规格，皮肤不动它的几何。

### 为什么是"改令牌"而不是"改元素"

实测 DSH 设背景的规则里 **45 条有 44 条是 `var(--dsw-…)`**，只有 `body` 自己一条是字面量。
而 `--dsw-alias-bg-base` 这一个令牌就被 **31 条规则**使用（body、frame、右栏、遮罩…）。
所以改一个令牌等于改一片，而且**不需要知道任何组件叫什么名字** ——
连渲染在应用根节点之外的对话框和菜单也自动跟着变。

反面教材就在这个仓库的历史里：上一版用 `[class*="_newSession"]` 去覆盖，结果
**一个"新会话"按钮里四层元素各被刷了一层白**（`newSession` ⊃ `Content` ⊃ `LabelMax` ⊃ `Label`），
四层 40% 白叠起来就是一块糊的实心。这正是"改来改去不行"的机制原因。

### 三条不要破坏的约束

| 约束 | 为什么 |
| --- | --- |
| **容器内部不许自己画东西** | 一个区域只该有一层外观。内部根若也有底色，会和容器**叠加**（实测侧栏 34% + 34% 渲染成 56%，比设计值浓一倍） |
| **禁写 `border` 与 `background` 简写** | 它们会隐式重置 `border-radius` / `background-image`。实测 `border: 0.5px solid …` 把「标准模式」按钮清成了直角 |
| **别动交互令牌** | `--dsw-alias-interactive-bg-hover` 等承担悬停/选中反馈；透明化它们会让界面"死掉" |

这三条由 `npm run audit`（`tests/audit-skin.mjs`）把关：它会报出未登记的令牌、
`border`/`background` 简写、以及 `[class*=]` 选择器数量失控（那通常意味着又回到了逐元素覆盖）。

### 换掉壁纸

§2 那五团光斑就是壁纸。想换成纯色，把 `body::before` 整块删掉、在 `body` 上写
`background-color: <你的颜色>` 即可。

### 关掉壁纸漂移

删掉 §1 末尾那段 `@media (prefers-reduced-motion: no-preference)` 里的 `animation`。
如果系统本身设了「减少动态效果」，它已经不会动。

## 三条经验（写自己的样式表时）

| 经验 | 原因 |
| --- | --- |
| 需要压过内置样式时用 `!important` | 自定义样式与内置样式表特异性相同时，谁后插入谁赢，而插入时机不受你控制（见 [`docs/known-issues.md`](../docs/known-issues.md)） |
| 别长期依赖构建哈希类名（`hHd-Xa_footArea`） | 名字随 DSH 版本变；要用就从 DOM 里现抓，且抓类名的正则**必须包含 `-`** |
| `:has()` 只写一层 | 嵌套 `:has()` 会让 Chrome 抛 `is not a valid selector`，**整条规则被静默丢弃** |

## 写玻璃材质时的两条额外经验（`acrylic.css` 踩出来的）

| 经验 | 原因 |
| --- | --- |
| **变量引用 DSH 令牌时，必须定义在 `body` 上，不能放 `:root`** | DSH 把全部 `--dsw-*` 定义在 **`body`** 上。在 `:root` 里写 `--x: var(--dsw-…)` 会解析成空值，接着**整条依赖它的声明被静默丢弃**（壁纸就是这么消失的，浏览器不报错） |
| **玻璃面加在"拥有底色的那个元素"上** | 给祖先加会形成 backdrop root，嵌套菜单与 fixed 浮层会跟着受影响（DSH 自己的注释也强调这点）。而且要留意：常见容器往往是**实心白**，得先把它的底让开，玻璃才透得上来 |
| **壁纸这类固定尺寸的元素，`inset` 别乱扩** | 写 `inset: -20%` 想给动画留余量，会让元素比视口大 40%，于是 `radial-gradient(… at 82% …)` 的右边缘落到**视口之外**，右半边只剩 `transparent` —— 看起来像"壁纸只铺了左半边" |

更多（描述符块、自定义属性动画、host 半需重启等）见 [`docs/known-issues.md`](../docs/known-issues.md)。