Master CSS の言語サービス

#概要

Master CSS 言語サービスで、プロジェクトが実際に対応するクラスを探し、編集しながら CSS を調べられます。提案はプロジェクトのトークンと定義を読み、独自のユーティリティ、mixin、セレクター、条件も反映します。

Master CSS をインストール済みのプロジェクトから始めます。拡張機能はソースの記述を助け、ブラウザーへのスタイルシート配信は引き続きフレームワーク連携が担います。

#VS Code を設定する

公式の Master CSS 拡張機能をインストールし、VS Code でプロジェクトフォルダーを開いて、文字列内の補完を有効にします。

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

拡張機能は @master/css を読み込む CSS エントリー、または Master CSS パッケージを宣言する package.json から文脈を見つけます。複数アプリのあるリポジトリでは、使いたいテーマを持つアプリのソースを開いてください。

#プロジェクトのトークンを確認する

アプリの CSS エントリーで、既存のインポートの後に間隔トークンを追加します。

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

HTML ファイルの class 属性内に p-ca と入力します。候補から p-card を選び、補完したクラスをホバーします。

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

1つのプロジェクトトークンを、クラス名の補完と宣言の検査で確認します。エディターのプレビューでは、ブラウザーで何が優先するかは分かりません。

テキストによる説明

1. 定義する. アプリのスタイルシートで @master/css を読み、@theme に --spacing-card: 1.5rem を宣言します。
2. 補完する. HTML の class 属性内で、p-ca にプロジェクトを反映した p-card の補完が出ます。
3. 調べる. p-card のホバーで、生成した padding: var(--spacing-card) 宣言を表示します。ページへの CSS 配信はフレームワーク連携が担うので、描画結果は別途検証します。

ホバーの生成ルールに padding: var(--spacing-card) が含まれるはずです。クラス名はプロジェクトのトークンから来て、宣言は変数参照を保ちます。ブラウザーで実際のパディングを確認してください。p-card がなければ、設定を増やす前にワークスペースの文脈を解決します。

補完とホバーで記述時の文脈を確認します。実際のページはビルドとブラウザーでも検証してください。

テキストによる説明

1つのソースクラスから2つに分岐します。言語サービスは作者に生成 CSS を示し、連携ツールはブラウザーに CSS を配信します。

#保存時のクラス並べ替えを追加する

クラスのポリシー診断と保存時の並べ替えには、コードの lintを設定し、ESLint 拡張機能を入れます。editor.quickSuggestions と併せて次を追加します。

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

これで明示的な保存時に、プロジェクトの ESLint 設定で並べ替えられます。ルール一覧だけでは保存時アクションは有効になりません。eslint.codeActionsOnSave.mode は既定の all にします。拡張機能の problems モードはこのルールフィルターを無視します。ESLint の設定を参照してください。

#編集しながらスタイルを調べる

#クラスと条件を補完する

補完は設定したクラスソース内で動きます。マークアップ属性、フレームワークのバインド属性、JavaScript ヘルパー呼び出し、タグ付きテンプレート、独自のクラス宣言が対象です。ユーティリティ、プロパティ値、色トークン、セレクター、クエリー、指令構文を提案し、マニフェストの読み込み後はプロジェクトのトークンも出ます。

#生成ルールを読む

fg-blue-60:hover@sm などをホバーして、宣言、セレクターの状態、クエリーを調べます。この例は sm 以上でのホバー時にだけプリセットの青色トークンを適用します。

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

#構文の強調表示

拡張機能は CSS 系文書の指令構文を強調し、クラスリストの宣言、値、セレクター、クエリー、単位、important、引用区間、構成要素の境界にセマンティックトークンを使います。既定ではカーソル下の文字列だけを強調し、長いマークアップを落ち着かせます。色が出なければ、使用中の VS Code テーマでセマンティック強調表示を有効にしてください。

Shiki のコード例も、カーソルの代わりにポインターのホバーを使う同じ控えめな既定表示です。transformerMasterCSS と併せて公開スタイルシートを読み込みます。

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

#色のツール

Master CSS の色ユーティリティとマニフェストの色は、VS Code の色デコレーターとカラーピッカーを使います。masterCSS.renderSyntaxColors と editor.colorDecorators の両方を有効にします。

#指令の整形

文書全体と範囲の整形は、CSS、SCSS、LESS、および Vue、Svelte、Astro の CSS 系 <style> ブロックの指令ソースを整え、生成 CSS は変えません。クラスリスト指令では important をクラスに接続し、@safelist "(background-color:transparent) !"; を @safelist "(background-color:transparent)!"; にします。

#診断

言語サーバーは同じ文書内の指令エラーと、プロジェクトのマニフェスト読み込みエラーを報告します。クラス文字列の構文、ポリシー、並べ替えの診断はコードの lintに任せ、重複しません。クライアントは designSystem で、開いた管理対象 CSS のトークン参照検査も選択できます。master-css inspect と同じデザインシステムオプションを受け取ります。

#クラスソースを認識させる

組み込みのソースには class、className、フレームワークのバインディング、一般的なヘルパー呼び出し、タグ付きテンプレートがあります。別のヘルパーや属性を使う場合は名前を追加します。

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

たとえば cn("p-card") でも補完が使えます。言語サービスの配列は組み込みソースを拡張するので、clsx も使えます。一方、ESLint の設定は既定値を置き換えます。独自の規約を加えたら両方を設定してください。

#ワークスペースごとのマニフェスト

auto では、@master/css を読み込む各 CSS ファイルと Master CSS パッケージを宣言する各 package.json にワークスペースを検出し、それぞれにマニフェストを与えます。モノレポでは補完、ホバー、色、診断が最も近い Master CSS プロジェクトに従います。検出が配置と合わなければディレクトリを列挙します。境界はモノレポを参照してください。

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

依存やワークスペース配置の変更後、または VS Code がマニフェスト編集を拾っていない場合は、Master CSS: Restart Language Server を実行します。

#トラブルシューティング