Development

AIにも渡せる命名の用語表を作る

AIにデザインやコードを作らせるとき、名前に使う語をプロジェクトの用語表で決めておくようにしました。デザインツールのコンポーネント名、コードのコンポーネント名、CSSのクラス名とカスタムプロパティ名のどこでも、同じ語を同じ意味で使うためです。

語の定義は私がGistにまとめたデザインシステムの用語の指針を元にしています。

Design System Terminology Guideline

Design System Terminology Guideline. GitHub Gist: instantly share code, notes, and snippets.

gist.github.com

コーディングの大半はAIに委託する現在、命名はAIが考える機会が多くなりました。クラス名を考えたくないという悩みは過去の話でしょう。しかし、AIに命名を任せるときに気になることは命名のずれです。

名前が少しずれているくらいなら、AIが前後の文脈から補ってくれそうにも見えます。困るのは、ずれた名前を次の層がそのまま読むときです。

層をまたいで語がずれると、AIの誤りが重なる

例えば、料金表の区画をデザインからコードに起こすとします。デザインのデータではカードがPlan Box、コンポーネントではPriceCard、CSSでは.card-1から.card-3と呼ばれていたとします。CSSとHTMLは次のとおりです。

書き直す前の料金表(CSS)
@layer components {
	.pricing {
		padding-block: calc(var(--spacing--xxl) * 1px);

		& > .container {
			margin-inline: auto;
		}
	}

	.container {
		--gutter: calc(var(--spacing--md) * 1px);

		box-sizing: unset;
		max-inline-size: calc(960 / 16 * 1rem);
		padding-inline: var(--gutter);

		& > * + * {
			margin-block-start: calc(var(--spacing--lg) * 1px);
		}
	}

	.pricing-title {
		font-size: var(--text--heading--fluid-font-size);
		line-height: var(--text--heading--leading);
	}

	.card-wrapper {
		display: block grid;
		grid-template-columns: repeat(auto-fit, minmax(min(100%, calc(240 / 16 * 1rem)), 1fr));
		gap: var(--gutter);

		& > * {
			grid-row: span 4;
		}
	}

	.card-1,
	.card-2,
	.card-3 {
		display: block grid;
		grid-template-rows: subgrid;
		row-gap: calc(var(--spacing--xs) * 1px);
		padding: calc(var(--spacing--md) * 1px);
		border: 2px solid transparent;
		background-color: var(--background--surface);
	}

	.card-2 {
		border-color: var(--foreground--accent);
	}

	.card-name {
		font-size: var(--text--subheading--fluid-font-size);
		line-height: var(--text--subheading--leading);

		& > .card-badge {
			margin-inline-start: calc(var(--spacing--xxs) * 1px);
		}
	}

	.card-badge {
		padding-inline: calc(var(--spacing--xxs) * 1px);
		background-color: var(--background--accent);
		color: var(--foreground--on-accent);
		font-size: calc(var(--text--label--font-size) / 16 * 1rem);
	}

	.card-price {
		font-size: var(--text--heading--fluid-font-size);
		font-weight: var(--font-weight--bold);
		line-height: var(--text--heading--leading);
	}

	.btn {
		padding-block: calc(var(--spacing--xs) * 1px);
		background-color: var(--background--inverse);
		color: var(--foreground--inverse);
		font-weight: var(--font-weight--bold);
		text-align: center;

		&:focus-visible {
			background-color: color-mix(in oklab, var(--background--inverse) 80%, var(--background--base));
		}

		&:any-link:hover {
			@media (any-hover) {
				background-color: color-mix(in oklab, var(--background--inverse) 80%, var(--background--base));
			}
		}
	}
}
書き直す前の料金表(HTML)
<section class="pricing" aria-labelledby="pricing-title">
	<div class="container">
		<h2 class="pricing-title" id="pricing-title">料金プラン</h2>
		<div class="card-wrapper">
			<section class="card-1">
				<h3 class="card-name">ライト</h3>
				<p class="card-price">0円/月</p>
				<p>ひとりで試すための基本の機能</p>
				<a class="btn" href="#light">ライトで始める</a>
			</section>
			<section class="card-2">
				<h3 class="card-name">スタンダード<span class="card-badge">おすすめ</span></h3>
				<p class="card-price">1,980円/月</p>
				<p>小さなチームで運用するための機能</p>
				<a class="btn" href="#standard">スタンダードで始める</a>
			</section>
			<section class="card-3">
				<h3 class="card-name">ビジネス</h3>
				<p class="card-price">4,980円/月</p>
				<p>複数のチームと権限を管理するための機能</p>
				<a class="btn" href="#business">ビジネスで始める</a>
			</section>
		</div>
	</div>
