定義

1. アーティファクト分類

1.1 Primitive

プリミティブ（または、非スタイル化コンポーネント）は、スタイリングを伴わずに振る舞いとアクセシビリティを提供する最下位の構成要素です。

プリミティブは完全にヘッドレス（つまり非スタイル化）であり、セマンティクス、フォーカス管理、キーボード操作、レイヤリング／ポータル、ARIA の配線、計測などの関心事をカプセル化します。振る舞いの基盤を提供しますが、完成した UI にするにはスタイリングが必要です。

例:

• Radix UI Primitives (Dialog, Popover, Tooltip, etc.)
• React Aria Components
• Base UI
• Headless UI

期待事項:

• 完全に非スタイル化（ヘッドレス）。
• 単一責任; スタイリングされたコンポーネントに合成可能。
• そのロールに対する包括的なアクセシビリティ振る舞いを同梱。
• バージョニングは安定性を重視; 破壊的変更は稀で文書化される。

1.2 Component

コンポーネントは、プリミティブに視覚的デザインを追加するか、複数の要素を組み合わせて完全で機能的なインターフェース要素を作る、スタイル済みの再利用可能な UI 単位です。

コンポーネントは依然として比較的低レベルですがスタイリングを含むため、アプリケーションで即座に利用できます。通常、未スタイル化のプリミティブを既定の視覚デザインでラップしつつカスタマイズ可能な形を保ちます。

例:

• shadcn/ui components (Radix プリミティブのスタイルラッパー)
• Material UI components
• Ant Design components

期待事項:

• 明確な props API; 適用可能な場合は制御された使用と非制御の使用をサポート。
• デフォルトのスタイリングを含むが上書きしやすい（classes、トークン、スロット）。
• 完全にキーボード対応かつスクリーンリーダーフレンドリー（プリミティブから継承）。
• 合成可能（children/slots、render props、または複合サブコンポーネント）。
• プリミティブから構築される場合もあれば、スタイリングとともに振る舞いを直接実装する場合もある。

1.3 Pattern

パターンは、特定の UI/UX 問題を解決するためにプリミティブまたはコンポーネントを特定の形で構成したものです。

例:

• インラインエラーを伴うフォームバリデーション
• 破壊的操作の確認
• タイプアヘッド検索
• 楽観的 UI

期待事項:

• 振る舞い、アクセシビリティ、キーボードマップ、および失敗モードを記述する。
• 複数フレームワークでの参考実装を含む場合がある。

1.4 Block

特定のインターフェースユースケース（多くは製品固有）をコンテンツの足場とともに解決する、意見のある本番対応のコンポーネント群の構成です。Blocks は一般性を犠牲にして採用の迅速さを取ります。

例:

• 価格表
• 認証画面
• オンボーディングステッパー
• AI チャットパネル
• 請求設定フォーム

期待事項:

• 強いデフォルト、コピーペーストに優しい、ブランド化／テーマ化が容易。
• レイアウトとオーケストレーション以外のロジックは最小限; ドメインロジックはハンドラを通じてスタブ化される。
• props を通じてデータを受け取る; 文書化されたアダプタなしにフェッチの背後にデータを隠さない。

1.5 Page

単一ルートの完全なビューで、特定のユーザー向け目的を果たすために複数のブロックを配置して構成されます。ページはブロックを結合して、アプリケーション内の一つの到達点を表す統一レイアウトを作ります。

例:

• ランディングページ（ヒーローブロック + 機能ブロック + 価格ブロック + フッターブロック）
• 製品詳細ページ（画像ギャラリーブロック + 製品情報ブロック + レビューブロック）
• ダッシュボードページ（統計ブロック + チャートブロック + アクティビティフィードブロック）

期待事項:

• 単一ルートのために複数のブロックを統合した統一レイアウト。
• コンポーネントレベルの詳細よりもレイアウトとブロックのオーケストレーションに焦点を当てる。
• ブロック間のデータ調整のためのページ固有ロジックを含む場合がある。
• 単一の URL/ルート に対して自己完結的; ルート間で再利用することを目的としない。

1.6 Template

複数ページのコレクションまたはサイト全体の足場で、ページ、ルーティング設定、共有レイアウト、グローバルプロバイダ、プロジェクト構造をバンドルします。テンプレートはアプリケーション全体や主要なアプリケーションセクションのための完全な出発点です。

例:

• TailwindCSS Templates
• shadcnblocks Templates (フルアプリケーションシェル)
• "SaaS starter"（認証ページ + ダッシュボードページ + 設定ページ + マーケティングページ）
• "E-commerce template"（ストアフロント + 製品ページ + チェックアウトフロー + 管理ページ）

期待事項:

• ルーティング／ナビゲーション構造を伴う複数ページを含む。
• グローバル設定（テーマプロバイダ、認証コンテキスト、レイアウトシェル）を提供。
• 明確な規約を持つ意見のあるプロジェクト構造。
• 包括的な出発点として設計されており、依存関係としてインポートするのではなくフォークしてカスタマイズすることを想定。
• ビルド設定、デプロイ設定、開発ツールを含む場合がある。

1.7 Utility (Non-visual)

開発者の利便性や構成のためにエクスポートされるヘルパーで、レンダリングされる UI ではありません。

例:

• React フック（useControllableState、useId）
• クラスユーティリティ
• キーバインドヘルパー
• フォーカススコープ

期待事項:

