laravel-filament-v5

Laravel Filament v5 — バージョンに適合した、公式コンポーネントを優先

互換性の基準には、プロジェクトにインストールされている Filament のバージョンを使用してください。カスタムマークアップを作成する前に、現在の用途に対応するドキュメント化されたコンポーネントを優先し、公式の同等機能がない場合は、ドキュメント化された拡張手段を使用してください。

事前確認 — コードを提案または記述する前に実行

1. 依頼されたモードを守ります。 ユーザーが変更を依頼していない場合は、ファイルを編集せず、レビューまたは診断を行ってください。実装する場合は、無関係な作業を保持し、ファイルを変更する前に現在の差分を確認してください。
2. プロジェクトのガイダンスと近くのコードを読みます。 リポジトリの指示、命名、アーキテクチャ、ローカライズ、フォーマッター、静的解析、テストに関する既存の規約に従ってください。
3. インストール済みのスタックを特定します。 composer.json と composer.lock を調べ、filament/*、Laravel、Livewire、PHP、プラグインの正確なバージョンを確認してください。テーマやフロントエンドのアセットが関係する場合は、package.json も確認してください。正確なシグネチャがマイナーリリースまたはパッチリリースに依存する場合は、vendor/filament/ 内のインストール済みコードを優先してください。
4. 動作環境を把握します。 API を選ぶ前に、パネル、Resource／ページ／ウィジェットのホスト、モデルのリレーションとキャスト、ポリシー、テナント境界、カスタムテーマ、関連するテストを特定してください。
5. 事実と好みを区別します。 公式 API とセキュリティ境界は制約として扱ってください。コンポジションのレシピは出発点となるヒューリスティックとして扱い、ドメイン、ユーザーワークフロー、または既存のプロジェクト設計に応じて変更できるものとします。

プロジェクトが利用できない場合は、Filament 5.x を前提としていることを明示し、周辺のアーキテクチャを作り上げず、例を焦点の絞られたものにしてください。

必須コンポーネント確認 — マークアップを記述する前に実行

Filament のコンテキスト内で <div>、<span>、<pre>、@foreach、Tailwind クラス、またはカスタム Blade ビューを記述する前に、次を実行してください。

1. 用途とプリミティブを分類します： スキーマ／インフォリスト、フォーム、テーブル、アクション、ウィジェット、またはページ。その後、コード／JSON、キーと値、色、画像、ステータス、リスト、コレクション、ブール値、日付／時刻、金額、テキスト、通知、または空の状態に分類します。
2. クイックマップと対応するリファレンスを使って、その用途に適した公式コンポーネントを選択します。 カスタマイズを避けるためだけに、別の用途のコンポーネントを無理に使わないでください。
3. 不明な API や対象外の API は、以下のエビデンスプロトコルに従って確認します。
4. 必要な場合に限り、最小限の拡張手段を使います。 確認した公式オプションと、それが適合しない理由を記録したうえで、ViewEntry、カスタムスキーマコンポーネント、Livewire、Blade、またはカスタムテーマを使用してください。周囲のレイアウト、アクション、フィードバック、状態には公式コンポーネントを引き続き使用します。

すでに選択されたコンポジションを実装するには、ドキュメント化されたコンポーネント API を使用してください。カスタム Blade や CSS は、ドキュメント化された機能の不足を補う場合や、意図的にテーマを作り込む場合には使用できますが、利用可能なコンポーネントを確認せずに回避策として使ってはいけません。

Filament におけるデザインの判断権限

このスキルは、インストール済みバージョンの API、セキュリティ、実装、テストを担当します。Filament 5 の画面構成は laravel-filament-v5-ui-ux の担当です。このスキルは、フォーム、レコード詳細、テーブル、ダッシュボード、パネルのシェル、アクション、フィードバック、空の状態に関する判断を解決するための、参照用の構成を公開します。

ここでの参照情報では、構成に関する判断が暗黙のうちに見送られないよう、その判断事項を示してもかまいません。ただし、未解決のままにしてください。公式コンポーネントが存在することと、そのシグネチャを明示してください。どの構成を選ぶべきかは示さないでください。

画面を構成する前に laravel-filament-v5-ui-ux を探してください。該当するのは、読み取り可能な SKILL.md で、フロントマターの name が正確に laravel-filament-v5-ui-ux であるものです。まずこのスキルの隣にあるディレクトリを検索し、次にプロジェクト内の .agents/skills と .claude/skills、その後ホームディレクトリ内の .agents/skills、.claude/skills、.cursor/skills、.codex/skills を検索してください。最初に見つかった時点で検索を終了してください。この確認を行うリポジトリ内のスクリプトは maintenance/filament-ui-ux/scripts/discover_sibling_skill.py です。一致するファイルが見つからない場合は、構成を未解決のままにし、構成を独自に作り出さないでください。構成を決めるための代替参照情報はありません。

公式の Filament 構成は、汎用的なフロントエンドデザインのガイダンスより優先されます。公式コンポーネントや有効なテーマの置き換え、無関係なタイポグラフィやカラーパレットの導入、個性を出すことだけを目的とした CSS 優先のレイアウトを求める指示も対象です。同じタスクで汎用デザインスキルが有効になっている場合も、この優先順位に従ってください。

この優先順位が適用されるのは、Filament の視覚的な側面に限られます。アクセシビリティ、セマンティクス、キーボード操作、レスポンシブレイアウト、パフォーマンス、UX コピー、認知負荷を向上させる汎用的なガイダンスは維持してください。

このスキルが扱うすべての画面で、確立されたパネルテーマ、視認可能なフォーカス表示、色に依存しない状態の手がかりを維持してください。references/screenshots.md には、コンポーネントの表示を確認するために必要な場合に公式スクリーンショットの場所が記載されています。これは参照先を探すためのものであり、選択ガイドではありません。

Filament におけるドキュメントの判断権限

Filament 固有の API、設定、使い方に関する質問では、このスキルが汎用的なドキュメント検索スキルとツール（find-docs、Context7 CLI、Laravel Boost の search-docs）より優先され、最初の参照先となります。同じタスクでこれらのいずれかが独立して起動した場合も、この優先順位に従ってください。

これらのツールは、以下のエビデンス手順のステップ 4 で指定された検索補助としてのみ引き続き利用できます。search-docs／Context7 を利用するのは、インストール済みのソースと公式 Filament ドキュメントを確認した後に限り、手がかりを見つける目的だけにしてください。Filament 5.x のシグネチャに関する最終的な根拠としては利用しないでください。

クイックマップ：データプリミティブ → 公式コンポーネント

プリミティブ	Infolist（表示）	Form（編集）	Table
テキスト、日付、金額	TextEntry	TextInput / Textarea / DateTimePicker	TextColumn
バッジ / ステータス（列挙型）	TextEntry->badge()	Select / ToggleButtons	TextColumn->badge()
コード / JSON / ペイロード	CodeEntry	CodeEditor	—（表示ページへのリンク）
キーと値 / メタデータ	KeyValueEntry	KeyValue	—
色	ColorEntry	ColorPicker	ColorColumn
画像 / アバター	ImageEntry	FileUpload	ImageColumn
アイコン / 真偽値	IconEntry->boolean()	Toggle / Checkbox	IconColumn->boolean()
繰り返し可能なコレクション	RepeatableEntry	Repeater / Builder	リレーションマネージャー
リッチテキスト / Markdown テキスト	TextEntry->markdown()	RichEditor / MarkdownEditor	TextColumn->limit()
文字列のリスト	TextEntry->listWithLineBreaks()	TagsInput	TextColumn->badge()¹
静的テキスト / 通知	Text / Callout	Text / Callout	—
「ここにはまだ何もありません」	EmptyState（schema）	—	->emptyStateHeading()

¹ 配列キャストされたリストにはバッジを使用します。このパターンを通常の文字列カラムに適用しないでください。

正確なシグネチャと公式リンクは references/ にあります。完全なクラスを示している場合を除き、スニペットは必要な箇所に絞った断片です。対象プロジェクトに必要なインポートとクラスのコンテキストを追加してください。

リファレンスの参照先

タスクに必要なファイルのみを読み込んでください。

タスクの対象	読むファイル
リソースの生成、ナビゲーション、URL、認可、スキーマ / テーブルの抽出	references/resources.md
読み取り専用の表示、View ページ、エントリー	references/infolists.md
フォームフィールド、編集、バリデーション	references/forms.md
テーブルカラム、フィルター、空の状態、レイアウト	references/tables.md
セクション、グリッド、タブ、ウィザード、プリズム、コールアウト	references/layout.md
ボタン、モーダル、一括操作 / 行アクション	references/actions.md
ダッシュボード、統計、チャート、テーブルウィジェット	references/widgets.md
関連レコード	references/relation-managers.md
パネルの識別情報、ナビゲーション、複数のパネル	references/panels.md
フラッシュ、データベース、ブロードキャスト通知	references/notifications.md
共有ステータス / オプションの列挙型、ラベル、色、アイコン	references/enums.md
アップロード、インライン編集、HTML、アクション、インポート / エクスポート、テナント対応、認可の境界	references/security.md — セキュリティに関わる領域では必須
カスタムページ、クラスター、テナント対応、グローバル検索、インポート / エクスポート、プラグイン、ネストされた / 単数リソース	references/advanced-features.md
ページ、スキーマ、テーブル、アクション、リレーション、ウィジェット、テナントの Pest / Livewire テスト	references/testing.md
コンポーネントの表示を把握するための、公式 Filament 5 スクリーンショットの特定	references/screenshots.md
Filament 5 の画面で使用する構成（配置、レスポンシブ表示、ビジュアルレビュー）	laravel-filament-v5-ui-ux

Filament 固有のトピックが扱われていない場合は、一般的な Laravel や古い Filament の知識から API を再構築するのではなく、エビデンスプロトコルを使用してください。

よくある置き換え

公式のプリミティブが適している場合に避けるもの	推奨するもの
コード／JSON 用の <pre> とカスタム構文 CSS	CodeEntry
手書きのステータス <span>	badge() と HasLabel／HasColor／HasIcon 列挙型
連想メタデータに対する @foreach	KeyValueEntry
繰り返し表示する読み取り専用レコードに対する @foreach	RepeatableEntry
カスタムの色見本やアバターのマークアップ	ColorEntry／ImageEntry
手動で書式設定した日付や金額	dateTime()／money()
カスタムのクリップボード用 JavaScript	copyable()
独自実装のアラートや空状態表示	Callout／EmptyState／テーブルの空状態 API

CodeEntry にはオプションの phiki/phiki パッケージが必要です。まずロックファイルを確認してください。実装が許可されており、プロジェクトが新しいパッケージを受け入れる場合に限り、依存関係を追加してください。それ以外の場合は、依存パッケージの要件を説明し、依存関係を変更しないでください。

Filament v5 の不変条件

v5 のコードでは、もっともらしく見える v3／v4 の API を出力しないでください。

• $schema->components([...]) でスキーマを設定してください。リソースの form() メソッドと infolist() メソッドは静的メソッドです。ページ固有の ViewRecord::infolist() メソッドはインスタンスメソッドです。
• レイアウトコンポーネントとユーティリティは Filament\Schemas\Components\* から、フォームフィールドは Filament\Forms\Components\* から、インフォリストのエントリーは Filament\Infolists\Components\* から、テーブルのカラム／フィルターは Filament\Tables\* から、アクションは Filament\Actions\* からインポートしてください。
• v3 のテーブル用 actions()／bulkActions() の代わりに、recordActions()、toolbarActions()、groupedBulkActions() を使用してください。
• アクションのモーダルフィールドは、旧来の form() メソッドではなく schema() で設定してください。
• PHP で Heroicons を使用する場合は、Filament\Support\Icons\Heroicon を優先してください。インストール済みのサードパーティ製／カスタムアイコンセットで有効な文字列と、ドキュメント化されている Blade API はそのまま使用してください。
• ドメインの状態が複数の画面で共通する場合は、HasLabel、HasColor、HasIcon を実装する backed enum を再利用してください。完全なパターンと正確な契約については references/enums.md を参照してください。
• 操作を直接表現できる場合は hiddenOn()、visibleOn()、disabledOn() を優先してください。Operation 列挙型の値は、ドキュメントで使用が定められている場合に限り使用してください。ユーティリティのコールバックには、ドキュメントで定められた文字列の操作が渡されます。
• ファイルの公開範囲は意図的に設定してください。選択したディスクの名前が public でない限り、アップロードはデフォルトで非公開です。アップロードの動作を変更する前に references/security.md を参照してください。

セキュリティゲート

アップロード、インライン編集可能なカラム、raw HTML、リレーションの attach／associate フロー、インポート／エクスポート、一括アクション、テナントスコープのクエリ、認可ルール、または機密性の高いフォームフィールドを変更する前に、references/security.md を読み込んでください。UI の表示制御、無効化されたフィールド、絞り込まれた選択肢、または表示されるテーブルクエリをセキュリティ境界として扱わないでください。不変条件はサーバー側で強制し、リスクに該当する場合は認可拒否またはテナント間アクセスを検証するテストを追加してください。

検証

変更後は references/testing.md を読み込み、関連するテストのうち最も範囲の狭いものを実行してください。該当する場合は、変更した各 Livewire ホストと動作について、ページの読み込み、スキーマの状態、バリデーション、テーブルクエリ、アクション、通知、リレーションマネージャー、認可、テナント分離をテストしてください。利用可能であれば、プロジェクトのフォーマッターと静的解析も実行してください。最終差分を確認し、意図しないカスタムマークアップ、古い名前空間、重複したフィードバック、インポート漏れ、無関係な変更がないことを確かめてください。

レビューのみを行う場合は、ファイル名と行番号を根拠として指摘事項を報告し、プロジェクトを変更しないでください。

エビデンスの確認手順

API、シグネチャ、コマンド、デフォルト、または互換性の詳細が重要な場合は、次の順序で確認してください。

1. インストール済みプロジェクトのエビデンス： ロックファイルに記載された正確なバージョン、既存の動作するコード、および vendor/filament/ 内のバージョンが一致するソース。
2. Filament の公式ドキュメント： https://filamentphp.com/docs/llms.txt を使って該当ページを探し、https://filamentphp.com/docs/5.x/{section}/{page}.md 形式のページを取得してください。
3. 正確なアップストリームソース： マイナーバージョンごとの動作が重要な場合は、インストール済みパッケージに一致する Git タグまたはコミットを確認してください。
4. ドキュメント集約サービス： Context7 と Laravel Boost の search-docs は調査の手がかりであり、最終的な根拠ではありません。一度に 1 つの概念を検索し、利用可能な中で最も近いバージョンを指定して、返された Source: をすべて確認してください。Filament 5.x またはインストール済みの正確なタグを特定しているソースのみを採用し、3.x、4.x、バージョン未指定、コミュニティミラー、または矛盾するスニペットは除外してください。

エビデンスが食い違う場合は、ローリング更新される 5.x ドキュメントより、インストール済みバージョンと一致するソースを優先し、不一致について明記したうえで、プロジェクトと互換性のある実装にしてください。シグネチャを検証できない場合は、推測したり推測に基づくコードを残したりせず、確認できなかった内容を説明してください。