Claude Code にWebサイトのコーディングを任せるとき、デザインカンプ（画像/PDF）をそのまま渡すだけでは、レイアウトが正確に再現できないという壁にぶつかりました。

特に難しいのが「横並び」と「SP/PCで変わる表示順」です。カンプを見れば人間には一目瞭然でも、AIに言葉で伝えようとすると曖昧さが残り、毎回違う実装になってしまう。

そこで、カンプとコーディングの間に 「中間設計書」を挟むことにしました。この記事では、人間もAIも読める独自のレイアウト記法 layout-design-spec.md をどう設計したか、その試行錯誤を解説します。

なぜ「カンプ＋AI」だけではうまくいかないのか

最初は単純に考えていました。「デザインカンプの画像を渡して『これをコーディングして』と言えば済むはず」と。

ところが実際にやってみると、次のような問題が頻発しました。

• 横並びの解釈がブレる — デザインカンプでは横並びになっているのに、横並びで組まない。
• SP/PCの差が伝わらない — スマホでは縦積み、PCでは横並び、しかも表示順が入れ替わる、といった指定が言葉だと崩れる
• テキストの拾い漏れ・誤字 — カンプから直接コーディングすると、長い本文が省略されたり、画像化された文字を読み違えたりする

つまり、カンプという「人間向けの曖昧な情報」と、コーディングという「厳密な実装」の間に、
認識のギャップが大きすぎたのです。

解決策：間に「中間設計書」を挟む

そこで、工程を3段階に分けました。

① 設計書作成   ：カンプ（PDF） → 中間設計書（.md）
       ↓
② テキスト照合 ：カンプ（画像） + 設計書 → 誤字・抜けを修正
       ↓
③ コーディング ：照合済み設計書 → HTML/CSS 実装

ポイントは、①と③を分離したことです。いきなりコーディングさせず、
まず「カンプを構造化したテキスト＝設計書」を作る。この設計書は、

• AIが解釈しやすいように構造が明示されていて
• 人間が見ても確認・修正ができるように読みやすく書きやすく
• それでいてシンプルである

という3条件を満たす必要があります。この設計書を書くための記法を定義したのが layout-design-spec.md です。

layout-design-spec.md（レイアウト設計書ルール）

# layout-design-spec.md（レイアウト設計書ルール）

デザインカンプ（PDF/画像）から `page-{CONTENT}.md` を生成するための記法・ルール集。
Claude.ai にデザインカンプを渡したとき、このドキュメントに従って設計書を出力させる。

---

## ワークフロー

設計書の作成からコーディングまでのフローは以下の通り：

```
Task X.1: 設計書作成（PDF → 設計書）
  ↓
Task X.2: テキスト照合・誤字修正（JPG + 設計書 → 照合）
  ↓
Task X.3: コーディング（照合済み設計書 → 実装）
```

### Task X.1: 設計書作成

- デザインカンプ（PDF）からテキストを抽出し、設計書を作成する
- **テキストは省略せず全文を記載する**（`...` や `［...］` での省略は禁止）
- 要素指定（`<p>`, `<em>`, `<small>` 等）、クラス指定、パターン判断を含める

### Task X.2: テキスト照合・誤字修正

- **デザインカンプの JPG/PNG 画像**と設計書のテキストを突き合わせて照合する
- PDF テキストレイヤーからの抽出は類似漢字の誤認識が起きやすい（例:「貢献」→「直献」）
- 照合結果は設計書に反映し、設計書を「照合済み」状態にしてからコーディングに入る

### Task X.3: コーディング

- 照合済み設計書を正本としてコーディングする
- パターンCSS は各パターンの `.md`（例: `patterns/shelf.md`）のスニペットからコピーして調整する

---

## 出力ファイル

`{ページフォルダ}/page-{CONTENT}.md`

---

## 記法

