ahmido
02028be7e4
## Summary - add canonical UI standards under `docs/product/standards/` - add a comprehensive filter audit as source material for future filter standardization work - extend the constitution with incremental UI standards enforcement guidance ## Included - `docs/product/standards/README.md` - `docs/product/standards/filament-table-ux.md` - `docs/product/standards/filament-filter-ux.md` - `docs/product/standards/filament-actions-ux.md` - `docs/product/standards/list-surface-review-checklist.md` - `docs/audits/filter-audit-comprehensive.md` - `.specify/memory/constitution.md` ## Notes - this is documentation and governance work only; no runtime code paths changed - no tests were run because the change is docs-only - the new standards structure separates permanent principles, living standards, rollout audits, and review checklists ## Review Focus - confirm the standards location under `docs/product/standards/` - confirm the constitution principle belongs at the constitutional level - confirm the filter audit should live under `docs/audits/` as reference material Co-authored-by: Ahmed Darrazi <ahmed.darrazi@live.de> Reviewed-on: #153
123 lines
3.4 KiB
Markdown
123 lines
3.4 KiB
Markdown
# 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`
|