naming-audit

命名の監査

デザインシステムのコンポーネントとドキュメント化されたパターンの命名規則を監査するスキルです。違反レポートを作成し、具体例、曖昧さの指摘、根拠を添えた改名案を提示します。トークン名は token-audit、プロパティ名は component-api-validator、Figma の変数名は figma-variable-audit が監査するため、このスキルではそれらの調査結果を引用し、重複して取り上げません。

始める前に：参照ファイルを確認する

このスキルのフロントマターにある references: の各パスが、この SKILL.md からの相対パスとして存在することを確認します。存在しないものがある場合は中断してください。インストールが不完全であり、通常はフラット化するインストーラー（例：npx skills install）がリポジトリのルートにある knowledge-notes/ ディレクトリを取り込めていないことが原因です。ユーザーに 1-INSTALL.md に記載された方法で再インストールし、インストールルートから verify-install.sh を実行するよう伝えてください。ユーザーが参照ファイルなしで進めることを明示的に指示した場合に限り、参照ファイルなしで続行し、その場合は、出力がパックの参照資料を使わずに作成されたことを明記してください。

コンテキスト

命名は、デザインシステムとその利用者をつなぐ主要なインターフェースです。名前は、コンポーネントの機能、トークンの意味、パターンの動作について、デザイナーや開発者が最初に得る情報です。良い名前は予測しやすく、利用者は調べる前に、その名前が何を指すのか推測できます。悪い名前は、調査や確認が必要になり、意図の確認のためにやり取りが発生することもあります。

命名上の問題は蓄積します。曖昧なコンポーネント名が一つあるだけなら不便にすぎません。しかし、異なる三つの規則に従う名前が混在しながら、ライブラリ全体に曖昧な名前が二十個も散在していると、新しいチームメンバーには把握できず、経験豊富なチームメンバーも信頼できないシステムになります。

この監査では、コンポーネントと、ドキュメント化されたあらゆるパターンの命名を対象とします。特定の命名規則を義務づけるのではなく、命名に一貫性があり、曖昧さがなく、目的に適しているかを評価します。

ステップ 0：対象を特定する

名前を監査する前に、対象がどのような共有 UI なのかを判断します。ライブラリの種類に応じて、一貫性に求める厳しさや、提案の妥当な範囲が変わります。

コードベースの手がかりから分類します：

• デザインシステム — 完全な監査を適用します。命名規則は文書化され、一貫性があり、適用されている必要があります。文書化されていない規則については、決定記録を作成するよう提案します。
• コンポーネントライブラリ — 命名の一貫性は重要ですが、「決定記録を作成する」という提案は、「すでに従っている規則を書き留める。README のコメントだけでもよい」という程度に調整します。5 個のコンポーネントからなるライブラリに、正式なガバナンス文書は必要ありません。
• パターンライブラリ — 命名規則は、多くの場合、ドキュメントツールの規則（Fractal のフォルダー番号や Storybook のストーリー階層など）に従います。内部の一貫性だけでなく、ツールの規則に照らしても監査します。パターン名は、機能よりもパターンが示す内容を説明する傾向があります。これは混乱を招く場合にのみ指摘し、一律に違反とは見なしません。
• ユーティリティコレクション — 命名は主要なインターフェースです。参照できるドキュメントサイトがないため、すべてのユーティリティ名は曖昧さがなく、予測しやすい必要があります。監査では明確さを厳しく評価し、形式的な規則には寛容に対応します。接頭辞規則に従っていたとしても、u-cw より clamp-width のほうが適切です。

レポートのヘッダーに「Library type: [Design system / Component library / Pattern library / Utility collection]」として分類を記載し、それに応じて提案の重要度を調整します。

---

ステップ 1：名前の一覧を収集する

質問する前に、ソースから名前を抽出します。

• コンポーネント名 — 公開されているバレルエクスポート（パッケージルートの index.ts／index.js、またはモノレポ内の各パッケージのエントリーポイント）。実際に利用者が入力する名前はエクスポート名であり、内部ファイル名ではありません。バレルがない場合は、コンポーネントのディレクトリを確認します。各エクスポートのファイル名と行番号を記録します。これが指摘の根拠になります。
• パターン名 — ドキュメント化されている場合は、ドキュメントサイトまたは Storybook の階層を確認します。
• 既存の命名規則ドキュメント — README、CONTRIBUTING、ADR を確認します。
• 関連するレポート — token-audit レポート（トークンの命名に関する指摘）または component-api-validator レポート（プロパティの命名に関する指摘）が実施済みの場合は、再監査せず、要約でその ID を引用します。

ソースにアクセスできない場合に限り、ユーザーに名前の一覧を尋ね、どの名前がどこから取得されたかを伝えます。バレル、コンポーネントディレクトリ、ドキュメントの階層のいずれも見つからない場合は、ファイル名を監査せず、コンポーネントの場所を尋ねます。

命名規則のドキュメントが存在する場合は、それに照らして評価します。存在しない場合は、既存の名前から暗黙の規則を導き出し、互いに一貫していない箇所を記します。

