Filament Actions UX Standard

Canonical rules for row actions, bulk actions, header actions, and inspect affordances on all Filament table surfaces. This standard consolidates the Action Surface Contract from the constitution and docs/ui/action-surface-contract.md.

Last reviewed: 2026-03-09

Governing Principle

Filament-native first. Action patterns use native Filament action APIs. The constitution's Action Surface Contract (in .specify/memory/constitution.md) is the authoritative source for safety and RBAC rules. This document provides the quick-reference standard for implementation.

Required Surfaces

Every list/table must define:

Header Actions — primary CTA (create, sync, etc.)
Row Actions — inspect + contextual operations
Bulk Actions — where batch operations exist
Empty-State CTA — exactly 1 primary action, RBAC-gated

Inspect Affordance (Required)

Every list-style surface must provide a way to open a record.

Preferred: clickable rows

$table->recordUrl(fn ($record) => /* route to view/edit */)

Alternative: primary link column or View action

Use only when clickable rows are impractical.

Rule: no lone "View" button

If "View" is the only row action, prefer clickable rows and set actions([]) to avoid an unnecessary Actions column.

Row Action Limits

Max 2 visible row actions (typically View/Edit or Edit/Delete)
Everything else goes into an ActionGroup labeled "More"
Destructive actions must never be the primary visible action

Bulk Actions

Bulk actions must be grouped via BulkActionGroup
Destructive bulk actions require confirmation
Typed confirmation may be required for large/bulk changes

Destructive Action Safety

All destructive actions must use ->requiresConfirmation()
Destructive actions must not be styled as primary
Confirmation text must clearly describe the consequence
Server-side authorization must still enforce the action regardless of UI confirmation

This is a constitution-level non-negotiable (RBAC-UX-005).

Action Consistency

Standard action labels

Action	Label	Icon guidance
View record	"View" or clickable row	heroicon-o-eye
Edit record	"Edit"	heroicon-o-pencil-square
Delete record	"Delete"	heroicon-o-trash
Archive record	"Archive"	heroicon-o-archive-box
Restore record	"Restore"	heroicon-o-arrow-uturn-left
Force delete	"Force Delete"	heroicon-o-trash

Action ordering in "More" group

Non-destructive operations first
Destructive operations last
Separated by divider if Filament supports it

RBAC Enforcement

Non-member access: abort(404), do not leak existence
Member without capability: visible but disabled with tooltip
Server-side must enforce via Gate::authorize(...) or Policy method
Missing server-side authorization is a P0 security bug

Spec / DoD Gate

Every spec with UI changes must include a UI Action Matrix listing:

Which actions exist on which surfaces
Which are destructive and how confirmation is handled
Which capabilities gate each action

A change is not "Done" unless the Action Surface Contract is met.

Canonical Sources

Constitution: .specify/memory/constitution.md → "Filament UI — Action Surface Contract"
Detailed reference: docs/ui/action-surface-contract.md

3.4 KiB Raw Blame History