| 記号 | 意味 | 対応するHTML要素 |
|------|------|-----------------|
| `§` | section / department（大枠） | `<section>` / `<div class="dept-...">` |
| `[[]]` | コンテナ・ゾーン・レーン（内枠） | `section__interior` / `topzone` / `bottomzone` / `leftlane` / `rightlane` |
| `{}` | ラッパー（パターン名付き） | `fluid-wrapper` / `shelf-wrapper` / `chest-wrapper` 等 |
| `[]` | アイテム | `<dt>` / `<dd>` / `<li>` 等 |
| `<>` | HTML要素 | `<img>` / `<h2>` / `<p>` 等（タグ名 + テキストまたはファイルパス） |
| `<> なし` | テキストのみ（お任せ） | 要素指定なしのテキスト |
| `()` | 補足情報 | `alt=""` / リンク先 / キャプション等 |
| `.` | class | `class="..."` |
| `#` | ID | `id="..."` |
| `---` | 区切り線 | `<hr>` |
| `,` | 縦並べ | 通常の縦積み（デフォルト） |
| `/` | 横並べ | grid 的な分割（float / flex / grid の横並び） |

### `.` と `#` の書き方

Pug と同じ記法。タグ名・ラッパー名・アイテムに続けて書く。

```
< h3.fz-lg.c-primary : 見出しテキスト >
< img#hero-img : images/xxx.jpg >
{ shelf.ta-center (data-cols_pc="3") : ... }
[ .fl-right.order-2_sp : ... ]
```
（※`<` の後に半角スペースを空けているのは、スペースなしだと VS Code がエラー表示をしてしまうため）

### `/` の多義性について

`/` は2レベルで使われる：

- Fluid 内の float 分割な`{ fluid: [画像] / [テキスト] }`
- Lane の横並びな`[[ leftlane ]] / [[ rightlane ]]`

`[[]]` で囲まれているかどうかで読み分けること。

### `,` と `/` の使い分け

`/` は grid 的な**分割**を意味する。`+`（Pug の並列）とは異なり、「列を区切る」イメージ。

```
{ fluid: [画像] / [テキスト] }     ← 左右に分割
{ shelf: [A] / [B] / [C] }         ← 横並べ（wrap する複数アイテム）
[[ leftlane ]] / [[ rightlane ]]   ← 左右 Lane に分割
{ shelf: [A], [B], [C] }           ← 縦並べ（wrap する複数アイテム）
```

---

## ブロック構造

```
§section : {セクション名}(@SP) 
───────────────────
[[ interior.mx-auto :
  ...
]]


§section : {セクション名}(@PC) 
───────────────────
[[ interior.mx-auto :
  ...
]]
```

### SP / PC の書き分けルール

**レイアウトが SP と PC で異なる場合は必ず別ブロックで書く。**

- Lane 分割の有無（`fxd-row_pc` 等）が変わる場合
- Fluid の float 方向が変わる場合
- アイテムの表示順が変わる場合（`order-*`）

レイアウトが同じで見た目だけ変わる場合（幅・文字サイズ等）は1ブロックでよい。

---

## 命名規則

### セクション名

```
sect-{識別コード}-{セクション名}
```

例：`sect-eqipCki4-Section`

### 画像ファイル名

```
{識別コード}-{セクション名}_{種別}{連番}.{拡張子}
```

| 種別 | 用途 |
|------|------|
| `pht` | 写真 |
| `ttl` | タイトル画像・SVG |
| `pic` | 図解・イラスト |
| `logo` | ロゴ |

例：
```
eqipCki4-Section_pht1.jpg
eqipCki4-Section_ttl1.svg
eqipCki4-Section_pic2.png
```

SP / PC で異なる画像を使う場合は `_sp` / `_pc` サフィックスを付ける：
```
eqipCki4-Section_pht1_sp.jpg
eqipCki4-Section_pht1_pc.jpg
```

---

## `[[]]` コンテナの種類