小規模システムに関する注記（コンポーネントが 5 個未満の場合）： この規模のシステムでは、命名監査はコンプライアンス監査というより、命名についてのワークショップに近いものです。一貫性の確認（ステップ 2）は簡単です。コンポーネントが 1～4 個なら、すべての名前が同じ規則に従っているか、または不一致がすぐにわかります。パターン検出よりも、目的の明確さと曖昧さの指摘に重点を置きます。システムが小さく、移行コストをかけずに名前を変更できる今のうちに、規則を決定記録（decision-record）にまとめることを提案します。

ステップ 1b：支配的な規則を導き出す

命名規則のドキュメントが存在しない場合、まず規則を決めるために作業を止めてはいけません。一覧から、すでに最も多くの名前に採用されているパターンを導き出し、チームが確認または修正できるよう、レポートの規則一覧に記載します。

• コンポーネント： 大文字・小文字の形式、具体性の順序（ButtonPrimary と PrimaryButton）、略語の使い方、接頭辞・接尾辞の規則
• パターン： 名前がユーザーのタスク（「サインイン」「リストの絞り込み」）を表すか、関連するコンポーネント（「検証付きフォーム」）を表すか、またドキュメントツールの階層に従っているか

導き出した規則に照らして監査し、その規則が導出されたものであることを明記します。支配的な規則がない場合は、いずれかを選ぶのではなく、そのことを指摘として報告します。最後に、decision-record スキルを使って規則を決定記録にまとめることを提案します。

ステップ 2：コンポーネントの命名を評価する

一貫性の確認

コンポーネント名は一貫した規則に従っていますか？使用されている規則を特定します。

• 大文字・小文字の形式：PascalCase、camelCase、kebab-case、または混在
• 具体性のパターン：一般的な要素から具体的な要素へ（ButtonPrimary）、またはカテゴリを先にする（NavigationPrimary）
• 略語の方針：略語を使っているか、また一貫しているか（Btn と Button、Nav と Navigation）

ライブラリ内の他の名前が従うパターンから外れているコンポーネントを列挙します。次に変更する際に、規則に合わせるとよいでしょう。違いが意図的な命名上の判断である可能性がある場合は、見落としだと決めつけず、その旨を述べて確認します。

目的の明確さの確認

コンポーネント名は、背景情報がなくても、そのコンポーネントの役割が伝わるものにします。

次に該当する名前を指摘してください。

• コンポーネントの具体的な役割に対して、意味がないほど汎用的な名前：特定の役割を持つコンポーネントに付けられた Wrapper、Base、Thing、Item。ただし、レイアウトの基本要素は除きます。Box、Stack、Flex、Grid、Container、Layout は、汎用的なレイアウトコンポーネントとして広く理解されている名前です。
• 機能ではなく見た目を表す名前：BlueCard、LargeText、RoundedButton
• チーム内だけで通じる専門用語を使った名前：組織に新しく加わった人には理解できない名前
• 類似するコンポーネントとの区別が曖昧な名前：同じシステムにある Modal と Dialog、明確な使い分けのない Tooltip と Popover

指摘した名前ごとに、どのような曖昧さがあるかを説明し、改名案を提案してください。改名案はシステムで確立されている規則に従い、単に名前を変えるのではなく、改善につながるものにしてください。

接尾辞と接頭辞の規則

システムでカテゴリー、バリエーション、役割を示す接尾辞や接頭辞を使っている場合、一貫して適用されていますか？

確認すべき一般的なパターン：

• サイズの接尾辞：ButtonSm、ButtonMd、ButtonLg — サイズの表記はコンポーネント間で一貫していますか？
• 状態の接尾辞：-active、-disabled、-loading — 状態名はコンポーネント間で一貫していますか？
• カテゴリーの接頭辞：Form-、Nav-、Data- — 関連するすべてのコンポーネントに接頭辞が適用されていますか？

システムの規則に照らして接頭辞や接尾辞を付けるべきなのに、付いていないコンポーネントを指摘してください。

ステップ 3：パターンの命名を評価する

システムでパターンが文書化されている場合（ドキュメントサイトのセクション、Storybook の「Patterns」階層、patterns/ フォルダー）のみ実施してください。該当しない場合は省略した旨を記してください。

• タスクと組み立ての違い — パターン名は、部品の一覧（Modal with two buttons）ではなく、ユーザーが行うこと（Confirm a destructive action）を表すべきです。名前だけでは 2 つのパターンを区別できない場合に限り、組み立てを表す名前を指摘してください。
• ドキュメントツールとの一貫性 — Storybook の階層や Fractal のフォルダー番号で順序が定められている場合は、その順序から外れているパターンを指摘してください。
• コンポーネントとの名前の衝突 — パターンとコンポーネントが同じ名前（パターンの Wizard とコンポーネントの Wizard）だと、検索や Figma で混乱を招きます。該当するものを指摘し、どちらを改名するか提案してください。

他の監査との相互確認

トークンの命名は token-audit、プロパティの命名は component-api-validator の対象です。いずれかのレポートが存在する場合は、命名に関する指摘の件数と ID を概要で引用し、命名全体を把握できるようにしてください。どちらのレポートも存在せず、ユーザーが「すべての命名」を求めている場合は、このレポートで扱わない範囲を示し、実行を提案してください。