• 副作用がない（明示的に文書化されている場合を除く）。
• 単体でテスト可能; ツリーシェイキングをサポート。

2. API と構成の語彙

2.1 Props API

コンポーネントの公開設定面。Props は安定して型付けされ、デフォルトとアクセシビリティへの影響が文書化される。

2.2 Children / Slots

呼び出し元が提供する構造やコンテンツのプレースホルダ。

• Children（暗黙のスロット）。開閉タグ間の JSX。
• 名前付きスロット。icon、footer のような props、または <Component.Slot> サブコンポーネント。
• スロットの転送。基底要素へ DOM 属性／className／refs を渡すこと。

2.3 Render Prop (Function-as-Child)

レンダリングを委譲するために使用される関数子で、親が状態／データを供給します。

<ParentComponent data={data}>
  {(item) => (
    <ChildComponent key={item.id} {...item} />
  )}
</ParentComponent>

親がデータ／振る舞いを保持しなければならず、かつコンシューマがマークアップを完全に制御する必要がある場合に使用します。

2.4 Controlled vs. Uncontrolled

制御された（Controlled） と 非制御（Uncontrolled） は、コンポーネントの状態を表す用語です。

制御された コンポーネントはその値が props によって駆動され、通常 onChange イベントを発火します（真実のソースは親）。非制御 コンポーネントは内部状態を保持し、defaultValue や命令的なリセットを公開する場合があります。

多くの入力は両方をサポートすべきです。詳細は controlled and uncontrolled state を参照してください。

2.5 Provider / Context

サブツリーに共有状態／設定（例: テーマ、ロケール、アクティブタブ id）を供給するトップレベルコンポーネント。Provider は配置要件が明示的に文書化されます。

2.6 Portal

レイヤリング／スタッキングコンテキストを管理するために DOM 階層外に UI をレンダリングする（例: モーダル、ポップオーバー、トースト）。同時にアクセシビリティ（フォーカストラップ、aria-modal、非アクティブ化された背景）を保持します。

3. スタイリングとテーマの語彙

3.1 Headless

外観を規定せずに振る舞いとアクセシビリティを実装します。消費者がスタイリングを提供する必要があります。

3.2 Styled

デフォルトの視覚デザイン（CSS クラス、インラインスタイル、またはトークン）を備えていますが、上書きしやすい（className マージ、CSS 変数、テーマ化）。

3.3 Variants

props を通じて公開される離散で文書化されたスタイルまたは振る舞いの変種（例: size="sm|md|lg", tone="neutral|destructive"）。Variants は別個のコンポーネントではありません。

3.4 Design Tokens

視覚デザインをパラメータ化しテーマ化をサポートする名前付きのプラットフォーム非依存の値（例: --color-bg, --radius-md, --space-2）。

4. アクセシビリティの語彙

4.1 Role / State / Property

セマンティクス（role="menu"）、状態（aria-checked）、関係（aria-controls, aria-labelledby）を伝える WAI-ARIA 属性。

4.2 Keyboard Map

ウィジェットのために文書化されたキーボード操作セット（例: Tab, Arrow keys, Home/End, Escape）。すべてのインタラクティブなコンポーネントはキーボードマップを宣言し実装します。

4.3 Focus Management

初期フォーカス、ロービングフォーカス、フォーカストラップ、および解体時のフォーカスの戻しに関するルール。

5. 配布の語彙

5.1 Package (Registry Distribution)

コンポーネント／ライブラリがパッケージレジストリ（例: npm）に公開され、バンドラ経由でインポートされます。バージョン管理された更新と依存関係管理を重視します。

5.2 Copy-and-Paste (Source Distribution)

ソースコードが消費者のリポジトリに直接統合されます（多くは CLI を介して）。所有権、カスタマイズ、余計なランタイムがないことを重視します。

5.3 Registry (Catalog)

メタデータ、プレビュー、インストール／コピー手順を備えたアーティファクト（プリミティブ、コンポーネント、ブロック、テンプレート）のキュレーションされたインデックス。レジストリは必ずしもパッケージマネージャではありません。

6. 分類のヒューリスティクス

この意思決定フローを使ってアーティファクトの命名と配置を行ってください:

1. スタイリングなしで単一の振る舞いまたはアクセシビリティ関心事をカプセル化しているか？→ Primitive
2. プリミティブに視覚的デザインを追加する、または複数の要素を合成するスタイル済みの再利用可能な UI 要素か？→ Component
3. 意見のある構成と文面で具体的な製品ユースケースを解決するか？→ Block
4. ルーティング／プロバイダを伴い置換可能な領域を持つページ／フローの足場か？→ Template
5. 実装に依存しない反復的なソリューションの文書か？→ Pattern
6. エルゴノミクス／構成のための非表示ロジックか？→ Utility

7. 非目的および明確化

• Web Components と "Components"。この仕様では "component" は再利用可能な UI 単位（React の例を含む）を指します。明示されていない限り HTML Custom Elements 標準を意味しません。原則はフレームワーク間で同等に適用されます。
• Widgets。用語 "widget" は曖昧さがあるため避けます; 一般的な場合は component を、文書のみのソリューションの場合は pattern を使用してください。
• Themes と Styles。テーマはスタイルのパラメータ化（トークン経由）です。スタイルは具体的なプレゼンテーションです。コンポーネントはテーマをサポートすべきであり、ブロック／テンプレートは意見のあるスタイルとテーマフックを提供する場合があります。