</section>

コードの中の--spacing--*は余白の段階を単位のない数値で持つトークンです。--spacing--mdは24、--spacing--smは16で、使う場所で* 1pxを掛けて単位を付けます。

表示は崩れていません。問題は、このコードをAIが読んで続きを書くときに出ます。

AIはクラス名やカスタムプロパティ名から要素の役割を推測して、コードを書き足します。しかも層をまたいで名前を読みます。デザインのデータからコンポーネントを起こし、コンポーネント名からCSSを書く、という順です。Plan BoxとPriceCardと.card-1のように層ごとに語が違うと、名前だけでは前の層のものと同じだと結び付けにくくなります。

そのうえ、ずれた名前はそれぞれ別の誤りを呼びます。

  • .containerは幅を制限しているだけです。container-typeでサイズクエリの問い合わせ先にした要素だと読むと、この要素の幅を問い合わせるコンテナクエリが書き足されるかもしれません
  • .btnは見た目がボタンの<a>に付いています。ボタンだと読んで:disabledのスタイルを足しても、<a>にはdisabled属性がないので当たりません
  • --gutterは画面の端との余白(padding-inline)とカードの間隔(gap)を兼ねています。値を変えたいとき、使っている箇所をすべて読まないと影響が分かりません
  • .card-1から.card-3は並び順を表すだけです。おすすめのカードが.card-2なのは、たまたま2番目にあるからです

どれも単独なら小さなずれです。ただ、AIはずれた名前に沿ってコードを書き足すので、ずれた名前が後続のコードにも引き継がれるおそれがあります。

何と呼ぶかを決める4つの基準

語を選ぶときは次の4つを順に確かめます。

  1. コードに現れるプロパティ名、要素名、ロール名(gap、container、columns、<button>、menuロールなど)は、その意味を変えずに使う
  2. 見た目ではなく責務で選ぶ
  3. 同じ概念には同じ語を使い、違う概念には違う語を使う
  4. wrapper、block、module、widgetのような総称を避ける

1つめは、先述した.containerの誤りの正体です。containerやcolumnsはCSSのプロパティ名、<button>はHTMLの要素名、menuはARIAのロール名として、すでに意味が決まっています。コードを読む人もAIも名前をその意味で読むので、別の意味に流用するとずれが生まれます。

例えばmenuは、HTMLとARIAで意味が違います。HTMLの<menu>はコマンドのツールバーを表す<ul>の意味的な代わりで、キーボード操作は定めていません。一方でARIAのmenuロールは、矢印キーなどで項目を移るメニューを表します。サイトの導線にmenuと付けてARIAのmenuロールを連想させると、そのキーボード操作を実装すべきだと誤解させます。WAI-ARIA Authoring Practices Guide(APG)には導線にmenubarを使う例もありますが、同じページで、典型的なサイトの導線には不要な複雑さだと注意しています。

2つめは.btnに当たります。見た目がボタンでも、ページを移動する<a>ならLinkです。名前を見た目で決めると、要素の振る舞いと名前がずれ、:disabledのような当たらないスタイルを呼び込みます。

3つめには2つの向きがあります。--gutterは、画面の端との余白とカードの間隔という違う概念を同じ語で呼んでいます。この語を変えるときは、どちらの意味で使っている箇所かを1つずつ読み分けることになります。逆にPlan Box、PriceCard、.card-1は、同じカードを層ごとに違う語で呼んでいます。こちらは、名前だけでは層をまたいだ対応を読み取りにくくなります。

4つめは.card-wrapperです。wrapperは何かを包んでいることしか伝えないので、何の責務で包むのかが分かりません。包む要素に名前が要るなら、内容の幅を決めるのか(Inner)、外側の配置と余白を決めるのか(Outer)を語で分けます。

