# 文档

[← 返回 README](../README.md)

按「想做什么」找，不按目录结构找。

---

## 我刚装上，想让它跑起来

| 文档 | 解决什么 |
| --- | --- |
| [安装](./install.md) | 三种装法、**装错时每个症状对应哪一步漏了**、卸载与换版本 |
| [三分钟上手 · 它是什么](./getting-started.md) | 第一条样式怎么写、样式表放在哪、为什么用文件而不是浏览器存储 |
| [自定义壁纸](./wallpaper.md) | 不写 CSS 也能给界面换一张背景图（入口在插件详情页里） |
| [已知坑](./known-issues.md) | 写完了没生效时**先看这里**（前两条能解释大多数情况） |

## 我在用它写样式

| 文档 | 解决什么 |
| --- | --- |
| [编辑器](./editor.md) | 快捷键、查找替换、格式化、高亮与补全、外部改动同步、历史版本、问题检测 |
| [自定义壁纸](./wallpaper.md) | 换背景图：四个控件怎么调、图片存在哪、和皮肤谁说了算、section 怎么画 |
| [元素拾取器](./picker.md) | 不想抄类名时怎么点选元素、候选怎么排序、令牌反查 |
| [规则面板](./rule-panel.md) | 点选择器展开的那块：属性字典 112 条、值写错了会怎样、声明模板 |
| [格式校验](./validation.md) | 状态行那行红字怎么读、变量体检在查什么 |
| [控件](./controls.md) | 表头那几个按钮与菜单、窄窗口下谁先让位、强调显示 |
| [国际化](./i18n.md) | 跟着 DSH 的语言走：哪些已双语、哪些还是中文、加一条文案的正确姿势 |
| [写 CSS 用的页面 API](./authoring-api.md) | 控制台里的 `window.dshCss`：读写样式表、查命中数、找死选择器、反查令牌、点选元素 |
| [`examples/acrylic.css`](../examples/acrylic.css) | 可直接导入的**亚克力皮肤**：渐变壁纸 + 玻璃面板 + 背景模糊 |
| [`examples/showcase.css`](../examples/showcase.css) | 60 行的最小示例（想学怎么写就看它） |

## 我想改这个插件

| 文档 | 解决什么 |
| --- | --- |
| [**交接文档**](./handoff.md) | **先读这个**：现状、怎么验、预览块的四条定死的规则、踩过的坑、还剩什么 |
| [**预览块 v4 重写方案**](./preview-v4.md) | **下一版的设计依据**：为什么推倒重来（12 条带行号的诊断）、组件边界、kit 增补、分 7 步落地 |
| [开发](./development.md) | 命令表、开发实例（3081）、视觉探针、两条硬约束 |
| [CSS 公共层](./shared-layer.md) | 随插件发布的样式基座（`--dsl-g-*` 令牌 + 三个零特异性原语），以及它的源码块同步 |
| [UI 组件库](./ui-kit.md) | **加界面只调用 `ui.*`**：控件、行布局、反馈、每个组件的状态 |
| [测试与巡检](./testing.md) | 两套冒烟测试守什么、五个审计、CI 三个工作流、发版 |
| [仓库结构](./repo-map.md) | 每个目录是干什么的、哪些是产物 |
| [设计一致性](./design-tokens.md) | 每处控件规格的出处 —— **改样式前先读** |
| [`docs/naming.md`](./naming.md) | 每个界面元素**唯一的名字**（提需求、写代码、记日志都用它） |
| [CONTRIBUTING.md](../CONTRIBUTING.md) | 硬约束与发版流程 |

## 我在排查问题

| 文档 | 解决什么 |
| --- | --- |
| [已知坑与已知限制](./known-issues.md) | 坑 = 这么写会出事；限制 = 它本来就不做这件事 |
| [兼容性](./compat.md) | 支持哪些 DSH 版本、**换代时的两种失效模式怎么判别** |
| [host 侧文件接口](./api-host.md) | 为什么控制台直接打接口会 401、各端点与文件名规则 |
| [README · 兼容性](../README.md#兼容性) | 验证矩阵（自动维护） |

## 规划中

| 文档 | 解决什么 |
| --- | --- |
| [预览块](./preview.md) | **设计全部实现**（0.8.0 → 0.13.0）：单屏 + 对比 + 状态芯片 + 合成样本 + 全屏视图（0.12.0 重新设计），v4（0.13.0）把控件统一到 `ui.*`、预览固定在面板顶部、去掉卡片导航 |
| [令牌管理](./token-manager.md) | **阶段 1、2 已实现，材质令牌默认值已上线**：清单 + 搜索（0.5.0），接管 / 撤销（0.6.0），`--dsh-material-*`（0.6.1）；预设按钮待做 |
| [预设](./presets.md) | **已实现（0.7.0）**：亚克力 / 毛玻璃 / 云母 / 细描边卡片，复用模板按钮，写入是一次编辑 |