TenantAtlas/docs/product/standards/list-surface-review-checklist.md

List Surface Review Checklist

Use this checklist for every spec or PR that creates or modifies a Filament table/list surface. All items must be satisfied or have a documented exception.

---

Table Structure

• Columns follow the tier model (Primary / Context / Detail)
• Max ~7 visible columns by default (or density justified)
• Primary identifier is searchable() and sortable()
• Explicit defaultSort() is defined
• Timestamps use ->since() + tooltip in lists
• Null values use ->placeholder('—') consistently
• IDs are toggleable(isToggledHiddenByDefault: true) and copyable() where useful
• Status/enum columns use badge() via BadgeCatalog / BadgeRenderer
• Pagination profile matches the surface type (see table standard)

Empty State

• emptyStateHeading(...) is domain-specific
• emptyStateDescription(...) explains what the user should do
• Exactly 1 primary CTA in emptyStateActions([...]), RBAC-gated
• When non-empty, CTA is in header only (not duplicated)

Filters

• Tier 1–2 resources use the persistence trio
• Status/state filters use enum-backed options
• Soft-deletable resources use standard TrashedFilter labels
• Date range filters use indicateUsing()
• Filter count is reasonable (2–5 for Tier 1–2, 0–3 for Tier 3)
• Filter labels are clear and consistent with domain vocabulary

Actions

• Inspect affordance exists (clickable rows preferred)
• No lone "View" row action button
• Max 2 visible row actions; rest in "More" group
• Destructive actions use ->requiresConfirmation()
• Bulk actions use BulkActionGroup
• All actions are server-side authorized

Persistence & State

• Resource lists (Tier 1–2) persist filters, search, sort in session
• Picker/widget tables do NOT persist state
• Refresh does not destroy user context on critical lists

Performance

• No casual sortable() / searchable() on relations without query review
• No row-by-row counts in hot lists unless optimized
• Eager loading where relation-backed columns are rendered
• Default sort is query-efficient

RBAC / Tenancy

• Cross-tenant/workspace tables provide enough context
• Technical IDs are not more prominent than needed
• Actions/CTAs are capability-gated
• Non-member access is 404, not 403

Responsive

• No unnecessary horizontal overload
• Long text uses wrap() or limit() + tooltip()
• Long IDs do not break layout

---

How to Use

1. Before submitting a PR that touches a table surface, walk through this checklist.
2. Mark items as checked or note the documented exception.
3. If you're adding a new resource, this checklist applies from the first implementation.
4. Guard tests enforce the most critical items automatically — this checklist catches the rest.