省略語と番号

4つの基準を満たした語でも、略したり番号を付けたりすると読めなくなります。

btnやdescのような省略で節約できるのは数バイト程度です。CSSとHTMLは圧縮して転送されることが多いので、差はさらに小さくなります。一方で、読む人には元の語に戻す負担が残り、略し方が人によって揺れると名前で検索できなくなります。

原則として、省略してよいのはWeb標準の略語(img、nav)と、プロジェクトで浸透した略語(ctaなど)だけにします。ただし、後者は元の語と一緒に用語表に書いておきます。

クラス名に番号を付けるのもやめたほうがよいでしょう。番号は並び順を表すだけなので、カードを並べ替えたり足したりするとずれます。役割が違うなら役割名、見た目の種類が違うならdata-variantのような属性、位置で選ぶだけなら:first-childや:nth-child()を使います。

書き直す前の料金表では、カードに番号のクラスしかなく、共通のクラスがありません。カードに共通のスタイルは.card-1, .card-2, .card-3と列挙して書いています。一覧の側からは、この例では.card-wrapperの中で& > *と子をすべて選んでいます。子要素なら何でも選ぶセレクタなので、あとから並びに別の要素を足すと、その要素にもgrid-row: span 4が当たります。共通のクラスがあれば、番号のクラスを列挙せずにカードだけを選べ、カードの種類を増やしてもセレクタを直さずに済みます。

名前はその要素が何かを説明できるようになってから付けます。役割が分からないうちは、無理に名前を付けずにタイプセレクタや:nth-child()で選んでおくほうが、ずれた名前を残すよりマシです。

どの分類に当たるかの判定

何と呼ぶかとは別に、その単位がPattern、Component、Dynamic Element、Templateのどれに当たるかも決めておきます。分類の語がずれると、「Componentと書いてあるのに入力点がない」「Templateと呼んでいるのに静的な断片」のように、AIが受け取る設計の前提がずれるためです。

判定には次の3つの問いを使います。

  1. JavaScriptや状態の遷移を伴うか。伴えばDynamic Element(Componentと兼ねることがある)
  2. 単一の定義で管理され、差し替えられる入力点(props、slots、variantsなど)を持つか。持てばComponent、持たなければPatternかElement
  3. ページ全体に条件つきで適用されるか。そうならTemplate、そうでなければTemplateと呼ばない

PatternとComponentを分けるのは2つめの問いです。料金表のカードの一覧はJavaScriptを使わないので、Dynamic Elementには当たりません。一方で、プランの配列を受け取ってカードを並べます。名前、価格、説明、リンク先、variantという入力点を持ち、1つの定義から何度でも描けるので、静的でもComponentに当たります。

ただし、Dynamic ElementとComponentは排他ではありません。Dynamic Elementは「動的かどうか」の軸の分類なので、再利用の契約を持つ動的なUIは両方に当たります。

用語表

4つの基準と判定を通した語を、5つのまとまりに分けて用語表にしています。各語には、何を指すかと一緒に、何を指さないかを書きます。何を指さないかがないと、AIも人も近い意味の場面に語を広げて使ってしまうためです。

構造と余白

  • Element: HTML要素そのもの、または要素に1対1で対応する最小単位。HTML要素の総称をBlockと呼ばない
  • Section: ページの中の意味のある区画。<section>と1対1とは限らない。幅を制限するだけの要素には使わない
  • Inner: 区画の中で内容の幅を制限し、中央に寄せる要素
  • Outer: 親のコンポーネントが、子のコンポーネントの配置と外側の余白を決めるための要素
  • Container: container-type(またはcontainerのショートハンド)で、サイズクエリの問い合わせ先にした要素だけ。幅を制限するだけの要素には使わない
  • Gutter: コンテンツの外縁と画面の端のあいだの、インライン方向の余白。列や要素どうしの間隔には使わない
  • Gap: FlexboxやGridの子要素どうしの間隔。画面の端との余白や、通常フローのマージンには使わない

Inner、Outer、Containerは、単独で使わずに必ず「何の」を付けます(section-inner、card-outer)。innerだけだと、開発者ツールで見た人はルートまでたどらないと何の内側か分かりません。内側を包む要素が2つ以上になったときも、付け直さずに済みます。

