html-css-delivery / DESIGN.md comparison

既存DESIGN.md と検証版の違い

既存版は「短くて運用しやすいブランド指示書」。検証版は「デザイントークンまで持つ設計システム仕様」です。

結論

検証版をそのまま置き換えるより、既存版に良い部分だけ移植するのが安全です。

検証版は整理がかなり良い一方で、長く、既存テンプレと一部ズレがあります。Skill運用では「短く守れるルール」が強いので、トークン表・Do/Don't・Tailwind連携だけを部分採用するのがおすすめです。

まず大きさが違う

既存 DESIGN.md
79行

人間がすぐ読める短さ

DESIGN.perfected.md
426行

設計仕様として詳しい

検証版 lint
0件

errors / warnings なし

Tailwind theme
有

theme JSONを生成済み

性格の違い

既存版

現場用の短い指示書

HTMLを作る時に迷わないための、最小限のブランドルールです。短いので毎回読みやすく、Skillの実運用に向いています。

  • 単一HTMLが基本
  • 色・フォント・角丸・禁止事項を短く指定
  • 31ブロックを使う方針が明確
  • 読みやすく、メンテしやすい
検証版

デザイントークン付きの仕様書

色、文字、余白、角丸、部品をYAML front matterで定義した、より機械可読な設計システムです。

  • colors / typography / spacing / components を定義
  • Tailwind theme JSONに変換できる
  • アクセシビリティや運用ルールが詳しい
  • ただし毎回読むには重い

比較表

観点既存 DESIGN.md検証版 DESIGN.perfected.md判断
基本思想 Ad Insights Lab と同じトンマナでHTMLを作る。 同じ思想を、YAML front matterの正本トークンとして再定義。 思想は同じ
色 --bg、--primary などCSS変数の表。 background、on-primary、on-status まで追加。 検証版が詳しい
文字 見出し、本文、コードのフォント指定中心。 display、headline-lg、body-md など階層化。 部分採用したい
余白 本文15〜17px、行間1.7〜2.0など文章指定。 xs から 3xl、card-padding までトークン化。 採用候補
コンポーネント 31ブロックのカタログを参照。 31ブロックに加えて、card/button/badge/tableの部品定義あり。 テンプレ同期が必要
禁止ルール AIっぽさを消す禁止ルールが短く明確。 Do/Don'tとしてより具体化。 強化できる
実装との整合 template-blocks.html と近い。 一部、既存CSSとズレる値がある。 そのまま差替え注意

検証版で増えたもの

Tokens

YAML front matter

色、文字、角丸、余白、部品を先頭に定義。将来的にCSSやTailwindへ変換しやすい構造です。

Rules

運用ルールが具体的

primary は1画面1箇所、状態色は意味がある時だけ、など判断基準が増えています。

Theme

Tailwind theme JSON

Web UI側に寄せる場合に使える design.tailwind.theme.json が生成されています。

そのまま置き換えない方がいい理由

重い

毎回読むには長い

Skillは作業前に読むので、426行の仕様書を毎回読むと、運用の軽さが落ちます。

ズレ

既存テンプレと一部不一致

検証版の on-primary や文字間指定は、既存テンプレの実装と思想が少し違います。

二重管理

brand.css と正本が割れる

YAMLを正本にすると、CSS変数と同期する仕組みがない限り、どちらが正しいか迷いやすくなります。

おすすめの採用方針

1. 既存維持短いDESIGN.mdをベースにする
→
2. 良い規則だけ移植色運用、余白、Do/Don'tを追加
→
3. themeは別資料Tailwind化する時に使う

移植候補

採用度内容理由
採用primary は1画面1箇所レポートが派手になりすぎるのを防げる。
採用状態色は意味がある時だけ使う多色チップ乱用を避けられる。
採用余白トークン 24px / 32pxカード内余白とセクション間隔の基準が明確になる。
修正して採用Typography scale負のletter-spacingは使わず、サイズ階層だけ採用する。
別資料Tailwind theme JSONHTML skillの正本にせず、Web UI連携用の参考資料にする。
見送りfront matterを正本にする現時点では brand.css と二重管理になりやすい。

対象ファイル

比較元

/Users/kozawayoshiki/ad-creative-lab/.claude/skills/html-css-delivery/DESIGN.md

検証結果

/Users/kozawayoshiki/Downloads/design検証結果/DESIGN.perfected.md

/Users/kozawayoshiki/Downloads/design検証結果/design.tailwind.theme.json

/Users/kozawayoshiki/Downloads/design検証結果/DESIGN.perfected.lint.json