ステップ 4：命名監査レポートを作成する

見出しとなる一文から始めてください。例：「コンポーネント名には一貫性がありますが、トークン名では 3 つの異なる規則が併存しており、混乱を招いています。問題の箇所は次のとおりです。」

---

命名監査レポート

日付： [date] 対象： [components / patterns / both]、および [引用した token-audit / component-api-validator の指摘、または「未実施」] 規則の文書化状況： [文書化され、参照として使用 / 文書化されていない — 規則は一覧から導出]

---

概要

1 段落で記述します。全体的な命名の品質はどうですか？一貫性の欠如は特定の時期や特定チームの貢献に集中していますか、それとも広く分布していますか？最も重要な指摘は何ですか？率直に書いてください。命名がひどい場合は、はっきりそう伝えてください。

---

規則の一覧

現在どのような命名規則が使われていますか？主な規則と、見つかった例外的な規則を列挙してください。このセクションでは、チームが実際に使っている規則を明らかにします。これが改善に向けた基準となります。

---

指摘事項

コンポーネントの命名規則違反

ID	コンポーネント名	根拠	問題点	名前の変更案	重大度
NA-01	[name]	[export file:line]	[specific issue]	[suggested name]	🔴/🟠/🟡/⚪

パターンの命名規則違反（パターンが文書化されている場合）

ID	パターン名	根拠	問題点	名前の変更案	重大度
NA-[n]	[name]	[docs path or story id]	[specific issue]	[suggested name]	🔴/🟠/🟡/⚪

重大度の基準：

• 🔴 重大 — 名前が実際に誤解を招く場合。コンポーネントが実行しないことを示している、またはエクスポートされた2つのコンポーネントに同じ名前が付いている
• 🟠 高 — 曖昧さによって、実際に誤用のリスクが生じる場合（利用者が名前だけでは区別できない2つのコンポーネント）
• 🟡 中 — 主流の規則と一貫していないが、誤解は招かない場合
• ⚪ 低 — 理解に影響しない、大文字・小文字や略語の誤り

---

推奨事項

命名規則のドキュメントがない場合： 名前を変更する前に、導き出した命名規則をチームで確認し、文書化してください。基準がなければ、名前変更の判断に安定した拠り所がなくなり、同じ不統一が再び積み重なります。

名前変更の順序： コンポーネントやトークンの名前変更は、破壊的変更です。以下を推奨します。

1. まず新規追加分を修正する — 今後は正しい命名規則を適用します
2. 重大度の高い順に名前を変更する — 優先度の高い違反から、中程度、低いものへと進めます
3. コンポーネント名の変更には非推奨化の手順を用いる — 古い名前はすぐに削除せず、移行手順を示して非推奨にしてください
4. 名前の変更を破壊的変更として告知する — change-communication スキルを参照してください

decision-record との連携： 新たに導き出した、または変更した命名規則を、decision-record スキルを使って意思決定記録に残すことを提案してください。これは利用者が最も頻繁に参照するガバナンス上の決定事項なので、記録する価値があります。ただし、提案を受け入れるかどうかはユーザーが決めます。

---

対象範囲

• 調査対象： [実際に確認したバレルエクスポートとドキュメントのソース、引用した関連レポート]
• 未調査： [調査できなかった対象。例：Figma のレイヤー名、内部専用コンポーネント]
• 「該当なし」の確認方法： [「違反なし」と報告する場合、確認が有効に機能したことをどのように示したか。違反がないとの記載がない場合は省略]
• 前提： [例：導き出した命名規則が意図されたものである]

以下の締めくくりの注記で終えてください。

---

締めくくりの注記（すべてのレポートに含める）

レポートは次の文で締めくくってください。

背景に関する注記： この監査では、一般的な命名規則に照らして命名パターンを確認します。名前が選ばれた理由までは把握できません。意図的な使い分けによる不統一もあるかもしれません。チームが意図して選んだ名前を指摘している項目があれば、お知らせください。命名規則を学習し、今後の実行では該当するパターンを除外します。目的は、意図的な決定を覆すことではなく、意図しない不統一を見つけることです。

---

品質チェック

• すべての違反に根拠（エクスポートのファイルと行、またはドキュメントのパス）と、理由を添えた具体的な名前の変更案がある。単に指摘するだけではない
• トークンとプロパティの命名は、ここで再監査せず、それぞれを所管するスキルを根拠として引用する
• 名前の変更案は、システムで確立されている命名規則に従い、一貫性を保ちながら命名を改善する
• 命名規則の一覧には、システムがどうあるべきかではなく、実際の命名状況が記載されている
• 重大度の評価は実際の影響を反映している。誤解を招く名前は優先度が高く、軽微な大文字・小文字の不統一は低い
• 推奨事項のセクションで、命名変更は破壊的変更であり、それに応じて扱う必要があることを踏まえ、変更の順序を示している
• 対象範囲のブロックと、意図的な逸脱についての締めくくりの注記が含まれている