# 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

```php
$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

1. Non-destructive operations first
2. Destructive operations last
3. 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`