stylelintで定義済み変数を使わずにハードコードされている値に警告を出すカスタムルールを作る

css や scss で定義された変数があるにもかかわらずチーム開発の中で 16px や 4px などのハードコーディングされた値が直接使われてしまうことがあります。
こうしたケースをコードレビュー前に自動で検出するため stylelint でカスタムルールを作成し、定義済みの変数を使うように警告を出す方法をまとめました。

今回は scss の利用を例として取り上げます。

対象の例

次のようなコードが対象です。

.example {
  font-size: 16px;
  border-radius: 4px;
}

これを以下のように置き換えるよう警告を出したいというのが目的です。

.example {
  font-size: $font-size-default;
  border-radius: $border-radius-small;
}

カスタムルールの実装

no-specific-values.js をプロジェクト直下の任意のディレクトリ（例: my-custom-rules/）に配置します。

no-specific-values.js

/**
 * 変数定義済の値に警告を出すルール
 */
const stylelint = require('stylelint');

const ruleName = 'my-custom-rules/no-specific-values';
const messages = stylelint.utils.ruleMessages(ruleName, {
  rejected: (property, value, suggested) => `${property}: ${value} は避け、定義済みの ${suggested} を使用してください。`
});

const ruleFunction = (primaryOption, _secondaryOption, context) => (postcssRoot, postcssResult) => {
  const validOptions = stylelint.utils.validateOptions(
    postcssResult, ruleName, { actual: primaryOption }
  );
  if (!validOptions) return;

  // 警告を出すプロパティとその推奨値
  const disallowedValues = {
    'font-size': {
      '14px': '$font-size-small',
      '16px': '$font-size-default',
      '18px': '$font-size-large',
    },
    'border-radius': {
      '4px': '$border-radius-small',
      '8px': '$border-radius-default',
      '16px': '$border-radius-large',
    }
  };

  postcssRoot.walkDecls((_decl) => {
    const decl = _decl;
    const { prop, value } = decl;

    if (disallowedValues[prop] && disallowedValues[prop][value]) {
      const suggestedValue = disallowedValues[prop][value];

      if (context.fix) {
        decl.value = suggestedValue;
        stylelint.utils.report({
          message: messages.rejected(prop, value, suggestedValue),
          node: decl,
          result: postcssResult,
          ruleName
        });
      }
    }
  });
};

module.exports = stylelint.createPlugin(ruleName, ruleFunction);
module.exports.ruleName = ruleName;
module.exports.messages = messages;

stylelintにルールを読み込ませる

.stylelintrc.js にてカスタムルールを読み込みます。

.stylelintrc.js

module.exports = {
  ~~~
  "plugins": [
    ~~~
    "./my-custom-rules/no-specific-values.js" // カスタムルールを読み込み
  ],
  "rules": {
    ~~~
    "my-custom-rules/no-specific-values": true // 追加![対応していない形式のファイルです。]()

  }
};

動作確認

コマンドラインやエディタで警告が出れば設定完了です

1. エディタで赤線の警告が出ている様子

2. エラー詳細には、推奨される変数が表示されます。

3. さらに --fix オプションを使えば自動で以下のように修正されます。

.scss

.example {
  font-size: $font-size-default;
  border-radius: $border-radius-small;
}

おわりに

今回例に上げた font-size border-radius 以外にも、
同様のルールを他のプロパティ（例: color, margin, padding など）にも拡張できます。

チームのコーディングルールを自動チェックすることで、レビュー工数の削減とコード品質の向上が期待できます。