CSS設計で「引き継ぎ地獄」を避ける方法｜スタイル管理の実践テクニック

#CSS設計 #スケーラビリティ #チーム開発 #保守性 #命名規則
C
クリオ
Web制作ディレクター / フロントエンジニア

こんにちは！

今日は「CSS設計で『引き継ぎ地獄』を避ける方法」というテーマで解説します。

「前の人の書き方がわかからない問題」の現実

これ、ほんま多くのWeb制作チームが抱えてる悩みなんですよね。
僕も昔、先輩が書いたCSSコードを引き継いで、めっちゃ苦労した経験があります。

具体例を挙げるとこんな感じです。

  • クラス名が .button-primary-large-v2 みたいに何重にも修飾されてる
  • margin が 10px 20px 30px auto って書かれてて、「なんでこの値なの？」ってわからん
  • 後から修正される度に !important が増えてく
  • 同じスタイルがファイルの別々の場所に3回も4回も書かれてる
  • 「これ何のためのクラスですか？」って聞いても、もう誰も覚えてない

こういった状況になると、新しく入ってきた人は「とりあえずこのクラスに合わせとこ…」って思考停止に陥っちゃうわけです。
そしてその人が書いたコードも同じように謎のままになって、どんどん負債が溜まっていく。
これが「引き継ぎ地獄」の始まりです。

でもですね、これって実は「設計がない」か「設計があってもそれが誰にも伝わってない」のどちらかなんです。

複数人で安心して触れるCSS設計の基本

では、どうすれば複数人で安心して触れるCSS設計ができるのか。
これはBEMやFLOCSSといった既存の手法を「正しく理解すること」が鍵になります。

「命名規則」は単なる美学ではなく、チームとの契約

BEM（Block Element Modifier）を例に考えてみましょう。

BEMは .block__element--modifier という形で書く命名規則ですが、これって実は「このコードを読む人が、このクラスの役割を瞬時に判断できる」ための約束なんです。

例えば：

  • .card → 「これはカード型のコンポーネント全体」
  • .card__header → 「カードの中の、ヘッダー部分」
  • .card__header--featured → 「このカードのヘッダーは、特別な装飾がされてる状態」

この規則に従ってれば、新しく引き継いだ人でも「ああ、.card__header--featured ってのはカードのヘッダーの特別版なんだ」とすぐにわかるわけです。

僕が現場で見てきた成功例は、BEMの厳密な適用よりも「チーム全体で『このプロジェクトではこのルールで書く』っていう統一性」を保つことの方が大事だったりします。

「責任を1つのファイルに集約する」設計思想

もう1つ大事なのが、「1つのコンポーネントのスタイルは、1つのファイル（または1つのセクション）に集約する」ということです。

例えば、カード型のコンポーネントなら：

  • ファイル構成： /styles/components/card.css
  • 内容：

/* Card Component */
.card { }
.card__header { }
.card__header–featured { }
.card__body { }
.card__footer { }

こうしておくと、「カードのスタイルを修正したい」って時に、わざわざ複数ファイルを行ったり来たりせずに済むわけです。
ほんま、これだけでも引き継ぎの難易度がぐっと下がります。

「スタイルの意図」をコメントで残す

でね、ここからが大事なんですけど、「なぜ」この値にしたのかをコメントで残すことです。

.card__header–featured {
  /* スマホでは不要な上部マージンなので、
    モバイルファースト設計により0。
    デスクトップ以上で20pxを追加 */
  margin-top: 0;
}

この一言があるかないかで、次の人が「あ、これはなんか理由があって0になってるんだな」とわかります。
逆にコメントがなかったら「この0px、消しても大丈夫かな…？」って不安になるし、最悪勝手に削除して後で問題が出たりするわけです。

引き継ぎ時に困らないドキュメント化のコツ

CSS設計を正しく整えても、それがドキュメント化されてなかったら意味がありません。
現場ではめっちゃ簡単でいいんです。凝る必要はありません。

必要な最小限のドキュメント

引き継ぎ時に必要なドキュメントは、以下の3つだけで十分です。

  1. ファイル構成図
    /styles/components/、/styles/utilities/、/styles/base/ みたいにどういう構成になってるのか
  2. 命名規則のルール
    「うちのプロジェクトではBEMを使ってます」「ただし〜の場合は例外」みたいな1ページ分の説明
  3. 修正テンプレート
    「新しいコンポーネントを追加する時はこのファイルを参考にしてください」という見本のコード

これ、Markdownファイルで README.md か STYLE_GUIDE.md として置いとくだけで、新しい人がめっちゃ助かります。

「このクラスはなぜ必要か」を履歴として残す

ちょっと工夫したいなら、Gitのコミットメッセージやブランチ名で「なぜこのスタイルが追加されたのか」の背景を残すといいですよ。

git commit -m “feat: card–featuredの追加 (トップページのバナーセクション用)”

こうしておくと、後から「なんでこんなクラスあるんだろう…」って時に git log を見ればすぐわかるわけです。

実装チェックリストを用意する