| 書き方 | 対応クラス | 用途 |
|--------|-----------|------|
| `[[ interior.mx-auto ]]` | `section__interior mx-auto` | 通常のコンテンツ幅 |
| `[[ inheader.mx-auto ]]` | `section__inheader mx-auto` | セクション内ヘッダー |
| `[[ topzone ]]` | `section__topzone` | 縦分割・上部（幅が interior と同じ） |
| `[[ bottomzone ]]` | `section__bottomzone` | 縦分割・下部（幅が narrower な場合等） |
| `[[ leftlane ]]` | `section__leftlane` | 横分割・左カラム |
| `[[ rightlane ]]` | `section__rightlane` | 横分割・右カラム |

### Zone（縦分割）を使うとき

セクション内で **見出し部分とコンテンツ部分の幅が異なる** 場合に使う。

```
[[ interior.mx-auto :
  [[ topzone :          ← 見出し（interior 全幅）
    { hgroup : ... }
  ]],
  [[ bottomzone :       ← コンテンツ（narrower）
    { ledge : ... }
  ]]
]]
```

### Lane（横分割）を使うとき

**同一 interior 内を左右カラムに分割する** 場合に使う（`fxd-row`）。

```
[[ interior.fxd-row_pc.mx-auto :
  [[ leftlane : ... ]] /
  [[ rightlane : ... ]]
]]
```

---

## `{}` ラッパーのパターン名

SKILL.md の使用判断フローで決定したパターン名を記載すること。

| 書き方 | 対応ラッパー | 使いどころ |
|--------|------------|-----------|
| `{ hgroup : }` | `hgroup-wrapper` | セクション見出しグループ |
| `{ fgroup : }` | `fgroup-wrapper` | セクション末尾グループ |
| `{ list : }` | `list-wrapper` | リストグループ |
| `{ chest : }` | `chest-wrapper` | レイアウト設定なし・汎用BOX |
| `{ fluid : [] / [] }` | `fluid-wrapper_pc` | 画像＋テキストの横並び（float） |
| `{ bleed : }` | `bleed-wrapper` | 画面端まではみ出すレイアウト（float） |
| `{ shelf : [] [] [] }` | `shelf-wrapper_pc` | 横並び複数行（flex-wrap: wrap） |
| `{ ledge : [] [] }` | `ledge-wrapper_pc` | 横並び1行（flex-wrap: nowrap） |
| `{ tiles : }` | `tiles-wrapper` | 均等グリッド |
| `{ bento : }` | `bento-wrapper` | 不均一グリッド |
| `{ rack : }` | `rack-wrapper` | 縦積み（flex-direction: column） |
| `{ cards : }` | `cards-wrapper` | カード型（縦） |
| `{ frame : }` | `frame-wrapper` | 画像上にテキスト配置 |
| `{ board : }` | `board-wrapper` | 要素を絶対位置で自由配置 |

---

## `<>` HTML要素の書き方

```
<タグ名.クラス名 : 内容またはファイルパス>（補足）
```

例：
```
< h2 : ZEH >
< h3.fz-xxl : 断熱材とペアガラス >
< img : images/eqipCki3-Glass_pic1.png (alt="断熱材とペアガラス") >
< em.fz-xxl : 強調テキスト >
< small.fz-xs : 注釈テキスト >
```

### テキストの記載ルール ★重要

**設計書ではテキストを省略しない。** デザインカンプに表示されているテキストは全文を記載する。

```
❌ 禁止:
< p.fz-rg : 24時間皆様の安全な...（省略） >
< em.fz-ml : ［SDGs 詳細文言 … 提供いたします。］ >

✅ 正しい:
< p.fz-rg : 24時間皆様の安全なマンションライフを維持するために24時間機械監視システムを導入しています。火災やエレベーターの故障等の緊急報告、漏水や鍵の紛失通報など、マンションに関する緊急事態をいち早くキャッチし、メンテナンススタッフが迅速な処理にあたります。 >
```

