Master CSS 語言服務

#概覽

使用 Master CSS 語言服務，探索專案實際支援的 class，並在編輯時檢查 CSS。建議內容會讀取專案 token 與定義，包括你自訂的 utility、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 宣告。建議包含 utility、屬性值、色彩 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 色彩 utility 與 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。

#疑難排解