スタイルクエリでは、container-typeを指定しなくてもすべての要素がコンテナになります。そのため、Containerという語はサイズクエリのコンテナに充てます。

Outerは単独のコンポーネントにせずに親のコンポーネントの子要素として扱います。子のコンポーネントの外側の余白は、子を置く親が決めることだからです。

Gutterの値は区画ごとに決めずにサイト全体で同じトークンを参照します。区画ごとにpadding-inlineを調整していると、ガターを変えるときに全区画を直すことになるためです。CSS Gridの仕様は行や列の間隔をgutterと呼びますが、この用語表ではプロパティ名のgapに合わせて間隔をGapと呼び、Gutterは外縁の余白に限ります。

配置

  • Columns: マルチカラムレイアウトの段組みだけ。FlexboxやGridの列には使わない
  • Flex Columns: Flexboxで横に並べた列。単にColumnsと呼ばない
  • Grid: CSS Gridの配置
  • Row: 親のレイアウトで成り立つ配置の結果。要素の名前にしない

配置の語はCSSの配置方式に合わせます。ただし、方式を名前に含めるのは、方式そのものがその要素の責務のときだけです。狭い画面ではFlexbox、広い画面ではGridのように幅で方式が変わる要素には、役割名を付けます。

要素

  • Link: ページを移動する<a>の要素。見た目がボタンでもLink
  • Button: ページの中の操作や状態の変化を起こす<button>の要素。<input type="submit">のように振る舞いがボタンと同じ要素もButton
  • List: <ul>か<ol>の項目の並びと、それを1つだけ包むコンポーネントのルート。<ul>や<ol>を使わない並びには使わない
  • Navigation: サイトやアプリの中を移動する導線
  • Menu: 操作を実行したり選んだりする選択肢の一覧。サイトの導線には使わない
  • Paragraph: 1つの段落。単にTextと呼ばない
  • Rich Text: 見出し、段落、リストなどを含む編集領域

Link、Button、Listは要素で決めます。NavigationとMenuは命名の約束で、この用語表では通常のサイトの導線をNavigationと呼び、Menuは操作の選択肢の一覧に使います。導線が複数あるなら、Primary Navigation、Footer Navigationのように責務を語で足して区別します。

再利用と分類

  • Pattern: 静的で再利用できる見た目の断片。動的なデータや条件の分岐を前提にしない
  • Component: 単一の定義から管理され、差し替えられる入力点を持つ再利用の単位。見た目が共通なだけではComponentとしない
  • Dynamic Element: JavaScriptや状態の遷移を伴う、振る舞いが中心のUI。Componentと排他ではない
  • Template: ページ単位の描画の定義。静的な断片をTemplateと呼ばない
  • Theme: 構造の上に乗る見た目、トークン、タイポグラフィ、色、余白のまとまり。差し替えても構造や動的なロジックを変えない

正式名称に使わない語

  • Block: display: blockと衝突し、総称としても曖昧
  • Wrapper: 何の責務で包むのかを表さない。InnerとOuterに分ける
  • Text: 段落、インラインのテキスト、編集領域を区別できない
  • Widget、Module: 責務の範囲が曖昧で、設計の境界を表さない

どれも責務の範囲を表さない語です。名前が曖昧なら設計の境界も曖昧になりやすく、AIはその要素に何を書き足してよいかを名前から判断できません。

Blockは、ツールや人によって指すものがとくにばらつく語です。WordPressのGutenbergはブロックエディターと呼ばれ、あらゆる要素をブロックと呼びます。同じような部品を、開発者によってはモジュールやエレメントと呼びます。Bricks Builderには「Block」という名前の部品があり、既定ではdisplay: flexで幅100%の<div>として出力されます。

一方でCSSでは、ブロックはdisplay: blockやブロックレベルのように、要素の描かれ方を表す語です。Bricks BuilderのBlockは既定でdisplay: flexなので、名前とdisplayの値はむしろ食い違います。この用語表ではblockの意味を変えないように、HTMLの要素はElementと呼びます。CSSのタイプセレクタも要素を選ぶので、名前とセレクタの語がそろいます。既定でFlexboxを使う<div>に名前が要るなら、「Flex Div」のように中身を表す語にします(Flexboxで横に並べた列なら、用語表のFlex Columnsに当たります)。