**理由:** 省略されたテキストは、コーディング時にカンプから拾い直す必要があり、抜け漏れや誤字の原因になる。全文記載しておけば、コーディング時はそのまま使える。

---

### 色クラス（`c-primary` / `c-accent` 等）の付け方ルール ★重要

**設計書段階でも、色クラスを付けるのは「カンプで明確に色付きの要素のみ」。**「強調っぽいから赤」のような推測判断で色クラスを付けない。

```
❌ 禁止（カンプで色なしなのに、設計書段階で色クラスを付ける）:
< h4.fz-md.c-primary : リスクアセスメントを軸とした安全な職場づくり >
（→ 実装で赤文字になり、カンプとズレる）

✅ 正しい（カンプで色なしなら色クラスは付けない）:
< h4.fz-md : リスクアセスメントを軸とした安全な職場づくり >
```

**理由:** 設計書はカンプの忠実な翻訳であるべき。設計書段階での推測判断（「サブ見出しだから強調 → 赤」等）は、コーディング時に誤った装飾として実装される。

**チェック手順:**
1. カンプ画像を目視で開く
2. 色を付けようとしている要素が、カンプで実際に色付きか確認する
3. 迷ったら **色なし**（色クラスを付けない）を選ぶ → コーディング時に再確認

---

### 見出しレベルの目安

| 要素 | 用途 |
|------|------|
| `<h2>` | ページタイトル（hgroup 内） |
| `<h3>` | セクション見出し（hgroup 内） |
| `<h4>` | セクション内小見出し |
| `**` | キャッチコピー・強調文 |
| `<em>` | リード文・強調文 |
| `<p>` | 本文 |
| `<small>` | 注釈・キャプション |

### 見出し画像（タイトル SVG）の `max-width` 算出 ★重要

Intro / ChapterIntro 等で見出し画像（`ttl1.svg` 等）を配置する場合、`max-width` は **SP カンプの画像幅を 750px（SP カンプの画面幅）で割った vw 値** を使う：

```
max-width: min({SP画像幅 / 750 * 100}vw, 100%);
```

例：
- SECURITY（SPカンプで 364px 幅）→ `min(48.5vw, 100%)`
- STRUCTURE（SPカンプで 406px 幅）→ `min(54.1vw, 100%)`

> ⚠️ **`interior`（92.5vw）で割らないこと**。割るのは常に SP カンプの 100vw（= 750px）基準。
> PC カンプ（1440px）から書き出した SVG は、PC 時には元サイズのまま表示される。

---

## 共通属性（設計書には書かなくてよい・コーディング時に自動付与）

コーディング時に Claude Code が自動付与するもの：

- `scroll-fadeIn`（`section__interior` / `department__interior` に付与）
- `contain-intrinsic-size: 1000px`（`<section>` に付与。ただし **隣接セクションとネガティブマージン（`margin-bottom: -Nrem`）で連結させる場合は付けない**。付けると見切れる）
- lazy load：`class="lazy"` + `src="data:image/gif;base64,..."` + `data-src0="..."`
- `<picture>` で必ず `<img>` を囲む

---

## margin / padding / font-size の指定

設計書では **デザインカンプから読み取れる範囲で記載する**。省略してもよい（コーディング時に調整する）。

```
< h3.fz-lg.mb-1r : 見出し >         ← font-size・margin をクラスで指定
< p.fz-ss : テキスト >              ← font-size のみ指定
< img : images/xxx.jpg >            ← サイズ指定なし（お任せ）
```

### よく使うクラス

| クラス | 意味 |
|--------|------|
| `fz-xxxs` `fz-xxs` `fz-xs` `fz-ss` `fz-sm` `fz-sl` `fz-md` `fz-ml` `fz-lg` `fz-xl` `fz-xxl` | font-size |
| `mt-1r` `mb-1r` `mt-2r` `mb-2r` 等 | margin-top / bottom |
| `ta-center` `ta-center_sp` | text-align |
| `mx-auto` | margin-inline: auto |


