デザインシステムの用語を「見た目」ではなく責務で揃え、AI の解釈ズレを減らす
Button に見えるから Button、箱だから Container、といった見た目ベースの命名は、人と AI の両方で解釈が割れる。Web 標準の意味を優先し、Element／Section／Inner／Gap／Link／Button／Navigation／Menu／Pattern／Component／Template／Theme などを責務で定義した用語ガイドを、エージェントが読むドキュメントに置く。
解決する問題
- デザインと実装と AI 生成 UI で、「Container」「Menu」「Text」の指すものが毎回違う
- エージェントが
aを Button と呼ぶ、内容幅ラッパーを Container と呼ぶ、など標準と衝突する
やり方
- 用語ガイドラインを1ファイルにし、CLAUDE.md／AGENTS.md またはデザイン Skill から参照する
- 最低限の方針
- HTML/CSS/ARIA で意味が定まっている語を再定義しない（
button/container/menuなど） - 見た目ではなく責務・要素・挙動で名付ける（見た目がボタンでも
aなら Link） - 構造・動的 UI・再利用部品・ページテンプレート・テーマを混ぜない
- HTML/CSS/ARIA で意味が定まっている語を再定義しない（
- 迷ったら判定フロー: 標準の意味 → 見た目依存でないか → 静的か動的か → 単一ソースか → ページ単位か
公開されている例: @tak_dcxi の Design System Terminology Guideline（Gist）。
注意点
- フレームワーク慣用（Bootstrap の Container など）と意図的にずらす場合は、その旨を一文で書く
- 用語変更は互換性破壊として扱い、エージェント用ドキュメントも同時に更新する