hzwx-theme-tool

HZWX 设计变量（Design Token）智能提示插件。让你在写 var(--hzwx-*) 时看得见颜色、看得懂语义、打得快。

能力

能力	触发方式	效果
颜色 + 中文语义 hover	鼠标悬停在 `--hzwx-color-neutral-1` 上	色块卡片、色值、明暗、建议前景色、SCSS 变量名、定义位置、中文用途说明
自动补全	在 `var(` 内输入 `-` 或 `Ctrl/Cmd+Space`	39 个变量按品牌 → 中性 → 功能 → 基础 → 辅助 → 字体排序，右侧带色值，详情面板带色块
行内颜色装饰	自动	`var(--hzwx-*)` 左侧直接出现颜色方块（VS Code 原生色块）
跳转定义	`Cmd/Ctrl + 点击` 变量名	跳到设计包 `rootVar.scss` 对应行
拼写纠错	悬停未定义的 `--hzwx-*`	提示「未在设计规范中定义」并给出最接近的变量
变量浏览器	命令面板 `HZWX 设计变量：浏览全部变量`	搜索 + 回车插入到光标

css / scss / sass / less / postcss / vue / svelte / html / astro / javascript(react) / typescript(react)

可在设置里通过 hzwxTheme.languages 收窄。

变量快照内置在扩展里（src/data/tokens.json），运行时零文件依赖。快照由脚本从设计包解析生成：

npm run gen          # 默认读 /Users/shawei/_work/_hzwx/hzwx-design/packages/style/rootVar.scss
npm run gen -- /abs/path/to/rootVar.scss

脚本会顺着 @use './var.scss' 把 SCSS 变量一起解析，并对 #{$color-brand} 这类插值做递归求值，因此快照里存的是最终色值而不是 #{$...}。

设计包更新颜色后：npm run gen → npm run package → 重装 vsix。

配置覆盖：settings 里的 hzwxTheme.descriptions（最高）
自定义 JSON：工作区 .hzwx-theme/colorDescriptions.zh.json，或由 hzwxTheme.descriptionsFile 指定
SCSS 注释：rootVar.scss / var.scss 里变量上方的 // 注释
命名规则自动推断（兜底）

生成第 2 项的内容：命令面板执行 HZWX 设计变量：导出中文描述 JSON。

--hzwx-color-other-1 ~ 9 这类无法从命名推断用途的变量，默认描述带「补充色板，具体用途待补充」，建议导出 JSON 后改成真实语义。

npm install
npm run build      # esbuild 打包到 dist/extension.js
npm run watch      # 增量构建
npm run typecheck  # tsc --noEmit

按 F5 启动 Extension Host 调试。

npm run package       # 产出 hzwx-theme-tool.vsix
npm run install:local # 打包并安装到本机 VS Code

或手动：VS Code → 扩展 → ... → 从 VSIX 安装。

配置	默认	说明
`hzwxTheme.enabled`	`true`	总开关
`hzwxTheme.languages`	全部	生效的语言列表
`hzwxTheme.hover.enabled`	`true`	变量 hover
`hzwxTheme.hover.showColorSwatch`	`true`	hover 里渲染色块
`hzwxTheme.hover.warnUnknown`	`true`	未定义变量告警
`hzwxTheme.completion.enabled`	`true`	自动补全
`hzwxTheme.completion.triggerMode`	`in-var`	`in-var` 仅 `var()` 内触发；`anywhere` 任意位置
`hzwxTheme.colorDecorator.enabled`	`true`	行内颜色方块
`hzwxTheme.definition.enabled`	`true`	跳转定义
`hzwxTheme.descriptions`	`{}`	内联覆盖中文描述
`hzwxTheme.descriptionsFile`	`null`	自定义描述 JSON 路径