語は層をまたいで同じにし、表記は層の慣習に従う

用語表でそろえるのは語です。大文字と小文字や区切り方は各層の慣習に従います。料金表の区画なら、次のように並びます。

層表記の慣習区画区画の内側カードの一覧カード
デザインツールのコンポーネント語を空白で区切るPricing SectionPricing Section InnerPlan ListPlan List Card
コンポーネントパスカルケースPricingSectionPricingSectionの中PlanListPlanListの中
CSSのクラスケバブケース.pricing-section.pricing-section-inner.plan-list.plan-list-card

語がそろっていれば、Pricing SectionとPricingSectionと.pricing-sectionは表記が違っても、名前の上で対応が読み取れます。AIがデザインのデータからコンポーネントを起こし、コンポーネントからCSSを書くときも、前の層の名前が次の層の名前を決める手がかりになります。

コンポーネントの中の要素は、クラス名をルートの語で始めます。.pricing-section-innerはPricingSectionの中の要素で、.plan-list-cardはPlanListの中の要素です。カードのクラスを.plan-cardで始めると、PlanListの内部要素なのか、独立したPlanCardなのかを名前だけで区別できません。

書き直した後の料金表

先述した料金表を、用語表の語で書き直したものが次の実装例です。

書き直した後の料金表
<section class="pricing-section" aria-labelledby="pricing-section-title">
	<div class="pricing-section-inner">
		<h2 class="pricing-section-title" id="pricing-section-title">料金プラン</h2>
		<ul class="plan-list">
			<li class="plan-list-card">
				<h3 class="plan-list-card-name">ライト</h3>
				<p class="plan-list-card-price">0円/月</p>
				<p>ひとりで試すための基本の機能</p>
				<a class="plan-list-card-link" href="#light">ライトで始める</a>
			</li>
			<li class="plan-list-card" data-variant="recommended">
				<h3 class="plan-list-card-name">スタンダード<span class="plan-list-card-badge">おすすめ</span></h3>
				<p class="plan-list-card-price">1,980円/月</p>
				<p>小さなチームで運用するための機能</p>
				<a class="plan-list-card-link" href="#standard">スタンダードで始める</a>
			</li>
			<li class="plan-list-card">
				<h3 class="plan-list-card-name">ビジネス</h3>
				<p class="plan-list-card-price">4,980円/月</p>
				<p>複数のチームと権限を管理するための機能</p>
				<a class="plan-list-card-link" href="#business">ビジネスで始める</a>
			</li>
		</ul>
	</div>
</section>
/* 画面の端との余白は区画ごとに決めず、サイト全体でこの値を共有する */
@layer tokens {
	:root {
		--gutter: var(--spacing--md);
	}
}

/* PricingSection のファイルに書くスタイル */
@layer components {
	.pricing-section {
		padding-block: calc(var(--spacing--xxl) * 1px);

		& > .pricing-section-inner {
			margin-inline: auto;
		}
	}

	.pricing-section-inner {
		/* max-inline-size を内容の幅にし、ガターの値を変えても最大幅の式を直さずに済むようにする */
		box-sizing: unset;
		max-inline-size: calc(960 / 16 * 1rem);
		padding-inline: calc(var(--gutter) * 1px);

		& > * + * {
			margin-block-start: calc(var(--spacing--lg) * 1px);
		}
	}

	.pricing-section-title {
		font-size: var(--text--heading--fluid-font-size);
		line-height: var(--text--heading--leading);
	}
}

/*
 * PlanList のファイルに書くスタイル。プランの配列(名前、価格、説明、リンク先、variant)を受け取り、カードを並べる。
 * カードの行を一覧の行にそろえるので、一覧とカードを 1 つのコンポーネントにする
 */