### font-size の目安

| 要素 | クラス |
|------|------|
| `<h2>` | fz-xxl 〜  fz-xl |
| `<h3>` | fz-lg 〜  fz-ml |
| `<h4>` | fz-sl 〜  fz-md |
| `**` | fz-lg 〜  fz-ml |
| `<em>` | fz-md 〜  fz-rg |
| `<p>` | fz-ss 〜  fz-sm |
| `<small>` | fz-xs 〜  fz-xxs |

---

## section vs department

| 要素 | クラス | 用途 |
|------|--------|------|
| `<section>` | `sect-{識別コード}-{セクション名}` | コンテンツセクション |
| `<div>` | `dept-{識別コード}-{セクション名}` | メニュー・前置き・後置き等（非コンテンツ） |

設計書での書き方：
```
§section : Intro
§department : Prelude
```

---

## lang 属性

| 値 | フォント | 用途 |
|----|---------|------|
| `ja-MP` | ヒラギノ明朝, 游明朝 | 和文・明朝体 |
| `ja-GP` | Noto Sans JP | 和文・ゴシック体（本文） |
| `ja-ShipOMP` | しっぽり明朝 OTF | リード文・強調文 |

セクション全体に適用する場合は `<section lang="ja-GP">` のように `section` タグに指定。
部分的に変える場合は該当 `<>` 要素に指定する。

設計書での書き方：
```
§section[lang="ja-GP"] : Intro
```

---

## 出力例

