AIが正しくCSSを書くための設計ガイド — linear-gradientのhoverアニメーション編

AIが正しくCSSを書くための設計ガイド

こんにちは。今回は Cursor + LLM を使って、
「背景グラデーションのhoverアニメーションをCSSだけで滑らかに動かす」ための 設計ルール をまとめます。

使用ツール

• エディタ: Cursor
• モデル: GPT-5
• 環境: Next.js

まずはそのまま使ってみる

Cursorに投げた最初のプロンプト

グラデーションのボタンを作って、hoverで色が変わるように実装してください。

出力結果

.btn-gradient {
  background-image: linear-gradient(
    90deg,
    #6366f1 0%,
    #a855f7 50%,
    #ec4899 100%
  );
  transition: background-image 0.3s ease;
}

.btn-gradient:hover {
  background-image: linear-gradient(
    90deg,
    #ec4899 0%,
    #f43f5e 50%,
    #fb923c 100%
  );
}

*（話をグラデーション部分に絞るため、関係しない記述は削除しています）

なにが問題？

• background-image は画像扱いで、色が補間されず“パッ”と切り替わる（＝滑らかに変化しない）。
• transition: background を書いても色の中間をアニメーションできない。

解決策 CSS変数 + @propertyを使用

• グラデーションの色を変数化して、hoverで変数の値だけを変える。
• 変数を補間可能にするため、@property で型を宣言する。

ルールをプロジェクトに仕込む（.style-guide-rules.md）

CSS変数と@propertyを使用することでアニメーションできても、
毎回手書きでCSSを書くのは非効率であり。特に、複数メンバーでの開発やLLMを利用したコード生成では、ルールがなければ書き方にブレが生じます。これを防ぎ、誰が書いても同じ品質・挙動を得られるようにするため、.style-guide-rules.md に明文化しておきます。

# CSS Style Guide Rules — Gradients / Hover Animation

## 基本方針
- グラデーションの色は **CSS変数**で渡す（`--grad-*`）。
- 変数は **@property** で `<color>` 型を宣言して **補間可能**にする。
- `hover` では **background-imageを変えず**、色変数だけを書き換える。
- （必要なら）色数に応じて `--grad-stop-*` を増やす。

---

## 2色グラデーション（最小構成）

### 宣言（どこか一度だけ。例：globals.css）
```css
@property --grad-start {
  syntax: "<color>";
  inherits: false;
  initial-value: #6366f1;
}
@property --grad-end {
  syntax: "<color>";
  inherits: false;
  initial-value: #a855f7;
}

ルールに従って生成されたCSS

@property --grad-start {
  syntax: "<color>";
  inherits: false;
  initial-value: #6366f1;
}
@property --grad-mid {
  syntax: "<color>";
  inherits: false;
  initial-value: #a855f7;
}
@property --grad-end {
  syntax: "<color>";
  inherits: false;
  initial-value: #ec4899;
}

.btn-gradient {
  --grad-start: #6366f1;
  --grad-mid: #a855f7;
  --grad-end: #ec4899;
  background-image: linear-gradient(
    90deg,
    var(--grad-start) 0%,
    var(--grad-mid) 50%,
    var(--grad-end) 100%
  );
  transition: --grad-start 300ms ease,
              --grad-mid 300ms ease,
              --grad-end 300ms ease;
}

.btn-gradient:hover {
  --grad-start: #ec4899;
  --grad-mid: #f43f5e;
  --grad-end: #fb923c;
}

最後に

今回紹介した「linear-gradientのhoverアニメーション」も、ルール化しておくことでLLMが一発で正しいCSSを出せるようになります。
同じように、<details> を使ったアコーディオンアニメーションや grid / subgrid の実装方法など、LLMが標準では出力しにくいCSS設計パターンはまだまだあります。
次回以降は、そういった「LLMが出しにくいHTML / CSS」の実装を中心に、ルールと具体例を解説していきます。