@layer components {
	.plan-list {
		display: block grid;
		grid-template-columns: repeat(auto-fit, minmax(min(100%, calc(240 / 16 * 1rem)), 1fr));

		/* カードどうしの間隔は、画面の端との余白(--gutter)とは別に決める */
		gap: calc(var(--spacing--sm) * 1px);

		/* 名前、価格、説明、リンクの 4 行を、隣のカードの同じ行とそろえる */
		& > .plan-list-card {
			grid-row: span 4;
		}
	}

	.plan-list-card {
		display: block grid;
		grid-template-rows: subgrid;
		row-gap: calc(var(--spacing--xs) * 1px);
		padding: calc(var(--spacing--md) * 1px);

		/* おすすめのカードで枠の色だけを変え、太さの違いで中身がずれないようにする */
		border: 2px solid transparent;
		background-color: var(--background--surface);

		&[data-variant="recommended"] {
			border-color: var(--foreground--accent);
		}
	}

	.plan-list-card-name {
		font-size: var(--text--subheading--fluid-font-size);
		line-height: var(--text--subheading--leading);

		& > .plan-list-card-badge {
			margin-inline-start: calc(var(--spacing--xxs) * 1px);
		}
	}

	/* 枠の色が見分けられなくても、おすすめであることを文字で伝える */
	.plan-list-card-badge {
		padding-inline: calc(var(--spacing--xxs) * 1px);
		background-color: var(--background--accent);
		color: var(--foreground--on-accent);

		/* ラベルは小さくすると読みにくいので、画面の幅で変えない */
		font-size: calc(var(--text--label--font-size) / 16 * 1rem);
	}

	.plan-list-card-price {
		font-size: var(--text--heading--fluid-font-size);
		font-weight: var(--font-weight--bold);
		line-height: var(--text--heading--leading);
	}

	/* 見た目はボタンでも、ページを移動する <a> なので link と呼ぶ */
	.plan-list-card-link {
		padding-block: calc(var(--spacing--xs) * 1px);
		background-color: var(--background--inverse);
		color: var(--foreground--inverse);
		font-weight: var(--font-weight--bold);
		text-align: center;

		&:focus-visible {
			background-color: color-mix(in oklab, var(--background--inverse) 80%, var(--background--base));
		}

		&:any-link:hover {
			@media (any-hover) {
				background-color: color-mix(in oklab, var(--background--inverse) 80%, var(--background--base));
			}
		}
	}
}

マウスかキーボードでコードを選ぶと編集でき、表示結果に反映されます。編集中は Tab キーで字下げし、Esc キーでエディターから抜けます。

区画はSection、幅の制限は.pricing-section-inner、カードの並びはListです。申し込みのリンクはLink、画面の端との余白はGutter、カードの間隔はGapで、おすすめのカードは番号ではなくvariantで示しています。

書き直す前と後で、名前に関係しない宣言の値はそろえてあります。名前と要素を直し、--gutterの流用を分けた結果、置き場所と間隔の値も変わりました。違いは次の5つです。

  1. 名前と要素。<div>の中に<section>のカードを並べた形を<ul>と<li>にし、カードの番号をdata-variantに変えた
  2. --gutterの置き場所と形。前は.containerの中に単位付きで置いていた。後はサイト全体のトークンとして単位なしで置き、使う場所で単位を付ける
  3. カードの間隔。前は--gutterを流用した24pxだった。後はgapに別の値を指定し、16pxにした
  4. 一覧の子の選び方。前の例では& > *で子をすべて選んでいた。後はカードに共通の.plan-list-cardのクラスで選ぶ
  5. 後の版にだけ、理由のコメントと、コンポーネントごとのレイヤーの区切りがある

2つめの--gutterは、上の実装例の@layer tokensの部分で、サイト全体のトークンとして置いています。

--gutterは単位を持たない数値で、.pricing-section-innerの側でpadding-inline: calc(var(--gutter) * 1px)のように単位を付けて使います。ほかの区画も同じトークンを参照するので、ガターを変えるときはこの1か所を直せば済みます。

3つめと4つめは、上の実装例の.plan-listのルールにまとまっています。

カードの間隔はgapに--spacing--smを直接指定し、画面の端との余白と切り離しました。カードの間隔を詰めたくなっても、ガターには影響しません。子は.plan-list-cardのクラスで選んでいるので、並びに別のクラスの要素を足してもgrid-row: span 4は当たりません。

一覧とカードを1つのコンポーネントにした理由