```
§section : Intro(@SP) 
───────────────────
[[ inheader.mx-auto :
  { hgroup :
    < h3.fz-lg.bd-bottom : オールマイティシステム >
  }
]],
[[ interior.mx-auto :
  [[ leftlane :
    { fluid :
      [< img : images/eqipCki4-Section_pic2.png >] / ←float の横並び
      [< em.fz-md : キーを差し込んで回す操作が不要なオートキー。 >,
       < img : images/eqipCki4-Section_logo1.png (alt="Clavis") >,
       < h4 : オートキー >,
       < p.fz-ss : 鞄やポケットに入れたまま通過可能です。 >]
    }
  ]], ←通常の縦積み
  [[ rightlane :
    { fluid :
      [< img : images/eqipCki4-Section_pic3.png (alt="エントランス") >] /
      [< p.fz-ss : 携帯していれば便利です。 >]
    }
  ]]
]]


§section[lang="ja-GP"] : Intro(@PC) 
───────────────────
[[ inheader.mx-auto :
  { hgroup :
    < h3.fz-lg.bd-bottom : オールマイティシステム >
  }
]],
[[ interior.fxd-row_pc.mx-auto :
  [[ leftlane :
    { fluid :
      [< img : images/eqipCki4-Section_pic2.png >] / ←float の横並び
      [< em.fz-md : キーを差し込んで回す操作が不要なオートキー。 >,
       < img : images/eqipCki4-Section_logo1.png (alt="Clavis")>,
       < h4 : オートキー >,
       < p.fz-ss : 鞄やポケットに入れたまま通過可能です。 >
      ]
    }
  ]] / ←flex の横並び
  [[ rightlane :
    { fluid :
      [< img : images/eqipCki4-Section_pic3.png (alt="エントランス") >] /
      [< p.fz-ss : 携帯していれば便利です。 >]
    }
  ]]
]]

記法の核：記号でレイアウト構造を表す

HTMLの入れ子構造を、なるべく少ない記号で表現できるよう設計しました。基本の記号セットは以下です。

外側から内側へ、§ → [[ ]] → { } → [ ] → < > と入れ子が深くなります。簡単な例を挙げます。

§section : Intro
───────────────────
[[ interior :
  { hgroup :
    < h2 : サービス紹介 >,
    < p : 私たちが提供する3つの価値をご紹介します。 >
  }
]]

これは「Introセクションの中に、コンテンツ領域があり、その中に見出しグループ（h2＋p）が縦に並ぶ」という構造を表しています。HTMLのタグを全部書くより圧倒的に短く、かつ構造が一目で追えます。

「横並び」の表現

記法設計で考えたのが、横並びをどう伝えるかでした。

縦積みは ,　横並べは / で伝えることにしました。

{ fluid : [画像] / [テキスト] }       ← 画像とテキストを横並び（アイテムのレベル）
[[ leftlane ]] / [[ rightlane ]]      ← 左右カラムに分割（コンテナのレベル）

SP/PCの書き分けと「コーディング済み」マーカー

SP/PCで構造が変わる場合は別ブロックで書く

スマホとPCでレイアウトが変わる（カラム分割の有無、表示順の入れ替えなど）場合は、無理に1つにまとめず、別ブロックで書くルールにしました。対象は行末の (@SP) / (@PC) で示します。

§section : Feature (@SP)     ← スマホ用ブロック
§section : Feature (@PC)     ← PC用ブロック

実装済みセクションは「✅ coded」で畳む

ページが大きくなると、設計書も長くなります。すでに実装が終わったセクションまで全文残っていると、「これから実装する箇所」が埋もれて見通しが悪い。

そこで、コーディング完了したセクションは中身を省略し、✅ coded マーカーだけ残す運用にしました。

§section : ItemList1
───────────────────
✅ coded

§section : ItemList2
───────────────────
✅ coded

ただし、そのページで初めて使うレイアウトパターンの場合は、再利用時の参考になるよう補足だけ残します。設計書を「未実装の箇所に集中させる」ための工夫です。

設計書に課した「翻訳の忠実さ」ルール

記法とは別に、設計書の品質を保つための原則も決めました。一番大事なのは 「設計書はカンプの忠実な翻訳であるべき」という考え方です。具体的には2つ。

① テキストは省略しない — カンプに表示されている本文は、長くても全文を設計書に書く。省略すると、コーディング時にカンプから拾い直す必要が生じ、抜けや誤字の温床になります。全文書いておけば、実装時はそのままコピーで済みます。

② 推測で装飾を足さない — 「サブ見出しっぽいから赤文字にしておこう」のような推測判断で色クラスを付けない。カンプで実際に色が付いている要素だけに色を指定します。設計書段階での推測は、実装でカンプとのズレになって返ってきます。

この2つは地味ですが、AIが「気を利かせて」勝手に変えてしまうのを防ぐ、重要なブレーキになっています。

まとめ：中間表現がAIコーディングの精度を上げる

カンプから直接コーディングさせるのをやめ、間に「中間設計書」を挟むことで、レイアウト再現の精度が大きく上がりました。要点を整理します。

• 工程を分ける — カンプ→設計書→コーディングの3段階。いきなり実装させない
• 構造を記号で明示する — 入れ子・横並び・縦並びを少ない記号で表現
• 曖昧さを徹底的に潰す — 「/ の左右は同じ階層」のような一意ルールで解釈ブレを防ぐ
• 記号は実用性で選ぶ — 打ちやすさ・見分けやすさ・検索しやすさを優先
• 忠実な翻訳を徹底する — テキスト全文記載、推測装飾の禁止

「AIに任せる」とは、丸投げすることではなく、AIが正確に解釈できる形に情報を整えてあげることだと実感しました。最初に記法を整備する手間はかかりますが、一度作れば全ページで使い回せます。2ページ目、3ページ目から一気に楽になりました。

この設計書を使った具体的なコーディングの指示出しについては、別記事で解説しています。

Claude Code にWebサイトのコーディングをさせる方法—ドキュメント設計から指示出しまで

Claude Code にWebサイトのHTML/CSSコーディングを任せるための、CLAUDE.md・スキル・指示文の設計方法を実例付きで解説。独自CSSシステムとの連携・SP/PC対応・命名規則の伝え方まで体系化したノウハウをまとめます。  続きを読む