Master CSS 语言服务

#概览

使用 Master CSS 语言服务，探索项目实际支持的 class，并在编辑时检查 CSS。建议内容会读取项目 token 与定义，包括你自定义的工具类、mixin、选择器与条件。

请先准备已安装 Master CSS 的项目。扩展协助编写源码；样式表仍由框架集成交付到浏览器。

#设置 VS Code

安装官方 Master CSS 扩展，在 VS Code 打开项目文件夹，并启用字符串内补全：

{  "editor.quickSuggestions": {    "strings": true  }}

扩展通过导入 @master/css 的 CSS 入口，或声明 Master CSS 包的 package.json，发现项目上下文。仓库有多个应用时，请打开你想使用其主题的应用源文件。

#检查项目 token

在应用 CSS 入口的现有导入后，加上间距 token：

@import '@master/css';@theme {  --spacing-card: 1.5rem;}

在 HTML 文件的 class 属性中输入 p-ca。从建议中选择 p-card，再将鼠标移到完成的 class：

<article class="p-card">Field notes</article>

一个项目 token，两种编辑器检查：补全 class 名称，再检查声明。编辑器预览无法证明浏览器中哪个规则胜出。

文字说明

1. 定义. 应用样式表导入 @master/css，并在 @theme 中声明 --spacing-card: 1.5rem。
2. 补全. 在 HTML class 属性中，p-ca 会获得根据项目内容提供的 p-card 补全。
3. 检查. 将鼠标移到 p-card，会显示生成的 padding: var(--spacing-card) 声明。CSS 仍由框架集成提供给页面；渲染结果须另外验证。

Hover 的生成规则应包含 padding: var(--spacing-card)。Class 名称来自项目 token，声明保留变量引用。请在浏览器打开页面，查看实际内边距。若没有 p-card，先解决工作区上下文，再新增其他编辑器设置。

补全与 hover 验证编写上下文。实际页面也需通过构建与浏览器验证。

文字说明

一个源码 class 分成两条路径：语言服务向作者显示生成的 CSS，集成工具则将 CSS 交付给浏览器。

#保存时自动排序 class

若要获得 class 策略诊断与保存时排序，先设置代码检查，并安装 ESLint 扩展。在 editor.quickSuggestions 旁加入下列选项：

{  "editor.codeActionsOnSave": {    "source.fixAll.eslint": "explicit"  },  "eslint.codeActionsOnSave.rules": [    "@master/css/sort-classes"  ]}

现在明确执行保存时，就能按项目 ESLint 配置排序 class。只有规则列表不会启用保存操作。eslint.codeActionsOnSave.mode 保持默认 all：扩展的 problems 模式会忽略此规则筛选。详见 ESLint 扩展设置。

#编辑时检查样式

#补全 class 与条件

补全适用于已配置的 class 来源：标记属性、框架绑定属性、JavaScript 辅助函数调用、标签模板与项目专属 class 声明。建议包含工具类、属性值、颜色 token、选择器、查询与指令语法；工作区 manifest 加载后也会显示项目 token。

#阅读生成的规则

将鼠标移到 fg-blue-60:hover@sm 这类 class，检查声明、选择器状态与查询。此例只在 sm 及以上宽度的 hover 状态应用预设蓝色 token：

<a class="fg-text-body fg-blue-60:hover@sm" href="/notes">  Field notes</a>

#语法高亮

扩展在 CSS 类文档中高亮指令语法，并用语义 token 标示 class 列表区段：声明、值、选择器、查询、单位、important 标记、引号区段与组成部分边界。默认只标示光标下的 class 字符串，让长标记保持清晰。若看不到语义颜色，请在当前 VS Code 主题启用语义高亮。

Shiki 代码示例对标记 class 属性采用相同的低干扰默认设置，用悬停代替光标。请在 transformerMasterCSS 旁导入公开样式表：

import '@master/css-language-service/shiki.css'import { transformerMasterCSS } from '@master/css-language-service/shiki'

#颜色工具

Master CSS 颜色工具类与 manifest 颜色使用 VS Code 颜色装饰与取色器。请同时启用 masterCSS.renderSyntaxColors 与 VS Code 的 editor.colorDecorators。

#指令格式化

文档与范围格式化可整理 CSS、SCSS、LESS 文档，以及 Vue、Svelte、Astro 中 CSS 类 <style> 块的指令源码，不改变生成的 CSS。对于 class 列表指令，important 标记会紧贴对应 class：@safelist "(background-color:transparent) !"; 会变成 @safelist "(background-color:transparent)!";。

#诊断

语言服务器报告上述文档中的指令错误，以及项目 manifest 加载错误。Class 字符串语法、策略与排序诊断由代码检查负责，不会重复报告。语言服务器客户端也可通过 designSystem 设置，选择对已打开且受管理的 CSS 文件检查 token 引用；它接受与 master-css inspect 相同的设计系统选项。

#识别 class 来源

内置来源包含 class、className、框架绑定、常用辅助函数调用与标签模板。项目使用其他辅助函数或属性时，加入其名称：

{  "masterCSS.classAttributes": ["ui"],  "masterCSS.classDeclarations": ["classes", "styles"],  "masterCSS.classFunctions": ["cn"]}

例如，现在 cn("p-card") 也会有 class 补全。语言服务数组会扩展内置 class 来源，因此 clsx 仍可使用。ESLint 来源设置则会替换默认值；引入项目约定时，请同时设置两项工具。

#按工作区选择的 manifest

在 auto 模式中，语言服务器会为每个导入 @master/css 的 CSS 文件，以及声明 Master CSS 包的 package.json 检测工作区，并各自建立 manifest。Monorepo 中的补全、hover 预览、颜色与诊断会跟随最近的 Master CSS 项目。检测结果不符仓库布局时，请列出工作区目录；项目边界详见 Monorepo：

{  "masterCSS.workspaces": ["apps/admin", "apps/shop", "packages/design-system"]}

依赖、工作区布局改变，或 VS Code 尚未读到 manifest 编辑时，运行 Master CSS: Restart Language Server。

#故障排查