一覧とカードはPlanListという1つのコンポーネントにまとめています。

分けなかったのは、カードの中の行(名前、価格、説明、リンク)を隣のカードとそろえるためです。行をそろえるsubgridは、一覧の側のgrid-row: span 4と、カードの側のgrid-template-rows: subgridの両方の宣言がないと成り立ちません。一覧とカードを別のコンポーネントにすると、どちらのコンポーネントも単独では行がそろわなくなります。

2026年11月時点でsubgridはBaselineの「広く利用可能」で、主要なブラウザで使えます。

Subgrid

広く利用可能 2026年3月から(新しく利用可能になったのは2023年9月)

執筆時点(2026年11月)から変わっていません

117
117
71
16
16

web-features 3.44.0 のデータ

webstatus.dev で見る

AIのワークフローに組み込む

AGENTS.mdを短く保つため、用語表は独立したMarkdownのファイルにします。AGENTS.mdには用語表へのリンクと、いつ読むかだけを置きます。用語表のファイルは次のような形です。

docs/naming-terms.md
# 命名の用語表

デザインツールのコンポーネント名、コードのコンポーネント名、CSS のクラス名とカスタムプロパティ名で、同じ語を同じ意味で使う。表記(大文字と小文字、区切り方)は各層の慣習に従う。

| 語 | 意味 | 避ける呼び方・使わない場面 |
| --- | --- | --- |
| Element | HTML 要素、またはそれに 1 対 1 で対応する最小単位 | HTML 要素を総称して Block と呼ぶ |
| Section | ページの中の意味のある区画 | 幅を制限するだけの要素 |
| Inner | 区画の中で内容の幅を制限し、中央に寄せる要素。「何の」を付ける(section-inner) | container、wrapper と呼ぶ |
| Outer | 親が子のコンポーネントの配置と外側の余白を決める要素。親の子要素として扱う | wrapper と呼ぶ、単独のコンポーネントにする |
| Container | `container-type`(または `container`)でサイズクエリの問い合わせ先にした要素 | 幅を制限するだけの要素 |
| Gutter | コンテンツの外縁と画面の端のあいだの、インライン方向の余白。サイト全体で 1 つのトークン | 列や子要素どうしの間隔 |
| Gap | Flexbox や Grid の子要素どうしの間隔 | 画面の端との余白、通常フローのマージン |
| Columns | マルチカラムの段組み | Flexbox や Grid の列 |
| Flex Columns | Flexbox で横に並べた列 | 単に Columns と呼ぶ |
| Grid | CSS Grid の配置 | Flexbox の配置 |
| Row | 配置の結果 | 要素の名前 |
| Link | ページを移動する `<a>`。見た目がボタンでも Link | `<button>` |
| Button | ページの中の操作を起こす `<button>`、`<input type="submit">` | `<a>` |
| List | `<ul>` か `<ol>` の並びと、それを 1 つだけ包むコンポーネントのルート | `<ul>`、`<ol>` を使わない並び |
| Navigation | 通常のサイトの導線 | 操作の選択肢 |
| Menu | 操作を実行したり選んだりする選択肢の一覧 | サイトの導線 |
| Paragraph | 1 つの段落 | Text と呼ぶ |
| Rich Text | 見出し、段落、リストを含む編集領域 | Text と呼ぶ |
| Pattern | 静的で再利用できる見た目の断片 | 動的なデータを前提にした UI、Template と呼ぶ |
| Component | 単一の定義で管理され、差し替えられる入力点(props、slots、variants)を持つ単位 | 見た目が共通なだけの断片 |
| Dynamic Element | JavaScript や状態の遷移を伴う、振る舞いが中心の UI(Component と兼ねてよい) | 静的な断片 |
| Template | ページ単位で条件つきに適用する描画の定義 | 静的な断片 |
| Theme | 構造の上に乗る見た目、トークン、色、余白のまとまり | 構造や動的なロジック |

- 正式名称に使わない語: Block、Wrapper、Text、Widget、Module
- Inner、Outer、Container は単独で使わず、対象を表す語を付ける(section-inner、card-outer、list-container)
- コンポーネントの中の要素は、クラス名をルートの語で始める(PlanList の中なら plan-list-card)
- 省略語は Web 標準の略語(img、nav)と、この表に元の語と並べて書いた略語だけを使う
- クラス名に番号を付けない。役割が違えば役割名、見た目の種類が違えば data-variant、位置で選ぶだけなら :nth-child() を使う
- 表にない語を使うときは、コードに現れるプロパティ名、要素名、ロール名と同じ語かを調べ(同じ語ならその意味を変えずに使う)、責務を表す語かを確かめてから、この表に足す

表は、語、意味、避ける呼び方・使わない場面の3列にしています。3列めは、AIが生成したコードを照らすときの基準にもなります。

AGENTS.mdには、次のように見出しと1行だけを書きます。

AGENTS.md(抜粋)
## 命名

クラス名、カスタムプロパティ名、コンポーネント名、デザインのコンポーネント名を付ける前と変える前に、[命名の用語表](docs/naming-terms.md)を読む。

リンクを置くだけでは、エージェントが読みに行くとは限りません。いつ読むかを書いておけば、名前を付ける作業の前に読む手がかりになります。

Claude Codeなら、用語表のファイル自体を.claude/rules/に置き、frontmatterのpathsに当たるファイルを指定できます。Claude CodeではCSSやコンポーネントのファイルを触ったときだけ用語表が読み込まれるので、ほかの作業の文脈を圧迫しません。ほかのエージェントにとっては、同じファイルがAGENTS.mdのリンク先になります。この場合は、AGENTS.mdのリンク先を.claude/rules/naming.mdに書き換えます。

.claude/rules/naming.md
---
paths:
  - "src/**/*.css"
  - "src/components/**"
---

# 命名の用語表

(以下、上の用語表と同じ内容)

デザインのデータをAIに読ませてコードを起こす流れでは、デザインの側から語をそろえます。デザインのコンポーネント名やレイヤー名が、そのままコンポーネント名やクラス名になるためです。デザインでPlan Boxと呼んでいれば、AIはその語からPlanBoxや.plan-boxを作りやすくなります。

AIが名前を付けたコードは用語表と照らして直します。AIに名前を付けさせると、次のような名前がよく出ます。

  • .container、.wrapper、.rowのような、CSSフレームワーク由来の名前
  • 見た目がボタンの<a>に付けた.btn
  • 列の間隔を表すカスタムプロパティのgutter

.container、.btn、列の間隔に流用した--gutterは、書き直す前の料金表にもありました。生成されたコードにこれらが出たら、用語表のどの語に当たるかを確かめて置き換えます。

語を足すとき、変えるとき

用語表にない語が要るときは次の順で確かめてから足します。

  1. コードに現れるプロパティ名、要素名、ロール名と同じ語かを調べる。同じ語なら、その意味を変えずに使う
  2. 見た目ではなく責務を表しているかを確かめる
  3. 何を指し、何を指さないかを、表と同じ形で書き足す

一方で、公開したコンポーネント名やカスタムプロパティ名に使った語を変えるのは、表記の修正ではありません。互換性のない変更です。

例えば、料金表の--gutterを--page-paddingに改名したとします。ある区画の呼び出し側がstyle属性で--gutterを上書きしていた場合、改名した後はその上書きを読む宣言がなくなります。エラーは出ずに、その区画だけサイト全体の既定のガターに戻るので、表示を見るまで気付けません。語を変えるときは使っている箇所を検索し、すべて同時に直します。

UIのラベルと正式名称も、できるだけ一致させたほうがよいでしょう。管理画面のラベルが「ボックス」で正式名称がSectionだと、デザイナーと実装者とAIが同じものを別の語で呼ぶことになります。デザインとコードで語をそろえても、運用の中で別の語が使われ始めます。

チームの中で通じる俗称を、正式名称の代わりにもしません。俗称を許すときも、正式名称は別に定義しておきます。俗称だけで呼ばれる要素は、用語表に意味も「使わない場面」もないまま、AIの書くコードの中に広がっていきます。


名前に使う語を用語表で決めておけば、デザイン、コンポーネント、CSSのどこでAIが名前を読んでも、名前の上では同じ意味で読めます。AIが出した名前も同じ表と照らして直せば、ずれが層を越えて重なる前に止められます。